Distil

サーバーレスのプロンプト圧縮MCPコネクタで、プロンプトを高速に圧縮し、Distilスタイルのメトリクス（トークン、コスト、レイテンシ、計算負荷、エネルギー、炭素）を返します。すべての数値は実測または明確にラベル付けされた推定値です。完全な設計はSPEC.mdを参照してください。

ソースのホワイトペーパーのPrompt Intelligence + トークン/コスト/計算/エネルギー/炭素レイヤー（構築可能なスライス — GPUハードウェア不要）を基に構築されています。

ハイライト

• ブラウザ拡張機能: claude.ai、chatgpt.com、gemini.google.comに直接入力する内容を圧縮します。APIキー不要で、通常のログイン済みチャットセッション内で動作します。extension/README.mdを参照してください。

• LLMゲートウェイ: OpenAI/Anthropic/Gemini用のドロップインプロキシ。base_urlをDistilに向けるだけで、すべてのリクエストが実際のプロバイダに届く前に圧縮（オプションでガバナンス）され、ストリーミングも含まれます。下記参照。

• 高速+サーバーレス: デフォルトのヒューリスティック圧縮は純粋なPython（約3ms、モデル不要、APIキー不要）。高品質なオプションのgpt-4o-miniモードもあります。

• MCPコネクタ: ストリーミング可能なHTTP上で5つのツール+メトリクスリソースを公開します。

• Distilメトリクス: トークン/コスト/レイテンシ（実測）+ エネルギー/炭素/GPU負荷（推定、ラベル付き）。GPU意図は計算負荷モデルで保持され、偽装されません。

• ライブダッシュボード + 公開/metricsエンドポイント。

• 誠実な設計: すべての推定値はestimated: trueとフラグ付けされ、クローズドモデルのパラメータはparams_known: falseとフラグ付けされます。

Related MCP server: token-optimization-mcp

LLMゲートウェイ（ドロップインプロキシ）— ビジネス製品

既存のOpenAI/Anthropic/Geminiクライアントをプロバイダに直接向ける代わりに、Distilに向けます。Distilはプロンプトを圧縮し、あなた自身のAPIキーを使用して実際のプロバイダに転送し、回答をそのままストリーミングで返します。リクエスト/レスポンスの形状は同じなので、ベースURL以外のコードは変更不要です。

your app → Distil (/v1/...)  →  compress + optional governance  →  real provider  →  same answer back to you

1行の変更（OpenAI SDK）:

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_OWN_OPENAI_KEY",       # unchanged — sent straight through, never stored
    base_url="https://getdistil.vercel.app/v1",
)
resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Could you please possibly explain, in a very detailed way, what a REST API is?"}],
)

curl（圧縮+通常の回答+節約ヘッダーの証明）:

curl -i https://getdistil.vercel.app/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Could you please possibly explain, in a very detailed way, what a REST API is?"}]
  }'
# Response body is a normal OpenAI chat.completion object.
# Response headers include:
#   x-distil-original-tokens, x-distil-sent-tokens, x-distil-tokens-saved

AnthropicとGeminiも同じように動作します。ベースURL/パスと認証ヘッダーが変わるだけです（既存のクライアントライブラリが処理します）:

動作

• あなたのキー、あなたの請求。 Distilは、各リクエストで送信されたAuthorization/x-api-key/keyを実際のプロバイダにそのまま転送します。Distilはそれを保存せず、メモリ内に一方向ハッシュのみを保持し、レート制限/メータリングの識別にのみ使用します。

• デフォルトで圧縮されるもの: すべてのuserロールメッセージ（OpenAI/Anthropic）またはuserロールのcontentsエントリ（Gemini）のテキスト — 「最新メッセージ」と、そこに貼り付けられた大きなコンテキスト/ドキュメントの両方をカバーします。system/system_instructionおよび以前のassistant/modelターンは変更されません。関数/ツールスキーマ（tools、tool_calls、tool_resultブロック）は決して変更されません。

• フェイルセーフ: 圧縮またはガバナンスが何らかの理由で例外をスローした場合、Distilは呼び出しを壊す代わりに、元の未圧縮リクエストを転送します。

• ストリーミング: "stream": trueは最初に一度だけ圧縮され、その後プロバイダのSSEレスポンスがチャンクごとにバッファリングなしで中継されます（遅いテストソースに対してローカルで検証済み — チャンクはプロバイダ自身のペースで到着し、バッチ処理されません）。

• ガバナンスモード（x-distil-govern経由）: off（デフォルトはlog）は決してブロックしません。logは分類/PII/インジェクション/モデレーションチェックを実行し、違反を記録しますが、リクエストは転送します。enforceは、判定がblockの場合、転送する代わりにプロバイダ形式の4xxエラーを返します。

設定ヘッダー（すべてオプション）

誠実さに関する注記

• 圧縮はゲートウェイではヒューリスティックのみです（圧縮のためのリクエストごとのLLM呼び出しはありません — レイテンシとコストが2倍になるため）。少しぎこちなく読める場合があります。プロンプトで回答品質が低下する場合はx-distil-ratioを上げ（例: 0.7）、本番で依存する前にテストしてください。

• ライブプロバイダAPIに対して検証済みであり、推測ではありません。OpenAIとAnthropicのリクエスト/レスポンス/エラー/SSE形状は、api.openai.comとapi.anthropic.comに実際のリクエストを送信し（無効なキーを使用して実際のエラーエンベロープを観察）、レスポンスをバイト単位で検査して確認しました。GeminiのgenerateContentリクエスト/レスポンス/エラー形状も同じ方法で検証しました。そのストリーミングフレーミング（:streamGenerateContent?alt=sse）はGoogleのREST例に記載されているSSEモードですが、有効なGeminiキーでライブ検証はされていません — 依存する前にこのパスをテストしてください。

• プロバイダ自身のレスポンス本文内のusage/トークンカウントフィールドは、プロバイダの実際の信頼できる数値です（Distilはそれらに触れません）。x-distil-*ヘッダーは、Distilが圧縮した内容の独自のカウントです。

クイックスタート（ローカル）

pip install -r requirements.txt
python demo.py                    # try the core on a sample
python eval/run_eval.py           # measured eval over sample prompts
pytest tests/                     # test suite
python mcp_server.py              # run the MCP server over stdio
uvicorn api.index:app --port 8000 # run the HTTP server + dashboard
# → open http://localhost:8000/  (dashboard) and /mcp (connector)

MCPツール

リソース: metrics://summary。

各 compress_prompt の結果には分散トレーススパン（§2.2）も含まれます — 測定されたサブステップのタイミング（route、cache_lookup、compress、token_metrics、estimates）。

セマンティックキャッシュ（§8.2）とマルチモデルルーティング（§8.4）

• キャッシュ — 2層構造、サーバーレス対応: 完全一致（正規化ハッシュ）＋類似度（語彙コサイン、DISTIL_CACHE_THRESHOLD、デフォルト 0.92）により、ほぼ同一のプロンプトは以前の圧縮結果を再利用。(ratio, quality, model) で名前空間が分離。ウォームインスタンスごとに保持。ヒット率はダッシュボードに表示。

• ルーティング — route_prompt / target_model="auto" はプロンプトの複雑度（推論動詞、コード、構造、長さ）をスコアリングし、小規模 vs 大規模モデルを選択。モデルごとのコスト見積もりも提供されるため、選択は透明です。

ガバナンスワークフロー

govern の allow/warn/block 判定に加えて、Distil は以下をサポートします:

• モデルポリシー — DISTIL_MODEL_POLICY_MODE（デフォルト denylist | allowlist）

  • DISTIL_DENIED_MODELS / DISTIL_ALLOWED_MODELS。ゲートウェイ（リクエストボディの model → 403 model_not_allowed）と process_prompt の両方でチェックされます。

• Redact / quarantine / require-approval — process_prompt(..., enforcement=) は "block"（デフォルト）、"redact"（PII/シークレットをマスクして続行）、"quarantine"（セキュリティレビューのために保留）、"approval"（承認待ちで保留）のいずれか。quarantine/approval は即座にレビュー ID を返します — resolve_review が承認または却下するまで、何も圧縮されません。ライブ LLM ゲートウェイは block/redact のみをサポート（x-distil-enforcement ヘッダー）— 同期プロキシ呼び出しは人間の判断を待つ手段がないため、quarantine/approval は /process と MCP のみで利用可能です。

• 例外ワークフロー — grant_exception(scope, value, tenant?, ttl_hours?, reason?) は、ポリシー全体を無効化する代わりに、パッケージまたはモデルのブロックに対する狭い範囲・期限付きの上書きを付与します。check_packages / check_model_policy によって自動的にチェックされます。

• ライセンススキャン — scan_licenses(text) は、参照されているパッケージ（permissive / weak_copyleft / copyleft / unknown）を小規模なオフラインレジストリに対して分類します。copyleft のヒットはガバナンスを warn にエスカレーションします（法的レビューフラグであり、ハードブロックではありません）。不明なパッケージは推測せずにフラグ付けされます。

• 監査トレイル — すべての govern 呼び出し（allow を含む）は証跡グレードのエントリを書き込みます — 決定 ID、テナント、判定、理由、プロンプトハッシュ＋60文字のプレビュー（完全なプロンプト内容は決して含まない）— 違反ログとは別に保存されるため、監査ボリュームが /metrics を汚染しません。export_audit_log(fmt="csv") で監査人に引き渡せます。

• アラート — DISTIL_ALERT_WEBHOOK_URL（＋ DISTIL_ALERT_MIN_SEVERITY、デフォルト high）は、ガバナンスブロックまたは quarantine/approval の提出時にウェブフックを発火します。二重構造のペイロード: Slack 互換の text フィールドに加え、PagerDuty/Jira 自動化や汎用チケット取り込み用の構造化 distil_event。フェイルセーフ — 壊れたウェブフックが、それをトリガーしたリクエストに影響を与えることはありません。

• クロスプロバイダールーティング — route_provider_prompt(text)（route_prompt の階層のみの推奨とは異なり）は実際のプロバイダー＋モデルを選択します: PII/シークレットが検出されたプロンプトは、設定されている場合 DISTIL_TRUSTED_PROVIDERS（デフォルト local）に制限されます。候補は、キーが設定されているすべてのプロバイダー（OpenAI の小規模/大規模階層だけでなく）にわたって、最近のヘルス（core.availability、実際のゲートウェイトラフィックから供給）→ コストの順でランク付けされます。

管理エンドポイント（/audit、/review-queue/*、/exceptions/*、/alerts/test）は API の他の部分と同じ方法でゲートされます — 専用の x-admin-key 要件には DISTIL_ADMIN_KEY を設定します。Distil にはそれ以上のロール分離はまだないため、設定がない場合は有効な Distil キーなら誰でも呼び出せます。

デプロイ（サーバーレス、Vercel）

1. GitHub にプッシュし、Vercel にインポート（Python / Fluid Compute — 自動検出）。

2. 環境変数を設定: CONNECTOR_API_KEY（/mcp をゲート）、任意の OPENAI_API_KEY（品質モード）、任意の UPSTASH_REDIS_REST_URL ＋ _TOKEN（永続メトリクス。それ以外はローカル JSON ファイルを使用）。

3. コネクタ設定から Claude に追加 → https://<app>.vercel.app/mcp。

メトリクスダッシュボード: https://<app>.vercel.app/。

メトリクスリファレンス

レイアウト

core/                 compression + intelligence + estimates + metrics store
core/gateway.py        LLM Gateway request rewriting (no networking; pure logic)
mcp_server.py          FastMCP tools/resource
api/index.py            serverless ASGI entrypoint (MCP + dashboard + /metrics + auth)
api/gateway_routes.py   LLM Gateway HTTP routes (/v1/chat/completions, /v1/messages, /v1beta/...)
dashboard/             static metrics page
eval/                  measured evaluation
tests/                 unit tests (tests/test_gateway.py covers the gateway)

プロンプト圧縮エージェントから再利用

tiktoken カウント、フィラーリスト＋分析ロジック、メトリクスデータクラスのパターン、および OpenAI 配線（オプションの LLM パス用）。