Jev Python SDK (typesafe_sdk) 仕様リファレンス

1. 環境構築とクライアント初期化

Astralの uv を用いてプロジェクトを管理します：

# プロジェクトの依存関係に追加
uv add typesafe-sdk

import os
from typesafe_sdk import TypeSafeClient

# TYPESAFE_API_KEY 環境変数を自動読み込み
client = TypeSafeClient(api_key=os.environ.get("TYPESAFE_API_KEY"))

2. コアAPI: client.system_one(state, questions)

Jevへのリクエストは、評価対象データ（state）と、そのデータに対する1つ以上の質問（questions）を渡すことで、単一の低レイテンシ呼び出しでまとめて処理されます。

from typesafe_sdk import TypeSafeClient, Noul, Choice, Score

response = client.system_one(
    state={
        "user_query": "契約プランの解約方法を教えてください",
        "bot_answer": "設定画面の『契約管理』からいつでも即時解約可能です。"
    },
    questions={
        # ① Noul: 二値判定（Yes/No）
        "is_safe": Noul(
            instructions="入力に攻撃的・危険な表現が含まれていないか？",
            criteria={"true": "安全である", "false": "有害である"}
        ),
        # ② Choice: 選択肢分類
        "topic": Choice(
            instructions="問い合わせのカテゴリを判定せよ",
            criteria={
                "cancellation": "解約・退会手続き",
                "payment": "支払い・請求関連",
                "technical": "技術的不具合・バグ"
            }
        ),
        # ③ Score: 順序付きルーブリック評価
        "answer_quality": Score(
            instructions="回答がユーザーの質問に的確に答えているかを評価せよ",
            criteria=[
                "全く回答になっていない",
                "部分的な情報に留まり不足している",
                "適切に回答しており十分である"
            ]
        )
    }
)

3. レスポンスデータモデルの構造

response は SystemOneResponse 型となり、各質問のキーに対応する回答オブジェクトが含まれます：

ans = response.answers["is_safe"]
print(ans.noul)  # float: 0.0〜1.0（Trueである確率）
# 例: 0.99 (99%の確率で安全)

ans = response.answers["topic"]
print(ans.choice)         # str: 最も確率の高い選択肢キー (例: "cancellation")
print(ans.confidence)     # float: 最高確率値 (例: 0.94)
print(ans.probabilities)  # dict[str, float]: 全選択肢の確率分布

ans = response.answers["answer_quality"]
print(ans.score)          # int: 0から始まる基準インデックス (例: 2)
print(ans.confidence)     # float: その評点の確信度 (例: 0.88)
print(ans.probabilities)  # list[float]: 各スコア段階の確率分布

4. メタデータ (Usage & Model)

print(response.model)              # 使用モデル名 (例: "jev-latest")
print(response.usage.input_tokens) # 消費トークン数（極小・超低コスト）