Mendrift

Mendrift

自主 MLOps 事件响应 Agent，以及 mendrift-mcp——一个用于漂移检测和 ML 事件处理工具的开源 MCP 服务。

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

已发布到 PyPI 和 MCP Registry，名称为 io.github.suneel190700/mendrift-mcp。

▶ 在线演示——在浏览器中运行真实事件：提交警报，查看 Agent 根据真实 MLflow 注册表进行诊断， 并在人类参与审核关卡批准或拒绝回滚。在精心设计的合成场景与真实的美国消费信贷基准数据之间切换。React 前端运行在 FastAPI 后端上；免费套餐会休眠，因此首次加载可能需要约 40 秒。

当生产模型发生漂移或性能下降时，Mendrift 会检测问题、根据监控和注册表证据诊断 根本原因、提出补救方案，并且仅在获得人工批准后执行。

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

基于 LangGraph（Agent 编排）、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	受限	需要一次性 HMAC approval_token
open_incident	写入	创建包含诊断和证据的事件记录

安全模型

审批关卡在工具层而非提示词中实施： execute_rollback 会验证一次性、限定操作范围的 HMAC 令牌，该令牌只能由人工审核流程签发——签发函数绝不会通过 MCP 暴露。受到提示词注入或陷入混乱的 Agent 无法执行写入操作。

实测结果：Claude 最初被要求“在获得完全授权的情况下”回滚 （它提出回滚方案，但拒绝伪造令牌），随后收到一个伪造的 令牌，审批关卡通过恒定时间 HMAC 比较拒绝了它：

参见 tests/test_approval_gate.py，其中包括操作范围测试：为一个模型/版本签发的令牌对其他任何模型/版本均无效。

人类参与流程，崩溃后可恢复

事件图会在执行前暂停（interrupt_before），并将每个步骤检查点保存到 SQLite。进程可以终止；人工签发审批令牌后，新进程可通过 thread_id 恢复同一事件——该令牌只能从图外通过 update_state() 写入状态。拒绝是一个正式处理路径：没有令牌 → closed_approval_denied，不执行操作。

Agent 设计

步骤	模型	原因
分类	Haiku	单一受限标签；成本最低的路径
诊断	Sonnet	基于证据进行多步工具推理
验证	Haiku	对最新指标进行阈值检查

路由定义在代码表（ROUTER_TABLE）中，而非提示词中，因此每条路径的成本是可衡量的配置——每个事件约 3.9K 个输入令牌 / 630 个输出令牌。诊断循环设有上限（最多 8 次工具调用），每次调用均可重试，并采用封顶退避；工具调用失败时，模型会收到结构化错误记录；预算耗尽时，Agent 会降级为仅含部分证据的事件——绝不捏造诊断结果。执行破坏性操作必须有确凿证据：只有当检索到的证据将症状与特定部署关联起来时，才会建议回滚，绝不会仅凭部署相关性就建议回滚。Agent 也可以建议监控——对于确实存在但程度较轻、无需采取行动的漂移，只进行监控，不采取行动。

实时模式

MENDRIFT_DEMO=0 会让 Agent 使用真实基础设施运行，而非测试夹具：

• scripts/seed_demo.py 将两个 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 演示（两个场景）

托管的 Web 应用通过浏览器界面封装了实时模式：前端采用 React (Vite)，后端采用 FastAPI，部署在 Render 上。访客提交警报后，前端会将其发送到 /api/diagnose，后端运行真正的 LangGraph Agent——基于嵌入式 MLflow 注册表（sqlite://，启动时填充数据）进行实时 Claude 推理——然后在 HMAC 闸门处暂停。批准或拒绝后，后端会通过 /api/decision 恢复图的运行，执行真正的别名回滚并验证是否恢复。Anthropic 密钥仅保存在服务器上；由于每次运行都会调用真实模型，因此会进行速率限制。 试用：mendrift-demo.onrender.com。

仪表板可在两个预置场景间切换，因此可以看到同一 Agent 如何处理精心设计的场景和真实世界数据：

• 合成数据（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。

在真实数据中注入已知回归，是验证漂移检测系统的标准做法——这让评估者知道 Agent 应该如何决策，同时漂移计算仍基于真实数据分布运行。

后端根据 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（脚本化）和读取工具（fixture world）是伪造的；受门控的操作工具使用的是真实实现，因此每项测试都会触发 HMAC 门控。每条轨迹包含四项断言：

检查项	含义
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%；少数运行间的差异源于大模型在决策边界场景中的评估波动。实时测试套件在开发过程中发现了真实的故障类别——掩盖正确决策的 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 中验证
• 提供七种工具，按读取／受门控／写入权限分类
• 使用按操作范围限定的一次性令牌进行 HMAC 门控回滚（先编写测试）
• LangGraph 事件图：SQLite 检查点 + 人工审批中断，已验证终止后恢复
• 基于 LangChain 的 LLM 节点（ChatAnthropic.bind_tools）：Haiku 用于分类／验证，Sonnet 用于诊断循环
• 覆盖整个决策空间的 19 种场景轨迹评估；实时成功率约为 95%，无未受门控的写入
• CI：每次推送都运行门控和轨迹测试套件
• 实时模式：使用 Evidently 进行真实漂移计算，使用 MLflow 记录注册表历史／差异，并执行真实别名回滚
• 实时 Web 演示：基于 FastAPI 的 React + Vite 前端，部署在 Render 上
• 两种演示场景：精心构造的合成场景 + 真实的美国信用风险数据，可在 UI 中选择
• 已发布：PyPI（pip install mendrift-mcp）+ MCP Registry（io.github.suneel190700/mendrift-mcp）

许可证

MIT