funcpointer/interlock-ai
GitHub: funcpointer/interlock-ai
这是一个AI驱动的工程PDF跨文档差异检测系统，用于自动识别参数不匹配并评估严重性。
Stars: 0 | Forks: 0
# nglish. "AI" is common technical jargon, so I might keep it as "AI".
工程PDF跨文档差异检测。审阅者上传同一项目的两个PDF文件；系统以**带身份感知的配对**、**配对置信度评分**、**诚实未配对记录展示**以及可选的LLM重要性判断，呈现带方向性、引用性的**严重性分级**参数不匹配。
**实时演示：** https://interlock-ai-re8mb948inkerzmkn5zpgv.streamlit.app/ (Streamlit Cloud 免费层 — 首次访问可能因冷启动需约30秒)
- PRD: [`docs/PRD.md`](docs/PRD.md) — 审阅者画像、切入点、5层平台路径
- TDD: [`docs/TDD.md`](docs/TDD.md) — 架构、容差范围、评估、已知限制
- 架构图: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — 控制流、数据流、缓存层次
- 著作权: [`docs/AUTHORSHIP.md`](docs/AUTHORSHIP.md) — 哪些是构建的/复用的/披露的，按阶段
- 演示脚本: [`docs/DEMO_SCRIPT.md`](docs/DEMO_SCRIPT.md) — 3分钟演练
- 锁定范围 + 测试数据: [`docs/SCOPE.md`](docs/SCOPE.md), [`docs/FIXTURES.md`](docs/FIXTURES.md)
- 风险登记册: [`docs/RISK_REGISTER.md`](docs/RISK_REGISTER.md)
- 待办事项（超出范围）: [`docs/BACKLOG.md`](docs/BACKLOG.md)
## 快速开始（本地）
```
uv sync
uv run pytest --deselect tests/real_world # 261 tests, ~1:30 wall-clock
uv run streamlit run src/interlock/ui/app.py
```
## 系统要求
- Python 3.12 (在 `.python-version` 中固定)
- [uv](https://github.com/astral-sh/uv)
- Ghostscript (Camelot 依赖): `brew install ghostscript`
- `.env` 已从 `.env.example` 填充：
- `VOYAGE_API_KEY` — 必需（语义对齐 + 规范术语表）
- `ANTHROPIC_API_KEY` — 视觉OCR回退（任何扫描PDF页面）和可选的LLM重要性判断所必需
## 演示
仓库附带了两对测试数据。
### 选项 1 — 修订版差异（60% 基准 ↔ 90% 修订版）
- `doc_a_60pct.pdf` — 文档 A（权威版，真实的Eaton样本协调研究）
- `doc_b_90pct.pdf` — 文档 B（下游版，衍生自文档 A，包含6处有文档记录的变更 — 见 `fixtures/mutations/MUTATIONS.md`）
预期结果：**4个标记**，全部归类为**严重**严重性 — 均属于小数点移位类（`%Z 5.75 → 0.575`, `故障电流 20,000 → 200,000 A`, `变压器额定值 1000 → 100 kVA` × 2处）。零误报。FP-1单位等效陷阱（`150 kVA` vs `0.15 MVA`）通过Pint单位标准化被抑制。默认抑制信息级别内的容差变化（降低置信度阈值滑块可使其显示）。
### 选项 2 — 跨文档（设备规格书 ↔ 协调研究）
- `spec_xfmr_001.pdf` — 文档 A（权威版，合成的变压器设备数据表；见 `docs/AUTHORSHIP.md` 的披露说明）
- `doc_a_60pct.pdf` — 文档 B（下游版，复用相同的Eaton研究）
预期结果：通过语义对齐 + 规范术语表显示**3个标记**：
- `额定功率 1100 kVA ↔ 变压器额定值 1000 kVA`（次要，偏差9%）
- `一次电压 12.47 kV ↔ 系统电压 13.8 kV`（主要，偏差10.7%，配对置信度0.90）
- `额定阻抗 4.5 % ↔ %Z 5.75 %`（主要，偏差28%）
另外，在“📋 未配对记录”展开部分显示规格书侧的**4条未配对记录**（二次电压、频率、BIL、绝缘等级 — 在研究中无对应项）以及研究侧的**49条未配对记录**（熔断器标识符 + 重复变压器引用 — 在规格书中无对应项），以诚实报告差距。在侧边栏切换 **使用LLM重要性判断** 可为每个标记添加工程原理 + 下游效应传播的注释（Anthropic Opus 4.7，提示缓存）。
### 选项 3 — 扫描PDF（视觉OCR + 合理性再OCR）
- `doc_a_scanned.pdf` — `doc_a_60pct.pdf` 的JPEG编码栅格图（每页纯图像，零原生文本）
在侧边栏启用 **视觉OCR**；数据摄取会将每个低覆盖率页面通过Claude Sonnet 4.5（300 DPI）处理，并在某个数值超出其数据族合理性范围时，以400 DPI进行验证性再OCR处理。UI中显示每页进度条。可与 `doc_b_90pct.pdf`（或任何其他文档）配对，基于提取的文本进行完整审阅。恢复54个参数，而原生基线为52个（104%的产出率）。
A/B比较证实选项2展示了选项1无法实现的能力：
```
uv run python scripts/run_ab.py
cat eval/results/ab_comparison.json
```
## 评估
```
uv run python scripts/run_eval.py
cat eval/results/baseline.json
```
黄金数据集：`fixtures/eval/gold.yaml`。验收阈值锁定在 `docs/FIXTURES.md` 第6节（对真正正例的召回率=1.0，对陷阱的误报率=0.0）。
## 部署（Streamlit Cloud）
1. 使用拥有此仓库的GitHub账户登录 https://share.streamlit.io 。
2. 新建应用 → 仓库 `funcpointer/interlock-ai`, 分支 `main`, 主文件 `streamlit_app.py` (根入口垫片；实际UI在 `src/interlock/ui/app.py`)。
3. 高级设置 → Python 3.12。
4. 密钥 → 将 `VOYAGE_API_KEY` 和 `ANTHROPIC_API_KEY` 以TOML格式粘贴。
5. 部署。
`packages.txt` 声明了 `ghostscript`，以便Camelot的格栅解析器能在云运行器上工作。
## 访问说明
| 资产 | 位置 | 审阅者如何访问 |
|---|---|---|
| 源代码 | https://github.com/funcpointer/interlock-ai | 公开只读。阶段标签和 `v1.*` 检查点提供时间点快照。 |
| 已部署原型 | https://interlock-ai-re8mb948inkerzmkn5zpgv.streamlit.app/ | 公开只读。首次访问因冷启动约需30秒（Streamlit Cloud免费层）。 |
| 演示视频 | (录制后添加URL) | 公开只读。 |
| 测试数据PDF | 仓库中的 `fixtures/pdfs/` | 在git中跟踪。真实的Eaton文档是公开样本；合成测试数据在 `docs/AUTHORSHIP.md` 中披露。 |
| 评估黄金数据集 | `fixtures/eval/gold*.yaml` | 在git中跟踪。验收阈值在 `docs/FIXTURES.md` 第6节。 |
| API密钥 | 不在仓库中（`.env` 已被git忽略） | 审阅者自带 `VOYAGE_API_KEY` 和 `ANTHROPIC_API_KEY` 用于本地运行；已部署的Streamlit Cloud实例已在服务器端配置。 |
| 内部会话记录/规划笔记 | `docs/superpowers/`, `CLAUDE.md` | 已被git忽略。不属于提交内容。 |
## 阶段标签
仓库的历史被划分为TDD阶段；每个阶段以一个可验证的检查点标签结束。
```
phase-0-scaffold phase-3-extract phase-6-citation
phase-1-fixtures phase-4-align phase-7-ui
phase-2-ingest phase-5-detect phase-8-eval
phase-9-deploy phase-11-cross-doc phase-12-real-world
phase-13-tolerance phase-14-entity-claim phase-17-deliverables
phase-18-ux-ocr phase-19-identity-alignment phase-20-ocr-quality
v1.0-mvp · v1.1-cross-doc · v1.2-real-world · v1.3-tolerance ·
v1.4-entity-claim · v1.5-mvp-ready
```
**测试覆盖范围（v1.5-mvp-ready）：** 261个通过（默认），83个标记为慢速 + 实时API测试被排除，mypy严格检查通过，ruff检查通过。每次演示运行成本低于0.10美元（利用diskcache + Anthropic 1小时提示缓存本体块）。对9页扫描测试数据启用OCR运行：冷启动约0.45美元，热启动约0美元。
标签：AI审核, Apex, API集成, Kubernetes, OCR, PDF差异检测, Python, Streamlit, 严重性分级, 制造, 包管理, 参数匹配, 可观测性, 工程文档, 工程管理, 建筑, 控制流, 数据流, 文档处理, 无后门, 机器学习, 机械工程, 测试驱动开发, 缓存层次, 置信度评分, 表格提取, 视觉AI, 访问控制, 跨文档比较, 身份感知, 逆向工具