UK Break Clause Analyzer

UK 解约条款分析器（MCP）

一个可自我评估的 MCP 服务，用于判断英国商业租约的租户是否真的能够 行使解约条款，并公布自身测得的幻觉率。

⚖️ 仅用于辅助决策，非法律建议。 本工具基于合成数据，采用刻意 简化且非专有的规则集。任何实际决策都必须由具备资质的律师审核。

---

200 万英镑的句号

2012 年，一名租户及时送达了有效的解约通知，准备解除租约——但在解约日，他们 尚未支付几周前到期的一季度租金。解约失败了。他们因此被租约及其租金 绑定了多年。没有戏剧性场面，也没有恶意——只是有一项先决条件未满足，直到为时已晚才被所有人发现。

解约条款就是如此无情。租户能否真的离开，取决于一份简短的检查清单——是否及时送达通知、通知送达方式是否正确、是否拖欠租金、是否交付空置占有——其中任何一项出错都可能造成灾难性后果。这正是你可能会交给大模型处理的任务……前提是你能相信它不会信誓旦旦地编造答案。

本项目旨在赢得这种信任，并对其进行衡量。 它不是一个巧妙的解析器，而是一个可靠性测试框架：每项主张都必须有逐字引用的原文支撑，否则就不会作出；真正含糊不清的案例会交由人工处理，而不是靠猜测；项目还附带一套评估机制，用于公布它说谎的频率。

优势

• 有据可依——每项断言的条件都有逐字引用的原文片段作为依据。如果系统找不到对应文本，就会返回 NOT_FOUND；它绝不会编造引文。确定性关卡会从原文中截取该片段，因此系统不可能回显幻觉生成的文本。
• 经过校准——当租约确实无法明确某个问题时，答案是 AMBIGUOUS — human verify，而不是抛硬币式地猜测。坦诚弃答是一项功能。
• 可自我评估——pytest 测试框架会基于 24 个已标注案例评估抽取准确率、引文忠实度、幻觉率和校准情况。
• 负责推理与验证——大模型只负责提出建议；确定性代码负责作出判断（核验每条引文、计算日期、应用空置占有法律测试，并汇总结论）。

核心数据

完整评估见 report/report.md（包含全部四项指标、 模型间对比、混淆矩阵和已捕获幻觉的示例）。

仓库中提交的报告是启发式基线（无需 API 密钥即可运行）——它已经揭示了核心结论：依据核验关卡将无依据（捏造的）幻觉降至零，而非推理基线仍会错误归因，并且在真正含糊的案例中从不弃答。这正是经过校准的大模型应当弥合的差距：

uv run python scripts/run_eval.py --record   # measure claude-haiku-4-5 vs claude-sonnet-4-6

工作原理

flowchart LR
    A["Lease + Background Facts"] --> T["MCP tools"]
    T --> L["LLM adapter<br/>extract + reason · temperature 0"]
    L -- "proposes verbatim quotes<br/>+ findings" --> G{"Grounding gate<br/>verbatim? else NOT_FOUND"}
    G -- "spans sliced from source" --> C["Deterministic core<br/>checklist · UK date math · VP legal test"]
    C --> R["Strict-precedence aggregate<br/>fail→INVALID · uncertain→AMBIGUOUS · else VALID"]
    R --> O["Assessment<br/>verdict + calibration + human-verify gates"]
    subgraph EVAL["Eval (the point)"]
      D["24 labelled cases"] --> H["harness"] --> M["4 metrics"] --> P["report.md + SVG"]
    end

信任边界是结构性的：确定性 core/ 包在物理上无法导入 llm/ 包（由测试强制执行）。“大模型提出建议，确定性代码作出判断”是代码库本身的特性，而不是一项行为准则。

四个 MCP 工具（各司其职）

工具	功能
extract_break_clause	返回解约条款及其逐字原文片段
check_conditions	四项条件检查清单：逐项标记通过／不通过／不确定，并提供有据可依的证据
find_citation	返回支持某项主张的准确逐字原文，或返回 NOT_FOUND
assess_validity	编排后的结论、校准说明，以及必须由人工核验的关卡

快速开始（从克隆到运行，不到 2 分钟）

# 1. Install uv (skip if you have it)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Install deps (uv fetches its own Python 3.12)
uv sync

# 3. Run the test suite — proves the eval apparatus is correct
uv run pytest -q

# 4. Check the dataset (every gold span verbatim, every label coherent)
uv run python scripts/validate_dataset.py

# 5. Regenerate the eval report
uv run python scripts/run_eval.py        # heuristic baseline, no key needed

以上所有操作都不需要 ANTHROPIC_API_KEY——评估会回退到启发式基线，并且可以完全复现。设置该密钥（并使用 --record）即可评估实际的 Claude 模型。

你的 Anthropic API 密钥

只有在进行实时 LLM 提取时（eval 的 --record 步骤和服务的真实模式）才需要此密钥。其他所有操作都无需密钥。

• 切勿提交此密钥。 .env 已加入 Git 忽略列表，录制文件会对 x-api-key 标头进行脱敏。
• 运行本地命令时，可以导出密钥，也可以使用 .env 文件：

  export ANTHROPIC_API_KEY=sk-ant-…           # option 1: shell
  # or
  cp .env.example .env && $EDITOR .env          # option 2: .env, then:
  uv run --env-file .env python scripts/run_eval.py --record
  

• 使用 MCP 客户端时，将密钥填入服务配置的 env 区块（见下文）。

运行 MCP 服务

# Inspect it interactively (the official MCP Inspector)
npx @modelcontextprotocol/inspector uv run break-clause-analyzer

Claude Desktop — 添加到 claude_desktop_config.json（使用克隆仓库的绝对路径， 以便从项目目录运行）：

{
  "mcpServers": {
    "break-clause-analyzer": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/rubo-mcp", "break-clause-analyzer"],
      "env": { "ANTHROPIC_API_KEY": "sk-ant-…" }
    }
  }
}

Claude Code — 运行一条命令：

claude mcp add break-clause-analyzer -e ANTHROPIC_API_KEY=sk-ant-… \
  -- uv run --directory /absolute/path/to/rubo-mcp break-clause-analyzer

即使没有密钥，服务仍会运行并作出响应——它会使用启发式基线，并明确说明这一点。每条工具响应都会附带决策支持免责声明。

可复现的评估（录制文件）

temperature=0 并不保证 API 输出具有确定性，因此，可复现性依赖于录制文件（VCR.py）。scripts/run_eval.py --record 会为每个模型录制一组录制文件，并对 x-api-key 标头进行脱敏；之后无需密钥即可在数秒内重新运行并回放。如需了解详情，请参阅 eval/cassettes/README.md。

目录结构

src/break_clause_analyzer/
  core/       # deterministic trust boundary (no network; cannot import llm/)
    grounding.py  dates.py  checklist.py  aggregate.py
  llm/        # the only network egress (Anthropic + heuristic fallback)
  pipeline.py # propose → gate → dispose orchestration
  server.py   # FastMCP server: the four tools
data/cases/   # 24 labelled synthetic case files (+ dataset README)
eval/         # harness, metrics, report generator, cassettes
docs/METHODOLOGY.md  # pre-registered metric definitions
report/       # generated eval report + SVG
.planning/    # the eval-first roadmap, requirements, and decision log

方法与诚实性

指标定义已在运行任何模型之前预先注册于 docs/METHODOLOGY.md，因此无法事后定义关键数字来美化结果。幻觉率统计错误依据和过度自信，而不只是捏造内容——因为设置依据核验关卡后，捏造内容很容易降为零。评分器不使用 LLM 评审；它通过金标准预言机和刻意破坏的系统进行验证，详情见 tests/test_harness.py。

范围（刻意限定）

仅涉及租户解约条款 · 四项先决条件 · 仅使用合成数据/公开数据 · 用于决策支持，而非法律建议。其他租赁条款、房东解约权、真实客户端数据和生产引擎均明确不在范围内。

---

作为可靠性工程成果构建。评估才是重点。