NeuralNode v2.2.0

NeuralNode is a Python AI framework focused on:

• real cloud providers that are implemented
• local model execution with Transformers, Ollama, llama.cpp, and Horus
• agents, memory, and RAG
• Replica TTS and speech recognition
• Telegram integration

Install

pip install neuralnode
pip install "neuralnode[all]"

Useful extras:

pip install "neuralnode[horus]"
pip install "neuralnode[telegram]"
pip install "neuralnode[replica]"
pip install "neuralnode[speech]"
pip install "neuralnode[turboquant]"

Quick Start

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"))

Horus

Horus Cyper Nano 1.0 BETA Early Access API

Approved Early Access users can call the hosted model 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-cyper-nano",
    model="horus-cyper-nano-1.0-beta",
    api_key="horusNN-XXXXXXXXXXXXXXXX",
)

print(ai.chat("Review this code for defensive cybersecurity issues."))

The client reads HORUS_CYPER_NANO_API_KEY automatically. Override HORUS_CYPER_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_cyper_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:

• horus
• Horus-1.0-4B
• Horus-1.0-4B-Q4_K_M.gguf
• Horus-1.0-4B-Q5_K_M.gguf
• Horus-1.0-4B-Q6_K.gguf
• Horus-1.0-4B-Q8_0.gguf
• Horus-1.0-4B-F16.gguf
• Horus-Lens-1.0
• Horus-Hiero-9B
• Horus-Hiero-9B-Q4_K_M.gguf
• Horus-Hiero-9B-Q6_K.gguf
• Horus-Hiero-Mini-4B
• Horus-Hiero-Mini-4B-Q4_K_M.gguf
• Horus-Hiero-Mini-4B-Q6_K.gguf

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:

• docs/replica_voice_ids.md
• docs/replica_voice_ids.csv

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:

1. a dedicated embedding provider
2. sentence-transformers
3. lexical fallback embeddings

Supported Provider Surface

Only implemented providers are exposed through the public provider registry.

Cloud chat providers:

• anthropic
• google
• cohere
• mistral
• groq
• deepseek
• perplexity
• ai21
• together
• fireworks
• bedrock
• vertexai

Local providers:

• ollama
• llamacpp
• transformers
• llamafile
• koboldcpp
• textgenwebui
• exllama
• autogptq
• autoawq
• vllm
• tgi
• deepspeed
• rayserve
• mlflow
• bentoml
• triton
• mlx
• horus

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 is intentionally blocked in NeuralNode.
• GGUF Horus models require llama-cpp-python.
• Horus downloads from Hugging Face require huggingface_hub.

OpenClaw Integration

NeuralNode 2.2.0 introduces full end-to-end integration with OpenClaw. You can easily set up, start, and control OpenClaw directly through the framework.

The integration operates by running a local FastAPI server in the background that exposes an OpenAI-compatible API to the OpenClaw Node gateway. This server proxies LLM requests directly to NeuralNode providers, allowing seamless interaction.

It also fully supports the WhatsApp API, allowing users to activate it and bind it to their phone numbers entirely via code and OpenClaw.

Links

• TokenAI: https://tokenai.cloud/
• NeuralNode: https://neuralnode.tokenai.cloud/