指南
Jev Python 指南
官方 TypeSafe Python SDK 可以不改代码地对接本站：安装 typesafe-sdk，把 base URL 指向 jev-api.org，用本站密钥调用 system_one。本指南覆盖安装、配置、三种问题类型、读取答案和异步客户端。
更新于
安装
PyPI 上的包名是 typesafe-sdk，需要 Python 3.10 或更高。源码在 github.com/typesafe-ai/typesafe-sdk-python。
pip install typesafe-sdk
# or: uv add typesafe-sdk
# requires Python 3.10+配置密钥和 base URL
SDK 读取两个环境变量。TYPESAFE_API_KEY 填本站控制台签发的密钥——TypeSafe 控制台的密钥在这里不可用——TYPESAFE_BASE_URL 必须是 https://jev-api.org，这样请求才会到达 TypeSafe 兼容的 /v1/systemone 接口而不是 api.typesafe.ai。
# .env — a key from your jev-api.org dashboard
TYPESAFE_API_KEY=jeva_...
TYPESAFE_BASE_URL=https://jev-api.org也可以直接传参：TypeSafeClient(api_key=..., base_url="https://jev-api.org")。默认模型是 jev-latest，可用 TYPESAFE_DEFAULT_MODEL 或 model 参数覆盖。默认超时 10 秒。
第一次调用：Noul、Choice 和 Score
client.system_one 接收一个 state——字符串、对象或数组——和一个由 Noul、Choice、Score 类构造的 questions 映射。下面这次调用大约在模型公布的 70–500 毫秒延迟区间内返回，本站计 1 积分。
from typesafe_sdk import Choice, Noul, Score, TypeSafeClient
with TypeSafeClient() as client: # reads TYPESAFE_API_KEY and TYPESAFE_BASE_URL
response = client.system_one(
state={"document": "I was charged twice. Please fix this ASAP."},
questions={
"billing": Noul(instructions="Is this ticket about billing?"),
"tone": Choice(
instructions="What is the customer's tone?",
criteria={"calm": None, "frustrated": None, "angry": None},
),
"urgency": Score(
instructions="How urgent is this ticket?",
criteria=["can wait", "this week", "today"],
),
},
)
print(response.nouls["billing"].noul) # 0.0 .. 1.0
print(response.choices["tone"].choice) # winning option
print(response.scores["urgency"].score) # fractional level读取答案
响应对象提供类型化视图：response.nouls、response.choices 和 response.scores，按你的问题 id 索引。Noul 答案带 .noul——为是的概率，0 到 1。Choice 答案带 .choice、.probabilities 和 .confidence。Score 答案带可落在档位之间的 .score，以及 .legend、.probabilities 和 .confidence。
把 confidence 当作交接信号：它偏低或两个选项接近时，把案子转给人工或追加一个更窄的问题，而不是盲目下调阈值。也可以通过 response.answers["id"] 读取每个问题的原始对象。
异步客户端
AsyncTypeSafeClient 接口相同、调用可 await——适合在 FastAPI 接口里，或需要并发展开多个 state 的 worker 中使用。
from typesafe_sdk import AsyncTypeSafeClient, Noul
async with AsyncTypeSafeClient() as client:
response = await client.system_one(
state="I was charged twice for my subscription.",
questions={"refund": Noul(instructions="Is the customer asking for money back?")},
)
print(response.answers["refund"])不用 SDK：直接 requests
不想引入依赖的话，自己 POST JSON 请求体即可。本站的简单接口 /api/v1/decisions 接受同样的 state 加 questions 结构，模型 id 用 jev-1.13，限制略紧（1 到 6 个问题、2 到 8 个 Choice 选项）。
import os
import requests
res = requests.post(
"https://jev-api.org/api/v1/decisions",
headers={"Authorization": f"Bearer {os.environ['JEV_API_KEY']}"},
json={
"model": "jev-1.13",
"state": "I was charged twice for my subscription.",
"questions": {
"refund": {"type": "noul", "instructions": "Is the customer asking for money back?"}
},
},
timeout=30,
)
print(res.json()["answers"]["refund"])错误与超时
jev-api.org 返回带 detail 字段的 JSON 错误。你会遇到的状态码：
- 401——密钥缺失或被拒绝。检查 Authorization: Bearer 头，以及密钥是否来自本站。
- 402——密钥有效但余额不足以支付本次调用。到价格页充值。
- 422——请求体未通过校验，或被模型拒绝（例如超出 64k/32k token 限制）。报错信息会指明字段。
- 429——触发限流。退避后重试。
- 502——决策服务未返回答案。不扣积分。
常见问题
能用 TypeSafe 控制台的密钥调本站吗？
不能。密钥不通用：TypeSafe 密钥用于 api.typesafe.ai，jev-api.org 控制台签发的密钥用于本站。把 TYPESAFE_API_KEY 设为本站密钥，TYPESAFE_BASE_URL 设为 https://jev-api.org。
SDK 在本站调用哪个接口？
把 base_url 设为 https://jev-api.org 后，SDK 会请求 /v1/systemone——TypeSafe 兼容接口，接受完整问题集（最多 256 个问题、255 个 Choice 选项、结构化 instructions），每次成功调用计 1 积分。
SDK 会自动重试吗？
TypeSafe SDK 默认带重试策略，覆盖 429 这类瞬时错误；可通过客户端的 retry 选项覆盖。422 校验错误应该改请求体，而不是重试。
需要什么 Python 版本？
Python 3.10 或更高。typesafe-sdk 包里同时有同步（TypeSafeClient）和异步（AsyncTypeSafeClient）客户端。
怎么知道是哪一版模型在回答？
响应的 model 字段始终报告实际服务的版本化 id——目前是 jev-1.13.0——即使你发送的是 jev-latest 这样的别名。
发出第一次决策
创建密钥，设置两个环境变量，然后运行上面的代码。