Metadata-Version: 2.1
Name: neuralbridge-sdk
Version: 5.6.0
Summary: NeuralBridge - AI Agent 自愈引擎。三层故障自愈：L1 自动重试 → L2 语义等价降级 → L3 Failover 兜底。内置本地监控面板，依赖 httpx + aiohttp，pip install 即可接入。
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/neuralbridge-sdk/neuralbridge-sdk
Project-URL: Documentation, https://neuralbridge.dev/docs
Project-URL: Bug Tracker, https://github.com/neuralbridge-sdk/neuralbridge-sdk/issues
Project-URL: Changelog, https://github.com/neuralbridge-sdk/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,AI自愈,LLM容错,大模型容错,AI Agent,故障切换
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
Requires-Dist: aiohttp >=3.8.0
Provides-Extra: all
Requires-Dist: httpx >=0.24.0 ; extra == 'all'
Requires-Dist: aiohttp >=3.8.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'
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: redis
Requires-Dist: redis ; extra == 'redis'

# NeuralBridge SDK — AI Agent 自愈引擎

[![PyPI version](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/)
[![Downloads](https://img.shields.io/pypi/dm/neuralbridge-sdk)](https://pypi.org/project/neuralbridge-sdk/)
[![License](https://img.shields.io/pypi/l/neuralbridge-sdk)](LICENSE)

**开发者优先的 AI API 平台。SDK 嵌入你的进程，控制台观测一切。**
**不是 Gateway，不需要 Docker，一行 `pip install` 获得生产级容错。**

```
pip install neuralbridge-sdk
```

- **SDK-first** — 核心价值在代码里，不在网页上。`pip install` 直接进入你的 Python 进程。
- **嵌入式** — 进程内运行，零外部依赖，不是外部 Gateway 服务。
- **控制台观测层** — 实时延迟监控、Provider 健康、自愈记录、成本分析，全部在 [neuralbridge.cn](https://neuralbridge.cn) 控制台。
- **混合计费** — 免费体验 + 按量计费（¥0.1/次起）+ 月付订阅（¥99/¥199/¥699），灵活匹配使用规模。

## 🚀 一行代码接入自愈引擎

```python
import neuralbridge as nb
import asyncio

engine = nb.SelfHealingEngine()
engine.add_provider(nb.ProviderConfig(
    name="deepseek",
    base_url="https://api.deepseek.com/v1",
    api_key="sk-your-key",
    models=["deepseek-v4-flash"],
))

result = asyncio.run(engine.call("你好，请用一句话介绍自己"))
print(result.text)
# Output: 你好！我是 NeuralBridge 自愈引擎...
```

## 🔥 核心能力

| 能力 | 说明 | 竞品对比 |
|------|------|----------|
| **🩺 自愈恢复** | API 故障自动切换备用 Provider | LiteLLM 只转发不恢复 |
| **✅ 输出验证** | Contract 机制确保恢复结果有效 | LangSmith 只看不验证 |
| **📌 断点续跑** | Agent 中途崩溃可从中断处恢复 | L1-L4 级联恢复 |
| **🛡️ 国内支持** | 原生支持 DeepSeek/阿里云/月之暗面 | LangSmith 需翻墙 |
| **💰 BYOK** | 客户用自己的 API Key，不走中转 | 省钱又安全 |
| **📊 监控面板** | 实时延迟/Provider 健康/自愈记录/成本 | — |
| **♻️ 智能路由** | 成本/延迟/质量多策略路由 | — |
| **🌱 碳追踪** | LLM 调用碳排放统计 | — |

## 📦 安装

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

支持 Python 3.8+。包体积 ~1MB，仅 1 个运行时依赖（httpx）。

## 🎯 为什么选择 NeuralBridge？

### vs LiteLLM
LiteLLM 是 API 网关——它转发请求，如果挂了就报错。NeuralBridge 是 SDK 内建的自愈引擎——如果 A 挂了，自动切换到 B，**并验证 B 的输出是否有效**。

### vs LangSmith / Langfuse
它们是观测平台——告诉你系统出了问题。NeuralBridge 是修复平台——**发现问题后自动修复**。自带 Web 控制台用于观测和管理。

### vs 自研容灾
你需要投入团队维护。NeuralBridge 是开箱即用的一行代码。

## 🏗️ 架构

```
用户请求 → SelfHealingEngine → Monitor(监控)
                                   ↓
                              Analyze(诊断) 
                                   ↓
                              Plan(计划恢复)
                                   ↓
                              Execute(执行切换)
                                   ↓
                              Knowledge(学习优化)
                                   ↓
                              Contract Validation(输出验证)
                                   ↓
                             ✅ 有效结果
```

SDK 运行在你的进程内，控制台通过 [neuralbridge.cn](https://neuralbridge.cn) 访问，实时展示：

| 观测维度 | 内容 |
|----------|------|
| 📈 API 延迟实时波形 | 60 秒滚动，基线/阈值线，P50/P95/P99 |
| 🏥 Provider 健康 | 8 个 Provider 在线/降级/离线实时状态 |
| 🔔 异常事件推送 | Provider 离线、降级、恢复实时通知 |
| 🛡️ 自愈记录 | L1-L4 各层级触发次数、耗时、节省成本 |
| 💰 用量 & 成本 | 实时调用量、费用、余额 |

## 🧪 更多示例

### BYOK 模式（自备 Key）

```bash
nb-doctor setup --provider deepseek --key sk-your-key
```

### Contract 输出验证

```python
contract = nb.Contract(
    required_entities=["def ", "return"],
)
result = asyncio.run(engine.call(
    "写一个 Python 函数",
    model="deepseek-v4-pro",
    contract=contract,
))
# 输出不符合合约时自动重试
```

### OpenAI 兼容代理模式

```python
import neuralbridge as nb

server = nb.serve(
    host="127.0.0.1", port=8080,
    providers=["deepseek"],
    api_keys={"deepseek": "sk-your-key"},
)
server.serve_forever()
# Codex/任何 OpenAI 客户端可接入：
# base_url=http://localhost:8080/v1
```

## 💳 定价

| 方案 | 价格 | 适用场景 |
|------|------|----------|
| 🎁 免费体验 | ¥0 | 12 项 API 安全检查、基础诊断、报告生成 |
| 💰 按量计费 | ¥0.1/次起 | 余额永久有效，按调用量扣费 |
| 👤 个人版 | ¥99/月 | 个人开发者，每月 10 万次调用 |
| 🚀 专业版 | ¥199/月 | 小团队，每月 50 万次调用 |
| 🔬 深度版 | ¥699/月 | 企业级，每月 500 万次调用 |
| 🏢 企业定制 | 另议 | 私有部署、SLA、专属支持 |

> 在线购买/充值: [neuralbridge.cn/buy](https://neuralbridge.cn/buy)

## 🗺️ 路线图

- [x] 智能路由与自愈
- [x] Contract 输出验证
- [x] Checkpoint 断点续跑
- [x] BYOK 自备 Key 模式
- [x] Web 控制台（实时监控/自愈记录/成本分析）
- [x] 按量计费 & 订阅支付
- [ ] Windows .pyd 原生支持
- [ ] 企业版私有化部署
- [ ] 中文文档站

## 📄 许可证

Apache 2.0

## 🤝 联系

- 官网: https://neuralbridge.cn
- 控制台: https://neuralbridge.cn/console.html
- 购买/充值: https://neuralbridge.cn/buy.html
- 邮件: wangguigui@neuralbridge.cn

## Real-World Performance (from Flywheel Logs)

| Metric | Data |
|---|---|
| Self-Heal Rate | **84.1%** |
| Successful Recoveries | **5,085** |
| Failed | 964 |
| Learned Rules | **84** |
| Health Check Overhead | 0.0025ms |
| Package Size | 357KB |
| Dependencies | 1 (httpx) |

> ⚠️ 以上数据来自内部 Flywheel 日志统计，基于特定测试环境和故障场景。实际表现可能因网络、Provider 状态和配置不同而有差异。

### vs The Competition

| Capability | NeuralBridge | LiteLLM | LangSmith | Langfuse | AgentRx |
|---|---|---|---|---|---|
| Self-Healing | **L1-L4 cascading** | Fallback only | Read-only | Read-only | Diagnosis only |
| Output Validation | **Contract** | — | — | — | Academic |
| Checkpoint/Resume | **✅** | — | — | — | — |
| **三合一** (自愈+验证+续跑) | **✅** | — | — | — | — |
| Web Console (Observability) | **✅** | ✅ | ✅ | ✅ | — |
| **自愈可视化** (Failover 时间线) | **✅ 独家** | — | — | — | — |

> Three months. One person. One dependency. One line of code.
> `pip install neuralbridge-sdk`
