Jev のクイックスタート

「Jev」のクイックスタートをまとめました。

1. Jevとは

Jevは、文章生成ではなく、高速な「判断」の出力に特化したAIモデルです。

Jevの基本構造は、

です。

状態（state）と質問（questions）を渡すと、型付きの確率的な判断（Typed Decisions）を返します。また、複数の質問を並列に評価できる設計により、高速な判断を実現しています。

2. 3種類の判断

Jevでは、「Choice」「Score」「Noul」という3種類の型を使って質問を定義します。

2-1. Choice - どれ？

Choiceは、「どれを選ぶ？」という判断に使います。
たとえば、敵を見つけたときの行動を選ばせます。

Choice(
    instructions="次に取る行動は？",
    criteria={
        "attack": "敵を攻撃する",
        "escape": "敵から逃げる",
        "heal": "回復する",
    },
)

・出力例

{
  "choice": "attack",
  "probabilities": {
    "attack": 0.82,
    "escape": 0.13,
    "heal": 0.05
  },
  "confidence": 0.76
}

この場合は、「攻撃する」に最も高い確率を割り当てています。

2-2. Score - どのくらい？

Scoreは、「どのくらい？」という程度の判断に使います。
たとえば、現在どれくらい危険な状況かを評価します。

Score(
    instructions="現在の危険度は？",
    criteria=[
        "安全",
        "少し危険",
        "かなり危険",
    ],
)

・出力例

{
  "score": 1.6,
  "confidence": 0.81
}

基準は、

なので、`1.6`ならかなり危険寄りという意味です。

Score の criteria は2個以上の段階を指定します。たとえば5段階なら、レベル番号は 0〜4 になります。

2-3. Noul - Yes / No？

Noulは、「Yes / No？」という判断に使います。
たとえば、今すぐ回復が必要かを判断させます。

Noul(
    instructions="今すぐ回復する必要がある？",
)

・出力例

{
  "noul": 0.93
}

`0.93`なら、93%の確率でYesという意味です。

3. Playgroundで試す

まずはTypeSafeのWeb Interfaceにある「Playground」でJevを試せます。

Playgroundでは、判断材料となる「State」と、判断してほしい「Questions」を入力してから「Run」をクリックします。

・State

・Questions

{
  "next_action": {
    "type": "choice",
    "instructions": "次に取る行動は？",
    "criteria": {
      "heal": "回復アイテムを使ってHPを回復する",
      "retreat": "敵から距離を取って退避する",
      "attack": "近くの敵を攻撃する"
    }
  },
  "danger_level": {
    "type": "score",
    "instructions": "現在の危険度は？",
    "criteria": [
      "低：差し迫った脅威がなく、安全に行動できる",
      "中：脅威があり、注意して行動する必要がある",
      "高：倒される危険が高く、直ちに対処する必要がある"
    ]
  },
  "need_healing": {
    "type": "noul",
    "instructions": "今すぐ回復する必要がある？",
    "criteria": {
      "true": "今すぐ回復する必要がある",
      "false": "今すぐ回復する必要はない"
    }
  }
}

実行すると、Jevがそれぞれの質問を評価し、選択結果、スコア、Yesの確率などを返します。

4. PythonからJevを使う

4-1. セットアップ

(1) SDKのインストール。
公式SDKはPython 3.10以上に対応しています。

pip install typesafe-sdk

uvを使っている場合は、次のコマンドで追加します。

uv add typesafe-sdk

(2) APIキーの設定。
TypeSafeのダッシュボードからAPIキーを取得し、環境変数TYPESAFE_API_KEYに設定します。

export TYPESAFE_API_KEY="取得したAPIキー"

利用開始時点で、5ドル分のクレジットが付与されているようです。残高や利用額は、「Usage」画面下部の「See billing for more details.」から請求画面を開くと確認できます。

4-2. サンプルコードの実行

(1) サンプルコードの作成。

・jev_sample.py

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

state = (
    "プレイヤーのHPは20%。敵が近くに3体いる。\n"
    "回復アイテムを1個持っている。"
)

with TypeSafeClient(model="jev-latest") as client:
    response = client.system_one(
        state=state,
        questions={
            "next_action": Choice(
                instructions="次に取る行動は？",
                criteria={
                    "heal": "回復アイテムを使ってHPを回復する",
                    "retreat": "敵から距離を取って退避する",
                    "attack": "近くの敵を攻撃する",
                },
            ),
            "danger_level": Score(
                instructions="現在の危険度は？",
                criteria=[
                    "低：差し迫った脅威がなく、安全に行動できる",
                    "中：脅威があり、注意して行動する必要がある",
                    "高：倒される危険が高く、直ちに対処する必要がある",
                ],
            ),
            "need_healing": Noul(
                instructions="今すぐ回復する必要がある？",
                criteria={
                    "true": "今すぐ回復する必要がある",
                    "false": "今すぐ回復する必要はない",
                },
            ),
        },
    )

print("次に取る行動:", response.choices["next_action"].choice)
print("現在の危険度:", response.scores["danger_level"].score)
print("回復が必要な確率:", response.nouls["need_healing"].noul)

(2) サンプルコードの実行。

python jev_sample.py 

次に取る行動: heal
現在の危険度: 2.0
回復が必要な確率: 0.81

4-3. HTTP APIからの実行

SDKを使わず、HTTP APIを直接呼び出すこともできます。同じAPIキーを設定したターミナルで、次のコマンドを実行します。

curl -X POST https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "プレイヤーのHPは20%。敵が近くに3体いる。\n回復アイテムを1個持っている。",
    "model": "jev-latest",
    "questions": {
      "next_action": {
        "type": "choice",
        "instructions": "次に取る行動は？",
        "criteria": {
          "heal": "回復アイテムを使ってHPを回復する",
          "retreat": "敵から距離を取って退避する",
          "attack": "近くの敵を攻撃する"
        }
      },
      "danger_level": {
        "type": "score",
        "instructions": "現在の危険度は？",
        "criteria": [
          "低：差し迫った脅威がなく、安全に行動できる",
          "中：脅威があり、注意して行動する必要がある",
          "高：倒される危険が高く、直ちに対処する必要がある"
        ]
      },
      "need_healing": {
        "type": "noul",
        "instructions": "今すぐ回復する必要がある？",
        "criteria": {
          "true": "今すぐ回復する必要がある",
          "false": "今すぐ回復する必要はない"
        }
      }
    }
  }'

{
  "model": "jev-1.13.0",
  "answers": {
    "next_action": {
      "type": "choice",
      "choice": "heal",
      "confidence": 0.71,
      "probabilities": {
        "attack": 0.0,
        "retreat": 0.19,
        "heal": 0.81
      }
    },
    "danger_level": {
      "type": "score",
      "score": 2.0,
      "confidence": 1.0,
      "legend": {
        "0": "低：差し迫った脅威がなく、安全に行動できる",
        "1": "中：脅威があり、注意して行動する必要がある",
        "2": "高：倒される危険が高く、直ちに対処する必要がある"
      },
      "probabilities": {
        "0": 0.0,
        "1": 0.0,
        "2": 1.0
      }
    },
    "need_healing": {
      "type": "noul",
      "noul": 0.81
    }
  },
  "usage": {
    "input_tokens": 558,
    "output_tokens": 73
  }
}

5. Jevの設計パターン

TypeSafeでは、Jevをアプリケーションに組み込むための代表的なパターンを4つ紹介しています。

5-1. Speculative Fan-Out - 複数の判断をまとめて出す

Jevでは、同じStateに対する複数の質問を、1回のAPI呼び出しでまとめて送れます。

たとえばゲームなら、

といった質問をまとめて送り、それぞれを並列に評価できます。

さらに、あとで必要になるかもしれない質問も先に送っておき、実際に必要になった結果だけ使う方法を、TypeSafeでは「Speculative Fan-Out」と呼んでいます。

5-2. Composite Scoring - 判断を分けて、あとで組み合わせる

複雑な判断を、1つの大きな質問にまとめるのではなく、複数の小さな評価に分ける方法です。

たとえば「現在どれくらい危険か」を、

のように分けて、それぞれをScoreで評価します。

最後に、プログラム側で結果を組み合わせます。

danger = (
    enemy_score * 0.4
    + hp_score * 0.4
    + escape_difficulty_score * 0.2
)

TypeSafeでは、このように複数の評価を組み合わせる方法を「Composite Scoring」と呼んでいます。

5-3. Confidence-Gated Routing - 自信があるときだけ判断を使う

ChoiceとScoreには、判断結果とともにconfidenceが返ります。

たとえば、

といった切り替えができます。

if answer.confidence >= 0.8:
    action = answer.choice
else:
    action = default_action

このように、confidenceを使って処理を切り替える方法を「Confidence-Gated Routing」と呼んでいます。

5-4. Intent Routing - 判断結果に応じて処理先を変える

Jevを、入力内容に応じて処理先を選ぶために使う方法です。

たとえば問い合わせなら、

のように振り分けられます。

if intent == "order_status":
    handle_order()
elif intent == "product_question":
    ask_llm()
elif intent == "complaint":
    escalate_to_human()

TypeSafeでは、このように入力の意図を判断して処理先を切り替える方法を「Intent Routing」と呼んでいます。

6. Jevの活用例

TypeSafe公式ドキュメントでは、Jevの活用例を「用途のカテゴリ」「具体的なユースケース」「基本的な判断タスク」の3つのレベルで紹介しています。

6-1. おすすめ用途

TypeSafe公式ドキュメントでは、Jevの用途カテゴリとして、次の5つを紹介しています。

6-2. ユースケース

TypeSafe公式ドキュメントでは、Jevを利用できる具体的なユースケースとして、次のような例を紹介しています。

・検索 / RAG

・科学研究

・モデルルーティング

・LLMガードレール

・セマンティックコードLint

・予測モデル用の特徴量抽出

・採用

・営業リードの獲得

・カスタマーサポート

・保険請求

・金融犯罪対策

・法務 / コンプライアンス

・ECマーケットプレイス

・モデレーション / Trust & Safety

・広告

・ゲーム

・リスク評価

・需要予測

・グラフ / ナレッジグラフ

6-3. タスク

Jevのユースケースは、さらに次のような基本的な判断タスクに分解できます。

7. AIエージェントから使う

7-1. Agent Skillとは

TypeSafeでは、Claude CodeやCodexなどのAIエージェント向けに、公式の「TypeSafe Agent Skill」も提供しています。

Agent Skillを導入すると、コーディングエージェントがTypeSafeの、

などを参照しながら、Jevを使った設計やコードの提案・実装を行いやすくなります。

7-2. Agent Skillのインストール

・Claude Code
Claude Codeでは、次のコマンドでインストールできます。

claude plugin marketplace add typesafe-ai/skills
claude plugin install typesafe@typesafe-ai

インストール後は、プロンプトで、

と指定して利用できます。

Claude Codeでは、次のコマンドから直接Skillを呼び出すこともできます。

/typesafe:typesafe-ai

・Codexなど
Codexなど、その他の対応エージェントでは次のコマンドを使います。

npx skills add typesafe-ai/skills --skill typesafe-ai

実行すると利用するエージェントを選択できます。

デフォルトではプロジェクト単位でインストールされます。グローバルにインストールする場合は -g を付けます。

7-3. Agent Skillを使った開発

公式ドキュメントでは、まずプロジェクトを分析して、TypeSafeを利用できそうな場所を探させる方法が紹介されています。

たとえば既存のコードに、

などがあれば、Jevの型付き判断に置き換えられないかをエージェントに検討させることができます。

APIキーを TYPESAFE_API_KEY に設定しておけば、エージェントに実際のAPIを試させながら、利用方法を検討させることもできます。

TypeSafeのCookbookを参照して、現在のコードに使える設計パターンを探させる使い方も紹介されています。

7-4. Agent Skill利用時のポイント

TypeSafe公式ドキュメントでは、Agent Skillを使った開発でも、エージェントにすべて任せるのではなく、人間がQuestionsやしきい値を確認することを推奨しています。

特に、

ことが重要とされています。

Jevでは、コードそのものだけでなく「何をどのような基準で判断させるか」が動作に大きく影響するため、Questionsやしきい値をレビューしやすい形にしておくのがポイントです。