awesome-jevでJevの意思決定パターンを見つけ、評価する方法

awesome-jevとは？

awesome-jevは、TypeSafe AIのSystem One意思決定モデルであるJevに関する公開事例を厳選してまとめたカタログです。著者、記事、リポジトリ別ではなく、ツールの選択、コンテキストの順位付け、脅威の分類、情報を保持すべきかどうかの判断など、行われる意思決定ごとに整理されています。

このリポジトリはインデックスであり、Jev製品やSDKではありません。TypeSafe AIとは提携しておらず、掲載は推奨を意味しません。開発者が実装を見つけ、使用されているプリミティブを調べ、パターンを採用する前に重要な注意点を理解できるようにすることが目的です。

カタログへの掲載は、リンクが有効であり、誰かがレビューしたことを意味します。実装が正しい、安全で、効果的、または本番環境に適していることを意味するものではありません。

Jevを理解する

Jevは状態と型付きの質問を受け取り、調整済みの確信度を伴う型付きの回答を返します。長文のテキスト生成ではなく、エージェントループ内で高速かつ低コストに意思決定を行うことを想定しています。

カタログでは、Jevの3つのプリミティブを追跡しています。

• Choice：利用可能な選択肢の中から決定する必要がある場合に使用します。
• Score：項目や候補に型付きのスコアが必要な場合に使用します。
• Noul：個別の判断や命題に使用します。

異なるプリミティブの構成が互換的に使えるとは考えないでください。READMEでは、複数の選択肢に対して1つのChoiceを使う場合と、各選択肢に1つずつNoulを使う場合では、異なる問いに答えることが明確に警告されています。この違いは、実装上のエラーを招く一般的な原因です。

Jevは、文字列、JSONオブジェクト、テキスト配列などのテキスト入力を受け付けます。ドキュメントに記載されたリクエストコンテキストは64,000トークンで、状態と最長の質問に利用できるのは32,000トークンです。公開されたモデルの重みはないため、Jevをローカルで実行することはできません。

カタログの主な機能

意思決定を中心とした整理

主要なインデックスでは、再利用可能な意思決定パターンごとにエントリを整理しています。これにより、Jevに言及している無関係な投稿を検索するのではなく、「エージェントはどのようにツールを選択しているか」といった質問に答えやすくなります。

検索・共有可能なビュー

検索可能なサイトでは、フィルター、エントリカード、カバレッジヒストグラム、共有可能なURLを提供しています。専用のプリミティブビューと互換性ビューも含まれています。

証拠と注意点のメタデータ

各エントリには、出典、実装言語、コードが実際に呼び出しているプリミティブが記載されています。また、シャドーモード、ベンダー提供の数値、未検証、ライセンスなしなどの注意点が付いている場合もあります。詳細な注記はcatalog.jsonに保存され、サイト上に表示されます。

カバレッジと調査上の空白

カバレッジビューでは、各意思決定パターンについて公開事例がいくつ存在するかを確認できます。0は表示上の問題ではなく、調査上の空白を示します。確立されたパターンの発見だけでなく、まだ公開実証されていない有望な用途の特定にも役立ちます。

独立した測定結果

専用セクションでは、宣伝文句ではなく測定結果を取り上げています。Jevが既存の要約ツールを下回った評価、既存の分類器と同等だった評価、意味のあるレイテンシ改善をもたらさないまま課金対象の入力を増加させた評価など、否定的または中立的な結果を報告するエントリも複数あります。

インストールとセットアップ

方法1：ホストされたカタログを使う

通常の調査にインストールは必要ありません。ホストされたサイトを開き、意思決定パターンを選択して、該当するエントリを確認してください。

1. 検索可能なサイトを開きます。
2. カバレッジヒストグラムのバーを選択し、意思決定パターンで絞り込みます。
3. エントリを開き、出典、言語、プリミティブ、注意点を確認します。
4. 絞り込んだビューを共有する場合は、生成されたURLをコピーします。

方法2：リポジトリをクローンする

ソースデータ、ドキュメント、例、生成スクリプトをローカルで確認したい場合は、プロジェクトをクローンしてください。

git clone https://github.com/kydlikebtc/awesome-jev.git
cd awesome-jev

READMEはcatalog.jsonから生成されます。リポジトリでは、生成済みのREADMEを直接編集せず、カタログを編集するようメンテナーに明示的に指示しています。再生成するには、リポジトリのルートから次のドキュメント記載のコマンドを実行します。

python3 scripts/build_readme.py

提供された資料では、READMEに追加のインストール手順は記載されていません。カタログを変更または検証する前に、リポジトリのファイルと自動化設定を確認してください。

基本的な使い方：関連する実装を見つける

ステップ1：意思決定を定義する

広い技術ラベルではなく、システムが行う必要のある意思決定から始めます。例えば次のようなものです。

• エージェントは次にどのツールを呼び出すべきか？
• レビューのコンテキストにどのファイルを含めるべきか？
• 以前のツール結果はまだ重要か？
• ニュース項目に最もよく当てはまる脅威カテゴリはどれか？

ステップ2：対応するパターンを選択する

サイトのカバレッジヒストグラム、または README の意思決定パターンのセクションを使用してください。エージェントが次のアクションを選択する場合は、まずツール選択から始めます。カタログには、関数呼び出しやスキル提案から、ブラウザー操作や権限レビューまで、さまざまな例が含まれています。

ステップ 3: プリミティブで絞り込む

アーキテクチャから質問の種類がすでに示されている場合は、プリミティブの一覧を使用してください。クローズドセットのアクション選択なら Choice の例が適している可能性があり、独立した関連性判断なら Score または Noul の例が適している可能性があります。

プリミティブのラベルは、参照先のコードが何を呼び出しているかを説明するものとして扱ってください。実装が最適なプリミティブを選択していることを保証するものではありません。

ステップ 4: 注意事項を読む

リンク先のプロジェクトを開く前に、警告タグとカタログの注記を確認してください。たとえば、シャドーモードと記された統合はシステムに接続されていても、その判断が本番のラベル、キャッシュ、アラートに影響しないよう意図的に動作している場合があります。

ステップ 5: 元のソースを確認する

カタログは発見のために使用し、リンク先のリポジトリやドキュメントで動作を検証してください。状態がどのように構築されるか、質問がどのように型付けされるか、どのしきい値が使用されるか、信頼度が低い場合に何が起きるかを確認します。

調査ワークフローの例

3 つのプリミティブを学ぶ

初めて学ぶ場合は、リポジトリが推奨する順序で読み進めてください。

1. Choice、Score、Noul の質問を含むリクエストについて、公式クイックスタートを読みます。
2. Jev 1.13 の既知の制限を読みます。
3. カタログの3 つのプリミティブの例を確認します。

リポジトリには、ローカルの例を公式 API リファレンスとフィールドごとに照合したものの、ライブ API に対しては実行していないと記載されています。評価する際は、この違いを維持してください。

ツール選択を調査する

大規模なカタログから 1 つのツールを選択するエージェントを設計しているとします。ツール選択パターンを検索し、次のような実装を比較してください。

• 公式の関数呼び出しクックブック。クローズドセットの質問を使用して、リクエストを型付き関数にマッピングします。
• スキル提案クックブック。スキルが必要かどうかを評価し、候補スキルを順位付けします。
• FastMCP の実験的な Jev 検索変換。候補を絞り込んだツールを判定する前に、大まかな順位付けを行います。
• Composio のプロバイダー。ツール呼び出しを再構築し、棄権または確認が必要なケースを処理します。

これらのエントリを比較すると、単純な人気順では見えないアーキテクチャ上の選択が明らかになります。たとえば、段階的な検索、明示的な棄権、確認処理の分離などです。

コンテキスト選択を評価する

Jev でファイルやメモリを順位付けしたい場合は、宣伝用のデモンストレーションではなく、測定された例から始めてください。カタログによると、no-mistakes のレビューコンテキスト実験では候補ファイルごとに 1 つの Score を使用した結果、請求対象の入力が大幅に増えた一方で、実時間はほとんど改善しませんでした。この結果は、このパターンが常に効果的でないことを証明するものではありませんが、より単純なベースラインと比較評価する具体的な理由になります。

高度なヒント

独立した測定を優先する

手法、ベースライン、失敗、そして生データまたは再現可能な証拠を公開しているベンチマークのエントリを優先してください。カタログでは、Hermes Agent の圧縮評価が取り上げられています。これは Jev を既存の要約器と比較し、このアプローチを採用しないという判断を公開したものです。

同様に、中立的な結果も役立ちます。worldmonitor の統合は、ブラインド評価で Jev が現行モデルと同点にとどまった後も、シャドーモードのままでした。これは、新しい意思決定システムが本番の動作に直ちに影響を与えない状態でテストするための実践的なモデルです。

選択肢の順序への感度をテストする

ある独立した報告では、選択肢の順序を逆にすると、確率が 0.9 のしきい値を超えるほど変化したとされています。この結果は再現されていないため、その大きさを普遍的なものとして扱うべきではありません。ただし、次のような有用な堅牢性テストを示唆しています。

1. 元の選択肢の順序で同じ判断を実行します。
2. 意味を変えずに、選択肢をシャッフルまたは逆順にします。
3. 選択された回答と信頼度の値を比較します。
4. 運用上のしきい値を超えるか確認します。

無害な順序変更によって本番の動作が変わる場合、そのしきい値は見かけほど安定していない可能性があります。

同等の予算と単純なベースラインを比較する

Jev は、置き換える対象のシステムと必ず比較してください。新しさによる順序付け、決定論的なルール、現行の分類器、専用の再順位付け器など、単純な代替手段も含めます。コンテキストの予算が異なる場合は、予算を揃えた条件で結果を比較し、追加の入力ではなく判断品質を評価できるようにしてください。

型付き出力と正しい出力を分けて考える

型付き回答は統合の扱いやすさを高めますが、基礎となる判断が正しいことを保証するものではありません。アプリケーションを代表するデータで、精度、キャリブレーション、レイテンシ、コスト、失敗時の動作を検証してください。

棄権とレビューを前提に設計する

カタログの例には、明示的な棄権、確認が必要なケース、シャドーデプロイ、オプトイン機能が含まれています。誤った高信頼度の回答が安全でない、または高コストなアクションを引き起こす可能性がある場合、これらのパターンは特に有用です。

実装前に互換性を確認する

クロスプラットフォーム間の違いについては、リポジトリの互換性ドキュメントを確認してください。Python、JavaScript、TypeScript、Go、その他の言語で書かれた例が、同一の動作や統合の詳細を備えているとは限りません。

カタログデータを正しく使用する

プロジェクトを編集する際は、catalog.jsonを信頼できる唯一の情報源として扱い、その後READMEを再生成してください。リポジトリのバッジでは、カタログデータがCC0-1.0、プロジェクトコードがMITライセンスであることが示されています。ただし、リンク先プロジェクトのライセンスは異なる場合や、存在しない場合もあるため、各プロジェクトを個別に確認してください。

避けるべきよくある間違い

• カタログを推奨とみなす：掲載は、リンクが確認され解決できたことだけを示します。
• スター数だけで例を選ぶ：人気があっても、正確性、キャリブレーション、適合性が保証されるわけではありません。
• Choiceと独立したNoulの判断を混同する：これらの構成は異なる問いに答えるものです。
• 基準値なしでベンダーの性能値を信頼する：独立した再現可能な測定を優先してください。
• 否定的な結果を無視する：失敗した実験や中立的な実験から、最も実用的なエンジニアリング上の知見が得られることがあります。
• 型付き出力が正しさを保証すると考える：ラベル付きの、または別の方法で妥当性を説明できる正解データに照らして判断を検証してください。
• 生成されたREADMEを直接編集する：代わりにcatalog.jsonを更新し、ビルドスクリプトを実行してください。

まとめ

awesome-jevは、Jev統合のための証拠重視のリサーチマップとして活用するのが最適です。まずシステムが必要とする判断を明確にし、パターンとプリミティブで例を絞り込み、注意点を確認して、すべての主張を原典で検証してください。設計を採用する前に、自分のデータで再現し、単純なベースラインと比較し、信頼度の安定性をテストしたうえで、棄権または人によるレビューの計画を立ててください。