ガイド

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.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〜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 つの環境変数を設定して、上のスニペットを実行してください。