ガイド
Jev Python ガイド
公式 TypeSafe Python SDK はこのサイトにそのまま使えます。typesafe-sdk をインストールし、base URL を jev-api.org に向け、jev-api.org のキーで system_one を呼ぶだけです。インストール、設定、3 つの質問タイプ、回答の読み方、非同期クライアントを解説します。
更新日
インストール
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 は 2 つの環境変数を読みます。TYPESAFE_API_KEY には jev-api.org ダッシュボードのキーを設定します。TypeSafe コンソールのキーはここでは使えません。TYPESAFE_BASE_URL は https://jev-api.org にすると、api.typesafe.ai ではなく TypeSafe 互換の /v1/systemone にリクエストが届きます。
# .env — a key from your jev-api.org dashboard
TYPESAFE_API_KEY=jeva_...
TYPESAFE_BASE_URL=https://jev-api.orgTypeSafeClient(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〜500ms の遅延帯で返り、このサイトでは 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 を引き継ぎのシグナルに使います。低い場合や 2 つの選択肢が近い場合は、しきい値を下げるのではなく、人に回すか、より狭い追加質問を投げます。response.answers["id"] で生の質問オブジェクトも読めます。
非同期クライアント
AsyncTypeSafeClient は同じインターフェースで await 可能です。FastAPI のエンドポイント内や、複数 state を同時に展開するワーカーで便利です。
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
依存を増やしたくなければ、自分で JSON 本文を POST すればよいです。このサイトのシンプルなエンドポイント /api/v1/decisions は同じ state+questions 形を受け付け、モデル id は jev-1.13、制限は少し厳しめ(質問 1〜6、Choice 選択肢 2〜8)です。
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 — API キーがないか拒否されました。Authorization: Bearer ヘッダーと、キーがこのサイト発行かを確認してください。
- 402 — キーは有効ですが残高が不足しています。料金ページでクレジットを追加してください。
- 422 — 本文が検証に失敗したか、モデルに拒否されました(例:64k/32k トークン制限超過)。メッセージがフィールドを指します。
- 429 — レート制限です。待ってから再試行してください。
- 502 — 判断サービスが回答を返しませんでした。クレジットは消費されません。
よくある質問
TypeSafe コンソールのキーはこのサイトで使えますか?
使えません。キーは相互利用できません。TypeSafe のキーは api.typesafe.ai 用、jev-api.org ダッシュボードのキーはこのサイト用です。TYPESAFE_API_KEY に jev-api.org のキー、TYPESAFE_BASE_URL に https://jev-api.org を設定してください。
SDK はこのサイトのどのエンドポイントを呼びますか?
base_url を https://jev-api.org にすると、SDK は TypeSafe 互換エンドポイント /v1/systemone に POST します。こちらは完全な質問セット(最大 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 のようなエイリアスを送った場合でも同様です。
最初の判断を送る
キーを作成し、2 つの環境変数を設定して、上のスニペットを実行してください。