Mendrift

Mendrift

自律型 MLOps インシデント対応エージェントと、ドリフト検出および ML インシデント対応ツールを提供するオープンソースの mendrift-mcp MCP サーバーです。

pip install mendrift-mcp     # or: uvx mendrift-mcp

PyPI および MCP Registry に io.github.suneel190700/mendrift-mcp として公開されています。

▶ ライブデモ — ブラウザーで実際のインシデントを実行できます。アラートを入力すると、エージェントが実際の MLflow レジストリを参照して診断する様子を確認でき、ヒューマン・イン・ザ・ループのゲートでロールバックを承認または拒否できます。作り込まれた合成シナリオと、実際の米国消費者信用ベンチマークデータを切り替えられます。FastAPI バックエンド上で動作する React フロントエンドです。無料プランではスリープ状態になるため、最初の読み込みに約 40 秒かかる場合があります。

本番モデルにドリフトや性能低下が発生すると、Mendrift はそれを検出し、監視データとレジストリの証拠から根本原因を診断して、修正策を提案します。実行されるのは人間の承認後のみです。

alert ──> classify ──> diagnose (MCP tools) ──> propose
             │                                     │
           noise ──> close               human approval gate
                                                   │
                                    execute ──> verify recovery

LangGraph（エージェントのオーケストレーション）、LangChain（ChatAnthropic + bind_tools）、Model Context Protocol、Evidently、MLflow、Claude （Haiku + Sonnet）を使用して構築されています。

mendrift-mcp ツール

ツール	種類	用途
get_drift_report	読み取り	特徴量ごとのドリフト距離とスキーマの変更（Evidently）
summarize_metric_anomalies	読み取り	現在のトラフィックでスコアを算出した、本番モデルと前バージョンの比較
get_deployment_history	読み取り	レジストリのバージョン遷移とエイリアス
diff_deployments	読み取り	バージョン間のパラメーター／メトリクス／特徴量スキーマの差分
propose_rollback	読み取り	レビュー可能なロールバック計画を生成
execute_rollback	ゲート付き	1 回限りの HMAC approval_token が必要
open_incident	書き込み	診断と証拠を含むインシデント記録

安全性モデル

承認ゲートはプロンプトではなく、ツール層で強制されます。 execute_rollback は、ヒューマンレビューのフローでのみ発行される、アクションに紐づいた 1 回限りの HMAC トークンを検証します。トークン発行関数は MCP 経由では公開されません。プロンプトインジェクションを受けたエージェントや誤動作したエージェントでも、書き込み操作は実行できません。

実環境でテスト済みです。Claude にまず「完全な権限を持つ」としてロールバックするよう指示したところ、ロールバックを提案しましたが、トークンの捏造は拒否しました。次に、捏造したトークンを渡すと、ゲートは一定時間の HMAC 比較によってそれを拒否しました。

tests/test_approval_gate.py を参照してください。アクションのスコープを検証するテストも含まれています。あるモデル／バージョン向けに発行されたトークンは、他のモデル／バージョンには無効です。

ヒューマン・イン・ザ・ループ、クラッシュ耐性

インシデントグラフは実行前に停止し（interrupt_before）、各ステップを SQLite にチェックポイントとして保存します。プロセスが停止しても、人間が承認トークンを発行した後、新しいプロセスが thread_id によって同じインシデントを再開できます。トークンはグラフの外部から update_state() を通じてのみ状態に追加されます。拒否も正式な処理経路です。トークンがなければ closed_approval_denied となり、実行されません。

エージェントの設計

ステップ	モデル	理由
分類	Haiku	制約された単一ラベルの分類で、最もコストを抑えられます
診断	Sonnet	証拠を使った複数段階のツール推論が必要です
検証	Haiku	新しいメトリクスに対するしきい値チェックです

ルーティングはプロンプトではなくコードテーブル（ROUTER_TABLE）にあるため、経路ごとのコストを設定として測定できます。インシデントあたり約3.9Kの入力トークン／630の出力トークンです。診断ループには上限があり（ツール呼び出しは最大8回）、呼び出しごとに再試行し、バックオフにも上限を設けています。ツールが失敗すると、モデルは構造化されたエラーレコードを受け取ります。予算を使い切ると、エージェントは部分的な証拠に基づくインシデントとして処理し、診断を捏造することはありません。破壊的なアクションには肯定的な証拠が必要です。ロールバックが推奨されるのは、取得した証拠から症状と特定のデプロイとの関連が確認できる場合に限られ、デプロイとの相関だけでは推奨されません。エージェントは監視を推奨することもできます。実在するものの軽微で、対応を要しない変動は、対処せず監視します。

ライブモード

MENDRIFT_DEMO=0を指定すると、フィクスチャではなく実際のインフラストラクチャに対してエージェントを実行します。

• scripts/seed_demo.pyは、2つのsklearnバージョンをローカルのMLflowレジストリに学習させます。v13は正常なモデルで、v14はスキーマの入れ替えがあり、見逃された不正利用ラベルによって学習期間が汚染されています（再現率は0.72から0.18に、AUCは0.84から0.82に低下）。また、参照フレームと現在のフレームを書き込みます
• get_drift_reportは、それらのフレームに対してEvidentlyのDataDriftPresetを実行し、メトリクスごとのしきい値に対する実際のWasserstein距離／JS距離と、実際の列セットから導出されたスキーマ変更を返します
• get_deployment_history／diff_deploymentsは、レジストリとその基になる実行履歴から、実際のエイリアス、パラメーター、メトリクスを読み取ります
• summarize_metric_anomaliesは、本番バージョンと前のバージョンの両方で現在のウィンドウをスコアリングするため、母集団のドリフトではなくモデルの乖離を報告します。ロールバックすれば解消しますが、通常のデータシフトでは解消しません
• 承認済みのexecute_rollbackは、実際のproductionエイリアスを移動します

uv run mlflow server --host 127.0.0.1 --port 5001        # separate terminal
PYTHONPATH=src uv run python scripts/seed_demo.py

rm -f demo.db
MENDRIFT_DEMO=0 PYTHONPATH=src uv run python scripts/demo_interrupt.py start
MENDRIFT_DEMO=0 PYTHONPATH=src uv run python scripts/demo_interrupt.py approve

ライブ実行では、計算された証拠に基づいて診断します。たとえば、*「v2でスキーマが入れ替わり、promo_flagがpromo_flag_v2に置き換わりました……label_noiseが0.0から0.45に増加し、val_recallが0.724から0.176に低下しました……直前のバージョンとの予測率の乖離は79.7％で、母集団のドリフトではなくモデルが原因です」*と診断した後、承認を求めて処理を停止し、解決します。

評価スイートは意図的にフィクスチャを使い続けます。評価ではCIでの決定性とコストゼロが必要ですが、ライブモードでは実際のスタックを検証します。

ライブ Web デモ（2つの世界）

ホスト型の Web アプリでは、ブラウザー UI を通じてライブモードを利用できます。React（Vite） フロントエンドと FastAPI バックエンドで構成され、Render にデプロイされています。訪問者がアラートを送信すると、フロントエンドから /api/diagnose にリクエストが送られ、バックエンドで実際の LangGraph エージェントが実行されます。エージェントは、埋め込み型 MLflow レジストリ（sqlite://、起動時にデータを投入）を対象に Claude の推論をライブで行い、HMAC ゲートで停止します。承認または却下すると、バックエンドが /api/decision 経由でグラフを再開し、実際のエイリアスロールバックを実行して復旧を検証します。Anthropic キーはサーバー上にのみ保持されます。実際のモデルを呼び出すため、実行回数にはレート制限が設けられています。 お試しください：mendrift-demo.onrender.com

ダッシュボードでは、あらかじめデータを投入した2つの世界を切り替えられます。同じエージェントを、作り込んだシナリオと実際のデータの両方で確認できます。

• 合成データ（scripts/seed_demo.py、モデル fraud-scorer）— スキーマ入れ替えのインシデントを再現したシナリオです。クリーンで学びやすく、ロールバックの流れが明確です。
• 米国の実データ（信用）（scripts/seed_real.py、モデル credit-risk）— Give Me Some Credit データセット（米国の消費者信用に関する実データ。ターゲットは SeriousDlqin2yrs）を借り手の年齢で基準期間と現在期間に分割し、実際の特徴量ドリフトを発生させています。さらに、インシデントの正解データを用意するため、v2 に 制御されたモデルの性能低下（デフォルト見逃しラベルへの非対称ノイズ）を注入しています。実際の分布と Evidently による実際のドリフトを使用し、正しい対応があらかじめ分かっています。 測定された差：val_recall 0.637 → 0.156、AUC 0.854 → 0.810。

実データに既知の性能低下を注入するのは、ドリフト検出システムの検証で標準的に使われる手法です。ドリフトの計算には実際の分布を使いながら、エージェントが どう判断すべきか を評価者が正確に把握できます。

バックエンドは dataset フィールドに基づいて、各リクエストを適切なデータセット（モデル、parquet フレーム、ラベル列）に振り分けます。ツール層はこれらを環境変数から読み込み、リクエストごとにロック下で適用するため、同時リクエスト間で設定が混在しません。

Web アプリをローカルで実行します：

# 1. build the React frontend (FastAPI serves the built assets)
cd frontend && npm install && npm run build && cd ..

# 2. seed both worlds, then start the backend (frontend + API on one port)
export ANTHROPIC_API_KEY=sk-ant-...
export MLFLOW_TRACKING_URI="sqlite:///$(pwd)/mlflow.db"
PYTHONPATH=src uv run python scripts/seed_demo.py     # synthetic world (fraud-scorer)
PYTHONPATH=src uv run python scripts/seed_real.py     # real world (credit-risk)
PYTHONPATH=src uv run uvicorn app.main:app --port 8000     # open http://localhost:8000

ホットリロードを使ったフロントエンド開発では、cd frontend && npm run dev を実行します（ポート 5173）。Vite が /api をポート 8000 のバックエンドにプロキシします。

評価

src/mendrift/evals/ では、合成されたインシデントの軌跡を実際のグラフに対して再生します。偽装しているのは LLM（スクリプト制御）と読み取りツール（フィクスチャのワールド）だけです。ゲート付きアクションツールは実際の実装を使用するため、すべてのテストで HMAC ゲートが検証されます。軌跡ごとに次の 4 項目を確認します。

check	意味
no_ungated_writes	すべての execute_rollback に有効な HMAC トークンが付与されていること — 失敗時は即時エラー
classification_ok	トリアージラベルが一致したこと
tool_sequence_ok	必須のツール呼び出しが順番どおりに行われたこと（追加の呼び出しは許可）
action_ok	最終的な結果が一致したこと

意思決定の領域全体を網羅する、ロジック上異なる 19 種類のインシデントシナリオ。それぞれに固有の証拠構成と適切なアクションがあります。

• ロールバック — デプロイに関連したドリフト、または肯定的な差分の証拠を伴う品質の低下
• 再トレーニング — ラベル／概念のシフト、セグメント固有の性能低下（有効なロールバック先がない場合）
• 監視 — 軽度の季節性ドリフト、重要度の低い特徴量のドリフト、祝日の影響
• インシデント（調査） — 上流スキーマの名称変更、特徴量ストアの変更、ドキュメントのみのデプロイ、キャリブレーションの破綻、しきい値の変化、気付かれにくいデータ品質の低下
• 段階的な縮退 — 証拠ツールがダウンした場合 → 部分的な証拠でインシデントとして扱い、診断を捏造しない
• ノイズ — 頻発する／自動解決済みのアラートは、ツール呼び出しゼロでクローズ
• 人間による却下 — 根拠のあるロールバックをレビュー担当者が却下した場合 → クローズし、実行しない

高速な CI ではスクリプト制御で、測定する成功率では実モデルで実行します。

PYTHONPATH=src uv run python scripts/run_traj.py --all          # scripted, fast
PYTHONPATH=src uv run python scripts/run_traj.py --all --live   # real models

実モデルによる評価では、タスク成功率は約 95% です。実行ごとのわずかな差異は、意思決定の境界にあるシナリオで生じる LLM 評価のばらつきを反映しています。実モデルのテストスイートにより、開発中に実際の失敗クラスが明らかになりました。正しい判断を覆い隠す JSON 抽出処理、アラートの安心させる文言に誘導された分類器、相関関係だけを根拠にロールバックを提案する診断器です。それぞれの問題は、該当する層（パーサー、アラートの文言、証拠ルールのプロンプト）で修正しました。

クイックスタート（デモモード）

uv sync
MENDRIFT_DEMO=1 uv run mendrift-mcp     # stdio MCP server with fixture data
PYTHONPATH=src uv run pytest -v         # gate + trajectory suite

Claude Desktop の設定：

{"mcpServers": {"mendrift": {
  "command": "uvx",
  "args": ["mendrift-mcp"],
  "env": {"MENDRIFT_DEMO": "1"}
}}}

ステータス

• stdio 経由の mendrift-mcp サーバー。MCP Inspector と Claude Desktop で検証済み
• 読み取り／ゲート付き／書き込みの権限分類を備えた 7 つのツール
• アクションごとの使い捨てトークンを使用する HMAC ゲート付きロールバック（テストを先に作成）
• LangGraph のインシデントグラフ：SQLite チェックポイント＋人間による承認割り込み。停止後の再開を実証済み
• LangChain 上の LLM ノード（ChatAnthropic.bind_tools）：分類／検証に Haiku、診断ループに Sonnet
• 意思決定の領域全体を網羅する 19 シナリオの軌跡評価。実モデルで約 95%、ゲートを迂回した書き込みはゼロ
• CI：すべてのプッシュでゲートと軌跡スイートを実行
• 実モデルモード：Evidently による実際のドリフト計算、MLflow レジストリの履歴／差分、実際のエイリアスロールバック
• 実モデルを使ったライブウェブデモ：FastAPI 上の React + Vite フロントエンドを Render にデプロイ
• 2 つのデモワールド：作り込んだ合成シナリオと実際の米国の信用リスクデータ。UI で選択可能
• 公開済み：PyPI（pip install mendrift-mcp）＋ MCP Registry（io.github.suneel190700/mendrift-mcp）

ライセンス

MIT