Metadata-Version: 2.1
Name: neuralbridge-sdk
Version: 5.2.11
Summary: NeuralBridge - 生成级API稳定器。三层综合保护：大模型容错·Agent自愈·网关MCP守护。不漏数据、不崩服务、不被攻击。一行命令装完，微秒级诊断，零外部依赖。
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: 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: 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"


<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/neuralbridge-sdk/neuralbridge-sdk/main/assets/logo-dark.svg">
    <img alt="NeuralBridge" src="https://raw.githubusercontent.com/neuralbridge-sdk/neuralbridge-sdk/main/assets/logo-light.svg" width="480">
  </picture>
</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/neuralbridge-sdk/neuralbridge-sdk"><img src="https://img.shields.io/github/stars/neuralbridge-sdk/neuralbridge-sdk?style=flat" alt="GitHub stars"></a>
</p>

---

**⚠️ 品牌声明**：PyPI 上的 `neuralbridge-sdk` 是本项目。注意与以下同名项目无关：
[iceccarelli/neuralbridge](https://github.com/iceccarelli/neuralbridge) (FastAPI 中间件)、
[dondetir/neuralbridge_mcp](https://github.com/dondetir/neuralbridge_mcp) (Android MCP)、
`neuralbridge.ru` (俄罗斯 API 聚合)。

---

# NeuralBridge — 生成级 API 稳定器

**三层综合保护：大模型容错 · Agent 自愈 · 网关 MCP 守护**
让你的 AI 应用在生产环境里不漏数据、不崩服务、不被攻击。

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

一行命令装完 · 微秒级诊断 · 零外部依赖（仅 httpx）

不是网关，不是代理，不需要 Docker。直接嵌入你的 Python 进程。

---

## 快速开始

```python
import neuralbridge as nb

# 自动从环境变量读取 API Key（DEEPSEEK_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY）
result = nb.chat("用一句话解释量子计算")
print(result.text)
print(f"提供商: {result.provider}")
print(f"是否自愈: {result.recovered}")
```

---

## 🎯 装了 NeuralBridge 和不装的区别

| 场景 | 没装 NeuralBridge | 装了 NeuralBridge |
|------|------------------|------------------|
| **API 429 Rate Limit** | 程序崩溃 / 任务失败 | 自动切换 Provider，任务继续 |
| **500 服务器错误** | 请求超时、用户报错 | L1 重试 → L2 降级 → L3 Failover |
| **API Key 失效** | 全线瘫痪，手动换 Key | 自动降级到可用 Provider |
| **模型输出 JSON 破损** | 解析异常、程序中断 | 自动修复 + 合约验证 |
| **Agent 进程崩溃** | 从头重跑，丢失中间结果 | Checkpoint 断点续跑 |
| **排查故障** | 翻日志、手动重试 | `nb.simulate_crash()` 一键演练 |
| **运维压力** | 彻夜监控、随时响应 | 喝杯咖啡，一切自动 |

```bash
# 30 秒体验区别
pip install neuralbridge-sdk
python -c "import neuralbridge as nb; nb.simulate_crash()"
```

---

## 与 LiteLLM 对比

| 维度 | NeuralBridge SDK | LiteLLM |
|------|-----------------|---------|
| 部署模式 | **嵌入式**（pip install，自带进程内） | **Gateway**（需部署 Docker 服务） |
| 包体积 | ~1.5 MB（_core.pyd 418 KB + Python 源码） | ~16 MB |
| 运行时依赖 | **2 个**（httpx + aiohttp） | 21–85 个依赖 |
| 故障恢复 | **三层自愈**：LLM 级 + MCP 级 + Agent 级 | 单层 HTTP retry |
| 故障诊断 * | ~22 µs P50（进程内诊断，无网络开销） | ~ms 级（Gateway 远程调用） |
| 集中治理 | ❌ 不支持（设计上无中心节点） | ✅ Gateway 模式天然支持 |
| 团队协作 | ❌ 不支持统一计费/管控 | ✅ 多用户共享 API Key |

> *诊断延迟为 SDK 内置 benchmark 实测值（`python -m pytest tests/test_benchmark.py -v`），测试环境：Windows Python 3.12，源码模式。编译后延迟更低。
>
> **选择建议**：需要集中管控 → LiteLLM Gateway；追求低延迟、高容错、零运维 → NeuralBridge SDK

---

## 性能数据（可复现）

以下数据来自 SDK 内置基准测试，可在任意环境复现：

| 指标 | 实测值 | 测试条件 |
|------|--------|----------|
| 故障诊断 P50 | **22 µs** | 1000 次调用（Windows .py） |
| 故障诊断 P99 | **47 µs** | 1000 次调用 |
| 熔断器检查 | **0.4 µs** | 1000 次调用 |
| 遥测吞吐 | **177,582 rec/s** | 1000 条记录 |
| 引擎内存（10 routes） | **0.06 MB** | tracemalloc |
| 并发诊断 | **10,000 次/秒** | 100 线程 × 100 次 |
| 运行时依赖 | **1 个**（httpx） | pip list 验证 |

> 测试命令：`python -m pytest tests/test_benchmark.py tests/test_stress.py -v -s`

### 测试通过率

| 测试套件 | 通过/总数 | 说明 |
|---------|-----------|------|
| 引擎核心 | 22 / 22 | 含 telemetry、MAPE-K、熔断器 |
| Client / Router / Checkpoint | 66 / 66 | 含 1,000+ 并发测试 |
| Async API | 9 / 9 | sync + async 全覆盖 |
| Monkeypatch | 13 / 13 | 零代码集成 openai SDK |
| Error Scenarios | 7 / 7 | 边界条件覆盖 |
| v250 兼容 | 25 / 25 | openai v1.0~v1.55 兼容 |
| **合计（pytest）** | **146 / 148** | 2 errors 为 pytest 收集冲突（自定义测试框架） |
| 功能验证（独立） | 11 / 11 | `python tests/test_features.py` — License/设备指纹/Stats |
| 源码级验证（独立） | 13 / 13 | `python tests/test_monkeypatch.py` — monkeypatch 全覆盖 |

> 实测于 2026-06-15，Python 3.12.8 Windows x64。  
> 测试命令: `python -m pytest tests/ --ignore=tests/test_runner.py --ignore=tests/test_benchmark.py --ignore=tests/test_stress.py`  
> 自定义测试: `python tests/test_features.py && python tests/test_monkeypatch.py`  
> **所有测试内容全部通过，0 失败。** 2 个 pytest 收集报错源自自定义 `@test` 装饰器（非 pytest fixture），不影响测试结果。

---

## 核心能力

| 能力 | 说明 |
|------|------|
| **HTTP 故障切换** | 超时、连接错误、5xx 自动重试/降级/切换 |
| **协议层修复** | JSON 破损、SSE 截断、空内容识别（~47 µs） |
| **模型异常映射** | 20+ 模型错误码分类（429/401/500/408…） |
| **Checkpoint 断点续跑** | Agent 崩溃后从断点恢复，跳过已完成步骤 |
| **异步原生** | `nb.chat_async()` 顶层 API |
| **并发安全** | 100 线程 × 100 次诊断无竞争 |

### 明确不做

- ❌ 事实性幻觉检测（需要外部知识库）
- ❌ 全局流量管控（无中心节点）
- ❌ 多节点状态同步（进程独立自愈决策）

---

## 架构

<p align="center">
  <img src="assets/architecture.svg" alt="NeuralBridge 三层综合保护架构" width="100%">
</p>

---

## 项目状态

| 指标 | 数据 |
|------|------|
| 版本 | v5.2.11 |
| PyPI 下载 | 有机增长中（[查看](https://pypi.org/project/neuralbridge-sdk/#data)） |
| GitHub Stars | 4（萌芽期，[欢迎 ⭐](https://github.com/neuralbridge-sdk/neuralbridge-sdk)） |
| 公开客户案例 | 暂无知名企业背书（我们在努力） |
| 生产建议 | 个人项目可以放心用；生产环境建议先 PoC 验证 |
| License | Apache 2.0（Python 接口层）+ 商业授权（引擎二进制） |

---

## 定价

| 计划 | 价格 | 适用场景 |
|------|------|----------|
| Trial | ¥0（7 天全功能） | 试用评估 |
| Pro | ¥699/年 | 个人开发者、小团队 |
| Professional | ¥3,999/年 | 企业项目 |
| Enterprise | 定制 | 大规模部署、私有部署 |

详见 [docs/sla-pricing.md](docs/sla-pricing.md)

---

<p align="center">
  <code>pip install neuralbridge-sdk</code><br>
  Apache 2.0 Licensed · Commercial Engine
</p>
