核心特性
V2 错误码与能力 Extras
13 个 V2 标准错误码，统一错误处理。基于能力的 extras：8 个可选包，外加 full 完整安装。
异步优先设计
全程原生 async/await。基于 httpx 的传输与连接池。 CancellableStream 支持优雅终止流。
Pydantic v2 类型
完整类型注解与 Pydantic v2 校验。ProtocolManifest、Message、 ContentBlock、StreamingEvent 均类型安全并带运行时验证。
韧性执行器
ResilientExecutor 组合背压、限流、熔断与指数退避重试。 PreflightChecker 在执行前门控请求。
模型路由
ModelManager + ModelArray 实现智能选型。策略含轮询、加权、成本优先与质量优先。
生产级遥测
MetricsCollector 支持 Prometheus 导出。OpenTelemetry 分布式追踪。 结构化日志、健康监控与用户反馈采集。
结构化输出
JSON 模式配置、由 Pydantic 模型生成 schema、输出校验。 Guardrails 提供内容过滤与 PII 检测。
符合 Python 习惯、直观易用
干净、符合 Python 习惯的 API。用模型标识创建客户端， 以流畅 Builder 构造请求，并迭代统一的流式事件。
同一套代码适用于所有服务商。从 OpenAI 切换到 Anthropic 再到 DeepSeek by changing one string —the protocol manifest handles the rest.
from ai_lib_python import AiClient
# Works with ANY provider
client = await AiClient.create(
"anthropic/claude-3-5-sonnet"
)
# Streaming chat
async for event in client.chat() \
.user("Explain AI-Protocol") \
.temperature(0.7) \
.max_tokens(1000) \
.stream():
if event.is_content_delta:
print(event.as_content_delta.text,
end="")
# Non-streaming with stats
response, stats = await client.chat() \
.user("Summarize this") \
.execute_with_stats()
print(f"Tokens: {stats.total_tokens}")
print(f"Latency: {stats.latency_ms}ms")内部架构
与 Rust 运行时相同的分层架构——协议驱动、基于算子，韧性按需启用。
模块概览
client/ + errors/standard_codes/
AiClient, AiClientBuilder, ChatRequestBuilder, ChatResponse, CallStats, CancelToken, CancellableStream.
protocol/
ProtocolLoader（本地 / 环境变量 / GitHub）、Pydantic 清单模型、JSON Schema 校验器、 热重载支持。
pipeline/
Decoder（SSE、JSON Lines、Anthropic SSE）、Selector（JSONPath）、Accumulator、FanOut、 EventMapper（协议驱动 / 默认 / Anthropic）。
resilience/
ResilientExecutor, RetryPolicy, RateLimiter, CircuitBreaker, Backpressure, FallbackChain, SignalsSnapshot, PreflightChecker.
routing/
ModelManager、ModelArray 与选型策略（轮询、加权、成本、质量）。 主流服务商预置目录。
telemetry/
MetricsCollector（Prometheus）、Tracer（OpenTelemetry）、结构化 Logger、 HealthChecker、用户反馈采集。
embeddings/ + tokens/
EmbeddingClient 提供向量运算。TokenCounter（tiktoken 集成）与用量成本估算。
plugins/ + structured/
Plugin 基类、PluginRegistry、HookManager 与中间件链。JSON 模式配置、 SchemaGenerator、OutputValidator。