neuronum

Neuronum SDK

Python Version

About

Neuronum is built around the Secure Agent Session (SAS), an end-to-end encrypted channel designed for stateful agent-to-client and agent-to-agent communication across businesses, partners, and customers. A session connects two parties to automate data exchange, take actions, and coordinate tasks without manual integration, custom APIs, or file transfers.

The SDK handles encryption, identity, and delivery. You write the agent logic.

Requirements

Python >= 3.8

Installation

Set up and activate a virtual environment:

python3 -m venv ~/neuronum-venv
source ~/neuronum-venv/bin/activate

Install the Neuronum SDK:

pip install neuronum

Note: Always activate this virtual environment (source ~/neuronum-venv/bin/activate) before running any neuronum commands.

Agent

An Agent is your address used to send and receive data on the Neuronum network. You can think of it like a unique digital identity.

Example IDs: acme.com::agent

Create an Agent:

neuronum create-agent

This generates your Agent ID, public/private key pair, and a 12-word mnemonic recovery phrase. Your Agent credentials are stored locally at ~/.neuronum/.env.

Connect your Agent to a device using your 12-word mnemonic:

neuronum connect-agent

View the connected Agent ID:

neuronum view-agent

Verify the connected Agent ID:

neuronum verify-agent

Disconnect Agent credentials from this device:

neuronum disconnect-agent

Delete your Agent permanently from the network:

neuronum delete-agent

Methods

Agents interact on Neuronum using the following methods:

Method	Description
`list_agents()`	List all Neuronum Agents
`list_sessions()`	List your Secure Agent Sessions (SAS)
`create_secure_agent_session(recipient, instruct=None, subject=None)`	Create and invite to a session via email or agent_id, optionally setting agent instructions and session password
`fetch_session_metadata(session_id)`	Fetch session metadata
`send_session_message(session_id, data)`	Send an encrypted message to a session
`get_session_messages(session_id)`	Fetch and decrypt messages from a session
`upload_session_file(session_id, file_path, mime_type)`	Upload an encrypted file to a session
`download_session_file(session_id, file_id)`	Download a file from a session by file ID
`sync_messages()`	Receive messages from all sessions in real-time

All data is end-to-end encrypted. The network handles routing, key exchange, and delivery. You just send and receive.

Connecting to the network: Use async with Agent() as agent to connect. This reads your Agent credentials from ~/.neuronum/.env and establishes a connection to the Neuronum network at neuronum.net. Pass a network parameter only if you need to point at a different network.

Quick Examples

List Agents

import asyncio
from neuronum import Agent

async def main():
    async with Agent() as agent:
        agents = await agent.list_agents()
        print(agents)

asyncio.run(main())

List Sessions

import asyncio
from neuronum import Agent

async def main():
    async with Agent() as agent:
        sessions = await agent.list_sessions()
        print(sessions)

asyncio.run(main())

Create a Secure Agent Session

import asyncio
from neuronum import Agent

async def main():
    async with Agent() as agent:
        session = await agent.create_secure_agent_session(
            recipient="your@email.com",  #or recipient="acme.com::agent"
            instruct="Set specific goals, conversation context or further instructions",  #optional
            subject="Set session subject"  #optional - !Notice: Subject is sent in plaintext!
        )
        print(session)

asyncio.run(main())

Fetch Session Metadata

import asyncio
from neuronum import Agent

async def main():
    async with Agent() as agent:
        metadata = await agent.fetch_session_metadata("session_id")
        print(metadata)

asyncio.run(main())

Send a message to a session

import asyncio
from neuronum import Agent

async def main():
    async with Agent() as agent:
        success = await agent.send_session_message(
            "session_id",
            {"msg": "Hello"}
        )
        print(success)

asyncio.run(main())

Fetch messages from a session

import asyncio
from neuronum import Agent

async def main():
    async with Agent() as agent:
        messages = await agent.get_session_messages(session_id)
        print(messages)

asyncio.run(main())

Upload a file to a session

import asyncio
from neuronum import Agent

async def main():
    async with Agent() as agent:
        success = await agent.upload_session_file(
            "session_id",
            "/path/to/file.pdf",
            mime_type="application/pdf"
        )
        print(success)

asyncio.run(main())

Download a file from a session

The file_id is available in the file metadata message sent automatically after a successful upload. Retrieve it via get_session_messages from the file_id field.

import asyncio
from neuronum import Agent

async def main():
    async with Agent() as agent:
        file_bytes = await agent.download_session_file("session_id", "file_id")
        with open("output.pdf", "wb") as f:
            f.write(file_bytes)

asyncio.run(main())

Receive messages in real-time

import asyncio
from neuronum import Agent

async def main():
    async with Agent() as agent:
        async for message in agent.sync_messages():
            print(message["session_id"], message["sender"], message["data"])

asyncio.run(main())

Elements

Elements are UI components rendered on the client's frontend. Pass an element key in any send_session_message call to trigger them.

Element	Description
`confirm`	Renders Accept / Decline buttons
`choice`	Renders a set of option buttons
`input`	Renders a single text input field
`form`	Renders a multi-field form
`table`	Renders a data table
`card`	Renders a composite card combining multiple elements
`file`	Renders a file upload prompt
`link`	Renders a clickable button that opens a URL in a new browser tab

Confirm

await agent.send_session_message(session_id, {
    "msg": "Do you accept the session terms?",
    "element": "confirm"
})

Choice

await agent.send_session_message(session_id, {
    "msg": "Which report format do you prefer?",
    "element": "choice",
    "choices": ["PDF", "CSV", "JSON"]
})

Input

await agent.send_session_message(session_id, {
    "msg": "What is your company name?",
    "element": "input",
    "placeholder": "e.g. Acme Corp"
})

Form

await agent.send_session_message(session_id, {
    "msg": "Tell us about yourself:",
    "element": "form",
    "fields": [
        {"name": "company",  "label": "Company",  "placeholder": "Acme Corp"},
        {"name": "role",     "label": "Role",      "placeholder": "CEO"},
        {"name": "teamsize", "label": "Team size", "placeholder": "50"}
    ]
})

Table

await agent.send_session_message(session_id, {
    "msg": "Here are the results:",
    "element": "table",
    "columns": ["Name", "Status", "Score"],
    "rows": [
        ["Alice", "Active", 92],
        ["Bob", "Inactive", 74],
        ["Carol", "Active", 88]
    ]
})

Card

A card combines multiple elements into a single message.

await agent.send_session_message(session_id, {
    "msg": "Review this proposal:",
    "element": "card",
    "components": [
        {"type": "table", "columns": ["Item", "Cost"], "rows": [["Dev", "$5k"], ["Design", "$2k"]]},
        {"type": "input", "name": "budget", "label": "Your budget", "placeholder": "$10,000"},
        {"type": "choice", "name": "timeline", "label": "Timeline", "choices": ["1 month", "3 months", "6 months"]},
        {"type": "confirm", "name": "approved", "label": "Do you approve?"}
    ]
})

File

Renders a file upload prompt on the client.

await agent.send_session_message(session_id, {
    "msg": "Please upload your contract:",
    "element": "file"
})

Link

Renders a clickable button that opens a URL in a new browser tab.

await agent.send_session_message(session_id, {
    "msg": "Click below to visit our website:",
    "link": "https://example.com",
    "element": "link"
})

Neuronum MCP Server

neuronum neuronum start-mcp

Full Documentation

Visit the Neuronum Docs for the complete SDK reference.

License
- OSI Approved :: MIT License
Operating System
- OS Independent
Programming Language
- Python :: 3

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

neuronum-2026.7.11.tar.gz (23.0 kB view details)

Uploaded Aug 1, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

neuronum-2026.7.11-py3-none-any.whl (21.6 kB view details)

Uploaded Aug 1, 2026 Python 3

File details

Details for the file neuronum-2026.7.11.tar.gz.

File metadata

Download URL: neuronum-2026.7.11.tar.gz
Upload date: Aug 1, 2026
Size: 23.0 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.13.5

File hashes

Hashes for neuronum-2026.7.11.tar.gz
Algorithm	Hash digest
SHA256	`ecf9180b2738effa59ded151de9ebc565fba3eb336be1ca0d01887ff676431ff`
MD5	`1566d687941662374ca4b5e06c3e6ca2`
BLAKE2b-256	`f889ea572e5e445eec8d724940290fd889dec748ffb4278a9a0fb8a28f9425d5`

See more details on using hashes here.

File details

Details for the file neuronum-2026.7.11-py3-none-any.whl.

File metadata

Download URL: neuronum-2026.7.11-py3-none-any.whl
Upload date: Aug 1, 2026
Size: 21.6 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.13.5

File hashes

Hashes for neuronum-2026.7.11-py3-none-any.whl
Algorithm	Hash digest
SHA256	`2e640599f9626d211cd7d67593a1f7a49e85dcf91a5430ee8bbb4b10c9ddbdec`
MD5	`a2f3560e8a786e09786a691bc4cf4749`
BLAKE2b-256	`f8304917535c4196a9a4a210da2425fb231e2c9c2b8e8db8fd407f10c85a20a2`