Skip to main content

NeuralNode

NeuralNode

NeuralNode 2.2.10 is a Python framework for connecting cloud and local AI models through one provider interface. It includes chat, streaming, vision, embeddings, agents, memory, RAG, speech, Hugging Face models, Horus models, Ollama, OpenClaw, and optional integrations.

NeuralNode is developed and fully owned by TokenAI. It is distributed under the TokenAI Source-Available License described at the end of this file.

Install

pip install neuralnode

Install only the feature set you need:

pip install "neuralnode[ollama]"      # Ollama client support
pip install "neuralnode[local]"       # local Transformers/GGUF models
pip install "neuralnode[horus]"       # Horus local models
pip install "neuralnode[replica]"     # Replica TTS adapter
pip install "neuralnode[telegram]"    # Telegram integration
pip install "neuralnode[openclaw]"    # OpenClaw gateway integration
pip install "neuralnode[all]"         # all published optional features

The base package stays lightweight. Large ML runtimes, vector stores, speech libraries, and provider SDKs are optional.

Quick start

import neuralnode as nn

ai = nn.NeuralNode(provider="groq", model="llama-3.1-8b-instant")
print(ai.chat("Explain embeddings in one paragraph."))

Set the provider API key before running:

$env:GROQ_API_KEY="your-key"

Why use NeuralNode?

NeuralNode helps developers build model-powered applications through one consistent Python interface for providers, local runtimes, agents, tools, embeddings, and retrieval workflows.

  • Model interoperability — Move between cloud APIs, Ollama, Transformers, llama.cpp, vLLM, Horus, and other supported runtimes without rewriting the application layer.
  • Rapid prototyping — Start with a small chat call, then add streaming, vision, tools, memory, RAG, or speech as the application grows.
  • Local and private execution — Run compatible models locally through Ollama and other local backends when data-control or offline workflows matter.
  • Production building blocks — Use normalized provider responses, agents, tool calling, embeddings, vector stores, OpenClaw, and optional integrations.
  • Provider flexibility — Inspect the installed registry and switch models or providers through configuration instead of coupling business logic to one vendor.
  • Optional by design — Keep the base install lightweight and add only the SDKs and heavy runtimes needed by the project.

Do this → run this

See supported providers

import neuralnode as nn

print(nn.get_available_providers())
print(nn.get_provider_info("ollama"))

The registry is the source of truth for the installed package. Optional provider SDKs may still be required when creating a provider.

List the built-in model catalog

import neuralnode as nn

for model_id, info in nn.list_models().items():
    print(model_id, info)

Chat with a local Ollama model

Start Ollama and pull a model:

ollama serve
ollama pull qwen3

Then:

import neuralnode as nn

ai = nn.NeuralNode(provider="ollama", model="qwen3")
print(ai.chat("Give me three names for a robotics project."))

For a remote/containerized Ollama server:

ai = nn.NeuralNode(
    provider="ollama",
    model="qwen3",
    base_url="http://127.0.0.1:11434",
)

Enable or disable local-model reasoning

For Ollama, thinking maps to its native think field. None keeps the model default, True enables reasoning, and False disables it:

import neuralnode as nn

ai = nn.NeuralNode(provider="ollama", model="qwen3")
print(ai.chat("What is 2 + 2?", thinking=False))
print(ai.chat("Compare two sorting algorithms.", thinking=True))

To access the normalized reasoning trace itself:

from neuralnode.providers.local_providers import OllamaProvider

ollama = OllamaProvider(model="qwen3")
response = ollama.chat(
    [{"role": "user", "content": "Explain binary search."}],
    thinking=True,
)
print(response["content"])
print(response["thinking"])

Reasoning is model-dependent; a model without native reasoning may return an empty thinking field.

Stream a response

for chunk in ai.chat("Write a short poem about Cairo.", stream=True):
    print(chunk, end="", flush=True)

Send an image to a vision-capable model

ai = nn.NeuralNode(provider="ollama", model="llava")
print(ai.chat_with_image("Describe this image.", image="photo.jpg"))

Create an agent with tools and reasoning

ai = nn.NeuralNode(provider="ollama", model="qwen3")
agent = ai.agent(
    skills=["datetime", "calculator"],
    thinking=True,
    max_iterations=10,
)
print(agent.run("What time is it, and what is 37 * 19?"))

Supported skill names include web_search, datetime, system_control, file, python, calculator, and all. Use thinking=False to execute without the reasoning wrapper.

Add conversation memory

ai = nn.NeuralNode(provider="ollama", model="qwen3").with_memory()
ai.chat("My project is called Atlas.")
print(ai.chat_with_memory("What is my project called?"))

Generate embeddings

ai = nn.NeuralNode(provider="ollama", model="nomic-embed-text")
vectors = ai.embed(["NeuralNode connects models.", "Ollama runs locally."])
print(len(vectors), len(vectors[0]))

Build a small RAG system

ai = nn.NeuralNode(provider="ollama", model="qwen3")
rag = ai.rag(store="memory", top_k=3)
rag.add_documents(["NeuralNode is owned by TokenAI.", "Ollama is a local runtime."])
print(rag.query("Who owns NeuralNode?"))

For persistent Chroma storage:

pip install "neuralnode[chroma]"
rag = ai.rag(store="chroma", persist_dir="./neuralnode-db")

Download or load a Hugging Face model

from neuralnode import download_repo, load_hf_model

path = download_repo("sentence-transformers/all-MiniLM-L6-v2")
model = load_hf_model("sentence-transformers/all-MiniLM-L6-v2")
print(path, model)

Private or gated repositories require HF_TOKEN or an explicit token. Heavy dependencies are installed with the local extra.

Use Horus models

pip install "neuralnode[horus]"
from neuralnode import HorusModel

model = HorusModel(model_id="TokenAI/your-horus-model")
print(model.chat("Hello from a local Horus model."))

Generate speech with Replica

pip install "neuralnode[replica]"
from neuralnode import ReplicaTTS

tts = ReplicaTTS(voice_id="default")
tts.speak("Welcome to NeuralNode.", output_file="welcome.mp3")

Run Telegram

pip install "neuralnode[telegram]"
from neuralnode import NeuralNode
from neuralnode.integrations.telegram import TelegramBot

ai = NeuralNode(provider="ollama", model="qwen3")
bot = TelegramBot(token="your-token", agent=ai.agent())
bot.run()

Connect NeuralNode to OpenClaw

pip install "neuralnode[openclaw]"
from neuralnode import NeuralNode
from neuralnode.integrations.openclaw import OpenClawServer

ai = NeuralNode(provider="ollama", model="qwen3")
server = OpenClawServer(node=ai, host="127.0.0.1", port=8001, api_key="change-me")
server.run()

Keep the gateway on loopback unless a deliberate network and authentication configuration protects it. Do not expose a development gateway publicly without authentication and a reverse proxy policy.

Provider surface

The registry includes cloud adapters such as OpenAI-compatible, Anthropic, Google, Groq, Cohere, Mistral, DeepSeek, Perplexity, Together, Fireworks, Bedrock, and Vertex AI, plus local adapters including Ollama, llama.cpp, Transformers, vLLM, TGI, MLX, Horus, and other compatible runtimes.

Print the exact installed registry:

import neuralnode as nn
print("\\n".join(nn.get_available_providers()))

Provider SDKs and credentials are optional. A provider in the registry does not mean its external service or model is included in this package.

Resources

What's new in 2.2.9

  • Removed the deprecated WhatsApp/Twilio integration and legacy gateway.
  • Improved OpenClaw configuration, loopback binding, token authentication, OpenAI-compatible chat-completions support, and streaming fallback.
  • Upgraded Ollama to native /api/chat with role-preserving messages, streaming, structured output, tool calls, and native reasoning control through thinking=True or thinking=False.
  • Updated Ollama embeddings to batch /api/embed with a legacy compatibility fallback.
  • Added and validated the NeuralNode → OpenClaw → local model path on AWS.
  • Retained Hugging Face speech, vision, Horus, Replica, agents, memory, RAG, vector-store, and optional TurboQuant workflows.
  • Added reproducible wheel/source builds, CI validation for Python 3.9–3.12, and trusted PyPI publishing through GitHub Actions.

See CHANGELOG.md for the complete release history.

Coming soon to NeuralNode

  • replica-preview-0.6B — TTS model.
  • horus-cyber-nano-1.2 — text model with vision capabilities.

These are announced as coming soon and are not shipped weights in NeuralNode 2.2.9.

Support and security

For bugs, include the Python version, NeuralNode version, provider, model, a minimal reproduction, and the full error message with secrets removed. Never commit API keys, Hugging Face tokens, Telegram tokens, or OpenClaw authentication tokens.

Ownership and license

NeuralNode, its source code, documentation, branding, release artifacts, and maintained integrations are the exclusive property of TokenAI. Nothing in this repository transfers ownership or permits redistribution, rebranding, sale, sublicensing, or offering NeuralNode as a competing hosted service without written authorization from TokenAI.

NeuralNode is released under the TokenAI Source-Available License v1.0 in LICENSE. This is a proprietary source-available license, not an OSI-approved open-source license. Third-party providers, SDKs, model weights, and external services remain subject to their own licenses and terms.

Metadata

Release files for neuralnode 2.2.10

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for neuralnode 2.2.10
File Size Uploaded Provenance Actions
neuralnode-2.2.10.tar.gz 946.6 kB With provenance Details for neuralnode-2.2.10.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for neuralnode 2.2.10
File Interpreter ABI Platform Actions
neuralnode-2.2.10-py3-none-any.whl Python 3 none any Details for neuralnode-2.2.10-py3-none-any.whl

Total release size: 1.2 MB

Release files / neuralnode-2.2.10.tar.gz

Download URL neuralnode-2.2.10.tar.gz
Size 946.6 kB
Tags Source
SHA-256 checksum
How to use checksums
d3b93150baf5aa78dd8561857613b55fdb2acd2ffd7e4b68caccb858952b303a
BLAKE2b-256 checksum
How to use checksums
cfe7de92c38f9473af4f0488413cdf0f326fad4457c3e7785c1ba92df2b50d9a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.

Transparency log

Release files / neuralnode-2.2.10-py3-none-any.whl

Download URL neuralnode-2.2.10-py3-none-any.whl
Size 238.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
22bedd1bd690f342e908d296f64c8e2f40041a015fa8fc79eed3f377191399b4
BLAKE2b-256 checksum
How to use checksums
c0d7495052d95c6dbead79e6e1e049563d143652154ce0c02f5f00687a84e7cd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.

Transparency log

Security for neuralnode 2.2.10

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for neuralnode-2.2.10.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.2.10 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page