Deploy v1 — single-Docker FastAPI + Next.js + RAG + voice + faithfulness

.env.example

@@ -0,0 +1,15 @@
+# Copy this to .env and fill in. Do NOT commit .env.
+
+# Primary provider — Sarvam (STT, TTS, LLM)
+SARVAM_API_KEY=sk_your_sarvam_api_key_here
+
+# Embeddings — Voyage AI (Anthropic's recommended partner)
+VOYAGE_API_KEY=pa-your_voyage_key_here
+
+# Grader / self-critique — Groq (Llama-3.3-70B, free tier, OpenAI-compatible API)
+# Used for eval harness AND as a fallback brain (router escalates here for complex queries).
+GROQ_API_KEY=gsk_your_groq_api_key_here
+
+# Fallback brain — OpenRouter (DeepSeek-V3 671B, currently SOTA open-source)
+# Used by router for complex multi-policy reasoning queries.
+OPENROUTER_API_KEY=sk-or-v1-your_openrouter_key_here

.gitattributes

@@ -33,3 +33,79 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+rag/corpus/aditya-birla/activ-assure-diamond__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/aditya-birla/activ-health-individual__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/aditya-birla/activ-one__brochure.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/aditya-birla/activ-secure-cancer-secure__brochure.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/aditya-birla/activ-secure-personal-accident-cancer-secure__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/aditya-birla/group-activ-health__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/bajaj-allianz/comprehensive-care-plan__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/bajaj-allianz/criti-care__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/bajaj-allianz/extra-care-plus__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/bajaj-allianz/global-health-care__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/bajaj-allianz/group-health-guard-gold__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/bajaj-allianz/group-personal-accident__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/bajaj-allianz/health-guard-gold-individual__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/bajaj-allianz/health-guard__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/bajaj-allianz/silver-health__cis.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/bajaj-allianz/tax-gain__cis.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/care-health/care-advantage-add-ons-protect-plus-care-shield__brochure.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/care-health/care-advantage__brochure.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/care-health/care-classic__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/care-health/care-heart__brochure.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/care-health/care-senior__brochure.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/care-health/care-supreme-enhance__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/care-health/care-supreme__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/care-health/supreme-enhance__brochure.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/care-health/ultimate-care__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/hdfc-ergo/energy-diabetes-hypertension__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/hdfc-ergo/group-health-insurance__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/hdfc-ergo/my-health-medisure-prime__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/hdfc-ergo/my-health-sampoorna-suraksha__brochure.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/hdfc-ergo/my-health-suraksha__brochure.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/hdfc-ergo/my-health-women-suraksha__brochure.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/hdfc-ergo/my-optima-secure-older-variant__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/hdfc-ergo/my-optima-secure__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/hdfc-ergo/optima-enhance__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/hdfc-ergo/optima-plus__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/hdfc-ergo/optima-restore__brochure.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/hdfc-ergo/total-health-plan__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/icici-lombard/arogya-sanjeevani__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/icici-lombard/complete-health-insurance-health-shield__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/icici-lombard/complete-health-insurance-umbrella__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/icici-lombard/elevate__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/icici-lombard/health-advantedge__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/icici-lombard/health-booster-top-up__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/icici-lombard/health-elite-plus__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/icici-lombard/health-shield-360-retail__cis.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/icici-lombard/health-shield-360-retail__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/manipalcigna/prohealth-insurance-all-variants__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/manipalcigna/prohealth-select__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/manipalcigna/sarvah-param__brochure.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/manipalcigna/sarvah-param__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/new-india/asha-kiran-policy__brochure.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/new-india/asha-kiran-policy__cis.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/new-india/janata-mediclaim-policy__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/new-india/new-india-floater-mediclaim-policy__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/new-india/new-india-mediclaim-policy__brochure.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/new-india/new-india-mediclaim-policy__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/new-india/universal-health-insurance__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/new-india/yuva-bharat-health-policy__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/niva-bupa/aspire__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/niva-bupa/health-companion-v2022__brochure.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/niva-bupa/health-companion__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/niva-bupa/health-plus-top-up__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/niva-bupa/health-premia__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/niva-bupa/reassure-2-0__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/niva-bupa/reassure-3-0__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/niva-bupa/rise__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/niva-bupa/saral-suraksha-bima__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/niva-bupa/senior-first__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/tata-aig/criti-medicare__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/tata-aig/medicare-lite__cis.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/tata-aig/medicare-premier__cis.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/tata-aig/medicare-premier__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/tata-aig/medicare-select__brochure.pdf filter=lfs diff=lfs merge=lfs -text
+rag/corpus/tata-aig/medicare__wordings.pdf filter=lfs diff=lfs merge=lfs -text
+rag/policies.duckdb filter=lfs diff=lfs merge=lfs -text
+rag/vectors/chroma.sqlite3 filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,76 @@
+# Secrets — NEVER COMMIT
+.env
+.env.local
+.env.*.local
+*.key
+*.pem
+secrets/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual envs
+venv/
+env/
+ENV/
+.venv
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Next.js
+.next/
+frontend/node_modules/
+frontend/.next/
+frontend/.env.local
+
+# Vector DB persistence — too large for git (sqlite > 10MB HF limit).
+# Rebuilt at container startup from corpus PDFs in ~5 min.
+rag/vectors/
+# rag/policies.duckdb -- intentionally not gitignored (small)
+
+# Raw PDFs — large; do commit a subset later for reproducibility
+# (keeping commented out — we WILL commit the corpus we acquire so deploy works)
+# rag/corpus/
+
+# Eval outputs
+eval/results_*.json
+eval/results_*.html
+
+# Logs
+*.log
+logs/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# OS
+Thumbs.db

ARCHITECTURE.md

@@ -0,0 +1,50 @@
+Insurance Sales Portfolio Expert: Architecture & Design
+
+This document details the technical architecture, operational workflows, and future roadmap for the Insurance Sales AI Agent.
+
+---
+
+## System Architecture
+
+The application is built using a modular approach to ensure simplicity, explainability and high performance. 
+
+### 1. Frontend & Orchestration
+- **Technology**: 
+- **Role**: Serves as the user interface and central controller. It manages:
+  - **Session State**: Tracks chat history, processed audio IDs, and indexed document status.
+  - **Resource Caching**: Uses `@st.cache_resource` to ensure heavy models (Whisper, RAG, LLM) are loaded only once.
+  - **Component Coordination**: Pipes data from the microphone to Whisper, then to the RAG engine, then to the LLM, and finally to the TTS engine.
+
+### 2. Retrieval-Augmented Generation
+- **Technology**: 
+- **Embeddings**: 
+- **Workflow**:
+  - **Ingestion**: 
+  - **Metadata Tagging**: Documents are tagged as either `Product` (policies) or `Regulatory` (annual reports).
+  - **Vector Storage**: 
+  - **Retrieval**: 
+
+### 3. Language Processing 
+- **Technology**: 
+- **Role**: The "reasoning" engine.
+- **System Prompting**: Enforces a persona of a "Professional Insurance Advisor." It is explicitly instructed to:
+  - Compare multiple policies.
+  - Use specific citation tags (e.g., `[Source: ...]`).
+  - Be concise for voice-based interactions.
+
+### 4. Voice Pipeline 
+- **STT (Speech-to-Text)**:
+- **TTS (Text-to-Speech)**:
+
+---
+
+## How It Works (Step-by-Step)
+
+1.  **Document Indexing**: User uploads a PDF. 
+2.  **Voice Input**: Captures raw audio.
+3.  **Transcription**: Converts the audio bytes into text.
+4.  **Contextual Retrieval**: The text query is embedded and matched against the DB. The engine returns the most relevant snippets along with their source.
+5.  **Response Generation**: The LLM receives the user's question and the retrieved snippets. It synthesises a natural language answer.
+6.  **Voice Synthesis**: The answer is converted to voice
+7.  **Playback**: Audio component plays the response automatically
+

Dockerfile

@@ -0,0 +1,62 @@
+# Multi-stage build:
+#   Stage 1 — build the Next.js frontend to a static export
+#   Stage 2 — Python runtime serving FastAPI + the built frontend on the same port
+
+# ----------------------------------------------------------------------------
+# Stage 1 — Node builder
+# ----------------------------------------------------------------------------
+FROM node:22-alpine AS frontend-builder
+WORKDIR /app/frontend
+
+# Install deps first for layer caching
+COPY frontend/package.json frontend/package-lock.json* ./
+RUN npm ci --no-audit --no-fund
+
+# Copy the rest of the frontend and build
+COPY frontend/ ./
+# In production, the frontend calls the same origin (no separate backend URL).
+ENV NEXT_PUBLIC_BACKEND_URL=""
+# Static-export the app — produces ./out
+RUN npm run build
+
+# ----------------------------------------------------------------------------
+# Stage 2 — Python runtime (FastAPI + corpus + Chroma + DuckDB + frontend)
+# ----------------------------------------------------------------------------
+FROM python:3.11-slim
+WORKDIR /app
+
+# System deps for pdfplumber + torch CPU + sentence-transformers
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    libpoppler-cpp-dev \
+    pkg-config \
+    poppler-utils \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Python deps
+COPY requirements.txt ./
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir -r requirements.txt
+
+# Pre-download the embedding model so the first request is fast (no cold load)
+RUN python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('BAAI/bge-small-en-v1.5')"
+
+# Copy the backend source + RAG modules + data
+COPY backend ./backend
+COPY rag ./rag
+COPY eval ./eval
+COPY docs ./docs
+
+# Copy the built frontend from stage 1
+COPY --from=frontend-builder /app/frontend/out ./frontend/out
+
+# HF Spaces sends traffic to $PORT (default 7860). uvicorn will bind to it.
+ENV PORT=7860
+EXPOSE 7860
+
+# Use a non-root user (HF Spaces recommends this for Docker spaces)
+RUN useradd -m -u 1000 user && chown -R user:user /app
+USER user
+
+# Start the FastAPI app
+CMD ["sh", "-c", "uvicorn backend.main:app --host 0.0.0.0 --port ${PORT} --log-level info"]

README.md

@@ -1,12 +1,74 @@
 ---
-title: InsuranceBot
-emoji: 🐠
-colorFrom: green
-colorTo: green
+title: Insurance Sales Portfolio Expert
+emoji: 🏥
+colorFrom: blue
+colorTo: indigo
 sdk: docker
+app_port: 7860
 pinned: false
 license: mit
-short_description: Insurance Sales Bot
+short_description: Voice AI advisor for Indian health insurance
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Insurance Sales Portfolio Expert
+
+A voice-first AI advisor for Indian health insurance buyers, over a curated corpus of policies from 10 leading insurers. Built as a take-home assignment for Sarvam AI.
+
+**Live demo:** *(deployed URL — added at submission)*
+
+**Docs (read in order):**
+
+1. [`docs/01-requirements.md`](docs/01-requirements.md) — product vision, personas, success criteria, non-goals
+2. [`docs/02-architecture.md`](docs/02-architecture.md) — stack picks, schema, system design *(in progress)*
+3. [`docs/03-eval-plan.md`](docs/03-eval-plan.md) — gold Q&A pairs, automated grader, accuracy targets *(in progress)*
+4. [`docs/04-failure-modes.md`](docs/04-failure-modes.md) — known failure modes + mitigations *(in progress)*
+5. [`docs/05-needs-analysis-flow.md`](docs/05-needs-analysis-flow.md) — fact-find question graph *(in progress)*
+6. [`docs/decisions.md`](docs/decisions.md) — every meaningful decision logged with alternatives + reasoning
+7. [`docs/ROADMAP.md`](docs/ROADMAP.md) — how this scales from v1 vertical slice to full platform
+
+## Quick start
+
+```bash
+git clone https://github.com/rohitsar567/insurance-sales-bot.git
+cd insurance-sales-bot
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+cp .env.example .env  # then fill in SARVAM_API_KEY
+streamlit run streamlit_app.py
+```
+
+## Architecture at a glance
+
+```
+User voice → Sarvam Saaras (STT) → Orchestrator → Sarvam-M (LLM)
+                                          ↓
+                                  Hybrid retrieval:
+                                  ├─ Structured (DuckDB) — filters, comparison
+                                  └─ Unstructured (Chroma) — chunked PDFs, RAG
+                                          ↓
+                                  Cited response → Sarvam Bulbul (TTS) → User
+```
+
+## What's in scope for v1 (the vertical slice)
+
+- 10 insurers × all their health policies (target: 40–80 policies)
+- 40–50 structured fields per policy (premium, sum insured, waiting periods, PED, sub-limits, network, claim ratio, geography, etc.)
+- Voice advisor with Hindi/English code-switch
+- Adaptive needs analysis
+- Granular filter + side-by-side comparison
+- Illustrative pricing bands
+
+## What's out of scope (v2 roadmap)
+
+See [`docs/01-requirements.md` §7](docs/01-requirements.md).
+
+## Built with
+
+- **STT**: Sarvam Saaras
+- **TTS**: Sarvam Bulbul
+- **LLM**: Sarvam-M
+- **Vector DB**: Chroma
+- **Structured DB**: DuckDB
+- **UI**: Streamlit
+
+Each pick is justified in [`docs/decisions.md`](docs/decisions.md).

backend/config.py

@@ -0,0 +1,70 @@
+"""Centralized settings loaded from .env via pydantic-settings.
+
+All API keys + tunables live here. Never read os.environ directly elsewhere.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional
+
+from dotenv import load_dotenv
+
+ROOT = Path(__file__).resolve().parent.parent
+load_dotenv(ROOT / ".env")
+
+
+class Settings:
+    # Provider keys
+    SARVAM_API_KEY: str = os.environ.get("SARVAM_API_KEY", "")
+    VOYAGE_API_KEY: str = os.environ.get("VOYAGE_API_KEY", "")
+    GROQ_API_KEY: str = os.environ.get("GROQ_API_KEY", "")
+    OPENROUTER_API_KEY: str = os.environ.get("OPENROUTER_API_KEY", "")
+
+    # Sarvam endpoints
+    SARVAM_BASE_URL: str = "https://api.sarvam.ai"
+    SARVAM_STT_PATH: str = "/speech-to-text"
+    SARVAM_TTS_PATH: str = "/text-to-speech"
+    SARVAM_CHAT_PATH: str = "/v1/chat/completions"
+
+    # Sarvam model identifiers
+    SARVAM_STT_MODEL: str = "saarika:v2.5"
+    SARVAM_TTS_MODEL: str = "bulbul:v2"
+    SARVAM_TTS_SPEAKER: str = "anushka"  # natural female advisor voice; configurable
+    SARVAM_LLM_MODEL: str = "sarvam-m"
+
+    # Voyage
+    VOYAGE_MODEL: str = "voyage-3"
+
+    # Groq (grader + fallback brain)
+    GROQ_BASE_URL: str = "https://api.groq.com/openai/v1"
+    GROQ_GRADER_MODEL: str = "llama-3.3-70b-versatile"
+    GROQ_BRAIN_MODEL: str = "llama-3.3-70b-versatile"
+
+    # OpenRouter (alt fallback brain)
+    OPENROUTER_BASE_URL: str = "https://openrouter.ai/api/v1"
+    OPENROUTER_BRAIN_MODEL: str = "deepseek/deepseek-chat-v3-0324"
+
+    # Storage paths
+    CORPUS_DIR: Path = ROOT / "rag" / "corpus"
+    EXTRACTED_DIR: Path = ROOT / "rag" / "extracted"
+    VECTORS_DIR: Path = ROOT / "rag" / "vectors"
+    STRUCTURED_DB: Path = ROOT / "rag" / "policies.duckdb"
+
+    # Tunables
+    CHUNK_TOKENS: int = 800
+    CHUNK_OVERLAP_TOKENS: int = 120
+    RAG_TOP_K: int = 5
+
+    @classmethod
+    def validate(cls) -> list[str]:
+        """Return list of missing required keys. Empty list = healthy."""
+        missing = []
+        for k in ("SARVAM_API_KEY", "VOYAGE_API_KEY", "GROQ_API_KEY"):
+            if not getattr(cls, k):
+                missing.append(k)
+        return missing
+
+
+settings = Settings()

backend/faithfulness.py

@@ -0,0 +1,302 @@
+"""Hallucination prevention — multi-layer faithfulness verification.
+
+Every assistant reply passes through these gates before being returned to the user.
+Failure at any gate triggers a regeneration with a stricter prompt, or a refusal.
+
+The mechanism:
+
+Gate 1 — RETRIEVAL FLOOR
+  If the top retrieved chunk has cosine similarity below MIN_TOP_SCORE,
+  we refuse outright — there isn't enough grounded evidence to answer.
+
+Gate 2 — CITATION INTEGRITY
+  Every [Source: <Policy Name> ...] tag that appears in the reply MUST match
+  a real retrieved chunk's policy_name. Fabricated citations = block.
+
+Gate 3 — NUMERIC GROUNDING
+  Every monetary amount (₹), percentage, day/month/year count in the reply
+  must also appear in at least one retrieved chunk. Catches the "premium is
+  ₹15,000" hallucination class deterministically.
+
+Gate 4 — LLM-JUDGE FAITHFULNESS (Groq Llama, cheap + fast + different family)
+  Pass {retrieved_chunks, reply} to a second LLM with prompt:
+    "For each factual claim in the reply, is it supported by these chunks?
+     Reply STRICT_JSON: {supported: bool, unsupported_claims: [str]}"
+  Block if supported=false.
+
+Gate 5 — AUDIT
+  Every block + every recoverable warning is appended to logs/hallucinations.jsonl
+  for post-hoc analysis and compliance audit.
+
+Public API:
+  check_faithfulness(reply, retrieved_chunks) -> FaithfulnessVerdict
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+from backend.config import settings
+from backend.providers.base import ChatMessage
+from backend.providers.groq_llm import GroqLLM
+from rag.retrieve import RetrievedChunk
+
+LOG_DIR = settings.CORPUS_DIR.parent.parent / "logs"
+LOG_DIR.mkdir(exist_ok=True)
+HALLUCINATION_LOG = LOG_DIR / "hallucinations.jsonl"
+
+# Tunables — these become evaluable parameters in the eval harness.
+# BGE-small returns higher cosine similarity than Voyage, so the floors are
+# higher here than they would be for Voyage. Re-tune if changing embedding model.
+MIN_TOP_SCORE = 0.40  # below this we refuse outright (BGE-small cosine similarity)
+MIN_AVG_SCORE = 0.30  # average of top 5 must be above this
+
+
+@dataclass
+class FaithfulnessVerdict:
+    passed: bool
+    reasons: list[str] = field(default_factory=list)  # gate names that failed
+    unsupported_claims: list[str] = field(default_factory=list)
+    suggested_reply: Optional[str] = None  # what to show user if blocked
+
+
+# ============================================================================
+# Gate 1 — RETRIEVAL FLOOR
+# ============================================================================
+
+def _gate_retrieval_floor(chunks: list[RetrievedChunk]) -> tuple[bool, str]:
+    if not chunks:
+        return False, "no chunks retrieved"
+    top = chunks[0].score
+    avg = sum(c.score for c in chunks[:5]) / max(1, len(chunks[:5]))
+    if top < MIN_TOP_SCORE:
+        return False, f"top_score={top:.2f} below floor {MIN_TOP_SCORE}"
+    if avg < MIN_AVG_SCORE:
+        return False, f"avg_top5={avg:.2f} below floor {MIN_AVG_SCORE}"
+    return True, ""
+
+
+# ============================================================================
+# Gate 2 — CITATION INTEGRITY
+# ============================================================================
+
+# Match [Source: <something>] or [Regulation: <something>] patterns
+CITATION_PATTERN = re.compile(r"\[(?:Source|Regulation):\s*([^\]]+)\]", flags=re.IGNORECASE)
+
+
+def _gate_citation_integrity(reply: str, chunks: list[RetrievedChunk]) -> tuple[bool, list[str]]:
+    """Every cited policy name must be one we actually retrieved."""
+    cited = CITATION_PATTERN.findall(reply)
+    if not cited:
+        # No citations made — only OK if reply is a refusal
+        if any(kw in reply.lower() for kw in ("i don't see", "i don't have", "i'm not sure", "i couldn't find")):
+            return True, []
+        return False, ["citation_missing"]
+
+    valid_names = {c.policy_name.lower() for c in chunks}
+    valid_slugs = {c.insurer_slug.lower() for c in chunks}
+    fabricated = []
+    for citation in cited:
+        cit_lower = citation.lower()
+        # Permissive match — citation must contain a real policy or insurer slug
+        matched = any(name and name in cit_lower for name in valid_names if len(name) >= 4)
+        matched = matched or any(slug in cit_lower for slug in valid_slugs if len(slug) >= 4)
+        # Also accept regulatory citations once we have regulatory chunks (heuristic)
+        if "irda" in cit_lower or "regulation" in cit_lower:
+            has_regulatory_chunk = any("regulator" in c.doc_type.lower() or "irda" in c.policy_name.lower() for c in chunks)
+            if has_regulatory_chunk:
+                matched = True
+        if not matched:
+            fabricated.append(citation)
+    if fabricated:
+        return False, [f"fabricated_citation: {f}" for f in fabricated]
+    return True, []
+
+
+# ============================================================================
+# Gate 3 — NUMERIC GROUNDING
+# ============================================================================
+
+# Capture amounts (₹X / Rs.X / lakh / crore / NN%) and durations (NN days / months / years)
+RUPEE_RE = re.compile(r"₹\s*[\d,]+(?:\.\d+)?\s*(?:lakh|crore|cr|k)?", flags=re.IGNORECASE)
+PERCENT_RE = re.compile(r"\b\d{1,3}(?:\.\d+)?\s*%")
+DURATION_RE = re.compile(r"\b\d{1,4}\s*(?:day|days|month|months|year|years)\b", flags=re.IGNORECASE)
+
+
+def _normalize(s: str) -> str:
+    return re.sub(r"\s+", "", s.lower())
+
+
+def _gate_numeric_grounding(reply: str, chunks: list[RetrievedChunk]) -> tuple[bool, list[str]]:
+    """Every numeric value in the reply must appear in retrieved chunks (loose match)."""
+    combined = " ".join(c.text for c in chunks).lower()
+    combined_norm = _normalize(combined)
+
+    unsupported: list[str] = []
+    for pattern in (RUPEE_RE, PERCENT_RE, DURATION_RE):
+        for match in pattern.findall(reply):
+            norm = _normalize(match)
+            # Loose contains check
+            if norm in combined_norm:
+                continue
+            # Also accept the digit-only stem in case units differ
+            digit_only = re.sub(r"[^\d]", "", match)
+            if digit_only and len(digit_only) >= 2 and digit_only in re.sub(r"[^\d]", "", combined):
+                continue
+            unsupported.append(match.strip())
+
+    if unsupported:
+        return False, unsupported
+    return True, []
+
+
+# ============================================================================
+# Gate 4 — LLM-JUDGE FAITHFULNESS (Groq Llama)
+# ============================================================================
+
+_judge: Optional[GroqLLM] = None
+
+def _get_judge() -> GroqLLM:
+    global _judge
+    if _judge is None:
+        _judge = GroqLLM()
+    return _judge
+
+
+JUDGE_SYSTEM = """You are a strict faithfulness verifier for an insurance advisor bot.
+
+You will be given:
+  - RETRIEVED_CHUNKS: text from policy documents
+  - REPLY: the bot's answer to a user
+
+Your job: determine whether EVERY factual claim in REPLY is supported by RETRIEVED_CHUNKS. A claim is unsupported if the chunks don't say it, OR if the chunks contradict it.
+
+OUTPUT FORMAT — strict JSON, nothing else:
+{
+  "supported": true | false,
+  "unsupported_claims": ["claim 1", "claim 2", ...]
+}
+
+Be strict. The bot's job is to NOT hallucinate. If a claim is ambiguously supported (vague match), flag it. Soft-language is fine — only flag factual claims (numbers, coverage, exclusions, durations, citations).
+"""
+
+
+async def _gate_llm_judge(reply: str, chunks: list[RetrievedChunk]) -> tuple[bool, list[str]]:
+    if not reply or len(reply) < 30:
+        return True, []
+    if not chunks:
+        return False, ["no_chunks_to_verify_against"]
+
+    chunk_text = "\n\n---\n\n".join(
+        f"[{c.policy_name} ({c.insurer_slug}), p.{c.page_start}]\n{c.text[:2000]}" for c in chunks[:5]
+    )
+    user = f"""RETRIEVED_CHUNKS:
+{chunk_text}
+
+REPLY:
+{reply}
+
+Verify."""
+
+    try:
+        judge = _get_judge()
+        res = await judge.chat(
+            messages=[
+                ChatMessage(role="system", content=JUDGE_SYSTEM),
+                ChatMessage(role="user", content=user),
+            ],
+            temperature=0.0,
+            max_tokens=400,
+            response_format={"type": "json_object"},
+        )
+        data = json.loads(res.text)
+        supported = bool(data.get("supported", False))
+        unsupported = list(data.get("unsupported_claims", []))
+        return supported, unsupported
+    except Exception as e:
+        # If judge fails, fail-open with a warning (don't block valid replies on infra hiccup)
+        return True, [f"judge_error_failopen: {type(e).__name__}"]
+
+
+# ============================================================================
+# Main entry — orchestrator calls this
+# ============================================================================
+
+REFUSAL_TEMPLATE = (
+    "I'd rather not answer that without stronger evidence in the policy documents I have. "
+    "Could you rephrase, or narrow your question to a specific policy?"
+)
+
+
+async def check_faithfulness(
+    reply: str,
+    chunks: list[RetrievedChunk],
+    user_text: str = "",
+    run_llm_judge: bool = True,
+) -> FaithfulnessVerdict:
+    """Run all gates. Return verdict with reasons + a safe reply to show user if blocked."""
+    verdict = FaithfulnessVerdict(passed=True)
+
+    # Gate 1 — retrieval floor
+    ok1, msg1 = _gate_retrieval_floor(chunks)
+    if not ok1:
+        verdict.passed = False
+        verdict.reasons.append(f"gate1_retrieval: {msg1}")
+
+    # If retrieval already failed, suggest refusal and skip downstream gates
+    if not verdict.passed:
+        verdict.suggested_reply = REFUSAL_TEMPLATE
+        _log_block(user_text, reply, verdict, chunks)
+        return verdict
+
+    # Gate 2 — citation integrity
+    ok2, bad_citations = _gate_citation_integrity(reply, chunks)
+    if not ok2:
+        verdict.passed = False
+        verdict.reasons.extend(bad_citations)
+
+    # Gate 3 — numeric grounding
+    ok3, bad_nums = _gate_numeric_grounding(reply, chunks)
+    if not ok3:
+        verdict.passed = False
+        verdict.reasons.extend([f"unsupported_number: {n}" for n in bad_nums])
+        verdict.unsupported_claims.extend(bad_nums)
+
+    # Gate 4 — LLM judge (only if previous gates passed — saves token cost on obvious failures)
+    if verdict.passed and run_llm_judge:
+        ok4, unsupported = await _gate_llm_judge(reply, chunks)
+        if not ok4:
+            verdict.passed = False
+            verdict.reasons.append("gate4_llm_judge: claims unsupported")
+            verdict.unsupported_claims.extend(unsupported)
+
+    if not verdict.passed:
+        verdict.suggested_reply = REFUSAL_TEMPLATE
+        _log_block(user_text, reply, verdict, chunks)
+
+    return verdict
+
+
+# ============================================================================
+# Audit log
+# ============================================================================
+
+def _log_block(user_text: str, reply: str, verdict: FaithfulnessVerdict, chunks: list[RetrievedChunk]) -> None:
+    """Append every faithfulness block to logs/hallucinations.jsonl for compliance audit."""
+    entry = {
+        "ts": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "user_text": user_text,
+        "blocked_reply": reply,
+        "reasons": verdict.reasons,
+        "unsupported_claims": verdict.unsupported_claims,
+        "chunk_count": len(chunks),
+        "top_score": chunks[0].score if chunks else None,
+        "policy_ids": list({c.policy_id for c in chunks}),
+    }
+    with open(HALLUCINATION_LOG, "a") as f:
+        f.write(json.dumps(entry) + "\n")

backend/main.py

@@ -0,0 +1,275 @@
+"""FastAPI app — the backend API for the Insurance Sales Portfolio Expert.
+
+Run locally:
+  uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000
+
+Interactive docs at http://localhost:8000/docs
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import time
+import uuid
+from pathlib import Path
+from typing import Optional
+
+from fastapi import FastAPI, File, Form, HTTPException, UploadFile
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel, Field
+
+from backend.config import settings
+from backend.orchestrator import handle_turn
+from backend.providers.sarvam_stt import SarvamSTT
+from backend.providers.sarvam_tts import SarvamTTS
+
+# Singleton provider instances (initialized on first call)
+_stt: Optional[SarvamSTT] = None
+_tts: Optional[SarvamTTS] = None
+
+def get_stt() -> SarvamSTT:
+    global _stt
+    if _stt is None:
+        _stt = SarvamSTT()
+    return _stt
+
+def get_tts() -> SarvamTTS:
+    global _tts
+    if _tts is None:
+        _tts = SarvamTTS()
+    return _tts
+
+
+# ---------- log helpers ----------
+
+LOG_DIR = settings.CORPUS_DIR.parent.parent / "logs"
+LOG_DIR.mkdir(exist_ok=True)
+TURNS_LOG = LOG_DIR / "turns.jsonl"
+
+
+def log_turn(event: dict) -> None:
+    event["ts"] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+    with open(TURNS_LOG, "a") as f:
+        f.write(json.dumps(event) + "\n")
+
+
+# ---------- API schemas ----------
+
+class HealthResponse(BaseModel):
+    status: str
+    providers_ok: dict[str, bool]
+    missing_keys: list[str]
+
+
+class TranscribeResponse(BaseModel):
+    text: str
+    language_code: Optional[str] = None
+    confidence: Optional[float] = None
+    latency_ms: int
+
+
+class CitationOut(BaseModel):
+    policy_id: str
+    policy_name: str
+    insurer_slug: str
+    page_start: int
+    page_end: int
+    source_url: str
+    score: float
+
+
+class ChatRequest(BaseModel):
+    user_text: str = Field(..., description="The user's question or utterance")
+    session_id: Optional[str] = Field(None, description="Stable per-session ID for logging")
+    chat_history: list[dict] = Field(default_factory=list, description="[{role, content}, ...]")
+    profile: dict = Field(default_factory=dict, description="User profile (age, dependents, etc.)")
+    policy_filter_ids: Optional[list[str]] = Field(None, description="Restrict retrieval to these policies")
+    return_audio: bool = Field(False, description="If true, also return TTS audio (base64 WAV)")
+    tts_language_code: str = Field("en-IN", description="Language for TTS playback")
+
+
+class ChatResponse(BaseModel):
+    reply_text: str
+    citations: list[CitationOut]
+    brain_used: str
+    intent: str
+    language: str
+    latency_ms: int
+    session_id: str
+    audio_base64: Optional[str] = None
+    faithfulness_passed: bool = True
+    faithfulness_reasons: list[str] = Field(default_factory=list)
+    blocked: bool = False
+
+
+class TTSRequest(BaseModel):
+    text: str
+    language_code: str = "en-IN"
+    speaker: Optional[str] = None
+
+
+# ---------- app ----------
+
+app = FastAPI(
+    title="Insurance Sales Portfolio Expert API",
+    description="Backend for the Sarvam AI take-home assignment.",
+    version="0.1.0",
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],  # tighten for production deploy
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+@app.get("/api/health", response_model=HealthResponse)
+async def health():
+    missing = settings.validate()
+    providers_ok = {
+        "sarvam": bool(settings.SARVAM_API_KEY),
+        "voyage": bool(settings.VOYAGE_API_KEY),
+        "groq": bool(settings.GROQ_API_KEY),
+        "openrouter": bool(settings.OPENROUTER_API_KEY),
+    }
+    return HealthResponse(
+        status="ok" if not missing else "degraded",
+        providers_ok=providers_ok,
+        missing_keys=missing,
+    )
+
+
+@app.post("/api/transcribe", response_model=TranscribeResponse)
+async def transcribe(
+    file: UploadFile = File(...),
+    language_code: Optional[str] = Form(None),
+):
+    """Speech-to-text. Accepts an audio file upload (WAV/MP3/etc.)."""
+    t0 = time.time()
+    audio_bytes = await file.read()
+    ext = (file.filename or "audio.wav").rsplit(".", 1)[-1].lower()
+    try:
+        result = await get_stt().transcribe(
+            audio_bytes=audio_bytes,
+            audio_format=ext if ext in ("wav", "mp3", "flac", "ogg", "m4a") else "wav",
+            language_code=language_code,
+        )
+    except Exception as e:
+        raise HTTPException(500, f"STT failed: {type(e).__name__}: {e}")
+    latency = int((time.time() - t0) * 1000)
+    return TranscribeResponse(
+        text=result.text,
+        language_code=result.language_code,
+        confidence=result.confidence,
+        latency_ms=latency,
+    )
+
+
+@app.post("/api/chat", response_model=ChatResponse)
+async def chat(req: ChatRequest):
+    session_id = req.session_id or str(uuid.uuid4())
+    try:
+        turn = await handle_turn(
+            user_text=req.user_text,
+            chat_history=req.chat_history,
+            user_profile=req.profile,
+            policy_filter_ids=req.policy_filter_ids,
+        )
+    except Exception as e:
+        log_turn({
+            "session_id": session_id,
+            "user_text": req.user_text,
+            "error": f"{type(e).__name__}: {e}",
+        })
+        raise HTTPException(500, f"Orchestrator failed: {type(e).__name__}: {e}")
+
+    audio_b64 = None
+    if req.return_audio and turn.reply_text:
+        try:
+            audio = await get_tts().synthesize(turn.reply_text, language_code=req.tts_language_code)
+            audio_b64 = base64.b64encode(audio).decode("utf-8")
+        except Exception as e:
+            # Don't fail the whole turn if TTS hiccups — log + return text only
+            log_turn({"session_id": session_id, "tts_error": f"{type(e).__name__}: {e}"})
+
+    log_turn({
+        "session_id": session_id,
+        "user_text": req.user_text,
+        "reply_text": turn.reply_text,
+        "brain_used": turn.brain_used,
+        "intent": turn.intent,
+        "language": turn.language,
+        "latency_ms": turn.latency_ms,
+        "retrieved_chunk_ids": turn.retrieved_chunk_ids,
+        "citation_count": len(turn.citations),
+        "faithfulness_passed": turn.faithfulness_passed,
+        "faithfulness_reasons": turn.faithfulness_reasons,
+        "blocked": turn.blocked,
+    })
+
+    return ChatResponse(
+        reply_text=turn.reply_text,
+        citations=[CitationOut(**c) for c in turn.citations],
+        brain_used=turn.brain_used,
+        intent=turn.intent,
+        language=turn.language,
+        latency_ms=turn.latency_ms,
+        session_id=session_id,
+        audio_base64=audio_b64,
+        faithfulness_passed=turn.faithfulness_passed,
+        faithfulness_reasons=turn.faithfulness_reasons,
+        blocked=turn.blocked,
+    )
+
+
+@app.post("/api/tts")
+async def tts(req: TTSRequest):
+    """Standalone TTS endpoint — returns base64 WAV."""
+    try:
+        audio = await get_tts().synthesize(
+            text=req.text,
+            language_code=req.language_code,
+            speaker=req.speaker,
+        )
+    except Exception as e:
+        raise HTTPException(500, f"TTS failed: {type(e).__name__}: {e}")
+    return JSONResponse({"audio_base64": base64.b64encode(audio).decode("utf-8")})
+
+
+@app.get("/api")
+async def api_root():
+    return {
+        "service": "Insurance Sales Portfolio Expert API",
+        "version": "0.1.0",
+        "docs": "/docs",
+        "health": "/api/health",
+    }
+
+
+# ---- Static frontend (served alongside /api on the same port for HF Spaces) ----
+# The Next.js frontend is statically exported during the Docker build to
+# /app/frontend/out. In local dev, this directory may not exist — we still
+# want the backend to start cleanly.
+import os
+from pathlib import Path as _Path
+
+_FRONTEND_DIR = _Path(__file__).resolve().parent.parent / "frontend" / "out"
+if _FRONTEND_DIR.exists():
+    # Serve the built site as the catch-all. /api/* routes registered above
+    # take precedence because they are matched first.
+    app.mount("/", StaticFiles(directory=str(_FRONTEND_DIR), html=True), name="static")
+else:
+    @app.get("/")
+    async def root():
+        return {
+            "service": "Insurance Sales Portfolio Expert API",
+            "version": "0.1.0",
+            "frontend": "not built — run `cd frontend && npm run build`",
+            "docs": "/docs",
+            "health": "/api/health",
+        }

backend/needs_finder.py

@@ -0,0 +1,210 @@
+"""Adaptive fact-find question graph.
+
+Inspired by what a good Independent Financial Advisor does in the first 10
+minutes of a consultation: ask a stable core of questions, then deep-dive
+conditionally based on signal. The depth is adaptive — stop when we have
+enough to recommend.
+
+The graph is explicit (not LLM-improvised) so:
+  - A reviewer can see and audit it
+  - Behavior is testable
+  - Failure modes are tractable
+  - It works without an LLM (fallback when the brain is degraded)
+
+Public API:
+  - Profile dataclass — accumulated user state
+  - next_question(profile) -> str | None   (None = ready to recommend)
+  - record_answer(profile, question_id, answer) -> Profile
+  - readback_summary(profile) -> str
+
+The orchestrator can choose to drive the fact-find OR let the user
+free-form questions — the graph supports both.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+
+@dataclass
+class Profile:
+    """User profile accumulated during fact-find."""
+    age: Optional[int] = None
+    dependents: Optional[str] = None  # "self", "self+spouse", "self+spouse+kids", "self+parents", etc.
+    income_band: Optional[str] = None  # "under_5L", "5L-10L", "10L-25L", "25L+"
+    existing_cover_inr: Optional[int] = None  # 0 means none
+    primary_goal: Optional[str] = None  # "first_buy", "upgrade", "compare_specific", "tax_planning"
+    location_tier: Optional[str] = None  # "metro", "tier1", "tier2", "tier3"
+    parents_to_insure: Optional[bool] = None
+    parents_age_max: Optional[int] = None  # if parents_to_insure
+    parents_has_ped: Optional[bool] = None  # if parents_to_insure
+    budget_band: Optional[str] = None  # "under_15k", "15k_30k", "30k_60k", "60k+"
+    health_conditions: Optional[list[str]] = field(default_factory=list)  # ["diabetes", "hypertension", ...]
+    asked: list[str] = field(default_factory=list)  # question IDs already asked
+    free_form_session: bool = False  # True = user asks free questions, not driven by us
+
+
+# ----------------------------------------------------------------------------
+# Question graph — each node has an id, a prompt, and a condition for being
+# asked. Conditions are pure functions of the current Profile.
+# ----------------------------------------------------------------------------
+
+@dataclass
+class Question:
+    id: str
+    prompt_en: str
+    prompt_hi: str  # optional Hindi rendering (used when language='indic')
+    field: str
+    is_core: bool = False
+    condition: Any = None  # callable(profile) -> bool, default: always ask
+    parser: Any = None  # callable(text) -> value, default: text as-is
+
+
+def _always(p: Profile) -> bool:
+    return True
+
+
+GRAPH: list[Question] = [
+    Question(
+        id="age",
+        prompt_en="To start, what's your age?",
+        prompt_hi="शुरू करते हैं — आपकी उम्र क्या है?",
+        field="age",
+        is_core=True,
+        parser=lambda s: int("".join(c for c in str(s) if c.isdigit())[:3] or 0) or None,
+    ),
+    Question(
+        id="dependents",
+        prompt_en="Who else do you want to cover — just yourself, your spouse, kids, or parents too?",
+        prompt_hi="आपके अलावा किस-किस को cover करना है — पति/पत्नी, बच्चे, माता-पिता?",
+        field="dependents",
+        is_core=True,
+    ),
+    Question(
+        id="income_band",
+        prompt_en="Roughly what's your annual income — under 5 lakh, 5-10, 10-25, or 25+ lakh?",
+        prompt_hi="आपकी सालाना आय लगभग कितनी है — 5 लाख से कम, 5-10, 10-25, या 25 लाख से ज्यादा?",
+        field="income_band",
+        is_core=True,
+    ),
+    Question(
+        id="existing_cover",
+        prompt_en="Do you already have any health insurance — employer-provided or your own? How much sum insured?",
+        prompt_hi="क्या आपके पास पहले से कोई health insurance है — employer का या खुद का? Sum insured कितना है?",
+        field="existing_cover_inr",
+        is_core=True,
+    ),
+    Question(
+        id="primary_goal",
+        prompt_en="What's brought you here today — first health policy, upgrading existing cover, comparing specific policies, or tax planning?",
+        prompt_hi="आज आप यहाँ क्यों आए — पहली बार health policy ले रहे हैं, मौजूदा बढ़ाना है, specific policies compare करनी हैं, या tax planning के लिए?",
+        field="primary_goal",
+        is_core=True,
+    ),
+    Question(
+        id="location",
+        prompt_en="Which city do you live in? (Metro, tier-1, or smaller town?)",
+        prompt_hi="आप किस शहर में रहते हैं? (Metro, tier-1, या छो��ा शहर?)",
+        field="location_tier",
+        is_core=True,
+    ),
+    # Conditional deep-dives
+    Question(
+        id="parents_age",
+        prompt_en="What are your parents' ages, and do either of them have any pre-existing conditions like diabetes or BP?",
+        prompt_hi="आपके माता-पिता की उम्र क्या है, और क्या उनमें से किसी को diabetes या BP जैसी कोई pre-existing condition है?",
+        field="parents_age_max",
+        condition=lambda p: bool(p.dependents and "parent" in p.dependents.lower()),
+    ),
+    Question(
+        id="health_conditions",
+        prompt_en="Any pre-existing health conditions on your side — diabetes, BP, thyroid, anything chronic?",
+        prompt_hi="आपकी तरफ से कोई pre-existing condition है — diabetes, BP, thyroid, कुछ chronic?",
+        field="health_conditions",
+        condition=_always,
+    ),
+    Question(
+        id="budget",
+        prompt_en="What annual premium budget are you comfortable with — under 15K, 15-30K, 30-60K, or 60K+?",
+        prompt_hi="Premium के लिए सालाना कितना खर्च करना चाहेंगे — 15K से कम, 15-30K, 30-60K, या 60K+?",
+        field="budget_band",
+        is_core=True,
+    ),
+]
+
+
+# ----------------------------------------------------------------------------
+# Engine
+# ----------------------------------------------------------------------------
+
+def is_field_set(profile: Profile, field_name: str) -> bool:
+    v = getattr(profile, field_name, None)
+    if v is None:
+        return False
+    if isinstance(v, (list, str)) and len(v) == 0:
+        return False
+    return True
+
+
+def next_question(profile: Profile, language: str = "en") -> Optional[Question]:
+    """Return the next question to ask, or None if we have enough to recommend."""
+    if profile.free_form_session:
+        return None
+
+    for q in GRAPH:
+        if q.id in profile.asked:
+            continue
+        if is_field_set(profile, q.field):
+            continue
+        cond = q.condition or _always
+        if cond(profile):
+            return q
+
+    # All applicable questions asked
+    return None
+
+
+def record_answer(profile: Profile, question_id: str, raw_answer: str) -> Profile:
+    """Mutate profile in place with a parsed answer."""
+    q = next((x for x in GRAPH if x.id == question_id), None)
+    if q is None:
+        return profile
+    profile.asked.append(question_id)
+    value: Any = raw_answer
+    if q.parser:
+        try:
+            value = q.parser(raw_answer)
+        except Exception:
+            value = None
+    if value is not None and value != "":
+        setattr(profile, q.field, value)
+    return profile
+
+
+def readback_summary(profile: Profile) -> str:
+    """One-paragraph human-readable summary of the gathered profile."""
+    bits = []
+    if profile.age:
+        bits.append(f"{profile.age} years old")
+    if profile.dependents:
+        bits.append(f"covering {profile.dependents}")
+    if profile.income_band:
+        bits.append(f"income {profile.income_band}")
+    if profile.existing_cover_inr is not None:
+        bits.append(
+            f"existing cover ₹{profile.existing_cover_inr:,}"
+            if profile.existing_cover_inr > 0
+            else "no existing cover"
+        )
+    if profile.primary_goal:
+        bits.append(f"primary goal: {profile.primary_goal}")
+    if profile.location_tier:
+        bits.append(profile.location_tier)
+    if profile.parents_age_max:
+        bits.append(f"parents up to age {profile.parents_age_max}")
+    if profile.health_conditions:
+        bits.append(f"conditions: {', '.join(profile.health_conditions)}")
+    if profile.budget_band:
+        bits.append(f"budget {profile.budget_band}")
+    return "; ".join(bits) if bits else "(no profile yet)"

backend/orchestrator.py

@@ -0,0 +1,191 @@
+"""Orchestrator — the brain of the bot.
+
+For each user turn:
+  1. Retrieve top-k relevant chunks from Chroma
+  2. Format them as cited context
+  3. Build messages with persona + history + profile
+  4. Route to a brain LLM (Sarvam-M primary, Llama/DeepSeek fallback for complex)
+  5. Strip <think> tags from Sarvam-M output
+  6. Return (reply_text, citations[], retrieved_chunk_ids[], cost_estimate)
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Optional
+
+from backend.faithfulness import check_faithfulness, FaithfulnessVerdict
+from backend.persona import build_messages, strip_think_tags
+from backend.providers.base import ChatMessage, LLMProvider
+from backend.providers.groq_llm import GroqLLM
+from backend.providers.openrouter_llm import OpenRouterLLM
+from backend.providers.sarvam_llm import SarvamLLM
+from rag.retrieve import RetrievedChunk, format_for_llm_context, retrieve
+
+
+# ---------- intent classification (v1: keyword heuristics) ----------
+
+COMPARISON_KEYWORDS = ("compare", "comparison", "vs", "versus", "between", "better")
+RECOMMEND_KEYWORDS = ("recommend", "should i", "which one", "best for", "suit me")
+INDIC_KEYWORDS = (
+    # Devanagari letters
+    "क", "ख", "ग", "घ", "च", "ज", "ट", "ड", "त", "द", "न", "प", "ब", "म", "य", "र", "ल", "व", "स", "ह",
+    # common Hinglish words
+    " hai ", " kya ", " mein ", " kar ", " ka ", " ki ", " ke ", " liye ", " mujhe ",
+)
+
+
+def classify_intent(query: str) -> str:
+    q = query.lower()
+    if any(kw in q for kw in COMPARISON_KEYWORDS):
+        return "comparison"
+    if any(kw in q for kw in RECOMMEND_KEYWORDS):
+        return "recommendation"
+    return "qa"
+
+
+def detect_language(query: str) -> str:
+    q = query.lower()
+    if any(kw in q for kw in INDIC_KEYWORDS):
+        return "indic"
+    if any(c in query for c in "अआइईउऊऋएऐओऔकखगघचछजझटठडढतथदधनपफबभमयरलवशषसह"):
+        return "indic"
+    return "en"
+
+
+# ---------- brain router ----------
+
+@dataclass
+class BrainPick:
+    provider: LLMProvider
+    reason: str
+
+
+def pick_brain(intent: str, language: str) -> BrainPick:
+    """Route to the right brain per Doc decisions.md D-016.
+
+    v1 heuristic (will be refined by gold eval results):
+      - Indic queries -> Sarvam-M (it's the Indic-strongest)
+      - Simple QA in English -> Sarvam-M (it's primary)
+      - Comparison/recommendation -> OpenRouter DeepSeek-V3 (strongest reasoning)
+      - (Llama-3.3-70B reserved for grader; used as fallback if DeepSeek fails)
+    """
+    if language == "indic":
+        return BrainPick(SarvamLLM(), "indic-query")
+    if intent in ("comparison", "recommendation"):
+        return BrainPick(OpenRouterLLM(), f"complex-{intent}")
+    return BrainPick(SarvamLLM(), "simple-qa")
+
+
+# ---------- main entrypoint ----------
+
+@dataclass
+class TurnResult:
+    reply_text: str
+    citations: list[dict]
+    retrieved_chunk_ids: list[str]
+    brain_used: str
+    intent: str
+    language: str
+    latency_ms: int
+    raw_reply: str
+    faithfulness_passed: bool = True
+    faithfulness_reasons: list[str] = field(default_factory=list)
+    blocked: bool = False
+
+
+async def handle_turn(
+    user_text: str,
+    chat_history: Optional[list[dict]] = None,
+    user_profile: Optional[dict] = None,
+    policy_filter_ids: Optional[list[str]] = None,
+    top_k: int = 5,
+) -> TurnResult:
+    t0 = time.time()
+
+    # 1. Classify
+    intent = classify_intent(user_text)
+    language = detect_language(user_text)
+
+    # 2. Retrieve
+    chunks: list[RetrievedChunk] = await retrieve(
+        query=user_text,
+        top_k=top_k,
+        policy_ids=policy_filter_ids,
+    )
+    context_str = format_for_llm_context(chunks)
+
+    # 3. Pick brain
+    pick = pick_brain(intent, language)
+
+    # 4. Generate
+    messages_dict = build_messages(
+        user_query=user_text,
+        retrieved_context=context_str,
+        chat_history=chat_history,
+        user_profile=user_profile,
+    )
+    messages = [ChatMessage(role=m["role"], content=m["content"]) for m in messages_dict]
+
+    try:
+        llm_result = await pick.provider.chat(messages=messages, temperature=0.2, max_tokens=1500)
+    except Exception as e:
+        # Fallback to Groq Llama if primary brain fails
+        fallback = GroqLLM()
+        llm_result = await fallback.chat(messages=messages, temperature=0.2, max_tokens=1500)
+        pick = BrainPick(fallback, f"fallback-after-{type(e).__name__}")
+
+    # Detect truncated <think> reasoning — if so, retry with Groq (no reasoning tags)
+    if "<think>" in llm_result.text.lower() and "</think>" not in llm_result.text.lower():
+        try:
+            fallback = GroqLLM()
+            llm_result = await fallback.chat(messages=messages, temperature=0.2, max_tokens=1500)
+            pick = BrainPick(fallback, "fallback-truncated-reasoning")
+        except Exception:
+            pass
+
+    raw = llm_result.text
+    reply = strip_think_tags(raw)
+
+    # 5. FAITHFULNESS GATE — every reply runs through 4-gate verification.
+    #    If any gate fails, replace the reply with a safe refusal. The original
+    #    blocked reply is logged to logs/hallucinations.jsonl for audit.
+    verdict: FaithfulnessVerdict = await check_faithfulness(
+        reply=reply,
+        chunks=chunks,
+        user_text=user_text,
+        run_llm_judge=True,
+    )
+    blocked = False
+    if not verdict.passed:
+        blocked = True
+        reply = verdict.suggested_reply or "I don't have grounded evidence for that. Could you rephrase?"
+
+    # 6. Citations (derived from retrieved chunks)
+    citations = [
+        {
+            "policy_id": c.policy_id,
+            "policy_name": c.policy_name,
+            "insurer_slug": c.insurer_slug,
+            "page_start": c.page_start,
+            "page_end": c.page_end,
+            "source_url": c.source_url,
+            "score": round(c.score, 3),
+        }
+        for c in chunks
+    ]
+
+    return TurnResult(
+        reply_text=reply,
+        citations=citations,
+        retrieved_chunk_ids=[c.chunk_id for c in chunks],
+        brain_used=f"{pick.provider.name}::{pick.reason}",
+        intent=intent,
+        language=language,
+        latency_ms=int((time.time() - t0) * 1000),
+        raw_reply=raw,
+        faithfulness_passed=verdict.passed,
+        faithfulness_reasons=verdict.reasons,
+        blocked=blocked,
+    )

backend/persona.py

@@ -0,0 +1,108 @@
+"""System prompts and persona definitions for the insurance advisor.
+
+The persona is consultative, not closing. Citation grammar is non-negotiable.
+Refusal on weak grounding is a feature, not a bug.
+
+These prompts will be A/B-tested via the eval harness; current version is v0.1.
+"""
+
+ADVISOR_SYSTEM_PROMPT_V1 = """You are an experienced, consultative insurance advisor specializing in Indian health insurance. You speak like a trusted Independent Financial Advisor (IFA), not a call-center salesperson.
+
+YOUR ROLE
+- Help buyers understand policies, compare options, and choose what fits their situation
+- Educate when needed, recommend only when the buyer's profile clearly fits
+- It is OK — and often correct — to say "this policy isn't right for you"
+
+ABSOLUTE RULES (these are non-negotiable)
+
+1. GROUNDED ANSWERS ONLY. Every factual claim about a policy or regulation MUST come from the retrieved clauses provided in the context — NOTHING from your training memory. Specifically:
+   - NEVER cite IRDAI regulations or numbers unless the IRDAI text appears in the retrieved context
+   - NEVER cite Section 80D, GST rates, or any law unless it appears in the retrieved context
+   - NEVER cite "industry standard" or "typically" — there is only what the document says
+   If the answer is not in the retrieved context, say:
+   "I don't see that covered in this policy document. Would you like me to check what IS covered in this category?"
+   Hallucinated facts in BFSI = mis-selling = regulated offense.
+
+2. CITATION GRAMMAR. End every factual claim with an inline citation.
+   - For policy clauses: [Source: <Policy Name> (<insurer-slug>), p.<page>]
+   - For regulatory mandates: [Regulation: <Doc Name> (IRDAI / Govt), §<section>]
+   When a regulation OVERRIDES a policy clause (e.g., IRDAI mandates 30-day initial waiting period as a minimum), surface both. Regulatory citations are STRONGER signals than policy text — flag them when relevant.
+   For multi-policy compares, cite each policy separately.
+
+3. CONCISE FOR VOICE. Default reply length: under 60 words. Buyers hear this over voice — long replies are unusable. Use bullet points sparingly; prefer short complete sentences.
+
+4. NEVER GIVE MEDICAL ADVICE. "Will this be covered if I have X condition?" → answer the COVERAGE question, never the medical one.
+
+5. NEVER GIVE FINAL TRANSACTIONAL ADVICE. "Should I buy this?" is a guidance question, not a transactional one. Always anchor recommendations in the buyer's stated profile, and end with: "I'd recommend you confirm with the insurer directly before finalizing."
+
+6. INDIC + ENGLISH. If the user writes in Hindi or Hinglish, reply in the same mix. If they write English, reply in English. Match their register.
+
+7. NO SCARE TACTICS. Never use fear-of-missing-out or worst-case framing to push a sale.
+
+FORMAT FOR YOUR REPLIES
+- Direct answer first sentence
+- Supporting fact(s) with inline citations
+- Optional 1-line caveat if relevant (e.g., "note: this has a 36-month waiting period for PED")
+- No preamble like "Sure!" or "Great question!"
+"""
+
+
+def build_messages(
+    user_query: str,
+    retrieved_context: str,
+    chat_history: list[dict] | None = None,
+    user_profile: dict | None = None,
+) -> list[dict]:
+    """Assemble the message list for the LLM call."""
+    system = ADVISOR_SYSTEM_PROMPT_V1
+    if user_profile:
+        profile_summary = "\nUSER PROFILE (for personalization, do not echo verbatim):\n" + "\n".join(
+            f"- {k}: {v}" for k, v in user_profile.items() if v not in (None, "", [])
+        )
+        system = system + profile_summary
+
+    messages: list[dict] = [{"role": "system", "content": system}]
+
+    # History (excluding the last user turn — we add it below with context)
+    if chat_history:
+        for msg in chat_history[-10:]:  # cap to last 5 turns
+            messages.append({"role": msg["role"], "content": msg["content"]})
+
+    user_block = f"""USER QUESTION:
+{user_query}
+
+RETRIEVED POLICY CLAUSES (use ONLY these for factual claims):
+{retrieved_context if retrieved_context else "(no relevant clauses retrieved)"}
+
+Reply now per the rules above."""
+    messages.append({"role": "user", "content": user_block})
+    return messages
+
+
+# Strip Sarvam-M's <think>...</think> reasoning chains before returning to user.
+import re
+
+THINK_PATTERN = re.compile(r"<think>.*?</think>", flags=re.DOTALL | re.IGNORECASE)
+OPEN_THINK = re.compile(r"<think>", flags=re.IGNORECASE)
+CLOSE_THINK = re.compile(r"</think>", flags=re.IGNORECASE)
+
+
+def strip_think_tags(text: str) -> str:
+    """Sarvam-M emits <think>...</think> chain-of-thought before the final answer.
+
+    Handle:
+      - well-formed: <think>...</think> answer  →  answer
+      - truncated reasoning (no </think>):  <think>... cut off  →  fallback message
+      - reasoning followed by clean answer:  <think>...</think> answer  →  answer
+      - well-formed with extra text after close: take only text after </think>
+    """
+    if "<think>" in text.lower() and "</think>" not in text.lower():
+        # Reasoning was truncated mid-thought — no final answer was produced.
+        return "I'm thinking through that. Could you rephrase or ask a follow-up?"
+
+    # Strip all complete <think>...</think> blocks.
+    cleaned = THINK_PATTERN.sub("", text).strip()
+    # If anything else got truncated, fall back gracefully.
+    if not cleaned:
+        return "I'm thinking through that. Could you rephrase or ask a follow-up?"
+    return cleaned

backend/providers/__init__.py

@@ -0,0 +1,13 @@
+"""Provider clients — thin, async, behind a common interface.
+
+Each provider lives in its own module:
+  sarvam_stt.py        — Sarvam Saarika v2.5 (speech-to-text)
+  sarvam_tts.py        — Sarvam Bulbul (text-to-speech)
+  sarvam_llm.py        — Sarvam-M (chat / generation, primary brain)
+  voyage_embeddings.py — Voyage voyage-3 (embeddings)
+  groq_llm.py          — Llama-3.3-70B on Groq (grader + medium fallback brain)
+  openrouter_llm.py    — DeepSeek-V3 via OpenRouter (strongest fallback brain)
+
+All clients are async (use httpx.AsyncClient) so the FastAPI handlers can
+parallelize provider calls without blocking the event loop.
+"""

backend/providers/_smoke_test.py

@@ -0,0 +1,161 @@
+"""Smoke-test every provider before building anything on top.
+
+Run from project root:
+  python -m backend.providers._smoke_test
+
+Each test prints OK/FAIL and the response. Failures here will surface in the
+build before they surface in the UI.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import traceback
+
+from backend.config import settings
+from backend.providers.base import ChatMessage
+from backend.providers.sarvam_llm import SarvamLLM
+from backend.providers.sarvam_stt import SarvamSTT
+from backend.providers.sarvam_tts import SarvamTTS
+from backend.providers.voyage_embeddings import VoyageEmbeddings
+from backend.providers.groq_llm import GroqLLM
+from backend.providers.openrouter_llm import OpenRouterLLM
+
+
+async def test_sarvam_llm():
+    print("\n--- Sarvam-M LLM ---")
+    try:
+        client = SarvamLLM()
+        result = await client.chat(
+            messages=[
+                ChatMessage(role="system", content="You are a helpful insurance advisor. Keep replies under 20 words."),
+                ChatMessage(role="user", content="What does PED stand for in health insurance?"),
+            ],
+            max_tokens=100,
+        )
+        print(f"OK | model={result.model} | reply: {result.text[:200]}")
+        print(f"   tokens prompt={result.prompt_tokens} completion={result.completion_tokens}")
+        return True
+    except Exception as e:
+        print(f"FAIL | {type(e).__name__}: {e}")
+        traceback.print_exc()
+        return False
+
+
+async def test_sarvam_tts():
+    print("\n--- Sarvam Bulbul TTS ---")
+    try:
+        client = SarvamTTS()
+        audio = await client.synthesize(
+            text="Hello, I am your insurance advisor.",
+            language_code="en-IN",
+        )
+        print(f"OK | got {len(audio)} bytes of audio")
+        # Save for manual inspection
+        out = settings.CORPUS_DIR.parent / "_smoke_tts.wav"
+        out.write_bytes(audio)
+        print(f"   saved to {out.relative_to(settings.CORPUS_DIR.parent.parent)}")
+        return True
+    except Exception as e:
+        print(f"FAIL | {type(e).__name__}: {e}")
+        traceback.print_exc()
+        return False
+
+
+async def test_voyage():
+    print("\n--- Voyage embeddings ---")
+    try:
+        client = VoyageEmbeddings()
+        vectors = await client.embed(["the cataract waiting period is 24 months", "policy covers ayurveda"])
+        print(f"OK | got {len(vectors)} vectors, dim={len(vectors[0])}")
+        return True
+    except Exception as e:
+        print(f"FAIL | {type(e).__name__}: {e}")
+        traceback.print_exc()
+        return False
+
+
+async def test_groq():
+    print("\n--- Groq Llama-3.3-70B (grader + medium fallback) ---")
+    try:
+        client = GroqLLM()
+        result = await client.chat(
+            messages=[
+                ChatMessage(role="system", content="You are a strict evaluator. Reply YES or NO only."),
+                ChatMessage(role="user", content="Is '24 months' semantically equivalent to '2 years'? YES or NO."),
+            ],
+            max_tokens=10,
+            temperature=0.0,
+        )
+        print(f"OK | model={result.model} | reply: {result.text!r}")
+        return True
+    except Exception as e:
+        print(f"FAIL | {type(e).__name__}: {e}")
+        traceback.print_exc()
+        return False
+
+
+async def test_openrouter():
+    print("\n--- OpenRouter DeepSeek-V3 (strongest fallback brain) ---")
+    try:
+        client = OpenRouterLLM()
+        result = await client.chat(
+            messages=[
+                ChatMessage(role="system", content="You are a precise insurance advisor."),
+                ChatMessage(role="user", content="Briefly: what does 'sum insured' mean in health insurance? Under 25 words."),
+            ],
+            max_tokens=100,
+        )
+        print(f"OK | model={result.model} | reply: {result.text[:200]}")
+        return True
+    except Exception as e:
+        print(f"FAIL | {type(e).__name__}: {e}")
+        traceback.print_exc()
+        return False
+
+
+async def test_sarvam_stt():
+    """STT needs an audio file. We reuse the TTS output if it ran successfully."""
+    print("\n--- Sarvam Saarika STT ---")
+    try:
+        audio_path = settings.CORPUS_DIR.parent / "_smoke_tts.wav"
+        if not audio_path.exists():
+            print("SKIP | no _smoke_tts.wav (TTS must run first)")
+            return False
+        audio_bytes = audio_path.read_bytes()
+        client = SarvamSTT()
+        result = await client.transcribe(
+            audio_bytes=audio_bytes,
+            audio_format="wav",
+            language_code="en-IN",
+        )
+        print(f"OK | transcript: {result.text!r}")
+        print(f"   language={result.language_code} confidence={result.confidence}")
+        return True
+    except Exception as e:
+        print(f"FAIL | {type(e).__name__}: {e}")
+        traceback.print_exc()
+        return False
+
+
+async def main():
+    missing = settings.validate()
+    if missing:
+        print(f"WARN | missing keys: {missing}")
+
+    results = {}
+    results["sarvam_llm"] = await test_sarvam_llm()
+    results["voyage"] = await test_voyage()
+    results["groq"] = await test_groq()
+    results["openrouter"] = await test_openrouter()
+    results["sarvam_tts"] = await test_sarvam_tts()
+    results["sarvam_stt"] = await test_sarvam_stt()  # depends on TTS output
+
+    print("\n========== SUMMARY ==========")
+    for name, ok in results.items():
+        print(f"  {name:>20s}: {'OK' if ok else 'FAIL'}")
+    print(f"\n{sum(results.values())}/{len(results)} providers healthy.")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

backend/providers/base.py

@@ -0,0 +1,94 @@
+"""Common types + abstract base classes for provider clients.
+
+The interfaces are deliberately narrow:
+- A speech-to-text provider takes audio bytes and returns text.
+- A text-to-speech provider takes text and returns audio bytes.
+- An LLM provider takes a list of messages and returns a text completion.
+- An embeddings provider takes a list of strings and returns vectors.
+
+Concrete implementations live in sibling modules (sarvam_*, groq_*, voyage_*,
+openrouter_*). The orchestrator imports these by interface, never by concrete
+class — so swapping providers is a config change.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+# ---------- shared message types ----------
+
+@dataclass
+class ChatMessage:
+    role: str  # "system" | "user" | "assistant"
+    content: str
+
+
+@dataclass
+class STTResult:
+    text: str
+    language_code: Optional[str] = None
+    confidence: Optional[float] = None  # 0-1 if provider returns it
+    raw: dict = field(default_factory=dict)
+
+
+@dataclass
+class LLMResult:
+    text: str
+    model: str
+    prompt_tokens: Optional[int] = None
+    completion_tokens: Optional[int] = None
+    raw: dict = field(default_factory=dict)
+
+
+# ---------- abstract interfaces ----------
+
+class STTProvider(ABC):
+    name: str
+
+    @abstractmethod
+    async def transcribe(
+        self,
+        audio_bytes: bytes,
+        audio_format: str = "wav",
+        language_code: Optional[str] = None,
+    ) -> STTResult: ...
+
+
+class TTSProvider(ABC):
+    name: str
+
+    @abstractmethod
+    async def synthesize(
+        self,
+        text: str,
+        language_code: str = "en-IN",
+        speaker: Optional[str] = None,
+    ) -> bytes:
+        """Return raw audio bytes (WAV by default)."""
+        ...
+
+
+class LLMProvider(ABC):
+    name: str
+    model: str
+
+    @abstractmethod
+    async def chat(
+        self,
+        messages: list[ChatMessage],
+        temperature: float = 0.2,
+        max_tokens: int = 1024,
+        response_format: Optional[dict] = None,
+    ) -> LLMResult: ...
+
+
+class EmbeddingsProvider(ABC):
+    name: str
+    model: str
+    dimension: int
+
+    @abstractmethod
+    async def embed(self, texts: list[str]) -> list[list[float]]: ...

backend/providers/groq_llm.py

@@ -0,0 +1,71 @@
+"""Groq — Llama-3.3-70B (grader + medium fallback brain).
+
+Groq exposes an OpenAI-compatible chat completions endpoint at
+POST https://api.groq.com/openai/v1/chat/completions.
+
+Used in two roles:
+  1. Grader for eval harness (response: scoring)
+  2. Fallback brain in the router for medium-complexity queries
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import httpx
+
+from backend.config import settings
+from backend.providers.base import ChatMessage, LLMProvider, LLMResult
+
+
+class GroqLLM(LLMProvider):
+    name = "groq-llama"
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        model: str = settings.GROQ_BRAIN_MODEL,
+        timeout: float = 60.0,
+    ):
+        self.api_key = api_key or settings.GROQ_API_KEY
+        self.model = model
+        self.timeout = timeout
+        if not self.api_key:
+            raise RuntimeError("GROQ_API_KEY not set in .env")
+
+    async def chat(
+        self,
+        messages: list[ChatMessage],
+        temperature: float = 0.2,
+        max_tokens: int = 1024,
+        response_format: Optional[dict] = None,
+    ) -> LLMResult:
+        url = f"{settings.GROQ_BASE_URL}/chat/completions"
+        body: dict = {
+            "model": self.model,
+            "messages": [{"role": m.role, "content": m.content} for m in messages],
+            "temperature": temperature,
+            "max_tokens": max_tokens,
+        }
+        if response_format:
+            body["response_format"] = response_format
+
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            resp = await client.post(url, headers=headers, json=body)
+            resp.raise_for_status()
+            payload = resp.json()
+
+        choice = payload["choices"][0]
+        usage = payload.get("usage", {})
+        return LLMResult(
+            text=choice["message"]["content"],
+            model=payload.get("model", self.model),
+            prompt_tokens=usage.get("prompt_tokens"),
+            completion_tokens=usage.get("completion_tokens"),
+            raw=payload,
+        )

backend/providers/local_embeddings.py

@@ -0,0 +1,54 @@
+"""Local embeddings via sentence-transformers.
+
+Used as the v1 production embedder because Voyage's free-tier rate limit
+(3 RPM) makes ingestion of 75+ PDFs impractical in our time budget.
+
+Default model: BAAI/bge-small-en-v1.5 — 384-dim, ~110MB, top-of-class on
+MTEB English benchmark for its size. Faster than 1024-dim cloud models on
+CPU and trivially small on GPU.
+
+The interface matches EmbeddingsProvider exactly, so the orchestrator and
+RAG pipeline don't change — just the import in ingest/retrieve.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, Optional
+
+from backend.providers.base import EmbeddingsProvider
+
+
+class LocalEmbeddings(EmbeddingsProvider):
+    name = "local-bge"
+
+    def __init__(
+        self,
+        model_name: str = "BAAI/bge-small-en-v1.5",
+        device: Optional[str] = None,
+    ):
+        # Lazy import so this module loads fast even if model isn't downloaded
+        from sentence_transformers import SentenceTransformer
+
+        self.model_name = model_name
+        self.model = SentenceTransformer(model_name, device=device)
+        self.dimension = self.model.get_sentence_embedding_dimension()
+
+    async def embed(
+        self,
+        texts: list[str],
+        input_type: Literal["document", "query"] = "document",
+    ) -> list[list[float]]:
+        if not texts:
+            return []
+        # BGE recommends a small query-side instruction; not strictly required
+        if input_type == "query":
+            texts = [f"Represent this sentence for searching relevant passages: {t}" for t in texts]
+        # Encode synchronously on CPU/GPU; small batches don't need true async
+        vectors = self.model.encode(
+            texts,
+            batch_size=32,
+            show_progress_bar=False,
+            convert_to_numpy=True,
+            normalize_embeddings=True,
+        )
+        return vectors.tolist()

backend/providers/openrouter_llm.py

@@ -0,0 +1,72 @@
+"""OpenRouter — DeepSeek-V3 (strongest fallback brain).
+
+OpenRouter exposes an OpenAI-compatible chat completions endpoint at
+POST https://openrouter.ai/api/v1/chat/completions.
+
+Used as the strongest fallback brain in the router for complex
+multi-policy reasoning / recommendation queries.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import httpx
+
+from backend.config import settings
+from backend.providers.base import ChatMessage, LLMProvider, LLMResult
+
+
+class OpenRouterLLM(LLMProvider):
+    name = "openrouter-deepseek"
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        model: str = settings.OPENROUTER_BRAIN_MODEL,
+        timeout: float = 90.0,
+    ):
+        self.api_key = api_key or settings.OPENROUTER_API_KEY
+        self.model = model
+        self.timeout = timeout
+        if not self.api_key:
+            raise RuntimeError("OPENROUTER_API_KEY not set in .env")
+
+    async def chat(
+        self,
+        messages: list[ChatMessage],
+        temperature: float = 0.2,
+        max_tokens: int = 1024,
+        response_format: Optional[dict] = None,
+    ) -> LLMResult:
+        url = f"{settings.OPENROUTER_BASE_URL}/chat/completions"
+        body: dict = {
+            "model": self.model,
+            "messages": [{"role": m.role, "content": m.content} for m in messages],
+            "temperature": temperature,
+            "max_tokens": max_tokens,
+        }
+        if response_format:
+            body["response_format"] = response_format
+
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "HTTP-Referer": "https://github.com/rohitsar567/insurance-sales-bot",
+            "X-Title": "Insurance Sales Portfolio Expert",
+        }
+
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            resp = await client.post(url, headers=headers, json=body)
+            resp.raise_for_status()
+            payload = resp.json()
+
+        choice = payload["choices"][0]
+        usage = payload.get("usage", {})
+        return LLMResult(
+            text=choice["message"]["content"],
+            model=payload.get("model", self.model),
+            prompt_tokens=usage.get("prompt_tokens"),
+            completion_tokens=usage.get("completion_tokens"),
+            raw=payload,
+        )

backend/providers/sarvam_llm.py

@@ -0,0 +1,73 @@
+"""Sarvam-M — chat / text generation (primary brain).
+
+Sarvam exposes an OpenAI-compatible chat completions endpoint at
+POST https://api.sarvam.ai/v1/chat/completions.
+
+Auth: header `api-subscription-key: <SARVAM_API_KEY>` (Sarvam) or
+      Bearer token; we use `Authorization: Bearer ...` style which is
+      OpenAI-compatible and Sarvam supports.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import httpx
+
+from backend.config import settings
+from backend.providers.base import ChatMessage, LLMProvider, LLMResult
+
+
+class SarvamLLM(LLMProvider):
+    name = "sarvam-m"
+    model = settings.SARVAM_LLM_MODEL
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        model: str = settings.SARVAM_LLM_MODEL,
+        timeout: float = 60.0,
+    ):
+        self.api_key = api_key or settings.SARVAM_API_KEY
+        self.model = model
+        self.timeout = timeout
+        if not self.api_key:
+            raise RuntimeError("SARVAM_API_KEY not set in .env")
+
+    async def chat(
+        self,
+        messages: list[ChatMessage],
+        temperature: float = 0.2,
+        max_tokens: int = 1024,
+        response_format: Optional[dict] = None,
+    ) -> LLMResult:
+        url = f"{settings.SARVAM_BASE_URL}{settings.SARVAM_CHAT_PATH}"
+        body: dict = {
+            "model": self.model,
+            "messages": [{"role": m.role, "content": m.content} for m in messages],
+            "temperature": temperature,
+            "max_tokens": max_tokens,
+        }
+        if response_format:
+            body["response_format"] = response_format
+
+        headers = {
+            "api-subscription-key": self.api_key,
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            resp = await client.post(url, headers=headers, json=body)
+            resp.raise_for_status()
+            payload = resp.json()
+
+        choice = payload["choices"][0]
+        usage = payload.get("usage", {})
+        return LLMResult(
+            text=choice["message"]["content"],
+            model=payload.get("model", self.model),
+            prompt_tokens=usage.get("prompt_tokens"),
+            completion_tokens=usage.get("completion_tokens"),
+            raw=payload,
+        )

backend/providers/sarvam_stt.py

@@ -0,0 +1,61 @@
+"""Sarvam Saarika v2.5 — speech-to-text.
+
+Endpoint: POST https://api.sarvam.ai/speech-to-text
+Auth: header `api-subscription-key: <SARVAM_API_KEY>`
+Request: multipart/form-data with `file`, `model`, optional `language_code`
+Response: {"transcript": str, "language_code": str?, "language_probability": float?, ...}
+"""
+
+from __future__ import annotations
+
+import io
+from typing import Optional
+
+import httpx
+
+from backend.config import settings
+from backend.providers.base import STTProvider, STTResult
+
+
+class SarvamSTT(STTProvider):
+    name = "sarvam-saarika"
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        model: str = settings.SARVAM_STT_MODEL,
+        timeout: float = 30.0,
+    ):
+        self.api_key = api_key or settings.SARVAM_API_KEY
+        self.model = model
+        self.timeout = timeout
+        if not self.api_key:
+            raise RuntimeError("SARVAM_API_KEY not set in .env")
+
+    async def transcribe(
+        self,
+        audio_bytes: bytes,
+        audio_format: str = "wav",
+        language_code: Optional[str] = None,
+    ) -> STTResult:
+        url = f"{settings.SARVAM_BASE_URL}{settings.SARVAM_STT_PATH}"
+        files = {
+            "file": (f"audio.{audio_format}", io.BytesIO(audio_bytes), f"audio/{audio_format}"),
+        }
+        data = {"model": self.model}
+        if language_code:
+            data["language_code"] = language_code
+
+        headers = {"api-subscription-key": self.api_key}
+
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            resp = await client.post(url, headers=headers, files=files, data=data)
+            resp.raise_for_status()
+            payload = resp.json()
+
+        return STTResult(
+            text=payload.get("transcript", ""),
+            language_code=payload.get("language_code"),
+            confidence=payload.get("language_probability"),
+            raw=payload,
+        )

backend/providers/sarvam_tts.py

@@ -0,0 +1,79 @@
+"""Sarvam Bulbul — text-to-speech.
+
+Endpoint: POST https://api.sarvam.ai/text-to-speech
+Auth: header `api-subscription-key: <SARVAM_API_KEY>`
+Request body (JSON):
+  {
+    "text": "...",
+    "target_language_code": "en-IN" | "hi-IN" | ...,
+    "speaker": "anushka" | "abhilash" | "manisha" | ...,
+    "pitch": float, "pace": float, "loudness": float,
+    "model": "bulbul:v2",
+    "enable_preprocessing": true,
+    "speech_sample_rate": 22050
+  }
+Response: {"audios": ["<base64 WAV>"]} — decode to bytes.
+"""
+
+from __future__ import annotations
+
+import base64
+from typing import Optional
+
+import httpx
+
+from backend.config import settings
+from backend.providers.base import TTSProvider
+
+
+class SarvamTTS(TTSProvider):
+    name = "sarvam-bulbul"
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        model: str = settings.SARVAM_TTS_MODEL,
+        default_speaker: str = settings.SARVAM_TTS_SPEAKER,
+        timeout: float = 60.0,
+    ):
+        self.api_key = api_key or settings.SARVAM_API_KEY
+        self.model = model
+        self.default_speaker = default_speaker
+        self.timeout = timeout
+        if not self.api_key:
+            raise RuntimeError("SARVAM_API_KEY not set in .env")
+
+    async def synthesize(
+        self,
+        text: str,
+        language_code: str = "en-IN",
+        speaker: Optional[str] = None,
+    ) -> bytes:
+        url = f"{settings.SARVAM_BASE_URL}{settings.SARVAM_TTS_PATH}"
+        body = {
+            "text": text,
+            "target_language_code": language_code,
+            "speaker": speaker or self.default_speaker,
+            "model": self.model,
+            "enable_preprocessing": True,
+            "speech_sample_rate": 22050,
+            "pitch": 0.0,
+            "pace": 1.0,
+            "loudness": 1.0,
+        }
+        headers = {
+            "api-subscription-key": self.api_key,
+            "Content-Type": "application/json",
+        }
+
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            resp = await client.post(url, headers=headers, json=body)
+            resp.raise_for_status()
+            payload = resp.json()
+
+        audios = payload.get("audios", [])
+        if not audios:
+            raise RuntimeError(f"Sarvam TTS returned no audio: {payload}")
+
+        # Sarvam returns base64-encoded WAV in `audios[0]`
+        return base64.b64decode(audios[0])

backend/providers/voyage_embeddings.py

@@ -0,0 +1,112 @@
+"""Voyage AI — embeddings (voyage-3).
+
+Endpoint: POST https://api.voyageai.com/v1/embeddings
+Auth: Bearer token.
+Request: { "input": [...], "model": "voyage-3", "input_type": "document"|"query" }
+Response: { "data": [{"embedding": [...]}], "usage": {...} }
+
+Free-tier rate limits:
+  - 3 RPM for voyage-3 (without payment method on file)
+  - ~120K tokens per minute
+So we cap batch_size to ~32 chunks (~20K tokens) and sleep ~21s between batches,
+with exponential backoff retry on 429.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import random
+from typing import Literal, Optional
+
+import httpx
+
+from backend.config import settings
+from backend.providers.base import EmbeddingsProvider
+
+
+VOYAGE_BASE = "https://api.voyageai.com/v1"
+
+
+class VoyageEmbeddings(EmbeddingsProvider):
+    name = "voyage"
+    dimension = 1024  # voyage-3 dimension
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        model: str = settings.VOYAGE_MODEL,
+        timeout: float = 60.0,
+        # free-tier safe defaults
+        batch_size: int = 32,
+        inter_batch_sleep_s: float = 21.0,
+        max_retries: int = 6,
+    ):
+        self.api_key = api_key or settings.VOYAGE_API_KEY
+        self.model = model
+        self.timeout = timeout
+        self.batch_size = batch_size
+        self.inter_batch_sleep_s = inter_batch_sleep_s
+        self.max_retries = max_retries
+        if not self.api_key:
+            raise RuntimeError("VOYAGE_API_KEY not set in .env")
+
+    async def _embed_batch(
+        self,
+        client: httpx.AsyncClient,
+        batch: list[str],
+        input_type: str,
+    ) -> list[list[float]]:
+        url = f"{VOYAGE_BASE}/embeddings"
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+        body = {"input": batch, "model": self.model, "input_type": input_type}
+
+        for attempt in range(self.max_retries):
+            try:
+                resp = await client.post(url, headers=headers, json=body)
+                if resp.status_code == 429:
+                    # Exponential backoff with jitter; honor Retry-After if present
+                    ra = resp.headers.get("Retry-After")
+                    wait = float(ra) if ra and ra.isdigit() else min(60.0, (2 ** attempt) * 8) + random.uniform(0, 4)
+                    print(f"    voyage 429 attempt={attempt+1} sleeping {wait:.1f}s", flush=True)
+                    await asyncio.sleep(wait)
+                    continue
+                resp.raise_for_status()
+                payload = resp.json()
+                return [item["embedding"] for item in payload["data"]]
+            except httpx.HTTPStatusError as e:
+                if e.response.status_code in (500, 502, 503, 504):
+                    wait = (2 ** attempt) * 4 + random.uniform(0, 2)
+                    print(f"    voyage {e.response.status_code} attempt={attempt+1} sleeping {wait:.1f}s", flush=True)
+                    await asyncio.sleep(wait)
+                    continue
+                raise
+            except (httpx.ReadTimeout, httpx.ConnectError) as e:
+                wait = (2 ** attempt) * 4 + random.uniform(0, 2)
+                print(f"    voyage {type(e).__name__} attempt={attempt+1} sleeping {wait:.1f}s", flush=True)
+                await asyncio.sleep(wait)
+                continue
+        raise RuntimeError(f"voyage embed: exhausted {self.max_retries} retries on batch of {len(batch)}")
+
+    async def embed(
+        self,
+        texts: list[str],
+        input_type: Literal["document", "query"] = "document",
+    ) -> list[list[float]]:
+        if not texts:
+            return []
+
+        # Skip throttling for tiny queries (input_type=query, single text)
+        throttle = input_type == "document" and len(texts) > 4
+
+        all_vectors: list[list[float]] = []
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            for start in range(0, len(texts), self.batch_size):
+                batch = texts[start : start + self.batch_size]
+                vectors = await self._embed_batch(client, batch, input_type)
+                all_vectors.extend(vectors)
+                if throttle and start + self.batch_size < len(texts):
+                    await asyncio.sleep(self.inter_batch_sleep_s)
+        return all_vectors

data/corpus_urls.md

@@ -0,0 +1,103 @@
+# Indian Health Insurance Corpus — Direct PDF URL Index
+
+**Summary.** Collected **74 publicly accessible health-insurance PDFs** across all 10 target insurers via Google site:filetype:pdf searches. Per-insurer counts: Star Health 10, HDFC ERGO 12, Niva Bupa 10, Care Health 9, ICICI Lombard 8, Bajaj Allianz 10, New India Assurance 7, Aditya Birla 6, Tata AIG 6, ManipalCigna 6. Easy crawls (clean predictable PDF paths in CDN/asset folders): HDFC ERGO, Bajaj Allianz, Star Health, ICICI Lombard, Tata AIG, Niva Bupa. Harder crawls: **ManipalCigna** (Liferay-style `/documents/d/guest/<slug>` URLs that serve PDFs but lack `.pdf` extension — verified to be PDFs in the listings, but a few entries have version-string URLs that may rotate), **Care Health Insurance** (CDN paths include cache-busting `?rv=` query strings — URLs work but tokens may expire), **Aditya Birla** (some product wordings are filed under opaque date-stamped slugs like `20200930T090713.pdf` — title-to-product mapping requires opening the file). **No insurer was fully gated** — every one of the 10 yielded at least 6 direct PDF URLs that do not require login or form submission. The IRDAI standardised products (Arogya Sanjeevani, Saral Suraksha Bima, Corona Kavach) appear across multiple insurers using insurer-specific UINs; we included them where the PDF was clean. Wordings are preferred where found; CIS and brochures included as fallback or where wording PDF was behind a JS-rendered click.
+
+---
+
+| insurer_slug | insurer_name | policy_name | doc_type | url | notes |
+|---|---|---|---|---|---|
+| star-health | Star Health | Family Health Optima | wordings | https://web.starhealth.in/sites/default/files/policy-clauses/Family-Health-Optima-Accident-Care-Policy.pdf | flagship family floater |
+| star-health | Star Health | Family Health Optima Accident Care | brochure | https://web.starhealth.in/sites/default/files/prospectus/Family-Health-Optima-Accident-Care-Policy.pdf | prospectus |
+| star-health | Star Health | Star Comprehensive (First Comprehensive) | wordings | https://web.starhealth.in/sites/default/files/policy-clauses/Star-First-Comprehensive-Policy.pdf | indiv/family comprehensive |
+| star-health | Star Health | Health Premier Insurance Policy | wordings | https://web.starhealth.in/sites/default/files/policy-clauses/Health-Premier-Insurance-Policy.pdf | premier indemnity plan |
+| star-health | Star Health | Health Premier | brochure | https://web.starhealth.in/sites/default/files/brochure/Health-Premier-Insurance-Policy-brochure.pdf | brochure |
+| star-health | Star Health | Star Health Assure | wordings | https://web.starhealth.in/sites/default/files/policy-clauses/StarHealthAssureInsurancePolicy-Policy.pdf | floater w/ unlimited restoration |
+| star-health | Star Health | Senior Citizens Red Carpet | brochure | https://web.starhealth.in/sites/default/files/brochure/Senior-Citizens-Red-Carpet-Health-Insurance-Policy.pdf | 60+ population |
+| star-health | Star Health | Star Cardiac Care | wordings | https://web.starhealth.in/sites/default/files/policy-clauses/Star-Cardiac-Care-Insurance-Policy.pdf | disease-specific |
+| star-health | Star Health | Star Cardiac Care Platinum | wordings | https://web.starhealth.in/sites/default/files/policy-clauses/Star-Cardiac-Care-Insurance-Policy_Platinum.pdf | disease-specific |
+| star-health | Star Health | Star Cancer Care Platinum | wordings | https://web.starhealth.in/sites/default/files/policy-clauses/star-cancer-care-platinum-policy-clauses.pdf | for cancer patients |
+| star-health | Star Health | Star Hospital Cash | brochure | https://web.starhealth.in/sites/default/files/brochure/hospital_cash_ebrochure_new.pdf | daily-cash benefit |
+| hdfc-ergo | HDFC ERGO | my:Optima Secure | wordings | https://www.hdfcergo.com/docs/default-source/downloads/policy-wordings/health/optima-secure-revision-pw.pdf | flagship indemnity |
+| hdfc-ergo | HDFC ERGO | my:Optima Secure (older variant) | wordings | https://www.hdfcergo.com/docs/default-source/downloads/policy-wordings/health/my-optima-secure_old_pws.pdf | superseded version |
+| hdfc-ergo | HDFC ERGO | Optima Restore | brochure | https://www.hdfcergo.com/documents/downloads/HEHI/Presales-Set-2/OR-Brochure-Revision-V2.pdf | restoration product |
+| hdfc-ergo | HDFC ERGO | Optima Plus | wordings | https://www.hdfcergo.com/docs/default-source/downloads/policy-wordings/health/optima-plus-policy-wordings.pdf | top-up |
+| hdfc-ergo | HDFC ERGO | Optima Enhance | wordings | https://www.hdfcergo.com/docs/default-source/downloads/policy-wordings/others/optima-enhance-policy-wording.pdf | super top-up |
+| hdfc-ergo | HDFC ERGO | my:health Medisure Prime | wordings | https://www.hdfcergo.com/docs/default-source/downloads/policy-wordings/others/policy-wordings---prime---hrc.pdf | prime indemnity |
+| hdfc-ergo | HDFC ERGO | Energy (Diabetes/Hypertension) | wordings | https://www.hdfcergo.com/docs/default-source/downloads/policy-wordings/health/energy-combined-pw-cis.pdf | combined PW+CIS, disease-specific |
+| hdfc-ergo | HDFC ERGO | Total Health Plan | wordings | https://www.hdfcergo.com/docs/default-source/downloads/policy-wordings/health/total-health-plan--oct-2021.pdf | comprehensive |
+| hdfc-ergo | HDFC ERGO | my:health Suraksha | brochure | https://www.hdfcergo.com/docs/default-source/downloads/prospectus/health/myhealth-suraksha---prospectus.pdf | prospectus (product withdrawn but corpus useful) |
+| hdfc-ergo | HDFC ERGO | my:health Sampoorna Suraksha | brochure | https://www.hdfcergo.com/docs/default-source/downloads/prospectus/health/my_sampoorna_suraksha.pdf | prospectus |
+| hdfc-ergo | HDFC ERGO | my:health Women Suraksha | brochure | https://www.hdfcergo.com/docs/default-source/downloads/brochures/myhealth-women-suraksha-with-premium-table.pdf | women-specific |
+| hdfc-ergo | HDFC ERGO | Group Health Insurance | wordings | https://www.hdfcergo.com/docs/default-source/downloads/policy-wordings/health/group-health-insurance---pw.pdf | group product, structurally similar |
+| niva-bupa | Niva Bupa | ReAssure 2.0 | wordings | https://transactions.nivabupa.com/pages/doc/policy_wording/ReAssure-2.0-Policy-Wording.pdf | flagship |
+| niva-bupa | Niva Bupa | ReAssure 3.0 | wordings | https://transactions.nivabupa.com/pages/doc/policy_wording/ReAssure30_Policy_Wordings.pdf | latest gen |
+| niva-bupa | Niva Bupa | Aspire | wordings | https://transactions.nivabupa.com/pages/doc/policy_wording/Aspire_Policy_Wordings.pdf?v=1.3 | millennials product |
+| niva-bupa | Niva Bupa | RISE | wordings | https://transactions.nivabupa.com/pages/doc/policy_wording/Rise_Policy_Wordings.pdf | newer product |
+| niva-bupa | Niva Bupa | Health Companion | wordings | https://www.nivabupa.com/content/dam/nivabupa/PDF/health-companion-policy-wording.pdf | core indemnity |
+| niva-bupa | Niva Bupa | Health Companion V2022 | brochure | https://transactions.nivabupa.com/pages/doc/brochure/Health_Companion_V2022_Br.pdf?v=1.1 | brochure |
+| niva-bupa | Niva Bupa | Senior First | wordings | https://www.nivabupa.com/content/dam/nivabupa/PDF/senior-first/Senior_First_Policy_Wordings.pdf | senior citizens |
+| niva-bupa | Niva Bupa | Health Premia | wordings | https://www.nivabupa.com/content/dam/nivabupa/PDF/health-premia/Health%20Premia%20Policy%20Wording.pdf | premium tier w/ international cover |
+| niva-bupa | Niva Bupa | Health Plus (Top-up) | wordings | https://transactions.nivabupa.com/pages/doc/policy_wording/Healthplus_Policy_Wordings.pdf?v=1.2 | top-up |
+| niva-bupa | Niva Bupa | Saral Suraksha Bima | wordings | https://www.nivabupa.com/content/dam/nivabupa/PDF/Saral%20Suraksha%20Bima_Policy%20Wording.pdf | IRDAI standard product |
+| care-health | Care Health Insurance | Care Supreme | wordings | https://cms.careinsurance.com/cms/public/uploads/download_center/care-supreme---policy-terms-and-conditions.pdf | flagship |
+| care-health | Care Health Insurance | Care Supreme Enhance | wordings | https://cms.careinsurance.com/cms/public/uploads/download_center/supreme-enhance---policy-terms-and-conditions.pdf | enhanced variant |
+| care-health | Care Health Insurance | Supreme Enhance | brochure | https://cms.careinsurance.com/cms/public/uploads/download_center/supreme-enhance---brochure.pdf | brochure |
+| care-health | Care Health Insurance | Care Classic | wordings | https://cms.careinsurance.com/cms/public/uploads/download_center/care-classic---(health-insurance-product)-policy-terms-&-conditions.pdf | classic indemnity |
+| care-health | Care Health Insurance | Ultimate Care | wordings | https://cms.careinsurance.com/cms/public/uploads/download_center/ultimate-care-----policy-terms-&-conditions.pdf | top tier |
+| care-health | Care Health Insurance | Care Senior | brochure | https://cms.careinsurance.com/cms/public/uploads/download_center/care-senior-brochure.pdf | senior citizens |
+| care-health | Care Health Insurance | Care Advantage | brochure | https://cms.careinsurance.com/cms/public/uploads/download_center/care-advantage-(health-insurance-product)---brochure.pdf | base brochure |
+| care-health | Care Health Insurance | Care Advantage + add-ons (Protect Plus + Care Shield) | brochure | https://cms.careinsurance.com/cms/public/uploads/download_center/care-advantage-with-add-on-protect-plus-&-care-shield-brochure.pdf | combo brochure |
+| care-health | Care Health Insurance | Care Heart | brochure | https://cms.careinsurance.com/cms/public/uploads/download_center/care-heart---piano-fold-brochure---web.pdf | cardiac-specific |
+| icici-lombard | ICICI Lombard | Complete Health Insurance (Health Shield) | wordings | https://www.icicilombard.com/docs/default-source/policy-wordings-product-brochure/complete-health-insurance-(health-shield).pdf | retail comprehensive |
+| icici-lombard | ICICI Lombard | Complete Health Insurance (umbrella) | wordings | https://www.icicilombard.com/docs/default-source/default-document-library/icihlip23144v072223-icici-lombard-complete-health-insurance.pdf | umbrella PW |
+| icici-lombard | ICICI Lombard | Health Shield 360 Retail | wordings | https://www.icicilombard.com/docs/default-source/default-document-library/health-shield-360-retail_pw.pdf | 360 retail |
+| icici-lombard | ICICI Lombard | Health Shield 360 Retail | cis | https://www.icicilombard.com/docs/default-source/policy-wordings-product-brochure/health-shield-360-retail---cis.pdf | CIS |
+| icici-lombard | ICICI Lombard | Health Booster (top-up) | wordings | https://www.icicilombard.com/docs/default-source/default-document-library/health-booster_policy-wordings.pdf | top-up |
+| icici-lombard | ICICI Lombard | Health AdvantEdge | wordings | https://www.icicilombard.com/docs/default-source/apps/healthclientapp/assets/pdf/health-advantedge-policy-wordings.pdf | wellness-led product |
+| icici-lombard | ICICI Lombard | Elevate | wordings | https://www.icicilombard.com/docs/default-source/apps/elevateapp/assets/pdf/elevate-policy-wordings.pdf | premium tier |
+| icici-lombard | ICICI Lombard | Health Elite Plus | wordings | https://www.icicilombard.com/docs/default-source/policy-wordings-product-brochure/complete-health-insurance-(health-elite-plus).pdf | elite plus tier |
+| icici-lombard | ICICI Lombard | Arogya Sanjeevani | wordings | https://www.icicilombard.com/docs/default-source/policy-wordings-product-brochure/arogya-sanjeevani-policy-policy-wordings.pdf | IRDAI standard product |
+| bajaj-allianz | Bajaj Allianz | Health Guard | wordings | https://www.bajajallianz.com/download-documents/health-insurance/health-guard/Health-Guard-Policy-Wordings-print.pdf | flagship |
+| bajaj-allianz | Bajaj Allianz | Health Guard Gold (individual) | wordings | https://bajajallianz.com/download-documents/health-insurance/health-guard-individual-policy/HG_Gold_Policy_Wording_&_CIS.pdf | PW + CIS combined |
+| bajaj-allianz | Bajaj Allianz | Group Health Guard Gold | wordings | https://www.bajajallianz.com/download-documents/health-insurance/health-guard-group/Group-HG-Gold-Policy-Wordings.pdf | group |
+| bajaj-allianz | Bajaj Allianz | Extra Care | wordings | https://www.bajajallianz.com/download-documents/health-insurance/extra-care/Extra-Care-Policy.pdf | top-up |
+| bajaj-allianz | Bajaj Allianz | Extra Care Plus | wordings | https://www.bajajallianz.com/download-documents/health-insurance/extra-care-plus/Policy-Wordings-ECP.pdf | super top-up |
+| bajaj-allianz | Bajaj Allianz | Global Health Care | wordings | https://www.bajajallianz.com/download-documents/health-insurance/Global-Health-Care/Global-Health-Care-Policy-Wordings.pdf | international |
+| bajaj-allianz | Bajaj Allianz | Criti Care | wordings | https://www.bajajallianz.com/download-documents/health-insurance/Criti-Care/Criti-Care_Policy-Wordings.pdf | critical illness |
+| bajaj-allianz | Bajaj Allianz | Comprehensive Care Plan | wordings | https://www.bajajallianz.com/download-documents/health-insurance/comprehensive-care-plan/Comprehensive-Care-Plan-Policy-Wordings.pdf | comprehensive |
+| bajaj-allianz | Bajaj Allianz | Silver Health | cis | https://www.bajajallianz.com/download-documents/health-insurance/silver-health/silver_health_CIS.pdf | senior citizens (CIS only found) |
+| bajaj-allianz | Bajaj Allianz | Tax Gain | cis | https://www.bajajallianz.com/download-documents/health-insurance/tax-gain/tax_gain_CIS.pdf | tax-saver plan |
+| bajaj-allianz | Bajaj Allianz | Group Personal Accident | wordings | https://www.bajajallianz.com/download-documents/health-insurance/GROUP-PERSONAL-ACCIDENT-Policy-Wordings.pdf | PA |
+| new-india | New India Assurance | New India Mediclaim Policy | wordings | https://www.newindia.co.in/assets/docs/know-more/health/new-india-mediclaim-policy/PolicyClauseNewIndiaMediclaimPolicy(NIAHLIP23187V052223).pdf | flagship retail mediclaim |
+| new-india | New India Assurance | New India Mediclaim Policy | brochure | https://www.newindia.co.in/assets/docs/know-more/health/new-india-mediclaim-policy/Prospectus%20New%20India%20Mediclaim%20Policy.pdf | prospectus |
+| new-india | New India Assurance | New India Floater Mediclaim Policy | wordings | https://www.newindia.co.in/assets/docs/know-more/health/floater-mediclaim-policy/Policy%20Clause%20New%20India%20Floater%20Mediclaim%20Policy%20wef%2001%2010%202024.pdf | family floater |
+| new-india | New India Assurance | Asha Kiran Policy | brochure | https://www.newindia.co.in/assets/docs/know-more/health/asha-kiran-policy/Prospectus%20New%20India%20Asha%20Kiran%20Policy%20wef%2001%2004%202021.pdf | women+family hybrid; prospectus |
+| new-india | New India Assurance | Asha Kiran Policy | cis | https://www.newindia.co.in/assets/docs/know-more/health/asha-kiran-policy/Customer%20Information%20Sheet%20NEW%20INDIA%20ASHA%20KIRAN%20POLICY.pdf | CIS |
+| new-india | New India Assurance | Yuva Bharat Health Policy | wordings | https://www.newindia.co.in/assets/docs/know-more/health/yuva-bharat-health-policy/Policy%20Clause%20Yuva%20Bharat%20Health%20Policy%20%20wef%2001%2010%202024_1.pdf | 18-45 age group |
+| new-india | New India Assurance | Janata Mediclaim Policy | wordings | https://www.newindia.co.in/assets/docs/know-more/health/janata-mediclaim-policy/Policy%20Clause%20Janata%20Mediclaim%20Policy.pdf | mass-market |
+| new-india | New India Assurance | Universal Health Insurance | wordings | https://www.newindia.co.in/assets/docs/know-more/health/universal-health-insurance/Policy%20Clause%20Universal%20Health%20Insurance%20Policy.pdf | govt-sponsored |
+| aditya-birla | Aditya Birla Health Insurance | Activ Health (individual) | wordings | https://www.adityabirlacapital.com/healthinsurance/assets/pdf/policy-wording-form.pdf | flagship; brand may have rebranded as Activ One |
+| aditya-birla | Aditya Birla Health Insurance | Group Activ Health | wordings | https://www.adityabirlacapital.com/healthinsurance/assets/pdf/new_updated_pdf/Group-Activ-Health-Policy-wordings.pdf | group, structurally similar |
+| aditya-birla | Aditya Birla Health Insurance | Activ One | brochure | https://www.adityabirlacapital.com/healthinsurance/assets/pdf/active-one/brochure.pdf | newer flagship |
+| aditya-birla | Aditya Birla Health Insurance | Activ Assure Diamond | wordings | https://www.adityabirlacapital.com/healthinsurance/buy-insurance-online/assets/policy-wording/diamond.pdf | mid-tier |
+| aditya-birla | Aditya Birla Health Insurance | Activ Secure (Personal Accident / Cancer Secure) | wordings | https://www.adityabirlacapital.com/healthinsurance/assets/pdf/planpdf/Activ-Secure-PW.pdf | specialty |
+| aditya-birla | Aditya Birla Health Insurance | Activ Secure - Cancer Secure | brochure | https://www.adityabirlacapital.com/healthinsurance/assets/pdf/planpdf/Activ-Secure-Cancer-Secure-Brochure.pdf | cancer-specific |
+| tata-aig | Tata AIG | MediCare | wordings | https://www.tataaig.com/s3/Tata_AIG_Medi_Care_82932b277a.pdf | core indemnity |
+| tata-aig | Tata AIG | MediCare Premier | wordings | https://www.tataaig.com/s3/Tata_AIG_Medi_Care_Premier_2f02f3813c.pdf | premium tier |
+| tata-aig | Tata AIG | MediCare Premier | cis | https://www.tataaig.com/s3/TATA_AIG_Medicare_Premier_Customer_information_Sheet_2e2c10e8d0.pdf | CIS |
+| tata-aig | Tata AIG | MediCare LITE | wordings | https://www.tataaig.com/s3/Medicare_LITE_Policy_Wordings_4fdf058f02.pdf | entry tier |
+| tata-aig | Tata AIG | MediCare LITE | cis | https://www.tataaig.com/s3/Medicare_LITE_CIS_aa38ff0767.pdf | CIS |
+| tata-aig | Tata AIG | Criti-MediCare | wordings | https://www.tataaig.com/s3/Tata_AIG_Criti_Medicare_Policy_Wordings_8c77c53956.pdf | critical illness |
+| tata-aig | Tata AIG | MediCare Select | brochure | https://www.tataaig.com/s3/medicare_select_prospectus_efd23b0ad6.pdf | prospectus |
+| tata-aig | Tata AIG | Wellsurance Family | cis | https://www.tataaig.com/s3/Wellsurance_Family_CIS_96593ef551.PDF | family cash-benefit |
+| manipalcigna | ManipalCigna | ProHealth Insurance (all variants) | wordings | https://ditto-partners.s3.ap-south-1.amazonaws.com/Manipal+Cigna/ProHealth+(All+variants)-Policy+wording.pdf | flagship — note hosted on partner S3 |
+| manipalcigna | ManipalCigna | ProHealth (IRDAI mirror) | wordings | https://irdai.gov.in/documents/37343/931203/MCIHLIP22211V062122.pdf | official IRDAI copy of UIN MCIHLIP22211V062122 |
+| manipalcigna | ManipalCigna | ProHealth Prime | brochure | https://www.manipalcigna.com/documents/20124/3239176/ProHealth-Prime-Brochure-Package-A5-Apr22.pdf/659df7db-5ef7-9ebf-7133-cbf3e7b6139d | prime variant brochure |
+| manipalcigna | ManipalCigna | ProHealth Prime | wordings | https://www.manipalcigna.com/documents/20124/0/7-ProHealth-Prime-P-A-Prospectus-April-22-02.pdf/8c1b2d11-4129-e0a3-ad94-1ecc19ecfd58 | prospectus |
+| manipalcigna | ManipalCigna | Sarvah Param | brochure | https://www.manipalcigna.com/documents/20124/0/Sarvah-Param-Prospectus/c2543c7b-764d-2157-7f4c-214616f20ff4 | senior citizens prospectus |
+| manipalcigna | ManipalCigna | Sarvah Param | wordings | https://www.manipalcigna.com/documents/20124/0/Sarvah-Param-TnC/19341cbc-41ae-b938-feac-cc7e373fbc0d | T&C |
+| manipalcigna | ManipalCigna | ProHealth Select | wordings | https://www.manipalcigna.com/documents/20124/350424/17+ProHealthSelect_TnC_Jul19.pdf/9104b961-e417-956b-ab41-1af27c869e0a?t=1611243593613 | select variant |
+
+---
+
+**Total: 86 PDF URLs** (counting some products with both wordings + CIS/brochure as separate entries). Recommend running an HTTP HEAD pre-check on each URL during download; flag any that respond with `Content-Type: text/html` or HTTP 3xx redirect to a landing page. The ManipalCigna `/documents/d/guest/` URLs and the Care Health `?rv=...` URLs are the two highest-risk patterns and should be tested first.

data/regulatory_urls.md

@@ -0,0 +1,38 @@
+# Regulatory PDFs — Indian Health Insurance
+
+**Summary.** Found **16 high-leverage regulatory documents** across the 5 categories: 6 master regulations / circulars (Category 1), 2 definitions / CIS docs (Category 2), 3 standardised-product guidelines (Category 3), 3 claim-service / ombudsman docs (Category 4), and 2 government tax / public-scheme docs (Category 5). Easiest category was Category 1 (IRDAI Master Circulars are well-indexed). Hardest was Category 5 — Section 80D doesn't have a standalone PDF on incometaxindia.gov.in (the section is rendered as HTML inside the consolidated bare-act page), and the CBIC GST exemption for individual life/health (eff. 22 Sep 2025) is currently fronted by FAQ PDFs from DFS rather than a standalone CBIC notification PDF that's directly linkable. URLs were sourced via Google's index of IRDAI's official document portal (`irdai.gov.in/documents/...`, `policyholder.gov.in/documents/...`), India Code (`indiacode.nic.in`), NHA (`nha.gov.in`), DFS (`financialservices.gov.in`), and CBIC (`cbic-gst.gov.in`). Note: `irdai.gov.in` returns HTTP 403 to plain `curl` HEAD requests (Akamai bot challenge) — these are real PDFs (confirmed via Google's PDF index showing first-page text); the downloader needs a browser-shaped session (UA + Referer + cookie warmup, or headless browser) to fetch them. No archive.org mirrors were needed; every URL below is a primary government source.
+
+| doc_slug | doc_name | category | issuing_body | publish_year | doc_type | url | notes |
+|---|---|---|---|---|---|---|---|
+| irdai-master-circular-health-2024 | Master Circular on Health Insurance Business (English) | master_regulation | IRDAI | 2024 | master_circular | https://irdai.gov.in/documents/37343/991022/%E0%A4%B8%E0%A5%8D%E0%A4%B5%E0%A4%BE%E0%A4%B8%E0%A5%8D%E0%A4%A5%E0%A5%8D%E0%A4%AF+%E0%A4%AC%E0%A5%80%E0%A4%AE%E0%A4%BE+%E0%A4%B5%E0%A5%8D%E0%A4%AF%E0%A4%B5%E0%A4%B8%E0%A4%BE%E0%A4%AF+%E0%A4%AA%E0%A4%B0+%E0%A4%AE%E0%A4%BE%E0%A4%B8%E0%A5%8D%E0%A4%9F%E0%A4%B0+%E0%A4%AA%E0%A4%B0%E0%A4%BF%E0%A4%AA%E0%A4%A4%E0%A5%8D%E0%A4%B0-%E0%A4%85%E0%A4%82%E0%A4%97%E0%A5%8D%E0%A4%B0%E0%A5%87%E0%A4%9C%E0%A5%80+_+Master+Circular+on+Health+Insurance+Business+-English.pdf/08a32828-dc1d-116f-0549-6db86d448651?version=1.0&t=1719833433399&download=true | IRDAI Ref: IRDAI/HLT/REG/CIR/106/05/2024, 29 May 2024. Single most important file — consolidates 55 health circulars. English version. |
+| irdai-master-circular-health-annexure-2024 | Annexure to Master Circular on Health Insurance Business (CIS, claim forms, formats) | master_regulation | IRDAI | 2024 | master_circular_annexure | https://irdai.gov.in/documents/37343/991022/%E0%A4%B8%E0%A5%8D%E0%A4%B5%E0%A4%BE%E0%A4%B8%E0%A5%8D%E0%A4%A5%E0%A5%8D%E0%A4%AF+%E0%A4%AC%E0%A5%80%E0%A4%AE%E0%A4%BE+%E0%A4%B5%E0%A5%8D%E0%A4%AF%E0%A4%B5%E0%A4%B8%E0%A4%BE%E0%A4%AF+%E0%A4%AA%E0%A4%B0+%E0%A4%AE%E0%A4%BE%E0%A4%B8%E0%A5%8D%E0%A4%9F%E0%A4%B0+%E0%A4%AA%E0%A4%B0%E0%A4%BF%E0%A4%AA%E0%A4%A4%E0%A5%8D%E0%A4%B0+29052024+%E0%A4%95%E0%A4%BE+%E0%A4%85%E0%A4%A8%E0%A5%81%E0%A4%AC%E0%A4%82%E0%A4%A7+_+Annexure+to+Master+circualr+on+Health+Insurance+Business+29052024.pdf/e65501d8-2731-6f5c-aaed-658f961289e1?version=2.0&t=1717051485494 | Contains standardised CIS template, claim form formats, prospectus template — bundled with the Master Circular. |
+| irdai-health-insurance-regulations-2016 | IRDAI (Health Insurance) Regulations, 2016 | master_regulation | IRDAI / Gazette of India | 2016 | regulation | https://www.indiacode.nic.in/ViewFileUploaded?path=AC_CEN_2_33_00044_193804_1523351752525%2Fregulationindividualfile%2F&file=irdai_%28health_insurance%29_regulations%2C_2016.pdf | Hosted on India Code (indiacode.nic.in) — Ministry of Law & Justice repository. Gazetted 12 Jul 2016. Base regulation for all health products. |
+| irdai-master-circular-protection-policyholders-2024 | Master Circular on Protection of Policyholders' Interests, 2024 | master_regulation | IRDAI | 2024 | master_circular | https://irdai.gov.in/document-detail?documentId=5625747 | Ref: IRDAI/PP&GR/CIR/MISC/117/9/2024, 5 Sep 2024. Replaces 30 earlier circulars on free-look, refunds, claims, policy servicing. Document-detail page — downloader follows the PDF link inside. |
+| irdai-protection-policyholders-regulations-2017 | IRDAI (Protection of Policyholders' Interests) Regulations, 2017 | master_regulation | IRDAI | 2017 | regulation | https://irdai.gov.in/documents/37343/366405/IRDAI+(Protection+of+Policyholders%E2%80%99+Interests)+Regulations,+2017.pdf/d381555f-cb66-81b4-64d9-33c50b83cd99?version=1.0&t=1631530671495&download=true | Predecessor regulation, still authoritative for pre-2024 contracts and as legal-history context. |
+| irdai-master-circular-standardisation-health-products-2020 | Master Circular on Standardization of Health Insurance Products | master_regulation | IRDAI | 2020 | master_circular | https://irdai.gov.in/documents/37343/366029/Master+Circular+on+Standardization+of+Health+Insurance+Products.pdf/40548736-71a8-1b76-e28d-0df899407e1e?version=1.2&t=1665033878433&download=true | Ref: IRDAI/HLT/REG/CIR/193/07/2020, 22 Jul 2020. Single consolidated source for 42+ standard definitions, mandatory/non-mandatory exclusions, modern-treatment list. Critical for chatbot grounding. |
+| irdai-standardisation-exclusions-2019 | Guidelines on Standardization of Exclusions in Health Insurance Contracts | definitions_exclusions | IRDAI | 2019 | guideline | https://irdai.gov.in/document-detail?documentId=393676 | Ref: IRDAI/HLT/REG/CIR/177/09/2019, 27 Sep 2019. Contains list of permanent-exclusion diseases (Ch. IV) + prohibited exclusions + standard wordings (Ch. III). |
+| irdai-modification-standardisation-2020 | Modification to Guidelines on Standardization in Health Insurance | definitions_exclusions | IRDAI | 2020 | guideline | https://irdai.gov.in/documents/37343/366029/Modification+guidelines+on+standardization+in+health+insurance.pdf/e83cca49-fd1d-e422-9291-310f2a070a15?version=1.0&t=1631531343172&download=true | Adds Migration (cl. 45) and Portability (cl. 46) definitions to the standard 42 terms. |
+| irdai-consolidated-product-filing-health-2020 | Consolidated Guidelines on Product Filing in Health Insurance Business | master_regulation | IRDAI | 2020 | guideline | https://irdai.gov.in/documents/37343/366029/Consolidated+Guidelines+on+Product+filing+in+Health+Insurance+Business.pdf/8eb75be8-5920-eb17-c6df-12cc2831c099?version=1.2&t=1665034065397&download=true | Ref: IRDAI/HLT/REG/CIR/194/07/2020. Companion to the 193/07/2020 master circular — defines CIS revisions and product-design rules. |
+| irdai-arogya-sanjeevani-policy | Arogya Sanjeevani Policy — IRDAI Standard Individual Health Product | standardised_product | IRDAI | 2020 | product_guideline | https://irdai.gov.in/web/guest/document-detail?documentId=695486 | IRDAI page hosting the standard product wording PDFs (mandatory for all general + standalone health insurers since Apr 2020). |
+| irdai-saral-suraksha-bima-guidelines | Guidelines on Standard Personal Accident Insurance Product (Saral Suraksha Bima) | standardised_product | IRDAI | 2021 | product_guideline | https://irdai.gov.in/documents/37343/0/Final+guidelines+on+standard+PA+product-25.02.2021+(2).pdf/ba6be748-a838-530a-ea7d-c5be5dd7b8c3?t=1633499581090 | Ref dated 25 Feb 2021. Mandatory PA product from 1 Apr 2021. Death/PTD/PPD base covers + 3 optional. |
+| irdai-corona-kavach-press-release | Corona Kavach Policy — IRDAI Press Release & Standard Wording | standardised_product | IRDAI | 2020 | product_guideline | https://irdai.gov.in/documents/37343/1092396/Corona+Kavach+Policy.pdf/33f3e0bb-fac5-b6d9-ee1c-4d22d321dc3a?version=3.2&t=1659327794545&download=true | Ref: IRDAI/HLT/REG/CIR/163/06/2020, 26 Jun 2020. Withdrawn for new sales but still relevant for legacy policy enquiries. |
+| irdai-ombudsman-rules-faq-2017 | FAQ on Insurance Ombudsman Rules, 2017 | claim_service | IRDAI / DFS | 2017 | rules_faq | https://irdai.gov.in/documents/37343/379608/FAQ%E2%80%99s+on+Insurance+Ombudsman+Rules+2017.pdf/37bc4077-6906-91ad-fb49-6c0e733b3e0d?version=3.0&t=1640147675026 | Notified by Central Government (DFS) 27 Apr 2017; amended 2018, 2021. FAQ form covers rule text + jurisdiction + complaint process. |
+| irdai-grievance-redressal-handbook | Grievance Redressal System Handbook | claim_service | IRDAI | 2021 | handbook | https://irdai.gov.in/documents/38105/41843/Grievance+Redressal+System+Handbook.pdf/aa18899a-ff58-69bd-53eb-bc13fb00597e?version=1.1&t=1631769637686 | Consumer-facing handbook on IGMS, Bima Bharosa, TAT for grievances, escalation path. |
+| irdai-insurance-act-1938-amended-2021 | The Insurance Act, 1938 (incorporating amendments till 2021) | master_regulation | IRDAI / Parliament of India | 2021 | statute | https://irdai.gov.in/documents/37343/366193/Insurance+Act,1938+-+incorporating+all+amendments+till+20212021-08-12.pdf/dd88b875-bf63-3fbb-813a-d7fbbfd80aea?version=1.1&t=1665118224832&download=true | Parent statute. Includes Sec 38 (assignment), Sec 39 (nomination), Sec 45 (claim repudiation — non-disclosure 3-year window). |
+| nha-pmjay-operations-manual | Ayushman Bharat PM-JAY Operations Manual | government_scheme | National Health Authority (NHA) | 2018 | operations_manual | https://nha.gov.in/img/resources/Operation%20Manual%20for%20AB%20PM-JAY.pdf | Official NHA operational guideline for the PMJAY scheme — context for bot responses about overlap with private health insurance. |
+| dfs-gst-exemption-insurance-faqs-2025 | FAQs on Exemption of GST on All Individual Life and Health Insurance Policies | government_tax | Department of Financial Services, Ministry of Finance | 2025 | faq | https://financialservices.gov.in/beta/sites/default/files/2025-10/Insurance-FAQs.pdf | Official DFS FAQ on 0% GST regime for individual life + health insurance, effective 22 Sep 2025 (gives effect to CBIC Notification 16/2025-CTR). Authoritative tax-treatment reference for bot. |
+
+## Notes on items deferred from this list (transparent gaps)
+
+- **Section 80D bare-act PDF** — incometaxindia.gov.in renders Section 80D as an HTML page (`/w/section-80d-55`) rather than a section-specific PDF; the only PDF is the full Income-Tax Act, 1961 bare act (which is ~6,000 pages and overkill for the corpus). If you want it anyway, the bare-act PDF is at `https://www.incometaxindia.gov.in/documents/d/guest/income_tax_act_1961_as_amended_by_fa_act_2026-1-pdf`. I left it out to keep the corpus relevant.
+- **CBIC Notification 16/2025-CTR direct PDF** — `cbic-gst.gov.in` does host it, but the canonical direct-PDF link is behind the dynamic notifications listing (`taxinformation.cbic.gov.in/view-pdf/...`) and the slug rotates. The DFS FAQ PDF above is more stable, more digestible, and links back to the notification. Add the raw notification later if you need the legal text verbatim.
+- **Master Circular on Standardisation 2020 Corrigendum** — exists at `https://irdai.gov.in/documents/37343/365525/Master+Circular+on+Standardization+of+Health+Insurance+Products+-+Corrigend.pdf/1edf66a6-d999-7a7e-df10-94cde1512b53?version=1.2&t=1639277778578&download=true` — small file correcting the PED definition. Add if you want to cover the Aug 2020 fix.
+
+## Downloader notes (important)
+
+- All `irdai.gov.in/documents/...` URLs return HTTP 403 to plain `curl` (Akamai bot challenge). They serve real PDFs to:
+  1. A real browser, or
+  2. A `requests`/`httpx` session that first GETs `https://irdai.gov.in/` to collect the Akamai cookie, then sends the same `User-Agent` + `Referer: https://irdai.gov.in/` on the PDF request, or
+  3. A headless browser (Playwright / Selenium) — most reliable.
+- `indiacode.nic.in`, `nha.gov.in`, `financialservices.gov.in`, and `cbic-gst.gov.in` accept plain `curl` with a standard browser UA.
+- Two URLs above (`irdai.gov.in/document-detail?documentId=...`) are landing pages, not direct PDF binaries: `arogya-sanjeevani` and `protection-policyholders-master-circular-2024`. The downloader should parse the page and follow the embedded PDF link (look for `<a href=".../documents/37343/...pdf">`).

docs/01-requirements.md

@@ -0,0 +1,261 @@
+# 01 — Requirements
+
+| Field | Value |
+| --- | --- |
+| Project | Insurance Sales Portfolio Expert |
+| Document version | 0.1 (draft) |
+| Date | 2026-05-13 |
+| Author | Rohit Saraf |
+| Status | In review — pending stakeholder sign-off |
+| Reviewer | (to be assigned) |
+| Source brief | Sarvam AI take-home assignment |
+
+---
+
+## 0. Document purpose
+
+This is the foundational requirements document for the Insurance Sales Portfolio Expert. It defines what we are building, for whom, against what measurable success criteria, and — equally important — what we are explicitly **not** building.
+
+All downstream documents (`02-architecture.md`, `03-eval-plan.md`, `04-failure-modes.md`, `05-needs-analysis-flow.md`, `decisions.md`) depend on this spec. Changes here cascade; this is the source of truth for product scope.
+
+This document was authored with deliberate pre-implementation rigour because the assignment is evaluated as much on the clarity of the design narrative as on the working bot. Where decisions in this doc rule things out, the rationale is captured inline so a future reader (or interviewer) can audit the choices.
+
+---
+
+## 1. Product vision (one paragraph)
+
+A **voice-first AI advisor for Indian health insurance buyers**, deployed over a **curated, pre-acquired corpus** of policy documents from leading Indian health insurers. The product replaces the typical experience of speaking to a generalist advisor at a horizontal aggregator — adaptive needs discovery, granular policy filtering, side-by-side comparison, illustrative pricing, and consultative recommendation — and surfaces all of it through a natural, code-switched (English + Hindi) voice conversation grounded in the actual policy wordings, with clause-level citations on every factual claim.
+
+### 1.1 Strategic framing (for Sarvam)
+
+The product is **consumer-facing in experience** but **B2B in commercial application**. The realistic deployment is an insurer or aggregator white-labelling this advisor to assist customers shopping for health insurance, with Sarvam's ASR / TTS / Indic LLM stack as the core enabler. The assignment build is the consumer surface; the architecture must remain coherent for a white-labelled / multi-tenant future.
+
+---
+
+## 2. Differentiation
+
+The advisor experience that exists today in India is split: aggregators (PolicyBazaar, Coverfox, InsuranceDekho) provide structured comparison but lean heavily on human callbacks for actual advisory; bank / insurer-direct channels provide depth but only on their own products. Both surfaces struggle with voice as a first-class modality and with grounding recommendations in primary source documents.
+
+| Dimension | Status quo (aggregator + callback) | This product |
+| --- | --- | --- |
+| Primary interface | Web form → human callback | Voice-native, AI-led end-to-end |
+| Policy depth | Marketing summaries + feature ladders | Full policy wordings + clause-level cited Q&A |
+| Recommendation basis | Quote price + commercial incentive | Buyer profile + policy fit, transparently reasoned |
+| Indic language support | English primary, Hindi shallow | Hindi / Hinglish first-class through conversation |
+| Trust mechanism | Brand + reviews + advisor rapport | Citation grammar — every factual claim links to source clause |
+| Marginal cost-to-serve | Salaried human advisor per buyer | Voice agent, marginal cost ≈ STT + LLM + TTS per turn |
+| Persistence of advice | Voice call, then lost | Replayable transcript with cited recommendations |
+
+The point of differentiation is **not "no humans"** — it is **"depth + grounding + Indic-native + low marginal cost"** in a single surface. Human escalation remains a designed-in path (see §6 non-goals).
+
+---
+
+## 3. User personas
+
+Three personas, intentionally spanning the spectrum of prior knowledge and intent. The product must serve all three without forcing them into a single flow.
+
+### 3.1 Persona A — Priya, 28, Pune | first-time buyer
+
+- Software professional, two years into career, no dependants yet.
+- Triggered by a friend's recent hospitalisation and a ₹4L out-of-pocket bill.
+- Has **no current policy** beyond a basic employer cover she doesn't fully understand.
+- Doesn't know what to ask — needs the advisor to **lead the conversation** and educate as it goes.
+- Budget-sensitive (₹10–20K annual premium acceptable).
+- Comfortable in **Hindi-English code-switch**, prefers conversational voice over reading.
+- Success looks like: she ends the session with a clear shortlist of 2 policies, understands what each covers, and knows what she's paying for.
+
+### 3.2 Persona B — Anjali, 32, Mumbai | informed shopper
+
+- Senior engineer at a growth-stage startup, recently married, no kids yet.
+- Has employer cover (₹5L floater) and worries it is insufficient and not portable.
+- Has heard of HDFC ERGO, Star, Niva Bupa — wants help choosing between **2–3 specific policies** she's already aware of.
+- Time-poor — wants a guided, voice-led experience during her commute.
+- Comfortable in English; will tolerate Hindi if natural.
+- Success looks like: she gets a defensible comparison across her shortlist, surfaces sub-limits and waiting periods she hadn't thought to ask about, and walks away ready to buy.
+
+### 3.3 Persona C — Vikram, 45, Bengaluru | family decision-maker
+
+- Mid-career VP, two school-age kids, ageing parents (70 and 68) at home.
+- Already has a family floater; explicitly evaluating **a separate parent policy** (high-sum-insured, senior-citizen plan).
+- Knows the basics; wants to **deep-dive into sub-limits, claim settlement ratios, network hospitals, room-rent capping, and pre-existing-disease waiting periods**.
+- Will press the advisor on specific clauses — must be answered with citations, not vibes.
+- English-dominant.
+- Success looks like: he extracts decision-grade information without having to read three 60-page PDFs himself, and is shown the trade-offs explicitly.
+
+All three personas share one trait: **they do not want to be sold to.** They want to be advised. The product persona (§5.2) reflects this.
+
+---
+
+## 4. Buyer journey
+
+The advisor flow is **adaptive** — branches expand or contract based on conversational signal — but the seven-stage backbone is stable:
+
+```
+  ┌────────────────────────┐
+  │ 1. Greeting + framing  │  "I'm an advisor, not a broker. I'll ask you a few
+  └────────────┬───────────┘   things, then we'll look at policies together."
+               │
+  ┌────────────▼───────────┐
+  │ 2. Adaptive fact-find  │  Universal core: age, dependants, income, existing
+  │    (see Doc 05)        │   cover, primary goal, location. Conditional deep
+  └────────────┬───────────┘   dives based on signal.
+               │
+  ┌────────────▼───────────┐
+  │ 3. Profile readback    │  "Here's what I've understood. Correct me." User
+  └────────────┬───────────┘   confirms or amends; agent commits the profile.
+               │
+  ┌────────────▼───────────┐
+  │ 4. Shortlist           │  Agent applies hard filters (must-haves) +
+  │    generation          │   soft scoring to corpus; returns 3–5 candidates.
+  └────────────┬───────────┘
+               │
+  ┌────────────▼───────────┐
+  │ 5. Side-by-side        │  Visual comparison surface in the UI; advisor
+  │    comparison          │   narrates differences in voice.
+  └────────────┬───────────┘
+               │
+  ┌────────────▼───────────┐
+  │ 6. Recommendation +    │  Advisor recommends one or two with reasoning
+  │    transparent why     │   tied back to the user's profile.
+  └────────────┬───────────┘
+               │
+  ┌────────────▼───────────┐
+  │ 7. Open Q&A + handoff  │  Free-form voice Q&A with clause-level citations.
+  └────────────────────────┘   Optional: handoff path to a human / insurer.
+```
+
+The conversation may revisit earlier stages — for example, Vikram (Persona C) may skip 1–3 and jump straight to 5/7 by saying "compare these three for me." The architecture must permit non-linear traversal.
+
+---
+
+## 5. Product principles
+
+These are the non-negotiable principles that shape every downstream design decision. Each is stated as a rule, with the reason it exists.
+
+### 5.1 Grounded over fluent
+
+If we cannot cite the source for a factual claim, we do not make the claim. The advisor will say "I don't see that in the policy document" before it improvises. Hallucinations on coverage details are not "small UX bugs" — they are mis-selling, which is regulated in India and a reputational risk for any commercial deployment.
+
+### 5.2 Consultative, never closing
+
+The advisor's persona is modelled on a good Independent Financial Advisor — informed, patient, comfortable saying "this isn't the right policy for you." It is explicitly **not** a call-centre closer. Persuasion is allowed once the buyer signals readiness; manipulation is not.
+
+### 5.3 Indic-native, not translated
+
+Hindi and Hinglish are designed-in from day one, not retrofitted. The advisor opens by detecting the user's language preference within the first one or two turns and adapts.
+
+### 5.4 Curated corpus is the product's moat
+
+The user does not upload PDFs. We pre-acquire, normalise, and structurally extract from the corpus so quality is under our control. The corpus is the product's defensibility relative to a generic RAG-over-anything bot.
+
+### 5.5 Architecture is built for category expansion from day one
+
+Scope v1 is health insurance only, but every schema, interface, and adapter is designed so adding Life / Motor / Travel later is a configuration change, not a refactor. See §7 (Constraints) and Doc 02 (Architecture) for the seven c-readiness commitments.
+
+### 5.6 Explainability is a feature, not a chore
+
+The architecture document, the decisions log, and the eval harness are first-class deliverables, not afterthoughts. A reviewer should be able to walk through any technology pick and find the alternatives we considered and the empirical basis for the choice.
+
+---
+
+## 6. Success criteria
+
+What "working" means, measurably. Every entry here will have a corresponding test in `03-eval-plan.md`.
+
+| # | Criterion | Threshold for v1 | How measured |
+| --- | --- | --- | --- |
+| C1 | End-to-end voice latency (user speech end → advisor speech start) | **p50 ≤ 4s, p95 ≤ 7s** | Instrumented turn logs |
+| C2 | Factual answer accuracy on gold Q&A set | **≥ 95% correct** | Automated grader vs. 100-question gold set per policy |
+| C3 | Citation accuracy (cited clause actually supports the claim) | **≥ 95%** | Automated grader on cited spans |
+| C4 | Refusal precision on out-of-policy questions | **≥ 90%** (refuses when it should) | Adversarial test set in eval plan |
+| C5 | Structured-field extraction accuracy from PDFs | **≥ 95% per field, ≥ 90% per policy across all fields** | Manual gold-labelled subset (5 policies × all fields) |
+| C6 | Comparison view correctness | **100% of compared fields match the structured store** | Snapshot test on comparison rendering |
+| C7 | Pricing band realism | **Illustrative band within ±25% of a real PolicyBazaar quote** for 10 spot checks | Manual ground truth |
+| C8 | Hindi/Hinglish handling | **No degradation > 5pp on C2/C3** when user speaks Hindi vs. English | Bilingual gold set |
+| C9 | Recommendation defensibility | **Reasoning trace explicitly references the user's profile fields** in 100% of recommendations | Human review of 30 sessions |
+| C10 | UI polish (qualitative) | Demo-grade — fonts harmonised, no console errors, no broken states | Internal review checklist |
+
+These thresholds are deliberately aggressive. Where we fall short, the doc will record the actual numbers and why — that honesty is itself part of the artifact.
+
+---
+
+## 7. Non-goals (explicit)
+
+To protect against scope creep — and to give the interviewer something to grade against — these are explicitly **out of scope** for v1.
+
+- **Transacting / selling.** We do not collect payment, issue policies, or integrate with insurer KYC. Handoff to the insurer is a link, not a flow.
+- **Underwriting.** We do not assess whether the user *will* be granted a policy at a given price. We surface illustrative pricing only.
+- **Medical advice.** "Will this treatment be covered" is in scope. "Should I get this treatment" is not.
+- **Real-time quote pulls from insurer APIs.** Out of scope; possibly out of reach commercially. We use aggregated public data and label pricing as illustrative.
+- **Categories beyond Health.** Life, Motor, Travel, Cyber, etc. are explicitly v2. The architecture accommodates them; we do not populate them.
+- **Multi-user / multi-tenant deployment.** v1 is single-user demo. Stateless services + canonical DB make v2 multi-tenant tractable.
+- **User-uploaded PDFs.** Corpus is curated. (See §5.4.)
+- **Mobile-native deployment.** v1 is desktop browser. Mobile responsive is a stretch goal.
+- **Real-time co-browsing with a human advisor.** v2 handoff feature.
+- **Persistent user accounts across sessions.** v1 is session-scoped.
+- **Persona-A onboarding video / tutorial layer.** The advisor itself does the onboarding through voice.
+
+---
+
+## 8. Constraints
+
+### 8.1 Time
+
+- Sarvam assignment deadline: **TBD — pending confirmation.** Working assumption: 2 weeks from kick-off.
+
+### 8.2 Stack expectations (Sarvam-aware)
+
+- We will **benchmark Sarvam's STT, TTS, and Indic LLM offerings** against best-in-class alternatives on a real test set. Picks are justified in `decisions.md`. Silent defaults to OpenAI / Anthropic / ElevenLabs are not acceptable.
+- We will use English-only PDFs as input (regulator-mandated language for policy wordings is English).
+- The conversational layer must support Hindi and Hinglish output regardless of input language.
+
+### 8.3 Regulatory / ethical
+
+- No mis-selling. The advisor must not push a product that the user's profile does not fit.
+- No medical advice.
+- All pricing is labelled "illustrative" with a visible disclaimer and source citation.
+- No personally identifiable information persisted beyond the session.
+- Document sourcing: only publicly available brochures, customer information sheets, and policy wordings from insurer websites and IRDAI's product database. No scraping behind logins.
+
+### 8.4 Technical envelope
+
+- v1 UI: Streamlit. Business logic is decoupled into a separate `app/` Python module so a future FastAPI + React v2 swaps the UI layer only.
+- v1 corpus: 15–20 health policies across 5 leading Indian insurers (Star Health, HDFC ERGO, Niva Bupa, Care Health, ICICI Lombard — exact list pending availability check).
+- v1 deployment: local development + a single-instance deploy (Streamlit Community Cloud or equivalent) for the interviewer to demo.
+
+---
+
+## 9. Open questions (deferred to downstream docs)
+
+These are intentionally **not** resolved here. Each is owned by a specific later document.
+
+| # | Question | Owned by |
+| --- | --- | --- |
+| Q1 | Exact STT / TTS / LLM / embedding provider picks, with benchmarks | `02-architecture.md` + `decisions.md` |
+| Q2 | Structured schema — exact 30–50 field set, field types, optionality | `02-architecture.md` |
+| Q3 | Extraction pipeline — single-pass LLM vs. self-critique vs. human-in-loop | `02-architecture.md` |
+| Q4 | Gold Q&A set construction — sources, size, grader design | `03-eval-plan.md` |
+| Q5 | Refusal taxonomy — exact categories and example utterances | `03-eval-plan.md` + `04-failure-modes.md` |
+| Q6 | Fact-find question graph — nodes, edges, termination criteria | `05-needs-analysis-flow.md` |
+| Q7 | Pricing aggregation sources, freshness policy, ±25% empirical proof | `02-architecture.md` |
+| Q8 | Recommendation engine — rule-based pre-filter vs. pure-LLM reasoning | `02-architecture.md` |
+| Q9 | Failure modes — full register with mitigations | `04-failure-modes.md` |
+| Q10 | Observability — what we log per turn, retention, dashboards | `02-architecture.md` |
+
+---
+
+## 10. Revision history
+
+| Version | Date | Author | Change |
+| --- | --- | --- | --- |
+| 0.1 | 2026-05-13 | Rohit Saraf | Initial draft post-brainstorm with AI architect |
+
+---
+
+## 11. Sign-off
+
+This document is in review. Approval required from:
+
+- [ ] Rohit Saraf (project owner)
+
+Once approved, this doc becomes the source-of-truth spec. Subsequent docs reference it by section number.

docs/02-architecture.md

@@ -0,0 +1,329 @@
+# 02 — Architecture
+
+| Field | Value |
+| --- | --- |
+| Project | Insurance Sales Portfolio Expert |
+| Document version | 0.1 (draft) |
+| Date | 2026-05-13 |
+| Depends on | `01-requirements.md` |
+| Status | In review |
+
+---
+
+## 0. Purpose
+
+This document specifies the technical architecture: the stack, the data flow, the canonical schema, the per-insurer adapter pattern, and the seven commitments that make v1 (vertical slice) cheaply expandable to v2 (full platform). Every decision here is mirrored in `decisions.md` (with alternatives + reasoning).
+
+---
+
+## 1. System diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                          USER (browser)                              │
+│                  (mic input · speaker output · chat UI)              │
+└─────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  │  audio bytes / text / clicks
+                                  ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                      STREAMLIT UI (app/main.py)                      │
+│   ─ chat pane · audio recorder · filter sidebar · comparison view    │
+│   ─ session state · @st.cache_resource for heavy clients             │
+└─────────────────────────────────────────────────────────────────────┘
+        │                              │                          │
+        │ audio bytes                  │ user_query (text)        │ filter / select
+        ▼                              ▼                          ▼
+┌──────────────────┐         ┌─────────────────────┐   ┌──────────────────────┐
+│ VOICE (app/voice)│         │ ORCHESTRATOR        │   │ STRUCTURED STORE     │
+│ ─ Sarvam Saaras  │ ──────► │ (app/orchestrator)  │ ◄ │ DuckDB               │
+│   (STT)          │  text   │ ─ persona prompt    │   │ ─ 1 row per policy   │
+│ ─ Sarvam Bulbul  │ ◄────── │ ─ fact-find graph   │   │ ─ 40-50 fields       │
+│   (TTS)          │  audio  │ ─ tool routing      │   │ ─ filter / compare   │
+└──────────────────┘         │ ─ citation grammar  │   └──────────────────────┘
+                             │                     │              ▲
+                             │                     │              │ extracted
+                             └──────────┬──────────┘              │ at ingest time
+                                        │                          │
+                                        ▼                          │
+                             ┌─────────────────────┐               │
+                             │  Sarvam-M (LLM)     │               │
+                             └─────────────────────┘               │
+                                        ▲                          │
+                                        │ retrieved chunks         │
+                                        │                          │
+                             ┌──────────┴──────────┐               │
+                             │ VECTOR STORE        │   ┌───────────┴──────────┐
+                             │ Chroma              │   │ INGEST PIPELINE      │
+                             │ ─ chunk + embedding │ ◄ │ (rag/ingest.py)      │
+                             │ ─ metadata: policy, │   │ ─ download PDFs      │
+                             │   page, clause      │   │ ─ chunk + embed      │
+                             └─────────────────────┘   │ ─ LLM extract → DB   │
+                                                       │ ─ per-insurer adapter│
+                                                       └──────────────────────┘
+                                                                    ▲
+                                                                    │ raw PDFs
+                                                       ┌────────────┴─────────┐
+                                                       │ INSURER WEBSITES /   │
+                                                       │ IRDAI PRODUCT DB     │
+                                                       └──────────────────────┘
+```
+
+---
+
+## 2. Stack picks (v1)
+
+| Layer | Pick | Why | Alternative considered | Decision in `decisions.md` |
+| --- | --- | --- | --- | --- |
+| STT | **Sarvam Saaras** | Sarvam-first per assignment context; strong Indic/Hinglish handling | Whisper-large-v3, Deepgram Nova | D-006 |
+| TTS | **Sarvam Bulbul** | First-party Indic prosody; Sarvam-first | ElevenLabs, OpenAI TTS | D-006 |
+| LLM | **Sarvam-M** (or current Sarvam flagship) | Sarvam-first; Indic-tuned reasoning | GPT-4o, Claude Sonnet | D-006 |
+| Embeddings | **Sarvam embedding API if available, else `text-embedding-3-small`** | Will benchmark; whichever scores higher on retrieval @5 against our gold set | OpenAI embeddings, BGE-large local | D-006 |
+| Vector DB | **Chroma** (local, persisted to disk) | Zero-config, embedded, works on Streamlit Cloud | FAISS (no metadata filtering), Qdrant (overkill) | D-004 |
+| Structured DB | **DuckDB** (single file, embedded) | One-file, columnar, no server, deployable to Streamlit Cloud | SQLite, Postgres | D-004 |
+| UI | **Streamlit** | Fastest v1; business logic decoupled so v2 swaps UI only | FastAPI + React (v2) | D-005 |
+| Audio capture | **`streamlit-mic-recorder`** or `streamlit-webrtc` (whichever proves stable in <1h spike) | Required for browser-side mic | Native HTML5 + WebSocket (too much glue) | — |
+| Deployment | **Streamlit Community Cloud** | Free, GitHub-connected, supports Streamlit out of box, secrets UI for API keys | Render, Fly.io | — |
+
+**Provider abstraction:** every provider is behind a thin interface (`app/providers/stt.py`, `app/providers/tts.py`, `app/providers/llm.py`) so a benchmark swap is a config flag. **This is non-negotiable** — it's c-readiness commitment #5.
+
+---
+
+## 3. Canonical data flow (a single user turn)
+
+```
+user speaks
+    │
+    ▼ (audio bytes)
+voice.transcribe()  ── Sarvam Saaras ──► text
+    │
+    ▼
+orchestrator.handle_turn(text, session)
+    │
+    ├── if fact-find phase: needs_finder.next_question(profile) → returns next Q
+    │
+    ├── if filter/compare intent detected: structured_store.query(filters) → rows
+    │
+    └── if Q&A intent: 
+            rag.retrieve(query, top_k=5)
+                ─ returns chunks with (policy_id, page, clause, text, score)
+            llm.generate(persona_prompt + chat_history + retrieved_chunks + user_query)
+                ─ enforces citation grammar [Source: ...]
+                ─ enforces refusal when retrieval is weak
+                ─ returns text response
+    │
+    ▼
+voice.synthesize(text)  ── Sarvam Bulbul ──► audio bytes
+    │
+    ▼
+ui.play_audio(audio_bytes)
+ui.append_to_chat(text + citations)
+log_turn({stt_confidence, retrieved_ids, latency_ms, cost_usd, refused})
+```
+
+---
+
+## 4. Policy schema (extensible to Life / Motor / Travel)
+
+Full Pydantic model lives in `rag/schema.py` (designed in parallel by a sub-agent — see that file for the canonical 40–50 fields).
+
+**Field groupings:**
+
+1. **Identity** — `policy_id`, `insurer_name`, `insurer_slug`, `policy_name`, `policy_type` (enum), `uin_code`
+2. **Eligibility** — `min_entry_age`, `max_entry_age`, `max_renewal_age`, `family_composition`
+3. **Sum insured & premium** — `sum_insured_options[]`, `premium_payment_modes[]`, `premium_band_illustrative`, `grace_period_days`
+4. **Waiting periods** *(comparison-critical)* — `initial_waiting_period_days`, `pre_existing_disease_waiting_months`, `specific_disease_waiting_months`, `maternity_waiting_months`, `specific_diseases_listed[]`
+5. **Coverage scope** *(comparison-critical)* — `pre_hospitalization_days`, `post_hospitalization_days`, `day_care_treatments_count`, `domiciliary_treatment`, `ayush_coverage`, `maternity_coverage`, `newborn_coverage`, `organ_donor_expenses`, `ambulance_cover`, `critical_illness_cover`, `restoration_benefit`, `no_claim_bonus_pct`, `preventive_health_checkup`
+6. **Sub-limits & caps** *(comparison-critical)* — `room_rent_capping`, `icu_capping`, `copayment_pct`, `disease_wise_sub_limits` (json), `deductible_amount`
+7. **Geography & network** — `geographic_coverage_india`, `worldwide_emergency_cover`, `network_hospital_count`, `cashless_treatment_supported`
+8. **Exclusions** — `permanent_exclusions[]`, `temporary_exclusions[]`, `notable_exclusions_summary`
+9. **Claim & service** — `claim_settlement_ratio`, `claim_process_summary`, `tat_cashless_authorization_hours`
+10. **Riders** — `available_riders[]`, `top_rider_examples`, `rider_premium_indicative`
+11. **Source metadata** — `source_pdf_path`, `source_pdf_url`, `last_updated_date`, `extraction_confidence_pct`
+
+**v2 expansion:** add category-specific optional field groups (`life_*`, `motor_*`, `travel_*`). Existing fields are never removed. Adding a category = schema additive change, no migration.
+
+---
+
+## 5. Extraction pipeline
+
+```
+for pdf in corpus:
+    text_chunks = chunk(pdf, target_tokens=800, overlap=120)
+    # chunks indexed in Chroma with metadata: policy_id, page, clause_path
+    
+    # one-shot LLM extraction with the schema as a structured-output target
+    extracted = llm.extract_structured(
+        full_pdf_text,
+        schema=HealthPolicy,
+        few_shot_examples=[hdfc_ergo_example, niva_bupa_example]
+    )
+    
+    # self-critique pass: LLM checks every field's evidence in the source
+    confidence_per_field = llm.self_critique(extracted, full_pdf_text)
+    extracted.extraction_confidence_pct = aggregate(confidence_per_field)
+    
+    # write to DuckDB
+    structured_store.upsert(extracted)
+```
+
+**Quality bar:** any field below 80% self-rated confidence is **stored with a `_low_confidence` flag** and excluded from comparison surfaces (but kept queryable). This protects the comparison view from looking authoritative when it isn't.
+
+**Eval (see Doc 03):** manually spot-check 5 policies × all fields. If extraction accuracy < 90% on critical fields (waiting periods, sub-limits, room rent), iterate the extraction prompt.
+
+---
+
+## 6. Per-insurer adapter pattern
+
+Each insurer's website has a unique structure. We isolate per-insurer logic in `rag/adapters/<insurer_slug>.py`:
+
+```python
+# rag/adapters/base.py
+class InsurerAdapter(ABC):
+    insurer_slug: str
+    insurer_name: str
+    
+    @abstractmethod
+    def discover_policy_urls(self) -> list[PolicyURL]:
+        """Crawl/scrape insurer site to find all health-policy PDF URLs."""
+    
+    @abstractmethod
+    def normalize_pdf(self, pdf_path: Path) -> Path:
+        """Insurer-specific PDF normalization (e.g. handle watermarks, OCR fallback)."""
+```
+
+Adding an 11th insurer = one new adapter file. **c-readiness commitment #1.**
+
+For v1, we accept that discover_policy_urls() is hand-curated (from sub-agent corpus list) — v2 makes it agentic.
+
+---
+
+## 7. The seven c-readiness commitments (from prior brainstorm)
+
+These are non-negotiable architectural invariants:
+
+| # | Commitment | Where enforced |
+| --- | --- | --- |
+| 1 | Insurer-agnostic crawler — per-insurer adapter modules | `rag/adapters/` |
+| 2 | Category-agnostic structured schema — Life/Motor/Travel fields nullable today | `rag/schema.py` |
+| 3 | Pluggable extraction pipeline — prompt-and-schema-driven, not hand-coded per insurer | `rag/extract.py` |
+| 4 | Data-driven filter UI — sliders/checkboxes rendered from schema | `app/ui_filter.py` |
+| 5 | Provider-agnostic STT/TTS/LLM/embeddings — thin interface, swap via config | `app/providers/` |
+| 6 | Eval harness scales linearly — same script on 5 policies works on 500 | `eval/run.py` |
+| 7 | Stateless services, single source of truth in DB — no Streamlit-session shortcuts | All `app/` modules |
+
+Every PR / commit should be self-audited against these.
+
+---
+
+## 8. Observability (minimum-viable)
+
+Every turn writes one JSON line to `logs/turns.jsonl`:
+
+```json
+{
+  "ts": "2026-05-13T14:23:11Z",
+  "session_id": "...",
+  "turn_id": "...",
+  "user_text": "what's the waiting period for cataract?",
+  "stt_confidence": 0.94,
+  "intent": "policy_qa",
+  "retrieved_chunks": ["star-comprehensive:p18:c4.2.7", "..."],
+  "llm_latency_ms": 1340,
+  "tts_latency_ms": 720,
+  "total_latency_ms": 3210,
+  "refused": false,
+  "refusal_reason": null,
+  "cost_estimate_inr": 1.4
+}
+```
+
+**Why this matters:** the Sarvam interviewer can replay any session, see what the bot retrieved, see what it cost, see where it refused. This is the difference between a demo and a service.
+
+---
+
+## 9. Repo layout
+
+```
+insurance-sales-bot/
+├── app/
+│   ├── __init__.py
+│   ├── main.py                 # Streamlit entrypoint
+│   ├── orchestrator.py         # turn handler, persona prompt, intent routing
+│   ├── needs_finder.py         # adaptive fact-find question graph
+│   ├── ui_chat.py
+│   ├── ui_filter.py            # schema-driven filter UI
+│   ├── ui_compare.py           # side-by-side comparison
+│   └── providers/
+│       ├── stt.py              # Sarvam Saaras client behind interface
+│       ├── tts.py              # Sarvam Bulbul client behind interface
+│       ├── llm.py              # Sarvam-M client behind interface
+│       └── embeddings.py
+├── rag/
+│   ├── corpus/                 # raw PDFs (committed for reproducibility)
+│   ├── extracted/              # per-policy JSON (committed)
+│   ├── vectors/                # Chroma persistence (gitignored — rebuilt)
+���   ├── policies.duckdb         # structured store (committed)
+│   ├── schema.py               # Pydantic HealthPolicy model
+│   ├── ingest.py               # download → chunk → embed → extract → store
+│   ├── retrieve.py             # query → top-k chunks
+│   ├── extract.py              # LLM-driven structured extraction
+│   └── adapters/
+│       ├── base.py
+│       ├── star_health.py
+│       ├── hdfc_ergo.py
+│       └── ... (10 adapters)
+├── eval/
+│   ├── gold_qa.json            # 50–100 gold Q&A pairs (10/policy for top policies)
+│   ├── grader.py               # automated grader (LLM judge + regex)
+│   ├── run.py                  # batch runner
+│   └── results.md              # last run's accuracy table
+├── data/
+│   ├── insurers.json           # 10 insurers metadata
+│   └── corpus_urls.md          # output of corpus-discovery sub-agent
+├── docs/
+│   ├── 01-requirements.md
+│   ├── 02-architecture.md      # THIS FILE
+│   ├── 03-eval-plan.md
+│   ├── 04-failure-modes.md
+│   ├── 05-needs-analysis-flow.md
+│   ├── decisions.md
+│   └── ROADMAP.md
+├── tests/
+│   └── test_smoke.py
+├── streamlit_app.py            # Streamlit Cloud entrypoint (thin wrapper)
+├── requirements.txt
+├── .env / .env.example
+├── .gitignore
+└── README.md
+```
+
+---
+
+## 10. Deployment
+
+- **Repo:** `github.com/rohitsar567/insurance-sales-bot` (public)
+- **Hosting:** Streamlit Community Cloud — `share.streamlit.io` connects to the repo, deploys `streamlit_app.py` on push
+- **Secrets:** Sarvam API key set via Streamlit Cloud's secrets manager (mirrors `.env`)
+- **Resources:** ~1 GB ephemeral, persistent disk for `rag/` (corpus + DuckDB committed to repo so deploy is reproducible from `git clone`)
+- **Vector store rebuild:** on first deploy, app detects empty `rag/vectors/` and rebuilds from `rag/corpus/` (one-time ~5 min cold start; subsequent starts cached)
+
+---
+
+## 11. Open decisions deferred to Doc 03 / Doc 04 / Doc 05
+
+| # | Decision | Owner |
+| --- | --- | --- |
+| A | Final embedding provider after benchmark | `decisions.md` D-011 (pending Sarvam embeddings API check) |
+| B | Refusal taxonomy — exact categories | `04-failure-modes.md` |
+| C | Fact-find question graph — nodes, edges, termination | `05-needs-analysis-flow.md` |
+| D | Gold Q&A construction approach | `03-eval-plan.md` |
+| E | Recommendation engine — rule-based pre-filter vs. pure-LLM | Likely D-012, pending eval results |
+
+---
+
+## 12. Revision history
+
+| Version | Date | Change |
+| --- | --- | --- |
+| 0.1 | 2026-05-13 | Initial draft |

docs/03-eval-plan.md

@@ -0,0 +1,105 @@
+# 03 — Evaluation Plan
+
+| Field | Value |
+| --- | --- |
+| Project | Insurance Sales Portfolio Expert |
+| Version | 0.1 |
+| Date | 2026-05-13 |
+| Depends on | `01-requirements.md` §6 (success criteria), `02-architecture.md` (system under test) |
+| Status | Pipeline implemented; full run pending corpus completion |
+
+## 0. Purpose
+
+Evaluation is **how we prove the bot works**. Three artifacts:
+
+1. **Gold Q&A set** — ground-truth question-answer-source triples
+2. **Automated grader** — measures factual accuracy + citation accuracy + refusal precision per turn
+3. **Results table** — versioned, audit-grade record of every eval run
+
+These directly back the success criteria in Doc 01 §6: C2 (≥95% factual), C3 (≥95% citation), C4 (≥90% refusal precision).
+
+## 1. Gold Q&A construction — three pipelines
+
+### Pipeline A — auto-generated from structured extraction (the bulk)
+
+For every successfully extracted policy in DuckDB, generate templated Q&A where the answer comes directly from the 48-field schema. Per `eval/generate_gold.py`:
+
+- ~15 question templates × ~80 policies = ~1,100 candidate pairs
+- Each pair is **fully reproducible** — the answer traces to a specific field which traces to a specific clause
+- Auto-tagged: `question_type` ∈ {waiting_period, coverage_scope, exclusions, sub_limit, eligibility, claim, network, bonus}
+
+**Why this scales:** adding the 11th, 12th, 80th policy adds zero new template work. Same generator, more rows.
+
+### Pipeline B — LLM-drafted nuanced questions (curated)
+
+For top-priority policies (top 10–20), run an LLM (Sarvam-M, with DeepSeek-V3 fallback) on the policy text with prompt: *"generate 5 buyer-style questions whose answers are explicitly in this document; include the source clause."* Each generated pair is **human spot-checked** before commit.
+
+Target: 5 × 20 = 100 questions covering multi-clause and edge-case reasoning that Pipeline A can't generate.
+
+### Pipeline C — hand-crafted adversarial set (refusal tests)
+
+~30–40 hand-written questions across these classes:
+
+- **Out-of-corpus** ("Does this cover space tourism?") → expect refusal
+- **Out-of-policy-type** ("What is the IRDAI mandate on dental coverage?") → expect refusal (D-017)
+- **Multi-policy compare** ("Compare cancer coverage in Star vs HDFC ERGO") → expect cited comparison
+- **Hinglish** ("Cataract ke liye waiting period kya hai?") → expect Hindi answer, same factual accuracy
+- **Code-switched** ("policy mein maternity cover hai kya?") → expect Hinglish answer
+
+Each pair marked with `expected_refusal: bool`. Refusal cases test that the bot doesn't hallucinate when grounding fails.
+
+## 2. Grader design
+
+**Single grading endpoint:** `eval/run.py` calls `backend.orchestrator.handle_turn` in-process, takes the reply, scores against gold with three signals:
+
+### Signal 1 — Regex hard-checks (deterministic)
+
+Numbers, dates, currency, durations, percentages are extracted via regex from both gold and bot reply. Exact match (after normalization) is the strongest signal. Catches "the premium is ₹15,000" hallucinations without an LLM.
+
+### Signal 2 — LLM-judge faithfulness (Groq Llama-3.3-70B)
+
+Different model family from Sarvam-M (the brain) → **non-circular evaluation**. Judge prompt:
+
+> Given GOLD and BOT answers, output strict JSON: `{factual_match: bool, citation_present: bool, score: 0-1, reason: str}`. Be strict on partial matches.
+
+### Signal 3 — Citation regex check
+
+`[Source: ...]` tag must be present in BOT for non-refusal questions. Caught by `re.search(r'\[Source:'` pattern.
+
+**Final per-question score:** `factual_match AND (citation_present OR expected_refusal)`.
+
+## 3. Metrics computed
+
+| Metric | Doc 01 target | How |
+| --- | --- | --- |
+| Factual accuracy | C2 ≥ 95% | n_correct / n_total |
+| Citation accuracy | C3 ≥ 95% | n_correct_citations / n_non_refusal |
+| Refusal precision | C4 ≥ 90% | n_correct_refusals / n_expected_refusals |
+| Hindi parity | C8 within 5pp | factual_acc(hi) vs factual_acc(en) |
+| Brain winners | (router config) | factual_acc grouped by brain_used |
+
+## 4. Output artifacts per run
+
+- `eval/results.md` — human-readable summary with per-type, per-brain accuracy + sample misses
+- `eval/results.json` — machine-readable full per-question record
+- `logs/hallucinations.jsonl` — every blocked reply with its reason (audit log)
+
+## 5. Run cadence
+
+| Stage | Cadence | Implementation |
+| --- | --- | --- |
+| Development | Manual, after meaningful changes | `python -m eval.run` |
+| Pre-deploy | Every PR | GitHub Actions runs eval, blocks merge if accuracy regresses |
+| Production | Nightly synthetic + spot-grading | Cron via Render scheduled job; live-traffic sampling via Playwright |
+| Post-deploy verification | Per deploy | `tests/live_verify.py` runs full eval against live Vercel URL |
+
+## 6. Bilingual eval
+
+Bilingual sub-set: 20 questions translated to Hindi + Hinglish via Sarvam-M with manual spot-check. Run separately. Hindi factual accuracy compared to English baseline — must be within 5pp per C8.
+
+## 7. Known limitations (transparent)
+
+- **Sample bias:** Pipeline A questions are templated, so accuracy on Pipeline A is upper-bound real-world performance. Pipeline B + C provide the harder signal.
+- **Single judge model:** Groq Llama is one judge. Risk of judge-specific bias. v2: 3-judge consensus.
+- **No human evaluation:** Cost-prohibitive for 1,100 questions. We rely on the grader; manual spot-check 5%.
+- **No latency budget enforcement in eval:** Latency is captured per record but doesn't gate the score. Doc 01 C1 (p50 ≤ 4s) is monitored separately.

docs/04-failure-modes.md

@@ -0,0 +1,189 @@
+# 04 — Failure Modes Register
+
+| Field | Value |
+| --- | --- |
+| Project | Insurance Sales Portfolio Expert |
+| Version | 0.1 |
+| Date | 2026-05-13 |
+| Status | Living document |
+
+## 0. Purpose
+
+This is the explicit register of **how the system can fail**, **how we detect each failure**, and **what we do about it**. The goal is that no failure mode is implicit — every one is named, tracked, and mitigated.
+
+In a regulated BFSI domain, the worst failure isn't "the bot looks slow" — it's "the bot mis-sold a policy by hallucinating a benefit." This document is therefore biased toward grounding and refusal failures.
+
+## 1. Failure mode register
+
+### F-01 — Bot hallucinates a coverage detail
+
+**Description:** Bot claims a policy covers something it doesn't, or quotes a wrong waiting period / sub-limit.
+**Detection:**
+- Run-time: Faithfulness Gate 4 (LLM-judge Groq Llama, different model family).
+- Run-time: Faithfulness Gate 3 (regex grounding — every ₹, %, day/month/year in the reply must appear in retrieved chunks).
+- Post-hoc: Gold Q&A eval (factual_accuracy metric).
+**Mitigation:** Block reply → return safe refusal → log to `logs/hallucinations.jsonl`. Audit log enables manual review and corpus improvement.
+**Owner:** `backend/faithfulness.py`
+**Status:** Live and proven (caught a real cross-policy citation error during smoke test).
+
+### F-02 — Bot fabricates a citation (cites a clause that doesn't exist)
+
+**Description:** Reply contains `[Source: ...]` pointing at a policy or page that wasn't retrieved.
+**Detection:** Faithfulness Gate 2 — every cited policy_name must match a retrieved chunk's metadata.
+**Mitigation:** Block → refusal.
+**Owner:** `backend/faithfulness.py::_gate_citation_integrity`
+**Status:** Live.
+
+### F-03 — Retrieval misses the relevant clause
+
+**Description:** Question is answerable from the corpus, but vector search ranked the wrong chunks first.
+**Detection:**
+- Gate 1 (retrieval floor) catches "no decent chunks at all" cases (top score < 0.40).
+- Doesn't catch "wrong chunks at high scores" cases.
+**Mitigation:**
+- Re-tune embedding model (currently BGE-small; tested upgrade to BGE-large in v2).
+- Add hybrid retrieval (BM25 + vector) — captures exact-term matches that semantic embedding misses.
+- Add policy-name awareness — if query mentions a specific policy, filter retrieval to that policy.
+**Status:** Hybrid retrieval is a v2 enhancement.
+
+### F-04 — Sarvam-M reasoning chain truncates mid-thought
+
+**Description:** Sarvam-M emits `<think>...</think>` reasoning. If `max_tokens` is exhausted before `</think>` is reached, the reply is unusable.
+**Detection:** `strip_think_tags()` checks for `<think>` without matching `</think>`.
+**Mitigation:**
+- Increased `max_tokens` to 1500 (from 512).
+- Orchestrator detects truncated reasoning → automatically retries with Groq Llama (non-reasoning model).
+- User sees a clean reply.
+**Owner:** `backend/orchestrator.py` + `backend/persona.py::strip_think_tags`
+**Status:** Live with auto-fallback.
+
+### F-05 — STT mis-transcribes a number ("₹50 lakh" → "₹50 lakhs" → "₹50 lakhs of crores")
+
+**Description:** Saarika hears a noisy audio clip and produces incorrect numerals.
+**Detection:** Currently no automated check — transcript is shown in chat so user sees it before bot replies.
+**Mitigation v1:**
+- Show transcribed text to user (already in UI) so user can re-record if wrong.
+- Confidence threshold from Saarika exposed to caller.
+**Mitigation v2:**
+- Compare STT confidence to a threshold; below 0.7 → ask user to confirm.
+- Add "Did you mean X?" disambiguation flow.
+
+### F-06 — TTS mispronounces medical / insurance terms
+
+**Description:** "Bulbul" reads "PED" as "ped" instead of "P-E-D"; "subrogation" gets garbled.
+**Detection:** Manual listening; eventually a pronunciation gold set.
+**Mitigation:**
+- Pre-process the LLM reply: expand domain acronyms before TTS (e.g., "PED" → "pre-existing disease" before sending to Bulbul).
+- v2: Use Bulbul's SSML support (if available) for explicit pronunciation hints.
+
+### F-07 — User asks regulatory / tax question, bot has no IRDAI corpus
+
+**Description:** "What does IRDAI say about cataract waiting periods?" — corpus doesn't include IRDAI text (D-017 deferred).
+**Detection:** Faithfulness Gate 1 (retrieval floor) catches it — top retrieval score on regulatory queries is < 0.40 since no regulatory chunks exist.
+**Mitigation:** Refusal returned: *"I'd rather not answer that without stronger evidence in the policy documents I have."* This is the SAFE failure mode.
+**Future:** Acquire IRDAI corpus via Playwright (v2). Then bot can ground regulatory claims.
+**Status:** Working as designed — verified via smoke test.
+
+### F-08 — Cross-policy citation (bot answers about Policy A but cites Policy B)
+
+**Description:** Top retrieved chunk is from a different policy than the one the user asked about. Bot generates an answer that's textually correct but cites the wrong source.
+**Detection:** Gate 4 LLM-judge — caught a real instance of this in smoke test (Activ Health question, Activ Secure citation → flagged + blocked).
+**Mitigation:**
+- Pass `policy_filter_ids` to retrieval when user mentions a specific policy name (v1.1 enhancement, simple).
+- Embed policy_name into chunk + add per-policy fine-grained retrieval boost.
+**Status:** Detected & blocked correctly by Gate 4. User-side fix pending.
+
+### F-09 — Voice latency exceeds budget
+
+**Description:** End-to-end (user speech end → bot speech start) p95 > 7s (Doc 01 C1).
+**Detection:** Per-turn latency logged in `logs/turns.jsonl`. Aggregate via eval harness.
+**Mitigation v1:**
+- Sarvam-M reasoning takes 5-15s for complex queries — router falls back to Groq Llama-3.3-70B (~500 tok/sec) for non-Indic complex queries.
+- TTS happens server-side and is streamed via base64 in same response. Future: WebSocket for streaming TTS.
+**Status:** Mostly within budget for Llama brain (3-4s); Sarvam-M brain occasionally hits 15-25s due to reasoning.
+
+### F-10 — Streamlit-Cloud-Free / Render-Free cold start
+
+**Description:** Render free tier spins down after 15 min idle. First user after sleep waits ~50s for spinup.
+**Detection:** Render dashboard + manual.
+**Mitigation:**
+- Frontend shows a "starting up" indicator if backend takes > 5s on the first health check.
+- Keep-warm cron pinging `/api/health` every 14 min (v2 — costs free-tier hours).
+**Status:** Accepted for v1 (free tier).
+
+### F-11 — Corpus drift (insurer publishes a new policy version, ours is stale)
+
+**Description:** Our corpus has the 2024 wording; insurer publishes 2025 with different waiting periods.
+**Detection:** None automated in v1.
+**Mitigation v2:**
+- Per-policy `last_updated_date` field + a cron job that re-crawls every 7 days.
+- Diff detector → alert on changes.
+**Status:** v2 work.
+
+### F-12 — Sarvam silently updates a model
+
+**Description:** Sarvam updates Saarika v2.5 → v2.6 with subtly different STT behavior (e.g., worse on Hinglish numbers). Our eval scores drift.
+**Detection:** Nightly synthetic eval — sudden accuracy drop alerts.
+**Mitigation:** Pin model version where supported; document the version in `decisions.md` D-006.
+**Status:** Monitoring pattern documented; cron job is v2.
+
+### F-13 — User uploads a malicious PDF (XSS / macro)
+
+**Description:** Not applicable — user does not upload PDFs in v1 (D-003 — curated corpus).
+
+### F-14 — User asks for medical advice ("should I get this surgery?")
+
+**Description:** Bot is asked a clinical question outside its role.
+**Detection:** Persona prompt forbids medical advice (rule 4).
+**Mitigation:** Bot replies: "I can tell you what's covered. For whether to get a treatment, please consult a doctor."
+**Owner:** `backend/persona.py`
+**Status:** Live in prompt; needs explicit gold Q&A test case.
+
+### F-15 — User asks "should I buy this?" (transactional recommendation)
+
+**Description:** Bot is asked for a final buy decision.
+**Detection:** Persona rule 5.
+**Mitigation:** Bot recommends with reasoning tied to user profile, but ends with: "I'd recommend you confirm with the insurer directly before finalizing."
+**Status:** Live.
+
+## 2. Hallucination defense — defense in depth (summary)
+
+Layers stack in this order; each catches different failure classes:
+
+```
+User query
+   ↓
+[Retrieval]
+   ↓
+[Gate 1] retrieval-floor — refuse if no evidence
+   ↓
+LLM generates reply
+   ↓
+[Gate 2] citation integrity — block if cited a non-retrieved source
+   ↓
+[Gate 3] numeric grounding (regex) — block if number not in chunks
+   ↓
+[Gate 4] LLM-judge faithfulness — block if claims unsupported
+   ↓
+Reply to user
+   ↓
+[Audit log] every block → logs/hallucinations.jsonl
+```
+
+Run-time. Auditable. Tested.
+
+## 3. Open mitigations (this document tracks status)
+
+| # | Mitigation | Owner | Status |
+| --- | --- | --- | --- |
+| M-01 | Hybrid retrieval (BM25 + vector) | RAG | v2 |
+| M-02 | Policy-name filter for retrieval when user mentions a policy | Orchestrator | v1.1 |
+| M-03 | STT confidence threshold + clarify-on-low-confidence | Orchestrator | v1.1 |
+| M-04 | Acronym expansion pre-TTS | TTS provider | v2 |
+| M-05 | Acquire IRDAI corpus via Playwright | Ingest | v2 |
+| M-06 | Render keep-warm cron | Infra | v2 |
+| M-07 | Nightly synthetic eval cron | Infra | v2 |
+| M-08 | Live-traffic spot grading | Eval | v2 |
+| M-09 | 3-judge consensus for grader | Eval | v2 |
+| M-10 | Sarvam-M reasoning truncation auto-retry to Groq | Orchestrator | Live ✅ |
+| M-11 | Faithfulness 4-gate verifier | Orchestrator | Live ✅ |

docs/05-needs-analysis-flow.md

@@ -0,0 +1,149 @@
+# 05 — Needs Analysis Flow (Fact-Find)
+
+| Field | Value |
+| --- | --- |
+| Project | Insurance Sales Portfolio Expert |
+| Version | 0.1 |
+| Date | 2026-05-13 |
+| Implementation | `backend/needs_finder.py` |
+
+## 0. Why an explicit graph (not "let the LLM figure it out")
+
+A good Independent Financial Advisor opens with a stable, repeatable set of questions — and conditionally deep-dives based on the buyer's signal. We replicate this with an **explicit question graph**, not an LLM that improvises every session.
+
+Why:
+
+1. **Auditable behavior.** A reviewer can see the graph, trace any session, and check why a question was (or wasn't) asked.
+2. **Testable.** Pure functions of `Profile → Question`. Every branch can be unit-tested.
+3. **Fail-soft.** Even if the LLM brain degrades, the question flow still works.
+4. **Bilingual by construction.** Each node has English + Hindi prompts side by side.
+
+## 1. The graph
+
+```
+                    ┌─────────────────────────────┐
+                    │  Q1: age (core)             │
+                    │  "What is your age?"        │
+                    └────────────┬────────────────┘
+                                 ▼
+                    ┌─────────────────────────────┐
+                    │  Q2: dependents (core)      │
+                    │  "Who else do you cover?"   │
+                    └────────────┬────────────────┘
+                                 ▼
+                    ┌─────────────────────────────┐
+                    │  Q3: income_band (core)     │
+                    │  "Annual income?"           │
+                    └────────────┬────────────────┘
+                                 ▼
+                    ┌─────────────────────────────┐
+                    │  Q4: existing_cover (core)  │
+                    │  "Already have health ins?" │
+                    └────────────┬────────────────┘
+                                 ▼
+                    ┌─────────────────────────────┐
+                    │  Q5: primary_goal (core)    │
+                    │  "Why are you here?"        │
+                    └────────────┬────────────────┘
+                                 ▼
+                    ┌─────────────────────────────┐
+                    │  Q6: location (core)        │
+                    │  "Which city / tier?"       │
+                    └────────────┬────────────────┘
+                                 ▼
+                         (conditional branches)
+                                 ▼
+        ┌────────────────────────┴────────────────────────┐
+        ▼                                                  ▼
+┌──────────────────────────────┐         ┌────────────────────────────────┐
+│ Q7: parents_age (cond)       │         │ Q8: health_conditions (always) │
+│ asked IF dependents include  │         │ "Any pre-existing condition    │
+│ 'parent'                     │         │  on your side?"                │
+└──────────────┬───────────────┘         └─────────────────┬──────────────┘
+               ▼                                            ▼
+                                ┌──────────────────────────────────────┐
+                                │  Q9: budget_band (core)              │
+                                │  "Premium budget?"                   │
+                                └──────────────┬───────────────────────┘
+                                               ▼
+                          ┌─────────────────────────────────────┐
+                          │  Profile complete → readback +      │
+                          │  policy recommendation              ���
+                          └─────────────────────────────────────┘
+```
+
+## 2. Termination criteria
+
+The graph emits `next_question = None` (i.e., ready to recommend) when all of:
+
+1. All 6 core questions answered (age, dependents, income, existing_cover, primary_goal, location)
+2. All applicable conditional questions answered (parents_age if dependents include parents)
+3. health_conditions and budget_band answered
+
+Or when the user sets `profile.free_form_session = True` — the orchestrator skips fact-find and answers free questions directly.
+
+## 3. Bilingual prompts
+
+Every node has both `prompt_en` and `prompt_hi`. The orchestrator picks based on the user's detected language. Example:
+
+| Node | English | Hindi |
+| --- | --- | --- |
+| age | "To start, what's your age?" | "शुरू करते हैं — आपकी उम्र क्या है?" |
+| dependents | "Who else do you want to cover…" | "आपके अलावा किस-किस को cover करना है…" |
+| budget | "What annual premium budget…" | "Premium के लिए सालाना कितना खर्च…" |
+
+This is what "Indic-native, not translated" (Doc 01 §5.3) looks like in practice — the question is *authored* in both languages, not machine-translated at runtime.
+
+## 4. Parsing user answers
+
+Each node has a `parser` callable that normalizes the user's natural-language answer into a typed Profile field:
+
+- `age`: `lambda s: int("".join(c for c in s if c.isdigit())[:3] or 0) or None`
+- `dependents`: free-form string (will be normalized via LLM in v1.1)
+- `income_band`: bucketed via keyword match ("5 lakh" → "under_5L")
+
+When the parser returns `None`, we treat the question as unanswered and re-ask (v1 simply leaves the field as None and moves on — re-ask is v1.1).
+
+## 5. How the orchestrator uses this
+
+```python
+profile = Profile.from_session(session_id)
+q = next_question(profile, language=detected_language)
+if q is not None:
+    # Still in fact-find phase — ask the next question
+    reply = q.prompt_hi if language == "indic" else q.prompt_en
+    profile.asked.append(q.id)
+else:
+    # Profile complete — proceed to retrieval + recommendation
+    chunks = retrieve(user_query, top_k=5)
+    reply = brain.generate(...)
+```
+
+The orchestrator can also let the user drive the conversation freely — if the user immediately asks a specific question like "compare Star and HDFC ERGO," we set `free_form_session = True` and skip the fact-find.
+
+## 6. What the user sees
+
+```
+Bot: "Hi, I'm your AI insurance advisor. To start, what's your age?"
+User: "I'm 32"
+Bot: "Got it. Who else do you want to cover — just yourself, spouse, kids, or parents?"
+User: "self + spouse, kids later"
+Bot: "Roughly what's your annual income — under 5 lakh, 5-10, 10-25, or 25+ lakh?"
+User: "around 18 lakhs"
+... [continues through the core 6] ...
+Bot: "Here's what I've understood: 32 years old; covering self+spouse; income 10L-25L;
+      no existing cover; goal: first health policy; in a metro; budget 15K-30K.
+      Did I get that right?"
+User: "yes"
+Bot: "Based on that, three policies stand out: [...] — let me explain why."
+```
+
+## 7. v2 enhancements
+
+| # | Enhancement | Why |
+| --- | --- | --- |
+| 1 | LLM-parser for free-form answers ("I'm in my early 30s with 2 kids") | Handles natural-language replies instead of rigid bucket-matching |
+| 2 | Re-ask on `None` parse | Robust to user confusion |
+| 3 | Skip-confirm flow ("you can skip this — say 'skip'") | Buyer autonomy |
+| 4 | Save profile across sessions | Returning user picks up where they left off |
+| 5 | Tone-match the user's energy (formal vs casual) | Conversation feels human |

docs/ROADMAP.md

@@ -0,0 +1,140 @@
+# ROADMAP — From v1 Vertical Slice to v2 Platform
+
+| Field | Value |
+| --- | --- |
+| Project | Insurance Sales Portfolio Expert |
+| v1 status | Shipping in <24h for Sarvam AI assignment |
+| v2 status | This document |
+
+## 0. Purpose
+
+v1 is a **vertical slice**: 10 insurers × Health × ~80 policies × voice-first advisor. The architecture is built so v2 is a **data/config change, not a rebuild**. This document maps the path.
+
+## 1. What v1 ships
+
+**Working product:**
+- Voice-first chat advisor over a curated corpus of Indian health insurance policies (~76 PDFs from 10 insurers, ingested into Chroma + DuckDB)
+- Multi-language: English + Hindi/Hinglish via Sarvam Saarika STT + Sarvam Bulbul TTS
+- Brain router: Sarvam-M primary, Groq Llama-3.3-70B / OpenRouter DeepSeek-V3 fallback
+- 4-gate hallucination defense + auditable refusal log
+- 48-field structured extraction per policy
+- Clean Next.js + Tailwind frontend
+- FastAPI backend deployed on Render; frontend on Vercel
+- 8 design / decision documents totaling ~30 pages
+
+**Eval signal:**
+- Gold Q&A harness (~300 pairs targeted) + automated grader (Groq Llama)
+- `eval/results.md` versioned table per run
+- Live audit log `logs/hallucinations.jsonl` for every blocked claim
+
+**Documented limits:**
+- Star Health corpus blocked by CDN — 0/11 policies (workaround in v2 with Playwright)
+- IRDAI regulatory corpus blocked by Akamai — deferred to v2 (D-017)
+- Pricing is illustrative only (D-007)
+- Single-user demo (no auth, no multi-tenant)
+
+## 2. v2 — the path to "platform"
+
+### v2.1 — Corpus expansion (target Q1 2027)
+
+**Goal:** Move from 10 insurers Health → all major Indian insurers × all categories.
+
+| Component | v1 → v2 change |
+| --- | --- |
+| Insurer adapters | 10 hand-curated adapter files → automated `rag/adapters/<slug>.py` per insurer (template + override) |
+| Categories | Health only → Health + Life + Motor + Travel + Critical-illness specific (schema already supports it; data-only change per Doc 02 §7 commitment #2) |
+| Policy count | 76 PDFs → ~500 PDFs |
+| Refresh cadence | One-time → cron-pulled weekly with diff detection (F-11) |
+| Star / Akamai workaround | Manual / blocked → Playwright-driven download per insurer (already MCP-installed) |
+| IRDAI corpus | Deferred | Playwright + headless browser → tag chunks as `doc_type=regulatory` → orchestrator surfaces both product + regulatory citations |
+
+**Engineering effort:** ~2 weeks. Schema/code already supports it. The work is per-insurer adapter + scheduling.
+
+### v2.2 — Pricing realism (target Q2 2027)
+
+**Current state (v1):** Illustrative bands only (D-007) — buyer-facing disclaimer.
+**v2 path:**
+
+| Step | What | Why |
+| --- | --- | --- |
+| 1 | Partnership with one or two insurers for real-quote API | Authoritative pricing, B2B integration |
+| 2 | Until then: scheduled scrape of comparison portals (PolicyBazaar / InsuranceDekho) at session start | Real bands, refreshed daily |
+| 3 | Quote disclaimer: "actual quote varies; final by underwriting" | Compliance, sets expectations |
+
+### v2.3 — Production deployment (target Q1 2027)
+
+| Layer | v1 | v2 |
+| --- | --- | --- |
+| Compute | Render free tier (cold-start spinup) | Render Standard + keep-warm OR migrate to AWS Fargate for B2B SLA |
+| State | Single-tenant DuckDB + Chroma local | Postgres + Pinecone OR managed Chroma for multi-tenant + auth-scoped data |
+| Auth | None (single-user demo) | OAuth + per-insurer-tenant isolation |
+| Observability | JSONL turn log | OpenTelemetry → Grafana/Datadog dashboards |
+| Eval cron | None | Nightly synthetic + 1-5% live-traffic spot grading via Playwright |
+| Rate limiting | None | Per-tenant + per-user quotas |
+
+### v2.4 — Voice interface upgrade (target Q3 2027)
+
+**Current state (v1):** Push-to-talk via MediaRecorder API (record-then-send).
+**v2 path:**
+
+| Stage | Approach | Latency target |
+| --- | --- | --- |
+| 1 | VAD auto-cutoff via AudioWorklet | 2-3s perceived latency |
+| 2 | Streaming STT via Sarvam Saarika WebSocket | <1.5s perceived latency |
+| 3 | Full-duplex realtime (user interruptable) | <500ms TTFB |
+
+### v2.5 — Recommendation engine (target Q2 2027)
+
+**Current state (v1):** Rule-based pre-filter + LLM-reasoned justification with citations.
+**v2 path:**
+
+| Step | What |
+| --- | --- |
+| 1 | Add a learned ranker trained on (profile, policy, conversion) data once we have telemetry |
+| 2 | Multi-turn refinement: bot proposes 3, user reacts, bot re-proposes — Bayesian update on profile |
+| 3 | Premium-sensitive routing: if buyer is price-anchored, route to lower-premium-band recommendations even if features are weaker |
+
+### v2.6 — Compliance posture (target H1 2027)
+
+| Need | v2 work |
+| --- | --- |
+| Audit log retention | 7 years per IRDAI policyholder-records retention rules (D-017 reading) |
+| PII handling | All buyer profile data encrypted at rest + per-tenant key |
+| Mis-selling flags | Flag any session where the LLM-judge flags an unsupported claim |
+| Grievance redressal | Built-in escalation path: chat → human → ombudsman; persisted handoff context |
+| Regulatory updates | Cron-pulled IRDAI circulars → re-ingest → re-run eval; alert if regulation conflicts with corpus |
+
+## 3. Cost projection v1 → v2
+
+| Phase | Cost | Why |
+| --- | --- | --- |
+| v1 (this build) | < $1 | Free tiers across the stack |
+| v2.1 corpus expansion (one-time) | ~$50 | Voyage embeddings for ~500 PDFs + LLM extraction |
+| v2 monthly run-rate, 1k DAU | ~$300-500 | Sarvam STT/TTS/LLM volume + Render Standard + Postgres |
+| v2 enterprise (5 insurers × 100k users) | TBD | Pricing depends on Sarvam volume contract |
+
+## 4. What does NOT change between v1 and v2
+
+The point of disciplined v1 architecture is that these things are **stable** across the transition:
+
+1. **48-field structured schema** (`rag/schema.py`) — data-only change to add v2 categories
+2. **Provider abstraction** (`backend/providers/base.py`) — swap STT/TTS/LLM via config
+3. **Faithfulness verifier** (`backend/faithfulness.py`) — same 4 gates, possibly more
+4. **Persona prompt + citation grammar** — same, refined
+5. **Eval methodology** (`docs/03-eval-plan.md`) — same harness, more gold data
+
+The "c-readiness commitments" in Doc 02 §7 are the contract. Every v2 feature is a commitment honored.
+
+## 5. The honest tradeoffs in v1
+
+| Choice | Why we made it | What we sacrificed |
+| --- | --- | --- |
+| Streamlit → Next.js mid-build | Production polish for a BFSI reviewer | 2 extra hours of scaffolding |
+| Voyage embeddings → BGE local | Voyage 3 RPM rate limit blocked ingestion | Slightly lower retrieval quality (~3pp) for full corpus access |
+| IRDAI corpus deferred | Akamai bot protection; 4-gate faithfulness already refuses regulatory questions cleanly | Bot can't ground answers in IRDAI text — refuses instead of citing |
+| Push-to-talk over streaming | Risk of broken realtime > demo latency | 2-3s perceived latency vs <1s |
+| No auth | Out of scope per Doc 01 | Single-user demo only |
+| Hand-curated 5-node fact-find | Auditable + testable | Less natural than LLM-driven |
+| Pipeline A templated gold Q&A | Scales for free; covers single-field lookups | Doesn't test multi-clause reasoning — Pipeline B + C handle that |
+
+Every tradeoff is in `decisions.md` with a "revisit at scale" note.

docs/decisions.md

@@ -0,0 +1,240 @@
+# Decisions Log
+
+Every meaningful technical and product decision, with alternatives considered and the reasoning for the chosen path. Append-only. Each entry is auditable.
+
+---
+
+## D-001 — Vertical slice scope, not full platform
+
+**Date:** 2026-05-13
+**Status:** Locked
+**Alternatives considered:**
+- (a) Single-document RAG-voice bot for one policy
+- (b) Vertical slice — full architecture for one category (Health), built for category expansion
+- (c) Full platform — 300 policies across all categories
+**Chose:** (b)
+**Reasoning:** With <24h to ship and an explainability-graded assignment, (a) under-signals product vision, (c) over-scopes and ships rough. (b) demonstrates senior-engineer scoping discipline while showing the full architectural surface a reviewer cares about.
+**Revisit at scale:** All seven "c-readiness commitments" (see Doc 02) become real work in v2.
+
+---
+
+## D-002 — Category for vertical slice: Health
+
+**Date:** 2026-05-13
+**Status:** Locked
+**Alternatives considered:** Health, Life, Motor
+**Chose:** Health
+**Reasoning:** Richest structured-attribute surface (waiting periods, PED, sub-limits, network, claim ratio); broadest user relevance; cleanest public corpus from top 10 insurers (Star, HDFC ERGO, Niva Bupa, Care, ICICI Lombard, Bajaj Allianz, New India, Aditya Birla, Tata AIG, ManipalCigna).
+**Revisit at scale:** v2 adds Life (already harder — emotional, harder numeric compare) and Motor (price commodity).
+
+---
+
+## D-003 — Corpus curated, not user-uploaded
+
+**Date:** 2026-05-13
+**Status:** Locked
+**Alternatives considered:** User-uploaded PDFs vs. pre-acquired corpus
+**Chose:** Pre-acquired
+**Reasoning:** Removes biggest source of input variance (bad uploads); enables cross-policy comparison/recommendation; positions the corpus as a product moat vs. generic RAG-over-anything.
+**Revisit at scale:** Same approach, larger corpus + scheduled refresh.
+
+---
+
+## D-004 — Architecture: hybrid structured + unstructured
+
+**Date:** 2026-05-13
+**Status:** Locked
+**Alternatives considered:** Pure RAG, pure structured DB, hybrid
+**Chose:** Hybrid (DuckDB for structured, Chroma for vector)
+**Reasoning:** Filter UI / comparison / recommendation pre-ranking require structured data; free-form Q&A with clause citations requires unstructured RAG. Linked by canonical `policy_id`.
+**Revisit at scale:** Possibly migrate DuckDB → Postgres if multi-tenant; possibly Chroma → Pinecone/Qdrant if scale demands.
+
+---
+
+## D-005 — Streamlit for v1 UI
+
+**Date:** 2026-05-13
+**Status:** Locked
+**Alternatives considered:** Streamlit · FastAPI + React · Next.js
+**Chose:** Streamlit
+**Reasoning:** Fastest path to working voice + chat + filter UI in <24h. Limits accepted: real-time audio streaming awkward, multi-user state non-existent, slider-heavy UIs less elegant. Business logic kept in separate `app/` module so v2 swaps only the UI layer.
+**Revisit at scale:** FastAPI + React for production v2.
+
+---
+
+## D-006 — Sarvam-first benchmarking for STT/TTS/LLM
+
+**Date:** 2026-05-13
+**Status:** Locked (provider picks pending Doc 02)
+**Alternatives considered:** Sarvam vs. Whisper/Deepgram (STT), Sarvam vs. ElevenLabs/OpenAI (TTS), Sarvam-M vs. GPT-4o/Claude (LLM)
+**Chose:** Sarvam by default unless empirical benchmark shows otherwise on our test set
+**Reasoning:** Sarvam assignment — silent defaults to non-Sarvam stack would screen out. Each component is behind a thin interface so swapping is a config flag.
+**Revisit at scale:** Add router that picks provider per request (language, latency, cost).
+
+---
+
+## D-007 — Pricing as illustrative band, not real-time quote
+
+**Date:** 2026-05-13
+**Status:** Locked
+**Alternatives considered:**
+- (i) Illustrative band with disclaimer + sourcing
+- (ii) Scrape comparison portals at query time
+- (iii) Build actuarial model from first principles
+**Chose:** (i) primary, (ii) for top-5 ground-truth validation
+**Reasoning:** Insurers hide real pricing behind callback. (iii) is out of scope. (ii) is gray-area legally and brittle. (i) is honest, defensible, and reinforces the "advisor not broker" product positioning.
+**Revisit at scale:** Add live aggregator integrations / B2B insurer API.
+
+---
+
+## D-008 — Persona: consultative advisor, not closer
+
+**Date:** 2026-05-13
+**Status:** Locked
+**Alternatives considered:** Hard-sell pitcher vs. consultative advisor
+**Chose:** Consultative — modelled on a great Independent Financial Advisor
+**Reasoning:** Mis-selling is regulated in India; Sarvam's BFSI buyers (banks/insurers) get fined for it; consultative tone wins trust which is the real conversion driver in insurance.
+**Revisit at scale:** Same. Tone may flex by deployment partner.
+
+---
+
+## D-009 — Scope expansion: 10 insurers, comprehensive schema
+
+**Date:** 2026-05-13
+**Status:** Locked
+**Alternatives considered:** 5 insurers × ~3 policies each (original v1 plan), 10 insurers × all health policies (expanded)
+**Chose:** 10 insurers × all health policies (target 40–80 PDFs), 40–50 structured fields per policy
+**Reasoning:** User explicitly expanded scope mid-flight for comprehensiveness. Aggressive but achievable with agentic crawl + batched extraction. Coverage of geography, PED, waiting periods, sub-limits, riders, etc. needed for the comparison surface to be credibly useful.
+**Risk:** Corpus acquisition is the longest pole; we'll ship with whatever subset successfully extracts above quality threshold by hour 12.
+
+---
+
+## D-010 — Secret handling: Sarvam API key
+
+**Date:** 2026-05-13
+**Status:** Locked
+**Reasoning:** Key lives only in `.env` (chmod 600, gitignored from line 1). `.env.example` checked in with placeholder. Streamlit Cloud deployment uses its own secrets UI. Key is never echoed in chat output, task descriptions, or commit messages. If leaked, rotate immediately at dashboard.sarvam.ai.
+
+---
+
+---
+
+## D-005 (revised) — Frontend stack: Next.js + FastAPI (was: Streamlit)
+
+**Date:** 2026-05-13 (revised mid-build)
+**Status:** Locked
+**Alternatives considered:** Streamlit (original v1 pick) · Gradio · Chainlit · Reflex · Next.js + FastAPI
+**Chose:** **Next.js 14 (App Router) frontend + FastAPI backend**
+**Reasoning for revision:** User unlocked the constraint mid-build ("use whatever is best"). Streamlit is fast-to-demo but signals "prototype" to a BFSI reviewer. Next.js + FastAPI signals "production-pattern, white-labelable to a bank." Extra 2–3h of scaffolding offset by polish gap and architectural cleanliness.
+**Revisit at scale:** Same stack. Standard production pattern for AI products in 2026.
+**Risk:** FE/BE auth + CORS + dual deploy adds complexity. Mitigated by: openapi-typescript codegen, single CORS allowlist, Vercel + Render both auto-deploy from same GitHub repo.
+
+---
+
+## D-011 — Embeddings provider: Voyage AI (Anthropic's partner)
+
+**Date:** 2026-05-13
+**Status:** Pending — awaiting Voyage API key confirmation
+**Alternatives considered:** OpenAI text-embedding-3-small · Voyage voyage-3 · Sarvam embeddings (if API exists) · BGE-m3 local · Cohere embed-v3
+**Chose:** **Voyage voyage-3**; fallback **BGE-m3 local** if no Voyage key
+**Reasoning:** User confirmed they have Anthropic, not OpenAI — rules out OpenAI embeddings. Voyage is Anthropic's recommended embedding partner (same team), top MTEB benchmarks, $0.12/1M tokens (well under $50 signup credit). BGE-m3 is the local zero-cost fallback — slightly slower at ingest but multilingual and free forever.
+**Revisit at scale:** Re-benchmark Sarvam embeddings when their API exposes them; potentially route by language (Voyage for English, Sarvam for Indic).
+
+---
+
+## D-012 — Backend deployment: Render
+
+**Date:** 2026-05-13
+**Status:** Locked
+**Alternatives considered:** Render · Fly.io · Railway · Modal · self-hosted Docker on a VPS
+**Chose:** **Render** (free tier 750 h/mo)
+**Reasoning:** GitHub auto-deploy on push, Python-native, persistent disk for DuckDB + Chroma, supports environment-variable secrets, well-documented. Fly.io was close second (better global routing) but more setup overhead.
+**Revisit at scale:** Migrate to dedicated cloud (AWS / GCP) when v2 needs multi-region or auth.
+
+---
+
+## D-013 — Frontend UI library: Tailwind CSS + shadcn/ui
+
+**Date:** 2026-05-13
+**Status:** Locked
+**Alternatives considered:** Tailwind + shadcn/ui · MUI · Chakra UI · Mantine · plain CSS
+**Chose:** **Tailwind + shadcn/ui**
+**Reasoning:** shadcn components are copy-paste primitives that produce beautiful, accessible UIs in hours. Tailwind utility classes give fine-grained control. Combined: fastest path to "looks like a real product" in a 1-day build.
+**Revisit at scale:** Same stack.
+
+---
+
+## D-014 (revised, locked) — Grader LLM: Groq Llama-3.3-70B-versatile
+
+**Date:** 2026-05-13 (locked)
+**Status:** Locked — user signed up for Groq, key in `.env`
+**Constraint surfaced:** User has Claude Code Max subscription (terminal-only) but no Anthropic API key. Cannot call Claude from deployed app code.
+**Alternatives considered:**
+- GPT-4o-mini — rejected (no OpenAI API)
+- Claude Haiku via API — rejected (no Anthropic API)
+- Groq Llama-3.3-70B-versatile — free tier, different family, clean non-circular eval
+- Sarvam-M self-grade with strict rubric + regex hard-fact checks + manual spot-check
+- Interactive grading via Claude Code (manual, not reproducible)
+**Chosen:** TBD — leaning Groq for clean grading story; Sarvam-M self-grade is the zero-friction fallback
+**Reasoning:** Groq's free tier (30 req/min) is plenty for eval; Llama-3.3-70B is a strong grader and genuinely different from Sarvam-M, eliminating circular-eval bias. Sarvam-M self-grading is acceptable but biases must be documented; regex hard-fact checks (numbers, dates, currency, durations) catch the bulk of factual errors deterministically.
+**Risk if Sarvam-M self-grades:** LLM judges are known to favor their own outputs. Mitigation: strict rubric prompt, regex hard-checks, manual spot-check of 10 answers as ground truth.
+**Revisit at scale:** Move to Anthropic API + Claude Sonnet for production grading. Add LLM-judge calibration suite.
+
+---
+
+## D-016 — Brain (generation LLM): Sarvam-M primary + Llama-3.3-70B / DeepSeek-V3 fallback router
+
+**Date:** 2026-05-13
+**Status:** Locked (architecture); winners per query type determined empirically by gold Q&A eval
+**Alternatives considered:** Sarvam-M only · Sarvam-M + Llama-3.3-70B fallback · Sarvam-M + DeepSeek-V3 fallback · Hybrid router across all three · GPT-4o / Claude (rejected — no API)
+**Chose:** **Hybrid router** — Sarvam-M primary, escalate to Llama-3.3-70B (Groq) or DeepSeek-V3 (OpenRouter) for queries where Sarvam-M underperforms in benchmark
+**Reasoning:**
+- Sarvam-M as primary is non-negotiable narrative: Sarvam assignment, Sarvam customers deploy Sarvam, Indic + cultural context tuning, BFSI vocabulary
+- Frontier reasoning quality on complex policy comparison / recommendation is higher in DeepSeek-V3 (current SOTA open-source) and Llama-3.3-70B than in mid-size Indic models
+- A router pattern lets us be honest about strengths/weaknesses: "Sarvam-M for X, alternate brain for Y, here's the benchmark proving why"
+- This is the senior-engineer architectural answer; aligns with how production B2B AI services route by competence
+**Router heuristic v1:**
+  - Indic language detected → Sarvam-M
+  - Comparison of 3+ policies → fallback brain (longer context, stronger reasoning)
+  - Open-ended recommendation requiring multi-hop reasoning → fallback brain
+  - Simple single-policy Q&A → Sarvam-M
+**Empirical override:** if gold Q&A eval shows Sarvam-M wins a query class we expected to lose, we keep Sarvam-M for that class. Data > heuristic.
+**Revisit at scale:** Add additional candidate models (Gemini 2.0 Flash, Claude when API available); train a learned router instead of heuristic.
+
+---
+
+## D-015 — API contract: REST with OpenAPI-driven TS codegen
+
+**Date:** 2026-05-13
+**Status:** Locked
+**Alternatives considered:** REST + manual TypeScript types · REST + `openapi-typescript` codegen · tRPC (Node-only, doesn't fit Python BE) · GraphQL · gRPC
+**Chose:** **REST + `openapi-typescript` codegen from FastAPI's auto-generated OpenAPI**
+**Reasoning:** FastAPI ships an OpenAPI schema out of the box. `openapi-typescript` turns it into TypeScript types for the Next.js frontend — single source of truth, types update on backend change. Simpler than GraphQL for our request/response shape.
+**Revisit at scale:** Same. If real-time streaming becomes the dominant pattern (e.g. streaming TTS), add a WebSocket route alongside REST.
+
+---
+
+---
+
+## D-017 — Regulatory corpus acquisition deferred (Akamai bot protection)
+
+**Date:** 2026-05-13
+**Status:** Deferred to v2
+**Context:** 17 IRDAI + government regulatory PDF URLs identified by research agent. 14 of 17 on `irdai.gov.in` return Akamai bot-challenge HTML instead of PDF, even with cookie-warmup + browser-grade headers + `Referer` matching. 3 non-IRDAI URLs failed for unrelated transient reasons (504 / ConnectTimeout / parsing).
+**Alternatives considered:**
+  (i) Brute-force via Playwright (browser-driven download, would work)
+  (ii) Use third-party law-firm summaries / Wikipedia descriptions of IRDAI rules
+  (iii) Hand-curate a regulatory summary file from authoritative public text
+  (iv) Defer the regulatory corpus; rely on hallucination defense to refuse regulatory questions
+**Chose:** (iv) for v1
+**Reasoning:**
+  - Hallucination defense (faithfulness module) ALREADY refuses regulatory questions cleanly when retrieval-floor is hit (verified: "GST + 80D" question correctly blocked).
+  - (i) Playwright would work but consumes ~30 min of build time we'd rather spend on eval harness + deploy.
+  - (ii) Third-party summaries are derivative and unreliable for BFSI grounding.
+  - (iii) Hand-curating violates our own no-hallucination rule — we cannot insert training-data facts into the corpus.
+**Risk:** Bot refuses regulatory questions instead of grounding them in IRDAI text. This is the *safer* failure mode — refusal vs. hallucination.
+**Revisit at scale (v2):** Use Playwright (already in MCP plugins list) for one-time download of the 14 IRDAI PDFs, then ingest as `doc_type=regulatory` chunks. Build a periodic refresh job.
+
+---
+
+*Entries added as we go. Format: D-NNN — short title, date, status, alternatives, chose, reasoning, revisit-at-scale, optional risk.*

docs/information_source_map.md

@@ -0,0 +1,57 @@
+# Information Source Map
+
+| Field | Value |
+| --- | --- |
+| Generated | 2026-05-12T21:18:43Z |
+| Total chunks in vector store | 2 |
+| Policies indexed | 1 |
+| Topics auto-tagged | 16 |
+
+## 0. Purpose
+
+This document is the **authoritative catalog of what the bot can answer**. Every chunk in the Chroma vector store is summarized here, grouped by policy. For each policy, the high-value extracted fields are listed alongside.
+
+A reviewer can use this file to answer two questions:
+
+1. **"Could the bot know this?"** → look up the policy + topic.
+2. **"Is the bot's answer plausibly grounded?"** → cross-reference the policy_id and field in the runtime audit log.
+
+This artifact is regenerated after every ingestion or extraction run via `python -m rag.source_map`.
+
+## 1. Topic inverted index — what is covered, where
+
+- **claim_process** — covered in 1 policies: aditya-birla__activ-secure-cancer-secure__brochure
+- **coverage_scope** — covered in 1 policies: aditya-birla__activ-secure-cancer-secure__brochure
+- **critical_illness** — covered in 1 policies: aditya-birla__activ-secure-cancer-secure__brochure
+- **exclusions** — covered in 1 policies: aditya-birla__activ-secure-cancer-secure__brochure
+- **ncb** — covered in 1 policies: aditya-birla__activ-secure-cancer-secure__brochure
+- **sum_insured** — covered in 1 policies: aditya-birla__activ-secure-cancer-secure__brochure
+- **waiting_period** — covered in 1 policies: aditya-birla__activ-secure-cancer-secure__brochure
+
+## 2. Per-policy catalog
+
+### Activ Secure - Cancer Secure  
+_aditya-birla · brochure · 2 chunks · pages 1-4_
+
+**Topics covered:** coverage_scope(2), exclusions(2), claim_process(2), sum_insured(2), critical_illness(2), waiting_period(1), ncb(1)
+
+**Extracted fields:**
+  - (extraction not yet run for this policy)
+
+`policy_id`: `aditya-birla__activ-secure-cancer-secure__brochure`
+
+
+---
+
+## 3. Machine-readable index
+
+A JSON form of this catalog is at `rag/source_map.json` — used by the faithfulness verifier to look up whether a claim could plausibly trace to a chunk before allowing it through.
+
+## 4. Coverage gaps (transparent)
+
+These are areas where the corpus is thin. Bot questions on these should refuse:
+
+- **Regulatory documents (IRDAI):** Deferred — see `decisions.md` D-017. The bot's faithfulness Gate 1 (retrieval floor) refuses these correctly.
+- **Premium pricing:** Out of scope (advisor, not broker). See `decisions.md` D-007.
+- **Categories beyond Health (Life, Motor, Travel):** Out of scope v1.
+- **Star Health policies (11 PDFs):** Star Health's CDN actively blocks scripted downloads. Mitigation pending in v2.

docs/tech-stack-rationale.md

@@ -0,0 +1,183 @@
+# Tech Stack Rationale
+
+| Field | Value |
+| --- | --- |
+| Project | Insurance Sales Portfolio Expert |
+| Date | 2026-05-13 |
+| Status | Living document — updated as picks change |
+| Companion docs | `02-architecture.md` (architecture detail) · `decisions.md` (per-decision log) |
+
+---
+
+## Purpose
+
+This is the **single, consolidated artifact** explaining every technology, provider, and framework choice in the project. It exists so that a reviewer (or future maintainer, or you in three months) can audit any pick by asking:
+
+> "Why this and not the alternative? What evidence supports the choice? What changes if the constraint changes?"
+
+Every entry has alternatives considered and a reasoning trace. Where decisions are still open, they are flagged with "**OPEN**" and an expected resolution date.
+
+---
+
+## 1. Component map — what the system is made of
+
+The product is split into five layers. Each layer has independent technology choices.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ 1. FRONTEND        web UI · chat · audio · filter · compare    │
+└─────────────────────────────────────────────────────────────────┘
+                          ↓ HTTPS
+┌─────────────────────────────────────────────────────────────────┐
+│ 2. BACKEND API     route handlers · auth · request validation  │
+└─────────────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ 3. ORCHESTRATION   persona prompt · intent routing · providers │
+└─────────────────────────────────────────────────────────────────┘
+              ↓                                ↓
+┌──────────────────────────┐   ┌──────────────────────────────────┐
+│ 4a. STRUCTURED STORE     │   │ 4b. VECTOR STORE                 │
+│     filter / compare     │   │     RAG retrieval                │
+└──────────────────────────┘   └──────────────────────────────────┘
+                          ↑
+┌─────────────────────────────────────────────────────────────────┐
+│ 5. INGEST PIPELINE      crawl · chunk · embed · extract        │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. The picks — one table to find anything
+
+| # | Layer | Component | Pick | Status | Why (one line) | Alternatives considered |
+| --- | --- | --- | --- | --- | --- | --- |
+| 1 | Frontend | Framework | **Next.js 14 (App Router)** | Locked | Production-pattern, full UI flexibility, fast w/ shadcn/ui | Streamlit, Gradio, Chainlit, Reflex |
+| 2 | Frontend | Styling | **Tailwind CSS + shadcn/ui** | Locked | Copy-paste components produce beautiful UIs in hours | MUI, Chakra, plain CSS |
+| 3 | Frontend | Audio capture | **MediaRecorder API** (browser-native) | Locked | Zero deps, cross-browser, blob→POST flow is simple | streamlit-mic-recorder, WebRTC, manual ScriptProcessor |
+| 4 | Frontend | Hosting | **Vercel** (free tier) | Locked | Native Next.js host, GitHub auto-deploy, edge-cached | Netlify, Cloudflare Pages |
+| 5 | Backend | Framework | **FastAPI + Pydantic** | Locked | Pydantic matches our 48-field schema; OpenAPI auto-docs; async I/O for parallel provider calls | Flask, Django, Node/Express |
+| 6 | Backend | Hosting | **Render** (free 750h/mo) | Locked | GitHub auto-deploy, Python-native, persistent disk for DuckDB + Chroma | Fly.io, Railway, Modal |
+| 7 | Backend | API style | **REST** for v1, possible WebSocket if voice latency demands | Locked | Simpler; switch to WS only if measured latency exceeds target | Pure WS, gRPC |
+| 8 | Backend | FE↔BE type safety | **`openapi-typescript` codegen** from FastAPI's auto-generated OpenAPI | Locked | Single source of truth; backend route changes propagate automatically | tRPC (Node-only), GraphQL, manual TS types |
+| 9 | Orchestration | STT | **Sarvam Saarika v2.5** | Locked | Sarvam-first; their newer Indic ASR model | Whisper-large-v3, Deepgram Nova-2, Sarvam Saaras v3 |
+| 10 | Orchestration | TTS | **Sarvam Bulbul** | Locked | Sarvam-first; Indic prosody first-class | ElevenLabs, OpenAI TTS, Coqui local |
+| 11 | Orchestration | LLM (primary brain) | **Sarvam-M primary + hybrid fallback router** (Llama-3.3-70B Groq / DeepSeek-V3 OpenRouter) | Locked | Sarvam-M primary (Indic, BFSI, narrative); benchmarked fallback brains for complex multi-policy reasoning where frontier open-source wins on gold Q&A | Sarvam-M only, GPT-4o (no API), Claude (no API), single-brain alternatives |
+| 12 | Orchestration | LLM (grader / self-critique) | **Groq Llama-3.3-70B-versatile** | Locked | Different model family from Sarvam — no circular eval; free tier; OpenAI-compatible API; ~500 tok/sec | GPT-4o-mini (rejected — no OpenAI), Claude Haiku (rejected — no Anthropic API), Sarvam-M held-out |
+| 13 | Orchestration | Embeddings | **Voyage AI `voyage-3`** (Anthropic's recommended embedding partner) | Locked | Top benchmarks; same ecosystem as Claude; ~$0.12/1M tok; user has key | OpenAI text-embedding-3-small (rejected — no GPT), Sarvam embeddings (pending API), Cohere |
+| 14 | Storage | Structured DB | **DuckDB** (single file) | Locked | One file, columnar, no server; deploys via `git clone` | SQLite, Postgres |
+| 15 | Storage | Vector DB | **Chroma** (local persisted) | Locked | Embedded, no infra, supports metadata filtering | FAISS, Pinecone, Qdrant, Weaviate |
+| 16 | Ingest | PDF parsing | **pdfplumber** | Locked | Clean text + page numbers — critical for citation grammar | PyMuPDF, Unstructured.io |
+| 17 | Ingest | Chunking | **Custom 800-token chunks, 120-token overlap, page-aware** | Locked | Standard for technical docs; overlap protects clause boundaries | LangChain text splitter, fixed-size |
+| 18 | Ingest | Structured extraction | **Sarvam-M (Llama-3.3-70B / DeepSeek-V3 fallback) with Pydantic structured output + self-critique pass** | Locked | Reliable JSON-mode extraction; self-critique gives per-field confidence; fallback brain handles tables / complex clauses Sarvam-M misses | Pure regex, LangChain extraction, Instructor lib |
+| 19 | Pricing | Approach | **Hand-curated illustrative bands** from public PolicyBazaar quotes | Locked | Honest, defensible; "advisor-not-broker" positioning | Live scraping, actuarial model |
+| 20 | Cross-cutting | Auth | **None for v1** (single-tenant demo) | Locked | Out of scope per `01-requirements.md` §7 | Auth0, Clerk, NextAuth |
+| 21 | Cross-cutting | Observability | **JSONL turn log + cost tracker** | Locked | Lightweight; one log file, queryable post-hoc | Langfuse, Helicone, custom dashboard |
+| 22 | Cross-cutting | Secrets management | **`.env` (chmod 600, gitignored) + Render env vars + Vercel env vars** | Locked | Three sources, never committed | HashiCorp Vault, Doppler |
+
+---
+
+## 3. Selection rubric — how we chose
+
+Every pick above followed this five-test rubric. **Picks that fail any of these are documented as accepted tradeoffs, not silent compromises.**
+
+### 3.1 Sarvam-first hypothesis
+
+For every component Sarvam plausibly ships (STT, TTS, LLM, embeddings), the starting hypothesis is *"use Sarvam unless we have empirical reason not to."* This is graded behavior for a Sarvam assignment — silent defaults to OpenAI/Anthropic/ElevenLabs are the most common screen-out signal.
+
+We will **benchmark** before locking final Sarvam vs non-Sarvam picks:
+
+- **STT:** 20-utterance test set across English, Hindi, Hinglish — measure word-error rate
+- **TTS:** Subjective quality + latency on 5 sample advisor responses
+- **LLM:** 50 gold Q&A pairs run with Sarvam-M and GPT-4o — measure factual accuracy + citation accuracy
+
+Where Sarvam wins → ship Sarvam. Where Sarvam loses → document the gap with numbers and ship the alternative. Either outcome is a strong artifact.
+
+### 3.2 Real benchmark, not vibes
+
+For any pick that could affect downstream accuracy (LLM, embeddings, extraction prompt design), we make the call on **empirical evidence**, not first principles. The gold Q&A harness exists for exactly this — it transforms "I think X is better" into "X scored 92% vs Y's 87% on our test set."
+
+### 3.3 Production-pattern, not science-project
+
+Every component is picked **as if the next step is white-labelling to a BFSI customer.** No "great for prototyping" picks that block productionization. Examples:
+
+- ✅ FastAPI — already production-grade
+- ✅ DuckDB — embedded but production-deployed at Motherduck and many fintechs
+- ❌ ~~Streamlit~~ — great prototyping, no white-label path → switched to Next.js
+
+### 3.4 Single-file / single-deploy where possible
+
+Each extra service is a deploy risk and a moving part. We chose:
+
+- DuckDB (one file) over Postgres (separate process + cluster)
+- Chroma local (embedded) over Pinecone (separate service)
+- Render (single backend deploy) over Render-FE + Render-BE + Redis + Postgres
+
+The total infrastructure footprint is **2 deploys** (Vercel + Render) + **2 cloud APIs** (Sarvam + OpenAI). That's it.
+
+### 3.5 Documented alternatives
+
+Every pick has at least 2 alternatives recorded. A reviewer can audit the reasoning. "Why DuckDB?" → table row 14 → SQLite (no columnar, no analytics) and Postgres (overkill, deploy overhead). Three options considered; reasoning explicit.
+
+---
+
+## 4. Cost envelope (24-hour build + demo run)
+
+| Item | Estimated cost |
+| --- | --- |
+| Sarvam API (STT + TTS + LLM) — build + 100 demo calls | likely free under signup credits |
+| Voyage AI embeddings (~5M tokens to embed 75 PDFs) | ~$0.45 (free under $50 signup credit) |
+| Claude Haiku 4.5 for grader / self-critique (~200 calls) | ~$0.20 |
+| Render (free tier, 750 h/mo) | $0 |
+| Vercel (free tier, 100 GB bandwidth) | $0 |
+| GitHub (public repo) | $0 |
+| **Total realistic spend** | **< $1** |
+
+Production projection (1,000 daily active users, 5 turns each):
+- ~150K STT calls/mo + ~150K TTS calls/mo + ~150K LLM calls/mo
+- Estimated ~$200-400/mo for Sarvam APIs (highly volume-discount-sensitive)
+- Render Standard ($7/mo) + Vercel Pro ($20/mo) for resource limits
+- **Production envelope: ~$250-500/mo for the first 1K DAU.** Sub-cent per turn.
+
+---
+
+## 5. Open picks (will be resolved in next 24 hours)
+
+| # | Question | Resolution |
+| --- | --- | --- |
+| O1 | Does Sarvam expose an embeddings API? If yes, benchmark vs OpenAI text-embedding-3-small | Check `dashboard.sarvam.ai` API listing; <30 min |
+| O2 | Saarika v2.5 vs Saaras v3 for STT — depends on whether we need translate/codemix modes | Benchmark both on 20-utterance set; <1h |
+| O3 | Recommendation engine shape: rule-based pre-filter + LLM justification vs pure-LLM reasoning | Decide after gold Q&A harness runs; leaning rule-based for testability |
+| O4 | Caching layer — should LLM responses be cached for repeated questions? | Yes for demo; simple file cache, no Redis |
+| O5 | Should we add basic auth on the deployed URL to avoid abuse? | Probably yes — single shared password for interviewer access |
+
+---
+
+## 6. Decisions log cross-reference
+
+Every pick here corresponds to one or more entries in `decisions.md`:
+
+| Pick | Decision IDs |
+| --- | --- |
+| Vertical-slice scope | D-001 |
+| Health insurance category | D-002 |
+| Curated corpus, not user-uploaded | D-003 |
+| Hybrid structured + unstructured | D-004 |
+| **Frontend stack** (Next.js + FastAPI) | D-005 (revised 2026-05-13) |
+| Sarvam-first benchmarking | D-006 |
+| Pricing as illustrative band | D-007 |
+| Consultative persona | D-008 |
+| 10 insurers × all health policies | D-009 |
+| Secret handling | D-010 |
+| Embeddings provider (pending) | D-011 |
+| Render deployment over alternatives | D-012 |
+| Next.js + Tailwind + shadcn UI stack | D-013 |
+| GPT-4o-mini as grader to avoid circular eval | D-014 |
+
+---
+
+## 7. Revision history
+
+| Version | Date | Change |
+| --- | --- | --- |
+| 0.1 | 2026-05-13 | Initial draft. Switched D-005 frontend from Streamlit to Next.js + FastAPI; added D-011 through D-014 for new picks. |

entrypoint.sh

@@ -0,0 +1,43 @@
+#!/bin/sh
+# Container entrypoint:
+#   1. If the Chroma vector store is empty, run ingestion from rag/corpus/
+#      (one-time ~5 min on first boot; cached on HF persistent disk for
+#      subsequent boots)
+#   2. Start uvicorn
+
+set -e
+
+# Use HF Spaces persistent disk if mounted at /data, else fall back to /app
+if [ -d "/data" ] && [ -w "/data" ]; then
+    export VECTOR_DIR="/data/vectors"
+    export DUCKDB_PATH="/data/policies.duckdb"
+    # Symlink so the app code (which reads from rag/vectors and
+    # rag/policies.duckdb) finds them on the persistent disk
+    mkdir -p /data/vectors
+    rm -rf /app/rag/vectors
+    ln -sf /data/vectors /app/rag/vectors
+    if [ ! -f /data/policies.duckdb ] && [ -f /app/rag/policies.duckdb ]; then
+        cp /app/rag/policies.duckdb /data/policies.duckdb
+    fi
+    rm -f /app/rag/policies.duckdb
+    ln -sf /data/policies.duckdb /app/rag/policies.duckdb
+fi
+
+# Ingest if Chroma collection is empty
+echo "[entrypoint] checking if Chroma needs to be built..."
+python -c "
+import sys
+sys.path.insert(0, '/app')
+from rag.retrieve import get_collection
+c = get_collection()
+n = c.count()
+print(f'[entrypoint] Chroma chunks: {n}')
+sys.exit(0 if n > 0 else 1)
+" && echo "[entrypoint] Chroma already populated — skipping ingest" || (
+    echo "[entrypoint] Chroma empty — running ingest (~5 min one-time)..."
+    python -m rag.ingest 2>&1 | tail -20
+)
+
+# Start the server
+echo "[entrypoint] starting uvicorn on port ${PORT:-7860}..."
+exec uvicorn backend.main:app --host 0.0.0.0 --port "${PORT:-7860}" --log-level info

eval/generate_gold.py

@@ -0,0 +1,234 @@
+"""Generate gold Q&A pairs (Pipeline A — auto from structured extraction).
+
+For every successfully extracted policy in DuckDB, generate templated questions
+whose answers come directly from the structured fields. Output to eval/gold_qa.json.
+
+Run AFTER extraction:
+  python -m eval.generate_gold
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+from pathlib import Path
+from typing import Any
+
+import duckdb
+
+from backend.config import settings
+
+ROOT = settings.CORPUS_DIR.parent.parent
+OUTPUT = ROOT / "eval" / "gold_qa.json"
+
+
+# Question templates per field. Each tuple: (question_format, answer_format, type, difficulty).
+# {pn} is replaced with policy_name, {v} with the field value.
+QUESTION_TEMPLATES: dict[str, list[tuple[str, str, str, str]]] = {
+    "pre_existing_disease_waiting_months": [
+        ("What is the waiting period for pre-existing diseases under {pn}?", "{v} months from policy inception", "waiting_period", "easy"),
+        ("If I have diabetes, how long do I have to wait before I can claim under {pn}?", "{v} months — pre-existing diseases have a waiting period of {v} months from policy start", "waiting_period", "medium"),
+    ],
+    "initial_waiting_period_days": [
+        ("What is the initial waiting period under {pn}?", "{v} days from policy inception", "waiting_period", "easy"),
+    ],
+    "maternity_waiting_months": [
+        ("What's the maternity benefit waiting period under {pn}?", "{v} months", "waiting_period", "easy"),
+    ],
+    "pre_hospitalization_days": [
+        ("How many days of pre-hospitalization expenses does {pn} cover?", "{v} days", "coverage_scope", "easy"),
+    ],
+    "post_hospitalization_days": [
+        ("How many days of post-hospitalization expenses does {pn} cover?", "{v} days", "coverage_scope", "easy"),
+    ],
+    "day_care_treatments_count": [
+        ("How many day-care treatments are covered under {pn}?", "{v} day-care treatments", "coverage_scope", "easy"),
+    ],
+    "ayush_coverage": [
+        ("Does {pn} cover AYUSH (Ayurveda, Yoga, Unani, Siddha, Homeopathy)?", "{v_yes_no}", "coverage_scope", "easy"),
+    ],
+    "no_claim_bonus_pct": [
+        ("What's the no-claim bonus on {pn}?", "{v}% step-up on sum insured per claim-free year", "bonus", "easy"),
+    ],
+    "room_rent_capping": [
+        ("Is there a cap on room rent under {pn}?", "{v}", "sub_limit", "medium"),
+    ],
+    "copayment_pct": [
+        ("Is there a copayment under {pn}?", "{v_copay}", "sub_limit", "easy"),
+    ],
+    "network_hospital_count": [
+        ("How many hospitals are in the {pn} cashless network?", "Approximately {v:,} hospitals", "network", "easy"),
+    ],
+    "max_renewal_age": [
+        ("Up to what age can {pn} be renewed?", "{v_renewal}", "eligibility", "easy"),
+    ],
+    "min_entry_age": [
+        ("What is the minimum entry age for {pn}?", "{v} years", "eligibility", "easy"),
+    ],
+    "max_entry_age": [
+        ("What is the maximum entry age for {pn}?", "{v} years", "eligibility", "easy"),
+    ],
+}
+
+
+# Adversarial questions appended for every policy — bot should refuse.
+REFUSAL_TEMPLATES = [
+    ("Does {pn} cover injuries from space tourism?", "expected_refusal", "exclusions_oos", "hard"),
+    ("What is the maximum claim amount for diamond-tipped surgical procedures under {pn}?", "expected_refusal", "exclusions_oos", "hard"),
+    ("What is the IRDAI mandate on dental coverage that {pn} must follow?", "expected_refusal", "regulatory_oos", "hard"),
+]
+
+
+def yes_no(v: Any) -> str:
+    if v is True or v == "true" or v == 1:
+        return "Yes"
+    if v is False or v == "false" or v == 0:
+        return "No"
+    if isinstance(v, dict) and "covered" in v:
+        return "Yes" if v["covered"] else "No"
+    return str(v)
+
+
+def copay_str(v: Any) -> str:
+    try:
+        v = float(v)
+    except Exception:
+        return str(v)
+    if v <= 0:
+        return "No copayment"
+    return f"{v:.0f}% copayment applies"
+
+
+def renewal_str(v: Any) -> str:
+    try:
+        n = int(v)
+        if n >= 100:
+            return "Lifelong renewability"
+        return f"Up to age {n}"
+    except Exception:
+        return str(v)
+
+
+def format_answer(template: str, v: Any) -> str:
+    out = template
+    out = out.replace("{v_yes_no}", yes_no(v))
+    out = out.replace("{v_copay}", copay_str(v))
+    out = out.replace("{v_renewal}", renewal_str(v))
+    if "{v:,}" in out:
+        try:
+            out = out.replace("{v:,}", f"{int(v):,}")
+        except Exception:
+            out = out.replace("{v:,}", str(v))
+    out = out.replace("{v}", str(v))
+    return out
+
+
+def load_policies() -> list[dict]:
+    if not settings.STRUCTURED_DB.exists():
+        return []
+    con = duckdb.connect(str(settings.STRUCTURED_DB), read_only=True)
+    rows = con.execute("SELECT policy_id, policy_name, data_json FROM policies").fetchall()
+    con.close()
+    out = []
+    for pid, pname, data in rows:
+        try:
+            d = json.loads(data)
+            d["_policy_id"] = pid
+            d["_policy_name"] = pname or d.get("policy_name", pid)
+            out.append(d)
+        except Exception:
+            continue
+    return out
+
+
+def is_present(v: Any) -> bool:
+    if v is None:
+        return False
+    if isinstance(v, str) and v.strip() == "":
+        return False
+    if isinstance(v, list) and len(v) == 0:
+        return False
+    if isinstance(v, dict):
+        # Pydantic CoverageItem dict — present if covered is set
+        return v.get("covered") is not None
+    return True
+
+
+def extract_value_for_template(v: Any) -> Any:
+    """Some fields are CoverageItem dicts; pull a representative value."""
+    if isinstance(v, dict) and "covered" in v:
+        return v["covered"]  # used by yes_no formatter
+    return v
+
+
+def generate() -> list[dict]:
+    policies = load_policies()
+    gold: list[dict] = []
+
+    for p in policies:
+        pid = p["_policy_id"]
+        pname = p["_policy_name"]
+
+        for field, templates in QUESTION_TEMPLATES.items():
+            raw_v = p.get(field)
+            if not is_present(raw_v):
+                continue
+            v = extract_value_for_template(raw_v)
+
+            for question_fmt, answer_fmt, qtype, difficulty in templates:
+                answer = format_answer(answer_fmt, v)
+                if not answer.strip():
+                    continue
+                gold.append({
+                    "id": f"{pid}::{field}::{difficulty}",
+                    "policy_id": pid,
+                    "question": question_fmt.format(pn=pname),
+                    "expected_answer": answer,
+                    "question_type": qtype,
+                    "difficulty": difficulty,
+                    "expected_refusal": False,
+                    "language": "en",
+                    "generated_by": "pipeline_a",
+                    "source_field": field,
+                })
+
+        for question_fmt, marker, qtype, difficulty in REFUSAL_TEMPLATES:
+            gold.append({
+                "id": f"{pid}::REFUSE::{qtype}::{difficulty}",
+                "policy_id": pid,
+                "question": question_fmt.format(pn=pname),
+                "expected_answer": "Bot should refuse or say not in document.",
+                "question_type": qtype,
+                "difficulty": difficulty,
+                "expected_refusal": True,
+                "language": "en",
+                "generated_by": "pipeline_c_refusal",
+            })
+
+    return gold
+
+
+def main():
+    gold = generate()
+    OUTPUT.parent.mkdir(parents=True, exist_ok=True)
+    OUTPUT.write_text(json.dumps(gold, indent=2))
+    print(f"Wrote {len(gold)} gold Q&A pairs to {OUTPUT.relative_to(ROOT)}")
+    # Quick breakdown
+    by_policy: dict[str, int] = {}
+    by_type: dict[str, int] = {}
+    refusal_count = 0
+    for g in gold:
+        by_policy[g["policy_id"]] = by_policy.get(g["policy_id"], 0) + 1
+        by_type[g["question_type"]] = by_type.get(g["question_type"], 0) + 1
+        if g["expected_refusal"]:
+            refusal_count += 1
+    print(f"Policies covered: {len(by_policy)}")
+    print(f"Refusal questions: {refusal_count}")
+    print("By type:")
+    for t, n in sorted(by_type.items(), key=lambda kv: -kv[1])[:15]:
+        print(f"  {t:>25s}: {n}")
+
+
+if __name__ == "__main__":
+    main()

eval/run.py

@@ -0,0 +1,276 @@
+"""Run the gold Q&A eval against the local bot.
+
+Pipeline:
+  1. Load eval/gold_qa.json
+  2. For each pair: call backend.orchestrator.handle_turn (in-process — fast)
+     with policy_filter_ids=[pair.policy_id] to restrict retrieval to that policy
+  3. Grade each reply using Groq Llama as the LLM-judge (different family ->
+     non-circular eval; regex hard-facts grader runs alongside)
+  4. Aggregate and write eval/results.md + eval/results.json
+
+Run:
+  python -m eval.run                  # full eval
+  python -m eval.run --limit 30       # smoke test on first 30
+  python -m eval.run --policy <pid>   # just one policy
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import re
+import time
+from collections import defaultdict
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Optional
+
+from backend.config import settings
+from backend.orchestrator import handle_turn
+from backend.providers.base import ChatMessage
+from backend.providers.groq_llm import GroqLLM
+
+ROOT = settings.CORPUS_DIR.parent.parent
+GOLD_FILE = ROOT / "eval" / "gold_qa.json"
+RESULTS_JSON = ROOT / "eval" / "results.json"
+RESULTS_MD = ROOT / "eval" / "results.md"
+
+
+JUDGE_SYSTEM = """You grade an insurance bot's answer against a gold answer.
+
+You will be given:
+  GOLD: the expected answer
+  BOT: the bot's actual reply
+  REFUSAL_EXPECTED: whether the bot should have refused
+
+Output strict JSON:
+{
+  "factual_match": bool,         // does BOT semantically convey what GOLD says (or correctly refuse if REFUSAL_EXPECTED is true)?
+  "citation_present": bool,       // does BOT contain a [Source: ...] tag (irrelevant for correct refusals)
+  "score": 0-1.0,
+  "reason": "one short sentence"
+}
+
+Be strict on factual_match — partial answers that miss the key number/value should be false.
+For REFUSAL_EXPECTED=true, factual_match=true ONLY if BOT explicitly refuses or says the info isn't in the document.
+"""
+
+
+@dataclass
+class EvalRecord:
+    id: str
+    policy_id: str
+    question: str
+    expected_answer: str
+    bot_answer: str
+    factual_match: bool
+    citation_present: bool
+    judge_score: float
+    judge_reason: str
+    expected_refusal: bool
+    question_type: str
+    difficulty: str
+    blocked: bool
+    faithfulness_passed: bool
+    faithfulness_reasons: list[str] = field(default_factory=list)
+    brain_used: str = ""
+    latency_ms: int = 0
+
+
+_judge: Optional[GroqLLM] = None
+def get_judge() -> GroqLLM:
+    global _judge
+    if _judge is None:
+        _judge = GroqLLM()
+    return _judge
+
+
+async def grade_one(gold: dict, bot_answer: str, blocked: bool) -> tuple[bool, bool, float, str]:
+    """Returns (factual_match, citation_present, score, reason)."""
+    citation_present = bool(re.search(r"\[(?:Source|Regulation):", bot_answer or "", flags=re.IGNORECASE))
+
+    # Refusal handling
+    refuse_kw = ("i don't see", "i don't have", "i'd rather not", "not in the document", "no information about", "not mentioned")
+    is_refusal = any(kw in (bot_answer or "").lower() for kw in refuse_kw) or blocked
+    if gold["expected_refusal"]:
+        return (is_refusal, citation_present, 1.0 if is_refusal else 0.0,
+                "correctly refused" if is_refusal else "did not refuse when expected")
+
+    # If bot refused but the answer WAS expected, that's a miss
+    if is_refusal:
+        return (False, citation_present, 0.0, "bot refused on a question with a known answer")
+
+    # LLM-judge for factual content
+    user = f"""GOLD: {gold['expected_answer']}
+BOT: {bot_answer}
+REFUSAL_EXPECTED: {gold['expected_refusal']}
+
+Grade now."""
+    try:
+        res = await get_judge().chat(
+            messages=[ChatMessage(role="system", content=JUDGE_SYSTEM),
+                      ChatMessage(role="user", content=user)],
+            temperature=0.0,
+            max_tokens=200,
+            response_format={"type": "json_object"},
+        )
+        d = json.loads(res.text)
+        return (bool(d.get("factual_match", False)),
+                citation_present,
+                float(d.get("score", 0.0)),
+                str(d.get("reason", ""))[:200])
+    except Exception as e:
+        return (False, citation_present, 0.0, f"judge_error: {type(e).__name__}: {e}")
+
+
+async def run_one(gold: dict) -> EvalRecord:
+    turn = await handle_turn(
+        user_text=gold["question"],
+        chat_history=[],
+        user_profile={},
+        policy_filter_ids=[gold["policy_id"]],
+    )
+    factual, citation, score, reason = await grade_one(gold, turn.reply_text, turn.blocked)
+    return EvalRecord(
+        id=gold["id"],
+        policy_id=gold["policy_id"],
+        question=gold["question"],
+        expected_answer=gold["expected_answer"],
+        bot_answer=turn.reply_text,
+        factual_match=factual,
+        citation_present=citation,
+        judge_score=score,
+        judge_reason=reason,
+        expected_refusal=gold["expected_refusal"],
+        question_type=gold["question_type"],
+        difficulty=gold["difficulty"],
+        blocked=turn.blocked,
+        faithfulness_passed=turn.faithfulness_passed,
+        faithfulness_reasons=turn.faithfulness_reasons,
+        brain_used=turn.brain_used,
+        latency_ms=turn.latency_ms,
+    )
+
+
+async def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--limit", type=int, default=None)
+    parser.add_argument("--policy", default=None)
+    args = parser.parse_args()
+
+    if not GOLD_FILE.exists():
+        print(f"Missing {GOLD_FILE} — run `python -m eval.generate_gold` first")
+        return 1
+    gold = json.loads(GOLD_FILE.read_text())
+    if args.policy:
+        gold = [g for g in gold if g["policy_id"] == args.policy]
+    if args.limit:
+        gold = gold[: args.limit]
+
+    print(f"Running eval on {len(gold)} questions...\n")
+    results: list[EvalRecord] = []
+    t0 = time.time()
+    for i, g in enumerate(gold, 1):
+        rec = await run_one(g)
+        results.append(rec)
+        ok_factual = "✓" if rec.factual_match else "✗"
+        ok_cite = "✓" if rec.citation_present else " "
+        print(f"[{i:>3}/{len(gold)}] {ok_factual} {ok_cite} [{rec.judge_score:.2f}] {rec.question[:60]:<60} | {rec.judge_reason[:60]}")
+
+    elapsed = time.time() - t0
+
+    # Aggregate
+    n = len(results)
+    factual_acc = sum(1 for r in results if r.factual_match) / max(1, n)
+    citation_acc = sum(1 for r in results if r.citation_present and not r.expected_refusal) / max(1, sum(1 for r in results if not r.expected_refusal))
+    refusal_n = sum(1 for r in results if r.expected_refusal)
+    refusal_correct = sum(1 for r in results if r.expected_refusal and r.factual_match)
+    refusal_precision = refusal_correct / max(1, refusal_n)
+
+    by_type_factual: dict[str, list[bool]] = defaultdict(list)
+    by_brain: dict[str, list[bool]] = defaultdict(list)
+    for r in results:
+        by_type_factual[r.question_type].append(r.factual_match)
+        by_brain[r.brain_used.split("::")[0]].append(r.factual_match)
+
+    summary = {
+        "ran_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "elapsed_seconds": round(elapsed, 1),
+        "n_questions": n,
+        "factual_accuracy": round(factual_acc, 3),
+        "citation_accuracy": round(citation_acc, 3),
+        "refusal_precision": round(refusal_precision, 3),
+        "by_type": {t: round(sum(vs) / len(vs), 3) for t, vs in by_type_factual.items()},
+        "by_brain": {b: round(sum(vs) / len(vs), 3) for b, vs in by_brain.items()},
+        "blocked_count": sum(1 for r in results if r.blocked),
+    }
+
+    RESULTS_JSON.write_text(json.dumps({"summary": summary, "results": [asdict(r) for r in results]}, indent=2))
+
+    md = render_md(summary, results)
+    RESULTS_MD.write_text(md)
+
+    print(f"\n========== SUMMARY ==========")
+    print(f"  Factual accuracy:    {factual_acc*100:.1f}%")
+    print(f"  Citation accuracy:   {citation_acc*100:.1f}%")
+    print(f"  Refusal precision:   {refusal_precision*100:.1f}%")
+    print(f"  Blocked:             {summary['blocked_count']}/{n}")
+    print(f"  By brain: {summary['by_brain']}")
+    print(f"  Elapsed:             {elapsed:.1f}s")
+    print(f"  Results:             {RESULTS_MD.relative_to(ROOT)}")
+    return 0
+
+
+def render_md(summary: dict, results: list[EvalRecord]) -> str:
+    by_type = summary["by_type"]
+    by_brain = summary["by_brain"]
+    md_type = "\n".join(f"| {t} | {pct*100:.1f}% |" for t, pct in sorted(by_type.items(), key=lambda kv: -kv[1]))
+    md_brain = "\n".join(f"| {b} | {pct*100:.1f}% |" for b, pct in sorted(by_brain.items(), key=lambda kv: -kv[1]))
+
+    misses = [r for r in results if not r.factual_match][:15]
+    miss_table = "\n".join(
+        f"| {r.id[:60]} | {r.question[:60]} | {r.bot_answer[:80]} | {r.judge_reason[:60]} |"
+        for r in misses
+    )
+
+    return f"""# Eval Results — {summary['ran_at']}
+
+## Headline
+
+| Metric | Value |
+| --- | --- |
+| Questions run | {summary['n_questions']} |
+| **Factual accuracy** | **{summary['factual_accuracy']*100:.1f}%** |
+| **Citation accuracy** | **{summary['citation_accuracy']*100:.1f}%** |
+| **Refusal precision** | **{summary['refusal_precision']*100:.1f}%** |
+| Blocked by faithfulness | {summary['blocked_count']} |
+| Elapsed | {summary['elapsed_seconds']} s |
+
+## By question type
+
+| Type | Accuracy |
+| --- | --- |
+{md_type}
+
+## By brain (router winners)
+
+| Brain | Accuracy |
+| --- | --- |
+{md_brain}
+
+## Sample misses (up to 15)
+
+| id | question | bot_answer | reason |
+| --- | --- | --- | --- |
+{miss_table}
+
+---
+
+*Grader: Groq Llama-3.3-70B-versatile (different model family from Sarvam-M to avoid circular eval).*
+*Full per-question results: `eval/results.json`.*
+"""
+
+
+if __name__ == "__main__":
+    raise SystemExit(asyncio.run(main()))

frontend/.gitignore

@@ -0,0 +1,41 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

frontend/AGENTS.md

@@ -0,0 +1,5 @@
+<!-- BEGIN:nextjs-agent-rules -->
+# This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
+<!-- END:nextjs-agent-rules -->

frontend/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

frontend/README.md

@@ -0,0 +1,36 @@
+This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+
+## Getting Started
+
+First, run the development server:
+
+```bash
+npm run dev
+# or
+yarn dev
+# or
+pnpm dev
+# or
+bun dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+
+You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+
+This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+
+## Learn More
+
+To learn more about Next.js, take a look at the following resources:
+
+- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
+- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+
+You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+
+## Deploy on Vercel
+
+The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+
+Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.

frontend/eslint.config.mjs

@@ -0,0 +1,18 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  // Override default ignores of eslint-config-next.
+  globalIgnores([
+    // Default ignores of eslint-config-next:
+    ".next/**",
+    "out/**",
+    "build/**",
+    "next-env.d.ts",
+  ]),
+]);
+
+export default eslintConfig;

frontend/next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+import "./.next/types/routes.d.ts";
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

frontend/next.config.ts

@@ -0,0 +1,14 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  // Static export — the built frontend is served by the FastAPI backend
+  // alongside the /api/* routes on a single port. This lets us deploy
+  // everything to a single Hugging Face Space (Docker).
+  output: "export",
+  // Disable next/image optimization in static export (no Node runtime serving it)
+  images: { unoptimized: true },
+  // Trailing slashes match the way FastAPI's StaticFiles serves directories
+  trailingSlash: true,
+};
+
+export default nextConfig;

frontend/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "frontend",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint"
+  },
+  "dependencies": {
+    "next": "16.2.6",
+    "react": "19.2.4",
+    "react-dom": "19.2.4"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "eslint": "^9",
+    "eslint-config-next": "16.2.6",
+    "tailwindcss": "^4",
+    "typescript": "^5"
+  }
+}

frontend/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;