Connect models. Build AI.
NeuralNode v2.2.8
NeuralNode is a Python framework for connecting cloud and local AI models to one consistent interface. Build applications with model providers, agents, tools, memory, RAG, embeddings, vector stores, and integrations without rewriting your application around a single provider.
Why NeuralNode?
- One interface for many models — connect cloud APIs, local runtimes, and custom providers through a unified interface.
- Production building blocks — agents, tool calling, memory, RAG, embeddings, vector stores, and API gateways.
- Local and hosted execution — use Transformers, Ollama, llama.cpp, vLLM, Horus, and other supported runtimes.
- Composable integrations — connect applications to Telegram, Slack, Discord, OpenClaw, speech, vision, and text-to-speech workflows.
Quickstart
pip install neuralnode
import neuralnode as nn
ai = nn.NeuralNode(
provider="groq",
model="llama-3.1-70b-versatile",
api_key="YOUR_GROQ_API_KEY",
)
print(ai.chat("Hello from NeuralNode"))
Install optional integrations
pip install "neuralnode[all]"
pip install "neuralnode[horus]"
pip install "neuralnode[image]"
pip install "neuralnode[vision]"
pip install "neuralnode[telegram]"
pip install "neuralnode[replica]"
pip install "neuralnode[speech]"
pip install "neuralnode[turboquant]"
Core capabilities
- Chat and text-generation providers
- Agents and structured tool calling
- Conversation and persistent memory
- Retrieval-Augmented Generation (RAG)
- Embeddings and vector stores
- Vision and speech-to-text
- Text-to-speech and Replica integrations
- OpenAI-compatible local and hosted gateways
- Provider registry and custom provider extensions
Hugging Face text-to-image
Install the optional image dependencies and load a Diffusers-compatible
text-to-image repository. AutoPipelineForText2Image supports compatible
Diffusers model repositories; it does not make unrelated Hugging Face models
image generators.
pip install "neuralnode[image]"
For local image input with a Transformers vision-language model, install the
vision extra (pip install "neuralnode[vision]") and use the existing
chat_with_image(...) interface with a local image file.
from neuralnode import load_hf_image_model
image_model = load_hf_image_model("stabilityai/stable-diffusion-xl-base-1.0")
image = image_model.generate_image(
"A small robot reading under a tree, watercolor illustration",
output_path="generated/robot.png",
num_inference_steps=25,
seed=42,
)
One-turn voice agent
Connect speech recognition, an agent, and speech synthesis in one sequential turn. This is suitable for file-based or push-to-talk workflows; it does not provide low-latency, full-duplex streaming audio.
from neuralnode.speech import HTTPSTT
from neuralnode.tts import HTTPTTS
from neuralnode.voice import VoiceAgent
voice_agent = VoiceAgent(
agent=ai.agent(tools=[...]),
speech=HTTPSTT("http://localhost:5010"),
tts=HTTPTTS("http://localhost:5012", voice="sara", language="en"),
)
turn = voice_agent.process_audio_file("question.wav", output_audio="answer.mp3")
print(turn.transcript)
print(turn.response)
For local Hugging Face speech models, install pip install "neuralnode[hf-audio]".
The default models are openai/whisper-small for transcription and
facebook/mms-tts-eng for English speech generation. Pass another compatible
public or accessible Hugging Face model ID to either adapter.
from neuralnode.speech import HuggingFaceSTT
from neuralnode.tts import HuggingFaceTTS
stt = HuggingFaceSTT("openai/whisper-small")
text = stt.transcribe("question.wav", language="en-US")
tts = HuggingFaceTTS("facebook/mms-tts-eng")
tts.speak(text, output="recognized-speech.wav")
These adapters load models lazily and use CPU unless CUDA is available. Public
models do not need a token; gated models require HF_TOKEN set in the process
environment. HuggingFaceTTS.speak() writes mono PCM WAV output.
Documentation
Horus
H-Preview Model API
NeuralNode includes an OpenAI-compatible API gateway for serving H-Preview through a vLLM-compatible server on another machine. The gateway creates nn- access tokens with Basic (RPM controlled) and Elite (no application RPM accounting) tiers, plus one owner admin token for managing them. See docs/model_api.md for deployment and Python client examples.
import neuralnode as nn
ai = nn.NeuralNode(
provider="h-preview",
model="h-preview",
api_key="nn-...",
base_url="https://api.example.com/v1",
)
print(ai.chat("Say hello."))
Horus Cyber Nano 1.0 Early Access API
Horus Cyber Nano 1.0 is a Text-to-Text model. The hosted API is currently in Early Access. Approved users can call it through the same
NeuralNode interface. Each Access Token has its own server-enforced RPM limit,
and API conversations are retained by TokenAI under the Early Access terms.
import neuralnode as nn
ai = nn.NeuralNode(
provider="horus-cyber-nano",
model="horus-cyber-nano-1.0-beta",
api_key="horusNN-XXXXXXXXXXXXXXXX",
)
print(ai.chat("Review this code for defensive cybersecurity issues."))
The client reads HORUS_CYBER_NANO_API_KEY automatically. Override
HORUS_CYBER_NANO_BASE_URL only when TokenAI provides a different API endpoint.
The production API base URL is https://api.tokenai.llc/v1. Agent Mode supports
function tools, required or named tool choices, tool-result messages, and
buffered SSE compatibility streams. The hosted Early Access model has a 32,768
token context. See examples/horus_cyber_nano_agent_mode.py for the complete
tool-call round trip. NeuralNode retries temporary HTTP 429, 502, and 503
responses up to two times by default and respects the API Retry-After header.
Locally loaded Horus models use:
- unified chat template:
horus_unified - unified context window:
8192
Horus downloads are public-only. Private or gated Hugging Face repositories are not supported.
import neuralnode as nn
model = nn.HorusModel(
model_id="Horus-1.0-4B",
turboquant=True,
turboquant_bits=4,
).load()
response = model.chat([
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Explain Horus briefly."},
])
print(response.content)
Available Horus model IDs
from neuralnode import HorusModel
print(HorusModel.list_available_models())
Supported IDs currently include:
horusHorus-1.0-4BHorus-1.0-4B-Q4_K_M.ggufHorus-1.0-4B-Q5_K_M.ggufHorus-1.0-4B-Q6_K.ggufHorus-1.0-4B-Q8_0.ggufHorus-1.0-4B-F16.ggufHorus-Lens-1.0Horus-Hiero-9BHorus-Hiero-9B-Q4_K_M.ggufHorus-Hiero-9B-Q6_K.ggufHorus-Hiero-Mini-4BHorus-Hiero-Mini-4B-Q4_K_M.ggufHorus-Hiero-Mini-4B-Q6_K.ggufHorus-Cyber-Nano-1.0Horus-Cyber-Nano-1.0-Q4_K_M.ggufHorus-Cyber-Nano-1.0-Q5_K_M.ggufHorus-Cyber-Nano-1.0-Q6_K.ggufHorus-Cyber-Nano-1.0-Q8_0.ggufHorus-Cyber-Nano-1.0-F16.ggufHorus-Taleeq-0.2B-Base
Horus Hiero
import neuralnode as nn
model = nn.HorusModel(
"Horus-Hiero-Mini-4B-Q4_K_M.gguf",
device="cpu",
).load()
response = model.chat([
{"role": "user", "content": "Translate this hieroglyphic text into English."}
])
print(response.content)
Horus Lens text-to-image
import neuralnode as nn
model = nn.HorusLensModel("Horus-Lens-1.0").load()
model.generate_image(
"A detailed cinematic image of an ancient Egyptian AI lab, golden light",
output_path="outputs/horus_lens.png",
seed=42,
)
Replica TTS
Replica exposes 20 curated edge_tts voices through custom voice IDs.
import neuralnode as nn
print(nn.replica_voice_list())
tts = nn.ReplicaTTS(voice_id="replic-salma-language{ar-eg}")
tts.save_to_file("مرحبا من نيورال نود", "reply.mp3")
Voice mapping docs:
Horus + Replica
import neuralnode as nn
model = nn.HorusModel(
model_id="Horus-1.0-4B",
enable_tts=True,
tts_voice_id="replic-salma-language{ar-eg}",
).load()
result = model.chat_and_speak(
[{"role": "user", "content": "قل لي جملة ترحيب قصيرة"}],
output_file="horus_reply.mp3",
)
print(result["response"].content)
print(result["audio_path"])
Telegram
Use a BotFather token to connect an agent to Telegram.
import neuralnode as nn
ai = nn.NeuralNode(provider="horus", model="Horus-1.0-4B")
agent = ai.agent(agent_type="simple", thinking=False)
bot = nn.TelegramBot(
token="YOUR_BOTFATHER_TOKEN",
agent=agent,
config=nn.TelegramBotConfig(
token="YOUR_BOTFATHER_TOKEN",
enable_voice=True,
enable_documents=True,
reply_mode="both", # text | voice | both
voice_reply_voice_id="replic-aria-language{en-us}",
),
)
bot.start()
Telegram now supports:
- text chat
- voice transcription
- optional Replica voice replies
- document download and analysis
RAG
import neuralnode as nn
ai = nn.NeuralNode(provider="ollama", model="llama3.2")
rag = ai.rag(store="memory")
rag.add_documents(["notes.txt", "report.pdf"])
print(rag.query("Summarize the key findings"))
If the current LLM does not support embeddings, RAG automatically tries:
- a dedicated embedding provider
- sentence-transformers
- lexical fallback embeddings
Supported Provider Surface
Only implemented providers are exposed through the public provider registry.
Cloud chat providers:
anthropicgooglecoheremistralgroqdeepseekperplexityai21togetherfireworksbedrockvertexai
Local providers:
ollamallamacpptransformersllamafilekoboldcpptextgenwebuiexllamaautogptqautoawqvllmtgideepspeedrayservemlflowbentomltritonmlxhorus
TurboQuant
TurboQuant is integrated into:
HorusModel(..., turboquant=True, turboquant_bits=4)create_provider("transformers", turboquant=True, turboquant_bits=4, ...)
If the turboquant package is not installed or the backend cannot use it, NeuralNode falls back to normal generation automatically.
Notes
- OpenAI-compatible providers are fully supported (OpenAI, OpenRouter, AgentRouter, H-Preview, etc.).
- GGUF Horus models require
llama-cpp-python. - Horus downloads from Hugging Face require
huggingface_hub.
OpenClaw Integration
NeuralNode can expose a local OpenAI-compatible API for an OpenClaw Gateway to use. The
OpenClawServer serves /v1/models and /v1/chat/completions without authentication
on loopback by default. Binding to a non-loopback host requires an API key, and clients
must send it as a Bearer token. Browser access is disabled by default; pass explicit
cors_origins only when browser clients need access. The OpenClawManager generates a
per-instance token automatically and configures its local server to require it.
OpenClawClient calls the Gateway's OpenAI-compatible chat endpoint. Enable
gateway.http.endpoints.chatCompletions in the OpenClaw configuration before using
send_task; OpenClaw disables this endpoint by default. A stable session_id is sent
as the OpenAI user value, so the Gateway creates or resumes that conversation when
the first message is sent. OpenClaw session status/control uses its WebSocket RPC API
and is not implemented by this HTTP client. Messaging channels such as WhatsApp must
be configured and authorized in OpenClaw itself.
Links
- TokenAI: https://tokenai.cloud/
- NeuralNode: https://neuralnode.tokenai.cloud/
License and ownership
NeuralNode is distributed under the TokenAI Source-Available License Version 1.0. This is a source-available license, not an OSI-approved Open Source license.
The NeuralNode Framework and the original NeuralNode source code are owned by TokenAI, subject to the separate licenses of third-party libraries, models, model weights, APIs, datasets, and other external materials. This repository's license does not transfer ownership of NeuralNode, TokenAI, or their trademarks.
If you use, fork, embed, modify, or build a product on NeuralNode, you must retain the license and attribution notices and clearly state:
This product uses NeuralNode, a framework owned by TokenAI.
See LICENSE, NOTICE, TRADEMARKS.md, and THIRD_PARTY_NOTICES.md for the applicable terms.
Contributing
Contributions, bug fixes, tests, and documentation improvements are welcome through GitHub issues, forks, and pull requests. Every pull request is reviewed by TokenAI and may be accepted, changed, or rejected. A pull request becomes part of NeuralNode only after TokenAI merges it.
See CONTRIBUTING.md for the contribution terms and workflow.
Hugging Face Open-Weights Support
Any open-weight model on Hugging Face can be downloaded and used with NeuralNode (not only TokenAI models). Use the built-in HF helpers:
import neuralnode as nn
# 1) Discover files in a repo
print(nn.list_repo_files("org/model")) # e.g. ["config.json", "model.safetensors", ...]
# 2) Download the repo (or a specific file)
path = nn.download_repo("org/model") # safetensors/auto
path = nn.download_repo("org/model", file="model.gguf") # GGUF
# 3) Load it into NeuralNode
llm = nn.load_hf_model("org/model", device="auto")
print(llm.chat([{"role": "user", "content": "Hello with any HF model"}]))
Supported formats: GGUF/GGML, SafeTensors, PyTorch (.bin/.pt), ONNX, AWQ, GPTQ.
Private or gated repos are supported by the HF helpers (with HF_TOKEN env var).
Python example:
Metadata
Release files for neuralnode 2.2.8
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| neuralnode-2.2.8.tar.gz | 2.5 MB | Without provenance | Details for neuralnode-2.2.8.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| neuralnode-2.2.8-py3-none-any.whl | Python 3 | none | any | Details for neuralnode-2.2.8-py3-none-any.whl |
Total release size: 2.7 MB
Release files / neuralnode-2.2.8.tar.gz
| Download URL | neuralnode-2.2.8.tar.gz |
|---|---|
| Size | 2.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b3cf75e1f5f350cbb8bb7afeee7852ad8603c83817e1a5d0170a5b952a5a6322
|
|
BLAKE2b-256 checksum How to use checksums |
2d4181e47ebcf64b5b2b1300b06e6e1b174467e52efd61b34558aa7db1f04244
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
Release files / neuralnode-2.2.8-py3-none-any.whl
| Download URL | neuralnode-2.2.8-py3-none-any.whl |
|---|---|
| Size | 251.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
be1b60876bef6368e98922c8c4a14b731ed6908fd73715bb6cb4418f5e6d5e1d
|
|
BLAKE2b-256 checksum How to use checksums |
17440f2e95371328fa4082178111f02a43796dacff95809c3251eb3c388db8af
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
Security for neuralnode 2.2.8
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
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.