Python SDK reference.
cosmonapse Python package - verified against packages/python-sdk. If something here disagrees with the code, the code wins.
Neuron - sources
A Neuron is anything that interacts with the real world, exposed behind one signature: async (input, context) → dict. It is not limited to an LLM agent - it can be an agent, an MCP server, or a plain async function. The Neuron(source=…) factory wraps each kind into the same neuron_fn, so the Axon and the rest of the protocol can’t tell them apart. Each source is a soft dependency - installed only when you use it. An HTTP API is not a Neuron: keep your web framework at the edge and dispatch TASKs from its routes via an orchestrator Dendrite.
cosmonapse.Neuron(source, **kwargs)Returns a NeuronFn callable for the chosen source. Pass it straight to Axon(neuron_fn=…).
from cosmonapse import Axon, Neuron # A Neuron is anything that interacts with the real world. The same factory # wraps an LLM or an MCP server - the Axon never knows which. # 1 · LLM / agent - Ollama, HuggingFace, OpenAI, Anthropic, or any # OpenAI-compatible host (groq / openrouter / together / mistral). chat = Axon(neuron_id="chat", neuron_fn=Neuron(source="ollama", model="llama3")) cloud = Axon(neuron_id="cloud", # api_key falls back to OPENAI_API_KEY neuron_fn=Neuron(source="openai", model="gpt-4o")) # 2 · An HTTP API is NOT a Neuron. Keep your web framework (Flask/FastAPI) # at the edge and dispatch TASKs from its routes via an orchestrator # Dendrite - see the quickstart and the real-world-neurons example. # 3 · MCP server - wrap any stdio MCP server's tools as a Neuron files = Axon(neuron_id="files", neuron_fn=Neuron(source="mcp", server="filesystem", args=["/data"], tool="read_file")) # Shortcut: the source-paired factories - Axon.ollama() / .huggingface() # / .openai() / .anthropic() / .mcp() - do both steps in one call AND # wire the matching recogniser. See the Axon section below.
Available sources
| source= | Kind | Key kwargs | Notes |
|---|---|---|---|
| "ollama" | LLM | model*, endpoint, system, temperature, max_tokens | Wraps a local Ollama daemon (/api/generate + /api/chat). Needs httpx. |
| "huggingface" / "hf" | LLM | endpoint*, model, use_chat_api, api_key, max_new_tokens | TGI / vLLM / llama.cpp / LM Studio (OpenAI-compatible). Needs httpx. |
| "openai" | LLM | model*, api_key, endpoint, system, temperature, max_tokens | OpenAI Chat Completions. api_key falls back to OPENAI_API_KEY; point endpoint at Azure or a proxy. Needs httpx. |
| "anthropic" | LLM | model*, api_key, system, max_tokens, temperature | Anthropic Messages API. api_key falls back to ANTHROPIC_API_KEY; OpenAI-style system messages are hoisted to the top-level system field. Needs httpx. |
| "groq" / "openrouter" / "together" / "mistral" | LLM | model, api_key, endpoint, temperature, max_new_tokens | OpenAI-compatible hosted endpoints - pre-configured "huggingface" Neurons with the provider base URL and use_chat_api=True. api_key falls back to GROQ_API_KEY / OPENROUTER_API_KEY / TOGETHER_API_KEY / MISTRAL_API_KEY. Needs httpx. |
| "mcp" | MCP server | command+args or server+args, env, cwd, tool | Spawns any stdio MCP server and exposes its tools. Input is {tool, arguments} (or {"__list_tools__": True}); returns {response, result, is_error, content, meta}. Wrapper only - does not implement a server. Needs mcp. |
The "mcp" source ships STANDARD_MCP_SERVERS - launch presets for well-known published servers (filesystem, fetch, git, memory, everything, sequentialthinking, time). Pass server="filesystem" and anything in args is appended to the preset’s launch command. One subprocess is spawned and reused across tasks; the Axon tears it down on deregister.
Have a feature in mind?
The protocol, SDKs, and CLI are still pre-1.0. If something here is missing, ambiguous, or wrong - open an issue and propose a change. Every breaking change is debated in DECISIONS.md first.