官方 Python SDK 使用指南 (typesafe-sdk)

解决的核心问题与技术概览

typesafe-sdk 是 TypeSafe AI 的官方 Python 语言工具包。它原生提供同步 TypeSafeClient 与异步 AsyncTypeSafeClient 两种调用方式，内置连接池复用、退避重试策略以及与 Pydantic 结合的严格数据模型契约，用于在 Python 生态中接入 Jev 决策能力。

适用与不适用场景

适用场景

FastAPI、Django 或 Celery 等 Python 后端微服务，需在几十毫秒内完成意图判决与风控分流。
高并发异步场景，需在一次请求中对多个推测性分支进行并发评估。
在复杂 Agent 工作流中作为确定性前置门禁，拦截非法或低置信请求。

不适用场景

需要连续多轮会话交互、开放式文章摘要或创意文本润色的场景。
无网络连接且未配置本地模拟适配器的隔离内网。

安装引入与前置要求

pip install typesafe-sdk
# 或使用 uv
uv add typesafe-sdk

离线契约验证与示例代码

验证说明： 以下示例展示了在无网络凭据情况下的本地结构与输入契约校验。线上生产环境调用依赖网络连通与有效 API 密钥。

from dataclasses import dataclass
from typing import List

# 本地离线契约验证演示（静态断言，无网络请求）
@dataclass
class OfflineRoutingContract:
    user_tier: str
    risk_score: float
    options: List[str]

def validate_offline_contract(contract: OfflineRoutingContract) -> bool:
    assert contract.user_tier in ['free', 'pro', 'enterprise']
    assert 0.0 <= contract.risk_score <= 1.0
    return True

contract = OfflineRoutingContract(user_tier='enterprise', risk_score=0.15, options=['pass', 'review'])
print('Python 离线契约验证通过:', validate_offline_contract(contract))

运行依赖与已知边界限制

前置条件

Python 3.10 或更高版本。
系统中配置有效的 TYPESAFE_API_KEY 环境变量。

已知限制

真实环境执行必须连接官方云端 API。
SDK 本身不包含本地神经网络权重，本地运行仅为接口调用驱动。

官方资料来源与溯源

本页所有技术特性与原语签名均核对自以下官方公开资料：