Distil

Distil は、コーディングエージェントのコンテキストツールに実際にかかるコストを測定します。
解決したタスクあたりの金額と、変化した判断の両面から、あらゆる圧縮ツール、プロバイダー独自のコンパクション、そして Distil 自身を測定します。

uv tool install distil-llm && distil setup

_{その他のインストール方法（curl、Homebrew、pipx、Windows）：お好みの方法でインストール}

distil wrap -- claude      # run your agent through distil (or let `distil setup` make it always-on)
distil savings             # what it saved you, from your own traffic
distil doctor              # if something looks off

distil audit --compressor anthropic-context-editing --cap-usd 1 # did it change what your agent does, and what it cost? (opt-in, capped)
distil audit report # helped, hurt, or can't tell yet, per compressor

Distil は圧縮も行います（デフォルトでは可逆圧縮で、すべてのバイトを復元できます）。そして、その圧縮ツールにも同じ測定基準を適用します。

現在の測定結果（2026-10-06。すべての数値から根拠となる成果物にリンクしています）

• 短いコーディングタスクでは、コスト削減を示す圧縮ツールはありません。 SWE-bench Lite の 298 タスクを同じモデルと評価器で測定したところ、Distil は圧縮なしと同等でした（解決したタスクあたり $0.0393 対 $0.0387）。RTK はタスクあたりのコストが 20.7% 安く見えましたが、その実行環境が他の実行環境のプロンプトキャッシュを読み取っていたことが判明しました。コールド実行として再計算すると −6.5%［−13.1%、+0.1%］で、有意差はありません。Selective Context と Anthropic のコンテキスト編集も安くはありません。Headroom はまだこのベンチマークを実施していません。スコアボード →
• 長時間セッション：結論は出ていません。 7 タスクの長期実行パイロット（中央値 63～69 ステップ）では、Distil と RTK のどちらにもコスト差は見られませんでした。実行がクラッシュした試行を除いた 6 タスクでは、Distil のコストは通常の実行より 9.7% 高くなりました。実行結果 →
• その理由。 プロバイダーの請求額を、未確認の実行でも 2.5% 以内の誤差で再現するオフラインシミュレーターによると、可逆圧縮のポリシーによるコストの変化は 0.2% 未満です。また、エージェントが削除された情報を補うために追加のステップを実行しない場合に限り、非可逆圧縮はコストを削減します。次は、これを実際の A/B テストで測定します。シミュレーター → · RTK が安く見えた理由 →
• メンテナー自身の従量課金制 Claude Code トラフィック（2026 年 9 月、13,191 リクエスト）では、キャッシュ料金を含め、Distil 自身の費用を差し引いたうえで、請求額を推定 8.3～9.2% 削減しました（ソース、手法）。これは同一軌跡に基づく推定です。エージェントが同じように動作したと仮定しており、まさにこれを上記の A/B テストで検証する必要があります。

測定結果を信頼できる理由

• プロンプトキャッシュを壊しません。 Distil は、プロバイダー側にキャッシュされているバイト列を書き換えません。古いコンテキストが変更されるのは、そのキャッシュがすでに期限切れになった後だけです。このバグは一度リリースしてしまいましたが、発生コストを測定し、ルールを強制される不変条件にしました。キャッシュの契約 →
• 圧縮されたバイトはすべて復元できます。 distil は折りたたんで省いた内容をローカルストアに保持し、エージェントはタスクの途中で元の内容を正確に取り戻すための distil_expand ツールを利用できます。ダイジェストの仕組み →
• 実際の請求額で測定し、領収書も含まれます。 節約額はリクエストごとに集計され、プロバイダーが実際に請求する usage に合わせて調整されます。各リクエストについて、検証可能なハッシュチェーン付き領収書が記録されます。同じハーネスですべての他の圧縮ツールも実行し、直接比較で自らの不備を見つけた際には、その修正結果を公開しました。測定方法 →

そして、悪影響が出ている場合はそれを知らせます。 シャドーモードでは、リクエストのサンプルを元のコンテキストと圧縮後のコンテキストで再生し、圧縮モードごとの差を報告します。ダイジェストの損害上限が予算を超えると、プロキシはロスレスのみのモードを維持します。同じチェックをプロバイダーに適用したところ、Anthropic によるコンテキストのクリアでは、古いツールの結果がすべてクリアされると（keep=0、合成コーパス）、40 件中 37 件でエージェントの次のアクションが変わることが判明しました（調査）。

_{さらに詳しく：distil がチェックする内容と、そのチェックをプロバイダー独自の圧縮に適用して判明したこと ↓}

機能

• コンテキストツールを評価する — distil audit は、自分のリクエストから上限付きのサンプルを再生し、名前付き圧縮ツール（distil、Anthropic のコンテキスト編集、OpenAI の圧縮、Headroom）がどのように整形するかを検証して、役立った／悪影響があった／まだ判断できない、という結果を請求額とエージェントの次のアクションの両方で報告します（ADR 0024）。オフラインでは、SWE-bench の結果評価ハーネスを使って、各方式のプロンプトキャッシュを分離したうえで、解決したタスクあたりの費用を評価できます。結果はスコアボードで確認できます。

• エージェントをラップする — 18 種類のプリセット：distil wrap -- <agent> で、aider · claude · codex · gemini · copilot · goose · grok · kilo · kimi · vibe · opencode · openhands · qwen · cline · cn · crush · droid · omp に対応します。設定不要で、コードの変更も必要ありません。distil wrap --list を実行すると、すべての対象、その仕組み、対応するプロバイダー形式が表示されます。

• プロキシとして実行 — 任意の base_url クライアントから接続できます。Python、TypeScript、あらゆる言語、あらゆるフレームワークに対応します。同期プロキシ、非同期プロキシ、スタンドアロンのゲートウェイのいずれでも、同じプロバイダーに対応しています。Anthropic Messages、OpenAI Chat Completions および Responses API、Azure OpenAI、Gemini generateContent をサポートします。

• ライブラリとして呼び出す — 独自のエージェントループで from distil import compress_messages を使います。

• エージェントにリコールツールを提供 — MCP サーバーが出力を自ら圧縮し、要求に応じて元のバイト列を正確に返します。

• フレームワークフック — LangChain · LangGraph · LiteLLM · Agno · Strands · AutoGen · LlamaIndex にインプロセスで対応し、ネットワークホップはありません。独自の LLM エンドポイントをホストするあらゆる Starlette/FastAPI アプリ向けの ASGI ミドルウェア、および Vercel AI SDK 向けの npm パッケージも利用できます。

• プロキシが到達できない場所でも — distil setup --hooks を使うと、Claude Code、Cursor（MCP 出力）、Gemini CLI、Codex CLI が、ドキュメント化されたポストツールフックを通じてツール出力を圧縮します。サブスクリプションでは可逆圧縮のみですが、--digest を追加すると、すべてのダイジェストを distil expand <handle> で復元できます。プロキシは不要で、認証情報にも触れません。distil quota で、節約できるレート制限枠を確認できます。フック →

• シェル出力を発生源で整形 — distil sh -- <command>（オプトイン、ADR 0026）を使うと、テスト実行や git status の失敗、エラー、要約の各行は一字一句そのまま保持され、成功したテストのノイズは distil expand ハンドルの背後にまとめられます。distil hook install --shell を使うと、Claude Code でこの機能が有効になります。SWE-bench Lite のトランスクリプトではテスト実行がまれなため、Bash 出力の削減率は 0.06%にとどまり、オプトインのままです。シェル →

• すべてのプロバイダーで同じ仕組み — 原文の再取得、コールドポイントの削除、編集引用ガード、センサスは、Anthropic Messages、OpenAI Chat および Responses、Gemini で動作します。OpenAI と Gemini は有料のため、節約額と distil audit で $0 として計上されることはありません。distil savings の仮定再生では、Claude Code に加えて Codex CLI と Gemini CLI のセッションも再生できます。パリティマトリクス →

• VS Code Copilot Chat — BYOK Custom Endpoint から distil プロキシに接続できます：distil setup --vscode。

• スパンを一字一句そのまま保持 — プロンプトまたはツール出力内の <distil:keep>…</distil:keep> は圧縮されません。

• MCP ツール検索を有効なまま維持 — distil wrap -- claude を使うと、Claude Code の MCP ツール検索が有効なままになります。Claude Code は通常、プロキシ経由ではこれを無効にするため、この設定により未使用のコネクターは保留されたままとなり、毎回のターンに含まれることはありません。1.54.0（2026-09-25）でライブ検証済み：すべてのリクエストで tools_deferred は 4～5、ツールペイロードは 9,733 トークンで、プロンプトキャッシュの読み取りも維持されます。(ADR 0013)

• 実際のコードスケルトン — pip install 'distil-llm[code]' を実行すると、Go、Rust、Java、C/C++、Ruby、TS/JS の tree-sitter パーサーが追加されます。コードスケルトン →

• 処理内容を確認 — ライブステータス行、セッションの詳細分析、リクエストごとのヘッダー、OTel スパン、Prometheus メトリクスを利用できます。

uv tool install distil-llm && distil setup    # detects your agent + billing, wires everything

どの機能を選べばよいかわからない場合は？ 2つの質問に答えるだけでモードを選べます → — 平易な言葉で、現実的な節約率の範囲を提示し、専門用語は使いません。

_{◉  リアルタイム · 公開 git ブランチ上のオプトイン方式の利用状況調査に基づく実測値であり、推定値ではありません}

▶  カウンターのリアルタイム更新を確認し、すべての数値を検証する →

使い方 · ライブラリ · インテグレーション · インストール · 信頼できる理由 · ドキュメント全文 → · llms.txt

_{AI エージェント向け：/docs/llms.txtを参照してください。distil の概要と呼び出し方法を簡潔にまとめた、機械処理向けの要約です。}

🧩 ライブラリとして使う

エージェントを自分で構築していますか？プロキシもネットワーク経由の中継も不要です。メッセージリストがある場所で圧縮できます。

from distil import compress_messages, expand_handle

result = compress_messages(messages)          # OpenAI/Anthropic-style dicts
print(f"{result.saved_pct:.1f}% smaller")
response = client.messages.create(model=..., messages=result.messages)

original = expand_handle(result.handles[0])   # byte-exact, any time, any process

ツールの結果には可逆ダイジェストが適用されます。ユーザーおよびシステムのテキストには可逆性を損なわない変換のみが適用され、モデル自身のターンが書き換えられることはありません。ハンドルはプロセスをまたいで、また再起動後も解決できるため、プロキシで作成したダイジェストをここで展開でき、その逆も可能です。verbatim=True にすると、ダイジェストが完全に無効になります。

_{compress／expand ではなく compress_messages／expand_handle という名前にしているのは、distil.compress と distil.expand がモジュールだからです。トップレベルのエクスポートに同じ名前を付けると、無関係なインポート順序によって関数またはモジュールのどちらに解決されるかが変わってしまいます。}

TypeScript にも対応しています。npm パッケージの compress(messages) は、Python エンジンとバイト単位で同一です。完全なリファレンス：ライブラリ API → · 実行可能なサンプル：python_library.py · js_library.ts。

フレームワークを保守していますか？ docs/INTEGRATING.mdには約20行と4つのルールが記載されています。私たちのリポジトリではなく、あなたのリポジトリに統合を組み込んでいただくことを望んでいます。

🔬 distil が検証すること、そして検証で明らかになったこと

エージェントのコンテキストが、何者かによって書き換えられています。
Distil は、その代償を測定します。

プロバイダーはデフォルトで、古いツールの結果を消去したり、履歴を要約したりして、コンテキストウィンドウをサーバー側で自動的に編集するようになりました。変更内容は報告されません。
Distil は、最も重要な問いに答えるための計測ツールです。エージェントはそれでも同じ動作をしたのか？

Distil は、エージェントが各ターンで再送するツール出力、ログ、履歴も可逆的に圧縮します。圧縮自体の証明書、敵対的検証のゲート、そして表示を拒否できる数値を備えた、唯一のコンテキスト操作です。

60秒でわかる概要

検証できない圧縮は、エージェントの動作に関する憶測にすぎません。
Distil は、あらゆる部分を検証可能にし、その検証結果が「いいえ」になることも許容するよう設計されています。

証明と来歴

上記の主張はすべて検証可能です。リリースを提供したサプライチェーンも同様です。リリースにはPEP 740のアテステーションが含まれているため、侵害されたノートPCではなく、このリポジトリのCIからビルドされたことを検証できます。すべてのリリースにはCycloneDX SBOMが付属し、内容を確認できます。また、リポジトリ自体に対してOpenSSF Scorecardを毎週実行しています。敵対的な入力への対応経路は、前提とするのではなく文書化しています。対象範囲と対象外の内容については、脅威モデルとセキュリティホワイトペーパーを参照してください。信頼してデプロイで使用する前に、distil validateを実行して、悪意のある入力に対するデプロイを検証できます。

信頼できる理由 📊

SWE-bench Liteでは、リリース版の処理経路はコスト中立で、タスク成功率の差は約2ポイント以内です（n=300では統計的に有意な差はありません）。

_{シェル検索の修正後に2回実行した結果です。distil-served と通常の Claude を比較すると、204/299 対 210/299（−2.0ポイント、95％ CI −5.5～+1.5、コストは $7.18 対 $7.18）、および 213/298 対 218/298（−1.7ポイント、95％ CI −5.1～+1.7、コストは $8.44 対 $8.52）でした。事前登録した5ポイントのマージンでの非劣性は示されていません。長時間セッションのパイロット（7タスク）は結論が出ていません。他のすべての圧縮ツールも、同じ方法でスコアボードに評価結果が掲載されています。レポート：低負荷 · 中負荷。}

_{研究用設定（E8～E14、SWE-bench Verified）は研究ページに掲載されています。これらは出荷版の経路ではなく、ここでは出荷版の結果として引用していません。}

Distil を選ぶ理由 — 形容詞ではなく、特性

_{Headroom の列は、公開されているheadroom-ai 0.37.0 のソースを直接確認したものです。v0.37.0、2026-09-04 時点で、各項目には同リリースのfile:lineを引用しています。形容詞ではなく事実を示し、実際に優れている点はそのように述べています。}

_{オフラインでのトークン削減量であり、コストやタスク成功率の結果ではありません。同一コーパスで、Headroom のモデルを事前ロードして 2026-09-04 に再実行：distil はトークン 52.9% / $ 58.7% / 判断同等性 100% / PASS、対してHeadroom は 1.7% / 2.0% / 81% / FAILでした。読み取り→編集→再読み取りのコーディングワークロードでは、Headroom はトークン削減率 35.6% を達成しますが、distil のダイジェストは仕様上0.0%です。これは正確な引用保証のために払う代償であり、生の出力をコミットした両方の数値を1ページで確認できます。}

🚀 今すぐ使う

4 つのコマンドです。 distil --help にはこれらだけが表示されます。残りは distil --help-all で確認できます。

uvx --from distil-llm distil savings   # what your agent costs you now — no install, read-only
uv tool install distil-llm
distil setup                           # detects your agent + billing, wires the status line, tells you what's next
distil wrap -- claude                  # run your agent through distil
distil savings                         # spent, saved, daily graph, what to fix next
distil doctor                          # if anything looks wrong

distil setup は環境を検出します（Claude Code・Codex・Gemini CLI、従量課金かサブスクリプションか）。または、エージェントを直接ラップできます — 設定不要、コード変更不要です。

# Claude Code on a metered API key — saves real $$:
distil wrap --expand -- claude

# Claude Code on a Pro/Max subscription — flat-rate, ToS-safe (trims context, not $):
distil wrap --lossless-only -- claude

# Codex, Gemini CLI, aider — same pattern; env var auto-selected per agent:
distil wrap --expand -- codex     # → OPENAI_BASE_URL (routing unverified: codex-rs reads openai_base_url from its config)
distil wrap --expand -- gemini    # → GOOGLE_GEMINI_BASE_URL
distil wrap --expand -- aider     # → OPENAI_API_BASE
distil wrap --list                # every target, its mechanism, and the agents it can't reach

# Headless too — print mode, CI, and Agent SDK scripts route the same way:
distil wrap -- claude -p "summarise this diff"
distil wrap -- python my_agent_sdk_script.py

Cursor、Cline エディター拡張機能、Windsurf、Zed、Warp、Amp をお使いですか？（Cline CLI は別物です — distil wrap -- cline で実行できます。）これらはどれも、distil wrap で設定できるベース URL の仕様を公開していません — そのような設定項目自体がないものもあれば、構造上 localhost を指定できないものもあります（Warp はエージェントを独自のサーバーで実行し、プライベートアドレスを拒否します）。プロキシを実行し、ツール独自の設定でそのプロキシを指定してください。docs/IDE-AGENTS.md には、それぞれについて、主張の確認に使用したページと日付を記載しています。VS Code の Copilot 拡張機能 はリダイレクトできません。このページには、その事実が明記されているので、午後を無駄にせずに済みます — GitHub Copilot CLI は別のツールで、wrap で実行できます。

認識されたエージェントごとに適切な環境変数と上流が自動選択されます。--env-var や --upstream フラグは不要です。13 個は環境変数経由でルーティングされます（aider / claude / codex / gemini / copilot / goose / grok / kilo / kimi / vibe / opencode / openhands / qwen）。5 個は環境変数の仕様がなく、wrap がセッション中に管理し、終了時に元に戻す設定ファイル経由でルーティングされます（cline / cn / crush / droid / omp）。起動時に preset: <agent> detected → <VAR> と表示されます。明示的に指定したフラグが常に優先されます。

distil default            # adds a managed shell alias so `claude` always routes through distil
distil default --undo     # remove it anytime (backed up before any change)

次に、あなたのトラフィックから実際の節約額を確認しましょう — 推定ではなく、実測です。

distil savings              # billed spend vs saved, daily graph, top fixes (--since 7d / --all / --json)
distil leaderboard          # cumulative tokens + $ saved, from the local ledger
distil dashboard            # live terminal TUI — token-trim + decision-equiv bars, Ctrl-C to exit
distil dissect             # per-session deep-dive: savings, digest inventory, anomalies (--html/--serve)

実際のトラフィックで検証してください。 --shadow は一部のリクエストを 2 回実行し（圧縮版と完全版）、エージェントが次に選択したアクションを比較します。

distil wrap --shadow 0.1 -- claude   # wrap + shadow 10% of requests
distil shadow-stats                  # live decision-equivalence rate

適用範囲には注意が必要です。これは次のアクションの同等性であり、タスクの成功ではなくプロキシです（E7 では、積極的な損失あり圧縮では完全には引き継がれないことを示しています）。Distil は安全側に倒し、コンテキスト全体を使用します。

料金は節約できますか？ 従量課金（API キー）の場合、トークン数が減少します。メンテナーのトラフィックでは請求額の約 9% を節約できました。短い SWE-bench タスクでは、実測上の純コストへの影響はありませんでした。長時間セッションのパイロット（7 タスク）では結論が出ておらず、損失あり圧縮が有効かどうかは、エージェントが追加のステップを実行するかどうかに左右されます。これは次のライブ A/B テストで測定します。定額のサブスクリプションではトークンごとの請求がないため、節約できるのはレート制限の余裕です。1 ターンあたりのトークン数が減れば、上限に達するまでにより多くのターンを実行できます（distil quota でリアルタイムに確認できます）。

💡 Distil が他と違う理由

バイト単位の同等性は必要ありません。必要なのは意思決定の同等性です。つまり、コンテキストを圧縮しても、エージェントが同じアクションを取ることです。これは測定可能であり、認証も可能です。

• 前提ではなく、ゲートで制御 — 情報損失のあるモードを提供するのは、リクエストごとの意思決定変更チェックが予算内に収まる場合のみです。それを示せない場合は、完全なコンテキストを使います。タスクレベルの非劣性は、まだ示されていません（SWE-bench Lite：−1.7 ポイント、95% CI −5.1..+1.7）。
• 害も報告できる推定量 — ライブチェックは、ブートストラップによる 95% CI を持ち、ゼロで下限を切り上げない、ペア統計量 1{A=B} − 1{A=A'} です。従来の比率推定量は、偶然が有利に働くと常に正確に 100% と表示され、害をまったく表現できませんでした。報告下限がひとつ設けられ、ステータス行、証明台帳、shadow-stats、センサスフィード、公開ダッシュボードのすべてで共通して適用されます。見栄えのよい数値ではなく、報告下限未満と表示します。
• 引用がバイト単位で正確に保持されるため、Edit が引き続き適用可能 — Edit(old_string=…) は、エージェントが以前に読み取ったバイト列とのリテラル一致です。その読み取り内容をダイジェスト化すると、エージェントが成功を報告していても、編集は何もせずに終わります。来歴はツール名だけでなく、シェルコマンド（cat、head、sed -n）から読み取ります。これはツール名ルールでは対象にならなかった**ツール結果の 33.6%**に相当します。節約効果は低下しますが、それを隠さず、変更履歴に記載しています。
• 敵対的入力にもゲートを設け、2つの問題も正直に報告 — distil validate --adversarial は、プロキシが使うものと同じ公開経路で、COMA クラスの 7 ケースを実行します。信頼済みブロックと信頼されていないブロックの予算分離は構造的に保証されています。どこにもブロック間で共有される保持予算は存在せず、CI で等式として検証されています。問題を取り繕わずに公表する結果が2つあります。重複排除を誘発する攻撃では、本物のエラー行も実際に折りたたまれます（それを救うのは可逆性です）。また、偽の判定結果を大量に流し込む攻撃は、実際に発生する、緩和策のない節約の妨害です。このブロックでの節約率は 0.0% です。
• デフォルトだけでなく、設定範囲全体を測定 — distil bench --curve は、オフラインかつ無料で、各段階の節約率、事実の再現率、表示内容の再現率、失われた事実、可逆性を報告します。
• 自分で実行できるタスクレベルの上限 — distil certify-trajectories は、対応する評価結果に基づいて、圧縮によって解けなくなるタスク数の上限を算出します。私たちの SWE-bench 実行結果では、その上限はまだ 5 ポイントのマージンをクリアしていません。
• 情報損失ではなく、可逆 — ハンドルの背後にダイジェストを保持し、元の内容も残して、エージェントに distil_expand ツールを提供します。安心して圧縮できます。
• 答えを残し、ノイズを折りたたむ — コンテンツタイプごとの保持ポリシーにより、各タイプの重要な行（ログの合否判定、トレースバックのフレーム、差分のハンクヘッダー）を固定します。ほぼ同一のエラーの繰り返しは重複排除し、実行が成功した場合は、そうしたノイズが失敗の原因ではなかったため、重複排除をさらに強化します。
• クエリを考慮し、実際に尋ねられた行を保持 — distil はプロキシなので、出力と同じリクエスト内でエージェントの意図（tool_use の引数と最新の質問）を確認できます。検索した内容に一致する行（grep のヒット、設定値、SHA）は、任意の出力でも固定されます。これは追加的な処理なので、可逆性と証明書には影響しません。事後的なコンプレッサーには、このようなクエリと出力の組み合わせを利用できません。さらに、常時有効な意味処理も行います。依存関係ゼロのブリッジ（形態素解析、厳選した技術用語の同義語マップ、文字トライグラムによるあいまい一致）が、クエリと単語を共有していなくても、クエリへの回答となる行を固定します。「再試行上限は？」と尋ねると max_attempts = 5 が残り、「接続タイムアウトは？」と尋ねると deadline_ms が残ります。さらに、同梱されたデータではなく、ユーザー自身のトラフィックから2つのレイヤーが成長します。1つは、内容を保持しない expand フライホイール（ハッシュ化されたペア、--expand セッション）から distil が学習する関連付けです。もう1つは、ユーザーのラベルを使った保留データで、語彙ベースラインを上回る再現率を確認してから昇格する学習済み関連度モデルです。昇格までは、語彙レイヤーとブリッジレイヤーだけが実行されます。オプションで分布表現ベクトルのテーブルも指定できます（純粋な Python によるコサイン類似度。標準では同梱されません）。すべてのレイヤーは追加的に機能し、保持範囲を広げるだけなので、可逆性と証明書に影響しません。また、動作に埋め込みもモデルも必要ありません。
• 定額制プランでもロスレス — サブスクリプション／ロスレスモードは、単にそのまま出力するだけではありません。JSON を最小化し、重複した連続データをまとめ、表形式のツール出力を自己記述型のコンパクトなテーブルに折りたたみます（ToS に準拠し、情報損失のあるダイジェストは使いません）。最近のツール出力はバイト単位で正確に保持されます。その効果の大きさは明確にしておきます。ロスレスの節約効果はデータの形状によって異なり、distil 自身の評価用コーパス（JSON なし、重複行なし）では、節約率は**0.00%**です（E15b）。
• 何が起きたかを正確に確認 — distil dissect は、ラップセッションをレポートにまとめます。モデル／メカニズムごとの節約量、ダイジェストの一覧、課金対象使用量の較正、経路ごとのレイテンシ、そしてサイレント障害を自動検出する要注意の異常一覧を確認できます。
• 結果から学習し、効果を積み重ねる — 展開と対応する失敗から、保護すべきものをポリシーに学習させます（シグネチャのみで、内容は保持しません）。常により保守的になります。
• 再読み込みでは、読み直した分ではなく変更分がコストになる — コーディングエージェントは同じファイルを何度も読み込みます（測定した 2,489 セッションでは読み取りの 51.4%）。そのほとんどで、読み取り位置は同じではないため、ブロック単位の重複排除では見逃します。Distil は行単位で照合します。新たに読み取った内容と以前の読み取り内容で重複する部分がまだコンテキスト内にあれば、可逆参照に置き換え、それ以外はすべてバイト単位で正確に保ちます。最も新しい読み取りには手を加えません。これは正確な引用を保証する仕組みの内部で動作するため、distil がそのまま保持すると約束した内容から節約効果を取り戻す唯一の変換です。また、Edit の old_string は転送されたペイロードのどこかにバイト単位で正確に存在すればよいため、安全です。→ ADR 0010
• そこにないかのようにストリーミング — SSE はチャンク単位で中継し、TTFT を維持します。これは復元可能なダイジェストも同様です。推測的にストリーミングし、ストリーム中に実際の distil_expand 呼び出しがあった場合だけ横取りして、ターン全体をバッファリングせずに復元内容を差し込みます（可逆ティアで TTFT の増加はありません）。

忠実度の段階： ロスレス（--verbatim）・可逆（オンデマンドでバイト単位の復元が可能 — デフォルト）・ロッシー（その他すべてのツール）。Distil の可逆段階には、リクエストごとの判断変更チェックというゲートがあり、復元はエージェント向けです。つまり、モデルはタスクの途中で展開します（Headroom は、このようなゲートなしで取得機能を提供します）。どちらも、タスクの成果を維持したままコストを削減できることは示されていません。

⚡ API キーなしで数値をご自身で検証

上の表を鵜呑みにしないでください。distil bench は、8 ドメインのコーパスを同梱しており、オフラインで数秒のうちに、削減効果と判断の同等性を再検証します。これは CI で実行されるものと同じゲートです。評価方法と、タスクの成功率の差を伴わない圧縮率に意味がない理由は、私たち自身の否定的な結果も含めて、docs/EVALUATION.md にまとめています。

uvx --from distil-llm distil bench      # certify savings + quality across 9 domains, in seconds
distil verify                           # byte-fidelity: every compression is exactly reversible
distil validate                         # adversarial real-path gate: invariants on hostile inputs
distil retention                        # fact recall: what stays visible vs expand-recoverable
distil retention --dataset hotpotqa     # graded against a PUBLIC benchmark's ground truth
distil fidelity                         # state probes: artifact state, overclaim, continuation

CI には 5 つのゲートがあります。bench（コーパスでの非劣性）、verify（バイト単位の忠実性）、retention（事実レベルの想起）、fidelity（以下に示す状態プローブ）、そして validate — 圧縮器に敵対的な入力（巨大データ／Unicode／ネスト／不正形式／マーカーインジェクション／秘密情報に見えるデータ）を与え、可逆性、サイズが増える場合の拒否、最新情報の厳密な維持、フェイルオープン、内容を含まないテレメトリーが、どのケースでも保たれることを検証します。この最後のゲートがあるのは、ユニットテストがすべて成功していても、実際のトラフィックでのバグが残り続けていたためです。validate は、それらを検出する敵対的テスト層です。

想起だけでは不十分です。その理由を示すのが、次のケースです。 ある軌跡で、ターン 2 に net/scratch_bench.py が作成され、ターン 4 に削除されます。ターン 4 を圧縮で取り除いても、すべてのパスのトークンは残るため、文字列の想起率は 100% です。しかし、エージェントは実際には存在しないファイルがあると信じ、それを前提に計画を立ててしまいます。distil fidelity はツール呼び出しをファイル状態の台帳にまとめ、最終状態を評価します。これにより、lost（パスが失われている — エージェントは欠落に気づけます）と stale（パスは残っているが状態が誤っている — エージェントは誤情報を信じて自信を持って行動します）を区別します。このケースでは、文字列の想起率は 100% ですが、状態の忠実度は 0% です。 recall では確認できないことも、さらに3つ報告します。過剰な断定（"approximately 4200 ms" → "4200 ms" — 値は残りますが、不確実性は残りません）、継続性（エージェントは、残っている作業をまだ把握しているでしょうか？）、エラーの伝播（ターン k での損失は、ターン k+n での振る舞いの変化として現れるでしょうか？）。ゲートの対象はサイレントな失敗だけです — CI は --max-silent 15 を実行します — なぜなら、明白な損失はすでに retention --max-lost の役割であり、1つのリグレッションを二重にゲートすると、どの特性が壊れたのか分からなくなるためです。上限はゼロではなく、測定された値です。Tier-1 ダイジェストは、復元ハンドルの背後にある曖昧な表現を含むスパンをまとめ、171件の主張のうち9件で修飾語を落とします。そのため、ゼロを上限にすると、コンプレッサーが備えていない特性を備えていると主張することになります。さらに、distil suite は12個の公開ベンチマークを評価します。これらの正解データは、私たち以外の誰かが作成したものです。そこにはBFCLも含まれます。これはツールスキーマを圧縮し、正解の呼び出しに必要なすべての名前 — 関数と各引数 — が残っているかを確認します。**91.4%**の削減率でも、distil は正解の呼び出しに必要なすべての名前を保持します（生データ） — ただし、目に見える形では1つもありません。スキーマは復元ハンドルの背後にあり、distil_expand を1回実行すれば取り出せます。見栄えのよい数値だけでなく、その隔たり（visible → true support: bfcl 0%→100%）もスイートに表示します。モデルが実際にはスキーマを展開しなければならないのに、見えていると読者に思わせるのは、個々には正しい数値によって誤解させることになるためです。名前は文章ではなく、識別子として照合します — 引用符で囲まれた JSON トークンを対象とし、エスケープは許容します。汎用マッチャーでは、誤って正解85件中11件を加点していました（'a' が "tool-schemas" の中で一致）。BFCL が実際に a、b、c と名指しする正解15件は除外し、件数を記録します。1文字のトークンは、正直に加点することも不正解とすることもできないためです。ベンチマークに圧縮対象がなければ、それは根拠ではなく対照群であるため、各行にはペイロードが rich か thin かを表示します。対照群だけを評価する実行は終了コード1で終了します。API キーも費用も不要なので、リリース前の実行ではなく、make gate と CI のゲートジョブに組み込んであります。これらのプローブで私たち自身のコーパスの何が問題だと分かったのかを含む全手法についてはdocs/EVALUATION.md §6を、すべての実行方法についてはdocs/RUNNING-EVALS.mdを参照してください。

Recall と、自分で確かめられる数値。 上記の3つのゲートは、私たちのコーパスを私たちのオラクルと照合して評価します。厳密ではありますが、あなた自身で確かめることはできません。distil retention --dataset hotpotqa は、別の作成者による正解データ（8つの紛らわしい段落に含まれる HotpotQA の正解根拠文）と照合して評価し、同じケースで distil と同じ削減率になるよう調整した切り捨てベースラインも併せて示します。

distil retention は、再現率を可視（モデルの前に表示されているもの）と復元可能（distil_expand を1回実行すれば取り出せ、ハンドルの復元用バイト列と照合して検証済みのもの）にも分けて示します。コーパスでは、真の再現率は100%で損失は0です。また、損失ありではなく可逆であることによる再現率の差は**23.1%**です。これは全9ドメインの平均で、各ドメインを1回ずつ数えています（生データ）。これは意図的にマクロ平均を使っています。事実数で加重した平均は62.3%ですが、プローブ数が最も多いドメインによって左右され、ある HTML フィクスチャは、コンプレッサーにまったく変更がないにもかかわらず、かつてその値を50ポイント以上動かしました。これが、主張ではなく測定値としての堀です。distil retention --live を実行すれば、独自のトラフィックについても同じ数値を確認できます。メーターが保存するのは件数だけで、コンテンツは保存しません。 そして、実際の弱点が見つかりました。 リコールハーネスが最初に検出したのはリグレッションではなく、機能の不足でした。distil は HTML ツールの結果を 0.0% しか圧縮できていませんでした。最小化されたマークアップは1行に収まっているため、行の折りたたみでは何も折りたためなかったのです。フェッチやブラウザーのツールを使うエージェントは、<script>、<style>、ナビゲーションの表示要素に対して、全量分のコストを払っていました。今では、Wikipedia の記事と Python のドキュメントページは、0 件の事実も失わずにサイズの大部分を削減できます。（2つのページで測定しました。この実行結果はコミットされていないため、削減率は記載していません。）

可逆であることは、損失のある抽出では実現できない利点です。元の内容は正確な形のままハンドルの背後に保持されるため、不適切なヒューリスティック判定があっても、内容を失う代わりに distil_expand を1回実行するだけで済みます。

各レイヤーで何が検証されるのかを正確に説明します。コミットごとのゲートでは、コミット済みのコーパスに対するオフラインの決定論的オラクルを使って、判断の同等性を評価します（高速で無料、プッシュのたびに実行されますが、合成データです）。毎晩の live-cert ジョブでは、同じ軌跡を実際のモデルで再認証します（distil certify --runner anthropic）。予算に上限を設け、--max-live-calls で厳格な上限を設定しているため、無人実行で気付かないうちに費用が発生することはありません。上記の実測結果（SWE-bench n=500、ライブの直接比較 n=200）は実際のモデルで評価したものであり、コミットごとのバッジだけでそれを主張しているわけではありません。

ライブ実行の評価モデル。 1.56.0 以降、ライブ認証のデフォルトモデルは claude-sonnet-5-5、effort=low です（--effort は certify、eval、benchmark、frontier、conformal のフラグです）。このモデルは、実際の τ-bench トラフィックを使った事前登録済みのペア比較モデル移行評価で選定されました。claude-opus-4-8 に対する品質の下限が少なくとも −5 ポイントという条件を含むすべてのゲートを、1ケースあたりのコストを57.5%削減したうえでクリアしています。上記の以前のライブ結果は claude-opus-4-8 で評価されており、引き続きそのモデル名を付記しています。

ライブ認証モデルの選択と移行。 評価モデル自体も変数であるため、モデルの変更は単なるフラグの切り替えではなく、測定に基づいて判断します。実行ごとに --model でモデルを指定し（certify で指定すると、--runner anthropic の場合に軌跡のモデルを上書きします）、--effort low|medium|high|xhigh|max を設定します。デフォルトは claude-sonnet-5-5 の low です。新しいモデルを現行モデルと比較して適格性を確認するには、同じケースを実行し、保留したターンに対するペア比較を行います。

python benchmarks/model_migration_eval.py --fetch-tau-bench      # pinned, sha256-verified real traces
python benchmarks/model_migration_eval.py --cases real --flow .claude/hillclimb/decision-equivalence-real \
    --variant baseline --model claude-opus-4-8 --reps 4          # incumbent
python benchmarks/model_migration_eval.py --cases real --flow .claude/hillclimb/decision-equivalence-real \
    --variant v5 --model <new-model> --effort low --reps 4       # candidate
python benchmarks/model_migration_eval.py --status               # cross-variant table
python benchmarks/model_migration_summary.py                     # paired CIs -> benchmarks/results/model-migration/summary.json

ライブ実行には費用がかかります。まずオフラインで配線を確認するには、--fake oracle を追加してください。ゲート、表、その他のコマンドについては、モデル移行（docs/ab.html#model-migration）を参照してください。判断の記録：ADR 0020（デフォルトの認証モデル）とADR 0021（提供経路の認証）。 コーディング時のトラフィックに残るリスク。 認定済みの distil 戦略は最新のツール出力だけを要約し、実際の SWE-agent の軌跡でトークンを 2.6% 節約します。一方、サービングアダプターはそれ以前のツール出力をすべて要約して 52.6% 節約するため、サーブされるバイトの大半は認定されていませんでした。distil certify --strategy served は実際のアダプターを評価するようになりましたが、最初の結果は合格ではありません。リカバリーを行った場合、保留されたコーディング判断の 78.0% で次のアクションを維持します。圧縮していない同一の呼び出しを 2 回行った場合は 94.1% です。これがタスクの解決率に影響するかを調べるのが、SWE-bench の成果評価（仕様、benchmarks/swebench_outcome/）です。SWE-bench Lite の全 300 タスク（レポート）で、両エージェントがプロンプトキャッシュを使用した場合、distil をサーブしたエージェントはペアとなる 299 タスクのうち 201 件を解決し、通常のエージェントは 210 件を解決しました。差は −3.0 ポイント（95% CI −6.4〜+0.4、McNemar p = 0.12）です。これは事前登録された 5 ポイントのマージンで非劣性を示すものではなく、僅差で合格していた先行の 100 タスク実行結果に取って代わるものです。サービングではコストも 12.4% 増加し、ステップ数も 29.9% 増加しました。圧縮をオフラインで再生すると、その理由が分かります。distil はエージェントのシェル grep 出力の大半、つまり各情報の場所を示すマップを要約していました。そのためエージェントは distil_expand を呼び出さず、再度検索して読み直していました。distil はすでに Grep ツールの出力をそのまま保持していましたが、bash 経由で同じ検索を行った場合は保持していませんでした。今回、両方を保持するようになりました。この修正を適用して distil 側を再実行した結果（レポート）、ペナルティは解消されました。通常版に対するステップ数の増加は +29.9% から +3.1% に減り、コストは同等になりました。ただし、タスクの成功率は依然として示されていません。299 件中 204 件に対し通常版は 210 件で、差は −2.0 ポイント（95% CI −5.5〜+1.5）となり、マージンをわずかに下回っています。より高い労力設定での 2 回目の実行（レポート）も同じ傾向を示しています。コーディングエージェントでのサーブ経路はコスト中立と見なし、タスク成功についてはまだ実証されていないものとして扱ってください。長時間セッションについては、7 タスクのパイロットでは結論が出ていません（実行結果）。手法、表、再実行コマンドについてはModel Migrationを、使用したすべてのデータセットとそのソースおよびバージョン固定についてはEVALUATION.md §6.9を参照してください。

domain            trajectory                $ saved   distil   aggr  pruned
---------------------------------------------------------------------------
ops/sre           sre-disk-incident           32.8%     PASS   FAIL     615
coding            coding-bugfix               25.5%     PASS   FAIL     736
support           support-refund              32.6%     PASS   FAIL     765
research          research-synthesis          25.7%     PASS   FAIL     809
data-analysis     data-analysis-sql           18.1%     PASS   FAIL     965
devops            devops-rollback             22.8%     PASS   FAIL     857
finance           finance-reconcile           24.9%     PASS   FAIL    1014
web-research      web-research                89.8%     PASS   FAIL     428
agent-worklog     agent-worklog               35.3%     PASS   FAIL     891
---------------------------------------------------------------------------
aggregate: distil cuts $0.24052 -> $0.12400 (48.4% cheaper) reversibly; 7080 tokens causally prunable.
GATE: PASS — every trajectory certified non-inferior; aggressive rejected on all.

この数値を信頼できる理由は？ トークン削減率の数値は簡単に偽装できます。圧縮率が低いときに品質を測定し、圧縮率が高いときの削減率を宣伝すればよいのです。Distil はそれを許しません。精度と圧縮率は同じ軌跡で測定され、非劣性に合格できない戦略はリリースされません。

distil certify --strategy distil       # 判定：合格  （判断の一致率 100%）
distil certify --strategy aggressive   # 判定：不合格  （平均差 −1.0、ブロック）

distil eval は認定済み圧縮フロンティアをプロットします。各点に認定判定が付いた、削減率と品質の曲線です。非可逆圧縮によって判断が変わる境界を特定できます。競合他社が公開していない成果物はこちらです：benchmark.html。

📊 実証結果

再現可能で、留意事項も含めてすべて公開している3つの結果です。

• 合成コーパスでの直接比較：実際の llmlingua ／ headroom-ai と比較（benchmarks/gen_realworld.py で生成したシード固定の120ターンコーパスを claude-opus-4-8 で評価。2026-07-05、distil 1.10.1 対 llmlingua 0.2.2 および headroom-ai 0.27.0）：判断の変更なしで83.2％削減、約1,000倍高速（競合製品ではローカルのTransformer推論モデルを読み込むのに対し、こちらはMLモデルを読み込みません）。ライブプロキシの動作は tests/test_live_certified_equivalence.py によって、認定済みの戦略と一致するよう固定されています。レビュー済みの唯一の差分は、最も新しいツール結果のターンをそのまま保持する鮮度に関する例外です（エージェントには、最新の出力がバイト単位で正確に必要です）。1.45以降、この例外はプロバイダー側でキャッシュされていないコンテンツにのみ適用されます。クライアントの cache_control のブレークポイントを基準とし、暗黙的にキャッシュするプロバイダーでは例外を完全に無効化します。会話の末尾から数えた例外は、会話が長くなるにつれて前方にずれていました。その結果、1ターン後にすでにキャッシュされたコンテンツを書き換え、ダイジェストで削減できた分を上回る再請求対象のプレフィックスが発生していました。→ ベンチマーク

• E7（SWE-bench Verified）： 積極的な非可逆圧縮ではタスク成功率が大幅に低下します（52％ → 16％）。ステップごとの証明書は複数ターンには引き継がれません。一方、可逆の層は維持されます（56％対52％）。これが事実であるため公開しています。→ E7

• SWE-bench Lite、提供中の経路（n=300、2回実施）： コストは同等で、タスク成功率も約2ポイント以内です（−2.0ポイント、95％ CI −5.5..+1.5、−1.7ポイント、95％ CI −5.1..+1.7）。統計的に区別できず、5ポイントのマージンでの非劣性も示されていません。→ レポート。研究用の構成（E8〜E14、SWE-bench Verified）は研究ページに掲載されており、提供中の経路ではありません。

• 他のコンプレッサーとの直接比較（SWE-bench Lite、298タスク、長期パイロット、7タスク）： 成功率はスコアボードに掲載しています。この実行で共通プロンプトキャッシュによる交絡要因を取り除いた後、成功率で非劣性が示されたのはRTKのみであり、コストが低いと示されたアームはありません（タスクあたりRTK −6.5％［−13.1％、+0.1％］、有意差なし）。長期パイロットではコスト差は確認されていません。→ コストの交絡要因 · 理由

手法の全容、McNemar検定、インスタンスごとのデータ：docs/PAPER.md · PDF。

📡 動作を確認する

お客様のトラフィックで測定し、推定は行いません。お客様のマシンからデータが外部に送信されることもありません。

• リクエストごと： x-distil-* レスポンスヘッダー（tokens-saved、mode、compressible-tokens、expanded）。
• マシンごと： distil leaderboard（ページを表示するには --html を指定）。
• シャドーモード： distil proxy --shadow 0.05 で、ストリーミングを考慮した実際の判断変更率をレポートします。
• まだ削減できるコスト： distil discover は最近のセッションを集計し、現在もコストが発生している項目を順位付けします。リクエストのたびに再送されるツール／MCP の定義、定義が毎ターン送信されているのに一度も呼び出されていない MCP サーバー、ダイジェスト階層に到達しなかったセッション、ドリフトして再課金されるキャッシュプレフィックス、プロバイダーがすでに割引していない再折りたたみの無駄、肥大化したシステムプロンプトなどです。各対策には、週あたりに削減できるトークン数と金額、その数値の算出方法、実行するコマンドまたは設定が示されます。最良のセッションと並べて、セッションあたりの削減量の中央値と p10／p90も表示するため、最良のケースを典型的な値と誤解することはありません。また、独自の台帳で測定したレートを使用します。そのモードをこのマシンで実行したことがない場合に限り、公表済みのベンチマーク比率を使用し、その旨を行内に明記します。測定できない検出器は何も表示しないため、「推奨事項なし」は確認漏れではなく、結果を示します。
• 組織全体： distil proxy サイドカーを使用し、ANTHROPIC_BASE_URL を一度設定すれば、すべてのクライアントがそこを経由します。
• コミュニティ： オプトイン方式の集計（distil census on）では、数値のみの合計値を共有します。同意する前に distil census show で送信されるデータを正確に確認できます。スキーマは TELEMETRY.md に固定されています。デフォルトでは、引き続き何も送信されません。

ダッシュボード、ステータスラインプラグイン、フェデレーション型リーダーボードについては、デプロイと可観測性をご覧ください。

🔌 あらゆる SDK で動作

プロキシは 1 つだけです。base_url に対応するクライアント（Python、TypeScript、あらゆる言語）から接続するだけで、コードを変更せずに、キャッシュ対応の可逆圧縮を利用できます。

distil proxy --upstream https://api.anthropic.com   # localhost:8788

// JS/TS: npm i distil-llm  → helper so you don't hardcode the URL
import Anthropic from "@anthropic-ai/sdk";
import { distilBaseURL } from "distil-llm";
const client = new Anthropic({ baseURL: distilBaseURL() });

Anthropic / OpenAI / Gemini のワイヤ形式に対応するものなら何でも動作します。プロキシはフレームワークに依存しないため、CrewAI、AutoGen、LlamaIndex、Agno、Strands、Bedrock なども、クライアントのベース URL を distil に向けるだけで、変更せずに経由できます。

プロセス内での利用がお好みですか？クライアントを直接ラップできます。呼び出し箇所の変更も不要です。

from distil.adapters.anthropic import wrap
client = wrap(anthropic.Anthropic())   # compresses the request, keeps the cache warm

（OpenAI（Chat Completions と Responses API）および Gemini はプロキシ経由で利用できます：distil wrap -- codex を実行するか、OPENAI_BASE_URL をプロキシに設定してください。プロセス内でクライアントをラップできるのは Anthropic SDK のみです。）

フレームワークフック（プロキシ不要、ネットワーク経由なし） — メッセージリストを管理するエージェントフレームワークでは、メッセージがある場所で圧縮できます。

LangChain / LangGraph — langchain-distil

LangChain 独自のコミュニティミドルウェア連携に掲載されています。そこからお越しの場合は、このパッケージをお使いください。

pip install langchain-distil

from langchain_distil import compress_messages, pre_model_hook, as_runnable

msgs = compress_messages(msgs)                 # compress a message list in place of the call
graph = create_react_agent(..., pre_model_hook=pre_model_hook())   # LangGraph: before the model node
chain = as_runnable() | llm                    # or drop it into a chain (lazy langchain-core import)

ツールおよび関数のメッセージには可逆な Tier-1 ダイジェストが適用され、人間およびシステムのメッセージは Tier-0 のロスレス形式となります。また、アシスタントのメッセージは書き換えられません。モデル自身の言葉を編集するのは distil の役目ではありません。すべてのダイジェストはバイト単位で正確に復元できます。復元ツールを利用できない場合は、verbatim=True を指定すると Tier-0 のみを使用できます。

これは上記のフックを薄くラップしたものなので、同じ認定済み圧縮経路を継承し、再実装はありません。distil-llm は依存関係として含まれているため、両方を手動でインストールする必要はありません。

🎟️ サブスクリプション — 請求額ではなく、利用枠を節約

定額制の Pro/Max プランではトークンごとの請求が発生しないため、distil の金額は参考値です。一方、レート制限の利用枠は参考値ではありません。40 KB のテストログに費やしたトークンの分だけ、次のタスクで使える枠が減ります。

プロキシでは、ここでできることはあまりありません。Anthropic のコンシューマー向け利用規約（§3、項目 7）では、サブスクリプション認証情報を使った自動アクセスが制限されているため、distil は意図的に --lossless-only で動作します。ほとんどのトラフィックでは、これで節約できる量はほぼありません（distil 自身のコーパスでは 0.00%、E15b）。あなたのアカウントは、数パーセントの節約のために危険にさらす価値はありません。

PostToolUse フックは別の仕組みです — 公式に文書化された、ファーストパーティの拡張ポイントです。Claude Code はモデルが読む前に、独自のプロセス内で独自のツール出力を圧縮します：

distil hook --install     # writes ~/.claude/settings.json (idempotent, preserves your other hooks)
distil hook --selftest    # verify the schema adapters — a live mismatch is SILENT
distil quota              # the window it buys back

$ distil quota
Subscription quota (the currency a flat-rate plan actually spends):
  five_hour          [########............]  43.0% used  resets 2026-08-16 15:49Z
  seven_day          [....................]   4.0% used  resets 2026-08-23 07:59Z

単一セッションでの観察結果であり、ベンチマークではありません：1 つのタスクでライブのペア A/B テストを 1 回実施し、どちらの条件でも正しく回答しました。読み取られた tool_result は −38.6%、cache_creation は −67.4%、コスト加重では −68.3% でした（生データ）。さらに、検証可能な 5 つのタスクでも結果が一致しました（5/5、生データ）。これは大きな性能低下を検出するには十分ですが、一定の削減率を保証するものではありません。重要なのは、cache_read は 減少していない ことです。フックは各結果を 1 回だけ参照し、履歴を書き換えることはできません。そのため、圧縮は設計上追記のみとなり、プロンプトキャッシュは維持されます。

節約効果がないケース。 Tier-0 は JSON の最小化と連続する重複行の集約を行うため、節約効果はデータの形に左右されます。冗長な JSON（npm/pip/kubectl/terraform）では 28〜33%、重複するログ行では 最大 99%、一意な行だけのログ、文章、git log、git diff では 0% です。distil 自身の評価コーパスでは 0.00% の節約です。このコーパスには JSON も連続した重複行もありません。都合のよいテストデータだけを引用するのは、他者に対して私たちが批判している誇張になるため、この結果も公開しています。

他のエージェントについて：Gemini CLI の AfterTool は出力に間接的な影響を与えられます（評価中）。Codex CLI のフックは監視専用で、出力の書き換えを拒否するため、上流の仕組みによってブロックされています。

手法と注意事項を含むページ全文 →

🧠 MCP サーバー — エージェントにリコールツールを提供

Distil には、エージェントが自身のツール出力を圧縮し、後から元のバイト列を正確に取得できるようにする Model Context Protocol サーバーが付属しています。依存関係はゼロ（SDK を使わず、標準ライブラリの JSON-RPC を stdio 経由で使用）で、完全にローカルで動作します。コンテンツがマシンの外に出ることはありません。

1 行で追加できます：

claude mcp add distil -- distil mcp

{
  "mcpServers": {
    "distil": { "command": "distil", "args": ["mcp"] }
  }
}

{
  "mcpServers": {
    "distil": { "command": "uvx", "args": ["--from", "distil-llm", "distil", "mcp"] }
  }
}

起動していることを確認する — クライアントは不要です：

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | distil mcp

3 つのツール

各ツールには注釈（readOnlyHint、idempotentHint、openWorldHint: false）が付いているため、適切に動作する クライアントは、説明文から推測しなくても、distil_expand が安全で、繰り返し実行できるオフラインの読み取りだと認識できます。

これは再取得の経路であり、節約の経路ではありません。 MCP サーバーはエージェントの トラフィックを圧縮しません。それを透過的に行うのは distil wrap -- <agent> であり、ツール呼び出しは不要です。MCP サーバーが 追加するのは、もう一方の機能です。ラップしていないエージェントも含め、どのエージェントでも、コンテキスト内で見つけたハンドルを使って distil_expand を呼び出し、 元のデータを取得できます。ハンドルはセッションやプロセスをまたいで保持され、 DISTIL_RESTORE_TTL_DAYS（既定値は 14）を過ぎると期限切れになります。

🗜️ MCP コンプレッサー — 他のサーバーのツールと結果を圧縮

サブコマンド付きの distil mcp は、Codex、Cursor、Gemini CLI、opencode、Claude Desktop、Windsurf、カスタムエージェント向けに、 他の MCP サーバーの前段で動作する透過的なプロキシです。（Claude Code のツール検索では、未使用のツールがすでに遅延読み込みされます。詳しくは ADR 0017 をご覧ください。）

distil mcp wrap -- npx -y @modelcontextprotocol/server-filesystem ~/work   # one server
distil mcp serve --config mcp.json       # every stdio server in an mcpServers file
distil mcp install cursor                # route Cursor's servers through distil (…--undo restores byte-exact)
distil mcp watch                         # per-tool: tokens before→after, unlocks, fetches, expands

レベルは明示的です。L0 は損失のないスキーマ正規化（有効）、L1 は抽出型要約、 L2 はスキーマの取得後に実際のツールを表示する遅延読み込み（汎用の invoke を使い続ける方式ではありません）、L3 は L2 に使用状況から学習したピンを追加したもの、R は <server>_expand ツールを使って復元できる結果ダイジェスト（--results）です。 事前登録済みの精度プロトコルによる初回の実測では（claude-haiku-4-5、 各レベル 1,000 件のツールタスク）、すべてのレベルで認定基準を満たしました。適切なツールと引数の選択率は、生のツール一覧での 91.2% から L0～L3 では 92.1%／95.4%／96.3%／95.4% となり、R では生の結果の 99.7% に対して結果に関する質問の 99.5% に回答できました。 再現モデルでの実行が行われるまでは、L1～L3 と R はオプトインのままです。この実行では、短いインデックスがプロンプトキャッシュにヒットしなかったため、L2 の課金額は生のツール一覧を上回りました。詳細は docs/mcp.html をご覧ください。

📦 お好みの方法でインストール

初めての方へ。 uv tool install distil-llm を実行してから distil setup を実行してください。セットアップを行い、手順を案内します（今すぐ使うを参照）。先に効果を確かめたい場合は、distil bench を実行すると、API キーなしで認定基準を約 10 秒で確認できます。以下の一覧はインストール形式を選ぶためのもので、記載されている方法はすべて代替手段であり、必須ではありません。

インポートパッケージと CLI は distil、PyPI ディストリビューションは distil-llm です（名前だけの distil はすでに使われているため、uvx／pip では distil ではなく distil-llm を指定する必要があります）。Distil は CLI です。最新の macOS／Linux ではシステム全体への pip install がブロックされるため、分離環境（pipx／uv／brew／Docker）にインストールしてください（PEP 668）。Node／JS／TS： npx distil-llm wrap -- <agent>（npm パッケージが CLI と連携します）、または npm i distil-llm で、任意の SDK をプロキシに接続する distilBaseURL() ヘルパーを利用できます。または、base_url を自分で設定してください。

🧰 チートシート

基本的な内容は今すぐ使うとすべての SDK で使えますを参照してください。その他の内容は以下のとおりです。

ステータス行 — すべての状態で同じパターンです：distil · <live> · total ▼<lifetime>.

状態	表示内容	意味
圧縮中	distil · ⬢ digest · ▼12.0K · 40% smaller · $0.31 · total ▼27.0M · de 99%	圧縮中（モードチップ：⬢ digest · ◇ lossless · ▪ verbatim；de = 判断同等性）
待機中	distil · ✓ on · waiting for a large read · total ▼27.0M	オンですが、まだ大きなコンテンツはありません — 大きなファイルやコマンド出力から節約が得られます
アイドル	distil · ✓ on · total ▼27.0M	設定済みでオンですが、最近の通信はありません
ルーティングされていない	distil · off — session not routed · total ▼27.0M	このセッションのリクエストはプロバイダーに直接送られます — distil wrap（または常時有効の環境変数）で起動すると圧縮されます
バイパス中	distil · ⚠ wrapped, agent bypassing proxy · total ▼27.0M	wrap は起動していますが、3 分以上プロキシにリクエストが届いていません — エージェントが独自のエンドポイントを固定しています。修正方法：wrap を再起動してください。 主に claude.ai-subscription（OAuth）セッションで確認されています。カスタムベース URL 経由でのルーティングは上流で文書化されておらず、セッションが無視することがあります。続く場合は scripts/soak-report.sh で証拠を収集できます

de セグメントは、判断同等性のライブ証拠です。A/B サンプル 50 件 + A/A サンプル 30 件（A/B = 圧縮版と元のリクエストの比較、A/A = 同じリクエストを自身に対して再実行 — サンプリングノイズの基準値）が集まると ✓/⚠/✗ の割合が表示され、収集中は de n/50 と表示されます。シャドウサンプリングはデフォルトで 2% 有効です（--shadow 0 で無効化、--shadow 1.0 ですべてのリクエストをサンプリング — 約 3 倍のトークンコストで数分以内に同等性を確認でき、その後デフォルトの 2% に戻せます）。

実測 — 2026-09-15、ビルド 1.53.0rc1、ペア推定器（署名 v5）。 ライブサンプルが報告基準を超えました：A/B 398 件、A/A 399 件。モードごとに確認してください。digest は自己一致 113/206 に対し 102/206 の一致で、差は −5.3 pp と許容値の 5% を超過。一方、lossless のみでは 109/193 に対して 109/192 で（約 0）、ほぼ差はありません。ステータス行に表示されるプール値 ⚠de 97.5% (398) は、2 つの平均値であり、どちらのモードについても判定を示すものではありません。distil shadow-stats では各モードの値と区間が表示されます。リプレイは高温状態で実行され、399 件中 399 件で温度が固定されていません。そのため、生の一致率 53.0% ではなく、ペア差を確認してください。A/A 群にも同じ実行ごとのノイズが含まれており、差分によってそのノイズが相殺されます。成果物： benchmarks/results/shadow-live-2026-09-15.json。 以前の 2 つの測定値も記録に残しています。署名 v3 / 1.13.0 の数値（サンプリングした 116 件で 100%、A/A は 31/31）は撤回されています — 1.51.1 の変更履歴で、以前の thinking ブロックを含むリプレイがすべて署名エラーになり、該当するブロックがなかった少数のターンにサンプルが偏っていたことが判明したためです。また、1.51.1 の測定値（A/B 44 件、A/A 11 件、生の一致率 81.8%、基準未達、非ペア推定器）は benchmarks/results/shadow-live-2026-09-04.json に保存されています。

▼ = 節約したトークン数 · total = 累計 · de = 判断同等性（シャドウサンプルが A/B 50 件 + A/A 30 件集まった時点で判定）。git/cwd/model と同じ行に表示されますか？ DISTIL_STATUSLINE=minimal → distil ▼7.8K · 27M total。定額制のサブスクリプションでは、金額は参考値で、自動的に非表示になります（DISTIL_SUBSCRIPTION=0/1）。

🎚 圧縮モード — かんたんな説明

通常、モードを選ぶ必要はありません。distil onboard が課金方式を検出し、適切なモードを設定します。設定にモードが書き込まれるため、どのセッションでもそのまま使えます。特定のセッションで上書きするには、フラグを渡してください。

• digest（デフォルト）— Distil は大きなファイル、コマンド出力、過去の手順など、長い内容を短い要約にします。また、AI が必要とした瞬間に元の内容全体を取り戻せます。最も節約でき、元の内容が失われることもありません。元の内容は保持され、自動的に復元されます。ほとんどの方はこれを使えば大丈夫です。
• expand — digest と同じように内容を短縮しますが、Distil は AI が自分で押せる「全体を表示」ボタンも追加します。AI が長時間、自律的に動作する場合（例：長時間のコーディングセッション）に最適です。従量課金（API キー）の場合、自動的に選択されます。
• lossless-only（別名 --safe）— 慎重な設定です。Distil は余分な空白のように完全に再構築できる内容だけを削除し、要約は一切行いません。節約効果は小さくなりますが、詳細が失われる可能性はゼロです。月額定額サブスクリプションの場合、自動的に選択されます。
• verbatim — 最小限の処理です。書式を整えるだけで、それ以外は何も変更しません。節約効果はほとんどありません。送信内容を正確に確認または監査したい場合に使ってください。

技術的な詳細は次のとおりです。

サブスクリプションユーザーは --expand を強制しないでください。可逆圧縮の安全境界を越えることになります。コーディング時に再読み込みが必要な場合は、どちらのモードでも --session-delta を追加してください。

🧠 仕組み

効果の大部分を生み出すのは、2 つの手法です。エージェントのループでコストが実際にかかる部分を対象としており、コストがかかるように見える部分を対象としているわけではありません。

① キャッシュを考慮した圧縮 — 最大の効果をもたらす要素

各ステップで、増え続けるコンテキストを再送信します。プロンプトキャッシュでは、キャッシュの読み取りは新規入力の約 10 分の 1 のコストなので、実際のコスト要因はコンテキストのサイズではなく、キャッシュのミスです。Distil はプレフィックスのバイト列を安定させ（スキーマの正規化に加え、タイムスタンプや UUID などの変動するフィールドをプレフィックスの外に移動）、変動する末尾だけを圧縮します。

単純な再圧縮は、トークン数を減らしても、圧縮しない場合よりコストが高くなります。毎回プレフィックスを書き換えて、キャッシュを無効にするためです。Distil はそうしません — これこそが、ほとんどのツールが見落としている重要な点です。

• 転送済みバイト列のプレフィックス再生 — この仕組みのもう半分は、各ターンでモデルが読むトークンを変えずに自身の履歴を書き換えるクライアントです。cache_control のブレークポイントが進み、SDK が index フィールドを付与し、文字列がテキストブロックになります。オフラインで測定したところ、以前はプロバイダーを問わず、ターンごとにプレフィックス全体の転送が必要でした（転送バイト列が完全一致する割合は 0％）。Distil は、正規化後に一致する最長のプレフィックスについて、前のターンで転送したバイト列を再生するようになりました。該当するすべての書き換えパターンで**100％**を達成し、リクエストあたり約 0.13 ms です。復元するのはバイト列であり、判断ではないため、キャッシュヒットよりも正確な引用の保証が常に優先されます。各リクエストには再生が停止した理由（replay_stop: held、client、distil、marker、cold、untracked）が記録されるため、ウィンドウ内のキャッシュ書き込みについて、どちら側に原因があるかを特定できます。デフォルトで有効です。無効にするには --no-prefix-replay を指定します。→ ADR 0011
• コールドポイントでの再圧縮 — 古いバイト列をコストなしで変更できる唯一のタイミングは、プロバイダーのキャッシュエントリーがすでに期限切れになった後にターンが届いたときです（5 分間アイドル状態だった場合、またはクライアントが ttl: "1h" を指定した場合は 1 時間後）。そのターンでは、いずれにせよプレフィックス全体が再書き込みされます。そこで Distil は古いツール出力を distil_expand で復元可能なスタブに置き換え、以降のすべてのターンでそのスタブをそのまま転送することで、小さくなったプレフィックスがキャッシュされるようにします。期限切れが Distil 自身の時計から確実に分かる場合にのみ動作します。Distil が認識していない系譜、まだ処理中のリクエスト、または 1 つの系譜キーを共有する 2 つの会話では、何も行いません。正確な引用の読み取り、最新のターン、モデルが展開した内容には一切手を加えません。復元可能なダイジェストが動作する環境で実行されます（現時点では Anthropic）。無効にするには --no-cold-point または DISTIL_COLD_POINT=0 を指定します。節約効果は実環境ではまだ測定されていません。rc でのソークテストと A/B テストを通過する必要があります。→ ADR 0014
• ツール定義は意図的にそのまま転送されます。 実際のトラフィックでは、リクエストの tools 配列は課金対象の入力の大きな割合を占めますが、キャッシュされたプレフィックスの先頭にあり、そのほぼ全体がキャッシュ読み取り料金で課金されます。モデルが呼び出せるものを変えずに削除できる部分はごくわずかです。そのため、ロスレスなスキーマコンパクターでは、プレフィックスにリスクを負うほどの効果は得られません。測定には benchmarks/tool_schema_share.py を使用します。数値と再検討の条件は ADR 0012 に記載されています。ツールのオーバーヘッドを削減するには、使用していないコネクターを削除してください。distil discover でコスト順にランク付けできます。
• Claude Code 独自の MCP ツール検索は有効なままです。 Claude Code は MCP ツール定義の読み込みを保留し、モデルが検索したときにだけ読み込みますが、ANTHROPIC_BASE_URL がファーストパーティ以外のホストを指定すると、この機能を無効にします。そのためプロキシ経由では、以前は各コネクターの完全なスキーマが毎ターン送信されていました。現在は distil wrap -- claude が子プロセスに ENABLE_TOOL_SEARCH=true を設定します（エクスポート済みの ENABLE_TOOL_SEARCH=false がある場合はそちらが優先されます）。distil default --always-on は、Claude Code の設定にこの値がない場合にのみ追加します。また、Distil は defer_loading／tool_reference ブロックをバイト単位で完全一致したまま転送します。実環境で検証済み（2026-09-25）： ラップした Claude Code セッションが MCP ツールを呼び出し、すべてのリクエストで遅延読み込み対象のツールが記録され、キャッシュ読み取りは維持され、失敗はありませんでした。distil discover は、20 件以上のリクエストで送信され、一度も呼び出されていない MCP サーバーを表示します。→ ADR 0013 distil cache は、キャッシュが機能しているかを示し、意図的に2種類の数値を組み合わせています。キャッシュの読み取りと書き込みはプロバイダー独自の usage に基づき、金額の確かな根拠となります。一方、プレフィックスのドリフトは、送信した安定ブロックのコンテンツを含まないハッシュから、原因を distil が独自に診断したものです。測定に裏付けられていない診断は推測にすぎないため、両方を併記します。3ターンのライブセッションで、3ターン目にシステムプロンプトへセッション ID が追加されるケースでは、2つの指標は独立して一致します。ハッシュがフラグを立てたターンで、プロバイダーは再作成のために15,819トークンを再度請求しました。単に増えただけのターン、つまり会話が通常どおり進んだだけのターンはドリフトではありません。健全なターンのたびに警告が出ると、ユーザーはその機能をオフにしてしまうからです。プロキシされたリクエストがない場合は、安心させるようなゼロを表示するのではなく、ゼロ以外の終了コードで終了します。意図的に提供していないキャッシュ機能とその理由を含む全体像は、docs/CACHE.md をご覧ください。

② 因果的／反実仮想による刈り込み — 発見エンジン

評価は、横に取り付けられた単なる物差しではなく、発見エンジンです。コンテキストブロックを1つ取り除いて再実行したとき、判断に変化はあったでしょうか。判断を一度も変えないブロックは、削除しても問題がないと証明できます。

distil prune
# doc-0   PRUNE (causally inert)     # speculative retrieval, never cited
# obs-0   keep (changed a decision)  # carries the decision-driving signal

🎓 証明書（DERC）

ゲートが答えるのは、「この戦略は自分のコーパスで非劣性を満たすか？」です。Decision-Equivalence Risk Certificate が答えるのは、運用上の問いです。「自分で選んだリスク予算（たとえば、意思決定の変更が5%以下）に対して、実際のトラフィックで成り立つ保証のもと、どこまで圧縮できるか？」

distil conformal --corpus ./mycorpus --alpha 0.05 --delta 0.05
# ✔ CERTIFIED 'lossless' → 57.4% savings; decision-change ≤ 5.0% at 95% confidence (Learn-Then-Test)

すべての証明書には、評価に使ったオラクルが記載されます。 証明書は証拠です。何によって生成されたかが記されていない証拠は証拠とはいえません。そのため、Certificate.grader にはランナーから値が設定され、保証の中にも表示されます。デフォルトのオフラインゲートはモデルではなく、決定論的な合成オラクルによって評価され、そのことがそのまま表示されます：Graded by: deterministic (synthetic DECISION: oracle — NOT a model)。実際のモデルによる証拠は distil certify --runner anthropic で取得でき、その証明書には代わりにそのランナーが記載されます。数値には必ずその由来が付いているため、どのレイヤーから来た数値かは常に確認できます。

これはヒューリスティックな閾値ではなく、コンフォーマルリスク制御（Learn-Then-Test / CRC、分布自由・有限標本）です。保証を支える重要な但し書きが1つあります。保証には交換可能性（キャリブレーション用トラフィック ≈ ライブトラフィック）が必要で、その分布に対する周辺的な保証です。分布が変化したら再キャリブレーションしてください。理論の詳細と引用文献：概念 · docs/PAPER.md。

1つのリスク予算と、それに基づいて動作するアラーム。 証明書、ライブのドリフトアラーム、証明台帳はすべて、固定された定数の1組 distil.conformal.BUDGET_ALPHA / BUDGET_DELTA（信頼度95%で意思決定の変更が5%以下）を参照します。そのため、ある画面で変更なしと表示される一方、別の画面では予算超過とされることはありません。distil certify の TOST マージン（CERT_MARGIN、2 pp）も同じ場所にあり、予算より厳しい値に固定されています。シャドーモードのペア判定によって anytime-valid e-process が予算を超えると、プロキシは次のリクエストから損失を伴う圧縮を停止します。Tier-0 のみとなり、ダイジェストも出力整形も行いません。マシンごとに e-process は1つだけです。各プロキシはファイルロックのもとで、生成したばかりの判定をその e-process に加算するため、再起動、ホットスワップ、並列ラップによって同じ証拠が再検定されることはありません。停止状態は再起動後も維持され、レシートチェーンに記録されます。セッション単位ではなくグローバルに適用されるため、新しい distil wrap を実行して、前回の実行で有害と証明された動作をひそかに再開することはできません。また、長時間稼働するプロキシは、別プロセスによる停止や解除を30秒以内に反映します。ステータス行には ⚠ drift hold と表示され、wrap の終了サマリーと distil stats には平易な説明として BREACHED … compression held at lossless-only と表示されます。解除するには distil calibrate を実行し、その後 distil reset --drift-guard を実行してください。変更されるのはアラームだけで、節約量の合計には影響しません。アラームはデフォルトで有効です。予算超過後も圧縮を続けるには DISTIL_NO_DRIFT_GUARD=1 を設定してください（アラームの表示は続きます）。マルチテナントゲートウェイは意図的に対象外です（ADR 0016）。1.53.0rc1 からの新機能です。他のデフォルト有効の変更と同様、rc のソークテストをクリアする必要があります。

🏔 軌跡レベルの証明書

DERC は ステップ を証明しますが、こちらは タスク を証明します。E7 実験と、2024～26 年のエージェント圧縮に関する文献は、ステップ単位の忠実度は維持されても、エンドツーエンドの成功率が大きく低下することを示しています。そのため distil は、ユーザーが実際に体感するレベルも証明します。評価スイートを 2 回（フルコンテキストと圧縮後のコンテキスト）実行し、対応する結果を入力すると、圧縮によって解決可能なタスクがいくつ失われる可能性があるかについて、分布に依存しない上限が得られます。

distil certify-trajectories outcomes.jsonl --alpha 0.05 --delta 0.05
# each line: {"task_id": "...", "full_success": true, "compressed_success": true}
# → With confidence 95%, compression degrades at most 5.0% of tasks the full
#   context would have solved (observed 0.5% over 200 matched trajectories).

サンプル数が少ない場合は証明を拒み、交換可能性に関する前提を証明書そのものに明記します。また、ライブ環境で機能する anytime-valid な ドリフトアラーム（distil/drift.py、上記）と連携し、ライブトラフィックの変化が証明書を古くするほど大きくなった場合に通知します。プロキシ上では、その変化に応じて動作します。（trajectory_risk.drift_monitor は研究専用の関連機能であり、リクエスト処理経路にはありません。）結果に基づくポリシー（distil.compress.guideline）は、要約するとタスクを破綻させるコンテンツクラスを保護するよう設計されていますが、現時点ではまだ何も連携されていません。record_trajectory_outcome の呼び出し元はなく、distil doctor にもその旨が表示されます。

🧩 内容

実装済みの機能は 40 種類以上あり、すべて実際に動作します（スタブはありません）。キャッシュを考慮したコストエンジン、因果関係に基づくプルーニング、TOST ゲートとコンフォーマル証明書、プロキシと Anthropic／OpenAI／Gemini のファーストクラスアダプター（Chat Completions、Responses API、Gemini generateContent）、MCP サーバー、LiteLLM／LangChain／LangGraph フック、エージェントごとのラップ用プリセット、セッション終了時に出力する Proof Ledger、発行済みキーとレート制限を備えたマルチテナントゲートウェイ、復元ストアの保存時暗号化、学習型の保持モデル、出力圧縮、オプションの Rust ホットパスコア（maturin でソースからビルド可能。公開済みのホイールでは同じ API の純粋な Python エンジンを実行）を備えています。コアのランタイム依存関係は ゼロ です。

モジュール別の全体像はこちらをご覧ください：アーキテクチャ · 技術 · CLI リファレンス。

🔒 セキュリティとデプロイ

• デフォルトでは localhost のみ — プロキシは 127.0.0.1 にバインドし、設定された単一のアップストリームにのみ転送します（SSRF は発生しません）。
• シークレット／本文をログに記録しない — リクエスト本文や認証情報は一切ログに記録されません。
• 認証モードによる制御 — サブスクリプション／OAuth セッションが検出されると、--lossless-only が自動選択されます（Tier-0 の逐語モード：Tier-1 のダイジェストスタブなし、ツール注入なし — プロバイダーの利用規約に準拠）。distil wrap -- claude はデフォルトで安全で、フラグは不要です。明示的に --expand を指定すると、その場合でも復元可能なダイジェストを利用できます（復元ツールを許可しているため、不可逆的に失われるものはありません — issue #28）。展開ツールが注入されていない場合、エージェントはスタブを復元できないため、--lossless-only はそのまま逐語モードに切り替わります。
• 保存時に暗号化 — ~/.distil/restore/ のダイジェスト原文は、HMAC-SHA256-CTR（encrypt-then-MAC、DSTL1 ヘッダー、chmod 0600 のキー）で暗号化され、バックアップ／同期による漏えいや、共有ファイルシステムでのユーザー間読み取りを防ぎます。データファイルとキーファイルの両方を読み取れる、同じ UID の攻撃者は明示的に脅威モデルの対象外です（THREAT_MODEL.md を参照）。従来の平文ファイルも透過的に読み込まれます。DISTIL_NO_ENCRYPT_AT_REST=1 で暗号化を無効にできます。ハンドルは DISTIL_RESTORE_TTL_DAYS（デフォルトは 14 日）を過ぎると失効します。アップストリームにデータが転送されることはありません。
• 運用対応 — すべてのエントリーポイントで、認証不要の GET /distil/health ライブネスプローブを提供します（課金対象のアップストリームには一切アクセスしません）。ゲートウェイの使用量チェックポイントは 30 秒ごとにディスクに書き込まれます（クラッシュ時にも安全で、正常終了時だけではありません）。DISTIL_DEBUG=1 を設定すると、フェイルオープン圧縮パスで握りつぶされるすべての情報が表示されます。
• アップグレードは実行中のセッションに適用 — distil wrap は、wrap 専用のソケット上でプロキシをサブプロセスとして監視します。新しいバージョンがディスクに配置される（pipx／pip でアップグレードする）と、wrap は新しいワーカーにホットスワップします。同じポートを使い、処理中のストリームは旧ワーカーで完了するため、エージェントは再起動しません。ヘルスチェックと自動ロールバックにも対応しています。アップグレードに問題がある場合は、旧ワーカーが処理を継続します。POSIX では kill -USR1 <wrap pid> で強制的に実行でき、DISTIL_HOT_SWAP=0 で無効にできます。Windows では wrap は従来どおりスレッド内プロキシを使うため（シームレスな切り替えはありません）、バージョンの不一致があると警告します。Windows ではアップグレードは次のセッションから適用されます。
• OpenTelemetry GenAI スパン（オプトイン） — pip install 'distil-llm[otel]' を実行すると、プロキシを通るすべての呼び出しで、GenAI のセマンティック規約に準拠したスパン（gen_ai.request.model、gen_ai.usage.input_tokens）に加え、distil 独自の情報（distil.tokens.original と distil.tokens.compressed、distil.compression.ratio、distil.shadow.sampled、セッションごとのトレース相関に使う distil.session.id）が出力されます。既存の OTel バックエンドで、圧縮が各リクエストに与えた影響を正確に確認できます。追加パッケージがインストールされていない場合、処理は単一のブール値チェックのみで、オーバーヘッドはゼロです。また、OTel の障害によってリクエスト処理が妨げられることはありません。同じ数値は OTel のカウンター（distil.requests、distil.tokens.baseline／.sent／.saved）としてもエクスポートされます。スパン属性と同じ計測箇所で記録されるため、トレースとメトリクスが食い違うことはありません。また、スパンのチェックより前に記録されるため、トレースのサンプリングを無効にしていても機能します。
• Prometheus エンドポイント（ゲートウェイ） — GET /distil/metrics は標準のテキスト形式でメトリクス（distil_tokens_saved_total、distil_dollars_saved_total、distil_compression_ratio、…）を提供します。標準ライブラリのみで実装されているため、スクレイプ処理に依存関係は追加されず、インポートが失敗することもありません。系列にはテナントのラベルが付くため、このエンドポイントには /distil/stats とまったく同じ管理者ゲートが適用されます。ローカル使用ではループバック上で公開され、ループバック以外にバインドする場合は --admin-token が必要で、指定がなければ拒否されます。このゲートが重要なのは、認証されていないテナントラベル付き /metrics が、まさに LiteLLM の情報漏えいに相当するバグだからです。この点は直接テストされています（未認証では 403、誤ったトークンでは 401。さらにラベル注入と、公開データにシークレットが含まれないこともテストされます）。詳細なリファレンス：docs/adoption.html#metrics。
• ビジョン — スクリーンショットの繰り返しに全額を支払わなくて済みます — 1024×1024 の画像は約 1,400 個の入力トークンに相当します。UI のスクリーンショットを撮ったり、ダッシュボードをポーリングしたりするエージェントは、そのブロックがコンテキストに残るすべてのターンでその分のコストを支払います。Distil はバイト単位で完全一致する画像の重複だけを除外し、それぞれを復元可能な参照に置き換えます。最初の出現と異なる画像はすべて変更されず、再エンコードも縮小も行われません。また、distil_expand は元の source をバイト単位で完全に一致する形で返します。URL ソースは重複として扱いません。同じ URL が 2 回出現しても、同じピクセルである証拠にはならないためです。一般的な代替策は画像のサイズ変更ですが、これは仕組み上不可逆で、検証もできません。この方式は、稼働中のビジョンモデルとの判断等価性 100％（A/A の下限 100％、TOST p<0.0001）で認証済みであり、認証書は対象範囲を明記したうえでパッケージに同梱されています。distil certify --strategy vision --runner anthropic で、独自のワークロードを認証できます。失敗した場合も含め、あなたの結果は私たちの結果より優先されます。DISTIL_VISION=0 で無効にできます。詳細なリファレンス：Techniques § Vision。
• サプライチェーンの強化 — リリースには、PEP 740 Sigstore 認証（PyPI の Trusted Publishing 経由）、すべての GitHub リリースへの CycloneDX SBOM の添付、main で毎週実行される OpenSSF Scorecard が含まれます。リリースジョブは、公開したばかりのバージョンについて PyPI が認証バンドルを報告しない場合、失敗します。そのため、この記述が実態と乖離することはありません。1.19.0 以降のすべてのリリースで検証済みです。言葉だけでなく、次のコマンドで確認してください。curl -s https://pypi.org/integrity/distil-llm/<version>/<filename>/provenance（integrity API に注意してください。/pypi/<pkg>/<ver>/json には認証情報フィールドがなく、そちらを参照すると誤って認証情報なしと判定されます）、または uvx pypi-attestations verify pypi --repository https://github.com/dshakes/distil pypi:distil_llm-<version>-py3-none-any.whl。
• Kubernetes — マルチテナントゲートウェイ用の Helm チャートは packaging/helm/distil-gateway にあります。デフォルトで認証必須、非 root、読み取り専用 rootfs となっており、PDB、HPA、DNS と 443 への送信のみを許可する NetworkPolicy、さらに ServiceMonitor とアラートルールが含まれます。Grafana ダッシュボードも付属し、CI は各パネルとアラートを distil が実際に出力するメトリクスと照合します。
• SSO / RBAC — ゲートウェイは独自の dsk- キーに加え、OIDC ベアラートークンを受け付け、優先順位が定められた 3 つのロール（viewer < operator < admin）を使用します。JWS の検証は標準ライブラリのみで行います。RS256 には [oidc] extra が必要で、これがない場合、RS256 トークンは未検証のまま受け入れられるのではなく、拒否されます。
• 監査証跡 — 認証の成功、拒否、レート制限、キーの発行・失効はすべて $DISTIL_HOME/audit.jsonl に追記されます（0600、JSONL、flock による保護）。distil gateway audit で読み取るか、--json を使って SIEM に直接出力できます。distil が書き込むほかのデータと同様、内容は含まれません。記録されるのは識別子と結果だけで、プロンプトのテキスト、ツールの出力、生のキーは記録されません。
• リクエストごとのレシート — 第三者が検証できるチームの監査ログ — プロキシが処理する各リクエストについて、内容を含まないハッシュチェーン形式のレシート（トークン数、モード、発行されたハンドル、ハンドルが引き続き解決可能かどうか。プロンプトや完了テキストは含まれません）が $DISTIL_HOME/receipts.jsonl に追記されます（0600）。チェーンはローテーションされます。アクティブファイルがセグメントサイズに達すると、バイト単位で receipts-segments/ に封印され、その隣に小さなチェックポイントが書き込まれます。チェックポイントには、セグメント ID、行数、最初と最後のレシートハッシュ、およびセグメント全体の RFC 6962 形式の Merkle ルートが記録されます。次のレシートは封印されたセグメントの最後のハッシュにリンクされるため、履歴は一つのチェーンとして維持されます。distil receipts はすべてを検証します。--segment N はほかのセグメントを読み込まずに、チェックポイントに対して 1 つのセグメントを検証します。--checkpoints はチェックポイントレコードと各レコードの sha256 を出力するので、チームが信頼する場所に固定できます。--prove <request-id> は 1 つのレシートの Merkle 包含証明を出力します。監査担当者にはログ全体ではなく、1 つのレシートを渡せます。--check-proof proof.json --checkpoint-hash <sha256> は、証明とそのピンだけを使ってレシートの内容、セグメント、位置を検証します。--root <hex> だけの場合に検証できるのはそのツリーへの包含のみで、位置は検証できません。何も固定されていない場合、検証は循環論法となり、その旨が表示されます。セグメントが導入される前に書き込まれたチェーンは変更なしで検証され、最初のローテーション時に未変更のままセグメント 0 になります。信頼境界は明示されています。~/.distil に書き込める人はセグメントとそのチェックポイントの両方を書き換えられるため、チェックポイントのハッシュは、そのような人が書き換えられない場所に固定してください。
• キーの有効期間 — distil gateway keys issue --tenant acme --expires-in-days 90 を実行すると、キーに有効期間を設定でき、参照のたびに期限が確認されます。keys list は active／expired／revoked を個別に表示するため、突然の 401 が発生しても、実際には失効していないキーの失効原因を調べる必要はありません。有効期限のないキーは引き続き無期限で機能するため、既存のデプロイメントに変更はありません。

トポロジー（ローカルサイドカー、コンテナーサイドカー、共有ゲートウェイ）についてはデプロイとセキュリティを、レビューに適したデータ取り扱いとコンプライアンスの概要についてはセキュリティホワイトペーパーを、脆弱性の報告についてはSECURITY.mdをご覧ください。

✅ 期待を持たせないこと

• トークン数の自動補正 — オフラインのヒューリスティックは概ね正確であり、圧縮の比率はどのみち正確です。distil はプロキシであるため、各レスポンスでプロバイダーの実際の usage.* を参照します。そこから体系的な補正を学習します（コンテンツを含まず、ネットワークも使いません）。そのうえで、モデルとコンテンツ構成に合わせて絶対数を自動調整します。十分なトラフィックが蓄積されると、リーダーボードに「請求された使用量に合わせて補正済み（N リクエスト、±X%）」と表示されます。それまでは生のヒューリスティック（恒等値のため、偏りはありません）を使用します。文字列ごとの正確な値が必要な場合は、引き続き --tokenizer anthropic を使用できます。

• デフォルトのランナーは決定論的な代役です（正解データを用いたオフラインゲート）。循環しない評価では、実際のモデルを使った実際のエージェントのトレースを採点します — 証明ハーネス。

• 信頼できる採点を徹底： 多数決（単一サンプルでは採点者のノイズを判定の変化と誤認するため）、同じファミリーの採点者、そして可逆ティアを distil_expand の復元ループ込みで採点します。

• 重みを捏造しません — keep-model は実際のロジスティック分類器です（ホールドアウトデータで正解率 96.4%、F1 値 0.98。コミット済みの metrics.json は、シードを固定した python -m distil.codec.learned からバイト単位で同一に再生成できます）。オプションのトランスフォーマーコーデックにはチェックポイントがパッケージに含まれていません — デモ用チェックポイントは v0.1.0 リリースに添付されています。本番環境で使う場合は、自分のトレースで再トレーニングしてください（distil train-transformer）。

• 外部ベンチマークで、自社のゲートが見逃した欠陥が見つかりました。 API 自身の使用量フィールドを基に採点した 75 回のエージェント実行で、wrap --expand は、Claude Code を単独で使った場合の 13 件に対し、コーディングタスク 15 件中6 件を完了しました。7 回の実行では何もディスクに書き込まず、成功したと報告していました。原因は 4 つあり、すべて 1.49.0 で修正済みです。それぞれに対し、修正がなければ失敗することを確認済みの回帰テストを追加しています。確立できたことと確立できていないことを含む報告はこちらです。テストスイートがすべて成功しても、作業が完了した証明にはなりません。

意図的にプラットフォームではありません

Distil はコンテキストツールの審判役であり、同じゲートを課す圧縮機能を備えています — コンテキストスイートではありません。証明基準に適合しない機能は採用しませんでした：

採用した機能（ゲートを通過したもの）：エンティティを保護するためのプラグイン式重要度スコアラー、キャッシュプレフィックスの可観測性、フレームワークフック。

🎯 請求額の両側

Distil は入力／コンテキスト（包括的）と出力の両方を圧縮します。生成側では出力の冗長さを調整し（従量課金制で、distil output-savings を使って測定）、再入力時には可逆な出力ダイジェストを適用するため、過去の冗長な回答が履歴として残っても、全額分のコストがかかり続けることはありません。詳細：出力と I/O。

調整によってモデル自身の言葉が変わるため、誰かがフラグを入力しただけで有効になるわけではありません。有効になるのは、根拠が示すべき状態である場合だけです。従量課金制のセッションでは、--shape-output auto がデフォルトです。調整が実行されるのは、実行中のペア比較シャドー判定が共通の報告基準（A/B 50 件＋A/A 30 件）を超え、害の上限が distil certify の検証基準と同じ ±2pp の範囲内にあり、さらに圧縮による返信の長さへの測定効果が節約側でゼロを除外する場合に限られます。どれか一つでも満たさなければ、調整は無効になり、その理由が出力され、セッションマニフェストに保存され、distil dissect に表示されます。このゲートは、調整を無効にして測定したシャドー行だけを読み取るため、調整後の短い返信によって調整が有効な状態に保たれることはありません。サブスクリプションまたは OAuth のセッションでは、常に無効です。distil は定額料金のプロンプトを変更しません。

🔬 再現可能な評価と論文

すべての数値は、同梱のコーパスから再現できます（キー不要の distil bench）。循環論法にならない証明ハーネスでは、実際のモデルを使って、実際のエージェントのトレースを評価します（τ-bench／SWE-bench）：benchmarks/PROVE.md。完成した論文、LaTeX ソース、コミット済みのすべての結果：docs/PAPER.md · docs/paper/ · 論文 PDF。手順を追って確認：数値の再現 →

エージェントが読まないコンテキストを再送するために、料金を払い続けるのはやめましょう。

pipx install distil-llm && distil bench
_{約 10 秒で 9 分野の節約効果を認証 — API キー不要、実行時依存関係ゼロ}

はじめる → · SDK に組み込む · 証明を読む · PyPI

⭐ distil でトークンを節約できたら

スターを付けることで、次のエンジニアが、損失のある推測ではなく、実証可能な節約効果を見つけやすくなります。また、distil stats --badge を使えば、実測したあなた自身の数値を示す共有可能なバッジを作成できます。このバッジとこのリポジトリが、マーケティング部門のすべてです。

🤝 コントリビューション

プルリクエストを歓迎します。CONTRIBUTING.md をご覧ください。重要なルールは一つだけです。新しい圧縮戦略は make gate に合格しなければなりません（すべての分野で非劣性、バイト単位で可逆）。ゲートが合格しなければ、マージもできません。哲学を一文で表すと、これに尽きます。

評価を自分で実行する — すべてのゲートは無料でオフラインで実行できます。docs/RUNNING-EVALS.md をご覧ください。

💬 コミュニティとサポート

• 質問、アイデア、バグ報告 → issue を作成してください。どの質問も、まだ解決できていないドキュメントの不足を示しています。
• トークンの節約状況を見る → 公開に同意した場合に参加できる、最新の導入状況ボードをご覧ください。コミュニティの正確な合計値を投影なしで表示します。設計上、コンテンツは含まれません。
• リリースを確認する → リリースは高頻度で公開されます。pip install -U distil-llm（または uv tool upgrade distil-llm）で最新版を利用できます。

ライセンス

Apache-2.0 · 「同じ効き目で、より少ない量。」