Metadata-Version: 2.4
Name: neuralbrok
Version: 3.0.1
Summary: Agent orchestration platform — hardware-aware routing, MCP server, swarm intelligence, OpenAI-compatible
Project-URL: Homepage, https://neuralbroker.space
Project-URL: Repository, https://github.com/khan-sha/neuralbroker
Project-URL: Documentation, https://github.com/khan-sha/neuralbroker#readme
License: MIT License
        
        Copyright (c) 2026 NeuralBroker contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: llm,local-ai,ollama,openai-compatible,routing,vram
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: boto3>=1.34.0
Requires-Dist: click>=8.1.0
Requires-Dist: fastapi>=0.110.0
Requires-Dist: google-cloud-aiplatform>=1.50.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: litellm>=1.40
Requires-Dist: llmfit>=0.9.0
Requires-Dist: networkx>=3.3
Requires-Dist: nvidia-ml-py>=12.0.0
Requires-Dist: prometheus-client>=0.20.0
Requires-Dist: psutil>=6.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: redis>=5.0.0
Requires-Dist: resend>=0.7.0
Requires-Dist: sse-starlette>=2.1
Requires-Dist: uvicorn[standard]>=0.29.0
Provides-Extra: dev
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# 🧠 NeuralBroker 3.0: Unified Neural Gateway & Agent Orchestration

<div align="center">
  <img src="logo.svg" width="280" alt="NeuralBroker logo" />
  <br/>
  <h3>VRAM-Aware Routing · Knowledge Graph Memory · Swarm Intelligence · Zero-Trust Federation</h3>
</div>

<p align="center">
  <a href="https://pypi.org/project/neuralbrok/"><img alt="PyPI" src="https://img.shields.io/pypi/v/neuralbrok.svg?color=hotpink"></a>
  <a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-green"></a>
  <a href="https://discord.gg/neuralbroker"><img alt="Discord" src="https://img.shields.io/badge/Discord-Join-7289DA?style=flat&logo=discord"></a>
  <a href="https://neuralbroker.space"><img alt="Website" src="https://img.shields.io/badge/website-neuralbroker.space-pink"></a>
</p>

---

## ⚡ The Ultimate Agent Orchestration Platform

**NeuralBroker 3.0** transforms your machine into a **Swarm-Native Orchestration Node**. It goes far beyond standard model routing by merging the inference gateway, the swarm orchestrator, and structural memory into a single, self-improving daemon. 

It automatically evaluates your hardware, coordinates multi-agent task pipelines, builds a persistent graph memory of its actions, and securely talks to other machines across the internet via Zero-Trust Federation.

```bash
pip install neuralbrok
neuralbrok start
```

That's it. Point **Cursor**, **Claude Code**, **Cline**, or any OpenAI/Anthropic-compatible app at `http://localhost:8000`, and the NeuralBroker Gateway takes over.

---

## 🌟 What's New in v3.0: The Unified Vision

### 🔌 1. Unified Inference Gateway
NeuralBroker now acts as a native **Anthropic & OpenAI compatible proxy** via a single port (`:8000`).
- **Protocol Normalization**: Transparently routes both `/v1/messages` (Anthropic) and `/v1/chat/completions` (OpenAI) calls to any provider (Ollama, NVIDIA NIM, DeepSeek, OpenRouter) using LiteLLM.
- **Hardware-Aware Routing**: Automatically falls back to cloud when VRAM is saturated or when task complexity requires a frontier model.
- **Subscription Inheritance**: It reads the OAuth session your Claude Code CLI holds in `~/.claude/.credentials.json` and uses the `claude` binary as a free inference backend for hard tasks that spill over from your local GPU.

### 🕸️ 2. Neural Knowledge Graph & AgentDB
Every interaction creates a trace. NeuralBroker doesn't just store logs; it builds a **persistent graph memory** (NetworkX + SQLite) above its zero-dependency HNSW vector store.
- **Entity Linking**: Decisions, task outcomes, errors, and reasoning chains are stored as typed nodes.
- **Auto-Learning**: Agents query the graph before execution to inject historical context and avoid repeating past mistakes.
- **Live Visualization**: A real-time D3.js dashboard at `http://localhost:8000/dashboard/graph` visualizes the growth of your system's knowledge.

### 🛠️ 3. One-Command IDE Auto-Wiring
Zero configuration for your favorite IDEs.
When you run `neuralbrok start`, NeuralBroker automatically detects your IDEs (Cursor, VS Code, Claude Code) and **auto-wires** them to use the local gateway by injecting the proper environment variables and settings.

### 🐝 4. Agentic Swarms & Task Coordination
NeuralBroker doesn't just route prompts; it routes *objectives*. The built-in `SwarmCoordinator` decomposes complex user requests into **Plan → Execute → Review** pipelines, automatically picking the best specialized local agent (Coder, Planner, Reviewer, Analyst) for each subtask.

### 🧠 5. NeuralFit Hardware Intelligence
Powered by a native Python implementation of our advanced hardware scoring algorithm, NeuralBroker scores models across **Quality**, **Speed**, **Fit**, and **Context** based on your exact hardware specifications (NVIDIA, Apple Silicon, AMD, or CPU).
*Run `neuralbrok setup` to see your live VRAM projections and auto-select optimal models.*

### 🛡️ 6. Security & AIDefence
Every prompt is scrubbed:
- **PII Redaction:** AWS keys, emails, and SSNs are automatically masked before reaching cloud LLMs.
- **Injection Shield:** Federated incoming requests are heuristically scanned for adversarial jailbreaks.

### 🌐 7. Zero-Trust Federation
Swarms can securely communicate across networks. Using our local **mTLS/Ed25519-style** crypto module, your agents can encrypt and sign payloads and send them to other NeuralBroker nodes. Untrusted nodes are automatically downgraded. 

### 🤖 8. Background Workers (Autopilot)
When your machine is idle, NeuralBroker wakes up. The internal `WorkerDaemon` launches background tasks to optimize codebases and run simulated security audits while you sleep.

### 🔌 9. MCP Server & Dynamic Plugins
NeuralBroker functions as a native **Model Context Protocol (MCP)** server via stdio. Connect Claude Code directly to it. You can dynamically load `.yaml` agent definitions into your `~/.neuralbrok/plugins/` directory and share them with the community.

---

## 💻 Quickstart

### 1. Install & Configure
```bash
pip install neuralbrok

# Detect hardware and auto-configure optimal models
neuralbrok setup
```

### 2. Start the Gateway
```bash
# Starts the unified gateway on port 8000 and auto-wires your IDEs
neuralbrok start
```

### 3. Explore the Knowledge Graph
```bash
# Open the live memory visualizer in your browser
neuralbrok graph open

# Query the structural memory
neuralbrok memory search "database schema"
```

### 4. View Telemetry Dashboard
Open `http://localhost:8000/dashboard` to view the live **Pink Matrix** telemetry UI, complete with routing waterfalls and VRAM gauges.

---

## 🏗️ Architecture

```mermaid
graph TD
    User([IDE / Agent SDK / Claude Code]) --> Gateway[NeuralBroker Gateway :8000]
    
    Gateway --> Policy[VRAM Policy Engine]
    Policy --> Local[Local Ollama / CUDA]
    Policy --> Cloud[Cloud / NVIDIA NIM / OpenRouter / Claude Subprocess]
    
    Gateway --> Swarm[Swarm Orchestrator]
    
    Swarm --> Memory[(Neural Knowledge Graph)]
    Memory --> Reasoning[Graph-Augmented Context]
    Reasoning -.-> Swarm
```

---

## 🛠️ Development

```bash
git clone https://github.com/khan-sha/neuralbroker.git
cd neuralbroker
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
pytest tests/
```

## 📜 License
MIT © 2026 NeuralBroker Team. Built with 💖 by the Google Deepmind team (Advanced Agentic Coding).
