ClauseIQ

<div align="center"> # 条款智识 **一款多智能体AI系统，读取印度合同，标记对您不利的条款，并附有严重性评分，同时引用印度法律的具体条款。** 在网络上以流媒体应用运行 **和** 在Claude Desktop中作为MCP服务器运行。 **[▶ 在线应用](https://clause-iq-mu.vercel.app/)** · [安装到Claude Desktop (MCP)](docs/MCP_INSTALL.md) </div> --- ## 问题 印度人民每天签署租房、就业和自由职业合同，其中包含 **不公平或无法强制执行** 的条款，但他们无法分辨哪些条款是不公平的。诸如12个月锁定期，丧失您的 **全部** 押金；两年内印度范围内的不竞争条款；"在7天内提出异议，否则永久失去"。律师费用昂贵；通用AI聊天机器人会编造不存在的法律条款。 条款智识是我希望存在的工具：它读取合同，标记具有1-5严重性评分的风险条款，用通俗语言解释 **为什么** ，并且 **为每个标记提供真实、经过验证的引用** 到1872年印度合同法。 ## 在线演示 > 添加GIF/截图：`docs/assets/demo.gif`，`docs/assets/analysis.png`。 - **网络应用：** **https://clauseiq-app-fawn.vercel.app** — 粘贴合同或上传PDF，实时观看智能体工作。 - **API：** `https://clauseiq-api-124621416027.asia-south1.run.app` （Cloud Run；`GET /health` 用于存活检查，`/docs` 用于OpenAPI UI）。 - **在Claude Desktop (MCP)中：** 询问 *"分析此合同中的不公平条款"* — 参见 [docs/MCP_INSTALL.md](docs/MCP_INSTALL.md)。 ## 系统架构 一个应用核心，通过两个前端（REST/流媒体API和MCP服务器）暴露。分析本身是一个 **LangGraph** 状态机，由四个智能体组成： ```mermaid flowchart LR subgraph 客户端 网络[React应用<br/>SSE流媒体] 克劳德[克劳德桌面<br/>MCP] end 网络 -->|POST /analyze/stream| API[FastAPI] 克劳德 -->|stdio| MCP[MCP服务器] API --> 核心 MCP --> 核心 subgraph 核心[应用核心 - LangGraph] 方向 LR S[监管者<br/>分段 + 屏幕] --> R[检索者<br/>混合搜索] --> RA[风险分析者<br/>评分1-5] --> CV[引用验证者<br/>消除幻觉] end R -.-> VS[(ChromaDB + BM25<br/>印度合同法)] S & RA -.-> G[Gemini 2.5<br/>闪存 + 专业] 核心 --> OBS[Langfuse + 成本跟踪] ``` 混合检索融合稠密向量（ChromaDB）和词典BM25，通过互惠排名融合。 **引用验证者** 是反幻觉保证：任何未在语料库中的引用部分在您看到之前都会被删除。 ## 关键设计决策 1. **一个核心，两个前端（双模式MCP）。** 智能体生活在应用层，对传输一无所知；FastAPI和MCP服务器是同一`ContractAnalyzer`上的薄适配器。 *权衡：* 严格的六边形边界需要更多的前期结构，但这就是为什么相同的分析在浏览器和Claude Desktop中运行，没有重复的逻辑。 2. **通过Vertex AI使用Gemini，具有自动回退到AI Studio的功能。** 在`gemini-2.5-flash`上进行编排，在`gemini-2.5-pro`上进行分析。在生产环境中，它在 **Vertex AI** 上运行（计费到GCP积分，通过Cloud Run服务账号认证 — 服务器上没有密钥）；如果Vertex不可用或积分用完，客户端 **自动回退到AI Studio密钥** ，因此应用继续运行。 *权衡：* 单一供应商（Google）依赖，换取几乎零成本，强大的结构化输出和弹性 — 而且通过用户自己的Claude Desktop上的MCP，Claude仍然是免费的。 3. **确定性引用指标，而不仅仅是LLM裁判。** 引用准确性针对实际法规（存在 + 文本重叠）进行检查，因此反幻觉保证永远不会依赖另一个模型的意见。 *权衡：* 它只会捕获引用错误，因此它与LLM裁判的忠实度配对使用。 4. **评估关口CI。** 20个案例的黄金数据集在CI中运行；如果忠实度或引用准确性回归，构建失败。 *权衡：* 更慢，耗费令牌的CI，但提示回归不能悄悄发布。 5. **预期失败的结果类型 + 异常防护。** 预期失败（非合同，提示注入，缺失法律）是类型化的`Result`值和显式防护，而不是堆栈跟踪。 *权衡：* 调用站点更详细，API/MCP边界的行为更可预测。 ## 评估结果 使用DeepEval在完整的20案例黄金数据集（5个每个：租赁，就业，NDA，供应商）上进行衡量。LLM裁判指标使用Gemini作为裁判； **引用准确性是确定性的** （针对法规进行检查）。 | 指标 | 分数 | 关口 | 类型 | |---|---|---|---| | **引用准确性** | **1.00** | ≥ 0.90 ✅ | 确定性 | | **忠实度** | **0.90** | ≥ 0.85 ✅ | LLM裁判 | | 答案相关性 | 0.90 | 信息性 | LLM裁判 | | 法律健全性（G-Eval） | 0.82 | 信息性 | LLM裁判 | | 上下文精度 | 0.57 | 信息性 | LLM裁判 | | 上下文召回率 | 0.26 | 信息性 † | LLM裁判 | CI关口在 **引用准确性 + 忠实度** — 确定性反幻觉保证加上基础。其他指标报告用于洞察。 > † 上下文召回率比较 *黄金摘要* 和 *原始法规片段* ，这在结构上低估了它（摘要陈述了法律结论，而不是法规中的逐字逐句） — 这不是检索失败，因为完美的引用准确性和0.90的忠实度显示出来。 > > 分数由`tests/evaluation/`生成，并在CI中关口。 ## 每次查询的成本 每次分析（`gemini-2.5-flash`分段 + 按条款分析`gemini-2.5-pro`），通过每个模型的定价表跟踪，并在日志中、SSE `done`事件和Langfuse中显示。 在20案例评估运行（平均；按合同大小范围$0.0034–$0.0190）中测量。 | 组件 | 模型 | ~每次合同成本 | |---|---|---| | 分段/编排 | gemini-2.5-flash | ~$0.0008 | | 条款分析 | gemini-2.5-pro | ~$0.0063 | | 检索 + 引用验证 | 本地/确定性 | $0 | | 嵌入 | all-MiniLM-L6-v2（本地） | $0 | | **每次合同总计** | | **~$0.007** | ## 我会做不同的事情 - **托管向量数据库 + 每租户隔离。** 嵌入式ChromaDB对于单一实例演示来说是完美的；一个真正的产品需要一个托管的存储和隔离。 - **扩展法律语料库。** 目前它只有1872年印度合同法；租赁控制和劳动法规是存根。按状态划分的覆盖是下一个明显的步骤。 - **严重性校准指标。** 评估检查忠实度和引用；我会添加一个每条款严重性-MAE指标与专家标签对抗。 - **对抗性黄金案例。** 添加良性/接近遗漏的合同来衡量假阳性率，而不仅仅是遗漏不公平条款的召回率。 ## 技术栈 | 后端 | 前端 | |---|---| | Python 3.11, FastAPI | React 18, Vite, TypeScript（严格） | | LangGraph（多智能体） | Tailwind v4, shadcn/ui | | ChromaDB + rank-bm25（RRF） | TanStack Query, Zustand | | sentence-transformers（MiniLM） | Zod（运行时验证） | | Google Gemini 2.5（闪存 + 专业） | Framer Motion（流媒体UI） | | MCP（FastMCP，stdio） | Biome, Vitest | | DeepEval, Langfuse, structlog | pnpm | | uv, ruff, mypy --strict, pytest | Lighthouse 100/98/100/91 | ## 快速开始 ```bash # 后端（终端1） uv sync echo "CLAUSEIQ_GEMINI_API_KEY=your_key" > .env uv run python scripts/ingest_laws.py # 构建向量索引（一次） uv run uvicorn clauseiq.interfaces.api.main:app --app-dir src --reload --port 8000 # 前端（终端2） cd frontend && pnpm install && pnpm dev # http://localhost:5173 ``` API文档位于 http://localhost:8000/docs。使用`uv run pytest`运行测试套件。 **部署在** Google Cloud Run（后端）和Vercel（前端），使用Vertex AI上的Gemini。 ## 安装到Claude Desktop（MCP） 条款智识作为MCP服务器运行，因此您可以在Claude Desktop中分析和查找印度法律。设置需要不到一分钟 — 参见 **[docs/MCP_INSTALL.md](docs/MCP_INSTALL.md)**。 --- > **免责声明：** 条款智识是自动决策支持， **不是法律建议** 。修订历史不被跟踪；对于时间敏感的事项，请验证当前法律。