Lesson 0002: Python環境とSDKで動かすJev実践

1. 開発環境のセットアップ (uv)

本ワークスペースでは、現代の高速パッケージマネージャー uv を採用しています。pyproject.toml に typesafe-sdk が組み込まれており、即座に実行可能です。

# 依存関係の追加（実行済み）
uv add typesafe-sdk

# ハンズオンスクリプトの実行
uv run python hands_on_primitives.py

2. Jevのコア呼び出しパターン

Jevに対する問い合わせは、評価対象データ（state）と、そのデータに対する複数の質問辞書（questions）を client.system_one() に渡すだけのシンプルな構造です。

from typesafe_sdk import TypeSafeClient, Noul, Choice, Score

client = TypeSafeClient(api_key=os.environ.get("TYPESAFE_API_KEY"))

response = client.system_one(
    state={
        "user_query": "解約方法と違約金について知りたい",
        "bot_answer": "管理画面から即時解約でき、違約金は一切ありません。"
    },
    questions={
        "is_safe": Noul(instructions="安全な入力か？"),
        "category": Choice(
            instructions="問い合わせカテゴリを選択せよ",
            criteria={"cancellation": "解約", "payment": "支払い"}
        ),
        "quality": Score(
            instructions="回答の網羅性を評価せよ",
            criteria=["不十分", "一部回答", "完璧"]
        )
    }
)

生成型LLMでは質問ごとに別プロンプトを投げるか長大なプロンプトを連結する必要がありましたが、Jevでは単一リクエストで複数の型付き判断を超高速・並行的に完了できます。

3. 決定モデルならではのレスポンス処理

従来のモデルとの最大の違いは、戻り値が自然文ではなく厳密な型オブジェクトである点です。

① NoulAnswer (真偽確率)

ans.noul に 0.0〜1.0 の浮動小数点数が直接格納されます。ans.noul >= 0.5 で判定しつつ、確信度（閾値）でガードレール制御が可能です。

② ChoiceAnswer (カテゴリ・確信度・全分布)

ans.choice に最有力候補（例: "cancellation"）、ans.confidence にその確率、ans.probabilities に全選択肢の確率分布が辞書で返ります。

③ ScoreAnswer (期待スコア・加重平均)

Jevの Score は単なる「2点」という離散整数ではなく、各レベルの確率加重平均（期待値）を ans.score（連続値: 例 1.88）として返します。これにより、「レベル1とレベル2のちょうど中間（1.50）」といった繊細な境界状態を数理的に扱えます。

4. 実際に動かしてみよう

ワークスペース内に用意した hands_on_primitives.py を実行してみましょう：

uv run python hands_on_primitives.py

APIキーが未設定でも、SDKのデータ構造（NoulAnswer, ChoiceAnswer, ScoreAnswer）を100%再現したシミュレーションモードで動作し、判定結果・確率分布・カスケード制御の出力が確認できます。

💡 次のステップ（ゴール達成へ）

次回（Lesson 0003）は、いよいよ今回のミッションの本丸である「自作の評価基準（ルーブリック）を定義し、カスタム判定タスクを実行する実践」に進みます。

どのような評価タスク（例: RAG回答のハルシネーション検査、カスタマーサポートの回答品質、メールの緊急度判定など）に適用したいか、アイデアがあればお知らせください！