Content
<div align="center">
# ClauseIQ
**A multi-agent AI system that reads an Indian contract, flags the clauses that are unfair to you with a severity score, and cites the exact section of Indian law behind each one.**
Runs as a streaming web app **and** as an MCP server inside Claude Desktop.
**[▶ Live app](https://clause-iq-mu.vercel.app/)** · [Install into Claude Desktop (MCP)](docs/MCP_INSTALL.md)
</div>
---
## The problem
People in India sign rental, employment, and freelance contracts every day with
clauses that are quietly **unfair — or unenforceable** under Indian law, and have
no way to tell which. A 12-month lock-in that forfeits your *entire* deposit. A
two-year, all-India non-compete. "Raise any dispute within 7 days or lose it
forever." Lawyers are expensive; generic AI chatbots hallucinate sections of law
that don't exist.
ClauseIQ is the tool I wanted to exist: it reads the contract, flags the risky
clauses with a 1–5 severity score, explains *why* in plain language, and — the
part that matters — **backs every flag with a real, verified citation** to the
Indian Contract Act, 1872.
## Live demo
> Add a GIF/screenshots here: `docs/assets/demo.gif`, `docs/assets/analysis.png`.
- **Web app:** **https://clauseiq-app-fawn.vercel.app** — paste a contract or upload a PDF and watch the agents work live.
- **API:** `https://clauseiq-api-124621416027.asia-south1.run.app` (Cloud Run; `GET /health` for liveness, `/docs` for the OpenAPI UI).
- **In Claude Desktop (MCP):** ask *"analyse this contract for unfair clauses"* — see [docs/MCP_INSTALL.md](docs/MCP_INSTALL.md).
## System architecture
One application core, exposed through two front doors (a REST/streaming API and an
MCP server). The analysis itself is a **LangGraph** state machine of four agents:
```mermaid
flowchart LR
subgraph Clients
Web[React app<br/>SSE streaming]
Claude[Claude Desktop<br/>MCP]
end
Web -->|POST /analyze/stream| API[FastAPI]
Claude -->|stdio| MCP[MCP server]
API --> Core
MCP --> Core
subgraph Core[Application core - LangGraph]
direction LR
S[Supervisor<br/>segment + screen] --> R[Retriever<br/>hybrid search] --> RA[Risk Analyzer<br/>score 1-5] --> CV[Citation Verifier<br/>drop hallucinations]
end
R -.-> VS[(ChromaDB + BM25<br/>Indian Contract Act)]
S & RA -.-> G[Gemini 2.5<br/>flash + pro]
Core --> OBS[Langfuse + cost tracking]
```
Hybrid retrieval fuses dense vectors (ChromaDB) and lexical BM25 via Reciprocal
Rank Fusion. The **Citation Verifier** is the anti-hallucination guarantee: any
cited section that isn't in the corpus is dropped before you ever see it.
## Key design decisions
1. **One core, two front doors (dual-mode MCP).** The agents live in the
application layer with zero knowledge of transport; FastAPI and the MCP server
are thin adapters over the same `ContractAnalyzer`. *Tradeoff:* a strict
hexagonal boundary is more upfront structure, but it's why the exact same
analysis runs in a browser and inside Claude Desktop with no duplicated logic.
2. **Gemini via Vertex AI, with automatic fallback to AI Studio.** Orchestration on
`gemini-2.5-flash`, analysis on `gemini-2.5-pro`. In production it runs on
**Vertex AI** (billed to GCP credits, authenticated by the Cloud Run service
account — no key on the server); if Vertex is unavailable or the credits run out,
the client **automatically falls back to an AI Studio key**, so the app keeps
working. *Tradeoff:* a single-vendor (Google) dependency, in exchange for ~zero
cost, strong structured output, and resilience — and Claude is still free via the
user's own Claude Desktop over MCP.
3. **A deterministic citation metric, not just LLM judges.** Citation accuracy is
checked against the actual statute (existence + text overlap), so the
anti-hallucination guarantee never depends on another model's opinion.
*Tradeoff:* it only catches citation faults, so it's paired with LLM-judged
faithfulness for the rest.
4. **Eval-gated CI.** A 20-case golden dataset runs in CI; the build fails if
faithfulness or citation accuracy regress. *Tradeoff:* slower, token-spending
CI, but prompt regressions can't silently ship.
5. **Result types + guardrails over exceptions for expected failures.** Expected
failures (not-a-contract, prompt injection, missing law) are typed `Result`
values and explicit guardrails, not stack traces. *Tradeoff:* more verbose call
sites, far more predictable behaviour at the API/MCP boundary.
## Evaluation results
Measured with DeepEval over the full 20-case golden dataset (5 each: rental,
employment, NDA, vendor). LLM-judged metrics use Gemini as judge; **Citation
Accuracy is deterministic** (checked against the statute).
| Metric | Score | Gate | Type |
|---|---|---|---|
| **Citation Accuracy** | **1.00** | ≥ 0.90 ✅ | deterministic |
| **Faithfulness** | **0.90** | ≥ 0.85 ✅ | LLM judge |
| Answer Relevancy | 0.90 | informational | LLM judge |
| Legal Soundness (G-Eval) | 0.82 | informational | LLM judge |
| Contextual Precision | 0.57 | informational | LLM judge |
| Contextual Recall | 0.26 | informational † | LLM judge |
CI gates on **Citation Accuracy + Faithfulness** — the deterministic
anti-hallucination guarantee plus grounding. The rest are reported for insight.
> † Contextual Recall compares the *gold summary* against the *raw statute snippets*
> cited, which structurally understates it (the summary states legal conclusions not
> verbatim in the statute) — it's not a retrieval failure, as the perfect Citation
> Accuracy and 0.90 Faithfulness show.
>
> Scores are produced by `tests/evaluation/` and gated in CI.
## Cost per query
Per analysis (segmentation on `gemini-2.5-flash` + per-clause analysis on
`gemini-2.5-pro`), tracked live via a per-model price table and surfaced in logs,
the SSE `done` event, and Langfuse.
Measured across the 20-case eval run (avg; range $0.0034–$0.0190 by contract size).
| Component | Model | ~Cost / contract |
|---|---|---|
| Segmentation / orchestration | gemini-2.5-flash | ~$0.0008 |
| Clause analysis | gemini-2.5-pro | ~$0.0063 |
| Retrieval + citation verify | local / deterministic | $0 |
| Embeddings | all-MiniLM-L6-v2 (local) | $0 |
| **Total per contract** | | **~$0.007** |
## What I'd do differently
- **Hosted vector DB + per-tenant isolation.** Embedded ChromaDB is perfect for a
single-instance demo; a real product needs a managed store and isolation.
- **Expand the law corpus.** Today it's the Indian Contract Act, 1872; rent-control
and labour statutes are stubbed. State-specific coverage is the obvious next step.
- **Severity-calibration metric.** The eval checks faithfulness and citations; I'd
add a per-clause severity-MAE metric against expert labels.
- **Adversarial golden cases.** Add benign/near-miss contracts to measure the
false-positive rate, not just recall on unfair clauses.
## Tech stack
| Backend | Frontend |
|---|---|
| Python 3.11, FastAPI | React 18, Vite, TypeScript (strict) |
| LangGraph (multi-agent) | Tailwind v4, shadcn/ui |
| ChromaDB + rank-bm25 (RRF) | TanStack Query, Zustand |
| sentence-transformers (MiniLM) | Zod (runtime validation) |
| Google Gemini 2.5 (flash + pro) | Framer Motion (streaming UI) |
| MCP (FastMCP, stdio) | Biome, Vitest |
| DeepEval, Langfuse, structlog | pnpm |
| uv, ruff, mypy --strict, pytest | Lighthouse 100/98/100/91 |
## Quickstart
```bash
# Backend (terminal 1)
uv sync
echo "CLAUSEIQ_GEMINI_API_KEY=your_key" > .env
uv run python scripts/ingest_laws.py # build the vector index (once)
uv run uvicorn clauseiq.interfaces.api.main:app --app-dir src --reload --port 8000
# Frontend (terminal 2)
cd frontend && pnpm install && pnpm dev # http://localhost:5173
```
API docs at http://localhost:8000/docs. Run the test suite with `uv run pytest`.
**Deployed on** Google Cloud Run (backend) and Vercel (frontend), with Gemini on
Vertex AI.
## Install into Claude Desktop (MCP)
ClauseIQ runs as an MCP server, so you can analyse contracts and look up Indian
law directly inside Claude Desktop. Setup takes under a minute —
see **[docs/MCP_INSTALL.md](docs/MCP_INSTALL.md)**.
---
> **Disclaimer:** ClauseIQ is automated decision-support, **not legal advice**.
> Amendment history is not tracked; verify current law for time-sensitive matters.
