4.2 官方 SDK：Python 与 Node

4.2 官方 SDK：Python 与 Node

本节摘要：日常开发请用官方 SDK：Python 端 pip install typesafe-sdk（≥3.10，提供 TypeSafeClient / AsyncTypeSafeClient 与 Noul / Choice / Score 构造类），Node 端 npm install @typesafe-ai/sdk（≥20，提供 noul / choice / score 辅助函数，答案类型由 TypeScript 自动推断）。SDK 相比裸 REST 多给三样东西：编译期字段检查、内建的超时/重试/中断选项、更短的调用代码。本节内嵌完整的 Node 脚本（hello_jev.mjs）与 Python SDK 写法对照。

学习目标

阅读完本节，你应当能够：

1. 用任一官方 SDK 写出等价于 4.1 的调用。
2. 说出 SDK 相比裸 REST 的三点增益。
3. 知道在哪里设置超时与重试。

一、Node SDK（@typesafe-ai/sdk）

安装（Node ≥ 20）：

npm install @typesafe-ai/sdk
​

以下脚本即本教程的 hello_jev.mjs，完整内嵌于此：

// hello_jev.mjs —— Node 版：原生 fetch 调用（Node >= 20，零依赖）
//
// 生产建议改用官方 SDK：npm install @typesafe-ai/sdk
//   import TypeSafe, { noul } from "@typesafe-ai/sdk";
//   const r = await new TypeSafe().systemOne({
//     state, questions: { urgent: noul("Does this need attention right now?") },
//   });
//   r.nouls.urgent.noul;  // 类型安全
// 这里用裸 fetch 是为了展示协议本身，与 01_hello_jev.py 等价。

const API_URL = "https://api.typesafe.ai/v1/systemone";

async function main() {
  const key = process.env.TYPESAFE_API_KEY;
  if (!key) {
    console.error("请先设置环境变量 TYPESAFE_API_KEY（console.typesafe.ai 申请）");
    process.exit(1);
  }

  const resp = await fetch(API_URL, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${key}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "jev-latest",
      state:
        "The deploy failed twice and customers are seeing 500s. Can someone look now?",
      questions: {
        urgent: {
          type: "noul",
          instructions: "The message needs attention right now",
        },
      },
    }),
  });

  if (!resp.ok) {
    // 401 key 无效 / 422 请求校验失败 / 429、529 限速过载 -> 指数退避重试
    console.error(`HTTP ${resp.status}: ${await resp.text()}`);
    process.exit(1);
  }

  const result = await resp.json();
  console.log(JSON.stringify(result, null, 2));

  const urgency = result.answers.urgent.noul;
  console.log(
    urgency > 0.8
      ? `>>> 紧急（p=${urgency}）：通知值班`
      : `>>> 常规（p=${urgency}）`,
  );
}

main();
​

SDK 写法（注释里已给出，展开看）：

import TypeSafe, { noul, choice, score } from "@typesafe-ai/sdk";

const client = new TypeSafe();            // 自动读 TYPESAFE_API_KEY

const result = await client.systemOne({
  state: "Deploy failed twice, customers seeing 500s. Can someone look now?",
  questions: {
    urgent: noul("Does this need attention right now?"),
  },
});

result.nouls.urgent.noul;   // TypeScript 知道这是 0~1 的数 —— 拼错字段名编译期报错
​

noul / choice / score 三个辅助构造函数把第 3 章的请求片段变成一行；答案按类型分桶（result.nouls / result.choices / result.scores），类型自动推断。

二、Python SDK（typesafe-sdk）

安装（Python ≥ 3.10）：

pip install typesafe-sdk
​

SDK 提供 TypeSafeClient / AsyncTypeSafeClient 与 Noul / Choice / Score 类，与 Node 端对称：

# pip install typesafe-sdk —— 写法示意（字段以官方文档为准）
from typesafe import TypeSafeClient, Noul, Choice, Score

client = TypeSafeClient()          # 自动读 TYPESAFE_API_KEY

result = client.system_one(
    state="Deploy failed twice, customers seeing 500s.",
    questions={
        "urgent": Noul(instructions="Does this need attention right now?"),
        "route": Choice(
            instructions="工单应路由到哪个团队",
            criteria={"ops": "部署与基础设施", "app": "应用功能", "other": "以上皆非"},
        ),
    },
)

result.nouls["urgent"].noul        # 是非题 → 概率
result.choices["route"].choice     # 单选题 → 胜出项
​

⚠️ 版本提醒：SDK 处于早期访问阶段，类名与参数以 docs.typesafe.ai 当前版本为准；本文 4.1 的裸 REST 写法不随 SDK 变动，可作为稳定参照。

三、SDK 的三点增益

💡 选型建议：学习与排障用裸 REST（4.1）；项目开发一律 SDK——第 8 章的可靠性选项（超时、退避）都挂在 SDK 上。

本节要点回顾

1. 两个 SDK：Python typesafe-sdk（Noul/Choice/Score 类）、Node @typesafe-ai/sdk（noul/choice/score 辅助函数 + TS 类型推断）。
2. 答案分桶：nouls / choices / scores，按问题 ID 取用。
3. 何时用裸 REST：学习协议、排障、或 SDK 不可用的环境。

单次调用会发了，最后一步是把 Jev 装进你已有的框架——LangChain 的中间件与 Vercel AI SDK 的工作流，4.3 节收官。