Metadata-Version: 2.4
Name: neuralbridge-sdk
Version: 1.6.3
Summary: AI Agent Runtime Operations Platform — Diagnose. Self-Heal. Survive.
Author-email: Guigui Wang <Wgg234114134@163.com>
License-Expression: MIT
Project-URL: Homepage, https://neuralbridge.cn
Project-URL: Repository, https://github.com/hhhfs9s7y9-code/neuralbridge-sdk
Project-URL: Issues, https://github.com/hhhfs9s7y9-code/neuralbridge-sdk/issues
Keywords: agent,ops,self-heal,circuit-breaker,reliability,LLM,AI,LLMOps
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
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: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: httpx>=0.24.0
Dynamic: license-file

# NeuralBridge SDK

[![PyPI](https://img.shields.io/pypi/v/neuralbridge-sdk?color=blue&label=PyPI)](https://pypi.org/project/neuralbridge-sdk/)
[![Python](https://img.shields.io/pypi/pyversions/neuralbridge-sdk.svg)](https://pypi.org/project/neuralbridge-sdk/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Size](https://img.shields.io/badge/size-74.3KB-blueviolet)](https://pypi.org/project/neuralbridge-sdk/)

**The World's First AI Agent Self-Healing Infrastructure.**

Detect API failures in 6.7μs. Self-heal 95.19% of failures automatically. Every healed failure is energy saved.

```bash
pip install neuralbridge-sdk
nb-doctor scan
```

## The Problem

Every AI Agent fails. The question is: **how fast do you know, and can it fix itself?**

- Your LLM call times out → Your agent hangs → Your user leaves
- Your model swaps GPT-4 for GPT-3.5 → Your output quality tanks silently
- A downstream API rate-limits → Your entire pipeline cascades into failure

Datadog's 2026 report: **5% of all LLM API calls fail in production.** 60% caused by rate limits and capacity issues.

## The NeuralBridge Flywheel

```
┌─────────────┐    ┌──────────────┐    ┌──────────────┐
│   Detect    │───▶│  Diagnose    │───▶│   Self-Heal  │
│   6.7μs     │    │  L1/L2/L3    │    │   95.19%     │
└─────────────┘    └──────────────┘    └──────┬───────┘
       ▲                                      │
       │         ┌──────────────┐             │
       └─────────│  Adapt &     │◀────────────┘
                 │  Learn       │
                 └──────────────┘
```

1. **Detect** — 6.7μs median diagnosis latency
2. **Diagnose** — 3-tier self-healing (retry → model downgrade → provider switch)
3. **Self-Heal** — 95.19% recovery rate on recoverable failures
4. **Adapt** — Learn from failures, optimize routing automatically

## Performance (v1.6.3)

| Metric | Value |
|---|---|
| Diagnosis Latency (Median) | **6.7 μs** |
| Self-Heal Success Rate | **95.19%** |
| Supported Providers | **7** (OpenAI, Anthropic, Google, NVIDIA, Groq, DashScope, OpenRouter) |
| Package Size | **74.3 KB** |
| External Dependencies | **1 (httpx)** |

## 7-Provider Self-Healing Chain

When OpenAI 503s → auto-switch to NVIDIA NIM → then Anthropic → then DashScope. **Your agent never sees a failure.**

| Priority | Provider | Fallback Models |
|----------|----------|-----------------|
| 1 | OpenAI | gpt-4o → gpt-4o-mini → gpt-3.5-turbo |
| 2 | Anthropic | claude-sonnet-4 → claude-3.5-haiku |
| 3 | **NVIDIA NIM** ⭐ | llama-3.1-405b → 70b → 8b |
| 4 | DashScope | qwen-max → qwen-plus → qwen-turbo |

## Quick Start

```python
from neuralbridge import SelfHealingEngine

# Auto-configure from environment variables
from neuralbridge import auto_setup
engine = auto_setup()

# Or manually configure
engine = SelfHealingEngine(
    providers=["openai", "nvidia", "anthropic"],
    max_retries=3,
)

# The engine handles failures automatically
response = engine.call("Analyze this PR", model="gpt-4o")
```

## Energy Impact

Every self-heal saves ~1Wh of wasted compute and reduces 0.3g CO₂.

At global scale (5% failure rate × 60% infra overhead × 95.19% heal rate = 2.86% compute recovered):

- **~4.86 TWh/year** saved ≈ half a nuclear power plant
- **~146,000 tons CO₂** not emitted annually

**Every healed failure is energy saved.**

## nb-doctor — Free Diagnostic Tool

```bash
nb-doctor scan                    # Scan codebase for risks
nb-doctor diagnose --api-key KEY  # Diagnose a specific API
```

Free. No registration. Instant answers on why your AI API is broken.

## Supported Providers

| Provider | Adapter | Base URL |
|----------|---------|----------|
| OpenAI | `OpenAIAdapter` | api.openai.com |
| Anthropic | `AnthropicAdapter` | api.anthropic.com |
| Google | `GoogleAdapter` | generativelanguage.googleapis.com |
| **NVIDIA** | `NVIDIAAdapter` | integrate.api.nvidia.com |
| Groq | `GroqAdapter` | api.groq.com |
| DashScope | `DashScopeAdapter` | dashscope.aliyuncs.com |
| OpenRouter | `OpenRouterAdapter` | openrouter.ai |

## Architecture

```
┌─────────────────────────────────────────┐
│            Your AI Agent                │
├─────────────────────────────────────────┤
│  NeuralBridge SDK                       │
│  ┌──────────┐ ┌──────────┐ ┌────────┐  │
│  │Diagnoser │ │SelfHealer│ │Health  │  │
│  │ 6.7μs    │ │ 95.19%   │ │Scorer  │  │
│  └────┬─────┘ └────┬─────┘ └───┬────┘  │
│       └─────────────┼───────────┘       │
│               ┌─────┴─────┐             │
│               │CostTracker│             │
│               └───────────┘             │
├─────────────────────────────────────────┤
│  OpenAI │ Anthropic │ NVIDIA │ DashScope│
└─────────────────────────────────────────┘
```

## Links

- 🌐 Website: [neuralbridge.cn](https://www.neuralbridge.cn/)
- 📖 Docs: [docs.neuralbridge.cn](https://docs.neuralbridge.cn/)
- 📦 PyPI: [neuralbridge-sdk](https://pypi.org/project/neuralbridge-sdk/)
- 🐛 Issues: [GitHub](https://github.com/hhhfs9s7y9-code/neuralbridge-sdk)

## License

MIT License — © 2026 王桂桂 / NeuralBridge
