Metadata-Version: 2.1
Name: neuralbridge-sdk
Version: 5.1.2
Summary: NeuralBridge SDK - Embedded LLM self-healing engine. AI自愈引擎，LLM容错SDK，自动故障切换，多Provider路由。1 dependency, 762KB.
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/hhhfs9s7y9-code/neuralbridge-sdk
Project-URL: Documentation, https://neuralbridge.dev/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,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
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: cython>=3.0; extra == "dev"


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

---

# NeuralBridge SDK

一个 **762KB** 的嵌入式 LLM 调用容错 SDK。

不是网关，不是代理，不需要 Docker，不需要 K8s。  
装完就能用，故障自动切换。

---

## 一句话定位

个人开发者、早期原型、内部工具——不想搭网关，但想要基础自愈能力。

**不是给大型企业的。** 如果你需要全局流量管控、审计日志、等保合规，去看 [Higress](https://higress.io/) 或 [OneAPI](https://github.com/songquanpeng/one-api)。

---

## 安装

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

依赖只有一个：`httpx`。

---

## 快速开始

```python
import neuralbridge as nb

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

---

## 能做什么（实测验证）

| 能力 | 说明 | 延迟 |
|------|------|------|
| HTTP 故障切换 | 超时、连接错误、5xx 自动重试 | < 1ms |
| 协议层修复 | JSON 破损、SSE 截断、空内容识别 | ~45µs |
| 模型异常映射 | 20+ 模型错误码（DeepSeek、OpenAI、Claude 等） | 本地规则 |
| 兜底话术拦截 | "我无法回答"、"作为 AI 助手" 等空回复标记 | 正则匹配 |

### 不能做什么

- ❌ 事实性幻觉检测（需要外部知识库）
- ❌ 深度内容安全审核（需要分类模型）
- ❌ 事实性幻觉检测（需要外部知识库）
- ❌ 深度内容安全审核（需要分类模型）
- ❌ 全局流量管控（无中心节点，各进程独立决策）
- ❌ 多节点状态同步（进程 A 熔断的模型，进程 B 不知道，直到自己触发故障）

> ⚠️ **多节点架构说明：** 各进程独立决策，无全局协调。这是"无单点瓶颈"的必然代价。
> 如果你需要全局流量管控，配合 Higress 等独立网关使用。

---

## 架构与透明度

```
┌─────────────────┐
│   你的应用进程   │
│  ┌───────────┐  │
│  │  Python   │  │  ← 开源：调用接口、配置解析
│  │   接口层   │  │
│  ├───────────┤  │
│  │  Cython   │  │  ← 预编译：自愈引擎、规则匹配
│  │   引擎层   │  │     （闭源，但异常模式库可审计）
│  └───────────┘  │
└─────────────────┘
```

**为什么核心闭源：** 商业策略，防止直接复制。

**能审计什么：** `neuralbridge/rules/` 目录下的异常模式 JSON（20+ 模型错误码映射）。

---

## 实测数据（第三方）

来自独立开发者实测：

| 指标 | 数值 |
|------|------|
| 包体积 | 762KB（含 Cython 二进制） |
| 诊断延迟 | 44.9 µs（文档宣称 19-70 µs） |
| 安装 | 一条命令，零配置 |

---

## 适用场景

| 适合 | 不适合 |
|------|--------|
| 个人项目、黑客松 | 大型企业生产环境 |
| 早期原型验证 | 需要等保/信创审计 |
| 内部工具、Bot | 多业务线统一管控 |
| 不想运维网关的小团队 | 需要全局状态共享 |

---

## 为什么不选 LiteLLM

| | NeuralBridge | LiteLLM |
|--|-------------|---------|
| 体积 | 762KB | ~16MB |
| 依赖 | 1个 | 多个 |
| 自愈 | 协议层+浅层内容 | HTTP 重试 |
| 模型覆盖 | 主流模型 | 100+ |
| 部署 | SDK 嵌入 | SDK / 代理 / 网关 |
| 供应链风险 | 低（依赖少） | 2026.3 投毒事件 |

**不是替代关系。** 需要 100+ 模型、多语言 SDK、代理模式 → 用 LiteLLM。  
只需要轻量容错、嵌入进程、快速上线 → 用 NeuralBridge SDK。

---

## 现状与风险（诚实说）

- **GitHub：** 5 Star，0 Issue（刚起步，社区冷清）
- **客户案例：** 无知名企业公开背书
- **数据验证：** 核心指标来自自述 + 个别第三方实测

**建议：** 个人项目放心用，生产环境先观察。

---

## 路线图

- [ ] 纯 Python 降级模式（审计友好）
- [ ] 异常模式库完全开源（社区共建）
- [ ] 第一个公开客户案例
- [ ] 50+ GitHub Star（社区活跃门槛）

---

## 安装

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

文档：https://github.com/hhhfs9s7y9-code/neuralbridge-sdk

---

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