Building a Neuron.

# Python 3.11+. httpx powers the HuggingFace Neuron source.
$ pip install cosmonapse httpx

# Read scope is enough  -  the token grants access to the public
# Inference Providers router at https://router.huggingface.co.
$ export HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxx

# A Neuron is anything that satisfies the NeuronFn contract:
#   async fn(input, context) -> output
#
# The unified factory wraps any source behind that interface. Here it's
# a HuggingFace endpoint; it could equally be Ollama, a Flask app, or an
# MCP server  -  the Axon never knows the difference.
import os
from cosmonapse import Neuron

greeter = Neuron(
    source="huggingface",
    endpoint="https://router.huggingface.co",
    model="meta-llama/Llama-3.1-8B-Instruct",
    api_key=os.environ["HF_TOKEN"],
    use_chat_api=True,
    max_new_tokens=128,
    temperature=0.7,
)

# Input the orchestrator sends: {"prompt": "..."} or {"messages": [...]}
# Output the Neuron returns:    {"response": "<text>", "meta": <raw>}

# The Axon declares identity + capabilities and owns the Neuron.
# It doesn't know it's wrapping an LLM  -  this code is byte-for-byte the
# same as it would be for a hand-written async function.
from cosmonapse import Axon

axon = Axon(
    neuron_id="greeter",
    neuron_fn=greeter,
    capabilities=["text-generation", "chat", "greet"],
)

# The Dendrite is the only component that touches the Synapse.
# role="worker" is a protocol guard: workers can serve TASKs and bid,
# but cannot emit orchestration signals (TASK / FINAL / etc.).
from cosmonapse import Dendrite, MemorySynapse

synapse = MemorySynapse()         # in-process  -  no socket
await synapse.connect()

worker = Dendrite(
    synapse=synapse,
    namespace="demo",
    role="worker",
)
worker.attach_axon(axon)

orchestrator = Dendrite(synapse=synapse, namespace="demo")

# dispatch_and_wait is sugar over a Pathway:
#   1. emit a TASK on this trace_id
#   2. open a Pathway scoped to the trace
#   3. await the first terminal Signal (AGENT_OUTPUT here)
#   4. close the Pathway, return the Signal
async with worker, orchestrator:
    reply = await orchestrator.dispatch_and_wait(
        neuron="greeter",
        input={"prompt": "Say hello to a project called Cosmonapse in one line."},
        timeout_s=30.0,
    )
    print(f"[{reply.type.value}] {reply.payload['output']['response']}")

import asyncio, os
from cosmonapse import Axon, Dendrite, MemorySynapse, Neuron


greeter = Neuron(
    source="huggingface",
    endpoint="https://router.huggingface.co",
    model="meta-llama/Llama-3.1-8B-Instruct",
    api_key=os.environ["HF_TOKEN"],
    use_chat_api=True,
    max_new_tokens=128,
    temperature=0.7,
)


async def main():
    synapse = MemorySynapse()
    await synapse.connect()
    try:
        axon = Axon(
            neuron_id="greeter",
            neuron_fn=greeter,
            capabilities=["text-generation", "chat", "greet"],
        )
        worker = Dendrite(synapse=synapse, namespace="demo", role="worker")
        worker.attach_axon(axon)

        orchestrator = Dendrite(synapse=synapse, namespace="demo")

        async with worker, orchestrator:
            reply = await orchestrator.dispatch_and_wait(
                neuron="greeter",
                input={"prompt": "Say hello to a project called Cosmonapse in one line."},
                timeout_s=30.0,
            )
            print(f"[{reply.type.value}] {reply.payload['output']['response']}")
    finally:
        await synapse.close()


asyncio.run(main())

# The endpoint is the only HF-specific line. Point it elsewhere for any
# OpenAI-compatible chat server  -  your Neuron code never changes.
endpoint="https://router.huggingface.co"                          # default
endpoint="https://<your-endpoint>.endpoints.huggingface.cloud"   # dedicated HF endpoint
endpoint="http://localhost:8080"                                 # local TGI / vLLM / LM Studio

# For Ollama, switch source  -  same Axon, same Dendrite.
greeter = Neuron(source="ollama", model="llama3")

# This example runs in-process on MemorySynapse, which Prism cannot
# attach to. To watch it live, run a dev synapse and point the code at it:

# terminal 1  -  the bus
$ cosmo synapse start memory --namespace=demo

# terminal 2  -  Prism, the live browser view (http://127.0.0.1:7071)
$ cosmo doppler --prism --url=cosmo://127.0.0.1:7070 -n demo

# in the code  -  swap one line:
# synapse = MemorySynapse()
synapse = await connect_synapse("cosmo://127.0.0.1:7070")