Metadata-Version: 2.2
Name: neuralbridge-sdk
Version: 4.4.2
Summary: NeuralBridge — Agent stability SDK. Smart routing, auto-failover, crash recovery (checkpoint), contract validation. 1 dependency.
Author-email: NeuralBridge Team <wangguigui@neuralbridge.cn>
License: Apache-2.0
Project-URL: Homepage, https://www.neuralbridge.cn
Project-URL: Repository, https://github.com/hhhfs9s7y9-code/neuralbridge-sdk
Project-URL: Documentation, https://www.neuralbridge.cn/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
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
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: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: Cython>=3.0; extra == "dev"

# NeuralBridge SDK

**Claude goes down. Your Agent stays up.**

[![PyPI](https://img.shields.io/pypi/v/neuralbridge-sdk)](https://pypi.org/project/neuralbridge-sdk/)
[![Python](https://img.shields.io/pypi/pyversions/neuralbridge-sdk)](https://pypi.org/project/neuralbridge-sdk/)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)

NeuralBridge is an embedded stability SDK for LLM API calls. One package, four capabilities:

| Module | What it does | Who needs it |
|--------|-------------|--------------|
| **NB Router** | Smart routing + cost optimization | CFO / Cost-conscious teams |
| **NB Shield** | Auto failover + self-healing | SRE / Production reliability |
| **NB Checkpoint** | Agent crash recovery + resume | Agent developers |
| **NB Guard** | Contract validation | QA / Compliance |

```python
import neuralbridge as nb

# 1. Smart routing — cheap model for simple tasks
client = nb.Client(providers=["openai", "deepseek"], strategy="cost")
r = client.chat("Hello!", model="auto")  # → routes to gpt-4o-mini

# 2. Self-healing — provider fails, auto-switches
engine = nb.SelfHealingEngine(providers=["openai", "anthropic"])
r = engine.call_sync("Analyze this")  # OpenAI 500 → Anthropic ✓

# 3. Checkpoint — Agent crashes, resumes from last step
cp = nb.Checkpoint("research-agent")
papers = cp.step("search", lambda: client.chat("Search quantum computing").text)
analysis = cp.step("analyze", lambda: client.chat(f"Analyze: {papers}").text)
# Crashes here? Next run resumes from step 2, step 1 returns cached result
```

---

## Install

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

First `import` auto-runs a health check:

```
✅ NeuralBridge v4.2.2 installed
🔍 Quick health check...
   ✅ OpenAI: key valid (234ms)
   ✅ Anthropic: key valid (189ms)
   ⚠️  Only 2 providers — one outage = 50% capacity loss
```

---

## NB Router — Smart Routing + Cost Optimization

> **87% of enterprises waste API costs on over-powered models.** Simple tasks don't need GPT-4o.

```python
from neuralbridge import Client

client = nb.Client(
    providers=["openai", "anthropic", "deepseek"],
    strategy="cost",          # "cost" | "latency" | "quality"
)

# Auto: classify complexity → pick cheapest adequate model
r = client.chat("Hello!", model="auto")           # → gpt-4o-mini
r = client.chat("Analyze root cause of this bug", model="auto")  # → deepseek-chat
r = client.chat("Design a distributed system", model="auto")     # → gpt-4o

# Manual: specify model
r = client.chat("Complex task", model="gpt-4o")

# Cost tracking built-in
print(client.costs.summary())
# → total_calls: 150, total_cost: $2.31, savings: $8.70 (79%)
```

Three routing strategies:

| Strategy | Behavior | Best for |
|----------|----------|----------|
| `cost` | Cheapest model that can handle the task | Default — saves 50-80% |
| `latency` | Fastest provider + model | Real-time applications |
| `quality` | Best model regardless of cost | Critical tasks |

Complexity classification is **rule-based** (zero AI calls, sub-ms):
- **Simple** (greetings, translate, summarize) → mini tier (gpt-4o-mini, haiku)
- **Moderate** (write, extract, classify) → standard tier (gpt-4o, deepseek-chat)
- **Complex** (analyze, debug, architect) → premium tier (gpt-4o, claude-sonnet-4)

---

## NB Shield — Failover + Self-Healing

> **Production agents crash 17×/month, MTTR 28 min, $12K+ per incident.**

Every `call()` traverses a 4-level cascade:

```
L1: Smart Retry      → adjusted params, exponential backoff
L2: Model Downgrade  → GPT-4o → GPT-4o-mini (same provider)
L3: Provider Failover → OpenAI → Anthropic (cross-provider)
L4: Learned Recovery  → Flywheel rule from history (4x faster)
```

```python
from neuralbridge import SelfHealingEngine

engine = SelfHealingEngine(providers=["openai", "anthropic", "deepseek"])
result = engine.call_sync("Summarize this document")

print(result.text)            # response text
print(result.provider)        # which provider served it
print(result.heal_level)      # None | l1_retry | l2_downgrade | l3_failover | l4_learned
print(result.success)         # True / False
```

### Contract Validation (NB Guard)

Catch silent failures — the model returns a response but it's wrong:

```python
from neuralbridge import SelfHealingEngine, Contract

contract = Contract(
    output_schema={"required": ["name", "amount"]},
    required_entities=["USD"],
    forbidden_patterns=[r"I cannot", r"as an AI"],
)

result = engine.call_sync(
    "Extract: John paid $500 USD",
    task_type="extraction",
    contract=contract,
)
print(result.validation_passed)  # True or False
```

### Gateway Proxy (Any Language)

Drop-in OpenAI API replacement:

```bash
python -m neuralbridge.gateway --port 8080 --providers openai,anthropic
```

---

## NB Checkpoint — Agent Crash Recovery

> **Agent ran 10 steps and crashed. Without checkpoint: re-run all 10 steps (2× cost). With checkpoint: resume from step 10 (1 call).**

This is the feature **no other SDK provides**. LiteLLM, OpenRouter, Bifrost are all gateway-layer — they don't track Agent internal state. When an Agent crashes, its intermediate results are gone. Checkpoint fixes that.

### Step API (most flexible)

```python
from neuralbridge import Checkpoint

cp = Checkpoint("research-agent")

# Each step auto-saves. On crash, next run skips completed steps.
papers = cp.step("search", lambda: client.chat("Search quantum computing").text)
analysis = cp.step("analyze", lambda: client.chat(f"Analyze: {papers}").text)
report = cp.step("summarize", lambda: client.chat(f"Summarize: {analysis}").text)

# If crashes at step 3:
# - Next run: step 1+2 return cached results (zero API calls)
# - Step 3 re-executes normally
# - Total cost: 1 API call instead of 3
```

### Pipeline API (simplest)

```python
result = cp.pipeline([
    ("search",   lambda ctx: client.chat("Search quantum computing").text),
    ("analyze",  lambda ctx: client.chat(f"Analyze: {ctx['search']}").text),
    ("summarize", lambda ctx: client.chat(f"Summarize: {ctx['analyze']}").text),
])
```

### AgentSession (Checkpoint + Client in one)

```python
from neuralbridge import AgentSession

session = AgentSession(
    "research-agent",
    providers=["openai", "deepseek"],
    strategy="cost",
)

result = session.run([
    ("search",  "Search for the latest papers on quantum computing"),
    ("analyze", "Analyze the key findings"),
    ("report",  "Write a concise summary report"),
])
# Crashes at step 2? Next call auto-resumes from step 2.
```

### Checkpoint CLI

```bash
nb-doctor checkpoint list                    # List all checkpointed agents
nb-doctor checkpoint status <agent_id>       # Show checkpoint status
nb-doctor checkpoint reset <agent_id>        # Clear checkpoints
```

---

## Semantic Boundaries

Not everything should be auto-healed. NeuralBridge classifies every call into one of three domains:

| Domain | Behavior | Example |
|--------|----------|---------|
| **STRONG_EQUIVALENCE** | Contract validation required before accepting failover result | Data extraction, classification, JSON output |
| **TAU_NEIGHBORHOOD** | Validation optional | Summarization, translation |
| **OUT_OF_BOUNDS** | Self-healing **blocked** | Creative writing, brainstorming |

---

## Pricing

| Feature | Free | Pro (¥699/yr) |
|---------|------|---------------|
| Health check & connectivity | ✅ | ✅ |
| Fault diagnosis & classification | ✅ | ✅ |
| MAPE-K trace per call | ✅ | ✅ |
| Metrics & Prometheus format | ✅ | ✅ |
| L1 Smart Retry | 🔒 | ✅ |
| L2 Model Downgrade | 🔒 | ✅ |
| L3 Provider Failover | 🔒 | ✅ |
| L4 Flywheel Learning | 🔒 | ✅ |
| Contract Validation (5 strategies) | 🔒 | ✅ |
| Semantic Topology (3-domain) | 🔒 | ✅ |
| Smart Routing (cost/latency/quality) | ✅ | ✅ |
| Checkpoint (crash recovery) | ✅ | ✅ |
| Max providers | 1 | Unlimited |
| Watermark | Yes | No |

Free edition **detects and diagnoses** every fault. When it's time to **fix** it, upgrade to Pro.

```bash
nb-doctor status    # Check your plan
nb-doctor upgrade   # Upgrade to Pro
```

---

## CLI

```bash
nb-doctor scan              # Scan environment for API keys & connectivity
nb-doctor run               # Quick self-healing test
nb-doctor version           # Show version
nb-doctor status            # License status & plan info
nb-doctor upgrade           # Upgrade to Pro (opens browser)
nb-doctor auth <key>        # Activate license key
nb-doctor provider list     # List configured providers
nb-doctor provider status   # Show provider health & pricing
nb-doctor route <prompt>    # Test routing for a prompt
nb-doctor checkpoint list   # List all checkpointed agents
nb-doctor checkpoint status <agent_id>  # Show checkpoint details
nb-doctor checkpoint reset <agent_id>   # Clear agent checkpoints
```

---

## API Reference

### Client (NB Router)

```python
client = nb.Client(
    providers=["openai", "anthropic", "deepseek"],
    strategy="cost",           # "cost" | "latency" | "quality"
    api_keys={"openai": "..."}, # optional, auto-detected from env
    license_key="...",          # optional
)

response = client.chat(
    "Your prompt",
    model="auto",              # "auto" for smart routing, or specific model
    task_type="extraction",    # optional hint
    strategy="latency",        # override strategy per-call
)

response.text          # response text
response.provider      # "openai"
response.model         # "gpt-4o-mini"
response.complexity    # Complexity.SIMPLE
response.routing       # RoutingDecision object
response.success       # True / False
response.heal_level    # None | "l1_retry" | ...

client.costs.summary()  # cost report
client.status()         # routing + cost + health info
```

### Checkpoint (NB Checkpoint)

```python
cp = nb.Checkpoint(
    "agent-id",
    store=nb.FileCheckpointStore(),  # default: ~/.neuralbridge/checkpoints/
    auto_persist=True,
)

# Step-by-step
result = cp.step("step_name", lambda: your_function())

# Pipeline
result = cp.pipeline([
    ("step1", lambda ctx: fn1()),
    ("step2", lambda ctx: fn2(ctx["step1"])),
])

# Manual checkpoint
cp.mark_step("step_name", value="result")

# Status & recovery
cp.status()        # step counts, cost, per-step details
cp.resume_info()   # where to resume after crash
cp.history()       # execution history
cp.reset()         # clear all checkpoints
```

### AgentSession (Checkpoint + Client)

```python
session = nb.AgentSession(
    "agent-id",
    providers=["openai", "deepseek"],
    strategy="cost",
)

result = session.run([
    ("search",  "Search for papers on quantum computing"),
    ("analyze", "Analyze the findings"),
    ("report",  "Write a summary"),
])

session.status()     # checkpoint + client status
session.resume_info() # crash recovery info
session.reset()       # clear checkpoints
```

### SelfHealingEngine (NB Shield)

```python
engine = nb.SelfHealingEngine(providers=["openai", "anthropic", "deepseek"])

# Sync
result = engine.call_sync(
    "Your prompt",
    model="gpt-4o",
    task_type="classification",
    contract=Contract(...),
)

# Async
result = await engine.call("Your prompt", task_type="extraction", has_schema=True)

# Health
engine.health_check()              # {"openai": "healthy", ...}
engine.get_available_providers()   # ["openai", "anthropic"]
engine.get_stats()                 # call_count, heal_count, heal_rate
```

### Contract (NB Guard)

```python
contract = nb.Contract(
    output_schema={"required": ["name"]},
    determinism_hash="abc123",
    similarity_threshold=0.8,
    reference_text="expected output",
    required_entities=["Python"],
    forbidden_patterns=[r"I cannot"],
)
```

5 strategies: Schema, Determinism, Similarity, Entities, Forbidden.

### HA Components

```python
from neuralbridge import CircuitBreaker, RateLimiter, Bulkhead

cb = CircuitBreaker(failure_threshold=5, cooldown_seconds=30)
rl = RateLimiter(max_tokens=10, refill_rate=1.0)
bh = Bulkhead(max_concurrent=5)
```

---

## Supported Providers

| Provider | Models | Env Key |
|----------|--------|---------|
| OpenAI | gpt-4o, gpt-4o-mini, gpt-3.5-turbo | `OPENAI_API_KEY` |
| Anthropic | claude-sonnet-4, claude-3-5-haiku | `ANTHROPIC_API_KEY` |
| DeepSeek | deepseek-chat, deepseek-reasoner | `DEEPSEEK_API_KEY` |
| Google | gemini-2.0-flash, gemini-1.5-pro | `GOOGLE_API_KEY` |
| DashScope | qwen-max, qwen-plus, qwen-turbo | `DASHSCOPE_API_KEY` |
| Azure | gpt-4o, gpt-4o-mini | `AZURE_OPENAI_API_KEY` |
| NVIDIA | llama-3.1-8b/70b | `NVIDIA_API_KEY` |
| Groq | llama-3.1, mixtral | `GROQ_API_KEY` |
| Custom | Any OpenAI-compatible API | — |

---

## Why Not LiteLLM / OpenRouter?

| | NeuralBridge | LiteLLM | OpenRouter |
|---|---|---|---|
| Architecture | **Embedded** in-process | Proxy server | Proxy server |
| Latency overhead | Zero | Extra hop | Extra hop |
| Self-healing cascade | L1→L2→L3→L4 | Fallback only | Fallback only |
| Smart routing | Complexity-based + cost/latency/quality | Model list | Model list |
| **Agent crash recovery** | **✅ Checkpoint** | ❌ | ❌ |
| Contract validation | 5 strategies | No | No |
| Cost tracking | Built-in | Partial | Partial |
| Flywheel learning | Learns from history | No | No |
| Dependencies | 1 (httpx) | Many | API-based |
| Setup | `pip install` + import | Proxy deployment | API key |

**Key differentiator**: Checkpoint. No other SDK tracks Agent state. When your Agent crashes, everyone else makes you start from scratch. NeuralBridge resumes from the last completed step.

---

## For Agent Platforms

Building an Agent platform? Embed NeuralBridge as your default stability layer:

- **In-process**: no proxy latency, no extra infrastructure
- **Crash recovery**: agents resume from checkpoint, not from zero
- **Cost-aware**: simple tasks → cheap models automatically
- **Zero dependency**: only httpx, runs anywhere
- **Volume pricing**: per-call, not per-seat

→ **wangguigui@neuralbridge.cn**

---

## License

Apache License 2.0. "NeuralBridge" is a trademark of NeuralBridge Team.

Patent Pending: MAPE-K 5-Phase Adaptive Loop · Semantic Topology Three-Domain · Contract Validator · FlywheelLearner with TTL Decay
