Jev Python SDK 完整教程

1. 安装与鉴权

API Key 应仅保存在服务端。SDK 会读取 TYPESAFE_API_KEY 环境变量，无需把密钥写进应用代码。

python -m pip install typesafe-sdk
export TYPESAFE_API_KEY="your-api-key"

2. 发起类型化决策

state 提供需要判断的事实，questions 定义期望返回的封闭决策。下面的示例同时完成工单路由与紧急程度判断。

from typesafe_sdk import Choice, Noul, TypeSafeClient

with TypeSafeClient() as client:
    response = client.system_one(
        state={"message": "Stripe has failed for 3 days."},
        questions={
            "department": Choice(
                instructions="Which team should handle this?",
                criteria={
                    "billing": "Payments or subscriptions",
                    "technical": "Bugs or integrations",
                    "sales": "Pricing or account questions",
                },
            ),
            "is_urgent": Noul(
                instructions="Does the message convey urgency?"
            ),
        },
    )

3. 安全读取答案

Choice 返回胜出标签、完整概率分布与置信度；Noul 返回命题为真的概率。应把结果当成决策数据，而不是生成文本。

department = response.answers["department"]
print(department.choice)
print(department.probabilities)
print(department.confidence)

urgent = response.answers["is_urgent"]
print(urgent.noul)  # P(true)

4. 上线检查清单

记录模型版本，保持问题 ID 稳定，在触发副作用前校验答案，并将低置信度或高风险案例交给人工。