Metadata-Version: 2.4
Name: neuralbridge-sdk
Version: 1.6.2
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)

**AI Agent Runtime Operations Platform — Diagnose. Self-Heal. Survive.**

## Why NeuralBridge?

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

NeuralBridge detects failures and self-heals automatically — no code changes needed.

## Quick Start

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

```python
from neuralbridge import SelfHealingEngine, Diagnoser

# Diagnose
diagnoser = Diagnoser()
report = diagnoser.diagnose(target=my_agent)
print(report.summary)

# Self-heal
engine = SelfHealingEngine(providers=["openai", "anthropic"])
response = engine.call("Analyze this PR", model="gpt-4o")
```

## Quick Setup (Auto-configure from environment)

```python
from neuralbridge import auto_setup

# Scans OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.
engine = auto_setup()
response = engine.call("Hello", model="gpt-4o")
```

## Features

### Self-Healing Engine

Automatically recovers from API failures, rate limits, timeouts, and model substitutions.

```python
from neuralbridge import SelfHealingEngine

engine = SelfHealingEngine(
    providers=["openai", "anthropic", "google"],
    max_retries=3,
)
response = engine.call("Summarize this", model="gpt-4o")
```

### Smart Router

Route requests across multiple providers with configurable strategies.

```python
from neuralbridge import SmartRouter
from neuralbridge.types import RoutingStrategy

router = SmartRouter(strategy=RoutingStrategy.FAILOVER_ONLY)
```

### Health Scorer

Track provider health scores in real time.

```python
from neuralbridge import HealthScorer

scorer = HealthScorer()
scorer.record("openai", success=True, latency_ms=150)
score = scorer.get_score("openai")
```

### Cost Tracker

Monitor and limit API spending.

```python
from neuralbridge import CostTracker

tracker = CostTracker(daily_budget=50.0, monthly_budget=1000.0)
tracker.record("openai", tokens=1000, cost_usd=0.03)
print(tracker.get_daily_cost("openai"))
```

### Diagnoser

Free CLI diagnostic tool for LLM API issues.

```bash
nb-doctor scan                      # Scan codebase for risks
nb-doctor diagnose --api-key KEY --base-url URL --model MODEL  # Diagnose a specific API
nb-doctor check --api-key KEY --base-url URL   # Quick connectivity check
```

## Supported Providers

| Provider | Adapter |
|----------|---------|
| OpenAI (GPT-4, GPT-3.5-turbo) | `OpenAIAdapter` |
| Anthropic (Claude) | `AnthropicAdapter` |
| Google (Gemini) | `GoogleAdapter` |
| Groq | `GroqAdapter` |
| DashScope (通义千问) | `DashScopeAdapter` |
| OpenRouter | `OpenRouterAdapter` |

## Architecture

```
┌─────────────────────────────────────────┐
│            Your AI Agent                │
├─────────────────────────────────────────┤
│  NeuralBridge SDK                       │
│  ┌──────────┐ ┌──────────┐ ┌────────┐  │
│  │Diagnoser │ │SelfHealer│ │Health  │  │
│  │          │ │          │ │Scorer  │  │
│  └────┬─────┘ └────┬─────┘ └───┬────┘  │
│       └─────────────┼───────────┘       │
│               ┌─────┴─────┐             │
│               │CostTracker│             │
│               └───────────┘             │
├─────────────────────────────────────────┤
│        LLM APIs (OpenAI, Anthropic...)  │
└─────────────────────────────────────────┘
```

## Requirements

- Python >= 3.8
- Dependencies: httpx, requests

## Links

- 🌐 Website: [neuralbridge.cn](https://www.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
