| --- |
| title: CivicSetu |
| emoji: 🏛️ |
| colorFrom: blue |
| colorTo: purple |
| sdk: docker |
| sdk_version: "default" |
| app_file: app.py |
| pinned: false |
| --- |
| |
| # CivicSetu |
|
|
| **Live:** [https://civicsetu-two.vercel.app](https://civicsetu-two.vercel.app) |
|
|
| Open-source RAG system for querying Indian civic and legal documents — with accurate |
| citations, cross-reference traversal, and conflict detection between laws. |
|
|
| **Current status:** Phase 9 complete — 5-jurisdiction RERA coverage, RAGAS evaluation pipeline (0.90 faithfulness), hybrid RRF retrieval, and mobile-responsive Next.js frontend live on Vercel. |
|
|
| --- |
|
|
| ## What it does |
|
|
| Ask a plain-English question about RERA. Get a cited, structured answer with section |
| references, confidence score, and a legal disclaimer — grounded in real legal text. |
|
|
| ``` |
| |
| Query: "Which state rules implement section 9 of RERA on agent registration?" |
| |
| Answer: "Section 9 of the RERA Act 2016 governs agent registration at the central level. |
| Rule 11 of Maharashtra Rules 2017 and Rule 8 of Karnataka RERA Rules derive |
| from Section 9, specifying application procedures and timelines..." |
| |
| Citations: [Section 9, RERA Act 2016], [Rule 11, Maharashtra Rules 2017], |
| [Rule 8, Karnataka RERA Rules] |
| Confidence: 0.96 (high) |
| |
| ``` |
|
|
| --- |
|
|
| ## Architecture |
|
|
| ``` |
| |
| FastAPI → LangGraph Agent → pgvector + Neo4j + PostgreSQL |
| ↑ |
| Ingestion Pipeline (PDF → chunks → embeddings → graph) |
| |
| ``` |
|
|
| Three stores per query: |
| - **pgvector** — semantic similarity (fact lookups) |
| - **Neo4j** — section graph traversal (cross-references, DERIVED_FROM edges) |
| - **PostgreSQL** — full chunk text + metadata |
| |
| Full design: [HLD.md](docs/HLD.md) | [LLD.md](docs/LLD.md) | [RAG.md](docs/RAG.md) |
| |
| --- |
| |
| ## Quickstart |
| |
| ### Prerequisites |
| |
| - Docker + Docker Compose |
| - `uv` package manager |
| - One of: Gemini API key (free tier) or Groq API key (free tier) |
| |
| > **No Ollama required.** Embeddings run locally via `sentence-transformers`. |
| > First run downloads `nomic-embed-text-v1.5` (~550MB) from HuggingFace and caches it. |
| |
| ### Setup |
| |
| ```bash |
| # 1. Clone and install |
| git clone https://github.com/adeshboudh/civicsetu.git && cd civicsetu |
| make install |
| |
| # 2. Configure secrets |
| cp .env.example .env |
| # Set GEMINI_API_KEY and/or GROQ_API_KEY — everything else has working defaults |
| |
| # 3. Start infrastructure |
| make docker-up |
| |
| # 4. Ingest all 5 jurisdictions |
| make ingest |
| |
| # 5. Start the API |
| make serve |
| ``` |
| |
| **Full docs:** [HLD](docs/HLD.md) | [LLD](docs/LLD.md) |
| |
| ## Production |
| |
| - **Frontend:** [Vercel](https://civicsetu-two.vercel.app) — Next.js 15 App Router (Mobile Responsive) |
| - **API:** [Hugging Face Spaces](https://huggingface.co/spaces/adesh01/civicsetu) — FastAPI + Docker + 550MB model baked in |
| - **PostgreSQL + pgvector:** [Neon](https://neon.tech) — 1203 chunks |
| - **Neo4j:** [AuraDB Free](https://neo4j.com/cloud/aura) — 2090 sections, 2321 edges |
| - **LLM:** LiteLLM (Gemini → Groq → OpenRouter) |
| |
| ### 6. Query |
| |
| ```bash |
| curl -X POST http://localhost:8000/api/v1/query \ |
| -H "Content-Type: application/json" \ |
| -d '{"query": "What are the penalties for a promoter who delays possession?"}' |
| ``` |
| |
| > First request will be slow (~30–45s) while the embedding model loads into memory. |
| > Subsequent requests run at 5–15s. |
| |
| ### Other useful commands |
| |
| ```bash |
| make e2e # Run 12-case E2E benchmark across all 5 jurisdictions |
| make test # Run unit tests |
| make lint # Ruff linter |
| make typecheck # mypy |
| |
| # RAGAS evaluation |
| make eval-smoke-p1 # Phase 1: invoke graph for 5-row smoke dataset |
| make eval-smoke-p2 # Phase 2: score cached results with RAGAS |
| make eval-p1 # Phase 1: full 31-row golden dataset |
| make eval-p2 # Phase 2: score all 31 rows |
| make eval-reset # Clear eval caches (re-runs everything) |
| |
| make ingest --jurisdiction MAHARASHTRA # Re-ingest a single jurisdiction |
| make docker-down # Tear down containers |
| ``` |
| |
| --- |
| |
| ## Documents ingested |
| |
| | Document | Jurisdiction | Sections | |
| | ---------------------------------- | ------------- | -------- | |
| | RERA Act 2016 | Central | 224 | |
| | Maharashtra Real Estate Rules 2017 | Maharashtra | 214 | |
| | UP RERA Rules 2016 | Uttar Pradesh | 170 | |
| | UP RERA General Regulations 2019 | Uttar Pradesh | 85 | |
| | Karnataka RERA Rules 2017 | Karnataka | 235 | |
| | Tamil Nadu RERA Rules 2017 | Tamil Nadu | 157 | |
| |
| Total chunks: 1203. |
| Graph: 2090 Section nodes, 1297 HAS_SECTION edges, 933 REFERENCES edges, 91 DERIVED_FROM edges. |
| |
| |
| --- |
| |
| ## Tech stack |
| |
| | Layer | Technology | |
| | :-- | :-- | |
| | API | FastAPI + Uvicorn | |
| | Orchestration | LangGraph StateGraph | |
| | LLM routing | LiteLLM (Gemini → Groq → OpenRouter) | |
| | Embeddings | nomic-embed-text-v1.5 via sentence-transformers (local, no Ollama required) | |
| | Vector DB | pgvector + HNSW index | |
| | Graph DB | Neo4j Community | |
| | Relational | PostgreSQL + SQLAlchemy | |
| | Retrieval | Hybrid RRF: pgvector cosine + PostgreSQL FTS (websearch_to_tsquery OR-mode) | |
| | Reranker | FlashRank (rank-T5-flan) + score gap filter | |
| | Evaluation | RAGAS (faithfulness, answer relevancy, context precision) | |
| | PDF parsing | PyMuPDF | |
| |
| |
| --- |
| |
| ## Phase roadmap |
| |
| | Phase | Scope | Status | |
| | :-- | :-- | :-- | |
| | 0 | RERA Act 2016, vector RAG, FastAPI | ✅ Complete | |
| | 1 | Neo4j graph, cross-reference queries | ✅ Complete | |
| | 2 | MahaRERA Rules 2017, multi-jurisdiction | ✅ Complete | |
| | 3 | DERIVED_FROM edges, cross-jurisdiction graph | ✅ Complete | |
| | 4 | Multi-state expansion (UP, TN, Karnataka) | ✅ Complete | |
| | 5 | Agent pipeline hardening, E2E test suite | ✅ Complete | |
| | 6 | Next.js frontend, Vercel deployment, public URL | ✅ Complete | |
| | 7 | Graph explorer, section content drawer, D3 visualization | ✅ Complete | |
| | 8 | RAGAS eval pipeline, hybrid RRF retrieval, retrieval quality fixes | ✅ Complete | |
| | 9 | Mobile responsiveness, frontend polish, dual-pane layout, interaction animations | ✅ Complete | |
|
|
|
|
| --- |
|
|
| ## ADRs |
|
|
| - [RAG Techniques Reference](docs/RAG.md) — hybrid retrieval, RRF, reranking, RAGAS eval, known failure modes |
| - [ADR 001 — three store architecture](docs/adr/001-three-store-architecture.md) |
| - [ADR 002 — section boundary chunking](docs/adr/002-section-boundary-chunking.md) |
| - [ADR 003 — LangGraph over LangChain chains](docs/adr/003-langgraph-over-langchain.md) |
| - [ADR 004 — Multi-format chunker](docs/adr/004-multi-format-chunker.md) |
| - [ADR 005 — Document registry](docs/adr/005-document-registry.md) |
|
|
|
|
| ## Disclaimer |
|
|
| CivicSetu provides AI-generated legal information, not legal advice. |
| Always verify with a qualified lawyer or the official gazette. |
|
|
