A production-grade, zero-hallucination RAG system for Indian legal intelligence.
HECTOR is a hard-RAG legal reasoning engine purpose-built for Indian Law. It maps the transition from the Indian Penal Code (IPC) to the Bharatiya Nyaya Sanhita (BNS), grounding every response in verified Bare Act citations with a strict chain-of-verification pipeline that flags unverifiable claims instead of guessing.
- Zero hallucination — Every citation is verified against the source corpus before delivery
- Section-aware chunking — Documents split at legal section boundaries, never mid-sentence
- Temporal integrity — IPC-to-BNS mappings validated against the 2024 repeal timeline
- Deterministic retrieval — Hybrid BM25 + semantic search with cross-encoder reranking
- Defense in depth — 4 verification layers: citation grounding, temporal validation, BNS section bounds, and chain-of-verification
┌─────────────────────────────────────────────────────────────────────┐
│ INTERFACE LAYER │
│ ┌──────────────┐ ┌──────────────┐ ┌───────────┐ │
│ │ React SPA │ │ REST API │ │ CLI │ │
│ │ (Vite/TW) │ │ (FastAPI) │ │ (Typer) │ │
│ └──────┬───────┘ └──────┬───────┘ └─────┬─────┘ │
│ └─────────────────┴────────────────┘ │
└─────────────────────────────────┬───────────────────────────────────┘
│
┌─────────────────────────────────▼───────────────────────────────────┐
│ QUERY PIPELINE │
│ │
│ ┌──────────┐ ┌───────────┐ ┌──────────┐ ┌──────────────────┐ │
│ │ Entity │ │ Intent │ │ Hybrid │ │ Chain-of- │ │
│ │ Parser │→ │ Router │→ │ Retriever│→ │ Verification │ │
│ │ (regex) │ │(embedding)│ │ (BM25+ │ │ (citation + │ │
│ │ │ │ │ │ vector) │ │ temporal check) │ │
│ └──────────┘ └───────────┘ └──────────┘ └──────────────────┘ │
│ │
│ ┌───────────────┐ ┌────────────────┐ ┌───────────────────────┐ │
│ │ Query │ │ Entity │ │ Response │ │
│ │ Expander │ │ Reranker │ │ Generator │ │
│ │ (synonyms) │ │ (score boost) │ │ (citation grounded) │ │
│ └───────────────┘ └────────────────┘ └───────────────────────┘ │
└─────────────────────────────────┬───────────────────────────────────┘
│
┌─────────────────────────────────▼───────────────────────────────────┐
│ DATA LAYER │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │
│ │ ChromaDB │ │ BM25 Index │ │ 45 Bare Acts & │ │
│ │ (semantic) │ │ (keyword) │ │ Commentaries (~17,800 │ │
│ │ │ │ │ │ section-aware chunks) │ │
│ └──────────────┘ └──────────────┘ └──────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
| Stage | Module | Purpose |
|---|---|---|
| Entity Extraction | core/query_parser.py |
Regex-based extraction of act names (107 known acts), sections, topics, courts (17 jurisdictions), and articles from natural language queries |
| Intent Routing | core/embedding_router.py |
Sentence-transformers cosine similarity classifies query intent into LEGAL_RESEARCH, DOCUMENT_ANALYSIS, PRECEDENT, or GENERAL |
| Query Expansion | core/query_expander.py |
Legal synonym dictionary expands queries with related terms (e.g., "murder" → "culpable homicide", "section 302") |
| Hybrid Retrieval | data/hybrid_retriever.py |
BM25 keyword + semantic vector search fused via Reciprocal Rank Fusion, reranked by cross-encoder (ms-marco-MiniLM-L-6-v2) |
| Entity Reranking | core/entity_reranker.py |
Score boosting for matches on section numbers, act names, topic keywords, and constitutional articles |
| Chain-of-Verification | core/verifier.py |
4-layer verification: citation grounding, temporal validation, BNS section bounds (≤395), hallucination detection |
| Response Generation | core/response_generator.py |
Generates citation-grounded answers with IPC↔BNS comparison tables, source attributions, and confidence scores |
HECTOR employs four independent verification mechanisms to prevent legal misinformation:
Query → Retrieved Chunks → Citation Grounding → Temporal Validation
↓
Answer ← Confidence Score ← BNS Bounds Check ← Hallucination Scan
| Layer | What It Checks | Failure Mode |
|---|---|---|
| Citation Grounding | Every cited section exists in retrieved source text | Unverifiable claims flagged, not guessed |
| Temporal Validation | IPC sections cited as "current law" are checked against the July 2024 repeal | Repealed law flagged as historical context only |
| BNS Section Bounds | BNS section numbers must be ≤ 395 (the actual maximum) | Invalid section numbers rejected |
| Chain-of-Verification | Response claims cross-checked against source for factual consistency | Contradictions surfaced to user |
| Mechanism | Implementation |
|---|---|
| Authentication | HMAC-SHA256 JWT tokens with configurable expiry |
| API Key Storage | bcrypt hashing for at-rest key storage |
| Rate Limiting | Per-key token bucket algorithm with configurable refill rate |
| CORS | Configurable origin allowlist |
| Health Probes | /healthz (liveness) and /readyz (readiness) for orchestrators |
| Input Validation | Pydantic models enforce strict request schemas |
| Metric | Value |
|---|---|
| Total documents | 45 PDFs |
| Legal domains covered | 80+ topics |
| IPC→BNS mappings | 495 cross-references |
| Court jurisdictions | 17 (Supreme Court, 25 High Courts, tribunals) |
| Known act names | 107 (with real-name extraction from PDF content) |
| Chunk strategy | Section-aware (never splits mid-section) |
| Deduplication | Content-hash based, survives reindex crashes |
Criminal Law · Family Law · Constitutional Law · Commercial Law · Intellectual Property · Tax Law · Environmental Law · Telecom Law · Labor Law · Education Law · Cyber Law · RTI · Evidence Law · Property Law · Insurance · Banking · Juvenile Justice · Prevention of Corruption · Narcotics · National Security
| Layer | Technology |
|---|---|
| Backend | FastAPI, Python 3.11+ |
| Vector Database | ChromaDB |
| Embeddings | sentence-transformers (all-MiniLM-L6-v2) |
| Reranker | Cross-encoder (ms-marco-MiniLM-L-6-v2) |
| Intent Router | Local sentence-transformers (cosine similarity) |
| LLM (optional) | Groq (llama-3.3-70b-versatile) |
| Frontend | Vite 5, React 18, Tailwind CSS 4 |
| OCR | Tesseract 5, Poppler, pdf2image |
| Auth | HMAC-SHA256 JWT, bcrypt |
| Rate Limiting | Token bucket (per-key, sliding refill) |
| CLI | Typer |
| Testing | pytest (1,081 tests) |
| Linting | ruff (format + check) |
1,081 tests · 0 failures · 1 skipped
| Category | Coverage |
|---|---|
| Query Parser | Entity extraction, act name resolution, section parsing |
| Embedding Router | Intent classification, confidence scoring |
| Query Expander | Legal synonym expansion |
| Entity Reranker | Score boosting, topic matching |
| Legal Chunker | Section boundary detection, metadata enrichment |
| Nemo Retriever | Provider abstraction, fallback logic |
| Retrieval Accuracy | End-to-end legal QA against 25 curated test pairs |
| Rate Limiting | Token bucket behavior, window expiration, key isolation |
| Auth Flow | JWT lifecycle, API key verification, bcrypt hashing |
| Enhanced Ingestor | PDF processing, content-hash dedup, chunk generation |
| Verifier | Citation grounding, temporal validation, BNS bounds |
| API Endpoints | Search, compare, route, health, auth |
| Frontend Components | Response rendering, pipeline display, document panel |
| Method | Endpoint | Auth | Description |
|---|---|---|---|
POST |
/search |
API Key / JWT | Hybrid legal search with full pipeline |
POST |
/compare |
API Key / JWT | IPC ↔ BNS section comparison |
POST |
/route |
API Key / JWT | Intent classification |
POST |
/ingest |
API Key / JWT | PDF ingestion trigger |
GET |
/status |
API Key / JWT | System health + ChromaDB stats |
GET |
/healthz |
None | Kubernetes liveness probe |
GET |
/readyz |
None | Kubernetes readiness probe |
POST |
/auth/token |
API Key | JWT bearer token issuance |
WS |
/ws/search |
Query param | Streaming search events |
This project is licensed under the MIT License. See LICENSE for details.
Built for the Indian legal ecosystem.
Not a substitute for professional legal advice. Always consult a qualified legal professional.