ClauseIQ

A multi-agent AI system that reads an Indian contract, flags clauses that are unfair to the weaker party with a severity score, and backs every flag with a citation to the exact section of Indian law. It runs as a web app and as an MCP server inside Claude Desktop.

This is a case-study README — it explains the what and why. Build/run details live in docs/ and the scripts; architecture in docs/ARCHITECTURE.md.

The problem

Tenants, junior employees, freelancers, and small businesses sign contracts they can't fully evaluate. A lock-in that's unenforceable, a one-sided indemnity, an auto-renewal trap — these hide in dense legalese. ClauseIQ surfaces them in plain language and, crucially, cites the law (Indian Contract Act 1872, Specific Relief Act, Consumer Protection Act, state rent-control acts) so the output is checkable, not a black box.

Related MCP server: Document OCR MCP Server

What makes it interesting (the engineering story)

• Clean / hexagonal architecture with a strict dependency rule — a pure domain core, swappable adapters, the same use cases exposed over both FastAPI and MCP. See docs/ARCHITECTURE.md.

• Multi-agent supervisor (LangGraph): a supervisor delegates to Retriever, Risk Analyzer, and Citation Verifier workers. In MCP mode, Claude Desktop is the supervisor; internal sub-tasks use free Gemini.

• Hybrid retrieval (dense embeddings + BM25, fused with Reciprocal Rank Fusion) over a corpus of real statutory text, so retrieval catches both meaning and exact legal terms.

• Zero LLM cost in web mode (Gemini free tier) and zero embedding cost (local all-MiniLM-L6-v2).

• Production discipline: Pydantic v2 at every boundary, mypy --strict, structured logging with a trace_id, a Result type for expected failures, property-based tests, and a reproducible, versioned law corpus.

Tech stack (one-line why each)

Status

Milestone 1 (Foundation) — complete. End-to-end data pipeline: project scaffolding, the pure domain layer, the clause-aware chunker, hybrid retrieval (BM25 + dense + RRF) over ChromaDB, a versioned Indian Contract Act corpus (266 sections parsed from the official PDF), the law repository, a health API, and docker-compose for the full local stack. All gates green (ruff, mypy --strict, ~100 tests, 100% domain coverage).

Later milestones: the LangGraph agents, the analysis use case, guardrails, the MCP server, the eval harness, and the React frontend.

A note on legal accuracy

The law corpus is the official consolidated Act text, fetched from indiacode.nic.in, committed and versioned. Per-section amendment history is not tracked — last_amended is honestly null where it can't be derived, and the UI shows an "amendment history not tracked" note. ClauseIQ is decision-support, not legal advice; users should verify current law for time-sensitive matters.

What I'd do differently / next

• Automated weekly corpus refresh (stretch — architecture already supports it). A scheduled GitHub Action runs fetch_ica_source.py + diff_law_corpus.py weekly, posts the human-readable diff to Slack, and opens a PR that requires human approval before the refreshed corpus is merged. The pieces exist (deterministic fetch, normalized diff, versioned JSON); only the workflow and notification wiring remain. This keeps the law current without ever auto-merging legal-text changes unreviewed.

• An amendments database so last_amended becomes real per-section data (the schema already carries is_amendment_history_known to flip on later).

• More statutes beyond the Contract Act (Specific Relief, Consumer Protection, state rent-control acts) using the same ingestion pipeline.

• A longer-context embedder to allow larger chunks (the current 250-token size is bounded by MiniLM's 256-token window).