Metadata-Version: 2.5
Name: neuralnode
Version: 2.2.9
Summary: Connect models. Build AI. A Python framework for LLM providers, agents, memory, RAG, and tools.
Project-URL: Homepage, https://tokenai.llc/
Project-URL: NeuralNode, https://tokenai.llc/
Project-URL: Documentation, https://neuralnode.readthedocs.io
Project-URL: Repository, https://github.com/tokenaillc/neuralnode
Project-URL: Issues, https://github.com/tokenaillc/neuralnode/issues
Project-URL: Changelog, https://github.com/tokenaillc/neuralnode/blob/main/CHANGELOG.md
Author-email: Assem Sabry <assemsabry777@gmail.com>
Maintainer-email: Assem Sabry <assemsabry777@gmail.com>
License: TokenAI Source-Available License
        Version 1.0
        
        Copyright (c) 2024–2026 TokenAI. All rights reserved.
        
        IMPORTANT NOTICE
        
        This is a source-available license. It is not an OSI-approved Open Source
        license. The NeuralNode Framework and the original NeuralNode source code are
        owned by TokenAI, subject to the rights of third-party components identified in
        THIRD_PARTY_NOTICES.md and their respective licenses.
        
        1. Definitions
        
        "Licensor" means TokenAI, the owner of the NeuralNode Framework.
        
        "NeuralNode" or "Software" means the original source code, documentation,
        configuration, and other materials in this repository that are identified as
        part of the NeuralNode Framework and owned by TokenAI.
        
        "Derivative Work" means a work based on, incorporating, or substantially
        modifying the Software, including a fork or a product that incorporates the
        core NeuralNode runtime or architecture.
        
        "Competing Framework" means a generally available software framework, runtime,
        platform, SDK, or service whose primary purpose is substantially similar to
        the primary purpose of NeuralNode, including the orchestration of AI models,
        provider abstraction, agents, tools, memory, RAG, or materially similar
        capabilities, where NeuralNode or a substantial portion of its code or
        architecture is used as a material part of that offering.
        
        2. Limited License Grant
        
        Subject to this License, TokenAI grants you a worldwide, non-exclusive,
        non-transferable, royalty-free license to:
        
          a. view and study the Software;
          b. use the Software for personal, educational, research, and internal
             business purposes;
          c. modify the Software for those purposes; and
          d. create and distribute applications that use the Software, provided that
             the application is not a Competing Framework and all requirements of this
             License are satisfied.
        
        This license does not transfer ownership of the Software or any intellectual
        property rights in NeuralNode to you.
        
        3. Attribution and Source Notice
        
        If you use, modify, fork, embed, or distribute the Software or a Derivative
        Work, you must clearly and prominently acknowledge NeuralNode and its source
        repository in:
        
          a. the source distribution and its documentation;
          b. a credits, licenses, about, or acknowledgements page in the product; and
          c. the product's administrator-facing documentation or settings page when
             the product has such a page.
        
        The acknowledgement must include substantially the following statement:
        
          "This product uses NeuralNode, a framework owned by TokenAI."
          "Source: https://github.com/tokenaillc/neuralnode"
        
        You must retain this License, existing copyright notices, and all attribution
        notices. You must not remove or obscure the NeuralNode or TokenAI notices.
        
        4. Restrictions
        
        You may not:
        
          a. create, distribute, host, sell, license, or operate a Competing
             Framework based on or incorporating the Software;
          b. offer the Software itself, or a substantially unmodified version of it,
             as a standalone commercial product or hosted service;
          c. remove, alter, or obscure required attribution, copyright, or license
             notices;
          d. use the names, logos, or trademarks "NeuralNode" or "TokenAI" in a way
             that implies endorsement, sponsorship, partnership, or official status;
          e. represent that a fork or Derivative Work is the official NeuralNode
             project; or
          f. sublicense or relicense the Software under terms that conflict with this
             License.
        
        This License does not prevent you from building an application that uses
        NeuralNode as a component, provided that the application is not a Competing
        Framework and the attribution requirements are met.
        
        5. Contributions and Pull Requests
        
        TokenAI welcomes bug fixes, documentation improvements, tests, and other
        proposals submitted through GitHub issues, forks, or pull requests. A pull
        request is a proposal only; it does not become part of NeuralNode unless and
        until TokenAI accepts and merges it.
        
        By intentionally submitting a contribution for inclusion in NeuralNode, you
        agree that TokenAI may review, modify, combine, license, distribute, and
        relicense the contribution as part of NeuralNode under this License or under a
        separate commercial or successor license. You represent that you have the
        right to submit the contribution and that it does not knowingly violate a
        third party's rights.
        
        Submission of a pull request does not give the contributor commit, merge,
        release, or administrative access. TokenAI retains sole discretion to accept,
        request changes to, reject, close, or remove any contribution.
        
        Contributors must follow CONTRIBUTING.md and any contribution agreement or
        Developer Certificate of Origin required by the repository at the time of
        submission.
        
        6. Commercial License
        
        TokenAI may grant separate commercial licenses, waivers, or written
        permissions for uses restricted by this License. A commercial license may
        permit use in a Competing Framework, removal or relocation of attribution,
        white-label distribution, or other uses not permitted here. No commercial
        permission is granted unless it is signed or expressly issued in writing by
        TokenAI.
        
        7. Third-Party Materials
        
        This License applies only to material owned by TokenAI. Third-party libraries,
        models, model weights, APIs, datasets, fonts, images, and other materials are
        not relicensed by this document and remain subject to their own licenses and
        terms. See THIRD_PARTY_NOTICES.md and MODEL_LICENSES.md when present.
        
        8. Trademarks
        
        This License does not grant permission to use TokenAI or NeuralNode trademarks,
        logos, or brand assets except for the attribution required by Section 3 and
        ordinary factual reference to the Software. Additional use is governed by
        TRADEMARKS.md or requires written permission from TokenAI.
        
        9. Termination
        
        The rights granted by this License terminate automatically if you materially
        breach this License. Rights may be reinstated if TokenAI gives you written
        permission or if the breach is cured within thirty (30) days after written
        notice, where cure is possible.
        
        10. Disclaimer and Limitation of Liability
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTIES OR CONDITIONS OF ANY
        KIND, EXPRESS OR IMPLIED, INCLUDING WARRANTIES OF MERCHANTABILITY, FITNESS FOR
        A PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT. TO THE MAXIMUM EXTENT
        PERMITTED BY LAW, TOKENAI AND ITS CONTRIBUTORS SHALL NOT BE LIABLE FOR ANY
        DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
        ARISING FROM THE SOFTWARE OR THIS LICENSE.
        
        11. Governing Terms
        
        This License is intended to be interpreted under the laws applicable to TokenAI
        and the jurisdiction specified in any executed commercial agreement. If any
        provision is held unenforceable, the remaining provisions remain in effect.
        
        This License is a draft public distribution license for NeuralNode Source-
        Available License Version 1.0 and should be reviewed by qualified legal counsel
        before the repository is made public.
License-File: LICENSE
License-File: NOTICE
Keywords: agent,ai,anthropic,automation,embeddings,framework,google,langchain,llm,ollama,openai,rag,tools,vector-stores
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: numpy>=1.24.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: requests>=2.28.0
Provides-Extra: all
Requires-Dist: accelerate>=0.24.0; extra == 'all'
Requires-Dist: anthropic>=0.8.0; extra == 'all'
Requires-Dist: beautifulsoup4>=4.12.0; extra == 'all'
Requires-Dist: bitsandbytes>=0.41.0; extra == 'all'
Requires-Dist: chromadb>=0.4.0; extra == 'all'
Requires-Dist: cohere>=4.0.0; extra == 'all'
Requires-Dist: edge-tts>=6.1.0; extra == 'all'
Requires-Dist: einops>=0.7.0; extra == 'all'
Requires-Dist: faiss-cpu>=1.7.4; extra == 'all'
Requires-Dist: fastapi>=0.110.0; extra == 'all'
Requires-Dist: gguf; extra == 'all'
Requires-Dist: google-generativeai>=0.3.0; extra == 'all'
Requires-Dist: groq>=0.4.0; extra == 'all'
Requires-Dist: huggingface-hub>=0.23.0; extra == 'all'
Requires-Dist: llama-cpp-python>=0.2.0; extra == 'all'
Requires-Dist: mistralai>=0.0.12; extra == 'all'
Requires-Dist: ollama>=0.1.0; extra == 'all'
Requires-Dist: openai>=1.0.0; extra == 'all'
Requires-Dist: protobuf>=3.20.0; extra == 'all'
Requires-Dist: psutil>=5.9.0; extra == 'all'
Requires-Dist: pydub>=0.25.1; extra == 'all'
Requires-Dist: pypdf>=3.17.0; extra == 'all'
Requires-Dist: python-docx>=0.8.11; extra == 'all'
Requires-Dist: python-telegram-bot>=20.0; extra == 'all'
Requires-Dist: scipy>=1.10.0; extra == 'all'
Requires-Dist: sentence-transformers>=2.2.0; extra == 'all'
Requires-Dist: sentencepiece>=0.1.99; extra == 'all'
Requires-Dist: speechrecognition>=3.10.0; extra == 'all'
Requires-Dist: sqlalchemy>=2.0.0; extra == 'all'
Requires-Dist: torch>=2.0.0; extra == 'all'
Requires-Dist: transformers>=4.35.0; extra == 'all'
Requires-Dist: uvicorn>=0.27.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.8.0; extra == 'anthropic'
Provides-Extra: aws
Requires-Dist: boto3>=1.34.0; extra == 'aws'
Provides-Extra: azure
Requires-Dist: openai>=1.0.0; extra == 'azure'
Provides-Extra: chroma
Requires-Dist: chromadb>=0.4.0; extra == 'chroma'
Provides-Extra: cohere
Requires-Dist: cohere>=4.0.0; extra == 'cohere'
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: fastapi>=0.110.0; extra == 'dev'
Requires-Dist: mypy>=1.7.0; extra == 'dev'
Requires-Dist: pillow>=10.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: uvicorn>=0.27.0; extra == 'dev'
Provides-Extra: discord
Requires-Dist: discord-py>=2.3.0; extra == 'discord'
Provides-Extra: embeddings
Requires-Dist: fastembed>=0.1.0; extra == 'embeddings'
Requires-Dist: instructorembedding>=1.0.1; extra == 'embeddings'
Requires-Dist: sentence-transformers>=2.2.0; extra == 'embeddings'
Requires-Dist: tiktoken>=0.5.0; extra == 'embeddings'
Provides-Extra: faiss
Requires-Dist: faiss-cpu>=1.7.4; extra == 'faiss'
Provides-Extra: flash-attn
Requires-Dist: flash-attn>=2.3.0; extra == 'flash-attn'
Provides-Extra: google
Requires-Dist: google-cloud-aiplatform>=1.38.0; extra == 'google'
Requires-Dist: google-generativeai>=0.3.0; extra == 'google'
Provides-Extra: groq
Requires-Dist: groq>=0.4.0; extra == 'groq'
Provides-Extra: hf-audio
Requires-Dist: scipy>=1.11.0; extra == 'hf-audio'
Requires-Dist: soundfile>=0.12.0; extra == 'hf-audio'
Requires-Dist: torch>=2.0.0; extra == 'hf-audio'
Requires-Dist: transformers>=4.35.0; extra == 'hf-audio'
Provides-Extra: horus
Requires-Dist: accelerate>=0.24.0; extra == 'horus'
Requires-Dist: bitsandbytes>=0.41.0; extra == 'horus'
Requires-Dist: diffusers>=0.30.0; extra == 'horus'
Requires-Dist: einops>=0.7.0; extra == 'horus'
Requires-Dist: gguf; extra == 'horus'
Requires-Dist: huggingface-hub>=0.23.0; extra == 'horus'
Requires-Dist: llama-cpp-python>=0.2.0; extra == 'horus'
Requires-Dist: pillow>=10.0.0; extra == 'horus'
Requires-Dist: protobuf>=3.20.0; extra == 'horus'
Requires-Dist: scipy>=1.10.0; extra == 'horus'
Requires-Dist: sentencepiece>=0.1.99; extra == 'horus'
Requires-Dist: torch>=2.0.0; extra == 'horus'
Requires-Dist: transformers>=4.35.0; extra == 'horus'
Provides-Extra: image
Requires-Dist: accelerate>=0.24.0; extra == 'image'
Requires-Dist: diffusers>=0.30.0; extra == 'image'
Requires-Dist: pillow>=10.0.0; extra == 'image'
Requires-Dist: torch>=2.0.0; extra == 'image'
Requires-Dist: transformers>=4.35.0; extra == 'image'
Provides-Extra: local
Requires-Dist: accelerate>=0.24.0; extra == 'local'
Requires-Dist: gguf; extra == 'local'
Requires-Dist: huggingface-hub>=0.23.0; extra == 'local'
Requires-Dist: llama-cpp-python>=0.2.0; extra == 'local'
Requires-Dist: protobuf>=3.20.0; extra == 'local'
Requires-Dist: sentencepiece>=0.1.99; extra == 'local'
Requires-Dist: torch>=2.0.0; extra == 'local'
Requires-Dist: transformers>=4.35.0; extra == 'local'
Provides-Extra: local-all
Requires-Dist: accelerate>=0.24.0; extra == 'local-all'
Requires-Dist: bitsandbytes>=0.41.0; extra == 'local-all'
Requires-Dist: einops>=0.7.0; extra == 'local-all'
Requires-Dist: gguf; extra == 'local-all'
Requires-Dist: huggingface-hub>=0.23.0; extra == 'local-all'
Requires-Dist: llama-cpp-python>=0.2.0; extra == 'local-all'
Requires-Dist: protobuf>=3.20.0; extra == 'local-all'
Requires-Dist: scipy>=1.10.0; extra == 'local-all'
Requires-Dist: sentencepiece>=0.1.99; extra == 'local-all'
Requires-Dist: torch>=2.0.0; extra == 'local-all'
Requires-Dist: transformers>=4.35.0; extra == 'local-all'
Provides-Extra: milvus
Requires-Dist: pymilvus>=2.3.0; extra == 'milvus'
Provides-Extra: mistral
Requires-Dist: mistralai>=0.0.12; extra == 'mistral'
Provides-Extra: ollama
Requires-Dist: ollama>=0.1.0; extra == 'ollama'
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == 'openai'
Provides-Extra: openclaw
Requires-Dist: fastapi>=0.110.0; extra == 'openclaw'
Requires-Dist: uvicorn>=0.27.0; extra == 'openclaw'
Provides-Extra: pinecone
Requires-Dist: pinecone-client>=2.2.0; extra == 'pinecone'
Provides-Extra: qdrant
Requires-Dist: qdrant-client>=1.6.0; extra == 'qdrant'
Provides-Extra: rag
Requires-Dist: beautifulsoup4>=4.12.0; extra == 'rag'
Requires-Dist: markdown>=3.5.0; extra == 'rag'
Requires-Dist: openpyxl>=3.1.0; extra == 'rag'
Requires-Dist: pypdf>=3.17.0; extra == 'rag'
Requires-Dist: python-docx>=0.8.11; extra == 'rag'
Provides-Extra: redis
Requires-Dist: redis>=5.0.0; extra == 'redis'
Provides-Extra: replica
Requires-Dist: edge-tts>=6.1.0; extra == 'replica'
Provides-Extra: slack
Requires-Dist: slack-sdk>=3.21.0; extra == 'slack'
Provides-Extra: speech
Requires-Dist: pydub>=0.25.1; extra == 'speech'
Requires-Dist: speechrecognition>=3.10.0; extra == 'speech'
Provides-Extra: telegram
Requires-Dist: edge-tts>=6.1.0; extra == 'telegram'
Requires-Dist: pydub>=0.25.1; extra == 'telegram'
Requires-Dist: pypdf>=3.17.0; extra == 'telegram'
Requires-Dist: python-docx>=0.8.11; extra == 'telegram'
Requires-Dist: python-telegram-bot>=20.0; extra == 'telegram'
Requires-Dist: speechrecognition>=3.10.0; extra == 'telegram'
Provides-Extra: tools
Requires-Dist: psutil>=5.9.0; extra == 'tools'
Requires-Dist: pymongo>=4.6.0; extra == 'tools'
Requires-Dist: serpapi>=0.1.0; extra == 'tools'
Requires-Dist: sqlalchemy>=2.0.0; extra == 'tools'
Requires-Dist: wikipedia>=1.4.0; extra == 'tools'
Provides-Extra: turboquant
Provides-Extra: vision
Requires-Dist: pillow>=9.0; extra == 'vision'
Provides-Extra: weaviate
Requires-Dist: weaviate-client>=3.0.0; extra == 'weaviate'
Description-Content-Type: text/markdown

<p align="center">
    <img src="https://raw.githubusercontent.com/tokenaillc/neuralnode/v2.2.8/media/neuralnode.png" alt="NeuralNode — Connect models. Build AI." width="720">
</p>

<p align="center">
  <a href="https://pypi.org/project/neuralnode/"><img src="https://img.shields.io/pypi/v/neuralnode.svg?style=flat-square" alt="PyPI version"></a>
  <a href="https://pypi.org/project/neuralnode/"><img src="https://img.shields.io/pypi/pyversions/neuralnode.svg?style=flat-square" alt="Python versions"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Source--Available-172033.svg?style=flat-square" alt="Source-Available License"></a>
  <a href="https://github.com/tokenaillc/neuralnode/releases"><img src="https://img.shields.io/github/v/release/tokenaillc/neuralnode?display_name=tag&sort=semver&style=flat-square" alt="Latest release"></a>
</p>

<p align="center"><strong>Connect models. Build AI.</strong></p>

<p align="center">NeuralNode <code>v2.2.8</code></p>

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.

## What's new in 2.2.8

NeuralNode 2.2.8 expands the framework's local-model and multimodal building
blocks while making the public release safer to build and publish.

- Added Hugging Face authentication support for public, private, and gated
  model repositories through the `HF_TOKEN` environment variable or an
  explicit token argument.
- Added local Hugging Face speech adapters for speech-to-text and text-to-speech,
  including lazy loading, automatic CPU/CUDA selection, configurable model IDs,
  language handling, and WAV output.
- Added a sequential `VoiceAgent` workflow that connects audio transcription,
  an agent turn, and speech synthesis for file-based and push-to-talk use cases.
- Added local vision-language input and Diffusers-compatible text-to-image
  generation through dedicated Hugging Face model loaders.
- Improved Horus model loading, provider identity, deterministic generation,
  optional runtime imports, and model repository download behavior.
- Improved provider-backed agent tool calling, including textual actions and
  tool-result handling.
- Added and aligned OpenClaw integration behavior, including safer local API
  access and test coverage that does not require optional HTTP test packages.
- Hardened the release pipeline with source and wheel build validation,
  isolated build output, and trusted publishing to PyPI through GitHub Actions.

For the complete release record, see [CHANGELOG.md](CHANGELOG.md).

## 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

```bash
pip install neuralnode
```

```python
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

```bash
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.

```bash
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.

```python
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.

```python
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.

```python
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

- [Model API deployment](docs/model_api.md)
- [Examples](examples/)
- [Contributing](CONTRIBUTING.md)
- [License and ownership](LICENSE)

## Horus

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.

```python
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

```python
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-Cyber-Nano-1.0`
- `Horus-Cyber-Nano-1.0-Q4_K_M.gguf`
- `Horus-Cyber-Nano-1.0-Q5_K_M.gguf`
- `Horus-Cyber-Nano-1.0-Q6_K.gguf`
- `Horus-Cyber-Nano-1.0-Q8_0.gguf`
- `Horus-Cyber-Nano-1.0-F16.gguf`
- `Horus-Taleeq-0.2B-Base`

### Horus Hiero

```python
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

```python
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.

```python
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.md)
- [docs/replica_voice_ids.csv](docs/replica_voice_ids.csv)

## Horus + Replica

```python
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.

```python
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

```python
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-compatible providers are fully supported (OpenAI, OpenRouter, and AgentRouter).
- 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.

## Links

- **TokenAI**: [https://tokenai.llc/](https://tokenai.llc/)
- **NeuralNode**: [https://tokenai.llc/](https://tokenai.llc/)

## 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](LICENSE), [NOTICE](NOTICE), [TRADEMARKS.md](TRADEMARKS.md), and
[THIRD_PARTY_NOTICES.md](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](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:

```python
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:

