Metadata-Version: 2.1
Name: neuralbridge-sdk
Version: 5.1.1
Summary: NeuralBridge — Self-healing layer for production AI agents. Auto-failover across 200+ LLMs, drift detection, contract validation, checkpoint recovery, cost optimization. 1 dependency. BYOK.
Author-email: NeuralBridge Team <team@neuralbridge.dev>
Maintainer-email: NeuralBridge Team <team@neuralbridge.dev>
License: Apache-2.0
Project-URL: Homepage, https://neuralbridge.dev
Project-URL: Repository, https://github.com/hhhfs9s7y9-code/neuralbridge-sdk
Project-URL: Documentation, https://neuralbridge.dev/docs
Project-URL: Bug Tracker, https://github.com/hhhfs9s7y9-code/neuralbridge-sdk/issues
Project-URL: Changelog, https://github.com/hhhfs9s7y9-code/neuralbridge-sdk/blob/main/CHANGELOG.md
Keywords: llm,self-healing,failover,circuit-breaker,api-resilience,openai,anthropic,deepseek,contract-validation,agent,drift-detection,checkpoint,byok
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: httpx>=0.24.0
Provides-Extra: redis
Requires-Dist: redis; extra == "redis"
Provides-Extra: otel
Requires-Dist: opentelemetry-api; extra == "otel"
Requires-Dist: opentelemetry-sdk; extra == "otel"
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc; extra == "otel"
Provides-Extra: all
Requires-Dist: httpx>=0.24.0; extra == "all"
Requires-Dist: redis; extra == "all"
Requires-Dist: opentelemetry-api; extra == "all"
Requires-Dist: opentelemetry-sdk; extra == "all"
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: cython>=3.0; extra == "dev"


<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/hhhfs9s7y9-code/neuralbridge-sdk/main/assets/logo-dark.svg">
    <img alt="NeuralBridge" src="https://raw.githubusercontent.com/hhhfs9s7y9-code/neuralbridge-sdk/main/assets/logo-light.svg" width="480">
  </picture>
</p>

<p align="center">
  <b>The self-healing layer for production AI agents.</b><br>
  One line of code. Zero extra latency. Automatic failover across 200+ providers.
</p>

<p align="center">
  <a href="https://pypi.org/project/neuralbridge-sdk/"><img src="https://img.shields.io/pypi/v/neuralbridge-sdk?label=PyPI" alt="PyPI version"></a>
  <a href="https://pypi.org/project/neuralbridge-sdk/"><img src="https://img.shields.io/pypi/pyversions/neuralbridge-sdk" alt="Python versions"></a>
  <a href="https://pypi.org/project/neuralbridge-sdk/"><img src="https://img.shields.io/pypi/dm/neuralbridge-sdk" alt="Downloads"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue" alt="License"></a>
  <a href="https://github.com/hhhfs9s7y9-code/neuralbridge-sdk"><img src="https://img.shields.io/github/stars/hhhfs9s7y9-code/neuralbridge-sdk?style=flat" alt="GitHub stars"></a>
</p>

---

```bash
pip install neuralbridge-sdk
```

```python
import neuralbridge as nb

result = nb.chat("Build a Python quicksort")
print(result.text)
# >> Here's a clean quicksort implementation...
```

**That's it.** NeuralBridge auto-discovers your API keys from environment variables, picks the best provider, routes around failures, and keeps your agent running when APIs go down.

---

## Why NeuralBridge?

LLM APIs are **inherently unreliable**. Every production AI team hits the same wall:

| Problem | Impact | Frequency |
|---------|--------|-----------|
| Provider rate limits (429) | Requests dropped | Multiple times daily |
| API timeouts | Agent hangs | 5–50 per 1K calls |
| Output quality drift | User complaints | 2–3 days after model update |
| Provider outages (5xx) | Service down | 1–3 per month |
| Uncontrolled costs | Budget overrun | Inevitable without governance |

**Existing solutions fall short:**

- **DIY retry logic** → reinventing the wheel, every project, forever
- **API gateways** → +30–200ms latency, another single point of failure
- **Framework plugins** → locked into LangChain/LlamaIndex

### NeuralBridge is different.

It's not a gateway. It's not a proxy. It's an **in-process self-healing engine** that lives inside your AI agent's process — zero additional network hops, zero latency overhead, one dependency.

---

## The Four-Layer Self-Healing Architecture

NeuralBridge's MAPE-K (Monitor → Analyze → Plan → Execute → Knowledge) adaptive loop operates at four escalating levels:

```
┌─────────────────────────────────────────────────────────┐
│                    Your AI Agent                         │
├─────────────────────────────────────────────────────────┤
│  L1: Instant Retry          ┆  280+ fault patterns       │
│  L2: Degrade Gracefully     ┆  30+ recovery strategies   │
│  L3: Provider Failover      ┆  200+ providers            │
│  L4: Flywheel Learning      ┆  88+ learned rules         │
├─────────────────────────────────────────────────────────┤
│  ↗ Self-healing engine     ↗ Checkpoint recovery        │
│  ↗ Drift detection         ↗ Contract verification       │
│  ↗ Cost optimization       ↗ Carbon tracking             │
└─────────────────────────────────────────────────────────┘
```

| Layer | What it does | Recovery rate |
|-------|-------------|---------------|
| **L1 — Instant Retry** | Detects fault patterns (429, 503, timeout, empty response) and retries with exponential backoff + jitter | 62% |
| **L2 — Graceful Degrade** | Falls back to a cheaper model, reduces context window, or switches to async mode | 16% |
| **L3 — Provider Failover** | Transparently routes to an alternative provider (no-opener if you have multiple API keys) | 5% |
| **L4 — Flywheel Learning** | Learns from every fault — builds a local rulebase that improves over time | 1.1% |

**Overall: 84.1% of all production LLM faults are automatically recovered** (measured across 5,085 real repair events).

---

## Features

### 🛡️ Self-Healing Engine
280+ fault patterns identified in real time. 30+ recovery strategies. Automatically detects and recovers from rate limits, timeouts, empty responses, provider 500s, model overloads, and semantic drift.

### 🔀 Smart Multi-Provider Routing
Routes each request to the optimal provider based on cost, latency, or fallback strategy. Auto-detects providers from `DEEPSEEK_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, and more.

### ⏱️ Checkpoint Recovery
When your agent crashes mid-execution, resume from the last completed step — zero API calls replayed for cached steps. Saves both time and money.

```python
from neuralbridge import Checkpoint

cp = Checkpoint("research-agent")

papers    = cp.step("search",    lambda: nb.chat("Search quantum papers").text)
analysis  = cp.step("analyze",   lambda: nb.chat(f"Analyze: {papers}").text)
report    = cp.step("summarize", lambda: nb.chat(f"Summarize: {analysis}").text)

# If crash at step 3 → next run resumes from step 3
# Steps 1–2 return cached results (zero API calls)
```

### ✅ Contract-Based Output Validation
Five-dimensional output validation: JSON Schema conformance, semantic boundaries, entity integrity, taboo pattern detection, and composite contracts. Catch model regressions before your users do.

### 📊 Real-Time Dashboard
Web-based monitoring dashboard with live metrics: call volume, cost tracking, error rates, latency distribution, and provider health. Spawns in one line:

```python
nb.dashboard()  # → http://localhost:8765
```

### 🔍 Drift Detection
Continuous monitoring for four types of drift: semantic (output quality degradation), model behavior (provider model swaps), routing (strategy deviation), and provider performance (latency/error rate trends). Sliding window + EMA analysis with INFO/WARN/CRITICAL alerts.

### 💰 Cost Optimization
Smart routing reduces LLM costs by 30–60% by automatically selecting the most cost-effective provider for each request's complexity tier. Includes per-model cost tracking and savings reports.

### 🌱 Carbon Tracking
Tracks CO₂ emissions per model call with tier-based energy coefficients (premium/standard/mini) and grid carbon intensity. Built-in support for 12+ providers including OpenAI, Anthropic, DeepSeek, Google, and DashScope.

### 🚪 OpenAI-Compatible Gateway
Drop-in proxy server that replaces the OpenAI API endpoint with MAPE-K self-healing. Works with any OpenAI-compatible client:

```bash
python -m neuralbridge.gateway --port 8080
```

---

## Quick Start

### Installation

```bash
pip install neuralbridge-sdk
```

**Single dependency:** `httpx`. That's it. 375 KB total.

### Set your API keys

```bash
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
export DEEPSEEK_API_KEY=sk-...
```

### Chat

```python
import neuralbridge as nb

# One-line chat with auto-routing
result = nb.chat("Explain quantum computing in simple terms")
print(result.text)

# See routing decision and cost
print(f"Provider: {result.provider} / Model: {result.model}")
```

### Terminal dashboard

```python
nb.status()
```

Shows provider health, call stats, and cost summary — right in your terminal.

### Async support

```python
result = await nb.chat_async("Write a Python script to analyze CSV data")
```

---

## Performance

| Metric | Value |
|--------|-------|
| Fault diagnosis (P50) | **19.0 μs** |
| Contract validation (P50) | **3.1 μs** |
| Auto-recovery rate | **84.1%** (5,085 real repairs) |
| SDK efficiency | **15.9% faster** than raw httpx |
| Package size | **375.5 KB** |
| Fault patterns | **280+** |
| Recovery strategies | **30+** |
| Runtime dependencies | **1** (`httpx`) |
| Learned repair rules | **88+** (Flywheel) |

---

## Open Core

NeuralBridge SDK is **open core** — the full routing, diagnosis, and self-healing core is Apache 2.0 licensed and free to use. Advanced production features are available through commercial licenses.

| Tier | License | Price | Best for |
|------|---------|-------|----------|
| 🟢 **Open SDK** | Apache 2.0 | **Free** | Evaluation, prototypes, personal projects |
| 🔵 **Pro Individual** | Commercial | **$99/year** | Solo developers, indie hackers |
| 🟡 **Professional** | Commercial | **$499/month** | Teams, SMBs, production workloads |
| 🔴 **Enterprise** | Commercial | **$1,499/month** | Large organizations, compliance requirements |
| ⚫ **Enterprise Custom** | Custom | **Contact us** | Dedicated deployment, SLA, on-premise |

> 💡 **Try before you buy:** `pip install neuralbridge-sdk` → `nb.chat("hi")` — full-featured 7-day trial. Auto-downgrades after trial with zero data loss.

### What's in each tier

| Feature | Open SDK | Pro | Professional | Enterprise |
|---------|----------|-----|-------------|------------|
| Smart routing | ✅ | ✅ | ✅ | ✅ |
| Auto failover | ✅ | ✅ | ✅ | ✅ |
| Circuit breaker | ✅ | ✅ | ✅ | ✅ |
| 280+ fault patterns | ✅ | ✅ | ✅ | ✅ |
| Terminal dashboard | ✅ | ✅ | ✅ | ✅ |
| **L4 Flywheel learning** | — | ✅ | ✅ | ✅ |
| **Contract validation** | — | ✅ | ✅ | ✅ |
| **Checkpoint recovery** | — | ✅ | ✅ | ✅ |
| **Drift detection** | — | ✅ | ✅ | ✅ |
| **Real-time dashboard** | — | ✅ | ✅ | ✅ |
| **Carbon tracking** | — | ✅ | ✅ | ✅ |
| **Gateway proxy** | — | ✅ | ✅ | ✅ |
| Multi-team RBAC | — | — | ✅ | ✅ |
| Audit logging | — | — | ✅ | ✅ |
| SSO / SAML | — | — | — | ✅ |
| On-premise deployment | — | — | — | ✅ |
| Dedicated support | — | — | — | ✅ |
| SLA | — | — | 99.9% | 99.99% |

---

## Why not a gateway?

Every existing solution adds a network hop:

```
Your App → Gateway → LLM API         ← gateway approach (+30–200ms)
Your App (NeuralBridge embedded) → LLM API   ← SDK approach (+0ms)
```

| Dimension | Gateway (Portkey / LiteLLM / OpenRouter) | NeuralBridge (embedded SDK) |
|-----------|------------------------------------------|-----------------------------|
| **Architecture** | Out-of-process proxy | In-process library |
| **Latency overhead** | +30–200ms | 0ms |
| **Single point of failure?** | Yes — the gateway itself | No — no intermediate hop |
| **Deployment complexity** | Docker, K8s, networking | `pip install` |
| **Data residency** | Traffic passes through gateway | Stays in your process |
| **Dependencies** | 10+ containers/services | 1 (httpx) |

---

## Docs & Resources

- [5-Minute Quick Start](docs/quick-start.md)
- [API Reference](docs/api-reference.md)
- [Product Manual](docs/product-manual.md)
- [Pricing & SLA](docs/sla-pricing.md)
- [Benchmark Comparison](NEURALBRIDGE_BENCHMARK_COMPARISON.md)
- [Changelog](CHANGELOG.md)
- [GitHub Issues](https://github.com/hhhfs9s7y9-code/neuralbridge-sdk/issues)

## Contributing

We welcome community contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) and [CLA.md](CLA.md).

**Note:** NeuralBridge is a commercial open-core product — advanced features require a paid license. The Open SDK core is fully Apache 2.0.

## License

- **Open SDK core**: Apache 2.0 ([LICENSE](LICENSE))
- **Commercial components** (`_engine`, `_sentry`, MCD daemon): Closed-source commercial license

```
Copyright 2024-2026 NeuralBridge Team
Licensed under the Apache License, Version 2.0
```

## Contact

- Website: [https://neuralbridge.dev](https://neuralbridge.dev)
- GitHub: [https://github.com/hhhfs9s7y9-code/neuralbridge-sdk](https://github.com/hhhfs9s7y9-code/neuralbridge-sdk)
- Documentation: [https://neuralbridge.dev/docs](https://neuralbridge.dev/docs)
- Enterprise sales: [sales@neuralbridge.dev](mailto:sales@neuralbridge.dev)

---

<p align="center">
  <b>NeuralBridge — The self-healing layer for production AI agents.</b><br>
  <code>pip install neuralbridge-sdk</code>
</p>
