TypeSafe AI の Jev が公開されてから1週間あまりで、GitHub には Jev を使ったリポジトリが一気に増えました。デモ動画はたくさん流れてきますが、実装してみると気になるのは地味なところです。state には何をどう書くのか。選択肢が多すぎるときはどうするのか。Jev に届かなかったら何を返すのか。確信度が低いときは誰に回すのか。
こうした設計の答えは、公式ドキュメントよりも他の人のコードの中にたくさん書いてあります。README に「なぜこうしたか」を丁寧に書いている作者も多く、読むだけでかなり勉強になります。
この記事では、そういうリポジトリを20本選んで、どのファイルを読めば何が分かるかを紹介します。選んだ基準は次の三つです。
- 30分から1時間で読み切れる規模であること(大きなものは読む場所を絞って紹介します)
- 「ここは真似できる」という設計上の判断がはっきりあること
- README かコメントに、その判断の理由が書いてあること
スター数では選んでいません。スターがまだ一桁でも、設計がよく考えられているものを優先しました。日本の作者のリポジトリが多めです。
これが私の初めての記事です。読みにくいところや間違いがあれば、コメントで教えてもらえるとうれしいです。
私はオープンソースのエージェント開発環境 OpenChamber の共同創業者です。X の公開投稿から「Jev で作ったもの」を毎日集めるフィード Jev Builds も運営していて、この20本は、そこでコードへのリンクが付いている約800件の中から、README とソースを読んで選びました。
Jev のおさらい(3行)
- Jev は文章を生成しません。state(判断材料)と questions(選択肢を決めた問い)を渡すと、問いごとの確率が返ってきます
- 問いの型は Choice(どれか一つ)、Score(順序付きの段階)、Noul(Yes の確率)の三つです
- 一回のリクエストに入れた問いは並列に評価され、お互いの答えは見えません
呼び先は TypeSafe の API(https://api.typesafe.ai/v1/systemone)だけではありません。以下のリポジトリには、Vercel AI Gateway やロリポップ!AI ゲートウェイ経由で呼ぶ実装も出てきます。
まずここから
1. typesafe-ai/skills:公式が「どう設計するか」を書いた一枚
Markdown / ファイル6個
TypeSafe 公式の agent skill です。Claude Code なら claude plugin marketplace add typesafe-ai/skills のあとに claude plugin install typesafe@typesafe-ai、ほかのエージェントなら npx skills add typesafe-ai/skills --skill typesafe-ai で入ります。
読みどころ:skills/typesafe-ai/SKILL.md(約10KB)
- 使いどころが「分類」の一言で終わっていません。「生成せずに選ぶ」「判断を再利用できるデータにする(特徴量にする)」「検証してエスカレーションする」「変化する state に応じて次の一手を選ぶ」といった型が並んでいます
- 細かいけれど大事な注意がまとまっています。問いの ID はモデルに送られないので、
instructionsに完全な問いを書くこと。Noul の0.5は「中くらい」ではなく「Yes と No が同じくらいの確率」という意味であること。Web アプリでは API キーをサーバー側に置くこと - 「既知のルール、計算、厳密な照合、実行はコードに残す」という一文が、以下で紹介するリポジトリのほとんどに共通する設計方針になっています
真似できるところ:設計の前にこのファイルを読んでおくと、以下の19本が「なぜそうしているか」が読みやすくなります。
本番に入れるなら
2. TrainLCD/Functions:本番のフィードバック振り分けに Jev を入れたコード
TypeScript / Cloudflare Workers
鉄道アプリ TrainLCD のバックエンドです。ユーザーから届いたフィードバックをキューで受けて振り分ける処理に、Jev が使われています。タイトルと要約の生成は Workers AI が担当し、Jev はスパムかどうか、カテゴリ、優先度、原因のコンポーネントの判定だけを受け持つ、という分担です。
読みどころ:src/consumers/typesafeTriage.ts
- しきい値の決め方がコメントに書いてあります。実測データでフィッティングしたが、グリッド探索の最良値は使わず、分離幅の中央に寄せて丸めた値を使っている(最良値はデータに過学習するから)。スパムのしきい値を0.5にした理由も、正当な報告とスパムの信号がどこまで離れていたかという実測と一緒に書かれています
- instructions と criteria をすべて日本語で書いている理由も書いてあります。「車内放送の書き起こし」のような、英語に置き換えると輪郭がぼやける概念を基準に含めるためです。一致率が低いときに次に変えるべき変数は命令文の言語だ、という指摘まであります
- Noul の criteria に true / false それぞれの説明を書いています。たとえば「テスト」「送信試験」のような投稿をスパム側に含める、書き方が拙くてもアプリに向いた内容なら正当な報告とみなす、といった具合です
- 優先度の決め方は、最初は複数の Score の加重和だったものを、カテゴリで分岐させる形に変えています。要望に高い severity が付いて優先度が跳ね上がる、という実測上の問題があったからです
あわせて読む:src/cli/typesafe-triage-spike.ts
本番と同じ質問定義を import して、正解ラベル付きのデータで一致率を測るスクリプトです。モデル名を wrangler.jsonc の vars から読むようにしていて、「本番のモデルを変えたのにスパイクだけ古いモデルを測り続ける」事故を防いでいます。比較の落とし穴(現行モデルには few-shot として見せたデータなので、現行側の一致率は比べられない)までコメントに残っています。
真似できるところ:問いの定義を本番と計測スクリプトで共有すること。そして、しきい値の根拠をコードの中に書き残すこと。
3. m-mizutani/semgate:Go の HTTP ミドルウェアにする
Go / 主要ファイル10個ほど
net/http のミドルウェアとして、リクエストごとに Jev へ問いを投げ、型付きの答えをハンドラに渡すライブラリです。プロンプトインジェクションの検知やインテントでのルーティングを、func(http.Handler) http.Handler として書けます。
読みどころ:gate.go と body.go、そして README の「What is sent」
- 何が外に送られるかを最初に警告しています。既定では、
AuthorizationやCookieを含むすべてのヘッダーとクエリパラメータが TypeSafe の API に送られます。そのためWithHeaderDenylistなどで絞るように書いてあります -
g.Noulなどはミドルウェアを一つずつ作り、g.Askは複数の問いを1回の API 呼び出しにまとめます。ミドルウェアを重ねると問いの数だけ呼び出しが増える、という注意も README に明記されています - ボディは先頭だけ読んで送り、次のハンドラには全体をストリームのまま渡します。サイズ上限、読み取りのタイムアウト、上限を超えたときの扱い(切り詰めるか413で拒否するか)もオプションで選べます
- 評価に失敗したとき、既定では503を返します。
WithEvaluationErrorHandlerでリクエストを通す運用に切り替えることもできます
真似できるところ:「判定が失敗したときに通すか止めるか」をライブラリ側で決めてしまわず、利用者が選べるようにしていること。
4. giuliosmall/pg_typesafe:SQL から Jev を呼ぶ PostgreSQL 拡張
C / typesafe.c 1ファイル
SELECT typesafe_noul(本文, '緊急性があるか?') のように、SQL から Choice・Noul・Score を呼べる拡張です。まだプレアルファ版です。
読みどころ:README の「API key」と「Functions」、そして typesafe.c
- API キーを SQL に書かせない設計です。キーは Postgres サーバーの環境変数か、スーパーユーザーだけが設定できる
typesafe.api_key_fileで渡します。SET typesafe.api_keyはクエリログに残る、という注意も書いてあります - 1行ずつ呼ぶ関数とは別に、
typesafe_detect_manyのような一括版があります。重複のない値をまとめて、1リクエストに32件ずつ送ります。作者の計測では、1,000件の苦情に含まれる38種類の文面を分類するのに、1件ずつだと23秒、一括版だと0.86秒でした - 429 と 529 は
Retry-Afterを見ながら最大3回リトライします。実行中のリクエストもstatement_timeoutや Ctrl-C で止められます。EXECUTE権限は既定でPUBLICから剥がされています
真似できるところ:「一行ずつ呼べる便利な関数」と「まとめて呼ぶ速い関数」を両方用意して、README で後者に誘導していること。
5. shunshunNi/redmine_jev:何も止めない、入力中のヒント
Ruby / Redmine プラグイン
Redmine でチケットを書いている最中に、「選んだトラッカー(バグ、機能など)が内容に合っているか」を Jev に聞いて、フォームの下にヒントを出すプラグインです。
読みどころ:app/services/redmine_jev/tracker_check.rb と README の「The check」
- 何もブロックしません。バリデーションエラーも出さず、フィールドも書き換えません。Jev に届かなければ警告も出ません。判定モデルを業務システムに入れるときの、いちばん安全な入れ方です
- 選択肢の説明を実データから作っています。トラッカー自体の説明文は管理者しか書けず、たいてい空か古くなっているため、そのプロジェクトで最近起票されたチケットの件名を選択肢の説明として渡しています。まだ一件もないトラッカーは名前だけで出します
- 「今のトラッカーが合っているか」と「どれが一番合うか」の二つを1リクエストで聞いています
-
scripts/jev_tracker.rbは、プラグインを入れられない Redmine に対しても REST API 経由で同じ問いを投げ、しきい値をかける前の生の確率を表示します。導入前に「本当に使えるか」を確かめるための道具です
真似できるところ:選択肢の説明文を人に書かせず、実データ(最近の件名)から自動で作ること。
型と DSL にする
6. ItisNoMatter/kojev:答えを自分の enum で受け取る
Kotlin Multiplatform(JVM / Android / iOS)
Jev の答えを文字列ではなく、自分で定義した enum や sealed 型で受け取れるクライアントです。選択肢の説明は enum 定数に持たせるので、書き忘れるとコンパイルエラーになります。
読みどころ:README の「What Jev is, and is not」と docs/api-notes.md
- Noul は null チェックではない、Score の答えは段階そのものではない、という二つの注意がきちんと書かれています。Score の値は確率で重み付けした平均なので、段階と段階のあいだに落ちたり、確率がゼロの段階に落ちたりすることさえあります。kojev は平均・最頻値・分布をすべて返して、どれを使うかは利用者に決めさせます
-
docs/api-notes.mdには、リクエストとレスポンスの形が出典付きでまとめてあります。自分でクライアントを書く人にも役立つ資料です - モデル名を
jev-1.13.0のように固定する例が載っています。jev-latestはリリースに合わせて中身が変わるエイリアスだ、という注意付きです
真似できるところ:「選択肢の抜け」を型システムで防ぐ発想。Python の Enum でも TypeScript の union 型でも真似できます。
7. L4Ph/belief:条件が「自然言語の信念」になる言語
TypeScript / コンパイラとランタイムのモノレポ
bel という小さな言語です。if の条件に "the user asks for a refund" -> refund(t) のような自然言語の命題を書くと、普通の TypeScript にコンパイルされ、実行時に Jev が判定します。
読みどころ:docs/rfc/0001-bel-v0.md と examples/
- 命題は確率で答えられるものなので、条件の表面にしきい値が見えるように設計されています
- フローが実行前にどんな問いを投げるかが静的に分かるので、問いを1回の呼び出しにまとめられます
- テスト用の runtime として、モック、録画した回答の再生(カセット)、confidence の下限を変えるものがそろっています。実際の回答を録画して回帰テストにする例もあります
- 生成された TypeScript を
.belの隣にコミットし、両者がずれたら落ちるテストまで置いてあります
真似できるところ:「判定を呼ぶコード」をテスト可能にするためのカセット(録画再生)の仕組み。言語を作らなくても、そのまま真似できます。
8. jugyo/jev-workflow:次の一手を Jev に選ばせるワークフロー
TypeScript / src/index.ts 約8KB
状態(valibot のスキーマ)と、実行できるアクションの一覧(説明と実行関数)を渡すと、Jev が次のアクションを一つ選び、ライブラリがそれを実行します。状態が変わったら update() を呼んで続けます。
読みどころ:examples/document-review.ts
- 例は、文書を書く → レビューする → 落ちたら直す → 通ったら終える、というループです。「人間に任せる(escalate)」もアクションの一つとして並べてあります。エラーやレビューの失敗回数の上限を状態に持たせて、それを見たら escalate を選ぶように指示しています
- Jev が選べるのは事前に宣言したアクションだけなので、モデルが勝手な操作を作り出すことはありません
真似できるところ:状態を小さな列挙値の組み合わせ(not_created / ready など)にしておくと、判定が安定します。
CLI とエディタに入れる
9. uehaj/jev-semgrep:意味で探す grep
JavaScript / semgrep.mjs 1ファイル、依存ゼロ
semgrep -e "顧客が怒っている" tickets.txt のように、意味で行を探す grep です。作者による解説記事が Zenn にあります。
読みどころ:semgrep.mjs の evaluate 周辺と README の「How this differs from vector search」
- リクエストの組み立て方:state は
{L0: "1行目", L1: "2行目", …}という行 ID 付きのオブジェクトで、問いは「行 L3 はこの意味に合うか」という Noul を行×意味の数だけ並べています。30行または2万文字ごとにまとめて1リクエストにし、8本を並列に投げます - ベクトル検索との違いの説明がよくまとまっています。埋め込みは問いを見る前に行のベクトルが決まってしまうので、話題が近いかしか測れません。Jev は行と問いを一緒に読むので、否定や「誰が」「すでに終わったか」で答えが変わります。README には「返金について書かれている」6行のうち、顧客が返金を求めている2行だけが高い確率になる例が載っています
- 肯定のしきい値
-tと否定のしきい値-Tを分けていて、そのあいだのあいまいな行はどちらにも当たりません -
-rで再帰するときは、.env*や*.pemなど秘密情報らしいファイルを飛ばします。検索した行はすべて外部 API に送られるからです - 英語で書いた意味で日本語の行を探すこともできます。ただし作者は、日本語の意味はしきい値付近で少し揺れるので、きわどいときは英語で書くほうが安全だ、と書いています
真似できるところ:「1行ごとに Noul」を ID 付きの state で束ねて1リクエストにする書き方。ログ、チケット、RAG の候補など、どこにでも使えます。
10. syumai/jevyoumean:意味で「Did you mean?」を出す CLI ラッパー
Go
git remove foo.txt と打つと「git rm foo.txt のことですか?」と聞き返す、任意の CLI のラッパーです。編集距離ではなく意味で合わせるので、remove → rm や list → ps のように綴りが遠い組み合わせにも効きます。
読みどころ:README の「How it works」、internal/jev/suggest.go、internal/decide/decide.go
- 実行してから直すのでなく、実行する前に調べます。副作用が二度走らないようにするためです。stderr が TTY でない(スクリプトや CI の)ときは、何もせずにそのまま実行します
- 候補は対象コマンドの
--helpの出力から取り出し、サブコマンド名と説明を Choice の選択肢にして、必ず__none__(該当なし)を加えます。候補が254を超えると二段階の Choice に分割します - 自動実行モードでも、
rm・delete・reset・pushなどが当たったときは自動では実行せず、確認に回します
真似できるところ:選択肢を人が書かずに、既存の --help から作ること。そして、壊れやすい操作は確率が高くても自動実行しないこと。
11. youyo/decio:判定を終了コードにして、シェルと CI に渡す
Go / Homebrew で入る
git diff | decio --boolean "Does this change require running tests?" --result-exit-code のように、標準入力の文脈から型付きの判定を出して、終了コードで返す CLI です。判定に応じて、あらかじめ設定ファイルで宣言したコマンドを実行することもできます。
読みどころ:docs/design/decio-design.md と examples/claude-code/
- モデルの出力を絶対にシェルの断片として扱いません。実行できるのは、信頼できる設定ファイルに宣言したコマンドだけです。「文脈 → 判定 → 事前に宣言したアクション」という境界が設計の中心にあります
- boolean・choice・score の三種類を、フラグだけの手軽な使い方と YAML の宣言的な使い方の両方で使えます。Claude Code のフックに入れる例もあります
同じ系統の CLI に sharziki/semdecide(semdecide is '…' で真偽を返す)もあります。
真似できるところ:「判定はしても、実行するものは人間が事前に決める」という境界線の引き方。
12. mrnugget/jev-shell-history:zsh の履歴補完を Jev で並べる
TypeScript + zsh
fish のような灰色の補完候補を、zsh で Jev を使って出すプラグインです。直近100件の履歴から、今打っているのがどのコマンドの続きかを当てます。
読みどころ:README の「How it works」と src/suggest.ts
- 1リクエストに二つの問い:候補 ID に対する Choice(どれを補完しているか)と、Noul(そもそもどれかを補完しているか)です。二つの信号は失敗する場所が違う(履歴が少ないと Noul が弱く出るが Choice は決定的、でたらめな入力だと Choice が散るが Noul はゼロ近く)ので、両方を組み合わせてゲートにしています
- 前方一致する候補が一つしかなければ、リクエストを送らずにすぐ出します。「ルールで決まるものはコードで決める」をそのまま実践しています
- 打鍵のたびに実行中のリクエストを止め、応答が返ってきた時点で入力が変わっていたら、その結果を捨てます
真似できるところ:Choice と Noul を「二重のゲート」として組み合わせる考え方。
13. windymelt/ddskk-jev:SKK の変換候補を文脈で並べ替える
Emacs Lisp
Emacs の日本語入力 ddskk の変換候補を、前後の文脈に合わせて Jev に並べ替えさせるマイナーモードです。
読みどころ:README の「設計の根拠」「留意点」「HTTP プロトコルについて」
- 変換位置の前120文字と後40文字、読み、送り仮名を state にして、候補を最大12件まで Choice の選択肢として渡します。「どの候補も合わない」を加え、それが選ばれたときは辞書の順序をそのまま使います
- 失敗したときの設計が細かく書かれています。タイムアウト(既定2秒)を過ぎたら並べ替えを諦めて元の順序に戻します。連続3回失敗したら問い合わせ自体を止めます。変換の途中で順序が変わらないよう、並べ替えは変換の1発目だけです
- Vercel AI Gateway 経由と TypeSafe 直接の二つの呼び方を実装していて、Gateway の評価モデル向け HTTP プロトコルも README に書いてあります
- 公式ドキュメントに CJK のテキストは英語より精度が下がると書かれていることに触れ、指示文の既定を英語にしている、と理由を説明しています
真似できるところ:入力まわりに AI を入れるなら、失敗したら黙って元の動作に戻り、失敗が続いたら自分から止まる、という作り。
エージェントのまわりに置く
14. tamaratran/fast-jev-compaction:要約しないコンパクション
TypeScript / Claude Code プラグイン兼 npm ライブラリ
Claude Code のコンパクション(会話の要約)を置き換えるプラグインです。要約はせず、ツール呼び出しとその結果ごとに「まだ必要か」を Jev に判定させ、不要なものを削ります。残したものは一字一句そのままです。
読みどころ:src/state.ts(state を上限に収める処理)と src/compact.ts(判定の適用)
- 要約は情報を失う(ファイルパス、エラーの原文、制約が消える)、という問題意識から出発しています。削除なら、元の文を書き換えることは起きません
- 各呼び出しに Noul を二つ投げます。「呼び出したこと自体を残すべきか」と「結果を原文のまま残すべきか」です。前者だけ Yes なら、結果を先頭300文字に切り詰めて注記を付けます
- state は会話全体です。ただし、ツールの結果は短い注記に置き換え、上限(既定で推定2.5万トークン)に収まるまで段階的に削っていきます。1リクエストは Jev の上限3.2万トークンに収まるように分割します
- 最初のメッセージと直近のメッセージは固定で、決して消しません。失敗したときは例外を投げ、どうフォールバックするかは呼び出し側に任せています
真似できるところ:要約する代わりに、残すか捨てるかを判定させるという考え方。
15. burnigtm/jev-mcp:コーディングエージェントに判断ツールを9個足す MCP サーバー
TypeScript / stdio の MCP サーバー
Cursor や Codex から使える MCP サーバーです。次の一手のルーティング、パッチのレビュー、主張の検証、信頼できない内容のスクリーニング、候補のランク付けなど、九つのツールを提供します。
読みどころ:src/packs/(ツールごとの問いのセット)、src/limits.ts、docs/architecture.md
- 結果に必ず
action(auto/review/escalate)が付きます。コンテキストが足りないときは決してautoにしない、という方針がコードに組み込まれています - 上限の扱いが具体的に書かれています。state と問いの合計、state と最長の問いの組み合わせ、ランク付けの候補数(1回の呼び出しで250まで、それを超えたら何段階かで絞る)などです
-
JEV_MCP_MOCK=1で決定的に動くモックモードがあり、デモやテストに使えます
真似できるところ:判定結果を「自動 / 人が確認 / 上位に回す」の三段階の行動に翻訳して返すこと。
16. awlevin/typesafe-computer-use:1ステップ0.0002ドルのコンピューター操作
Python / macOS(Windows は実験的)
画面を OCR で決定的に読み取り、次に取るべき操作を Jev の Choice で選んでクリックする、コンピューター操作のループです。文章を書く必要があるときや、判定が止まって画面を読む必要があるときだけ、別の生成モデルを呼びます。
読みどころ:README の冒頭の比較表の下にある「honest caveat」、typesafe_computer_use/decide.py、dates.py
- 作者は正直にこう書いています。大きなモデルはイベントの日付をピクセルから読み取って比べられたが、分類器のほうは日付の解析を別途用意する必要があった。フロンティアモデルがタダでやっている推論は、すべて決定的な state として作り直さなければならない
- その「作り直し」の実物が
dates.pyです。Jev に判定させる前に、コードで何を用意すべきかがよく分かります - README は、Jev の Choice が一度に最大255個の選択肢を扱えることを前提に、「ほとんどのステップに必要なのは計画ではなく、短いリストからの一つの選択だ」と設計の考え方を説明しています
真似できるところ:Jev を速く安く使うには、そのぶん state を作る側のコードに手間がかかる、という見積もりの仕方。
業務データに使う
17. smasato/jev-jp-address:日本の住所の正規化
TypeScript / 依存は ai と @ai-sdk/typesafe-ai だけ
日本郵便の郵便番号データ(KEN_ALL)をマスタにして、表記の揺れた住所を都道府県 → 市区町村 → 町域 → 番地・建物の順に正規化し、郵便番号を出す CLI です。Vercel の AI SDK(experimental_evaluate)経由で Jev を呼んでいます。
読みどころ:README の「処理フロー」と「Jev の判定を優先する仕組み」、src/pipeline.ts
- ルールとマスタ照合で確定できるところは、すべてコードで決めます。Jev に聞くのは、確定できなかった段だけです。正規化した文字列を組み立てるのも、常にコード側です
- 候補にはカタカナの読みを criteria の説明として付けています。こうするとひらがなで入力された住所の照合精度が上がる、と書かれています
- Jev の選択肢の上限(255)を超える町域は、類似度の上位200件で試し、外れたら全候補をチャンクに分けて評価します
- 二段階で聞き直すやり方も使えます。1周目は「該当なし」付きで聞き、確率が低ければ、「誤字や入れ替わりがある前提で、最も近いものを必ず選べ」という指示で上位30件から聞き直します。2周目の結果は、1周目より確率が高いときだけ採用します
- 欠落・誤字・入れ替わり・かな表記を自動で作って、ルールだけの場合と Jev ありの場合の正答率を比べるスクリプト(
scripts/robustness.ts)まで付いています
真似できるところ:「ルール → 候補を絞る → Jev に選ばせる → だめなら条件を変えて聞き直す」という段階的な設計。住所に限らず、マスタとの照合全般に使えます。
18. coo-quack/jev-pii-checker:三層で個人情報を探す
TypeScript / CLI
テキストから個人情報を探す CLI です。Jev だけに頼らず、三つの層を組み合わせています。
読みどころ:docs/how-it-works.md、src/gate.ts、src/extract/names.ts
- ゲート:人名、連絡先、住所、生年月日、公的 ID など13種類の有無を Noul で判定し、3段階の機微度も判定します
- 正規表現:メールアドレス、国内外の電話番号、10〜16桁の数字列を抜き出します。noreply@ や 0120- のような法人のものは除きます
- 分かち書き:
Intl.Segmenterで人名の候補を作り、Jev に判定させて、重なった範囲をまとめます - README の冒頭で「検査したテキストはすべて TypeSafe の API に送られる。ローカルで完結するガードではない」と明記しています。個人情報を扱うツールなので、これを最初に書いてあるのは親切です
真似できるところ:正規表現で取れるものは正規表現で取り、あいまいなもの(人名かどうか、クレジットカード番号かマイナンバーか注文番号か)だけを Jev に回す分担。
19. jerryjliu/docjev:PDF の分類と分割
Python / ライブラリ・CLI・ローカルアプリ
PDF、DOCX、PPTX を、自然言語で書いたカテゴリのルールで分類します。いくつもの書類を1つにまとめた束(パケット)を、元の書類ごとにページ範囲で分割することもできます。ページのテキストは LiteParse でローカルに抜き出し、判定を Jev が行います。
読みどころ:src/jev_docs/split.py、src/jev_docs/rules.py、ルールの YAML の例
- ルールは「安定した ID」と「書類の目的の説明」だけで書きます(例:請求書は「すでに提供した商品やサービスについて、売り手が支払いを求めるもの」)。形式の特徴ではなく、目的で定義しています
- 分割は、同じカテゴリの書類が隣り合っているときも別の書類として切り分けられるかを、実際の公開文書で確かめています。ベンチマークの結果と、誤りの分析(
error-analysis.md)まで公開されています
真似できるところ:カテゴリの説明を「見た目」ではなく「その書類が何のためにあるか」で書くこと。
手元で動かす
20. jaredpalmer/kev:同じ API で動くローカルの判定モデル
Python / Qwen3.5 ベースの 0.8B・4B・9B モデル
Jev に似た小さな判定モデルを、自分で学習して動かすためのリポジトリです。重み、学習コード、評価データがそろっています。
読みどころ:kev/serve.py、README の Quick Start、PLAN.md(研究ログ)
- ローカルサーバーは
/v1/systemoneという同じ形のエンドポイントで、Choice・Noul・Score を受け付けます。クライアントの接続先を切り替えるだけで試せます - README の例では、「配送の遅れ」「サイズ違い」「二重請求」が一度に書かれたチケットで、担当部署の Choice の確信度が低く出ています。論点が複数あるときに分布がどう割れるかを見るのにちょうどいい例です
- 選択肢の順番が答えにどう影響するかを確かめられるプレイグラウンドがあります
-
PLAN.mdは140KBを超える研究ログで、何を試してどうだったかがすべて残っています
真似できるところ:データを外に出せない案件で「同じインターフェースのまま手元に置く」という選択肢。
おまけ:設計の発想が面白い3本
gyu-don/jev-othello:state の書き方がよく分かる
Jev とオセロで対戦するアプリです。README の「Jev への渡し方」が実践的です。候補手のラベルは、事前学習で見ているはずの棋譜表記(f5、c4)にしています。盤面は座標付きで描画し、打てるマスに印を付けます。候補手の説明は、すべての候補で同じキー・同じ順序の JSON にしています(返す枚数、着手後の相手の合法手数、角を与えるかどうかなど)。序盤と終盤で指示文を切り替えるのも工夫です。API キーをブラウザに渡さずサーバーから呼び、1回の起動あたりの呼び出し回数に上限を付けています。
kentaro/whistle:音をテキストにしてから判定する
口笛で Mac のアプリやショートカットを呼び出すメニューバーアプリです。Jev は音を受け取れないので、ローカルで口笛の音程を抜き出し、「30msごとの時刻と相対半音」というタイムラインのテキストにしてから、登録した口笛のどれか、または「不明」に分類させています(Sources/WhistleCore/SignalProcessing.swift)。テキスト以外の入力を Jev に渡すときの考え方がよく分かります。接続先には TypeSafe に加えて、ロリポップ!AI ゲートウェイも選べます。
kyotofin/tax-doc-classifier:分類器の正体は「説明文の JSON」
米国の税務書類をページ単位で分類するツールです。分類器の実体は、261種類の様式の説明を並べた data/criteria.json と Jev だけで、学習は一切していません。評価は厳しめで、「答えが間違っている」か「確信度が0.95未満」のどちらかなら誤りとして数えます。確信度が低かったページがどういうものだったか(様式名の書かれていない説明ページなど)まで README で説明しています。
20本を読んで見えてきた共通点
最後に、複数のリポジトリで同じように出てきた設計の判断をまとめておきます。
-
ルールで決まることはコードで決める。住所の正規化も、個人情報の検出も、履歴の補完も、まずルールで決め、決まらないところだけ Jev に聞いています。公式 skill の「既知のルールはコードに残す」がそのまま実装されています。
-
「該当なし」を必ず選択肢に入れる。jevyoumean の
__none__、ddskk-jev の「どの候補も合わない」、住所の「該当なし」、whistle のunknown。選択肢にない答えは選べないので、逃げ道を用意しておかないと、Jev は無理に何かを選ばされます。 -
選択肢の上限(255)を超えたら分ける。候補を類似度で絞る(住所)、二段階の Choice にする(jevyoumean)、何段階かで絞り込む(jev-mcp)。どれも、上限に当たることを前提に最初から設計されています。
-
失敗したら元の挙動に戻る。ddskk-jev はタイムアウトしたら辞書の順序に戻し、失敗が続けば自分から止まります。redmine_jev は Jev に届かなければ何も表示しません。jevyoumean はスクリプトの中ではそのまま実行します。判定モデルは「あれば便利、なくても壊れない」位置に置くのが基本です。
-
何が外に送られるかを最初に書く。semgate の Authorization と Cookie、jev-semgrep の秘密ファイルのスキップ、ddskk-jev のバッファの内容、jev-pii-checker の冒頭の警告。判定のたびに state が外部 API に送られることを、作者たちは README の目立つ場所に書いています。
-
問いの定義としきい値の根拠をコードに残す。TrainLCD は本番と計測で同じ質問定義を共有し、しきい値の決め方をコメントに書いています。kojev や semgate は、モデルのバージョンを固定する方法を用意しています。
-
日本語で書くか、英語で書くか。ここは作者によって判断が分かれています。TrainLCD は、日本語の概念の輪郭を保つために、あえて日本語で書いています。ddskk-jev は、公式ドキュメントの「CJK は英語より精度が下がる」を根拠に、指示文の既定を英語にしています。jev-semgrep は、きわどいときは英語で書くほうが安全だと書いています。どれが正しいとは言い切れないので、自分のデータで両方試すのがいちばん確実です。
今回の20本は、私が運営している、X の公開投稿から「Jev で作ったもの」を毎日集めるフィード Jev Builds(jev.openchamber.dev)で、コードへのリンクが付いているものから選びました。「Code or demo」で絞り込むと、コードかデモのある作品だけが並びます。検索は意味ベースなので、「Redmine のチケットを分類したい」「シェルの補完に使いたい」のように、やりたいことを日本語で書けば近いリポジトリが見つかります。各カードは作者の元の投稿にリンクしています。