---

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.

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:

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

# 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.

---

Disclaimer: ClauseIQ is automated decision-support, not legal advice. Amendment history is not tracked; verify current law for time-sensitive matters.