内容
# 合规监测
> 使用Claude API的合同和发票审计系统。
合规监测系统会对内部财务文件（发票、合同、补充协议）中的异常进行标记，以便进行人工合规审查。每个发现结果都可以追溯到一个确切的源摘录，并具有明确的置信度——而非不透明的自动指控。
---
[🇺🇸 英语](README.md) · [🇧🇷 葡萄牙语](README.pt-br.md)
---
**本项目使用的所有数据均为100%合成数据。** 项目中没有引用任何真实的公司、个人或公共实体——无论是在代码、数据集、示例还是文档中。请参阅 [`docs/data-disclaimer.md`](docs/data-disclaimer.md)。
## 截图
| 重复发票 — 高风险 | 被阻止的供应商 — 高风险 |
|---|---|
|  |  |
| 价格异常 — 高风险 | 清洁合同 — 低风险 |
|---|---|
|  |  |
> **无需API密钥试用：** 直接在任何浏览器中打开 `frontend/demo.html` — 无需服务器。
>
> **实时模式（真实Claude）：** 将您的 `ANTHROPIC_API_KEY` 添加到 `.env`，运行 `python frontend/app.py`，然后打开 `http://localhost:8080`。有关从演示到生产的完整转换指南，请参阅 [`docs/dev-setup.md`](docs/dev-setup.md)。
## 架构
```
文档到达（发票/合同/补充协议）
→ [路由：分类文档类型] Haiku — 便宜、快速
→ [实体提取] 预填充 + 停止序列 → 清洁JSON
→ [并行化：合规性检查] asyncio.gather → 被阻止的供应商/价格异常/重复
→ [检索器：交叉引用历史] BM25 + 余弦向量 → 互惠排名融合
→ [链式：草稿 → 引文审查] 两步链式；第二次传递温度=0
→ 最终可审计报告 每个声明都有引文
```
深度调查 **代理** (`agent/investigacao_profunda.py`) 是唯一的代理组件 — 由合规分析师在已标记的案件中手动触发。请参阅 [`docs/architecture-decision.md`](docs/architecture-decision.md)。
## 评估指标
> 在设置您的 `.env` 后，运行 `python evaluation/run_eval.py` 以填充本部分。
| 提示版本 | 平均分数（模型评分器） | 引文通过率 | DoD 门控 |
|---|---|---|---|
| 基线（存根） | — | — | 运行评估以填充 |
## 技术栈
- **Claude API** — Haiku（路由/生成）、Sonnet（分析）、Opus（高风险代理回合）
- **VoyageAI** — `voyage-3-large` 嵌入式语义搜索
- **BM25** + 余弦向量搜索 → 互惠排名融合混合检索器
- **MCP服务器** (`fastmcp`) — 3种合规工具 + 资源 + 提示
- **PDF原生支持 + 引文** — 每个文档块都有 `citations.enabled=True`
- **文件API + 代码执行** — 统计价格异常检测
- **扩展思考** — 在调查代理中条件激活
## 涵盖的技术
每个组件都映射到Claude API的特定功能：
| 技术 | 组件 |
|---|---|
| 多轮对话 | `core/claude_client.py` — 消息历史 |
| 系统提示 | `prompts/system_auditor.py` — 角色 + 策略 |
| 温度控制 | `MAX_ANALYSIS_TEMPERATURE = 0.2` 跨所有分析调用 |
| 流式传输 | `frontend/app.py` + `streaming_tools.js` — token-by-token UI |
| 结构化数据（预填充 + 停止） | `extraction/entities.py` — 清洁JSON提取 |
| 工具使用 | `tools/` + `core/run_conversation.py` — 4种合规工具 |
| 工具模式 | `tools/schemas.py` — `ToolParam` 模式 |
| RAG（分块 + 嵌入） | `rag/` — VoyageAI + 余弦索引 |
| BM25词汇搜索 | `rag/bm25_index.py` — 确切合同编号查找 |
| 混合检索（RRF） | `rag/retriever.py` — 合并语义 + 词汇 |
| 扩展思考 | `agent/investigacao_profunda.py` — 条件、低置信度仅限 |
| PDF支持 | `extraction/pdf_reader.py` — 文档块 |
| 引文 | 每个文档分析调用都强制执行 |
| 提示缓存 | `with_cache()` 在系统提示 + `tools_with_cache()` |
| 文件API + 代码执行 | `analysis/preco_stats.py` — 价格异常统计 |
| MCP服务器 | `mcp_server/` — 工具、资源、提示 |
| MCP客户端 | `mcp_client.py` — 异步上下文管理器 |
| 路由工作流 | `pipeline.rotear_tipo_documento` |
| 并行化工作流 | `pipeline.avaliar_politicas` — asyncio.gather |
| 链式工作流 | `pipeline.gerar_e_revisar` — 草稿 → 引文审查 |
| 代理 | `agent/investigacao_profunda.py` — 仅在需要灵活性时 |
| 评估管道 | `evaluation/` — 生成 → 评分 → 平均 → DoD门控 |
| 模型评分器 | `evaluation/graders/model_grader.py` — 预填充强制输出顺序 |
| 代码评分器 | `evaluation/graders/code_grader.py` — 引文硬门控 |
| 图像支持 | `extraction/scanned_pages.py` — 扫描页视觉分析 |
## 设置
```bash
git clone https://github.com/robertogfortes/compliance-watch.git
cd compliance-watch
cp .env.example .env
# 填写 ANTHROPIC_API_KEY 和 VOYAGE_API_KEY
uv sync
python scripts/smoke_test.py # 验证设置
```
有关完整说明，请参阅 [`docs/dev-setup.md`](docs/dev-setup.md)。
## 运行
```bash
# Web UI（流式 + 可点击引文）
python frontend/app.py
# → http://localhost:8080
# CLI 管道
python -c "from pipeline import auditar_documento; print(auditar_documento(open('tests/fixtures/invoice_cortex_005.pdf', 'rb').read().decode('latin-1', errors='ignore'))['report'])"
# 深度调查代理（手动，在标记的案件中）
python agent/investigacao_profunda.py --case "Duplicate invoice suspected" --document tests/fixtures/invoice_cortex_005.pdf
# MCP 检查器
mcp dev mcp_server/server.py
# 评估
python evaluation/generate_dataset.py
python evaluation/run_eval.py
```
## 灵感
该项目是作为应用顶点项目而构建的，同时完成了 **[使用Claude API构建](https://verify.skilljar.com/c/bgpvpoxjuqsg)** 课程。每个系统组件都直接映射到课程中涵盖的模块 — 从基本的API访问和工具使用到RAG、评估管道、MCP服务器和多步骤代理工作流。
