Deploy IndiaFinBench research site

.dockerignore

@@ -0,0 +1,40 @@
+# ── SECURITY — never bake API keys into the image ──────────────────────────────
+.env
+.env.*
+
+# ── Not needed at serve time (RAG index is pre-built) ──────────────────────────
+data/parsed/
+data/raw/
+data/eval/
+
+# ── Research artifacts — large, not needed in the app ──────────────────────────
+annotation/
+paper/
+evaluation/
+scripts/
+notebooks/
+_archive/
+results/
+
+# ── Dev tooling ────────────────────────────────────────────────────────────────
+.claude/
+demo/.claude/
+docs/superpowers/
+
+# ── Alternate RAG indices (only default rag/index/ is needed) ──────────────────
+rag/index_800/
+rag/index_2400/
+
+# ── Build / runtime artifacts ──────────────────────────────────────────────────
+*.pyc
+*.pyo
+*.pyd
+__pycache__/
+*.log
+*.db.bak
+.git/
+.gitignore
+
+# ── Misc ───────────────────────────────────────────────────────────────────────
+*.tmp
+.DS_Store

.gitattributes

@@ -0,0 +1,2 @@
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.index filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,55 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# ── System build dependencies ──────────────────────────────────────────────────
+# gcc/g++ required for numpy and faiss-cpu compilation
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc \
+    g++ \
+    && rm -rf /var/lib/apt/lists/*
+
+# ── Python dependencies ────────────────────────────────────────────────────────
+# Install CPU-only torch FIRST (prevents pulling the 2 GB CUDA wheel when
+# sentence-transformers later requests torch as a dependency)
+RUN pip install --no-cache-dir torch --index-url https://download.pytorch.org/whl/cpu
+
+# Copy requirements before source code so Docker can cache this layer
+COPY demo/requirements.txt /tmp/demo-req.txt
+COPY rag/requirements.txt  /tmp/rag-req.txt
+RUN pip install --no-cache-dir -r /tmp/demo-req.txt && \
+    pip install --no-cache-dir -r /tmp/rag-req.txt
+
+# ── Pre-download BGE embedding model ──────────────────────────────────────────
+# Bake the model into the image so startup is fast on HF Spaces (no network wait).
+# Store in /app/.cache/huggingface so it survives the non-root user switch below.
+ENV HF_HOME=/app/.cache/huggingface
+RUN python -c "\
+from sentence_transformers import SentenceTransformer; \
+SentenceTransformer('BAAI/bge-base-en-v1.5')" \
+    && chmod -R 755 /app/.cache
+
+# ── Application code ───────────────────────────────────────────────────────────
+# .dockerignore excludes .env, data/parsed/, paper/, scripts/, etc.
+COPY . .
+
+# ── Non-root user (HF Spaces requirement) ─────────────────────────────────────
+RUN useradd -m -u 1000 user && chown -R user:user /app
+USER user
+
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH \
+    HF_HOME=/app/.cache/huggingface \
+    PORT=7860
+
+EXPOSE 7860
+
+# ── Start server ───────────────────────────────────────────────────────────────
+# Run from /app (repo root) so both `demo` and `rag` are importable as packages.
+# 1 worker keeps SQLite writes safe; 4 threads handle concurrent requests.
+CMD exec gunicorn \
+    --bind "0.0.0.0:${PORT}" \
+    --workers 1 \
+    --threads 4 \
+    --timeout 120 \
+    demo.app:app

README.md

@@ -0,0 +1,23 @@
+---
+title: IndiaFinBench
+emoji: 📜
+colorFrom: red
+colorTo: yellow
+sdk: docker
+app_port: 7860
+pinned: false
+license: mit
+short_description: LLM benchmark for Indian financial regulation
+---
+
+# IndiaFinBench
+
+**The first evaluation benchmark for large language model performance on Indian financial regulatory text.**
+
+406 expert-annotated questions over 192 SEBI & RBI regulatory documents (1992–2026) · 12 frontier models evaluated · hybrid FAISS + BM25 retrieval with Recall@5 = 0.785.
+
+This Space hosts the live research site: the full leaderboard with statistical tier analysis, a dataset explorer, a live hybrid-RAG demo over the regulatory corpus, and model submission.
+
+- **Dataset:** [Rajveer-code/IndiaFinBench](https://huggingface.co/datasets/Rajveer-code/IndiaFinBench) (CC BY 4.0)
+- **Code & paper:** [github.com/Rajveer-code/IndiaFinBench](https://github.com/Rajveer-code/IndiaFinBench) (MIT)
+- **Author:** Rajveer Singh Pall — rajveerpall04@gmail.com

demo/.dockerignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+*.db
+.env
+.git
+.gitignore
+*.md
+leaderboard.db
+rag/setup_datastore.py
+.claude/

demo/app.py

@@ -0,0 +1,287 @@
+"""
+demo/app.py
+-----------
+Flask leaderboard + RAG demo for IndiaFinBench.
+
+Routes:
+  GET  /                  Main page
+  GET  /api/leaderboard   JSON leaderboard (12 models + human)
+  GET  /api/example       Random benchmark item
+  POST /api/rag           Hybrid RAG query (rate-limited 20/min per IP)
+  POST /api/submit        Returns pre-filled GitHub issue URL
+
+Run locally:
+  python demo/app.py
+
+On HuggingFace Spaces:
+  gunicorn --bind 0.0.0.0:7860 --workers 1 --threads 4 --timeout 120 demo.app:app
+"""
+
+import json
+import os
+import random
+import sys
+import threading
+import time
+import urllib.parse
+from collections import defaultdict, deque
+from pathlib import Path
+
+from flask import Flask, jsonify, render_template, request
+
+# ── Python path ────────────────────────────────────────────────────────────────
+# Root must come FIRST so `import rag` resolves to /app/rag/ (the real pipeline)
+# not /app/demo/rag/ (old shim, now deleted).
+# Demo comes second for database/ imports.
+_DEMO_DIR = Path(__file__).parent
+_ROOT_DIR  = _DEMO_DIR.parent
+
+if str(_ROOT_DIR) not in sys.path:
+    sys.path.insert(0, str(_ROOT_DIR))
+if str(_DEMO_DIR) not in sys.path:
+    sys.path.insert(1, str(_DEMO_DIR))
+
+from database.db import get_leaderboard, init_db  # noqa: E402
+
+# ── Data ───────────────────────────────────────────────────────────────────────
+
+QUESTIONS_PATH = _DEMO_DIR / "data" / "questions.json"
+with QUESTIONS_PATH.open(encoding="utf-8") as _f:
+    QUESTIONS: list[dict] = json.load(_f)
+
+init_db()
+
+# ── Flask app ──────────────────────────────────────────────────────────────────
+
+app = Flask(
+    __name__,
+    template_folder=str(_DEMO_DIR / "templates"),
+    static_folder=str(_DEMO_DIR / "static"),
+)
+app.config["TEMPLATES_AUTO_RELOAD"] = True
+app.config["SEND_FILE_MAX_AGE_DEFAULT"] = 0
+
+_JS_VER = str(int(time.time()))
+
+
+@app.after_request
+def _no_cache(response):
+    response.headers["Cache-Control"] = "no-store, no-cache, must-revalidate"
+    response.headers["Pragma"] = "no-cache"
+    return response
+
+
+# ── Constants ──────────────────────────────────────────────────────────────────
+
+TASK_FULL = {
+    "regulatory_interpretation": "Regulatory Interpretation",
+    "numerical_reasoning":       "Numerical Reasoning",
+    "contradiction_detection":   "Contradiction Detection",
+    "temporal_reasoning":        "Temporal Reasoning",
+}
+
+HUMAN_BASELINE = {
+    "rank":      "—",
+    "label":     "Human Expert",
+    "hf_id":     "— (n=100 sampled items)",
+    "params":    "—",
+    "type":      "Human Baseline",
+    "overall":   69.0,
+    "reg":       55.6,
+    "num":       44.4,
+    "con":       83.3,
+    "tmp":       66.7,
+    "n_items":   100,
+    "submitted": "2026-03-15",
+    "is_human":  True,
+}
+
+# ── RAG pipeline (lazy, thread-safe) ──────────────────────────────────────────
+
+_INDEX_DIR    = _ROOT_DIR / "rag" / "index"
+_rag_pipeline = None
+_rag_lock     = threading.Lock()
+
+
+def _get_rag_pipeline():
+    """Lazy-init the RAG pipeline with double-checked locking."""
+    global _rag_pipeline
+    if _rag_pipeline is not None:
+        return _rag_pipeline
+    with _rag_lock:
+        if _rag_pipeline is not None:
+            return _rag_pipeline
+        from rag.config import RAGConfig        # noqa: PLC0415
+        from rag.pipeline import RAGPipeline    # noqa: PLC0415
+        cfg = RAGConfig(index_dir=_INDEX_DIR)
+        p = RAGPipeline(config=cfg)
+        p.load_index()
+        _rag_pipeline = p
+    return _rag_pipeline
+
+
+def _warmup_rag() -> None:
+    """Pre-load the pipeline at startup so the first user request is fast."""
+    try:
+        _get_rag_pipeline()
+        app.logger.info("RAG pipeline ready (FAISS + BM25 loaded)")
+    except Exception as exc:                   # noqa: BLE001
+        app.logger.warning("RAG warmup failed: %s", exc)
+
+
+threading.Thread(target=_warmup_rag, daemon=True).start()
+
+# ── Rate limiter ───────────────────────────────────────────────────────────────
+
+_rag_rate: dict = defaultdict(deque)
+_RL_N = 20      # requests
+_RL_W = 60.0    # seconds window
+
+
+def _rl_check(ip: str) -> bool:
+    """Return True if the IP is within the rate limit, False if exceeded."""
+    now = time.time()
+    q   = _rag_rate[ip]
+    while q and now - q[0] > _RL_W:
+        q.popleft()
+    if len(q) >= _RL_N:
+        return False
+    q.append(now)
+    return True
+
+
+# ── Helpers ────────────────────────────────────────────────────────────────────
+
+def _normalize_models(df) -> list[dict]:
+    result = []
+    for _, row in df.iterrows():
+        result.append({
+            "rank":      int(row["Rank"]),
+            "label":     str(row["Model"]),
+            "hf_id":     str(row["HF Model ID"]),
+            "params":    str(row.get("Params", "—")),
+            "type":      str(row.get("Type", "Open")),
+            "overall":   round(float(row["Overall (%)"]), 1),
+            "reg":       round(float(row["REG (%)"]),     1),
+            "num":       round(float(row["NUM (%)"]),     1),
+            "con":       round(float(row["CON (%)"]),     1),
+            "tmp":       round(float(row["TMP (%)"]),     1),
+            "submitted": str(row.get("Submitted", "")),
+            "is_human":  False,
+        })
+    return result
+
+
+# ── Routes ─────────────────────────────────────────────────────────────────────
+
+@app.route("/")
+def index():
+    df     = get_leaderboard()
+    models = _normalize_models(df) if not df.empty else []
+    return render_template(
+        "index.html",
+        models=models,
+        human=HUMAN_BASELINE,
+        model_count=12,
+        human_overall=f"{HUMAN_BASELINE['overall']:.1f}",
+        js_ver=_JS_VER,
+    )
+
+
+@app.route("/api/leaderboard")
+def api_leaderboard():
+    df     = get_leaderboard()
+    models = _normalize_models(df) if not df.empty else []
+    models.append(HUMAN_BASELINE)
+    return jsonify(models)
+
+
+@app.route("/api/submit", methods=["POST"])
+def api_submit():
+    data       = request.get_json() or {}
+    hf_id      = (data.get("hf_id") or "").strip()
+    label      = (data.get("label") or (hf_id.split("/")[-1] if hf_id else "")).strip()
+    params     = (data.get("params") or "Unknown").strip() or "Unknown"
+    model_type = (data.get("model_type") or "Open").strip() or "Open"
+
+    if not hf_id:
+        return jsonify({"error": "hf_id is required"}), 400
+
+    safe = hf_id.replace("/", "_")
+    body = (
+        "**Model Submission for IndiaFinBench**\n\n"
+        "| Field | Value |\n|---|---|\n"
+        f"| Model Name | {label} |\n"
+        f"| HuggingFace ID | `{hf_id}` |\n"
+        f"| Parameters | {params} |\n"
+        f"| Type | {model_type} |\n\n"
+        "**Evaluation command:**\n"
+        "```bash\n"
+        "python evaluation/evaluate.py \\\n"
+        "    --dataset data/benchmark/indiafinbench_v1.csv \\\n"
+        f"    --model {hf_id} \\\n"
+        "    --provider huggingface \\\n"
+        f"    --output results/predictions/{safe}.csv\n"
+        "```\n"
+    )
+    issue_url = (
+        "https://github.com/Rajveer-code/IndiaFinBench/issues/new"
+        f"?title={urllib.parse.quote(f'[Submission] {label}')}"
+        f"&body={urllib.parse.quote(body)}"
+        "&labels=model-submission"
+    )
+    return jsonify({"issue_url": issue_url})
+
+
+@app.route("/api/rag", methods=["POST"])
+def api_rag():
+    data  = request.get_json() or {}
+    query = (data.get("query") or "").strip()
+    if not query:
+        return jsonify({"error": "Missing query"}), 400
+
+    ip = request.remote_addr or "unknown"
+    if not _rl_check(ip):
+        return jsonify({"error": "Rate limit reached (20 req/min). Please wait."}), 429
+
+    try:
+        result = _get_rag_pipeline().ask(query)
+    except Exception as exc:               # noqa: BLE001
+        result = {"error": f"RAG unavailable: {str(exc)[:300]}"}
+    return jsonify(result)
+
+
+@app.route("/api/example")
+def api_example():
+    task = request.args.get("task", "All")
+    diff = request.args.get("diff", "All")
+
+    pool = list(QUESTIONS)
+    if task != "All":
+        pool = [q for q in pool if TASK_FULL.get(q["task_type"], "") == task]
+    if diff != "All":
+        pool = [q for q in pool if q["difficulty"] == diff.lower()]
+
+    if not pool:
+        return jsonify({"error": "No examples match filters"})
+
+    q   = random.choice(pool)
+    ctx = q.get("context") or (
+        "Passage A: " + q.get("context_a", "")
+        + "\n\nPassage B: " + q.get("context_b", "")
+    )
+    return jsonify({
+        "id":         q["id"],
+        "task_type":  TASK_FULL.get(q["task_type"], q["task_type"]),
+        "difficulty": q["difficulty"],
+        "context":    ctx[:800] + ("…" if len(ctx) > 800 else ""),
+        "question":   q["question"],
+        "answer":     q["gold_answer"],
+    })
+
+
+# ── Entry point ───────────────────────────────────────────────────────���────────
+
+if __name__ == "__main__":
+    port = int(os.getenv("PORT", "7860"))
+    app.run(host="0.0.0.0", port=port, debug=False)

demo/data/baselines.json

@@ -0,0 +1,157 @@
+[
+  {
+    "model_id": "claude_haiku",
+    "label": "Claude 3 Haiku",
+    "hf_id": "anthropic/claude-3-haiku-20240307",
+    "params": "—",
+    "type": "Frontier API",
+    "scores": {
+      "REG": 0.9245,
+      "NUM": 0.9375,
+      "CON": 0.8667,
+      "TMP": 0.9143
+    },
+    "overall": 0.9133,
+    "n_items": 150,
+    "submitted": "2026-03-30",
+    "baseline": true,
+    "note": "Retired by Anthropic on April 19, 2026. Outputs cached for reproducibility."
+  },
+  {
+    "model_id": "gemini_flash",
+    "label": "Gemini 2.5 Flash",
+    "hf_id": "google/gemini-2.5-flash",
+    "params": "—",
+    "type": "Frontier API",
+    "scores": {
+      "REG": 0.9623,
+      "NUM": 0.8438,
+      "CON": 0.8333,
+      "TMP": 0.8
+    },
+    "overall": 0.8733,
+    "n_items": 150,
+    "submitted": "2026-03-31",
+    "baseline": true
+  },
+  {
+    "model_id": "llama4scout",
+    "label": "Llama 4 Scout 17B",
+    "hf_id": "meta-llama/llama-4-scout-17b-16e-instruct",
+    "params": "17B",
+    "type": "Open-weight API",
+    "scores": {
+      "REG": 0.7925,
+      "NUM": 0.75,
+      "CON": 1.0,
+      "TMP": 0.8
+    },
+    "overall": 0.8267,
+    "n_items": 150,
+    "submitted": "2026-04-08",
+    "baseline": true
+  },
+  {
+    "model_id": "qwen3_32b",
+    "label": "Qwen3-32B",
+    "hf_id": "Qwen/Qwen3-32B",
+    "params": "32B",
+    "type": "Open-weight API",
+    "scores": {
+      "REG": 0.7736,
+      "NUM": 0.75,
+      "CON": 0.8667,
+      "TMP": 0.9429
+    },
+    "overall": 0.8267,
+    "n_items": 150,
+    "submitted": "2026-04-08",
+    "baseline": true
+  },
+  {
+    "model_id": "llama33_70b",
+    "label": "LLaMA-3.3-70B",
+    "hf_id": "meta-llama/Llama-3.3-70B-Instruct",
+    "params": "70B",
+    "type": "Open-weight API",
+    "scores": {
+      "REG": 0.7736,
+      "NUM": 0.8438,
+      "CON": 0.9,
+      "TMP": 0.7714
+    },
+    "overall": 0.8133,
+    "n_items": 150,
+    "submitted": "2026-03-31",
+    "baseline": true
+  },
+  {
+    "model_id": "llama3_8b",
+    "label": "LLaMA-3-8B",
+    "hf_id": "meta-llama/Meta-Llama-3-8B-Instruct",
+    "params": "8B",
+    "type": "Local (Ollama)",
+    "scores": {
+      "REG": 0.7736,
+      "NUM": 0.625,
+      "CON": 0.8667,
+      "TMP": 0.7429
+    },
+    "overall": 0.7533,
+    "n_items": 150,
+    "submitted": "2026-03-31",
+    "baseline": true
+  },
+  {
+    "model_id": "gemma4_e4b",
+    "label": "Gemma 4 E4B",
+    "hf_id": "google/gemma-4-e4b",
+    "params": "4B",
+    "type": "Local (Ollama)",
+    "scores": {
+      "REG": 0.9057,
+      "NUM": 0.6563,
+      "CON": 0.7667,
+      "TMP": 0.5714
+    },
+    "overall": 0.7467,
+    "n_items": 150,
+    "submitted": "2026-04-10",
+    "baseline": true
+  },
+  {
+    "model_id": "mistral_7b",
+    "label": "Mistral-7B",
+    "hf_id": "mistralai/Mistral-7B-Instruct-v0.3",
+    "params": "7B",
+    "type": "Local (Ollama)",
+    "scores": {
+      "REG": 0.6981,
+      "NUM": 0.6875,
+      "CON": 0.8,
+      "TMP": 0.7429
+    },
+    "overall": 0.7267,
+    "n_items": 150,
+    "submitted": "2026-03-31",
+    "baseline": true
+  },
+  {
+    "model_id": "deepseek_r1_70b",
+    "label": "DeepSeek R1 70B",
+    "hf_id": "deepseek-ai/DeepSeek-R1-Distill-Llama-70B",
+    "params": "70B distilled",
+    "type": "Reasoning API",
+    "scores": {
+      "REG": 0.6038,
+      "NUM": 0.7813,
+      "CON": 0.9333,
+      "TMP": 0.6
+    },
+    "overall": 0.7067,
+    "n_items": 150,
+    "submitted": "2026-04-10",
+    "baseline": true,
+    "note": "Evaluated via OpenRouter (retired from Groq October 2, 2025). Identical model weights."
+  }
+]

demo/database/db.py

@@ -0,0 +1,216 @@
+"""
+database/db.py
+--------------
+Purpose:  SQLite-backed leaderboard database for IndiaFinBench Spaces.
+          Stores evaluation results, supports leaderboard retrieval.
+Inputs:   baselines.json (pre-populated on first init)
+Outputs:  Pandas DataFrame via get_leaderboard()
+Usage:
+    from database.db import init_db, save_result, get_leaderboard
+    init_db()
+    df = get_leaderboard()
+"""
+
+import json
+import sqlite3
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+import pandas as pd
+
+# ── Configuration ──────────────────────────────────────────────────────────────
+
+DB_PATH        = Path(__file__).parent.parent / "leaderboard.db"
+BASELINES_JSON = Path(__file__).parent.parent / "data/baselines.json"
+
+TASK_SHORTS = ["REG", "NUM", "CON", "TMP"]
+
+CREATE_TABLE_SQL = """
+CREATE TABLE IF NOT EXISTS results (
+    id           INTEGER PRIMARY KEY AUTOINCREMENT,
+    model_id     TEXT    NOT NULL,
+    label        TEXT    NOT NULL,
+    hf_id        TEXT    NOT NULL,
+    params       TEXT    DEFAULT 'Unknown',
+    model_type   TEXT    DEFAULT 'Open',
+    overall      REAL    NOT NULL,
+    score_REG    REAL    DEFAULT 0.0,
+    score_NUM    REAL    DEFAULT 0.0,
+    score_CON    REAL    DEFAULT 0.0,
+    score_TMP    REAL    DEFAULT 0.0,
+    n_items      INTEGER DEFAULT 150,
+    submitted_at TEXT    NOT NULL,
+    is_baseline  INTEGER DEFAULT 0,
+    notes        TEXT    DEFAULT ''
+)
+"""
+
+
+# ── Connection helper ──────────────────────────────────────────────────────────
+
+def _connect() -> sqlite3.Connection:
+    """Open (or create) the leaderboard SQLite database.
+
+    Returns:
+        sqlite3.Connection with row_factory set to sqlite3.Row.
+    """
+    conn = sqlite3.connect(str(DB_PATH))
+    conn.row_factory = sqlite3.Row
+    return conn
+
+
+# ── Initialisation ─────────────────────────────────────────────────────────────
+
+def init_db() -> None:
+    """Create the results table and pre-populate with baseline models.
+
+    Safe to call multiple times — baselines are inserted only once (by hf_id).
+    """
+    conn = _connect()
+    with conn:
+        conn.execute(CREATE_TABLE_SQL)
+
+    # Load baselines from JSON
+    if not BASELINES_JSON.exists():
+        print(f"  [WARN] baselines.json not found at {BASELINES_JSON}")
+        conn.close()
+        return
+
+    with BASELINES_JSON.open(encoding="utf-8") as f:
+        baselines = json.load(f)
+
+    with conn:
+        for b in baselines:
+            # Only insert if this hf_id is not already present
+            existing = conn.execute(
+                "SELECT id FROM results WHERE hf_id = ?", (b["hf_id"],)
+            ).fetchone()
+            if existing:
+                continue
+
+            scores = b.get("scores", {})
+            conn.execute(
+                """INSERT INTO results
+                   (model_id, label, hf_id, params, model_type,
+                    overall, score_REG, score_NUM, score_CON, score_TMP,
+                    n_items, submitted_at, is_baseline)
+                   VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)""",
+                (
+                    b["model_id"], b["label"], b["hf_id"],
+                    b.get("params", "N/A"), b.get("type", "API"),
+                    b["overall"],
+                    scores.get("REG", 0.0), scores.get("NUM", 0.0),
+                    scores.get("CON", 0.0), scores.get("TMP", 0.0),
+                    b.get("n_items", 150),
+                    b.get("submitted", datetime.utcnow().strftime("%Y-%m-%d")),
+                    1,
+                ),
+            )
+
+    conn.close()
+    print(f"  DB initialised: {DB_PATH}")
+
+
+# ── Save result ────────────────────────────────────────────────────────────────
+
+def save_result(
+    hf_id:      str,
+    label:      str,
+    overall:    float,
+    per_task:   dict[str, float],
+    params:     str = "Unknown",
+    model_type: str = "Open",
+    n_items:    int = 150,
+    notes:      str = "",
+) -> int:
+    """Save a new evaluation result to the database.
+
+    Args:
+        hf_id:      HuggingFace model ID.
+        label:      Display name for the model.
+        overall:    Overall accuracy (0–1).
+        per_task:   Dict of task_short -> accuracy (0–1).
+        params:     Parameter count string (e.g. "7B").
+        model_type: "Open" or "API".
+        n_items:    Number of items evaluated.
+        notes:      Optional notes.
+
+    Returns:
+        Row id of the inserted record.
+    """
+    conn = _connect()
+    with conn:
+        cursor = conn.execute(
+            """INSERT INTO results
+               (model_id, label, hf_id, params, model_type,
+                overall, score_REG, score_NUM, score_CON, score_TMP,
+                n_items, submitted_at, is_baseline, notes)
+               VALUES (?,?,?,?,?,?,?,?,?,?,?,?,0,?)""",
+            (
+                hf_id.split("/")[-1], label, hf_id,
+                params, model_type, overall,
+                per_task.get("REG", 0.0), per_task.get("NUM", 0.0),
+                per_task.get("CON", 0.0), per_task.get("TMP", 0.0),
+                n_items,
+                datetime.utcnow().strftime("%Y-%m-%d %H:%M:%S"),
+                notes,
+            ),
+        )
+        row_id = cursor.lastrowid
+    conn.close()
+    return row_id
+
+
+# ── Leaderboard retrieval ──────────────────────────────────────────────────────
+
+def get_leaderboard(include_duplicates: bool = False) -> pd.DataFrame:
+    """Retrieve the leaderboard as a pandas DataFrame.
+
+    Args:
+        include_duplicates: If False (default), keep only the best submission
+                            per hf_id.
+
+    Returns:
+        DataFrame sorted by overall accuracy descending, with columns:
+        Rank, Model, HF ID, Params, Type, Overall, REG, NUM, CON, TMP, Submitted.
+    """
+    conn  = _connect()
+    query = "SELECT * FROM results ORDER BY overall DESC, submitted_at ASC"
+    df    = pd.read_sql_query(query, conn)
+    conn.close()
+
+    if df.empty:
+        return df
+
+    if not include_duplicates:
+        df = df.sort_values("overall", ascending=False).drop_duplicates(
+            subset="hf_id", keep="first"
+        )
+
+    df = df.sort_values("overall", ascending=False).reset_index(drop=True)
+    df.insert(0, "Rank", range(1, len(df) + 1))
+
+    display_cols = {
+        "label":      "Model",
+        "hf_id":      "HF Model ID",
+        "params":     "Params",
+        "model_type": "Type",
+        "overall":    "Overall (%)",
+        "score_REG":  "REG (%)",
+        "score_NUM":  "NUM (%)",
+        "score_CON":  "CON (%)",
+        "score_TMP":  "TMP (%)",
+        "submitted_at": "Submitted",
+    }
+    df = df.rename(columns=display_cols)
+
+    # Convert 0–1 floats to percentages
+    pct_cols = ["Overall (%)", "REG (%)", "NUM (%)", "CON (%)", "TMP (%)"]
+    for col in pct_cols:
+        if col in df.columns:
+            df[col] = (df[col] * 100).round(1)
+
+    out_cols = ["Rank", "Model", "HF Model ID", "Params", "Type",
+                "Overall (%)", "REG (%)", "NUM (%)", "CON (%)", "TMP (%)", "Submitted"]
+    return df[[c for c in out_cols if c in df.columns]]

demo/requirements.txt

@@ -0,0 +1,10 @@
+flask>=3.0
+pandas
+rapidfuzz
+gunicorn>=22.0
+numpy>=1.26
+faiss-cpu>=1.8,<2.0
+sentence-transformers>=3.0,<4.0
+rank-bm25>=0.2,<0.3
+groq>=0.11,<1.0
+tqdm>=4.66

demo/static/css/main.css

@@ -0,0 +1,808 @@
+/* ════════════════════════════════════════════════════════════════════
+   IndiaFinBench — "The Record"
+   Archival-editorial design system. Paper, ink, sealing wax, ledger green.
+   ════════════════════════════════════════════════════════════════════ */
+
+*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+:root {
+  --paper:      #F5F1E8;
+  --paper-hi:   #FBF8F1;
+  --paper-deep: #EDE7D9;
+  --ink:        #1C1812;
+  --ink-2:      #4A4338;
+  --ink-3:      #8B8270;
+  --rule:       rgba(28, 24, 18, 0.14);
+  --rule-soft:  rgba(28, 24, 18, 0.08);
+  --red:        #A33B20;
+  --red-soft:   rgba(163, 59, 32, 0.10);
+  --green:      #1F5C45;
+  --green-soft: rgba(31, 92, 69, 0.10);
+  --gold:       #96752A;
+  --gold-soft:  rgba(150, 117, 42, 0.12);
+  --saffron:    #C96F12;
+
+  --serif: 'Fraunces', Georgia, serif;
+  --sans:  'Archivo', system-ui, sans-serif;
+  --mono:  'IBM Plex Mono', ui-monospace, monospace;
+
+  --maxw: 1080px;
+  --ease: cubic-bezier(0.22, 0.61, 0.36, 1);
+}
+
+html { scroll-behavior: smooth; }
+
+body {
+  font-family: var(--sans);
+  background: var(--paper);
+  color: var(--ink);
+  line-height: 1.6;
+  font-size: 16px;
+  -webkit-font-smoothing: antialiased;
+  position: relative;
+}
+
+/* paper grain */
+body::before {
+  content: '';
+  position: fixed; inset: 0;
+  pointer-events: none; z-index: 1000;
+  opacity: 0.35;
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='160' height='160'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='2' stitchTiles='stitch'/%3E%3CfeColorMatrix values='0 0 0 0 0.11 0 0 0 0 0.09 0 0 0 0 0.07 0 0 0 0.04 0'/%3E%3C/filter%3E%3Crect width='160' height='160' filter='url(%23n)'/%3E%3C/svg%3E");
+}
+
+::selection { background: var(--red); color: var(--paper-hi); }
+
+#archiveCanvas {
+  position: fixed; inset: 0; width: 100vw; height: 100vh;
+  z-index: 0; pointer-events: none;
+}
+main, .footer { position: relative; z-index: 2; }
+
+:focus-visible { outline: 2px solid var(--red); outline-offset: 2px; }
+
+a { color: inherit; }
+.mono { font-family: var(--mono); }
+.c-red { color: var(--red); }
+.c-green { color: var(--green); }
+
+.skip-link {
+  position: absolute; left: -9999px; top: 0;
+  background: var(--ink); color: var(--paper); padding: 10px 18px;
+  font-size: 13px; z-index: 2000; text-decoration: none;
+}
+.skip-link:focus { left: 12px; top: 12px; }
+
+/* ════════ MASTHEAD ════════ */
+.masthead {
+  position: fixed; top: 0; left: 0; right: 0; z-index: 600;
+  background: color-mix(in srgb, var(--paper) 88%, transparent);
+  backdrop-filter: blur(14px) saturate(140%);
+  border-bottom: 1px solid var(--rule);
+}
+.masthead::after {
+  content: ''; display: block; height: 1px;
+  background: var(--rule-soft); margin-top: 2px;
+}
+.masthead-inner {
+  max-width: 1280px; margin: 0 auto;
+  height: 60px; padding: 0 24px;
+  display: flex; align-items: center; justify-content: space-between; gap: 16px;
+}
+.brand { display: flex; align-items: baseline; gap: 10px; text-decoration: none; }
+.brand-seal {
+  font-family: var(--serif); font-weight: 700; font-size: 22px;
+  color: var(--red); line-height: 1;
+}
+.brand-word {
+  font-family: var(--serif); font-size: 19px; font-weight: 600;
+  letter-spacing: -0.01em;
+}
+.brand-word em { font-style: italic; color: var(--red); }
+.mast-nav { display: flex; gap: 4px; }
+.mast-nav a {
+  font-size: 13px; font-weight: 500; color: var(--ink-2);
+  text-decoration: none; padding: 7px 11px; border-radius: 2px;
+  transition: color 0.15s, background 0.15s;
+}
+.mast-nav a:hover, .mast-nav a.active { color: var(--red); background: var(--red-soft); }
+.mast-actions { display: flex; align-items: center; gap: 8px; }
+.mast-btn {
+  font-size: 12.5px; font-weight: 600; text-decoration: none;
+  padding: 7px 14px; border: 1px solid var(--rule);
+  color: var(--ink-2); border-radius: 2px;
+  transition: border-color 0.15s, color 0.15s, background 0.15s;
+}
+.mast-btn:hover { border-color: var(--ink); color: var(--ink); }
+.mast-btn-solid { background: var(--ink); color: var(--paper-hi); border-color: var(--ink); }
+.mast-btn-solid:hover { background: var(--red); border-color: var(--red); color: var(--paper-hi); }
+.mast-menu {
+  display: none; flex-direction: column; gap: 5px;
+  background: none; border: none; cursor: pointer; padding: 8px;
+}
+.mast-menu span { width: 20px; height: 2px; background: var(--ink); transition: transform 0.2s; }
+.mast-menu[aria-expanded="true"] span:first-child { transform: translateY(3.5px) rotate(45deg); }
+.mast-menu[aria-expanded="true"] span:last-child { transform: translateY(-3.5px) rotate(-45deg); }
+.mast-drawer {
+  display: none; flex-direction: column;
+  border-top: 1px solid var(--rule); background: var(--paper-hi);
+}
+.mast-drawer.open { display: flex; }
+.mast-drawer a {
+  padding: 14px 24px; text-decoration: none; font-size: 14px;
+  font-family: var(--mono); color: var(--ink-2);
+  border-bottom: 1px solid var(--rule-soft);
+}
+.mast-drawer a:hover { color: var(--red); background: var(--red-soft); }
+
+/* ════════ PROGRESS RAIL ════════ */
+.rail {
+  position: fixed; left: 26px; top: 50%; transform: translateY(-50%);
+  z-index: 500; display: flex; gap: 14px; align-items: stretch;
+}
+.rail-line { width: 1px; background: var(--rule); position: relative; }
+.rail-fill {
+  position: absolute; top: 0; left: 0; width: 100%; height: 0%;
+  background: var(--red); transition: height 0.2s linear;
+}
+.rail-list { list-style: none; display: flex; flex-direction: column; gap: 18px; }
+.rail-list a {
+  display: flex; align-items: baseline; gap: 8px;
+  text-decoration: none; opacity: 0.45; transition: opacity 0.2s;
+}
+.rail-list a b { font-family: var(--mono); font-size: 10px; font-weight: 600; color: var(--red); }
+.rail-list a span {
+  font-size: 11px; font-weight: 500; letter-spacing: 0.06em;
+  text-transform: uppercase; color: var(--ink-2);
+}
+.rail-list li.on a, .rail-list a:hover { opacity: 1; }
+@media (max-width: 1320px) { .rail { display: none; } }
+
+/* ════════ BUTTONS / CHIPS / INPUTS ════════ */
+.btn {
+  display: inline-flex; align-items: center; justify-content: center; gap: 8px;
+  font-family: var(--sans); font-size: 14px; font-weight: 600;
+  padding: 12px 24px; border-radius: 2px; text-decoration: none;
+  cursor: pointer; transition: background 0.15s, color 0.15s, border-color 0.15s, transform 0.1s;
+  border: 1px solid transparent;
+}
+.btn:active { transform: translateY(1px); }
+.btn-ink { background: var(--ink); color: var(--paper-hi); border-color: var(--ink); }
+.btn-ink:hover { background: var(--red); border-color: var(--red); }
+.btn-ink:disabled { opacity: 0.45; cursor: not-allowed; }
+.btn-line { background: transparent; color: var(--ink); border-color: var(--rule); }
+.btn-line:hover { border-color: var(--red); color: var(--red); }
+.btn-sm { padding: 8px 16px; font-size: 13px; }
+
+.chip {
+  font-family: var(--sans); font-size: 12.5px; font-weight: 500;
+  padding: 7px 14px; background: var(--paper-hi);
+  border: 1px solid var(--rule); border-radius: 100px;
+  color: var(--ink-2); cursor: pointer;
+  transition: color 0.15s, border-color 0.15s;
+}
+.chip:hover { color: var(--red); border-color: var(--red); }
+
+.input, .select {
+  font-family: var(--sans); font-size: 14px; color: var(--ink);
+  background: var(--paper-hi); border: 1px solid var(--rule);
+  border-radius: 2px; padding: 11px 14px; outline: none; width: 100%;
+  transition: border-color 0.15s, box-shadow 0.15s;
+}
+.input:focus, .select:focus { border-color: var(--red); box-shadow: 0 0 0 3px var(--red-soft); }
+.input::placeholder { color: var(--ink-3); }
+.select { cursor: pointer; }
+
+/* ════════ HERO ════════ */
+.hero {
+  position: relative; z-index: 2;
+  padding: 168px 24px 0;
+  border-bottom: 1px solid var(--rule);
+}
+/* radial paper glow keeps the headline column clear of the archive scene */
+.hero::before {
+  content: ''; position: absolute; inset: 0; z-index: 1; pointer-events: none;
+  background: radial-gradient(ellipse 56% 54% at 50% 40%,
+    var(--paper) 30%,
+    color-mix(in srgb, var(--paper) 72%, transparent) 62%,
+    transparent 100%);
+}
+.hero-inner {
+  position: relative; z-index: 2;
+  max-width: var(--maxw); margin: 0 auto; text-align: center;
+}
+.hero-kicker {
+  font-family: var(--mono); font-size: 12px; font-weight: 500;
+  letter-spacing: 0.14em; text-transform: uppercase; color: var(--red);
+  margin-bottom: 28px;
+}
+.hero-kicker::before, .hero-kicker::after {
+  content: '———'; letter-spacing: -0.18em; color: var(--rule);
+  margin: 0 14px; vertical-align: 2px;
+}
+.hero-title {
+  font-family: var(--serif); font-optical-sizing: auto;
+  font-size: clamp(44px, 7.4vw, 96px); font-weight: 560;
+  line-height: 1.02; letter-spacing: -0.022em;
+  max-width: 15ch; margin: 0 auto 28px;
+}
+.hero-title em { font-style: italic; color: var(--red); }
+.hero-sub {
+  font-size: clamp(15px, 1.7vw, 18px); color: var(--ink-2);
+  max-width: 620px; margin: 0 auto 40px; line-height: 1.75;
+}
+.hero-sub strong { color: var(--ink); font-weight: 600; }
+.hero-cta { display: flex; justify-content: center; gap: 12px; flex-wrap: wrap; margin-bottom: 64px; }
+
+.hero-scrollcue {
+  font-family: var(--mono); font-size: 11px; font-weight: 500;
+  letter-spacing: 0.16em; text-transform: uppercase; color: var(--ink-3);
+  margin-bottom: 56px;
+}
+.cue-arrow { display: inline-block; margin-left: 10px; color: var(--red); animation: cue-drop 2s var(--ease) infinite; }
+@keyframes cue-drop { 0%, 100% { transform: translateY(0); } 50% { transform: translateY(5px); } }
+
+.hero-ledger {
+  position: relative; z-index: 2;
+  max-width: 1180px; margin: 0 auto;
+  display: grid; grid-template-columns: repeat(6, 1fr);
+  border: 1px solid var(--rule); border-bottom: none;
+  background: color-mix(in srgb, var(--paper-hi) 78%, transparent);
+  backdrop-filter: blur(6px);
+}
+.ledger-cell {
+  padding: 26px 18px 22px; text-align: center;
+  border-right: 1px solid var(--rule-soft);
+}
+.ledger-cell:last-child { border-right: none; }
+.ledger-num {
+  display: block; font-family: var(--serif); font-weight: 600;
+  font-size: clamp(26px, 3vw, 40px); letter-spacing: -0.02em;
+  font-variant-numeric: tabular-nums; line-height: 1.1; margin-bottom: 6px;
+}
+.ledger-cell:nth-child(odd) .ledger-num { color: var(--ink); }
+.ledger-cell:nth-child(even) .ledger-num { color: var(--red); }
+.ledger-lbl {
+  font-size: 10.5px; font-weight: 600; letter-spacing: 0.1em;
+  text-transform: uppercase; color: var(--ink-3);
+}
+@media (max-width: 980px) { .hero-ledger { grid-template-columns: repeat(3, 1fr); } .ledger-cell:nth-child(3) { border-right: none; } .ledger-cell:nth-child(-n+3) { border-bottom: 1px solid var(--rule-soft); } }
+@media (max-width: 560px) { .hero-ledger { grid-template-columns: repeat(2, 1fr); } .ledger-cell { border-right: 1px solid var(--rule-soft) !important; } .ledger-cell:nth-child(2n) { border-right: none !important; } .ledger-cell:nth-child(-n+4) { border-bottom: 1px solid var(--rule-soft); } }
+
+/* ════════ CHAPTERS ════════ */
+.chapter { padding: 110px 24px; position: relative; }
+.chapter > * { max-width: var(--maxw); margin-left: auto; margin-right: auto; }
+.ch-alt {
+  background: color-mix(in srgb, var(--paper-deep) 91%, transparent);
+  border-top: 1px solid var(--rule); border-bottom: 1px solid var(--rule);
+}
+
+.ch-head { margin-bottom: 56px; position: relative; }
+.ch-no {
+  font-family: var(--mono); font-size: 13px; font-weight: 600;
+  letter-spacing: 0.18em; color: var(--red);
+  display: inline-block; margin-bottom: 14px;
+}
+.ch-no::after {
+  content: ''; display: inline-block; width: 64px; height: 1px;
+  background: var(--red); margin-left: 16px; vertical-align: 4px; opacity: 0.5;
+}
+.ch-title {
+  font-family: var(--serif); font-size: clamp(34px, 4.6vw, 56px);
+  font-weight: 560; letter-spacing: -0.02em; line-height: 1.05;
+  margin-bottom: 14px;
+}
+.ch-lede {
+  font-family: var(--serif); font-style: italic; font-size: clamp(17px, 2vw, 21px);
+  color: var(--ink-2); max-width: 60ch;
+}
+
+.prose { font-size: 16px; line-height: 1.8; color: var(--ink-2); }
+.prose strong { color: var(--ink); }
+.prose-narrow { max-width: 70ch; margin-bottom: 48px; }
+
+/* vellum: frosted-paper panel that guarantees legibility over the scene */
+.vellum {
+  background: color-mix(in srgb, var(--paper) 70%, transparent);
+  -webkit-backdrop-filter: blur(10px) saturate(130%);
+  backdrop-filter: blur(10px) saturate(130%);
+  border: 1px solid var(--rule-soft);
+  padding: 30px 34px;
+}
+@supports not (backdrop-filter: blur(1px)) {
+  .vellum { background: color-mix(in srgb, var(--paper) 94%, transparent); }
+}
+
+.prose-cols {
+  columns: 2; column-gap: 56px; column-rule: 1px solid var(--rule-soft);
+  margin-bottom: 64px; font-size: 16px; line-height: 1.8; color: var(--ink-2);
+}
+.prose-cols p { break-inside: avoid; margin-bottom: 1em; }
+.prose-cols p:first-child::first-letter {
+  font-family: var(--serif); font-size: 3.4em; font-weight: 600;
+  float: left; line-height: 0.82; padding: 4px 10px 0 0; color: var(--red);
+}
+@media (max-width: 760px) { .prose-cols { columns: 1; } }
+
+/* ════════ §01 PROBLEM ════════ */
+.problem-grid {
+  display: grid; grid-template-columns: repeat(3, 1fr); gap: 1px;
+  background: var(--rule); border: 1px solid var(--rule);
+  margin-bottom: 72px;
+}
+@media (max-width: 820px) { .problem-grid { grid-template-columns: 1fr; } }
+.problem-card { background: var(--paper-hi); padding: 32px 28px; position: relative; }
+.pc-no {
+  font-family: var(--serif); font-style: italic; font-size: 30px;
+  color: var(--red); display: block; margin-bottom: 16px; line-height: 1;
+}
+.problem-card h3 {
+  font-family: var(--serif); font-size: 20px; font-weight: 600;
+  letter-spacing: -0.01em; margin-bottom: 10px;
+}
+.problem-card p { font-size: 14px; line-height: 1.7; color: var(--ink-2); }
+
+/* specimen exhibit */
+.specimen {
+  border: 1px solid var(--ink); background: var(--paper-hi);
+  box-shadow: 4px 4px 0 var(--rule-soft);
+  padding: 0;
+}
+.spec-head {
+  display: flex; align-items: center; justify-content: space-between; gap: 12px;
+  padding: 14px 24px; border-bottom: 1px solid var(--rule);
+}
+.spec-tag {
+  font-family: var(--mono); font-size: 11px; font-weight: 600;
+  letter-spacing: 0.14em; text-transform: uppercase;
+  color: var(--paper-hi); background: var(--red); padding: 4px 10px;
+}
+.spec-src { font-family: var(--mono); font-size: 12px; color: var(--ink-3); }
+.spec-body {
+  font-family: var(--serif); font-size: clamp(18px, 2.2vw, 23px);
+  line-height: 1.85; padding: 36px 40px; color: var(--ink);
+}
+.spec-body mark {
+  background: transparent; padding: 1px 3px; position: relative;
+  border-bottom: 2px solid; white-space: nowrap;
+}
+.m-num   { color: var(--red);    border-color: var(--red);    background: var(--red-soft); }
+.m-scope { color: var(--green);  border-color: var(--green);  background: var(--green-soft); }
+.m-ref   { color: var(--gold);   border-color: var(--gold);   background: var(--gold-soft); }
+.spec-body mark::after {
+  content: attr(data-note);
+  position: absolute; left: 50%; bottom: calc(100% + 8px); transform: translateX(-50%) translateY(4px);
+  font-family: var(--mono); font-size: 10.5px; font-style: normal; white-space: nowrap;
+  background: var(--ink); color: var(--paper-hi); padding: 5px 10px;
+  opacity: 0; pointer-events: none; transition: opacity 0.18s, transform 0.18s;
+}
+.spec-body mark:hover::after { opacity: 1; transform: translateX(-50%) translateY(0); }
+.spec-legend {
+  display: flex; flex-wrap: wrap; gap: 22px;
+  padding: 14px 24px; border-top: 1px solid var(--rule);
+  font-family: var(--mono); font-size: 11.5px; color: var(--ink-2);
+}
+.spec-legend span { display: inline-flex; align-items: center; gap: 8px; }
+.lg { width: 14px; height: 3px; display: inline-block; }
+.lg-num { background: var(--red); } .lg-scope { background: var(--green); } .lg-ref { background: var(--gold); }
+
+/* ════════ §02 CORPUS ════════ */
+.corpus-grid { display: grid; grid-template-columns: 5fr 6fr; gap: 56px; align-items: start; }
+@media (max-width: 880px) { .corpus-grid { grid-template-columns: 1fr; } }
+.corpus-copy .prose { margin-bottom: 32px; }
+.corpus-stats { border-top: 1px solid var(--rule); }
+.corpus-stats > div {
+  display: flex; justify-content: space-between; align-items: baseline;
+  padding: 11px 2px; border-bottom: 1px solid var(--rule-soft);
+}
+.corpus-stats dt { font-size: 13.5px; color: var(--ink-2); }
+.corpus-stats dd { font-size: 14px; font-weight: 600; }
+
+.doc-field { border: 1px solid var(--rule); background: var(--paper-hi); padding: 28px; }
+.doc-dots {
+  display: grid; grid-template-columns: repeat(16, 1fr); gap: 7px;
+  margin-bottom: 20px;
+}
+.doc-dots i {
+  aspect-ratio: 3 / 4; border-radius: 1px; display: block;
+  opacity: 0; transform: scale(0.4) ;
+  transition: opacity 0.4s var(--ease), transform 0.4s var(--ease);
+  transition-delay: var(--d, 0s);
+}
+.doc-dots.shown i { opacity: 1; transform: scale(1); }
+.doc-dots .sebi { background: var(--green); }
+.doc-dots .rbi { background: var(--red); }
+.doc-field figcaption {
+  display: flex; gap: 22px; align-items: center;
+  font-family: var(--mono); font-size: 12px; color: var(--ink-2);
+}
+.doc-field figcaption span { display: inline-flex; align-items: center; gap: 8px; }
+.doc-total { margin-left: auto; color: var(--ink); font-weight: 600; }
+.dot { width: 9px; height: 12px; border-radius: 1px; display: inline-block; }
+.dot-sebi { background: var(--green); } .dot-rbi { background: var(--red); }
+
+/* ════════ §03 BENCHMARK ════════ */
+.pipeline {
+  list-style: none; counter-reset: step;
+  display: grid; grid-template-columns: repeat(5, 1fr);
+  border: 1px solid var(--rule); background: var(--paper-hi);
+  margin-bottom: 64px;
+}
+@media (max-width: 940px) { .pipeline { grid-template-columns: 1fr; } }
+.pipeline li {
+  counter-increment: step;
+  padding: 26px 22px 24px; position: relative;
+  border-right: 1px solid var(--rule-soft);
+}
+.pipeline li:last-child { border-right: none; }
+@media (max-width: 940px) { .pipeline li { border-right: none; border-bottom: 1px solid var(--rule-soft); } .pipeline li:last-child { border-bottom: none; } }
+.pipeline li::before {
+  content: '0' counter(step);
+  font-family: var(--mono); font-size: 11px; font-weight: 600;
+  color: var(--red); letter-spacing: 0.12em; display: block; margin-bottom: 12px;
+}
+.pipeline li:not(:last-child)::after {
+  content: '→'; position: absolute; right: -7px; top: 28px;
+  color: var(--red); font-size: 14px; z-index: 2;
+}
+@media (max-width: 940px) { .pipeline li::after { display: none; } }
+.pipeline b {
+  display: block; font-family: var(--serif); font-size: 19px;
+  font-weight: 600; margin-bottom: 7px;
+}
+.pipeline span { font-size: 12.5px; line-height: 1.6; color: var(--ink-2); }
+
+.task-grid {
+  display: grid; grid-template-columns: repeat(4, 1fr); gap: 1px;
+  background: var(--rule); border: 1px solid var(--rule);
+  margin-bottom: 48px;
+}
+@media (max-width: 940px) { .task-grid { grid-template-columns: repeat(2, 1fr); } }
+@media (max-width: 560px) { .task-grid { grid-template-columns: 1fr; } }
+.task-card { background: var(--paper-hi); padding: 28px 24px; }
+.task-code {
+  font-family: var(--mono); font-size: 13px; font-weight: 600;
+  letter-spacing: 0.1em; padding: 3px 9px; border: 1px solid currentColor;
+  display: inline-block; margin-bottom: 16px;
+}
+.task-card h3 { font-family: var(--serif); font-size: 18px; font-weight: 600; margin-bottom: 8px; letter-spacing: -0.01em; }
+.task-card p { font-size: 13px; line-height: 1.65; color: var(--ink-2); margin-bottom: 16px; }
+.task-n { font-family: var(--mono); font-size: 12px; color: var(--ink-3); }
+.task-n b { color: var(--ink); font-weight: 600; }
+.task-meter { height: 3px; background: var(--rule-soft); margin-top: 10px; overflow: hidden; }
+.task-meter i { display: block; height: 100%; width: 0; transition: width 1.1s var(--ease) 0.2s; }
+.shown .task-meter i { width: var(--w); }
+
+.diff-strip { }
+.diff-bar-outer {
+  display: flex; height: 56px; border: 1px solid var(--rule);
+  background: var(--paper-hi); overflow: hidden; margin-bottom: 14px;
+}
+.diff-seg {
+  width: 0; display: flex; align-items: center; justify-content: center;
+  transition: width 1.2s var(--ease); overflow: hidden; position: relative;
+}
+.shown .diff-seg { width: var(--w); }
+.diff-seg span {
+  font-family: var(--mono); font-size: 12px; font-weight: 600; white-space: nowrap;
+}
+.ds-easy { background: var(--green-soft); color: var(--green); border-right: 1px solid var(--rule-soft); }
+.ds-med  { background: var(--gold-soft); color: var(--gold); border-right: 1px solid var(--rule-soft); }
+.ds-hard { background: var(--red-soft); color: var(--red); }
+.diff-note { font-size: 13px; color: var(--ink-3); }
+
+/* ════════ PANELS (shared) ════════ */
+.panel {
+  background: var(--paper-hi); border: 1px solid var(--rule);
+  padding: 32px; margin-bottom: 28px;
+}
+.panel-bar {
+  display: flex; align-items: flex-start; justify-content: space-between;
+  gap: 24px; flex-wrap: wrap; margin-bottom: 28px;
+}
+.panel-title { font-family: var(--serif); font-size: 24px; font-weight: 600; letter-spacing: -0.01em; margin-bottom: 6px; }
+.panel-sub { font-size: 13.5px; color: var(--ink-3); max-width: 64ch; }
+
+.tabset { display: inline-flex; border: 1px solid var(--rule); background: var(--paper); }
+.tab {
+  font-family: var(--mono); font-size: 12.5px; font-weight: 500;
+  padding: 9px 18px; background: none; border: none; cursor: pointer;
+  color: var(--ink-3); border-right: 1px solid var(--rule-soft);
+  transition: color 0.15s, background 0.15s;
+}
+.tab:last-child { border-right: none; }
+.tab:hover { color: var(--ink); }
+.tab.active { background: var(--ink); color: var(--paper-hi); }
+
+/* ════════ §04 CHART ════════ */
+.chart { position: relative; padding: 8px 0 30px; }
+.chart-baseline {
+  position: absolute; top: 0; bottom: 30px; width: 0;
+  border-left: 2px dashed var(--red); opacity: 0.55;
+  transition: left 0.9s var(--ease);
+  pointer-events: none; z-index: 3;
+}
+.chart-baseline em {
+  position: absolute; bottom: -26px; left: 50%; transform: translateX(-50%);
+  font-family: var(--mono); font-style: normal; font-size: 10.5px;
+  color: var(--red); white-space: nowrap;
+}
+.crow { display: flex; align-items: center; gap: 14px; margin-bottom: 9px; position: relative; }
+.crow-label {
+  width: 168px; min-width: 168px; text-align: right;
+  display: flex; align-items: baseline; justify-content: flex-end; gap: 8px;
+}
+.crow-rank { font-family: var(--serif); font-style: italic; font-size: 13px; color: var(--ink-3); }
+.crow-name {
+  font-size: 13.5px; font-weight: 600; white-space: nowrap;
+  overflow: hidden; text-overflow: ellipsis;
+}
+.crow-track { flex: 1; height: 34px; background: var(--rule-soft); position: relative; }
+.crow-fill {
+  height: 100%; width: 0; position: relative;
+  transition: width 1.1s var(--ease);
+  display: flex; align-items: center;
+}
+.crow-fill::after { content: ''; position: absolute; right: 0; top: 0; bottom: 0; width: 3px; background: var(--ink); }
+.t1 .crow-fill { background: var(--ink); }
+.t2 .crow-fill { background: color-mix(in srgb, var(--ink) 64%, var(--paper)); }
+.t3 .crow-fill { background: color-mix(in srgb, var(--ink) 40%, var(--paper)); }
+.t1 .crow-fill::after { background: var(--red); }
+.crow-val {
+  position: absolute; left: calc(100% + 10px); top: 50%; transform: translateY(-50%);
+  font-family: var(--mono); font-size: 12.5px; font-weight: 600;
+  color: var(--ink); white-space: nowrap; opacity: 0; transition: opacity 0.3s 0.7s;
+}
+.crow-fill.shown .crow-val { opacity: 1; }
+.crow-tip {
+  position: absolute; bottom: calc(100% + 10px); left: 50%; transform: translateX(-50%);
+  background: var(--ink); color: var(--paper-hi); padding: 12px 16px;
+  font-size: 12px; white-space: nowrap; z-index: 50;
+  opacity: 0; pointer-events: none; transition: opacity 0.15s;
+  box-shadow: 4px 4px 0 var(--rule);
+}
+.crow-track:hover .crow-tip { opacity: 1; }
+.crow-tip b { display: block; font-size: 13px; margin-bottom: 8px; padding-bottom: 7px; border-bottom: 1px solid rgba(251,248,241,0.25); }
+.crow-tip .tt-grid { display: grid; grid-template-columns: auto auto; gap: 3px 20px; font-family: var(--mono); font-size: 11.5px; }
+.crow-tip .tt-grid i { font-style: normal; color: rgba(251,248,241,0.55); }
+.crow-tip .tt-ci { margin-top: 7px; font-size: 10.5px; color: rgba(251,248,241,0.5); text-align: center; }
+.crow.human .crow-name { font-weight: 400; font-style: italic; color: var(--ink-2); }
+.crow.human .crow-fill { background: repeating-linear-gradient(135deg, var(--rule), var(--rule) 4px, transparent 4px, transparent 8px); }
+.crow.human .crow-fill::after { background: var(--ink-3); }
+.chart-foot { font-size: 12.5px; color: var(--ink-3); margin-top: 24px; max-width: 70ch; }
+.chart-foot strong { color: var(--ink-2); }
+@media (max-width: 640px) {
+  .crow-label { width: 108px; min-width: 108px; }
+  .crow-name { font-size: 12px; }
+  .crow-val { display: none; }
+}
+
+/* ════════ TABLES ════════ */
+.table-scroll { overflow-x: auto; }
+.gz-table { width: 100%; border-collapse: collapse; font-size: 13.5px; }
+.gz-table thead tr { border-top: 2px solid var(--ink); border-bottom: 1px solid var(--ink); }
+.gz-table th {
+  font-family: var(--mono); font-size: 11px; font-weight: 600;
+  text-transform: uppercase; letter-spacing: 0.08em; color: var(--ink-2);
+  text-align: left; padding: 12px 14px; white-space: nowrap; user-select: none;
+}
+.gz-table th.c, .gz-table td.c { text-align: center; }
+.gz-table th.sortable { cursor: pointer; }
+.gz-table th.sortable:hover { color: var(--red); }
+.gz-table th.sorted { color: var(--red); }
+.gz-table th.sorted::after { content: ' ↓'; }
+.th-n { font-size: 9.5px; color: var(--ink-3); text-transform: none; letter-spacing: 0; }
+.gz-table tbody tr { border-bottom: 1px solid var(--rule-soft); transition: background 0.12s; }
+.gz-table tbody tr:hover { background: var(--red-soft); }
+.gz-table td { padding: 13px 14px; white-space: nowrap; vertical-align: middle; }
+.gz-table td.mono, .gz-table .mono { font-family: var(--mono); font-size: 12.5px; }
+.row-hi { background: var(--green-soft); }
+.row-hi:hover { background: var(--green-soft) !important; }
+.cfg { font-family: var(--mono); font-size: 10.5px; color: var(--ink-3); margin-left: 6px; }
+.cfg-pick {
+  font-family: var(--mono); font-size: 10px; font-weight: 600;
+  text-transform: uppercase; letter-spacing: 0.08em;
+  background: var(--green); color: var(--paper-hi); padding: 2px 8px; margin-left: 8px;
+}
+
+.rank-cell { font-family: var(--serif); font-style: italic; font-size: 15px; }
+.rank-1 { color: var(--gold); font-weight: 700; }
+.model-cell-name { font-weight: 600; font-size: 13.5px; }
+.model-cell-id { font-family: var(--mono); font-size: 10.5px; color: var(--ink-3); margin-top: 2px; }
+.score {
+  font-family: var(--mono); font-size: 12.5px; font-weight: 600;
+  padding: 3px 8px; display: inline-block; min-width: 56px;
+}
+.s-hi { background: var(--green-soft); color: var(--green); }
+.s-md { background: var(--gold-soft); color: var(--gold); }
+.s-lo { background: var(--red-soft); color: var(--red); }
+.score-best { box-shadow: inset 0 0 0 1px currentColor; }
+.access-tag {
+  font-family: var(--mono); font-size: 10.5px; letter-spacing: 0.04em;
+  border: 1px solid var(--rule); padding: 3px 9px; color: var(--ink-2);
+  border-radius: 100px; white-space: nowrap;
+}
+.tr-human td { background: var(--paper); }
+.tr-human .model-cell-name { font-style: italic; font-weight: 400; }
+.tr-subset td { background: var(--gold-soft); }
+.ci-cell { font-family: var(--mono); font-size: 11px; color: var(--ink-3); }
+.delta-up { color: var(--green); font-weight: 600; }
+.delta-down { color: var(--red); font-weight: 600; }
+
+/* ════════ §05 FINDINGS ════════ */
+.findings-grid {
+  display: grid; grid-template-columns: repeat(3, 1fr); gap: 1px;
+  background: var(--rule); border: 1px solid var(--rule);
+}
+@media (max-width: 980px) { .findings-grid { grid-template-columns: repeat(2, 1fr); } }
+@media (max-width: 640px) { .findings-grid { grid-template-columns: 1fr; } }
+.finding { background: var(--paper-hi); padding: 32px 28px; position: relative; overflow: hidden; }
+.finding::before {
+  content: ''; position: absolute; top: 0; left: 0; right: 0; height: 3px;
+  background: var(--red); transform: scaleX(0); transform-origin: left;
+  transition: transform 0.7s var(--ease) 0.15s;
+}
+.finding.shown::before { transform: scaleX(1); }
+.f-no {
+  font-family: var(--mono); font-size: 10.5px; font-weight: 600;
+  letter-spacing: 0.16em; text-transform: uppercase; color: var(--ink-3);
+}
+.f-stat {
+  font-family: var(--serif); font-size: clamp(30px, 3.4vw, 42px);
+  font-weight: 600; letter-spacing: -0.02em; color: var(--red);
+  margin: 10px 0 14px; line-height: 1; font-variant-numeric: tabular-nums;
+}
+.finding h3 { font-family: var(--serif); font-size: 18.5px; font-weight: 600; letter-spacing: -0.01em; line-height: 1.3; margin-bottom: 10px; }
+.finding p:last-child { font-size: 13.5px; line-height: 1.7; color: var(--ink-2); }
+
+/* ════════ §06 RETRIEVAL ════════ */
+.rag-diagram { margin-bottom: 28px; border: 1px solid var(--rule); background: var(--paper-hi); padding: 24px 16px; }
+.rag-diagram svg { width: 100%; height: auto; display: block; color: var(--ink-3); }
+.rd-node rect { fill: var(--paper); stroke: var(--ink); stroke-width: 1.25; }
+.rd-dense rect { stroke: var(--green); } .rd-dense .rd-t1 { fill: var(--green); }
+.rd-sparse rect { stroke: var(--red); } .rd-sparse .rd-t1 { fill: var(--red); }
+.rd-rrf rect { fill: var(--ink); stroke: var(--ink); }
+.rd-rrf .rd-t1, .rd-rrf .rd-t2 { fill: var(--paper-hi); }
+.rd-t1 { font-family: var(--sans); font-size: 15px; font-weight: 600; fill: var(--ink); }
+.rd-t2 { font-family: var(--mono); font-size: 10px; fill: var(--ink-3); }
+.rd-rrf .rd-t2 { fill: rgba(251,248,241,0.6); }
+.rd-flow {
+  fill: none; stroke: var(--ink-3); stroke-width: 1.25;
+  stroke-dasharray: 5 5;
+}
+.shown .rd-flow { animation: flow 1.2s linear infinite; }
+@keyframes flow { to { stroke-dashoffset: -20; } }
+
+.panel-live { border-color: var(--ink); box-shadow: 5px 5px 0 var(--rule-soft); }
+.live-dot {
+  display: inline-block; width: 9px; height: 9px; border-radius: 50%;
+  background: var(--green); margin-right: 10px; vertical-align: 2px;
+  animation: pulse 2.2s ease infinite;
+}
+@keyframes pulse { 0%,100% { box-shadow: 0 0 0 0 var(--green-soft); } 50% { box-shadow: 0 0 0 7px var(--green-soft); } }
+.rag-row { display: flex; gap: 10px; margin-bottom: 14px; }
+.rag-input { flex: 1; }
+@media (max-width: 560px) { .rag-row { flex-direction: column; } }
+.rag-examples { display: flex; flex-wrap: wrap; gap: 8px; }
+.rag-out { margin-top: 26px; border-top: 1px solid var(--rule); padding-top: 22px; }
+.rag-status { display: flex; align-items: center; gap: 10px; font-family: var(--mono); font-size: 12.5px; color: var(--ink-2); margin-bottom: 14px; }
+.spinner {
+  width: 14px; height: 14px; border: 2px solid var(--rule);
+  border-top-color: var(--red); border-radius: 50%;
+  animation: spin 0.8s linear infinite;
+}
+@keyframes spin { to { transform: rotate(360deg); } }
+.rag-answer { font-size: 15px; line-height: 1.85; color: var(--ink); white-space: pre-wrap; margin-bottom: 22px; }
+.rag-answer:empty { margin: 0; }
+.rag-sources { display: grid; grid-template-columns: repeat(auto-fill, minmax(260px, 1fr)); gap: 14px; }
+.rag-src {
+  border: 1px solid var(--rule); background: var(--paper); padding: 16px;
+}
+.rag-src-no {
+  font-family: var(--mono); font-size: 10px; font-weight: 600;
+  letter-spacing: 0.14em; text-transform: uppercase; color: var(--red);
+  margin-bottom: 6px;
+}
+.rag-src-title { font-size: 13px; font-weight: 600; line-height: 1.4; margin-bottom: 8px; }
+.rag-src-text {
+  font-size: 12px; line-height: 1.65; color: var(--ink-2);
+  display: -webkit-box; -webkit-line-clamp: 5; -webkit-box-orient: vertical; overflow: hidden;
+  margin-bottom: 12px;
+}
+.rag-src-scores {
+  display: flex; gap: 12px; font-family: var(--mono); font-size: 10px;
+  color: var(--ink-3); border-top: 1px solid var(--rule-soft); padding-top: 9px;
+}
+.rag-src-scores b { color: var(--ink-2); font-weight: 600; }
+
+/* ════════ §07 ACCESS ════════ */
+.explorer-controls { display: flex; gap: 10px; flex-wrap: wrap; align-items: center; }
+.explorer-controls .select { width: auto; }
+.ex-card { border-top: 1px solid var(--rule); padding-top: 24px; }
+.ex-meta { display: flex; gap: 10px; align-items: center; flex-wrap: wrap; margin-bottom: 18px; }
+.ex-id { font-size: 11px; color: var(--ink-3); }
+.ex-badge {
+  font-family: var(--mono); font-size: 10.5px; font-weight: 600;
+  text-transform: uppercase; letter-spacing: 0.08em;
+  border: 1px solid var(--rule); padding: 3px 10px; color: var(--ink-2);
+}
+.ex-label {
+  font-family: var(--mono); font-size: 10.5px; font-weight: 600;
+  letter-spacing: 0.14em; text-transform: uppercase; color: var(--red);
+  margin-bottom: 7px;
+}
+.ex-context {
+  font-family: var(--serif); font-size: 16px; line-height: 1.8; color: var(--ink-2);
+  border-left: 2px solid var(--rule); padding: 4px 0 4px 20px; margin-bottom: 20px;
+}
+.ex-question { font-size: 16px; font-weight: 600; margin-bottom: 20px; }
+.ex-answer { margin-top: 18px; background: var(--green-soft); border: 1px solid var(--green); padding: 16px 20px; }
+.ex-answer .mono { font-size: 14px; color: var(--green); font-weight: 600; }
+
+.access-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 28px; align-items: start; }
+@media (max-width: 880px) { .access-grid { grid-template-columns: 1fr; } }
+.form-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; margin-bottom: 20px; }
+@media (max-width: 560px) { .form-grid { grid-template-columns: 1fr; } }
+.field { display: flex; flex-direction: column; gap: 6px; }
+.field > span { font-size: 12.5px; font-weight: 600; color: var(--ink-2); }
+.field em { color: var(--red); font-style: normal; }
+.form-foot { display: flex; flex-direction: column; gap: 14px; }
+.status { font-size: 13px; line-height: 1.6; padding: 12px 16px; border: 1px solid var(--rule); white-space: pre-line; }
+.status.ok { border-color: var(--green); background: var(--green-soft); color: var(--green); }
+.status.err { border-color: var(--red); background: var(--red-soft); color: var(--red); }
+
+.cite-box { position: relative; background: var(--paper); border: 1px solid var(--rule); padding: 18px 20px; margin-bottom: 18px; }
+.cite-box pre { font-size: 11.5px; line-height: 1.8; overflow-x: auto; color: var(--ink-2); }
+.copy-btn {
+  position: absolute; top: 10px; right: 10px;
+  font-family: var(--mono); font-size: 11px; font-weight: 600;
+  padding: 5px 12px; background: var(--paper-hi); border: 1px solid var(--rule);
+  cursor: pointer; color: var(--ink-2); transition: color 0.15s, border-color 0.15s;
+}
+.copy-btn:hover { color: var(--red); border-color: var(--red); }
+.access-links { display: flex; gap: 10px; flex-wrap: wrap; }
+
+/* ════════ FOOTER ════════ */
+.footer { padding: 64px 24px 56px; text-align: center; border-top: 1px solid var(--rule); position: relative; }
+.footer-rule {
+  width: 64px; height: 3px; background: var(--red); margin: 0 auto 28px;
+}
+.footer-brand { font-family: var(--serif); font-size: 22px; font-weight: 600; margin-bottom: 10px; }
+.footer-brand em { font-style: italic; color: var(--red); }
+.footer-brand .brand-seal { font-size: 18px; margin-right: 6px; }
+.footer-line { font-size: 14px; color: var(--ink-2); margin-bottom: 6px; }
+.footer-line a { color: var(--red); text-decoration: none; }
+.footer-line a:hover { text-decoration: underline; }
+.footer-sub { font-family: var(--mono); font-size: 11px; color: var(--ink-3); letter-spacing: 0.04em; }
+
+/* ════════ REVEAL ════════ */
+.reveal {
+  opacity: 0; transform: translateY(26px);
+  transition: opacity 0.8s var(--ease), transform 0.8s var(--ease);
+}
+.reveal.shown { opacity: 1; transform: translateY(0); }
+
+/* ════════ RESPONSIVE / MOTION ════════ */
+@media (max-width: 1060px) {
+  .mast-nav { display: none; }
+}
+@media (max-width: 680px) {
+  .mast-actions .mast-btn { display: none; }
+  .mast-menu { display: flex; }
+  .chapter { padding: 72px 18px; }
+  .hero { padding-top: 130px; }
+  .panel { padding: 22px 18px; }
+  .spec-body { padding: 26px 22px; }
+  .spec-body mark { white-space: normal; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  html { scroll-behavior: auto; }
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+  .reveal { opacity: 1; transform: none; }
+  .crow-fill, .diff-seg, .task-meter i { width: var(--w, 100%); }
+}

demo/static/js/archive-scene.js

@@ -0,0 +1,409 @@
+/* ════════════════════════════════════════════════════════════════════
+   IndiaFinBench — archive-scene.js
+   "The Archive Assembles": 192 regulatory documents rendered as ruled
+   paper cards in WebGL. Scroll morphs the field through three states —
+   drifting cloud (hero) → tangled supersession chains (§01) → ordered
+   archive wall, SEBI block then RBI block (§02) — then dissolves.
+   Raw WebGL + GLSL, no dependencies. Degrades silently without WebGL.
+   ════════════════════════════════════════════════════════════════════ */
+(function () {
+  'use strict';
+
+  var canvas = document.getElementById('archiveCanvas');
+  if (!canvas) return;
+  var gl = canvas.getContext('webgl', { alpha: true, antialias: true, premultipliedAlpha: false });
+  if (!gl) { canvas.remove(); return; }
+
+  var REDUCED = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+  var N_DOCS = 192, N_SEBI = 92;
+  var N_MOTES = window.innerWidth < 700 ? 110 : 240;
+
+  /* ── Shaders ──────────────────────────────────────────────────────── */
+  var DOC_VS = [
+    'attribute vec3 aCloud;',
+    'attribute vec3 aTangle;',
+    'attribute vec3 aGrid;',
+    'attribute vec2 aCorner;',
+    'attribute vec2 aMeta;', // x: kind (0 SEBI / 1 RBI), y: seed
+    'uniform mat4 uProj;',
+    'uniform mat4 uView;',
+    'uniform float uT1;',
+    'uniform float uT2;',
+    'uniform float uTime;',
+    'uniform float uSize;',
+    'varying vec2 vUv;',
+    'varying float vKind;',
+    'varying float vFade;',
+    'void main(){',
+    '  vec3 p = mix(aCloud, aTangle, uT1);',
+    '  p = mix(p, aGrid, uT2);',
+    '  float s = aMeta.y * 43.7;',
+    '  float calm = 1.0 - uT2 * 0.85;',
+    '  p += vec3(sin(uTime*0.40+s), cos(uTime*0.31+s*1.7), sin(uTime*0.23+s*2.3)) * 0.09 * calm;',
+    '  vec4 mv = uView * vec4(p, 1.0);',
+    '  mv.xy += aCorner * vec2(uSize, uSize*1.36);',
+    '  gl_Position = uProj * mv;',
+    '  vUv = aCorner * 0.5 + 0.5;',
+    '  vKind = aMeta.x;',
+    '  vFade = clamp(1.0 - (-mv.z - 4.0) / 13.0, 0.10, 0.85);',
+    '}'
+  ].join('\n');
+
+  var DOC_FS = [
+    'precision mediump float;',
+    'varying vec2 vUv;',
+    'varying float vKind;',
+    'varying float vFade;',
+    'uniform float uAlpha;',
+    'void main(){',
+    '  vec2 d = min(vUv, 1.0 - vUv);',
+    '  float border = 1.0 - step(0.07, min(d.x, d.y));',
+    // three ruled "text lines" inside the card
+    '  float lines = 0.0;',
+    '  if (vUv.x > 0.18 && vUv.x < 0.82 && vUv.y > 0.22 && vUv.y < 0.80) {',
+    '    lines = step(fract(vUv.y * 4.6), 0.14);',
+    '  }',
+    '  vec3 ink   = vec3(0.110, 0.094, 0.071);',
+    '  vec3 sebi  = vec3(0.122, 0.361, 0.271);',
+    '  vec3 rbi   = vec3(0.639, 0.231, 0.125);',
+    '  vec3 paper = vec3(0.961, 0.945, 0.910);',
+    '  vec3 tint  = mix(mix(sebi, rbi, vKind), paper, 0.30);', // muted toward paper
+    '  vec3 col   = mix(ink, tint, border);',
+    '  float a = border * 0.42 + lines * 0.13 + 0.03;',
+    '  gl_FragColor = vec4(col, a * uAlpha * vFade);',
+    '}'
+  ].join('\n');
+
+  var LINE_VS = [
+    'attribute vec3 aCloud;',
+    'attribute vec3 aTangle;',
+    'attribute vec3 aGrid;',
+    'uniform mat4 uProj;',
+    'uniform mat4 uView;',
+    'uniform float uT1;',
+    'uniform float uT2;',
+    'void main(){',
+    '  vec3 p = mix(aCloud, aTangle, uT1);',
+    '  p = mix(p, aGrid, uT2);',
+    '  gl_Position = uProj * uView * vec4(p, 1.0);',
+    '}'
+  ].join('\n');
+
+  var LINE_FS = [
+    'precision mediump float;',
+    'uniform float uAlpha;',
+    'void main(){ gl_FragColor = vec4(0.110, 0.094, 0.071, uAlpha); }'
+  ].join('\n');
+
+  var MOTE_VS = [
+    'attribute vec3 aPos;',
+    'attribute float aSeed;',
+    'uniform mat4 uProj;',
+    'uniform mat4 uView;',
+    'uniform float uTime;',
+    'void main(){',
+    '  vec3 p = aPos;',
+    '  float s = aSeed * 61.3;',
+    '  p += vec3(sin(uTime*0.18+s), cos(uTime*0.14+s*1.3), 0.0) * 0.45;',
+    '  vec4 mv = uView * vec4(p, 1.0);',
+    '  gl_Position = uProj * mv;',
+    '  gl_PointSize = clamp(36.0 / -mv.z, 1.0, 3.2);',
+    '}'
+  ].join('\n');
+
+  var MOTE_FS = [
+    'precision mediump float;',
+    'uniform float uAlpha;',
+    'void main(){ gl_FragColor = vec4(0.110, 0.094, 0.071, 0.09 * uAlpha); }'
+  ].join('\n');
+
+  function compile(type, src) {
+    var sh = gl.createShader(type);
+    gl.shaderSource(sh, src);
+    gl.compileShader(sh);
+    if (!gl.getShaderParameter(sh, gl.COMPILE_STATUS)) {
+      throw new Error(gl.getShaderInfoLog(sh) || 'shader compile failed');
+    }
+    return sh;
+  }
+  function program(vs, fs) {
+    var p = gl.createProgram();
+    gl.attachShader(p, compile(gl.VERTEX_SHADER, vs));
+    gl.attachShader(p, compile(gl.FRAGMENT_SHADER, fs));
+    gl.linkProgram(p);
+    if (!gl.getProgramParameter(p, gl.LINK_STATUS)) {
+      throw new Error(gl.getProgramInfoLog(p) || 'program link failed');
+    }
+    return p;
+  }
+
+  var docProg, lineProg, moteProg;
+  try {
+    docProg = program(DOC_VS, DOC_FS);
+    lineProg = program(LINE_VS, LINE_FS);
+    moteProg = program(MOTE_VS, MOTE_FS);
+  } catch (e) { canvas.remove(); return; }
+
+  /* ── Formations ───────────────────────────────────────────────────── */
+  var rand = (function () { // deterministic, so the scene is identical every visit
+    var s = 1337;
+    return function () { s = (s * 16807) % 2147483647; return (s - 1) / 2147483646; };
+  })();
+
+  var cloud = new Float32Array(N_DOCS * 3);
+  var tangle = new Float32Array(N_DOCS * 3);
+  var grid = new Float32Array(N_DOCS * 3);
+
+  // cloud: drifting halo around the text column — the centre stays empty
+  // so the hero headline and chapter prose are never occluded
+  for (var i = 0; i < N_DOCS; i++) {
+    var x, y;
+    do {
+      x = (rand() * 2 - 1) * 9.5;
+      y = (rand() * 2 - 1) * 4.6;
+    } while (Math.abs(x) < 3.6 && Math.abs(y) < 3.0); // keep-out rectangle
+    cloud[i * 3]     = x;
+    cloud[i * 3 + 1] = y;
+    cloud[i * 3 + 2] = -9.0 - rand() * 4.5;
+  }
+
+  // tangle: 12 supersession chains — random walks knotting deep and to the
+  // right, clear of the reading column
+  var CHAINS = 12, perChain = Math.ceil(N_DOCS / CHAINS), idx = 0;
+  for (var c = 0; c < CHAINS; c++) {
+    var x = 4.4 + (rand() - 0.5) * 4.6, y = (rand() - 0.5) * 4.2, z = -11.5 + (rand() - 0.5) * 2.5;
+    for (var k = 0; k < perChain && idx < N_DOCS; k++, idx++) {
+      x += (rand() - 0.5) * 1.4 - (x - 4.4) * 0.08;
+      y += (rand() - 0.5) * 1.1 - y * 0.06;
+      z += (rand() - 0.5) * 0.8;
+      tangle[idx * 3] = x; tangle[idx * 3 + 1] = y; tangle[idx * 3 + 2] = z;
+    }
+  }
+
+  // grid: 16 × 12 archive wall — SEBI block fills first, RBI block after.
+  // Sits deep so it reads as a watermark, not a competitor to the copy.
+  var COLS = 16, SX = 0.86, SY = 1.04;
+  for (i = 0; i < N_DOCS; i++) {
+    var col = i % COLS, row = Math.floor(i / COLS);
+    grid[i * 3]     = (col - (COLS - 1) / 2) * SX + 2.2;
+    grid[i * 3 + 1] = ((11 - row) - 5.5) * SY * 0.62;
+    grid[i * 3 + 2] = -13.5 + (rand() - 0.5) * 0.3;
+  }
+
+  /* ── Doc quad buffers (6 verts per doc) ───────────────────────────── */
+  var V = N_DOCS * 6;
+  var bCloud = new Float32Array(V * 3), bTangle = new Float32Array(V * 3),
+      bGrid = new Float32Array(V * 3), bCorner = new Float32Array(V * 2),
+      bMeta = new Float32Array(V * 2);
+  var CORNERS = [-1, -1, 1, -1, 1, 1, -1, -1, 1, 1, -1, 1];
+  for (i = 0; i < N_DOCS; i++) {
+    var kind = i < N_SEBI ? 0 : 1, seed = rand();
+    for (var v = 0; v < 6; v++) {
+      var o = i * 6 + v;
+      bCloud.set([cloud[i * 3], cloud[i * 3 + 1], cloud[i * 3 + 2]], o * 3);
+      bTangle.set([tangle[i * 3], tangle[i * 3 + 1], tangle[i * 3 + 2]], o * 3);
+      bGrid.set([grid[i * 3], grid[i * 3 + 1], grid[i * 3 + 2]], o * 3);
+      bCorner.set([CORNERS[v * 2], CORNERS[v * 2 + 1]], o * 2);
+      bMeta.set([kind, seed], o * 2);
+    }
+  }
+
+  /* ── Chain line buffers (consecutive docs within each chain) ──────── */
+  var linePairs = [];
+  idx = 0;
+  for (c = 0; c < CHAINS; c++) {
+    for (k = 0; k < perChain - 1 && idx + 1 < N_DOCS; k++, idx++) linePairs.push(idx, idx + 1);
+    idx++;
+  }
+  var L = linePairs.length;
+  var lCloud = new Float32Array(L * 3), lTangle = new Float32Array(L * 3), lGrid = new Float32Array(L * 3);
+  for (i = 0; i < L; i++) {
+    var di = linePairs[i];
+    lCloud.set([cloud[di * 3], cloud[di * 3 + 1], cloud[di * 3 + 2]], i * 3);
+    lTangle.set([tangle[di * 3], tangle[di * 3 + 1], tangle[di * 3 + 2]], i * 3);
+    lGrid.set([grid[di * 3], grid[di * 3 + 1], grid[di * 3 + 2]], i * 3);
+  }
+
+  /* ── Motes ────────────────────────────────────────────────────────── */
+  var mPos = new Float32Array(N_MOTES * 3), mSeed = new Float32Array(N_MOTES);
+  for (i = 0; i < N_MOTES; i++) {
+    mPos[i * 3] = (rand() - 0.5) * 18;
+    mPos[i * 3 + 1] = (rand() - 0.5) * 9;
+    mPos[i * 3 + 2] = -6 - rand() * 9;
+    mSeed[i] = rand();
+  }
+
+  function buf(data) {
+    var b = gl.createBuffer();
+    gl.bindBuffer(gl.ARRAY_BUFFER, b);
+    gl.bufferData(gl.ARRAY_BUFFER, data, gl.STATIC_DRAW);
+    return b;
+  }
+  var docBufs = { cloud: buf(bCloud), tangle: buf(bTangle), grid: buf(bGrid), corner: buf(bCorner), meta: buf(bMeta) };
+  var lineBufs = { cloud: buf(lCloud), tangle: buf(lTangle), grid: buf(lGrid) };
+  var moteBufs = { pos: buf(mPos), seed: buf(mSeed) };
+
+  /* ── Matrices ─────────────────────────────────────────────────────── */
+  function perspective(fovy, aspect, near, far) {
+    var f = 1 / Math.tan(fovy / 2), nf = 1 / (near - far);
+    return new Float32Array([
+      f / aspect, 0, 0, 0,
+      0, f, 0, 0,
+      0, 0, (far + near) * nf, -1,
+      0, 0, 2 * far * near * nf, 0
+    ]);
+  }
+  function viewMatrix(rx, ry) {
+    var cx = Math.cos(rx), sx = Math.sin(rx), cy = Math.cos(ry), sy = Math.sin(ry);
+    // rotateX(rx) * rotateY(ry), column-major
+    return new Float32Array([
+      cy, sx * sy, -cx * sy, 0,
+      0, cx, sx, 0,
+      sy, -sx * cy, cx * cy, 0,
+      0, 0, 0, 1
+    ]);
+  }
+
+  /* ── Uniform/attribute lookups ────────────────────────────────────── */
+  function locs(prog, attrs, unis) {
+    var out = { a: {}, u: {} };
+    attrs.forEach(function (n) { out.a[n] = gl.getAttribLocation(prog, n); });
+    unis.forEach(function (n) { out.u[n] = gl.getUniformLocation(prog, n); });
+    return out;
+  }
+  var docL = locs(docProg, ['aCloud', 'aTangle', 'aGrid', 'aCorner', 'aMeta'],
+    ['uProj', 'uView', 'uT1', 'uT2', 'uTime', 'uSize', 'uAlpha']);
+  var lineL = locs(lineProg, ['aCloud', 'aTangle', 'aGrid'], ['uProj', 'uView', 'uT1', 'uT2', 'uAlpha']);
+  var moteL = locs(moteProg, ['aPos', 'aSeed'], ['uProj', 'uView', 'uTime', 'uAlpha']);
+
+  function attrib(loc, b, size) {
+    gl.bindBuffer(gl.ARRAY_BUFFER, b);
+    gl.enableVertexAttribArray(loc);
+    gl.vertexAttribPointer(loc, size, gl.FLOAT, false, 0, 0);
+  }
+
+  /* ── State ────────────────────────────────────────────────────────── */
+  var proj, W = 0, H = 0;
+  var mouseX = 0, mouseY = 0, rotX = 0, rotY = 0;
+  var problemEl = document.getElementById('problem');
+  var corpusEl = document.getElementById('corpus');
+
+  function resize() {
+    var dpr = Math.min(window.devicePixelRatio || 1, 2);
+    W = window.innerWidth; H = window.innerHeight;
+    canvas.width = W * dpr; canvas.height = H * dpr;
+    gl.viewport(0, 0, canvas.width, canvas.height);
+    proj = perspective(50 * Math.PI / 180, W / H, 0.1, 60);
+  }
+  resize();
+  window.addEventListener('resize', resize);
+
+  if (!REDUCED) {
+    window.addEventListener('pointermove', function (e) {
+      mouseX = (e.clientX / W) * 2 - 1;
+      mouseY = (e.clientY / H) * 2 - 1;
+    }, { passive: true });
+  }
+
+  function smooth(t) { return t * t * (3 - 2 * t); }
+  function sectionT(el, span) {
+    if (!el) return 0;
+    var r = el.getBoundingClientRect();
+    return smooth(Math.max(0, Math.min(1, (H - r.top) / (H * span))));
+  }
+
+  function sceneAlpha() {
+    if (!corpusEl) return 1;
+    var r = corpusEl.getBoundingClientRect();
+    // fade out once the corpus section's bottom rises past 70% of the viewport
+    var f = Math.max(0, Math.min(1, (H * 0.7 - r.bottom) / (H * 0.45)));
+    return 1 - f;
+  }
+
+  /* ── Render ───────────────────────────────────────────────────────── */
+  gl.enable(gl.BLEND);
+  gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+  gl.clearColor(0, 0, 0, 0);
+
+  function draw(time, t1, t2, alpha) {
+    gl.clear(gl.COLOR_BUFFER_BIT);
+    if (alpha <= 0.005) return;
+    var view = viewMatrix(rotX, rotY);
+
+    // motes
+    gl.useProgram(moteProg);
+    attrib(moteL.a.aPos, moteBufs.pos, 3);
+    attrib(moteL.a.aSeed, moteBufs.seed, 1);
+    gl.uniformMatrix4fv(moteL.u.uProj, false, proj);
+    gl.uniformMatrix4fv(moteL.u.uView, false, view);
+    gl.uniform1f(moteL.u.uTime, time);
+    gl.uniform1f(moteL.u.uAlpha, alpha);
+    gl.drawArrays(gl.POINTS, 0, N_MOTES);
+
+    // chain lines: visible only inside the tangle phase
+    var lineAlpha = alpha * t1 * (1 - t2) * 0.11;
+    if (lineAlpha > 0.004) {
+      gl.useProgram(lineProg);
+      attrib(lineL.a.aCloud, lineBufs.cloud, 3);
+      attrib(lineL.a.aTangle, lineBufs.tangle, 3);
+      attrib(lineL.a.aGrid, lineBufs.grid, 3);
+      gl.uniformMatrix4fv(lineL.u.uProj, false, proj);
+      gl.uniformMatrix4fv(lineL.u.uView, false, view);
+      gl.uniform1f(lineL.u.uT1, t1);
+      gl.uniform1f(lineL.u.uT2, t2);
+      gl.uniform1f(lineL.u.uAlpha, lineAlpha);
+      gl.drawArrays(gl.LINES, 0, L);
+    }
+
+    // documents
+    gl.useProgram(docProg);
+    attrib(docL.a.aCloud, docBufs.cloud, 3);
+    attrib(docL.a.aTangle, docBufs.tangle, 3);
+    attrib(docL.a.aGrid, docBufs.grid, 3);
+    attrib(docL.a.aCorner, docBufs.corner, 2);
+    attrib(docL.a.aMeta, docBufs.meta, 2);
+    gl.uniformMatrix4fv(docL.u.uProj, false, proj);
+    gl.uniformMatrix4fv(docL.u.uView, false, view);
+    gl.uniform1f(docL.u.uT1, t1);
+    gl.uniform1f(docL.u.uT2, t2);
+    gl.uniform1f(docL.u.uTime, time);
+    var small = W < 700;
+    gl.uniform1f(docL.u.uSize, (small ? 0.115 : 0.16) + t2 * 0.08);
+    gl.uniform1f(docL.u.uAlpha, alpha * (small ? 0.55 : 0.85) * (1 - t2 * 0.3));
+    gl.drawArrays(gl.TRIANGLES, 0, V);
+  }
+
+  if (REDUCED) {
+    // single static frame: mid-cloud, no motion, no listeners beyond resize redraw
+    var staticDraw = function () { draw(0, 0, 0, 0.9); };
+    staticDraw();
+    window.addEventListener('resize', staticDraw);
+    return;
+  }
+
+  var running = false;
+  function frame(now) {
+    if (!running) return;
+    var t = now * 0.001;
+    rotY += ((mouseX * 0.10) - rotY) * 0.04;
+    rotX += ((mouseY * 0.06) - rotX) * 0.04;
+    var t1 = sectionT(problemEl, 0.95);
+    var t2 = sectionT(corpusEl, 0.85);
+    draw(t, t1, t2, sceneAlpha());
+    requestAnimationFrame(frame);
+  }
+  function startLoop() {
+    if (running) return;
+    running = true;
+    requestAnimationFrame(frame);
+  }
+
+  // one immediate frame so the scene exists even before the loop starts
+  draw(0, sectionT(problemEl, 0.95), sectionT(corpusEl, 0.85), sceneAlpha());
+
+  if (document.visibilityState === 'visible') startLoop();
+  document.addEventListener('visibilitychange', function () {
+    if (document.hidden) running = false;
+    else startLoop();
+  });
+})();

demo/static/js/data.js

@@ -0,0 +1,60 @@
+/* ════════════════════════════════════════════════════════════════════
+   IndiaFinBench — data.js
+   Canonical frontend leaderboard data. Mirrors results/aggregate/
+   all_model_results.csv (Table 6) — do not edit numbers by hand.
+   ════════════════════════════════════════════════════════════════════ */
+
+window.IFB_MODELS = [
+  { rank: 1,  label: "Gemini 2.5 Flash",  hf_id: "google/gemini-2.5-flash",                   params: "—",                   type: "Frontier API",    overall: 89.7, reg: 93.1, num: 84.8, con: 88.7, tmp: 88.5, ci: "[86.3%, 92.3%]", n_items: 406, tier: 1 },
+  { rank: 2,  label: "Qwen3-32B",         hf_id: "Qwen/Qwen3-32B",                            params: "32B",                 type: "Open-weight API", overall: 85.5, reg: 85.1, num: 77.2, con: 90.3, tmp: 92.3, ci: "[81.7%, 88.6%]", n_items: 406, tier: 1 },
+  { rank: 3,  label: "LLaMA-3.3-70B",     hf_id: "meta-llama/Llama-3.3-70B-Versatile",        params: "70B",                 type: "Open-weight API", overall: 83.7, reg: 86.2, num: 75.0, con: 95.2, tmp: 79.5, ci: "[79.8%, 87.0%]", n_items: 406, tier: 1 },
+  { rank: 4,  label: "Llama 4 Scout 17B", hf_id: "meta-llama/Llama-4-Scout-17B",              params: "17B",                 type: "Open-weight API", overall: 83.3, reg: 86.2, num: 66.3, con: 98.4, tmp: 84.6, ci: "[79.3%, 86.6%]", n_items: 406, tier: 1 },
+  { rank: 5,  label: "Kimi K2",           hf_id: "moonshotai/Kimi-K2",                        params: "1T (MoE, 32B active)", type: "Frontier API",   overall: 81.5, reg: 89.1, num: 65.2, con: 91.9, tmp: 75.6, ci: "[77.5%, 85.0%]", n_items: 406, tier: 1 },
+  { rank: 6,  label: "LLaMA-3-8B",        hf_id: "meta-llama/Meta-Llama-3-8B-Instruct",       params: "8B",                  type: "Local (Ollama)",  overall: 78.1, reg: 79.9, num: 64.1, con: 93.5, tmp: 78.2, ci: "[73.8%, 81.8%]", n_items: 406, tier: 2 },
+  { rank: 7,  label: "GPT-OSS 120B",      hf_id: "openai/gpt-oss-120b",                       params: "120B",                type: "Open-weight API", overall: 77.1, reg: 79.9, num: 59.8, con: 95.2, tmp: 76.9, ci: "[72.8%, 80.9%]", n_items: 406, tier: 2 },
+  { rank: 8,  label: "GPT-OSS 20B",       hf_id: "openai/gpt-oss-20b",                        params: "20B",                 type: "Open-weight API", overall: 76.8, reg: 79.9, num: 58.7, con: 95.2, tmp: 76.9, ci: "[72.5%, 80.7%]", n_items: 406, tier: 2 },
+  { rank: 9,  label: "Gemini 2.5 Pro",    hf_id: "google/gemini-2.5-pro",                     params: "—",                   type: "Frontier API",    overall: 76.1, reg: 89.7, num: 48.9, con: 93.5, tmp: 64.1, ci: "[71.7%, 80.0%]", n_items: 406, tier: 2 },
+  { rank: 10, label: "Mistral-7B",        hf_id: "mistralai/Mistral-7B-Instruct-v0.3",        params: "7B",                  type: "Local (Ollama)",  overall: 75.9, reg: 79.9, num: 66.3, con: 80.6, tmp: 74.4, ci: "[71.5%, 79.8%]", n_items: 406, tier: 2 },
+  { rank: 11, label: "DeepSeek R1 70B",   hf_id: "deepseek-ai/DeepSeek-R1-Distill-Llama-70B", params: "70B",                 type: "Reasoning API",   overall: 75.1, reg: 72.4, num: 69.6, con: 96.8, tmp: 70.5, ci: "[70.7%, 79.1%]", n_items: 406, tier: 2 },
+  { rank: 12, label: "Gemma 4 E4B",       hf_id: "google/gemma-4-e4b",                        params: "4B",                  type: "Local (Ollama)",  overall: 70.4, reg: 83.9, num: 50.0, con: 72.6, tmp: 62.8, ci: "[65.8%, 74.7%]", n_items: 406, tier: 3 }
+];
+
+window.IFB_HUMAN = {
+  rank: "—", label: "Human Expert", hf_id: "— (n=100 sampled items)",
+  params: "—", type: "Human Baseline",
+  overall: 69.0, reg: 55.6, num: 44.4, con: 83.3, tmp: 66.7,
+  ci: "[59.4%, 77.2%]", n_items: 100, tier: 0, is_human: true
+};
+
+window.IFB_CLAUDE = {
+  rank: "†", label: "†Claude 3 Haiku", hf_id: "anthropic/claude-3-haiku (150-item subset)",
+  params: "—", type: "Frontier API†",
+  overall: 91.3, reg: 92.5, num: 93.8, con: 86.7, tmp: 91.4,
+  ci: "[85.7%, 94.9%]", n_items: 150, is_subset: true
+};
+
+window.IFB_DIFF = [
+  { label: "Gemini 2.5 Flash",  easy: 92.5, med: 89.0, hard: 84.4 },
+  { label: "Qwen3-32B",         easy: 81.9, med: 87.9, hard: 87.5 },
+  { label: "LLaMA-3.3-70B",     easy: 79.4, med: 85.2, hard: 90.6 },
+  { label: "Llama 4 Scout 17B", easy: 82.5, med: 81.9, hard: 89.1 },
+  { label: "Kimi K2",           easy: 81.9, med: 80.8, hard: 82.8 },
+  { label: "LLaMA-3-8B",        easy: 76.2, med: 79.7, hard: 78.1 },
+  { label: "GPT-OSS 120B",      easy: 79.4, med: 76.4, hard: 73.4 },
+  { label: "GPT-OSS 20B",       easy: 75.0, med: 79.7, hard: 73.4 },
+  { label: "Gemini 2.5 Pro",    easy: 83.1, med: 72.5, hard: 68.8 },
+  { label: "Mistral-7B",        easy: 74.4, med: 76.9, hard: 76.6 },
+  { label: "DeepSeek R1 70B",   easy: 72.5, med: 77.5, hard: 75.0 },
+  { label: "Gemma 4 E4B",       easy: 82.5, med: 64.8, hard: 56.2 }
+];
+
+window.IFB_TASKS = [
+  { code: "REG", key: "reg", label: "Regulatory Interpretation", n: 174, color: "#1F5C45",
+    desc: "Extract compliance rules, thresholds and deadlines from SEBI and RBI regulatory text." },
+  { code: "NUM", key: "num", label: "Numerical Reasoning", n: 92, color: "#A33B20",
+    desc: "Arithmetic over capital ratios, dividend limits, and margin requirements in regulatory prose." },
+  { code: "CON", key: "con", label: "Contradiction Detection", n: 62, color: "#96752A",
+    desc: "Identify whether two regulatory passages contradict each other on a stated issue." },
+  { code: "TMP", key: "tmp", label: "Temporal Reasoning", n: 78, color: "#3B3F8C",
+    desc: "Sequence regulatory amendments and identify which circular was operative at a given time." }
+];

demo/static/js/main.js

@@ -0,0 +1,512 @@
+/* ════════════════════════════════════════════════════════════════════
+   IndiaFinBench — main.js
+   Chart, tables, canvas, scroll choreography, live RAG, explorer, submit.
+   Vanilla JS, no dependencies.
+   ════════════════════════════════════════════════════════════════════ */
+(function () {
+  'use strict';
+
+  var MODELS = window.IFB_MODELS || [];
+  var HUMAN = window.IFB_HUMAN || null;
+  var CLAUDE = window.IFB_CLAUDE || null;
+  var DIFF = window.IFB_DIFF || [];
+  var TASKS = window.IFB_TASKS || [];
+  var REDUCED = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+  var $ = function (s, c) { return (c || document).querySelector(s); };
+  var $$ = function (s, c) { return Array.prototype.slice.call((c || document).querySelectorAll(s)); };
+
+  var esc = function (s) {
+    return String(s == null ? '' : s).replace(/[&<>"']/g, function (ch) {
+      return { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[ch];
+    });
+  };
+
+  /* ── Deep links: jump instantly on load instead of animating from top ─ */
+  if (location.hash) {
+    var deepTarget = document.getElementById(location.hash.slice(1));
+    if (deepTarget) {
+      requestAnimationFrame(function () {
+        deepTarget.scrollIntoView({ behavior: 'instant', block: 'start' });
+      });
+    }
+  }
+
+  /* ── Masthead drawer ──────────────────────────────────────────────── */
+  var menuBtn = $('#menuBtn');
+  var drawer = $('#menuDrawer');
+  if (menuBtn && drawer) {
+    menuBtn.addEventListener('click', function () {
+      var open = drawer.classList.toggle('open');
+      menuBtn.setAttribute('aria-expanded', String(open));
+    });
+    $$('a', drawer).forEach(function (a) {
+      a.addEventListener('click', function () {
+        drawer.classList.remove('open');
+        menuBtn.setAttribute('aria-expanded', 'false');
+      });
+    });
+  }
+
+  /* ── Scroll reveal ────────────────────────────────────────────────── */
+  var revealIO = new IntersectionObserver(function (entries) {
+    entries.forEach(function (e) {
+      if (e.isIntersecting) {
+        e.target.classList.add('shown');
+        revealIO.unobserve(e.target);
+      }
+    });
+  }, { threshold: 0.12, rootMargin: '0px 0px -40px 0px' });
+
+  function watch(el) { if (el) revealIO.observe(el); }
+  $$('.reveal').forEach(watch);
+
+  /* ── Count-up numbers ─────────────────────────────────────────────── */
+  function countUp(el) {
+    var target = parseFloat(el.dataset.count);
+    var dec = parseInt(el.dataset.dec || '0', 10);
+    var suffix = el.dataset.suffix || '';
+    if (REDUCED) { el.textContent = target.toFixed(dec) + suffix; return; }
+    var t0 = null, DUR = 1400;
+    function frame(t) {
+      if (!t0) t0 = t;
+      var p = Math.min((t - t0) / DUR, 1);
+      var eased = 1 - Math.pow(1 - p, 3);
+      el.textContent = (target * eased).toFixed(dec) + suffix;
+      if (p < 1) requestAnimationFrame(frame);
+    }
+    requestAnimationFrame(frame);
+  }
+  var countIO = new IntersectionObserver(function (entries) {
+    entries.forEach(function (e) {
+      if (e.isIntersecting) { countUp(e.target); countIO.unobserve(e.target); }
+    });
+  }, { threshold: 0.4 });
+  $$('[data-count]').forEach(function (el) { countIO.observe(el); });
+
+  /* ── Progress rail ────────────────────────────────────────────────── */
+  var railFill = $('#railFill');
+  var railItems = $$('.rail-list li');
+  var chapterIds = railItems.map(function (li) { return li.dataset.ch; });
+
+  window.addEventListener('scroll', function () {
+    if (!railFill) return;
+    var h = document.documentElement.scrollHeight - window.innerHeight;
+    railFill.style.height = (h > 0 ? (window.scrollY / h) * 100 : 0) + '%';
+  }, { passive: true });
+
+  var chapterIO = new IntersectionObserver(function (entries) {
+    entries.forEach(function (e) {
+      if (e.isIntersecting) {
+        railItems.forEach(function (li) {
+          li.classList.toggle('on', li.dataset.ch === e.target.id);
+        });
+        $$('.mast-nav a').forEach(function (a) {
+          a.classList.toggle('active', a.getAttribute('href') === '#' + e.target.id);
+        });
+      }
+    });
+  }, { rootMargin: '-30% 0px -60% 0px' });
+  chapterIds.forEach(function (id) {
+    var sec = document.getElementById(id);
+    if (sec) chapterIO.observe(sec);
+  });
+
+  /* ── §02 Corpus: 192 document marks ───────────────────────────────── */
+  (function docDots() {
+    var holder = $('#docDots');
+    if (!holder) return;
+    var frag = document.createDocumentFragment();
+    for (var i = 0; i < 192; i++) {
+      var el = document.createElement('i');
+      el.className = i < 92 ? 'sebi' : 'rbi';
+      el.style.setProperty('--d', (i * 7) + 'ms');
+      frag.appendChild(el);
+    }
+    holder.appendChild(frag);
+    watchShown(holder);
+  })();
+
+  function watchShown(el) {
+    new IntersectionObserver(function (entries, io) {
+      entries.forEach(function (e) {
+        if (e.isIntersecting) { e.target.classList.add('shown'); io.unobserve(e.target); }
+      });
+    }, { threshold: 0.25 }).observe(el);
+  }
+
+  /* ── §03 Task cards ───────────────────────────────────────────────── */
+  (function taskCards() {
+    var grid = $('#taskGrid');
+    if (!grid || !TASKS.length) return;
+    grid.innerHTML = TASKS.map(function (t) {
+      var share = (t.n / 406) * 100;
+      return '<article class="task-card reveal">' +
+        '<span class="task-code" style="color:' + t.color + '">' + esc(t.code) + '</span>' +
+        '<h3>' + esc(t.label) + '</h3>' +
+        '<p>' + esc(t.desc) + '</p>' +
+        '<div class="task-n"><b>' + t.n + '</b> items · ' + share.toFixed(1) + '% of benchmark</div>' +
+        '<div class="task-meter"><i style="--w:' + share.toFixed(1) + '%;background:' + t.color + '"></i></div>' +
+        '</article>';
+    }).join('');
+    $$('.task-card', grid).forEach(function (card) { watch(card); watchShown(card); });
+  })();
+
+  /* ── §03 difficulty strip + diff segments need .shown ─────────────── */
+  $$('.diff-strip, .rag-diagram').forEach(watchShown);
+
+  /* ── §04 Chart ────────────────────────────────────────────────────── */
+  var METRIC_META = {
+    overall: { title: 'Overall accuracy', desc: 'All 406 items · zero-shot · 95% Wilson confidence intervals on hover' },
+    reg: { title: 'Regulatory Interpretation', desc: '174 items · precision reading of rules, thresholds and applicability' },
+    num: { title: 'Numerical Reasoning', desc: '92 items · arithmetic over figures embedded in regulatory prose' },
+    con: { title: 'Contradiction Detection', desc: '62 items · do two passages conflict on the stated issue?' },
+    tmp: { title: 'Temporal Reasoning', desc: '78 items · supersession chains and operative-date resolution' }
+  };
+
+  var chartEl = $('#barChart');
+  var chartShown = false;
+
+  function tipHTML(m) {
+    return '<b>' + esc(m.label) + '</b>' +
+      '<span class="tt-grid">' +
+      '<i>REG</i><span>' + m.reg.toFixed(1) + '%</span>' +
+      '<i>NUM</i><span>' + m.num.toFixed(1) + '%</span>' +
+      '<i>CON</i><span>' + m.con.toFixed(1) + '%</span>' +
+      '<i>TMP</i><span>' + m.tmp.toFixed(1) + '%</span>' +
+      '<i>Overall</i><span>' + m.overall.toFixed(1) + '%</span>' +
+      '</span>' +
+      (m.ci ? '<span class="tt-ci">95% CI ' + esc(m.ci) + ' · n = ' + m.n_items + '</span>' : '');
+  }
+
+  function buildChart(metric) {
+    if (!chartEl) return;
+    var rows = MODELS.slice();
+    if (HUMAN) rows.push(HUMAN);
+    rows.sort(function (a, b) { return b[metric] - a[metric]; });
+
+    var html = rows.map(function (m, idx) {
+      var v = m[metric];
+      var cls = m.is_human ? 'human' : ('t' + (m.tier || 2));
+      return '<div class="crow ' + cls + '">' +
+        '<div class="crow-label">' +
+        '<span class="crow-rank">' + (m.is_human ? '—' : (idx + 1)) + '</span>' +
+        '<span class="crow-name' + (m.is_human ? ' human' : '') + '">' + esc(m.label) + '</span>' +
+        '</div>' +
+        '<div class="crow-track">' +
+        '<div class="crow-fill" data-w="' + v + '"><span class="crow-val">' + v.toFixed(1) + '%</span></div>' +
+        '<div class="crow-tip" role="tooltip">' + tipHTML(m) + '</div>' +
+        '</div>' +
+        '</div>';
+    }).join('');
+    html += '<div class="chart-baseline" id="chartBaseline"><em>human baseline · ' +
+      (HUMAN ? HUMAN[metric].toFixed(1) : '—') + '%</em></div>';
+    chartEl.innerHTML = html;
+
+    function animate() {
+      $$('.crow-fill', chartEl).forEach(function (f) {
+        f.style.width = f.dataset.w + '%';
+        f.classList.add('shown');
+      });
+      positionBaseline(metric);
+    }
+    if (chartShown) {
+      requestAnimationFrame(function () { requestAnimationFrame(animate); });
+    } else {
+      new IntersectionObserver(function (entries, io) {
+        if (entries[0].isIntersecting) {
+          chartShown = true;
+          animate();
+          io.disconnect();
+        }
+      }, { threshold: 0.15 }).observe(chartEl);
+    }
+  }
+
+  function positionBaseline(metric) {
+    var line = $('#chartBaseline');
+    var track = $('.crow-track', chartEl);
+    if (!line || !track || !HUMAN) return;
+    var v = HUMAN[metric];
+    var left = track.offsetLeft + (track.offsetWidth * v / 100);
+    line.style.left = left + 'px';
+  }
+  window.addEventListener('resize', function () {
+    var active = $('.tab.active');
+    if (chartShown) positionBaseline(active ? active.dataset.t : 'overall');
+  });
+
+  $$('#taskTabs .tab').forEach(function (tab) {
+    tab.addEventListener('click', function () {
+      $$('#taskTabs .tab').forEach(function (t) {
+        t.classList.toggle('active', t === tab);
+        t.setAttribute('aria-selected', String(t === tab));
+      });
+      var k = tab.dataset.t;
+      $('#chartTitle').textContent = METRIC_META[k].title;
+      $('#chartDesc').textContent = METRIC_META[k].desc;
+      buildChart(k);
+    });
+  });
+  buildChart('overall');
+
+  /* ── §04 Results table ────────────────────────────────────────────── */
+  var sortKey = 'overall', sortAsc = false;
+
+  function scoreCell(v, isBest) {
+    var cls = v >= 85 ? 's-hi' : v >= 70 ? 's-md' : 's-lo';
+    return '<td class="c"><span class="score ' + cls + (isBest ? ' score-best' : '') + '">' + v.toFixed(1) + '</span></td>';
+  }
+
+  function buildTable() {
+    var body = $('#tBody');
+    if (!body) return;
+    var rows = MODELS.slice();
+    rows.sort(function (a, b) {
+      var x = a[sortKey], y = b[sortKey];
+      if (sortKey === 'params') { x = parseFloat(x) || 0; y = parseFloat(y) || 0; }
+      if (sortKey === 'rank') return sortAsc ? a.rank - b.rank : b.rank - a.rank;
+      return sortAsc ? x - y : y - x;
+    });
+
+    var best = {};
+    ['reg', 'num', 'con', 'tmp', 'overall'].forEach(function (k) {
+      best[k] = Math.max.apply(null, MODELS.map(function (m) { return m[k]; }));
+    });
+
+    var html = rows.map(function (m) {
+      return '<tr>' +
+        '<td class="c rank-cell' + (m.rank === 1 ? ' rank-1' : '') + '">' + m.rank + '</td>' +
+        '<td><div class="model-cell-name">' + esc(m.label) + '</div><div class="model-cell-id">' + esc(m.hf_id) + '</div></td>' +
+        '<td class="mono">' + esc(m.params) + '</td>' +
+        '<td><span class="access-tag">' + esc(m.type) + '</span></td>' +
+        scoreCell(m.reg, m.reg === best.reg) +
+        scoreCell(m.num, m.num === best.num) +
+        scoreCell(m.con, m.con === best.con) +
+        scoreCell(m.tmp, m.tmp === best.tmp) +
+        scoreCell(m.overall, m.overall === best.overall) +
+        '<td class="c ci-cell">' + esc(m.ci) + '</td>' +
+        '</tr>';
+    }).join('');
+
+    if (HUMAN) {
+      html += '<tr class="tr-human">' +
+        '<td class="c rank-cell">—</td>' +
+        '<td><div class="model-cell-name">' + esc(HUMAN.label) + '</div><div class="model-cell-id">' + esc(HUMAN.hf_id) + '</div></td>' +
+        '<td class="mono">—</td><td><span class="access-tag">Human baseline</span></td>' +
+        scoreCell(HUMAN.reg) + scoreCell(HUMAN.num) + scoreCell(HUMAN.con) + scoreCell(HUMAN.tmp) + scoreCell(HUMAN.overall) +
+        '<td class="c ci-cell">' + esc(HUMAN.ci) + '</td></tr>';
+    }
+    if (CLAUDE) {
+      html += '<tr class="tr-subset">' +
+        '<td class="c rank-cell">†</td>' +
+        '<td><div class="model-cell-name">' + esc(CLAUDE.label.replace('†', '')) + '</div><div class="model-cell-id">' + esc(CLAUDE.hf_id) + '</div></td>' +
+        '<td class="mono">—</td><td><span class="access-tag">150-item subset</span></td>' +
+        scoreCell(CLAUDE.reg) + scoreCell(CLAUDE.num) + scoreCell(CLAUDE.con) + scoreCell(CLAUDE.tmp) + scoreCell(CLAUDE.overall) +
+        '<td class="c ci-cell">' + esc(CLAUDE.ci) + '</td></tr>';
+    }
+    body.innerHTML = html;
+  }
+
+  $$('#resultsTable th.sortable').forEach(function (th) {
+    th.addEventListener('click', function () {
+      var k = th.dataset.k;
+      if (sortKey === k) sortAsc = !sortAsc;
+      else { sortKey = k; sortAsc = (k === 'rank'); }
+      $$('#resultsTable th').forEach(function (h) { h.classList.toggle('sorted', h === th); });
+      buildTable();
+    });
+  });
+  buildTable();
+
+  /* ── §04 Difficulty table ─────────────────────────────────────────── */
+  (function diffTable() {
+    var body = $('#diffBody');
+    if (!body || !DIFF.length) return;
+    body.innerHTML = DIFF.map(function (m) {
+      var d = m.hard - m.easy;
+      var sign = d >= 0 ? '+' : '−';
+      var cls = d >= 0 ? 'delta-up' : 'delta-down';
+      return '<tr>' +
+        '<td><div class="model-cell-name">' + esc(m.label) + '</div></td>' +
+        '<td class="c mono">' + m.easy.toFixed(1) + '%</td>' +
+        '<td class="c mono">' + m.med.toFixed(1) + '%</td>' +
+        '<td class="c mono">' + m.hard.toFixed(1) + '%</td>' +
+        '<td class="c mono ' + cls + '">' + sign + Math.abs(d).toFixed(1) + '</td>' +
+        '</tr>';
+    }).join('');
+  })();
+
+  /* ── §06 Live RAG ──────��──────────────────────────────────────────── */
+  (function rag() {
+    var input = $('#ragQ'), btn = $('#ragBtn');
+    var out = $('#ragOut'), status = $('#ragStatus'), statusText = $('#ragStatusText');
+    var answerEl = $('#ragAnswer'), sourcesEl = $('#ragSources');
+    if (!input || !btn) return;
+
+    var PHASES = ['Encoding query…', 'Searching 4,347 chunks…', 'Fusing dense and sparse ranks…', 'Drafting cited answer…'];
+    var phaseTimer = null;
+
+    function startPhases() {
+      var i = 0;
+      statusText.textContent = PHASES[0];
+      phaseTimer = setInterval(function () {
+        i = Math.min(i + 1, PHASES.length - 1);
+        statusText.textContent = PHASES[i];
+      }, 1500);
+    }
+    function stopPhases() { clearInterval(phaseTimer); }
+
+    function run() {
+      var q = input.value.trim();
+      if (!q) return;
+      btn.disabled = true;
+      out.hidden = false;
+      status.hidden = false;
+      answerEl.textContent = '';
+      sourcesEl.innerHTML = '';
+      startPhases();
+
+      fetch('/api/rag', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ query: q })
+      }).then(function (r) { return r.json(); }).then(function (data) {
+        stopPhases();
+        status.hidden = true;
+        if (data.error) {
+          answerEl.textContent = '⚠ ' + data.error;
+        } else {
+          answerEl.textContent = data.answer || '';
+          (data.sources || []).forEach(function (s, i) {
+            var card = document.createElement('div');
+            card.className = 'rag-src';
+            card.innerHTML =
+              '<div class="rag-src-no">Source ' + (i + 1) + ' · ' + esc(s.source || s.doc_id || '') + '</div>' +
+              '<div class="rag-src-title">' + esc(s.title || s.doc_id || 'Document') + '</div>' +
+              '<div class="rag-src-text">' + esc(s.text || '') + '</div>' +
+              '<div class="rag-src-scores">' +
+              '<span>RRF <b>' + (s.rrf_score != null ? Number(s.rrf_score).toFixed(4) : '—') + '</b></span>' +
+              '<span>dense <b>' + (s.dense_score != null ? Number(s.dense_score).toFixed(3) : '—') + '</b></span>' +
+              '<span>BM25 <b>' + (s.bm25_score != null ? Number(s.bm25_score).toFixed(2) : '—') + '</b></span>' +
+              '</div>';
+            sourcesEl.appendChild(card);
+          });
+        }
+        btn.disabled = false;
+      }).catch(function (e) {
+        stopPhases();
+        status.hidden = true;
+        answerEl.textContent = '⚠ Network error: ' + e.message;
+        btn.disabled = false;
+      });
+    }
+
+    btn.addEventListener('click', run);
+    input.addEventListener('keydown', function (e) { if (e.key === 'Enter') run(); });
+    $$('.rag-examples .chip').forEach(function (chip) {
+      chip.addEventListener('click', function () {
+        input.value = chip.dataset.q || chip.textContent.trim();
+        run();
+      });
+    });
+  })();
+
+  /* ── §07 Specimen explorer ────────────────────────────────────────── */
+  (function explorer() {
+    var btn = $('#exBtn');
+    if (!btn) return;
+    btn.addEventListener('click', function () {
+      btn.disabled = true;
+      var task = encodeURIComponent($('#exTask').value);
+      var diff = encodeURIComponent($('#exDiff').value);
+      fetch('/api/example?task=' + task + '&diff=' + diff)
+        .then(function (r) { return r.json(); })
+        .then(function (q) {
+          btn.disabled = false;
+          var card = $('#exCard');
+          if (q.error) {
+            card.hidden = false;
+            $('#exId').textContent = '';
+            $('#exTaskBadge').textContent = '';
+            $('#exDiffBadge').textContent = '';
+            $('#exContext').textContent = q.error;
+            $('#exQuestion').textContent = '';
+            $('#exReveal').hidden = true;
+            $('#exAnswer').hidden = true;
+            return;
+          }
+          card.hidden = false;
+          $('#exId').textContent = q.id || '';
+          $('#exTaskBadge').textContent = q.task_type || '';
+          $('#exDiffBadge').textContent = q.difficulty || '';
+          $('#exContext').textContent = q.context || '';
+          $('#exQuestion').textContent = q.question || '';
+          $('#exReveal').hidden = false;
+          $('#exAnswer').hidden = true;
+          $('#exAnswerText').textContent = q.answer || '';
+        })
+        .catch(function () { btn.disabled = false; });
+    });
+    $('#exReveal').addEventListener('click', function () {
+      $('#exAnswer').hidden = false;
+      this.hidden = true;
+    });
+  })();
+
+  /* ── §07 Submit ───────────────────────────────────────────────────── */
+  (function submit() {
+    var btn = $('#subBtn');
+    if (!btn) return;
+    btn.addEventListener('click', function () {
+      var hfId = $('#hfId').value.trim();
+      var box = $('#statusBox');
+      box.hidden = false;
+      box.className = 'status';
+      if (!hfId || hfId.indexOf('/') < 1) {
+        box.classList.add('err');
+        box.textContent = 'Enter a valid HuggingFace model ID (org/model).';
+        return;
+      }
+      btn.disabled = true;
+      box.textContent = 'Preparing submission…';
+      fetch('/api/submit', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          hf_id: hfId,
+          label: $('#dispName').value.trim(),
+          params: $('#modelParams').value.trim(),
+          model_type: $('#mtype').value
+        })
+      }).then(function (r) { return r.json(); }).then(function (data) {
+        btn.disabled = false;
+        if (data.issue_url) {
+          box.classList.add('ok');
+          box.textContent = 'Submission issue opened in a new tab — submit it on GitHub and the model joins the evaluation queue.';
+          window.open(data.issue_url, '_blank', 'noopener');
+        } else {
+          box.classList.add('err');
+          box.textContent = data.error || 'Submission failed.';
+        }
+      }).catch(function (e) {
+        btn.disabled = false;
+        box.classList.add('err');
+        box.textContent = 'Network error: ' + e.message;
+      });
+    });
+  })();
+
+  /* ── §07 Copy citation ────────────────────────────────────────────── */
+  (function cite() {
+    var btn = $('#copyBtn');
+    if (!btn) return;
+    btn.addEventListener('click', function () {
+      navigator.clipboard.writeText($('#citeText').textContent).then(function () {
+        btn.textContent = 'Copied';
+        setTimeout(function () { btn.textContent = 'Copy'; }, 1600);
+      });
+    });
+  })();
+
+})();

demo/templates/index.html

@@ -0,0 +1,547 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>IndiaFinBench — The First Benchmark for Indian Financial Regulation</title>
+<meta name="description" content="IndiaFinBench: 406 expert-annotated questions over 192 SEBI &amp; RBI regulatory documents (1992–2026). Twelve frontier LLMs evaluated. Hybrid RAG with Recall@5 = 0.785. Open dataset, open leaderboard.">
+<meta property="og:title" content="IndiaFinBench — Can language models read India's financial law?">
+<meta property="og:description" content="The first evaluation benchmark for LLM performance on Indian financial regulatory text. 406 questions · 192 documents · 12 models · open dataset.">
+<meta property="og:type" content="website">
+<meta property="og:url" content="https://huggingface.co/spaces/Rajveer-code/IndiaFinBench">
+<link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'%3E%3Crect width='64' height='64' rx='8' fill='%23F5F1E8'/%3E%3Ctext x='32' y='46' text-anchor='middle' font-family='Georgia,serif' font-size='40' font-weight='700' fill='%23A33B20'%3E%C2%A7%3C/text%3E%3C/svg%3E">
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Fraunces:ital,opsz,wght@0,9..144,400..700;1,9..144,400..700&family=Archivo:wght@400;500;600;700&family=IBM+Plex+Mono:ital,wght@0,400;0,500;0,600;1,400&display=swap" rel="stylesheet">
+<link rel="stylesheet" href="/static/css/main.css?v={{ js_ver }}">
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "Dataset",
+  "name": "IndiaFinBench",
+  "description": "An evaluation benchmark of 406 expert-annotated question-answer pairs over 192 SEBI and RBI regulatory documents (1992-2026), testing LLM performance on Indian financial regulatory text.",
+  "url": "https://github.com/Rajveer-code/IndiaFinBench",
+  "sameAs": "https://huggingface.co/datasets/Rajveer-code/IndiaFinBench",
+  "license": "https://creativecommons.org/licenses/by/4.0/",
+  "creator": { "@type": "Person", "name": "Rajveer Singh Pall" },
+  "keywords": ["LLM evaluation", "financial NLP", "Indian regulation", "SEBI", "RBI", "benchmark"]
+}
+</script>
+</head>
+<body>
+
+<canvas id="archiveCanvas" aria-hidden="true"></canvas>
+
+<a class="skip-link" href="#leaderboard">Skip to leaderboard</a>
+
+<!-- ════════ MASTHEAD ════════ -->
+<header class="masthead" id="masthead">
+  <div class="masthead-inner">
+    <a class="brand" href="#top" aria-label="IndiaFinBench — back to top">
+      <span class="brand-seal" aria-hidden="true">§</span>
+      <span class="brand-word">India<em>Fin</em>Bench</span>
+    </a>
+    <nav class="mast-nav" aria-label="Chapters">
+      <a href="#problem">Problem</a>
+      <a href="#corpus">Corpus</a>
+      <a href="#benchmark">Benchmark</a>
+      <a href="#leaderboard">Leaderboard</a>
+      <a href="#findings">Findings</a>
+      <a href="#retrieval">Retrieval</a>
+      <a href="#access">Access</a>
+    </nav>
+    <div class="mast-actions">
+      <a class="mast-btn" href="https://huggingface.co/datasets/Rajveer-code/IndiaFinBench" target="_blank" rel="noopener">Dataset</a>
+      <a class="mast-btn mast-btn-solid" href="https://github.com/Rajveer-code/IndiaFinBench" target="_blank" rel="noopener">GitHub</a>
+      <button class="mast-menu" id="menuBtn" aria-label="Open menu" aria-expanded="false">
+        <span></span><span></span>
+      </button>
+    </div>
+  </div>
+  <div class="mast-drawer" id="menuDrawer">
+    <a href="#problem">§ 01 — The Problem</a>
+    <a href="#corpus">§ 02 — The Corpus</a>
+    <a href="#benchmark">§ 03 — The Benchmark</a>
+    <a href="#leaderboard">§ 04 — The Evaluation</a>
+    <a href="#findings">§ 05 — The Findings</a>
+    <a href="#retrieval">§ 06 — The Retrieval</a>
+    <a href="#access">§ 07 — The Access</a>
+  </div>
+</header>
+
+<!-- ════════ PROGRESS RAIL ════════ -->
+<aside class="rail" id="rail" aria-hidden="true">
+  <div class="rail-line"><div class="rail-fill" id="railFill"></div></div>
+  <ol class="rail-list">
+    <li data-ch="problem"><a href="#problem"><b>01</b><span>Problem</span></a></li>
+    <li data-ch="corpus"><a href="#corpus"><b>02</b><span>Corpus</span></a></li>
+    <li data-ch="benchmark"><a href="#benchmark"><b>03</b><span>Benchmark</span></a></li>
+    <li data-ch="leaderboard"><a href="#leaderboard"><b>04</b><span>Evaluation</span></a></li>
+    <li data-ch="findings"><a href="#findings"><b>05</b><span>Findings</span></a></li>
+    <li data-ch="retrieval"><a href="#retrieval"><b>06</b><span>Retrieval</span></a></li>
+    <li data-ch="access"><a href="#access"><b>07</b><span>Access</span></a></li>
+  </ol>
+</aside>
+
+<main id="top">
+
+<!-- ════════ HERO ════════ -->
+<section class="hero">
+  <div class="hero-inner">
+    <p class="hero-kicker reveal">A research benchmark &amp; open dataset · EMNLP 2026 submission</p>
+    <h1 class="hero-title reveal">Can language models read India&rsquo;s <em>financial&nbsp;law?</em></h1>
+    <p class="hero-sub reveal">
+      IndiaFinBench is the first evaluation benchmark for large language models on Indian
+      financial regulatory text — <strong>406 expert-annotated questions</strong> drawn from
+      <strong>192 SEBI and RBI documents</strong> spanning thirty-four years of the regulatory record.
+    </p>
+    <div class="hero-cta reveal">
+      <a class="btn btn-ink" href="#leaderboard">Read the leaderboard</a>
+      <a class="btn btn-line" href="#retrieval">Query the corpus live</a>
+    </div>
+  </div>
+  <p class="hero-scrollcue reveal" aria-hidden="true">Scroll — the archive assembles<span class="cue-arrow">↓</span></p>
+  <div class="hero-ledger reveal" role="list" aria-label="Benchmark statistics">
+    <div class="ledger-cell" role="listitem"><span class="ledger-num" data-count="406">0</span><span class="ledger-lbl">expert-annotated questions</span></div>
+    <div class="ledger-cell" role="listitem"><span class="ledger-num" data-count="192">0</span><span class="ledger-lbl">RBI &amp; SEBI documents</span></div>
+    <div class="ledger-cell" role="listitem"><span class="ledger-num" data-count="12">0</span><span class="ledger-lbl">frontier models evaluated</span></div>
+    <div class="ledger-cell" role="listitem"><span class="ledger-num" data-count="0.785" data-dec="3">0</span><span class="ledger-lbl">Recall@5, hybrid retrieval</span></div>
+    <div class="ledger-cell" role="listitem"><span class="ledger-num" data-count="89.7" data-dec="1" data-suffix="%">0</span><span class="ledger-lbl">best model accuracy</span></div>
+    <div class="ledger-cell" role="listitem"><span class="ledger-num" data-count="69.0" data-dec="1" data-suffix="%">0</span><span class="ledger-lbl">human expert baseline</span></div>
+  </div>
+</section>
+
+<!-- ════════ §01 THE PROBLEM ════════ -->
+<section class="chapter" id="problem">
+  <header class="ch-head reveal">
+    <span class="ch-no">§ 01</span>
+    <h2 class="ch-title">The Problem</h2>
+    <p class="ch-lede">Benchmarks read English. Regulation reads differently.</p>
+  </header>
+
+  <div class="prose-cols vellum reveal">
+    <p>
+      Financial NLP benchmarks — FinQA, TAT-QA, FiQA — are built almost entirely on Western
+      corporate filings. None test whether a model can navigate the regulatory apparatus
+      governing the world&rsquo;s most populous market. Indian regulation poses three difficulties
+      that existing benchmarks never measure.
+    </p>
+    <p>
+      Numerical thresholds are buried in dense statutory prose, often written out in words.
+      Circulars supersede one another in long chains, so the <em>operative</em> rule at a given
+      date is a temporal-reasoning problem, not a lookup. And the vocabulary — LODR, PMLA,
+      AIF, FEMA, SFB — is jurisdiction-specific, thinly represented in Western training corpora.
+    </p>
+  </div>
+
+  <div class="problem-grid">
+    <article class="problem-card reveal">
+      <span class="pc-no">i</span>
+      <h3>Numbers hide in prose</h3>
+      <p>Capital ratios, margin requirements and filing deadlines appear as words inside clauses, not cells inside tables. Extraction requires precision reading, then arithmetic.</p>
+    </article>
+    <article class="problem-card reveal">
+      <span class="pc-no">ii</span>
+      <h3>Circulars supersede circulars</h3>
+      <p>A 2019 master circular may amend a 2014 directive that replaced a 1998 notification. Answering &ldquo;what rule applied in 2016?&rdquo; means untangling the chain.</p>
+    </article>
+    <article class="problem-card reveal">
+      <span class="pc-no">iii</span>
+      <h3>The vocabulary is sovereign</h3>
+      <p>LODR is not a typo and an AIF is not a hedge fund. Jurisdiction-specific terms of art carry exact legal meanings that general-purpose corpora rarely teach.</p>
+    </article>
+  </div>
+
+  <figure class="specimen reveal" aria-label="Annotated regulatory excerpt">
+    <figcaption class="spec-head">
+      <span class="spec-tag">Exhibit A</span>
+      <span class="spec-src">SEBI (LODR) Regulations · Regulation 33(3)(a)</span>
+    </figcaption>
+    <blockquote class="spec-body">
+      The listed entity shall submit quarterly and year-to-date standalone financial results to the
+      stock exchange within <mark class="m-num" data-note="numeral written as words">forty-five days</mark>
+      of end of each quarter, <mark class="m-scope" data-note="scope exception">other than the last quarter</mark>,
+      as per the requirements of <mark class="m-ref" data-note="cross-reference to resolve">Regulation&nbsp;33</mark>.
+    </blockquote>
+    <figcaption class="spec-legend">
+      <span><i class="lg lg-num"></i>numerical threshold in prose</span>
+      <span><i class="lg lg-scope"></i>scope exception</span>
+      <span><i class="lg lg-ref"></i>cross-reference</span>
+    </figcaption>
+  </figure>
+</section>
+
+<!-- ════════ §02 THE CORPUS ════════ -->
+<section class="chapter ch-alt" id="corpus">
+  <header class="ch-head reveal">
+    <span class="ch-no">§ 02</span>
+    <h2 class="ch-title">The Corpus</h2>
+    <p class="ch-lede">Thirty-four years of primary sources, read in full.</p>
+  </header>
+
+  <div class="corpus-grid">
+    <div class="corpus-copy vellum reveal">
+      <p class="prose">
+        Every question in IndiaFinBench traces to a primary-source document published by the
+        Securities and Exchange Board of India or the Reserve Bank of India between
+        <strong>1992 and 2026</strong> — circulars, master directions, notifications and
+        regulations, collected with full source URLs and parsed into a queryable corpus.
+      </p>
+      <dl class="corpus-stats">
+        <div><dt>SEBI documents</dt><dd class="mono c-green">92</dd></div>
+        <div><dt>RBI documents</dt><dd class="mono c-red">100</dd></div>
+        <div><dt>Document span</dt><dd class="mono">1992–2026</dd></div>
+        <div><dt>Indexed chunks</dt><dd class="mono">4,347</dd></div>
+        <div><dt>Chunk size</dt><dd class="mono">1,600 chars</dd></div>
+        <div><dt>License</dt><dd class="mono">Public domain (GoI)</dd></div>
+      </dl>
+    </div>
+    <figure class="doc-field reveal" aria-label="192 source documents: 92 SEBI, 100 RBI">
+      <div class="doc-dots" id="docDots"></div>
+      <figcaption><span><i class="dot dot-sebi"></i>SEBI &middot; 92</span><span><i class="dot dot-rbi"></i>RBI &middot; 100</span><span class="doc-total">192 documents</span></figcaption>
+    </figure>
+  </div>
+</section>
+
+<!-- ════════ §03 THE BENCHMARK ════════ -->
+<section class="chapter" id="benchmark">
+  <header class="ch-head reveal">
+    <span class="ch-no">§ 03</span>
+    <h2 class="ch-title">The Benchmark</h2>
+    <p class="ch-lede">From circular to question: a dual-validated construction.</p>
+  </header>
+
+  <ol class="pipeline reveal" aria-label="Benchmark construction pipeline">
+    <li><b>Collect</b><span>192 primary documents, 1992–2026, with source URLs</span></li>
+    <li><b>Author</b><span>QA pairs drafted against exact passages, four task types</span></li>
+    <li><b>Validate</b><span>model check on answerability — 90.7% agreement, κ = 0.918 (CON)</span></li>
+    <li><b>Adjudicate</b><span>human IAA on 180 items across 3 rounds — 77.2% agreement, κ = 0.645 (CON)</span></li>
+    <li><b>Release</b><span>406 items, CC BY 4.0, with per-item difficulty labels</span></li>
+  </ol>
+
+  <div class="task-grid" id="taskGrid"><!-- built by JS from IFB_TASKS --></div>
+
+  <div class="diff-strip reveal" aria-label="Difficulty distribution">
+    <div class="diff-bar-outer">
+      <div class="diff-seg ds-easy" style="--w:39.4%" title="Easy: 160 items"><span>Easy · 160</span></div>
+      <div class="diff-seg ds-med" style="--w:44.8%" title="Medium: 182 items"><span>Medium · 182</span></div>
+      <div class="diff-seg ds-hard" style="--w:15.8%" title="Hard: 64 items"><span>Hard · 64</span></div>
+    </div>
+    <p class="diff-note">Difficulty assigned at authoring time by reasoning depth — <em>hard</em> means multi-instrument tracking or compound arithmetic.</p>
+  </div>
+</section>
+
+<!-- ════════ §04 THE EVALUATION ════════ -->
+<section class="chapter ch-alt" id="leaderboard">
+  <header class="ch-head reveal">
+    <span class="ch-no">§ 04</span>
+    <h2 class="ch-title">The Evaluation</h2>
+    <p class="ch-lede">Twelve models. Zero shots. One human baseline to beat.</p>
+  </header>
+
+  <div class="panel reveal">
+    <div class="panel-bar">
+      <div>
+        <h3 class="panel-title" id="chartTitle">Overall accuracy</h3>
+        <p class="panel-sub" id="chartDesc">All 406 items · zero-shot · 95% Wilson confidence intervals on hover</p>
+      </div>
+      <div class="tabset" id="taskTabs" role="tablist" aria-label="Metric">
+        <button class="tab active" role="tab" aria-selected="true" data-t="overall">Overall</button>
+        <button class="tab" role="tab" aria-selected="false" data-t="reg">REG</button>
+        <button class="tab" role="tab" aria-selected="false" data-t="num">NUM</button>
+        <button class="tab" role="tab" aria-selected="false" data-t="con">CON</button>
+        <button class="tab" role="tab" aria-selected="false" data-t="tmp">TMP</button>
+      </div>
+    </div>
+    <div class="chart" id="barChart"></div>
+    <p class="chart-foot">Dashed rule marks the human expert baseline for the selected metric (n = 100). Paired bootstrap over all 66 model pairs resolves <strong>three statistically distinct tiers</strong>.</p>
+  </div>
+
+  <div class="panel reveal">
+    <div class="panel-bar">
+      <div>
+        <h3 class="panel-title">Full results</h3>
+        <p class="panel-sub">Click a column to sort · † Claude 3 Haiku scored 91.3% on the initial 150-item subset; listed separately as not directly comparable</p>
+      </div>
+    </div>
+    <div class="table-scroll">
+      <table class="gz-table" id="resultsTable">
+        <thead><tr>
+          <th class="c sortable" data-k="rank">#</th>
+          <th>Model</th>
+          <th class="sortable" data-k="params">Params</th>
+          <th>Access</th>
+          <th class="c sortable" data-k="reg">REG</th>
+          <th class="c sortable" data-k="num">NUM</th>
+          <th class="c sortable" data-k="con">CON</th>
+          <th class="c sortable" data-k="tmp">TMP</th>
+          <th class="c sortable sorted" data-k="overall">Overall</th>
+          <th class="c">95% CI</th>
+        </tr></thead>
+        <tbody id="tBody"></tbody>
+      </table>
+    </div>
+  </div>
+
+  <div class="panel reveal">
+    <div class="panel-bar">
+      <div>
+        <h3 class="panel-title">Accuracy by difficulty</h3>
+        <p class="panel-sub">Δ = hard − easy. LLaMA-3.3-70B <em>improves</em> on hard items; Gemma 4 E4B collapses by 26.3 points.</p>
+      </div>
+    </div>
+    <div class="table-scroll">
+      <table class="gz-table" id="diffTable">
+        <thead><tr><th>Model</th><th class="c">Easy <span class="th-n">n=160</span></th><th class="c">Medium <span class="th-n">n=182</span></th><th class="c">Hard <span class="th-n">n=64</span></th><th class="c">Δ</th></tr></thead>
+        <tbody id="diffBody"></tbody>
+      </table>
+    </div>
+  </div>
+</section>
+
+<!-- ════════ §05 THE FINDINGS ════════ -->
+<section class="chapter" id="findings">
+  <header class="ch-head reveal">
+    <span class="ch-no">§ 05</span>
+    <h2 class="ch-title">The Findings</h2>
+    <p class="ch-lede">What 4,872 graded answers say about regulatory reasoning.</p>
+  </header>
+
+  <div class="findings-grid">
+    <article class="finding reveal">
+      <span class="f-no">Finding 1</span>
+      <p class="f-stat">3 tiers</p>
+      <h3>Performance is tiered, and the tiers are real</h3>
+      <p>Paired bootstrap (10,000 resamples, all 66 pairs) separates frontier API models (81–90%), mid-tier open-weight models (75–79%), and a small-model floor at 70%. Most cross-tier gaps are significant at p &lt; 0.05.</p>
+    </article>
+    <article class="finding reveal">
+      <span class="f-no">Finding 2</span>
+      <p class="f-stat">17B ≈ 70B</p>
+      <h3>Scale alone does not buy regulatory reasoning</h3>
+      <p>Llama 4 Scout 17B statistically matches LLaMA-3.3-70B (p = 0.79) with a quarter of the parameters — and GPT-OSS 120B is indistinguishable from GPT-OSS 20B (p = 0.91, Δ = +0.3 pp).</p>
+    </article>
+    <article class="finding reveal">
+      <span class="f-no">Finding 3</span>
+      <p class="f-stat">35.9 pp</p>
+      <h3>Numerical reasoning is the discriminator</h3>
+      <p>NUM shows the widest spread of any task — from 84.8% (Gemini 2.5 Flash) down to 48.9% (Gemini 2.5 Pro). If you want to tell models apart, ask them to do arithmetic inside statute.</p>
+    </article>
+    <article class="finding reveal">
+      <span class="f-no">Finding 4</span>
+      <p class="f-stat">48.9% vs 89.7%</p>
+      <h3>Capability dissociates within a single model</h3>
+      <p>Gemini 2.5 Pro ranks first on regulatory interpretation yet last on numerical reasoning — task-type performance can split wide open inside the same weights.</p>
+    </article>
+    <article class="finding reveal">
+      <span class="f-no">Finding 5</span>
+      <p class="f-stat">11th / 12</p>
+      <h3>Reasoning-specialised ≠ timeline-capable</h3>
+      <p>DeepSeek R1 70B, built for chain-of-thought, ranks 11th overall and manages only 70.5% on temporal reasoning — general deliberation does not transfer to supersession chains.</p>
+    </article>
+    <article class="finding reveal">
+      <span class="f-no">Finding 6</span>
+      <p class="f-stat">12 / 12 &gt; human</p>
+      <h3>Every model beats the human baseline</h3>
+      <p>Human experts score 69.0% (n = 100, CI [59.4, 77.2]). All twelve models exceed it — yet the best still miss one answer in ten, in a domain where the answer is a legal obligation.</p>
+    </article>
+  </div>
+</section>
+
+<!-- ════════ §06 THE RETRIEVAL ════════ -->
+<section class="chapter ch-alt" id="retrieval">
+  <header class="ch-head reveal">
+    <span class="ch-no">§ 06</span>
+    <h2 class="ch-title">The Retrieval</h2>
+    <p class="ch-lede">The benchmark closes the book. The retrieval system opens it.</p>
+  </header>
+
+  <p class="prose prose-narrow reveal">
+    IndiaFinBench evaluates closed-book reading. Its open-book counterpart is a hybrid
+    retrieval system over the same 192-document corpus: dense semantic search and sparse
+    lexical search run in parallel, fused by reciprocal rank — because regulatory text,
+    saturated with citation identifiers, rewards exact matching as much as meaning.
+  </p>
+
+  <figure class="rag-diagram reveal" aria-label="Hybrid retrieval pipeline">
+    <svg viewBox="0 0 940 240" xmlns="http://www.w3.org/2000/svg" role="img">
+      <defs>
+        <marker id="arr" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+          <path d="M0 0L10 5L0 10z" fill="currentColor"/>
+        </marker>
+      </defs>
+      <g class="rd-node" transform="translate(10,90)">
+        <rect width="130" height="60" rx="3"/>
+        <text x="65" y="28" text-anchor="middle" class="rd-t1">Query</text>
+        <text x="65" y="45" text-anchor="middle" class="rd-t2">natural language</text>
+      </g>
+      <path class="rd-flow" d="M140 110 H 205 V 55 H 250" marker-end="url(#arr)"/>
+      <path class="rd-flow" d="M140 130 H 205 V 185 H 250" marker-end="url(#arr)"/>
+      <g class="rd-node rd-dense" transform="translate(250,25)">
+        <rect width="190" height="60" rx="3"/>
+        <text x="95" y="28" text-anchor="middle" class="rd-t1">Dense · FAISS</text>
+        <text x="95" y="45" text-anchor="middle" class="rd-t2">BGE · 768-d · 4,347 vectors</text>
+      </g>
+      <g class="rd-node rd-sparse" transform="translate(250,155)">
+        <rect width="190" height="60" rx="3"/>
+        <text x="95" y="28" text-anchor="middle" class="rd-t1">Sparse · BM25</text>
+        <text x="95" y="45" text-anchor="middle" class="rd-t2">lexical · 1,600-char chunks</text>
+      </g>
+      <path class="rd-flow" d="M440 55 H 505 V 105 H 530" marker-end="url(#arr)"/>
+      <path class="rd-flow" d="M440 185 H 505 V 135 H 530" marker-end="url(#arr)"/>
+      <g class="rd-node rd-rrf" transform="translate(530,90)">
+        <rect width="160" height="60" rx="3"/>
+        <text x="80" y="28" text-anchor="middle" class="rd-t1">RRF fusion</text>
+        <text x="80" y="45" text-anchor="middle" class="rd-t2">reciprocal rank · k = 60</text>
+      </g>
+      <path class="rd-flow" d="M690 120 H 780" marker-end="url(#arr)"/>
+      <g class="rd-node" transform="translate(780,90)">
+        <rect width="150" height="60" rx="3"/>
+        <text x="75" y="28" text-anchor="middle" class="rd-t1">Answer</text>
+        <text x="75" y="45" text-anchor="middle" class="rd-t2">LLaMA-3.3-70B · cited</text>
+      </g>
+    </svg>
+  </figure>
+
+  <div class="panel reveal">
+    <div class="panel-bar">
+      <div>
+        <h3 class="panel-title">Retrieval ablation</h3>
+        <p class="panel-sub">Six configurations. Hybrid fusion gains +9.7 points of Recall@5 over dense-only; BM25 alone wins MRR — lexical structure matters in law.</p>
+      </div>
+    </div>
+    <div class="table-scroll">
+      <table class="gz-table">
+        <thead><tr><th>Configuration</th><th class="c">Recall@5</th><th class="c">MRR</th><th class="c">p50 latency</th></tr></thead>
+        <tbody>
+          <tr><td>Dense only <span class="cfg">B0</span></td><td class="c mono">0.688</td><td class="c mono">0.542</td><td class="c mono">48 ms</td></tr>
+          <tr><td>BM25 only <span class="cfg">B1</span></td><td class="c mono">0.764</td><td class="c mono"><strong>0.674</strong></td><td class="c mono">30 ms</td></tr>
+          <tr class="row-hi"><td><strong>Hybrid RRF</strong> <span class="cfg">B2</span> <span class="cfg-pick">selected</span></td><td class="c mono"><strong>0.785</strong></td><td class="c mono">0.640</td><td class="c mono">77 ms</td></tr>
+          <tr><td>Small chunks, 800 chars <span class="cfg">B3</span></td><td class="c mono">0.583</td><td class="c mono">0.493</td><td class="c mono">138 ms</td></tr>
+          <tr><td>Large chunks, 2,400 chars <span class="cfg">B4</span></td><td class="c mono">0.542</td><td class="c mono">0.410</td><td class="c mono">71 ms</td></tr>
+          <tr><td>Hybrid, k = 10 <span class="cfg">B5</span></td><td class="c mono">0.785</td><td class="c mono">0.640</td><td class="c mono">78 ms</td></tr>
+        </tbody>
+      </table>
+    </div>
+  </div>
+
+  <div class="panel panel-live reveal" id="ragPanel">
+    <div class="panel-bar">
+      <div>
+        <h3 class="panel-title"><span class="live-dot" aria-hidden="true"></span>Ask the corpus</h3>
+        <p class="panel-sub">Live hybrid retrieval over all 192 documents — every claim sourced, every source scored.</p>
+      </div>
+    </div>
+    <div class="rag-row">
+      <input class="rag-input" id="ragQ" type="text" placeholder="What is the minimum capital adequacy ratio for banks?" aria-label="Question for the regulatory corpus">
+      <button class="btn btn-ink" id="ragBtn">Retrieve</button>
+    </div>
+    <div class="rag-examples" aria-label="Example queries">
+      <button class="chip" data-q="What is the circuit breaker limit for NSE stocks?">Circuit breaker limits</button>
+      <button class="chip" data-q="What is SEBI's definition of insider trading?">Insider trading definition</button>
+      <button class="chip" data-q="What is the minimum capital adequacy ratio for banks?">Capital adequacy ratio</button>
+      <button class="chip" data-q="What are the KYC requirements for opening a bank account?">KYC requirements</button>
+    </div>
+    <div class="rag-out" id="ragOut" hidden>
+      <div class="rag-status" id="ragStatus" hidden><span class="spinner" aria-hidden="true"></span><span id="ragStatusText">Retrieving from corpus…</span></div>
+      <div class="rag-answer" id="ragAnswer"></div>
+      <div class="rag-sources" id="ragSources"></div>
+    </div>
+  </div>
+</section>
+
+<!-- ════════ §07 THE ACCESS ════════ -->
+<section class="chapter" id="access">
+  <header class="ch-head reveal">
+    <span class="ch-no">§ 07</span>
+    <h2 class="ch-title">The Access</h2>
+    <p class="ch-lede">An open dataset, an open leaderboard, an open invitation.</p>
+  </header>
+
+  <div class="panel reveal" id="explorerPanel">
+    <div class="panel-bar">
+      <div>
+        <h3 class="panel-title">Examine a specimen</h3>
+        <p class="panel-sub">Draw a random item from the 406 — filtered by task and difficulty, answer sealed until you ask.</p>
+      </div>
+      <div class="explorer-controls">
+        <select class="select" id="exTask" aria-label="Task type">
+          <option value="All">All tasks</option>
+          <option value="Regulatory Interpretation">Regulatory Interpretation</option>
+          <option value="Numerical Reasoning">Numerical Reasoning</option>
+          <option value="Contradiction Detection">Contradiction Detection</option>
+          <option value="Temporal Reasoning">Temporal Reasoning</option>
+        </select>
+        <select class="select" id="exDiff" aria-label="Difficulty">
+          <option value="All">All difficulties</option>
+          <option value="Easy">Easy</option>
+          <option value="Medium">Medium</option>
+          <option value="Hard">Hard</option>
+        </select>
+        <button class="btn btn-ink" id="exBtn">Draw item</button>
+      </div>
+    </div>
+    <div class="ex-card" id="exCard" hidden>
+      <div class="ex-meta"><span class="ex-id mono" id="exId"></span><span class="ex-badge" id="exTaskBadge"></span><span class="ex-badge" id="exDiffBadge"></span></div>
+      <p class="ex-label">Context</p>
+      <blockquote class="ex-context" id="exContext"></blockquote>
+      <p class="ex-label">Question</p>
+      <p class="ex-question" id="exQuestion"></p>
+      <button class="btn btn-line btn-sm" id="exReveal">Unseal answer</button>
+      <div class="ex-answer" id="exAnswer" hidden><p class="ex-label">Gold answer</p><p class="mono" id="exAnswerText"></p></div>
+    </div>
+  </div>
+
+  <div class="access-grid">
+    <div class="panel reveal">
+      <div class="panel-bar"><div><h3 class="panel-title">Submit a model</h3><p class="panel-sub">Any public HuggingFace model, evaluated zero-shot on all 406 items with four-stage scoring. Results join the leaderboard with Wilson CIs.</p></div></div>
+      <div class="form-grid">
+        <label class="field"><span>HuggingFace model ID <em>*</em></span><input class="input" id="hfId" type="text" placeholder="mistralai/Mistral-7B-Instruct-v0.3"></label>
+        <label class="field"><span>Display name</span><input class="input" id="dispName" type="text" placeholder="Mistral-7B"></label>
+        <label class="field"><span>Parameters</span><input class="input" id="modelParams" type="text" placeholder="7B"></label>
+        <label class="field"><span>Model type</span>
+          <select class="select" id="mtype"><option>Frontier API</option><option>Open-weight API</option><option>Local (Ollama)</option><option>Reasoning API</option></select>
+        </label>
+      </div>
+      <div class="form-foot">
+        <button class="btn btn-ink" id="subBtn">Open submission issue</button>
+        <p class="status" id="statusBox" role="status" hidden></p>
+      </div>
+    </div>
+
+    <div class="panel reveal">
+      <div class="panel-bar"><div><h3 class="panel-title">Cite the record</h3><p class="panel-sub">Dataset CC BY 4.0 · code MIT · source documents public domain (Government of India).</p></div></div>
+      <div class="cite-box">
+        <button class="copy-btn" id="copyBtn">Copy</button>
+<pre class="mono" id="citeText">{% raw %}@article{pall2026indiafinbench,
+  title   = {{IndiaFinBench}: An Evaluation Benchmark
+             for LLM Performance on Indian Financial
+             Regulatory Text},
+  author  = {Pall, Rajveer Singh},
+  journal = {Proceedings of EMNLP},
+  year    = {2026},
+  url     = {https://github.com/Rajveer-code/IndiaFinBench}
+}{% endraw %}</pre>
+      </div>
+      <div class="access-links">
+        <a class="btn btn-line" href="https://huggingface.co/datasets/Rajveer-code/IndiaFinBench" target="_blank" rel="noopener">Dataset on HuggingFace</a>
+        <a class="btn btn-line" href="https://github.com/Rajveer-code/IndiaFinBench" target="_blank" rel="noopener">Code on GitHub</a>
+      </div>
+    </div>
+  </div>
+</section>
+
+</main>
+
+<!-- ════════ FOOTER ════════ -->
+<footer class="footer">
+  <div class="footer-rule" aria-hidden="true"></div>
+  <p class="footer-brand"><span class="brand-seal">§</span> India<em>Fin</em>Bench</p>
+  <p class="footer-line">Rajveer Singh Pall · Gyan Ganga Institute of Technology and Sciences · <a href="mailto:rajveerpall04@gmail.com">rajveerpall04@gmail.com</a></p>
+  <p class="footer-sub">406 questions · 192 documents · 12 models · zero-shot · dataset CC BY 4.0 · code MIT</p>
+</footer>
+
+<script src="/static/js/data.js?v={{ js_ver }}"></script>
+<script src="/static/js/main.js?v={{ js_ver }}" defer></script>
+<script src="/static/js/archive-scene.js?v={{ js_ver }}" defer></script>
+</body>
+</html>

demo/tests/test_app.py

@@ -0,0 +1,143 @@
+"""
+Tests for demo/app.py API endpoints.
+Run from repo root: pytest demo/tests/test_app.py -v
+"""
+import json
+import sys
+from pathlib import Path
+
+# Mirror the exact sys.path setup that demo/app.py uses at runtime:
+# ROOT first (so `import rag` resolves to /repo/rag/), DEMO second.
+_DEMO_DIR = Path(__file__).parent.parent   # demo/
+_ROOT_DIR  = _DEMO_DIR.parent              # repo root
+
+if str(_ROOT_DIR) not in sys.path:
+    sys.path.insert(0, str(_ROOT_DIR))
+if str(_DEMO_DIR) not in sys.path:
+    sys.path.insert(1, str(_DEMO_DIR))
+
+import pytest
+
+# Importing app triggers init_db() and the RAG warmup background thread.
+from app import app as flask_app
+
+
+@pytest.fixture
+def client():
+    flask_app.config["TESTING"] = True
+    with flask_app.test_client() as c:
+        yield c
+
+
+class TestIndex:
+    def test_returns_200(self, client):
+        r = client.get("/")
+        assert r.status_code == 200
+
+    def test_contains_brand(self, client):
+        r = client.get("/")
+        assert b"IndiaFinBench" in r.data
+
+
+class TestLeaderboard:
+    def test_returns_json_list(self, client):
+        r = client.get("/api/leaderboard")
+        assert r.status_code == 200
+        data = json.loads(r.data)
+        assert isinstance(data, list)
+
+    def test_has_at_least_9_models(self, client):
+        r = client.get("/api/leaderboard")
+        data = json.loads(r.data)
+        models = [m for m in data if not m.get("is_human")]
+        assert len(models) >= 9
+
+    def test_each_model_has_required_keys(self, client):
+        r = client.get("/api/leaderboard")
+        data = json.loads(r.data)
+        for m in data:
+            for key in ("label", "overall", "reg", "num", "con", "tmp"):
+                assert key in m, f"Missing key '{key}' in model {m.get('label')}"
+
+
+class TestExample:
+    def test_returns_question(self, client):
+        r = client.get("/api/example")
+        assert r.status_code == 200
+        data = json.loads(r.data)
+        assert "question" in data
+        assert "answer" in data
+        assert "task_type" in data
+
+    def test_task_filter(self, client):
+        r = client.get("/api/example?task=Regulatory+Interpretation")
+        assert r.status_code == 200
+        data = json.loads(r.data)
+        assert data.get("task_type") == "Regulatory Interpretation"
+
+    def test_unknown_filter_returns_error(self, client):
+        r = client.get("/api/example?task=NotATask&diff=NotADiff")
+        assert r.status_code == 200
+        data = json.loads(r.data)
+        assert "error" in data
+
+
+class TestSubmit:
+    def test_returns_issue_url(self, client):
+        r = client.post(
+            "/api/submit",
+            data=json.dumps({"hf_id": "meta-llama/Llama-3.2-3B", "label": "Llama-3.2-3B"}),
+            content_type="application/json",
+        )
+        assert r.status_code == 200
+        data = json.loads(r.data)
+        assert "issue_url" in data
+        assert "github.com/Rajveer-code/IndiaFinBench/issues/new" in data["issue_url"]
+        assert "Llama-3.2-3B" in data["issue_url"]
+
+    def test_hf_id_in_issue_url(self, client):
+        r = client.post(
+            "/api/submit",
+            data=json.dumps({"hf_id": "mistralai/Mistral-7B-v0.3"}),
+            content_type="application/json",
+        )
+        data = json.loads(r.data)
+        assert "issue_url" in data
+        assert "mistralai" in data["issue_url"]
+
+    def test_missing_hf_id_returns_400(self, client):
+        r = client.post(
+            "/api/submit",
+            data=json.dumps({}),
+            content_type="application/json",
+        )
+        assert r.status_code == 400
+        data = json.loads(r.data)
+        assert "error" in data
+
+    def test_no_job_id_in_response(self, client):
+        r = client.post(
+            "/api/submit",
+            data=json.dumps({"hf_id": "some/model"}),
+            content_type="application/json",
+        )
+        data = json.loads(r.data)
+        assert "job_id" not in data
+
+
+class TestRag:
+    def test_empty_query_returns_400(self, client):
+        r = client.post(
+            "/api/rag",
+            data=json.dumps({"query": ""}),
+            content_type="application/json",
+        )
+        assert r.status_code == 400
+
+    def test_missing_query_key_returns_400(self, client):
+        r = client.post(
+            "/api/rag",
+            data=json.dumps({}),
+            content_type="application/json",
+        )
+        assert r.status_code == 400

rag/__init__.py

@@ -0,0 +1,14 @@
+"""
+rag/
+----
+Local FAISS + BM25 hybrid RAG pipeline for the IndiaFinBench corpus.
+
+Quick start:
+    from rag.pipeline import RAGPipeline
+    pipe = RAGPipeline()
+    pipe.load_index()          # load pre-built index
+    result = pipe.ask("What are the KYC norms under SEBI?")
+"""
+
+# Lazy import — do not eagerly pull in pipeline here; heavy deps may not be installed.
+# Users should import directly: from rag.pipeline import RAGPipeline

rag/bm25_index.py

@@ -0,0 +1,80 @@
+"""
+rag/bm25_index.py
+-----------------
+BM25Okapi index for lexical retrieval over chunk texts.
+
+Tokenisation strategy:
+  Lowercase + strip punctuation EXCEPT hyphens and parentheses.
+  Rationale: Indian regulatory text contains tokens like "91-day", "4(2)(b)",
+  "Section-51A" whose internal punctuation carries semantic meaning.
+  Standard whitespace tokenisation after these targeted strips preserves them.
+
+BM25 parameters:
+  k1=1.5  — term frequency saturation (standard Okapi default)
+  b=0.75  — document length normalisation (standard Okapi default)
+  These are not tuned; the corpus is too small to warrant grid search.
+"""
+
+import pickle
+import re
+from pathlib import Path
+
+from rank_bm25 import BM25Okapi
+
+from rag.models import ChunkRecord
+
+
+# Strip punctuation that is NOT part of regulatory term identifiers
+_STRIP_RE = re.compile(r"[^\w\s\-()]")
+
+
+class BM25Index:
+    def __init__(self) -> None:
+        self._bm25:   BM25Okapi | None   = None
+        self._chunks: list[ChunkRecord]  = []
+
+    # ── Tokenisation ──────────────────────────────────────────────────────────
+
+    @staticmethod
+    def tokenise(text: str) -> list[str]:
+        text = text.lower()
+        text = _STRIP_RE.sub(" ", text)
+        return text.split()
+
+    # ── Build ─────────────────────────────────────────────────────────────────
+
+    def build(self, chunks: list[ChunkRecord]) -> None:
+        self._chunks = list(chunks)
+        tokenised    = [self.tokenise(c.text) for c in chunks]
+        self._bm25   = BM25Okapi(tokenised, k1=1.5, b=0.75)
+
+    # ── Query ─────────────────────────────────────────────────────────────────
+
+    def search(self, query: str, k: int) -> list[tuple[ChunkRecord, float]]:
+        """Return up to k (chunk, bm25_score) pairs, descending by score."""
+        if self._bm25 is None:
+            raise RuntimeError("BM25Index not built. Call build() or load() first.")
+        tokens = self.tokenise(query)
+        scores = self._bm25.get_scores(tokens)
+        top_k  = min(k, len(self._chunks))
+        ranked = sorted(range(len(scores)), key=lambda i: scores[i], reverse=True)[:top_k]
+        return [(self._chunks[i], float(scores[i])) for i in ranked]
+
+    # ── Persistence ───────────────────────────────────────────────────────────
+
+    def save(self, index_dir: Path) -> None:
+        index_dir = Path(index_dir)
+        index_dir.mkdir(parents=True, exist_ok=True)
+        with open(index_dir / "bm25.pkl", "wb") as fh:
+            pickle.dump((self._bm25, self._chunks), fh)
+
+    @classmethod
+    def load(cls, index_dir: Path) -> "BM25Index":
+        obj = cls()
+        with open(Path(index_dir) / "bm25.pkl", "rb") as fh:
+            obj._bm25, obj._chunks = pickle.load(fh)
+        return obj
+
+    @property
+    def size(self) -> int:
+        return len(self._chunks)

rag/chunking.py

@@ -0,0 +1,146 @@
+"""
+rag/chunking.py
+---------------
+Recursive character-level text splitter that respects paragraph, sentence,
+and word boundaries — in that priority order.
+
+Algorithm (same invariant as LangChain's RecursiveCharacterTextSplitter):
+  1. Try each separator in SEPARATORS, highest-priority first.
+  2. On the first separator found in the text, split and merge fragments
+     back into chunks ≤ target_chunk_chars, carrying overlap_chars of
+     context from the tail of each chunk into the next.
+  3. Any merged chunk still over target_chunk_chars is recursively split
+     with the remaining lower-priority separators.
+  4. Chunks below min_chunk_chars (degenerate headers/footers) are discarded.
+
+Separators prioritised for Indian regulatory text:
+  \\n\\n > \\n > ". " > "; " > ", " > " " > "" (character-level fallback)
+"""
+
+from rag.models import ChunkRecord, Document
+
+
+_SEPARATORS = ["\n\n", "\n", ". ", "! ", "? ", "; ", ", ", " ", ""]
+
+
+class RecursiveCharacterSplitter:
+    def __init__(
+        self,
+        target_chunk_chars: int = 1600,
+        overlap_chars:      int = 200,
+        min_chunk_chars:    int = 100,
+        separators:         list[str] | None = None,
+    ) -> None:
+        self.target   = target_chunk_chars
+        self.overlap  = overlap_chars
+        self.min_size = min_chunk_chars
+        self.seps     = separators if separators is not None else _SEPARATORS
+
+    # ── Public API ────────────────────────────────────────────────────────────
+
+    def split_document(self, doc: Document) -> list[ChunkRecord]:
+        fragments = self._split_recursive(doc.raw_text, self.seps)
+        records: list[ChunkRecord] = []
+        search_from = 0
+        for idx, text in enumerate(fragments):
+            # Best-effort character offset tracking.
+            # Use the first 60 chars as a stable anchor since overlap means
+            # the same text may appear twice near the split boundary.
+            anchor = text[:60]
+            pos = doc.raw_text.find(anchor, search_from)
+            char_start = pos if pos != -1 else search_from
+            char_end   = char_start + len(text)
+            records.append(ChunkRecord(
+                chunk_id   = f"{doc.doc_id}__{idx:04d}",
+                doc_id     = doc.doc_id,
+                title      = doc.title,
+                source     = doc.source,
+                text       = text,
+                chunk_idx  = idx,
+                char_start = char_start,
+                char_end   = char_end,
+            ))
+            # Advance past this chunk, minus the overlap window
+            search_from = max(0, char_end - self.overlap)
+        return records
+
+    # ── Core splitting logic ──────────────────────────────────────────────────
+
+    def _split_recursive(self, text: str, separators: list[str]) -> list[str]:
+        if len(text) <= self.target:
+            return [text] if len(text) >= self.min_size else []
+
+        if not separators:
+            # Character-level hard fallback: slice at target with overlap stride
+            result: list[str] = []
+            stride = max(1, self.target - self.overlap)
+            for i in range(0, len(text), stride):
+                chunk = text[i : i + self.target]
+                if len(chunk) >= self.min_size:
+                    result.append(chunk)
+            return result
+
+        sep, *remaining = separators
+
+        if sep not in text:
+            return self._split_recursive(text, remaining)
+
+        # Split on this separator and merge into target-sized chunks
+        frags   = text.split(sep)
+        merged  = self._merge_with_overlap(frags, sep)
+
+        # Recursively split any chunk still above target
+        final: list[str] = []
+        for chunk in merged:
+            if len(chunk) > self.target and remaining:
+                final.extend(self._split_recursive(chunk, remaining))
+            else:
+                final.append(chunk)
+        return final
+
+    def _merge_with_overlap(self, frags: list[str], sep: str) -> list[str]:
+        """
+        Merge a list of text fragments into chunks ≤ target_chars.
+        After emitting a chunk, carry its last overlap_chars into the next
+        chunk to preserve cross-boundary context.
+        """
+        chunks:      list[str]  = []
+        current:     list[str]  = []   # fragments in the current chunk
+        current_len: int        = 0
+
+        for frag in frags:
+            sep_cost   = len(sep) if current else 0
+            addition   = sep_cost + len(frag)
+
+            if current_len + addition > self.target and current:
+                # Emit current chunk
+                chunk_text = sep.join(current)
+                if len(chunk_text) >= self.min_size:
+                    chunks.append(chunk_text)
+
+                # Carry overlap: walk backwards through current fragments
+                overlap_frags: list[str] = []
+                overlap_len:   int       = 0
+                for f in reversed(current):
+                    cost = (len(sep) if overlap_frags else 0) + len(f)
+                    if overlap_len + cost > self.overlap:
+                        break
+                    overlap_frags.insert(0, f)
+                    overlap_len += cost
+
+                current     = overlap_frags + [frag]
+                current_len = sum(
+                    len(f) + (len(sep) if i > 0 else 0)
+                    for i, f in enumerate(current)
+                )
+            else:
+                current.append(frag)
+                current_len += addition
+
+        # Flush the last chunk
+        if current:
+            chunk_text = sep.join(current)
+            if len(chunk_text) >= self.min_size:
+                chunks.append(chunk_text)
+
+        return chunks

rag/config.py

@@ -0,0 +1,44 @@
+"""
+rag/config.py
+-------------
+Single source of truth for all RAG hyperparameters.
+Override via environment variables or by constructing RAGConfig with explicit values.
+"""
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class RAGConfig:
+    # ── Chunking ──────────────────────────────────────────────────────────────
+    target_chunk_chars: int = 1600   # ~400 tokens at 4 chars/token for English legal text
+    overlap_chars:      int = 200    # ~50-token overlap to preserve cross-boundary clauses
+    min_chunk_chars:    int = 100    # discard degenerate micro-chunks
+
+    # ── Embedding ─────────────────────────────────────────────────────────────
+    embedding_model:      str = "BAAI/bge-base-en-v1.5"  # 768-dim, 512-token max
+    embedding_batch_size: int = 64
+    embedding_device:     str = "cpu"
+
+    # ── Retrieval ─────────────────────────────────────────────────────────────
+    top_k:          int = 5    # final chunks injected into generation context
+    candidates:     int = 20   # candidates fetched from each retriever before RRF
+    rrf_k:          int = 60   # RRF constant (Cormack et al. 2009 default)
+    max_per_source: int = 3    # diversity cap: max chunks from a single "rbi"/"sebi" source
+
+    # ── Generation ────────────────────────────────────────────────────────────
+    llm_backend:  str   = field(default_factory=lambda: os.getenv("RAG_LLM_BACKEND", "groq"))
+    groq_model:   str   = "llama-3.3-70b-versatile"
+    ollama_model: str   = "llama3.2:3b"
+    temperature:  float = 0.0    # deterministic; critical for reproducible evaluation
+    max_tokens:   int   = 512
+
+    # ── Paths ─────────────────────────────────────────────────────────────────
+    data_dir:  Path = field(default_factory=lambda: Path("data/parsed"))
+    index_dir: Path = field(default_factory=lambda: Path("rag/index"))
+
+    def __post_init__(self) -> None:
+        self.data_dir  = Path(self.data_dir)
+        self.index_dir = Path(self.index_dir)

rag/data_loader.py

@@ -0,0 +1,51 @@
+"""
+rag/data_loader.py
+------------------
+Scan data/parsed/{rbi,sebi}/*.txt and return a flat list of Document objects.
+Title extraction parses the filename convention used by the IndiaFinBench corpus:
+    {SOURCE}_{ShortLabel}_{full_slug}_{index}.txt
+e.g. RBI_Master Dir_master_direction_-_..._084.txt → title "RBI — Master Dir"
+"""
+
+import re
+from pathlib import Path
+
+from rag.models import Document
+
+
+class DataLoader:
+    SOURCES = ("rbi", "sebi")
+
+    def __init__(self, data_dir: Path | str) -> None:
+        self.data_dir = Path(data_dir)
+
+    def load(self) -> list[Document]:
+        docs: list[Document] = []
+        for source in self.SOURCES:
+            source_dir = self.data_dir / source
+            if not source_dir.exists():
+                continue
+            for fpath in sorted(source_dir.glob("*.txt")):
+                text = fpath.read_text(encoding="utf-8", errors="replace")
+                docs.append(Document(
+                    doc_id=fpath.stem,
+                    title=self._parse_title(fpath.stem, source),
+                    source=source,
+                    raw_text=text,
+                    file_path=str(fpath.resolve()),
+                ))
+        return docs
+
+    @staticmethod
+    def _parse_title(stem: str, source: str) -> str:
+        """
+        Filename format: {SRC}_{ShortLabel}_{long_slug}_{index}
+        Extract the short label (second underscore-delimited field).
+        """
+        parts = stem.split("_", 2)
+        if len(parts) >= 2:
+            label = parts[1].strip()
+            # Collapse runs of spaces introduced by the naming convention
+            label = re.sub(r"\s+", " ", label)
+            return f"{source.upper()} — {label}"
+        return stem

rag/embeddings.py

@@ -0,0 +1,58 @@
+"""
+rag/embeddings.py
+-----------------
+Thin wrapper around sentence-transformers for BGE-base-en-v1.5.
+
+BGE asymmetric encoding (important):
+  - Corpus documents: encoded WITHOUT any prefix.
+  - Queries: encoded WITH the prefix "Represent this sentence for searching
+    relevant passages: " as specified by BAAI for bge-base-en-v1.5.
+  Skipping the query prefix causes a measurable recall drop (~3–5% on MTEB).
+
+All output embeddings are L2-normalised so that inner product = cosine similarity.
+This is enforced here — callers must not re-normalise.
+"""
+
+import numpy as np
+from sentence_transformers import SentenceTransformer
+
+
+_QUERY_PREFIX = "Represent this sentence for searching relevant passages: "
+
+
+class BGEEmbedder:
+    def __init__(
+        self,
+        model_name:  str = "BAAI/bge-base-en-v1.5",
+        device:      str = "cpu",
+        batch_size:  int = 64,
+    ) -> None:
+        self._model      = SentenceTransformer(model_name, device=device)
+        self.batch_size  = batch_size
+        self.dim: int    = self._model.get_sentence_embedding_dimension()
+
+    def encode_corpus(self, texts: list[str], show_progress: bool = True) -> np.ndarray:
+        """
+        Encode a list of corpus texts.
+        Returns float32 array of shape (len(texts), dim), L2-normalised.
+        """
+        embeddings = self._model.encode(
+            texts,
+            batch_size=self.batch_size,
+            show_progress_bar=show_progress,
+            normalize_embeddings=True,
+            convert_to_numpy=True,
+        )
+        return embeddings.astype(np.float32)
+
+    def encode_query(self, query: str) -> np.ndarray:
+        """
+        Encode a single query with the BGE query prefix.
+        Returns float32 array of shape (1, dim), L2-normalised.
+        """
+        embedding = self._model.encode(
+            _QUERY_PREFIX + query,
+            normalize_embeddings=True,
+            convert_to_numpy=True,
+        )
+        return embedding.astype(np.float32).reshape(1, -1)

rag/evaluation.py

@@ -0,0 +1,855 @@
+"""
+rag/evaluation.py
+-----------------
+Phase 3 evaluation framework.
+
+Architecture principle: retrieval evaluation and generation evaluation are
+STRICTLY SEPARATED. This makes failure attribution unambiguous.
+
+  Stage 1 — Retrieval-only (no LLM calls):
+    Recall@k, MRR, Precision@k for all B0–B5 ablation configs.
+
+  Stage 2 — Full pipeline (retrieval + generation + judge):
+    Faithfulness (Gemini 1.5 Flash as judge), Answer Relevance.
+    Run only on B2 (proposed) and B0 (dense baseline) to manage quota.
+
+Eval dataset (50 items):
+  - 35 synthetic: generated by Gemini from corpus documents, with
+    verbatim_span used to locate ground-truth chunk(s).
+  - 15 adversarial: hardcoded to stress failure modes.
+  - Loaded from data/eval/eval_set.json if present; generated otherwise.
+
+Config snapshot: frozen at eval start; written alongside results JSON so
+every report is self-contained and reproducible.
+"""
+
+import json
+import logging
+import os
+import random
+import time
+from dataclasses import asdict, dataclass, field
+from difflib import SequenceMatcher
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from rag.bm25_index import BM25Index
+from rag.config import RAGConfig
+from rag.embeddings import BGEEmbedder
+from rag.index import FAISSIndex
+from rag.models import ChunkRecord
+from rag.retriever import HybridRetriever
+
+logger = logging.getLogger(__name__)
+
+# ── Faithfulness judge: prompt version tracking ───────────────────────────────
+# Increment when the prompt text changes so results remain comparable across runs.
+# LLM-as-judge caveat: Gemini 1.5 Flash is itself a language model and may exhibit
+# systematic biases (e.g., awarding higher faithfulness to longer, confident-sounding
+# answers regardless of factual grounding). Scores should be interpreted as
+# approximate signal, not ground truth. Use consistent judge model + prompt version
+# across all ablation runs to ensure internal comparability.
+FAITHFULNESS_JUDGE_PROMPT_VERSION = "v1.0"
+FAITHFULNESS_JUDGE_MODEL          = "gemini-1.5-flash"
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Data types
+# ─────────────────────────────────────────────────────────────────────────────
+
+@dataclass
+class EvalItem:
+    qid:                str
+    question:           str
+    reference_answer:   str
+    relevant_chunk_ids: list[str]   # empty → unanswerable / annotation pending
+    tier:               str         # "synthetic" | "adversarial"
+    source_doc:         str         # primary doc_id (empty string if N/A)
+
+
+@dataclass
+class RetrievalMetrics:
+    recall_at_k:     float
+    mrr:             float
+    precision_at_k:  float
+    k:               int
+    n_queries:       int   # queries with non-empty relevant_chunk_ids
+
+
+@dataclass
+class GenerationMetrics:
+    faithfulness:           float
+    hallucination_free_rate: float
+    answer_relevance:       float
+    n_queries:              int
+
+
+@dataclass
+class FailureRecord:
+    qid:                  str
+    question:             str
+    expected_chunk_ids:   list[str]
+    retrieved_chunk_ids:  list[str]
+    model_answer:         str
+    error_type:           str    # "retrieval_miss" | "hallucination" | "both" | "unanswerable_correct" | "unanswerable_hallucinated"
+    recall:               float
+    faithfulness:         float  # -1.0 if not computed
+
+
+@dataclass
+class LatencyStats:
+    mean_ms:   float
+    p50_ms:    float
+    p95_ms:    float
+    n_queries: int
+
+
+@dataclass
+class RunResult:
+    config_id:           str
+    config_snapshot:     dict[str, Any]
+    retrieval_metrics:   RetrievalMetrics
+    generation_metrics:  GenerationMetrics | None
+    latency:             LatencyStats
+    failures:            list[FailureRecord]
+    elapsed_seconds:     float
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Retrieval metrics (pure functions — no LLM calls)
+# ─────────────────────────────────────────────────────────────────────────────
+
+def compute_recall_at_k(retrieved_ids: list[str], relevant_ids: list[str]) -> float:
+    if not relevant_ids:
+        return 0.0
+    return len(set(retrieved_ids) & set(relevant_ids)) / len(relevant_ids)
+
+
+def compute_mrr(retrieved_ids: list[str], relevant_ids: list[str]) -> float:
+    relevant_set = set(relevant_ids)
+    for rank, cid in enumerate(retrieved_ids, 1):
+        if cid in relevant_set:
+            return 1.0 / rank
+    return 0.0
+
+
+def compute_precision_at_k(retrieved_ids: list[str], relevant_ids: list[str]) -> float:
+    if not retrieved_ids:
+        return 0.0
+    return len(set(retrieved_ids) & set(relevant_ids)) / len(retrieved_ids)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Generation metrics
+# ─────────────────────────────────────────────────────────────────────────────
+
+def compute_answer_relevance(
+    query: str, answer: str, embedder: BGEEmbedder
+) -> float:
+    """Cosine similarity between query embedding and answer embedding."""
+    q_emb = embedder.encode_query(query)          # (1, 768) L2-normalised
+    a_emb = embedder.encode_corpus([answer], show_progress=False)  # (1, 768)
+    return float(np.dot(q_emb, a_emb.T))
+
+
+def judge_faithfulness(
+    answer: str,
+    source_texts: list[str],
+    gemini_model: Any,
+) -> tuple[float, list[dict]]:
+    """
+    Use Gemini as a strict claim-attribution judge.
+
+    Returns (faithfulness_score, claims_list).
+    faithfulness_score = supported_claims / total_claims.
+    On parse failure returns (0.5, []) — conservative middle ground.
+    """
+    source_block = "\n\n".join(
+        f"[Source {i}] {t}" for i, t in enumerate(source_texts, 1)
+    )
+    prompt = (
+        "You are a strict fact-checker. Your ONLY job is claim attribution.\n\n"
+        f"SOURCES:\n{source_block}\n\n"
+        f"ANSWER:\n{answer}\n\n"
+        "For each distinct factual claim in ANSWER, determine if it is:\n"
+        "  SUPPORTED: directly stated or unambiguously implied by a source\n"
+        "  UNSUPPORTED: relies on knowledge absent from the sources\n\n"
+        "Output ONLY valid JSON, no other text:\n"
+        '{"claims": [{"text": "...", "supported": true, "source_ref": "[Source N] or null"}], '
+        '"faithfulness_score": <float 0-1>}'
+    )
+    try:
+        resp = gemini_model.generate_content(prompt)
+        raw  = resp.text.strip()
+        # Strip markdown code fences if present
+        if raw.startswith("```"):
+            raw = "\n".join(raw.split("\n")[1:])
+            if raw.endswith("```"):
+                raw = raw[:-3]
+        data = json.loads(raw)
+        return float(data["faithfulness_score"]), data.get("claims", [])
+    except Exception as exc:
+        logger.warning("Faithfulness judge parse error: %s", exc)
+        return 0.5, []
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Eval dataset: load or generate
+# ─────────────────────────────────────────────────────────────────────────────
+
+def _find_relevant_chunks(
+    verbatim_span: str, chunks: list[ChunkRecord], threshold: float = 0.70
+) -> list[str]:
+    """Locate chunk IDs containing or closely matching verbatim_span."""
+    span_lower = verbatim_span.lower().strip()
+    matches: list[str] = []
+    for chunk in chunks:
+        text_lower = chunk.text.lower()
+        if span_lower in text_lower:
+            matches.append(chunk.chunk_id)
+        elif len(span_lower) >= 40:
+            # Fuzzy match only for substantial spans (avoids false positives on short strings)
+            window = text_lower[: len(span_lower) + 100]
+            ratio  = SequenceMatcher(None, span_lower, window).ratio()
+            if ratio >= threshold:
+                matches.append(chunk.chunk_id)
+    return matches
+
+
+def _hardcoded_adversarial_items() -> list[EvalItem]:
+    """
+    15 manually crafted adversarial items covering the IndiaFinBench failure modes.
+    relevant_chunk_ids is empty for unanswerable queries (correct behaviour =
+    "insufficient context"); annotators should fill cross-doc and ref queries.
+    """
+    return [
+        # ── Cross-document synthesis (4) ──────────────────────────────────────
+        EvalItem(
+            qid="adv_001",
+            question="What KYC verification obligations apply to both SEBI-registered portfolio managers and RBI-regulated commercial banks?",
+            reference_answer="ANNOTATION REQUIRED",
+            relevant_chunk_ids=[],
+            tier="adversarial",
+            source_doc="",
+        ),
+        EvalItem(
+            qid="adv_002",
+            question="How do SEBI's anti-money laundering requirements for FPIs compare with RBI's AML obligations for NBFCs?",
+            reference_answer="ANNOTATION REQUIRED",
+            relevant_chunk_ids=[],
+            tier="adversarial",
+            source_doc="",
+        ),
+        EvalItem(
+            qid="adv_003",
+            question="Which SEBI and RBI circulars jointly govern the treatment of beneficial ownership disclosures?",
+            reference_answer="ANNOTATION REQUIRED",
+            relevant_chunk_ids=[],
+            tier="adversarial",
+            source_doc="",
+        ),
+        EvalItem(
+            qid="adv_004",
+            question="What reporting obligations exist under both SEBI and RBI frameworks for entities on UAPA designated lists?",
+            reference_answer="ANNOTATION REQUIRED",
+            relevant_chunk_ids=[],
+            tier="adversarial",
+            source_doc="",
+        ),
+        # ── Exact regulatory references (4) ───────────────────────────────────
+        EvalItem(
+            qid="adv_005",
+            question="What does Section 51A of UAPA 1967 specifically require financial institutions to do?",
+            reference_answer="ANNOTATION REQUIRED",
+            relevant_chunk_ids=[],
+            tier="adversarial",
+            source_doc="",
+        ),
+        EvalItem(
+            qid="adv_006",
+            question="What are the conditions specified under Regulation 4(2)(b) of the FPI Regulations 2019?",
+            reference_answer="ANNOTATION REQUIRED",
+            relevant_chunk_ids=[],
+            tier="adversarial",
+            source_doc="",
+        ),
+        EvalItem(
+            qid="adv_007",
+            question="Under which master direction does RBI mandate unique identifiers for financial market participants?",
+            reference_answer="ANNOTATION REQUIRED",
+            relevant_chunk_ids=[],
+            tier="adversarial",
+            source_doc="",
+        ),
+        EvalItem(
+            qid="adv_008",
+            question="What was the cut-off rate announced for the 91-day Treasury Bill auction in March 2026?",
+            reference_answer="ANNOTATION REQUIRED",
+            relevant_chunk_ids=[],
+            tier="adversarial",
+            source_doc="",
+        ),
+        # ── Unanswerable / out-of-corpus (4) ──────────────────────────────────
+        EvalItem(
+            qid="adv_009",
+            question="What is SEBI's regulatory framework for cryptocurrency derivative instruments?",
+            reference_answer="The provided context does not contain sufficient information to answer this question.",
+            relevant_chunk_ids=[],   # correct answer = "insufficient context"
+            tier="adversarial",
+            source_doc="",
+        ),
+        EvalItem(
+            qid="adv_010",
+            question="What are RBI's guidelines on digital lending apps for fintech startups?",
+            reference_answer="The provided context does not contain sufficient information to answer this question.",
+            relevant_chunk_ids=[],
+            tier="adversarial",
+            source_doc="",
+        ),
+        EvalItem(
+            qid="adv_011",
+            question="What is the minimum net worth requirement for a crypto exchange seeking SEBI registration?",
+            reference_answer="The provided context does not contain sufficient information to answer this question.",
+            relevant_chunk_ids=[],
+            tier="adversarial",
+            source_doc="",
+        ),
+        EvalItem(
+            qid="adv_012",
+            question="What is RBI's position on issuing a retail Central Bank Digital Currency in India?",
+            reference_answer="The provided context does not contain sufficient information to answer this question.",
+            relevant_chunk_ids=[],
+            tier="adversarial",
+            source_doc="",
+        ),
+        # ── Temporal / version conflict (3) ───────────────────────────────────
+        EvalItem(
+            qid="adv_013",
+            question="When is the next Monetary Policy Committee meeting scheduled after April 2026?",
+            reference_answer="ANNOTATION REQUIRED",
+            relevant_chunk_ids=[],
+            tier="adversarial",
+            source_doc="",
+        ),
+        EvalItem(
+            qid="adv_014",
+            question="What was the outcome of the 622nd meeting of the RBI Central Board?",
+            reference_answer="ANNOTATION REQUIRED",
+            relevant_chunk_ids=[],
+            tier="adversarial",
+            source_doc="",
+        ),
+        EvalItem(
+            qid="adv_015",
+            question="What SEBI circular superseded or amended the most recent FPI KYC guidelines?",
+            reference_answer="ANNOTATION REQUIRED",
+            relevant_chunk_ids=[],
+            tier="adversarial",
+            source_doc="",
+        ),
+    ]
+
+
+def _generate_synthetic_items(
+    docs: list,
+    chunks: list[ChunkRecord],
+    n: int = 35,
+    api_key: str | None = None,
+    seed: int = 42,
+) -> list[EvalItem]:
+    """
+    Generate n synthetic QA items via Gemini 1.5 Flash.
+    Each item's ground-truth chunk IDs are located via verbatim_span matching.
+    Requires GEMINI_API_KEY env var or explicit api_key parameter.
+    """
+    import google.generativeai as genai  # type: ignore[import]
+
+    key = api_key or os.environ.get("GEMINI_API_KEY")
+    if not key:
+        raise EnvironmentError("GEMINI_API_KEY not set. Cannot generate synthetic eval set.")
+
+    genai.configure(api_key=key)
+    model = genai.GenerativeModel(
+        "gemini-1.5-flash",
+        generation_config={"temperature": 0.3, "max_output_tokens": 512},
+    )
+
+    rng      = random.Random(seed)
+    sampled  = rng.sample(docs, min(n, len(docs)))
+    items:   list[EvalItem] = []
+    failed   = 0
+
+    for i, doc in enumerate(sampled):
+        text_excerpt = doc.raw_text[:3000]
+        prompt = (
+            "Given the following regulatory text, write ONE specific factual question "
+            "whose exact answer can be found in one or two consecutive paragraphs.\n\n"
+            f"TEXT:\n{text_excerpt}\n\n"
+            "Requirements:\n"
+            "- The question must be answerable ONLY from this text.\n"
+            "- The answer must be precise, not vague.\n"
+            "- Include a verbatim_span: the first 60 characters of the exact answer text.\n\n"
+            "Output ONLY valid JSON, no other text:\n"
+            '{"question": "...", "answer": "...", "verbatim_span": "..."}'
+        )
+        try:
+            resp = model.generate_content(prompt)
+            raw  = resp.text.strip()
+            if raw.startswith("```"):
+                raw = "\n".join(raw.split("\n")[1:]).rstrip("` \n")
+            data = json.loads(raw)
+
+            relevant_ids = _find_relevant_chunks(data["verbatim_span"], chunks)
+            items.append(EvalItem(
+                qid                = f"syn_{i+1:03d}",
+                question           = data["question"],
+                reference_answer   = data["answer"],
+                relevant_chunk_ids = relevant_ids,
+                tier               = "synthetic",
+                source_doc         = doc.doc_id,
+            ))
+            # Respect Gemini free-tier rate limits (~2 RPM for flash)
+            time.sleep(0.5)
+
+        except Exception as exc:
+            logger.warning("Skipping doc %s: %s", doc.doc_id, exc)
+            failed += 1
+
+    logger.info(
+        "Generated %d synthetic items (%d failed) from %d docs.",
+        len(items), failed, len(sampled),
+    )
+    return items
+
+
+def load_or_generate_eval_set(
+    path: Path,
+    docs: list | None = None,
+    chunks: list[ChunkRecord] | None = None,
+    n_synthetic: int = 35,
+    api_key: str | None = None,
+    seed: int = 42,
+) -> list[EvalItem]:
+    """
+    Load from path if it exists; otherwise generate and save.
+    docs and chunks required only for generation.
+    """
+    path = Path(path)
+    if path.exists():
+        raw   = json.loads(path.read_text(encoding="utf-8"))
+        items = [EvalItem(**item) for item in raw]
+        logger.info("Loaded %d eval items from %s", len(items), path)
+        return items
+
+    if docs is None or chunks is None:
+        raise ValueError("docs and chunks required to generate eval set.")
+
+    synthetic   = _generate_synthetic_items(docs, chunks, n_synthetic, api_key, seed)
+    adversarial = _hardcoded_adversarial_items()
+    items       = synthetic + adversarial
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        json.dumps([asdict(i) for i in items], indent=2, ensure_ascii=False),
+        encoding="utf-8",
+    )
+    logger.info("Saved %d eval items to %s", len(items), path)
+    return items
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Stage 1: Retrieval evaluation (no LLM)
+# ─────────────────────────────────────────────────────────────────────────────
+
+def evaluate_retrieval(
+    retriever: HybridRetriever,
+    eval_items: list[EvalItem],
+    mode: str = "hybrid",
+    k: int = 5,
+) -> tuple[RetrievalMetrics, LatencyStats, list[FailureRecord]]:
+    """
+    Evaluate retriever on items that have ground-truth chunk IDs.
+    Items with empty relevant_chunk_ids are skipped for metric aggregation
+    (they still appear as failures if retrieval returns nothing useful).
+    Also measures per-query wall-clock latency (retrieval only, no LLM).
+    """
+    recalls, mrrs, precisions = [], [], []
+    latencies_ms: list[float] = []
+    failures: list[FailureRecord] = []
+
+    for item in eval_items:
+        t0            = time.perf_counter()
+        results       = retriever.retrieve(item.question, mode=mode)
+        latencies_ms.append((time.perf_counter() - t0) * 1000)
+        retrieved_ids = [r.chunk.chunk_id for r in results]
+
+        if not item.relevant_chunk_ids:
+            # Adversarial / unanswerable — skip metric computation
+            continue
+
+        recall    = compute_recall_at_k(retrieved_ids, item.relevant_chunk_ids)
+        mrr       = compute_mrr(retrieved_ids, item.relevant_chunk_ids)
+        precision = compute_precision_at_k(retrieved_ids, item.relevant_chunk_ids)
+
+        recalls.append(recall)
+        mrrs.append(mrr)
+        precisions.append(precision)
+
+        if recall < 1.0:
+            failures.append(FailureRecord(
+                qid                  = item.qid,
+                question             = item.question,
+                expected_chunk_ids   = item.relevant_chunk_ids,
+                retrieved_chunk_ids  = retrieved_ids,
+                model_answer         = "",   # not computed in retrieval-only pass
+                error_type           = "retrieval_miss",
+                recall               = recall,
+                faithfulness         = -1.0,
+            ))
+
+    n = max(len(recalls), 1)
+    lat_sorted = sorted(latencies_ms)
+    p50 = lat_sorted[len(lat_sorted) // 2] if lat_sorted else 0.0
+    p95 = lat_sorted[int(len(lat_sorted) * 0.95)] if lat_sorted else 0.0
+    return (
+        RetrievalMetrics(
+            recall_at_k    = sum(recalls)    / n,
+            mrr            = sum(mrrs)       / n,
+            precision_at_k = sum(precisions) / n,
+            k              = k,
+            n_queries      = len(recalls),
+        ),
+        LatencyStats(
+            mean_ms   = sum(latencies_ms) / max(len(latencies_ms), 1),
+            p50_ms    = p50,
+            p95_ms    = p95,
+            n_queries = len(latencies_ms),
+        ),
+        failures,
+    )
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Stage 2: Generation evaluation (requires LLM + judge)
+# ─────────────────────────────────────────────────────────────────────────────
+
+def evaluate_generation(
+    pipeline: Any,   # RAGPipeline
+    eval_items: list[EvalItem],
+    embedder: BGEEmbedder,
+    gemini_model: Any,
+    mode: str = "hybrid",
+    max_items: int | None = None,
+) -> tuple[GenerationMetrics, list[FailureRecord]]:
+    """
+    Run the full pipeline (retrieval + generation) and score each answer.
+    Retrieval and generation failures are recorded separately in FailureRecord.error_type.
+    """
+    faithfulness_scores: list[float] = []
+    hallucination_free:  list[bool]  = []
+    relevance_scores:    list[float] = []
+    failures:            list[FailureRecord] = []
+
+    items_to_eval = eval_items[:max_items] if max_items else eval_items
+
+    for item in items_to_eval:
+        result = pipeline.ask(item.question, mode=mode)
+
+        if "error" in result:
+            logger.warning("Pipeline error for %s: %s", item.qid, result["error"])
+            continue
+
+        answer         = result["answer"]
+        source_texts   = [s["text"] for s in result.get("sources", [])]
+        retrieved_ids  = [s["chunk_id"] for s in result.get("sources", [])]
+
+        # Retrieval quality (if ground truth available)
+        recall = (
+            compute_recall_at_k(retrieved_ids, item.relevant_chunk_ids)
+            if item.relevant_chunk_ids else -1.0
+        )
+
+        # Faithfulness
+        f_score, claims = judge_faithfulness(answer, source_texts, gemini_model)
+        faithfulness_scores.append(f_score)
+        all_supported = all(c.get("supported", True) for c in claims)
+        hallucination_free.append(all_supported)
+
+        # Answer relevance
+        rel_score = compute_answer_relevance(item.question, answer, embedder)
+        relevance_scores.append(rel_score)
+
+        # Classify failure
+        is_retrieval_miss   = bool(item.relevant_chunk_ids) and recall < 0.5
+        is_hallucination    = f_score < 0.80
+        is_unanswerable     = not item.relevant_chunk_ids
+
+        if is_unanswerable:
+            insufficient_phrase = "does not contain sufficient"
+            error_type = (
+                "unanswerable_correct"
+                if insufficient_phrase in answer.lower()
+                else "unanswerable_hallucinated"
+            )
+        elif is_retrieval_miss and is_hallucination:
+            error_type = "both"
+        elif is_retrieval_miss:
+            error_type = "retrieval_miss"
+        elif is_hallucination:
+            error_type = "hallucination"
+        else:
+            continue  # no failure
+
+        failures.append(FailureRecord(
+            qid                  = item.qid,
+            question             = item.question,
+            expected_chunk_ids   = item.relevant_chunk_ids,
+            retrieved_chunk_ids  = retrieved_ids,
+            model_answer         = answer[:400],
+            error_type           = error_type,
+            recall               = recall,
+            faithfulness         = f_score,
+        ))
+
+    n = max(len(faithfulness_scores), 1)
+    return (
+        GenerationMetrics(
+            faithfulness            = sum(faithfulness_scores) / n,
+            hallucination_free_rate = sum(hallucination_free)  / n,
+            answer_relevance        = sum(relevance_scores)    / n,
+            n_queries               = len(faithfulness_scores),
+        ),
+        failures,
+    )
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Ablation runner
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Each config: id, retriever mode, top_k, optional alternative index dir
+ABLATION_CONFIGS: list[dict] = [
+    {"id": "B0_dense_only",  "mode": "dense",  "top_k": 5,  "index_dir": None, "chunk_chars": None},
+    {"id": "B1_bm25_only",   "mode": "bm25",   "top_k": 5,  "index_dir": None, "chunk_chars": None},
+    {"id": "B2_hybrid",      "mode": "hybrid", "top_k": 5,  "index_dir": None, "chunk_chars": None},
+    {"id": "B3_small_chunks","mode": "hybrid", "top_k": 5,  "index_dir": "rag/index_800",  "chunk_chars": 800},
+    {"id": "B4_large_chunks","mode": "hybrid", "top_k": 5,  "index_dir": "rag/index_2400", "chunk_chars": 2400},
+    {"id": "B5_higher_k",    "mode": "hybrid", "top_k": 10, "index_dir": None, "chunk_chars": None},
+]
+
+
+def _load_retriever_for_config(
+    cfg: dict,
+    base_faiss: FAISSIndex,
+    base_bm25:  BM25Index,
+    embedder:   BGEEmbedder,
+    base_cfg:   RAGConfig,
+) -> HybridRetriever | None:
+    """Build a HybridRetriever for an ablation config. Returns None if index missing."""
+    if cfg["index_dir"] is not None:
+        alt_dir = Path(cfg["index_dir"])
+        if not (alt_dir / "faiss.index").exists():
+            logger.warning(
+                "Skipping %s: index not found at %s. "
+                "Run: python -m rag.scripts.build_index --index-dir %s --chunk-size %s",
+                cfg["id"], alt_dir, alt_dir, cfg["chunk_chars"],
+            )
+            return None
+        faiss_idx = FAISSIndex.load(alt_dir, embedder.dim)
+        bm25_idx  = BM25Index.load(alt_dir)
+    else:
+        faiss_idx = base_faiss
+        bm25_idx  = base_bm25
+
+    return HybridRetriever(
+        faiss_index    = faiss_idx,
+        bm25_index     = bm25_idx,
+        embedder       = embedder,
+        top_k          = cfg["top_k"],
+        candidates     = base_cfg.candidates,
+        rrf_k          = base_cfg.rrf_k,
+        max_per_source = base_cfg.max_per_source,
+    )
+
+
+def run_ablation(
+    base_faiss:  FAISSIndex,
+    base_bm25:   BM25Index,
+    embedder:    BGEEmbedder,
+    base_cfg:    RAGConfig,
+    eval_items:  list[EvalItem],
+    configs:     list[dict] | None = None,
+) -> list[RunResult]:
+    configs = configs or ABLATION_CONFIGS
+    results: list[RunResult] = []
+
+    for cfg in configs:
+        retriever = _load_retriever_for_config(
+            cfg, base_faiss, base_bm25, embedder, base_cfg
+        )
+        if retriever is None:
+            continue
+
+        config_snapshot = {
+            "config_id":    cfg["id"],
+            "mode":         cfg["mode"],
+            "top_k":        cfg["top_k"],
+            "chunk_chars":  cfg["chunk_chars"] or base_cfg.target_chunk_chars,
+            "overlap_chars": base_cfg.overlap_chars,
+            "embedding_model": base_cfg.embedding_model,
+            "rrf_k":        base_cfg.rrf_k,
+            "candidates":   base_cfg.candidates,
+        }
+
+        logger.info("Running ablation: %s (mode=%s, k=%d)", cfg["id"], cfg["mode"], cfg["top_k"])
+        t0 = time.perf_counter()
+
+        metrics, latency, failures = evaluate_retrieval(
+            retriever, eval_items, mode=cfg["mode"], k=cfg["top_k"]
+        )
+
+        results.append(RunResult(
+            config_id          = cfg["id"],
+            config_snapshot    = config_snapshot,
+            retrieval_metrics  = metrics,
+            generation_metrics = None,   # filled in separately for B0 and B2
+            latency            = latency,
+            failures           = failures,
+            elapsed_seconds    = time.perf_counter() - t0,
+        ))
+
+    return results
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Terminal report
+# ─────────────────────────────────────────────────────────────────────────────
+
+def print_terminal_report(
+    ablation_results:   list[RunResult],
+    gen_results_by_id:  dict[str, tuple[GenerationMetrics, list[FailureRecord]]],
+    eval_items:         list[EvalItem],
+) -> None:
+    n_syn = sum(1 for i in eval_items if i.tier == "synthetic")
+    n_adv = sum(1 for i in eval_items if i.tier == "adversarial")
+
+    w = 72
+    print()
+    print("╔" + "═" * w + "╗")
+    print("║" + " IndiaFinBench RAG — Phase 3 Evaluation Report".center(w) + "║")
+    print("╚" + "═" * w + "╝")
+    print(f"\n  Eval dataset : {len(eval_items)} queries  ({n_syn} synthetic + {n_adv} adversarial)")
+    print(f"  Embedding    : BAAI/bge-base-en-v1.5 (768-dim, cosine, IndexFlatIP)")
+
+    # ── Retrieval table ───────────────────────────────────────────────────────
+    print()
+    print("  RETRIEVAL METRICS")
+    hdr = f"  {'Config':<22}  {'Recall@k':>9}  {'MRR':>8}  {'Prec@k':>8}  {'k':>3}  {'p50ms':>7}  {'p95ms':>7}  {'n':>4}"
+    print(hdr)
+    print("  " + "─" * (len(hdr) - 2))
+    for r in ablation_results:
+        m   = r.retrieval_metrics
+        lat = r.latency
+        tag = " ◄ proposed" if r.config_id == "B2_hybrid" else ""
+        print(
+            f"  {r.config_id:<22}  {m.recall_at_k:>9.4f}  {m.mrr:>8.4f}  "
+            f"{m.precision_at_k:>8.4f}  {m.k:>3}  {lat.p50_ms:>7.1f}  {lat.p95_ms:>7.1f}  {m.n_queries:>4}{tag}"
+        )
+
+    # ── Thresholds ────────────────────────────────────────────────────────────
+    print()
+    print("  Targets: Recall@5 ≥ 0.80 | MRR ≥ 0.65 | Precision@5 ≥ 0.50")
+
+    # ── Generation table ──────────────────────────────────────────────────────
+    if gen_results_by_id:
+        print()
+        print(
+            f"  GENERATION METRICS  "
+            f"(judge: {FAITHFULNESS_JUDGE_MODEL}, prompt {FAITHFULNESS_JUDGE_PROMPT_VERSION})"
+        )
+        print("  NOTE: LLM-as-judge scores are approximate. Consistent judge model + prompt")
+        print("  version across all runs ensures internal comparability, not absolute accuracy.")
+        ghdr = f"  {'Config':<22}  {'Faithful':>9}  {'Halluc-free':>12}  {'Ans-Rel':>9}  {'n':>4}"
+        print(ghdr)
+        print("  " + "─" * (len(ghdr) - 2))
+        for cfg_id, (gm, _) in gen_results_by_id.items():
+            print(
+                f"  {cfg_id:<22}  {gm.faithfulness:>9.4f}  "
+                f"{gm.hallucination_free_rate:>12.4f}  {gm.answer_relevance:>9.4f}  {gm.n_queries:>4}"
+            )
+        print()
+        print("  Targets: Faithfulness ≥ 0.85 | Halluc-free ≥ 0.90 | Ans-Rel ≥ 0.75")
+
+    # ── Failure analysis ──────────────────────────────────────────────────────
+    print()
+    print("  FAILURE ANALYSIS (B2 Hybrid)")
+    b2 = next((r for r in ablation_results if r.config_id == "B2_hybrid"), None)
+    all_failures: list[FailureRecord] = list(b2.failures) if b2 else []
+    if "B2_hybrid" in gen_results_by_id:
+        all_failures.extend(gen_results_by_id["B2_hybrid"][1])
+
+    if not all_failures:
+        print("  No failures recorded.")
+    else:
+        from collections import Counter
+        error_counts = Counter(f.error_type for f in all_failures)
+        for etype, count in error_counts.most_common():
+            pct = count / len(eval_items) * 100
+            print(f"  [{etype:<28}]  {count:3d} queries  ({pct:.1f}%)")
+
+        print()
+        print("  Top 2 failure examples:")
+        shown = 0
+        for f in all_failures[:10]:
+            if shown >= 2:
+                break
+            if f.error_type in ("retrieval_miss", "hallucination", "both"):
+                print(f"    [{f.error_type}]  {f.qid}: {f.question[:70]}")
+                if f.expected_chunk_ids:
+                    print(f"      expected: {f.expected_chunk_ids[:2]}")
+                    print(f"      got:      {f.retrieved_chunk_ids[:2]}")
+                shown += 1
+
+    print()
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Persistence
+# ─────────────────────────────────────────────────────────────────────────────
+
+def save_report(
+    ablation_results:  list[RunResult],
+    gen_results:       dict[str, tuple[GenerationMetrics, list[FailureRecord]]],
+    config_snapshot:   dict,
+    path:              Path,
+) -> None:
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    serialised_ablation = []
+    for r in ablation_results:
+        d = {
+            "config_id":          r.config_id,
+            "config_snapshot":    r.config_snapshot,
+            "elapsed_seconds":    round(r.elapsed_seconds, 2),
+            "retrieval_metrics":  asdict(r.retrieval_metrics),
+            "generation_metrics": None,
+            "failures":           [asdict(f) for f in r.failures],
+        }
+        if r.config_id in gen_results:
+            gm, _ = gen_results[r.config_id]
+            d["generation_metrics"] = asdict(gm)
+        serialised_ablation.append(d)
+
+    report = {
+        "system_config":    config_snapshot,
+        "judge_meta": {
+            "model":          FAITHFULNESS_JUDGE_MODEL,
+            "prompt_version": FAITHFULNESS_JUDGE_PROMPT_VERSION,
+            "bias_note":      "LLM judge scores approximate; compare only within same version.",
+        },
+        "ablation_results": serialised_ablation,
+    }
+    path.write_text(json.dumps(report, indent=2, ensure_ascii=False), encoding="utf-8")
+    logger.info("Report saved to %s", path)

rag/generator.py

@@ -0,0 +1,111 @@
+"""
+rag/generator.py
+----------------
+LLM generation backend with Groq (primary) and Ollama (local fallback).
+
+Backend selection: set env var RAG_LLM_BACKEND=groq|ollama, or pass
+`backend` explicitly to LLMGenerator.__init__.
+
+Prompt design decisions:
+  - Explicit prohibition on general knowledge: LLMs default to mixing
+    parametric memory with retrieved context, inflating faithfulness scores.
+  - temperature=0.0: deterministic output is required for reproducible eval.
+  - [Source N] citation format matches the source block numbering so the
+    judge in evaluation.py can cross-reference claims.
+  - "chunk {chunk_idx}" suffix in source header provides traceability to
+    exact chunk position, not just document title.
+"""
+
+import os
+
+from rag.models import RetrievalResult
+
+_SYSTEM_PROMPT = (
+    "You are an expert in Indian financial regulation specialising in "
+    "Reserve Bank of India (RBI) and Securities and Exchange Board of India "
+    "(SEBI) regulatory documents.\n\n"
+    "Answer the question using ONLY the numbered source passages provided. "
+    "Cite every factual claim inline as [Source N]. "
+    "If the sources do not contain sufficient information to answer the "
+    "question, state this explicitly — do not infer, extrapolate, or draw "
+    "on general knowledge not present in the sources. "
+    "Be concise and precise. Maximum 200 words unless the question requires more."
+)
+
+
+def _build_context_block(results: list[RetrievalResult]) -> str:
+    parts = [
+        f"[Source {i}] {r.chunk.title} (chunk {r.chunk.chunk_idx})\n{r.chunk.text}"
+        for i, r in enumerate(results, 1)
+    ]
+    return "\n\n".join(parts)
+
+
+class LLMGenerator:
+    def __init__(
+        self,
+        backend:    str   = "groq",
+        model:      str | None = None,
+        max_tokens: int   = 512,
+        temperature: float = 0.0,
+    ) -> None:
+        self.backend     = backend
+        self.max_tokens  = max_tokens
+        self.temperature = temperature
+
+        if backend == "groq":
+            from groq import Groq
+            self._client = Groq(api_key=os.environ["GROQ_API_KEY"])
+            self.model   = model or "llama-3.3-70b-versatile"
+
+        elif backend == "ollama":
+            import ollama as _ollama  # type: ignore[import]
+            self._client = _ollama
+            self.model   = model or "llama3.2:3b"
+
+        else:
+            raise ValueError(
+                f"Unknown backend {backend!r}. Valid options: 'groq', 'ollama'."
+            )
+
+    def generate(self, query: str, results: list[RetrievalResult]) -> str:
+        if not results:
+            return (
+                "No relevant passages were found in the corpus for this query. "
+                "Please rephrase or ask a different question."
+            )
+
+        context_block = _build_context_block(results)
+        user_msg      = (
+            f"SOURCES:\n{context_block}\n\n"
+            f"QUESTION:\n{query}\n\n"
+            f"ANSWER:"
+        )
+
+        if self.backend == "groq":
+            resp = self._client.chat.completions.create(
+                model=self.model,
+                messages=[
+                    {"role": "system", "content": _SYSTEM_PROMPT},
+                    {"role": "user",   "content": user_msg},
+                ],
+                temperature=self.temperature,
+                max_tokens=self.max_tokens,
+            )
+            return resp.choices[0].message.content.strip()
+
+        elif self.backend == "ollama":
+            resp = self._client.chat(
+                model=self.model,
+                messages=[
+                    {"role": "system", "content": _SYSTEM_PROMPT},
+                    {"role": "user",   "content": user_msg},
+                ],
+                options={
+                    "temperature": self.temperature,
+                    "num_predict": self.max_tokens,
+                },
+            )
+            return resp["message"]["content"].strip()
+
+        raise RuntimeError(f"Unhandled backend: {self.backend!r}")

rag/index.py

@@ -0,0 +1,80 @@
+"""
+rag/index.py
+------------
+FAISS IndexFlatIP wrapper for exact cosine-similarity retrieval.
+
+Why IndexFlatIP?
+  At M ≈ 7,000 chunks × 768 dims the index is ~21.5 MB and a single query
+  costs ~1.35 ms on CPU (5.4M FP32 multiplications). Approximate indices
+  (IVF, HNSW) introduce recall loss without meaningful latency benefit at
+  this scale.
+
+Embeddings MUST be L2-normalised before add() so that inner product = cosine.
+The BGEEmbedder guarantees this; do not pass raw embeddings.
+"""
+
+import pickle
+from pathlib import Path
+
+import faiss
+import numpy as np
+
+from rag.models import ChunkRecord
+
+
+class FAISSIndex:
+    def __init__(self, dim: int) -> None:
+        self.dim   = dim
+        self.index = faiss.IndexFlatIP(dim)
+        self._chunks: list[ChunkRecord] = []
+
+    # ── Build ─────────────────────────────────────────────────────────────────
+
+    def build(self, embeddings: np.ndarray, chunks: list[ChunkRecord]) -> None:
+        if embeddings.shape != (len(chunks), self.dim):
+            raise ValueError(
+                f"Embedding shape {embeddings.shape} does not match "
+                f"({len(chunks)}, {self.dim})"
+            )
+        self.index.add(embeddings)
+        self._chunks = list(chunks)
+
+    # ── Query ─────────────────────────────────────────────────────────────────
+
+    def search(
+        self, query_embedding: np.ndarray, k: int
+    ) -> list[tuple[ChunkRecord, float]]:
+        """
+        Return up to k (chunk, cosine_score) pairs, descending by score.
+        query_embedding must be shape (1, dim) and L2-normalised.
+        """
+        k = min(k, self.index.ntotal)
+        scores, indices = self.index.search(query_embedding, k)
+        results: list[tuple[ChunkRecord, float]] = []
+        for score, idx in zip(scores[0], indices[0]):
+            if idx == -1:
+                continue
+            results.append((self._chunks[idx], float(score)))
+        return results
+
+    # ── Persistence ───────────────────────────────────────────────────────────
+
+    def save(self, index_dir: Path) -> None:
+        index_dir = Path(index_dir)
+        index_dir.mkdir(parents=True, exist_ok=True)
+        faiss.write_index(self.index, str(index_dir / "faiss.index"))
+        with open(index_dir / "chunks.pkl", "wb") as fh:
+            pickle.dump(self._chunks, fh)
+
+    @classmethod
+    def load(cls, index_dir: Path, dim: int) -> "FAISSIndex":
+        index_dir = Path(index_dir)
+        obj       = cls(dim)
+        obj.index = faiss.read_index(str(index_dir / "faiss.index"))
+        with open(index_dir / "chunks.pkl", "rb") as fh:
+            obj._chunks = pickle.load(fh)
+        return obj
+
+    @property
+    def size(self) -> int:
+        return self.index.ntotal

rag/index/bm25.pkl

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7428eaba34b62697268b295b50290e0e107309b24cad30011a50d22e946f1ba5
+size 18054235

rag/index/chunks.pkl

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3fa2c5623c37543283e1a3465a2918849b74b05625bc291b3ed110de03c50387
+size 10208799

rag/index/faiss.index

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6396cf0a9b54346b30f895354f5ea167b6c1c08445af191dafcefebb6c0498f4
+size 17614893

rag/models.py

@@ -0,0 +1,39 @@
+"""
+rag/models.py
+-------------
+Canonical data types shared across all RAG modules.
+Import from here — never redefine these elsewhere.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Document:
+    doc_id:    str   # filename stem, e.g. "RBI_Master_Dir_084"
+    title:     str   # short human-readable label parsed from filename
+    source:    str   # "rbi" | "sebi"
+    raw_text:  str   # text content; mutated in-place by TextPreprocessor
+    file_path: str   # absolute path to source .txt file
+
+
+@dataclass
+class ChunkRecord:
+    chunk_id:   str   # f"{doc_id}__{chunk_idx:04d}" — globally unique
+    doc_id:     str   # parent Document.doc_id
+    title:      str   # inherited from parent Document
+    source:     str   # "rbi" | "sebi"
+    text:       str   # chunk text as indexed and embedded
+    chunk_idx:  int   # 0-indexed position within parent document
+    char_start: int   # character offset in preprocessed document text
+    char_end:   int   # exclusive end offset
+
+
+@dataclass
+class RetrievalResult:
+    chunk:       ChunkRecord
+    dense_score: float   # cosine similarity from FAISS  [-1, 1]
+    bm25_score:  float   # raw BM25Okapi score           [0, ∞)
+    rrf_score:   float   # RRF fused score               (0, 1/30]
+    dense_rank:  int     # 1-indexed rank in dense list  (candidates+1 if absent)
+    bm25_rank:   int     # 1-indexed rank in BM25 list   (candidates+1 if absent)

rag/pipeline.py

@@ -0,0 +1,172 @@
+"""
+rag/pipeline.py
+---------------
+RAGPipeline: the top-level orchestrator that wires ingestion, indexing,
+retrieval, and generation into a single callable interface.
+
+Public API (intentionally minimal, mirrors demo/rag/rag.py):
+    pipe = RAGPipeline()
+    pipe.build_index()   # run once; serialises to rag/index/
+    pipe.load_index()    # fast path on subsequent starts
+    result = pipe.ask("What are the KYC norms under SEBI?")
+    # result: {"answer": str, "sources": list[dict]} | {"error": str}
+
+The demo integration in demo/rag/rag.py is a thin shim over this module.
+"""
+
+import logging
+from pathlib import Path
+
+from rag.bm25_index import BM25Index
+from rag.chunking import RecursiveCharacterSplitter
+from rag.config import RAGConfig
+from rag.data_loader import DataLoader
+from rag.embeddings import BGEEmbedder
+from rag.generator import LLMGenerator
+from rag.index import FAISSIndex
+from rag.models import RetrievalResult
+from rag.preprocessing import TextPreprocessor
+from rag.retriever import HybridRetriever
+
+logger = logging.getLogger(__name__)
+
+
+class RAGPipeline:
+    def __init__(self, config: RAGConfig | None = None) -> None:
+        self.cfg       = config or RAGConfig()
+        self._embedder = BGEEmbedder(
+            model_name  = self.cfg.embedding_model,
+            device      = self.cfg.embedding_device,
+            batch_size  = self.cfg.embedding_batch_size,
+        )
+        self._generator = None
+
+        if getattr(self.cfg, "enable_generation", True):
+            self._generator = LLMGenerator(
+                backend     = self.cfg.llm_backend,
+                max_tokens  = self.cfg.max_tokens,
+                temperature = self.cfg.temperature,
+        )
+        self._retriever: HybridRetriever | None = None
+
+    # ── Index build (offline) ─────────────────────────────────────────────────
+
+    def build_index(self) -> None:
+        """
+        Full ingestion pipeline: load → preprocess → chunk → embed → index.
+        Idempotent: safe to re-run; overwrites rag/index/ on disk.
+        Typical runtime on CPU: 2–4 minutes for the 192-document corpus.
+        """
+        loader      = DataLoader(self.cfg.data_dir)
+        preprocessor = TextPreprocessor()
+        splitter    = RecursiveCharacterSplitter(
+            target_chunk_chars = self.cfg.target_chunk_chars,
+            overlap_chars      = self.cfg.overlap_chars,
+            min_chunk_chars    = self.cfg.min_chunk_chars,
+        )
+
+        docs = loader.load()
+        logger.info("Loaded %d documents", len(docs))
+
+        for doc in docs:
+            doc.raw_text = preprocessor.process(doc.raw_text)
+
+        all_chunks = []
+        for doc in docs:
+            all_chunks.extend(splitter.split_document(doc))
+        logger.info("Created %d chunks", len(all_chunks))
+
+        texts      = [c.text for c in all_chunks]
+        embeddings = self._embedder.encode_corpus(texts)
+
+        faiss_idx = FAISSIndex(self._embedder.dim)
+        faiss_idx.build(embeddings, all_chunks)
+        faiss_idx.save(self.cfg.index_dir)
+
+        bm25_idx = BM25Index()
+        bm25_idx.build(all_chunks)
+        bm25_idx.save(self.cfg.index_dir)
+
+        self._wire_retriever(faiss_idx, bm25_idx)
+        logger.info(
+            "Index built: %d vectors in FAISS, %d chunks in BM25. Saved to %s.",
+            faiss_idx.size, bm25_idx.size, self.cfg.index_dir,
+        )
+
+    # ── Index load (online startup) ───────────────────────────────────────────
+
+    def load_index(self) -> None:
+        faiss_idx = FAISSIndex.load(self.cfg.index_dir, self._embedder.dim)
+        bm25_idx  = BM25Index.load(self.cfg.index_dir)
+        self._wire_retriever(faiss_idx, bm25_idx)
+        logger.info(
+            "Index loaded: %d vectors (%s).",
+            faiss_idx.size, self.cfg.index_dir,
+        )
+
+    def _wire_retriever(self, faiss_idx: FAISSIndex, bm25_idx: BM25Index) -> None:
+        self._retriever = HybridRetriever(
+            faiss_index    = faiss_idx,
+            bm25_index     = bm25_idx,
+            embedder       = self._embedder,
+            top_k          = self.cfg.top_k,
+            candidates     = self.cfg.candidates,
+            rrf_k          = self.cfg.rrf_k,
+            max_per_source = self.cfg.max_per_source,
+        )
+
+    # ── Query (online) ────────────────────────────────────────────────────────
+
+    def ask(self, query: str, mode: str = "hybrid") -> dict:
+        """
+        Full RAG pipeline: retrieve → generate.
+
+        Args:
+            query: Natural language question.
+            mode:  "hybrid" | "dense" | "bm25" — retriever mode for ablation.
+
+        Returns:
+            {"answer": str, "sources": list[dict]}   on success
+            {"error": str}                            on failure
+        """
+        if not query or not query.strip():
+            return {"error": "Empty query."}
+        if self._retriever is None:
+            return {"error": "Index not loaded. Call build_index() or load_index() first."}
+
+        try:
+            results: list[RetrievalResult] = self._retriever.retrieve(
+                query.strip(), mode=mode
+            )
+            if self._generator is None:
+                return {"error": "Generation disabled in current configuration."}
+
+            answer = self._generator.generate(query.strip(), results)
+            sources = [
+                {
+                    "chunk_id":    r.chunk.chunk_id,
+                    "doc_id":      r.chunk.doc_id,
+                    "title":       r.chunk.title,
+                    "source":      r.chunk.source,
+                    "text":        r.chunk.text,
+                    "rrf_score":   round(r.rrf_score,   6),
+                    "dense_score": round(r.dense_score, 6),
+                    "bm25_score":  round(r.bm25_score,  4),
+                }
+                for r in results
+            ]
+            return {"answer": answer, "sources": sources}
+
+        except Exception as exc:  # noqa: BLE001
+            logger.exception("RAG pipeline error for query: %r", query)
+            return {"error": f"RAG pipeline error: {exc!s}"[:400]}
+
+    # ── Index status ──────────────────────────────────────────────────────────
+
+    @property
+    def index_ready(self) -> bool:
+        return self._retriever is not None
+
+    @property
+    def index_path(self) -> Path:
+        return self.cfg.index_dir

rag/preprocessing.py

@@ -0,0 +1,60 @@
+"""
+rag/preprocessing.py
+--------------------
+Lightweight text normalisation for PDF-extracted Indian regulatory documents.
+All operations are pure string transforms — no model inference.
+
+Pipeline (applied in order):
+  1. Unicode NFKC normalisation  — resolve ligatures, non-breaking spaces
+  2. Header/footer line removal  — heuristic pattern match on short lines
+  3. Trailing whitespace strip   — per-line
+  4. Blank-line collapse         — 3+ consecutive blank lines → 2
+  5. Leading/trailing strip      — final document trim
+"""
+
+import re
+import unicodedata
+
+
+# Lines matching these patterns and under 80 chars are dropped.
+# Ordered from most to least specific to minimise false positives.
+_HEADER_FOOTER_PATTERNS = re.compile(
+    r"""
+    ^\s*(?:
+        (?:reserve\s+bank\s+of\s+india)             |
+        (?:securities\s+and\s+exchange\s+board)      |
+        (?:rbi\s*[/|–-])                             |
+        (?:sebi\s*[/|–-])                            |
+        (?:page\s+\d+\s*(?:of\s+\d+)?)              |
+        (?:\d+\s*$)                                  |   # bare page numbers
+        (?:www\.\S+)                                 |
+        (?:https?://\S+)                             |
+        (?:©\s*.+)                                   |
+        (?:circular\s+no\.?\s*[a-z0-9/_\-\.]+$)
+    )\s*$
+    """,
+    re.IGNORECASE | re.VERBOSE,
+)
+
+_MULTI_BLANK = re.compile(r"\n{3,}")
+_TRAILING_SPACE = re.compile(r"[ \t]+$", re.MULTILINE)
+
+
+class TextPreprocessor:
+    def process(self, text: str) -> str:
+        text = unicodedata.normalize("NFKC", text)
+        text = self._strip_headers_footers(text)
+        text = _TRAILING_SPACE.sub("", text)
+        text = _MULTI_BLANK.sub("\n\n", text)
+        return text.strip()
+
+    @staticmethod
+    def _strip_headers_footers(text: str) -> str:
+        lines = text.splitlines()
+        cleaned: list[str] = []
+        for line in lines:
+            # Only apply heuristic to short lines to avoid false positives
+            if len(line) < 80 and _HEADER_FOOTER_PATTERNS.match(line):
+                continue
+            cleaned.append(line)
+        return "\n".join(cleaned)

rag/requirements.txt

@@ -0,0 +1,18 @@
+# RAG pipeline dependencies
+# Pin minor versions; patch versions are free to float for security fixes.
+
+# Core retrieval
+faiss-cpu>=1.8,<2.0
+sentence-transformers>=3.0,<4.0
+rank-bm25>=0.2,<0.3
+
+# Generation backends
+groq>=0.11,<1.0       # Groq API client (primary)
+ollama>=0.3,<1.0      # Ollama local client (fallback)
+
+# Utilities
+numpy>=1.26,<3.0
+tqdm>=4.66,<5.0
+
+# Evaluation (Phase 3)
+google-generativeai>=0.8,<1.0   # Gemini 1.5 Flash as faithfulness judge

rag/retriever.py

@@ -0,0 +1,107 @@
+"""
+rag/retriever.py
+----------------
+Hybrid retriever combining dense (FAISS) and lexical (BM25) search via
+Reciprocal Rank Fusion (Cormack et al., 2009).
+
+RRF formula:
+    score(d) = Σ_{r ∈ {dense, bm25}} 1 / (k_RRF + rank_r(d))
+where k_RRF=60 (empirically optimal constant from the original paper).
+Chunks absent from a list receive rank = candidates + 1.
+
+Two additional constraints:
+  - Source diversity: at most max_per_source chunks from the same regulatory
+    source ("rbi" or "sebi") in the final top-k, to support cross-document
+    synthesis queries.
+  - Score floor: dense-only and bm25-only modes supported for ablation
+    (pass mode="dense" | "bm25" | "hybrid").
+"""
+
+from rag.bm25_index import BM25Index
+from rag.embeddings import BGEEmbedder
+from rag.index import FAISSIndex
+from rag.models import ChunkRecord, RetrievalResult
+
+
+class HybridRetriever:
+    def __init__(
+        self,
+        faiss_index:    FAISSIndex,
+        bm25_index:     BM25Index,
+        embedder:       BGEEmbedder,
+        top_k:          int = 5,
+        candidates:     int = 20,
+        rrf_k:          int = 60,
+        max_per_source: int = 3,
+    ) -> None:
+        self._faiss         = faiss_index
+        self._bm25          = bm25_index
+        self._embedder      = embedder
+        self.top_k          = top_k
+        self.candidates     = candidates
+        self.rrf_k          = rrf_k
+        self.max_per_source = max_per_source
+
+    def retrieve(
+        self, query: str, mode: str = "hybrid"
+    ) -> list[RetrievalResult]:
+        """
+        mode: "hybrid" | "dense" | "bm25"
+          Used in Phase 3 ablation to isolate individual retriever contributions.
+        """
+        absent_rank = self.candidates + 1
+
+        # ── Dense retrieval ───────────────────────────────────────────────────
+        dense_hits: list[tuple[ChunkRecord, float]] = []
+        if mode in ("hybrid", "dense"):
+            qemb       = self._embedder.encode_query(query)
+            dense_hits = self._faiss.search(qemb, self.candidates)
+
+        # ── BM25 retrieval ────────────────────────────────────────────────────
+        bm25_hits: list[tuple[ChunkRecord, float]] = []
+        if mode in ("hybrid", "bm25"):
+            bm25_hits = self._bm25.search(query, self.candidates)
+
+        # ── Build rank & score lookup maps ────────────────────────────────────
+        dense_rank  = {c.chunk_id: r for r, (c, _) in enumerate(dense_hits, 1)}
+        bm25_rank   = {c.chunk_id: r for r, (c, _) in enumerate(bm25_hits, 1)}
+        dense_score = {c.chunk_id: s for c, s in dense_hits}
+        bm25_score  = {c.chunk_id: s for c, s in bm25_hits}
+        chunk_map   = {c.chunk_id: c for c, _ in dense_hits + bm25_hits}
+
+        # ── RRF scoring ───────────────────────────────────────────────────────
+        rrf_scores: dict[str, float] = {}
+        for cid in chunk_map:
+            rd = dense_rank.get(cid, absent_rank)
+            rb = bm25_rank.get(cid, absent_rank)
+            if mode == "dense":
+                rrf_scores[cid] = 1.0 / (self.rrf_k + rd)
+            elif mode == "bm25":
+                rrf_scores[cid] = 1.0 / (self.rrf_k + rb)
+            else:
+                rrf_scores[cid] = 1.0 / (self.rrf_k + rd) + 1.0 / (self.rrf_k + rb)
+
+        ranked = sorted(rrf_scores.items(), key=lambda x: x[1], reverse=True)
+
+        # ── Source diversity cap + top-k selection ────────────────────────────
+        results:      list[RetrievalResult] = []
+        source_count: dict[str, int]        = {}
+
+        for cid, rrf in ranked:
+            if len(results) >= self.top_k:
+                break
+            chunk  = chunk_map[cid]
+            n_from = source_count.get(chunk.source, 0)
+            if n_from >= self.max_per_source:
+                continue
+            source_count[chunk.source] = n_from + 1
+            results.append(RetrievalResult(
+                chunk       = chunk,
+                dense_score = dense_score.get(cid, 0.0),
+                bm25_score  = bm25_score.get(cid, 0.0),
+                rrf_score   = rrf,
+                dense_rank  = dense_rank.get(cid, absent_rank),
+                bm25_rank   = bm25_rank.get(cid, absent_rank),
+            ))
+
+        return results

rag/scripts/build_index.py

@@ -0,0 +1,89 @@
+"""
+rag/scripts/build_index.py
+--------------------------
+CLI entry point for the offline index build step.
+
+Usage (from project root):
+    python -m rag.scripts.build_index
+    python -m rag.scripts.build_index --data-dir data/parsed --index-dir rag/index
+    python -m rag.scripts.build_index --chunk-size 800   # ablation: small chunks
+    python -m rag.scripts.build_index --chunk-size 2400  # ablation: large chunks
+
+The script exits non-zero on any error so CI/CD pipelines can detect failures.
+"""
+
+import argparse
+import logging
+import sys
+import time
+from pathlib import Path
+
+from rag.pipeline import RAGPipeline
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s  %(levelname)-8s  %(message)s",
+    datefmt="%H:%M:%S",
+)
+logger = logging.getLogger(__name__)
+
+
+def parse_args() -> argparse.Namespace:
+    p = argparse.ArgumentParser(
+        description="Build FAISS + BM25 index for the IndiaFinBench RAG pipeline."
+    )
+    p.add_argument(
+        "--data-dir",
+        type=Path,
+        default=Path("data/parsed"),
+        help="Directory containing rbi/ and sebi/ subdirectories of .txt files.",
+    )
+    p.add_argument(
+        "--index-dir",
+        type=Path,
+        default=Path("rag/index"),
+        help="Output directory for faiss.index, chunks.pkl, bm25.pkl.",
+    )
+    p.add_argument("--chunk-size",    type=int, default=1600)
+    p.add_argument("--overlap",       type=int, default=200)
+    p.add_argument("--min-chunk",     type=int, default=100)
+    p.add_argument("--batch-size",    type=int, default=64,  help="Embedding batch size.")
+    p.add_argument("--device",        type=str, default="cpu")
+    return p.parse_args()
+
+
+def main() -> None:
+    # Import here so the script works from any working directory
+    from rag.config import RAGConfig
+    from rag.pipeline import RAGPipeline
+
+    args = parse_args()
+    cfg  = RAGConfig(
+        data_dir            = args.data_dir,
+        index_dir           = args.index_dir,
+        target_chunk_chars  = args.chunk_size,
+        overlap_chars       = args.overlap,
+        min_chunk_chars     = args.min_chunk,
+        embedding_batch_size= args.batch_size,
+        embedding_device    = args.device,
+    )
+
+    logger.info("Config: chunk=%d overlap=%d device=%s", cfg.target_chunk_chars, cfg.overlap_chars, cfg.embedding_device)
+    logger.info("Data dir  : %s", cfg.data_dir.resolve())
+    logger.info("Index dir : %s", cfg.index_dir.resolve())
+
+    t0 = time.perf_counter()
+    try:
+        cfg.enable_generation = False
+        pipe = RAGPipeline(config=cfg)
+        pipe.build_index()
+    except Exception:
+        logger.exception("Index build failed.")
+        sys.exit(1)
+
+    elapsed = time.perf_counter() - t0
+    logger.info("Done. Total time: %.1fs", elapsed)
+
+
+if __name__ == "__main__":
+    main()

rag/scripts/run_evaluation.py

@@ -0,0 +1,253 @@
+"""
+rag/scripts/run_evaluation.py
+------------------------------
+CLI entry point for Phase 3 evaluation.
+
+Stages:
+  1. Load frozen index (must exist — run build_index first).
+  2. Load or generate the 50-item eval dataset.
+  3. Run retrieval-only ablation (B0–B5) — no LLM calls, fast.
+  4. Optionally run generation evaluation on B2 (hybrid) and B0 (dense)
+     using the configured LLM backend + Gemini faithfulness judge.
+  5. Print structured terminal report.
+  6. Save JSON report to data/eval/results_<timestamp>.json.
+
+Usage:
+    python -m rag.scripts.run_evaluation
+    python -m rag.scripts.run_evaluation --no-generation
+    python -m rag.scripts.run_evaluation --eval-set data/eval/eval_set.json
+    python -m rag.scripts.run_evaluation --configs B0,B2,B5  # subset of ablation
+"""
+
+import argparse
+import dataclasses
+import json
+import logging
+import os
+import sys
+import time
+from datetime import datetime
+from pathlib import Path
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s  %(levelname)-8s  %(message)s",
+    datefmt="%H:%M:%S",
+)
+logger = logging.getLogger(__name__)
+
+
+def parse_args() -> argparse.Namespace:
+    p = argparse.ArgumentParser(
+        description="Run Phase 3 evaluation for the IndiaFinBench RAG pipeline."
+    )
+    p.add_argument("--index-dir",    type=Path, default=Path("rag/index"))
+    p.add_argument("--data-dir",     type=Path, default=Path("data/parsed"))
+    p.add_argument("--eval-set",     type=Path, default=Path("data/eval/eval_set.json"),
+                   help="Path to eval_set.json. Generated if missing and --generate-eval set.")
+    p.add_argument("--output-dir",   type=Path, default=Path("data/eval"))
+    p.add_argument("--no-generation", action="store_true",
+                   help="Skip generation evaluation (retrieval metrics only).")
+    p.add_argument("--generate-eval", action="store_true",
+                   help="Generate synthetic eval set via Gemini if eval_set.json missing.")
+    p.add_argument("--n-synthetic",  type=int, default=35,
+                   help="Number of synthetic QA pairs to generate.")
+    p.add_argument("--configs",      type=str, default=None,
+                   help="Comma-separated subset of ablation config IDs to run, "
+                        "e.g. B0_dense_only,B2_hybrid,B5_higher_k")
+    p.add_argument("--gemini-key",   type=str, default=None,
+                   help="Gemini API key (overrides GEMINI_API_KEY env var).")
+    p.add_argument("--groq-key",     type=str, default=None,
+                   help="Groq API key (overrides GROQ_API_KEY env var).")
+    p.add_argument("--max-gen-items",type=int, default=None,
+                   help="Limit generation eval to first N items (useful for quick tests).")
+    return p.parse_args()
+
+
+def main() -> None:
+    # Force UTF-8 stdout so box-drawing chars in the terminal report work on Windows
+    sys.stdout.reconfigure(encoding="utf-8")
+
+    args = parse_args()
+
+    # Apply key overrides before any imports that might read them
+    if args.gemini_key:
+        os.environ["GEMINI_API_KEY"] = args.gemini_key
+    if args.groq_key:
+        os.environ["GROQ_API_KEY"] = args.groq_key
+
+    # ── Imports ───────────────────────────────────────────────────────────────
+    from rag.config import RAGConfig
+    from rag.data_loader import DataLoader
+    from rag.embeddings import BGEEmbedder
+    from rag.evaluation import (
+        ABLATION_CONFIGS,
+        FAITHFULNESS_JUDGE_MODEL,
+        FAITHFULNESS_JUDGE_PROMPT_VERSION,
+        evaluate_generation,
+        load_or_generate_eval_set,
+        print_terminal_report,
+        run_ablation,
+        save_report,
+    )
+    from rag.bm25_index import BM25Index
+    from rag.index import FAISSIndex
+    from rag.pipeline import RAGPipeline
+    from rag.preprocessing import TextPreprocessor
+    from rag.chunking import RecursiveCharacterSplitter
+
+    # ── Load index ────────────────────────────────────────────────────────────
+    if not (args.index_dir / "faiss.index").exists():
+        logger.error(
+            "Index not found at %s. Run: python -m rag.scripts.build_index first.",
+            args.index_dir,
+        )
+        sys.exit(1)
+
+    cfg = RAGConfig(data_dir=args.data_dir, index_dir=args.index_dir)
+
+    logger.info("Loading embedder: %s", cfg.embedding_model)
+    t_emb = time.perf_counter()
+    embedder = BGEEmbedder(
+        model_name  = cfg.embedding_model,
+        device      = cfg.embedding_device,
+        batch_size  = cfg.embedding_batch_size,
+    )
+    logger.info("  Embedder loaded in %.1fs (dim=%d)", time.perf_counter() - t_emb, embedder.dim)
+
+    logger.info("Loading FAISS + BM25 index from %s", args.index_dir)
+    faiss_idx = FAISSIndex.load(args.index_dir, embedder.dim)
+    bm25_idx  = BM25Index.load(args.index_dir)
+    logger.info("  Index: %d vectors, %d BM25 chunks", faiss_idx.size, bm25_idx.size)
+
+    # ── Load or generate eval set ─────────────────────────────────────────────
+    docs:   list | None = None
+    chunks: list | None = None
+
+    if not args.eval_set.exists():
+        if not args.generate_eval:
+            logger.error(
+                "Eval set not found at %s. "
+                "Run with --generate-eval to create it, or provide --eval-set path.",
+                args.eval_set,
+            )
+            sys.exit(1)
+        logger.info("Generating synthetic eval set (%d items)…", args.n_synthetic)
+        loader      = DataLoader(cfg.data_dir)
+        preprocessor = TextPreprocessor()
+        splitter    = RecursiveCharacterSplitter(
+            target_chunk_chars=cfg.target_chunk_chars,
+            overlap_chars=cfg.overlap_chars,
+            min_chunk_chars=cfg.min_chunk_chars,
+        )
+        docs   = loader.load()
+        for d in docs:
+            d.raw_text = preprocessor.process(d.raw_text)
+        chunks = [c for d in docs for c in splitter.split_document(d)]
+
+    eval_items = load_or_generate_eval_set(
+        path        = args.eval_set,
+        docs        = docs,
+        chunks      = chunks,
+        n_synthetic = args.n_synthetic,
+        api_key     = args.gemini_key,
+    )
+    n_with_gt = sum(1 for i in eval_items if i.relevant_chunk_ids)
+    logger.info(
+        "Eval set: %d items total (%d with ground-truth chunk IDs, %d adversarial).",
+        len(eval_items), n_with_gt, len(eval_items) - n_with_gt,
+    )
+
+    # ── Filter ablation configs ───────────────────────────────────────────────
+    selected_configs = ABLATION_CONFIGS
+    if args.configs:
+        ids = {c.strip() for c in args.configs.split(",")}
+        selected_configs = [c for c in ABLATION_CONFIGS if c["id"] in ids]
+        if not selected_configs:
+            logger.error("No matching configs found for: %s", args.configs)
+            sys.exit(1)
+
+    # ── Stage 1: Retrieval ablation ───────────────────────────────────────────
+    logger.info("Stage 1: Retrieval-only ablation (%d configs)…", len(selected_configs))
+    ablation_results = run_ablation(
+        base_faiss  = faiss_idx,
+        base_bm25   = bm25_idx,
+        embedder    = embedder,
+        base_cfg    = cfg,
+        eval_items  = eval_items,
+        configs     = selected_configs,
+    )
+
+    # ── Stage 2: Generation evaluation (optional) ─────────────────────────────
+    gen_results: dict = {}
+
+    if not args.no_generation:
+        gemini_key = args.gemini_key or os.environ.get("GEMINI_API_KEY")
+        if not gemini_key:
+            logger.warning(
+                "GEMINI_API_KEY not set — skipping generation evaluation. "
+                "Set it or pass --gemini-key to enable faithfulness scoring."
+            )
+        else:
+            import google.generativeai as genai  # type: ignore[import]
+            genai.configure(api_key=gemini_key)
+            judge_model = genai.GenerativeModel(
+                FAITHFULNESS_JUDGE_MODEL,
+                generation_config={"temperature": 0.0, "max_output_tokens": 1024},
+            )
+
+            # Run generation eval on B2 (proposed) and B0 (dense baseline)
+            for target_id in ("B2_hybrid", "B0_dense_only"):
+                target_cfg = next(
+                    (c for c in selected_configs if c["id"] == target_id), None
+                )
+                if target_cfg is None:
+                    continue
+                logger.info("Stage 2: Generation eval for %s…", target_id)
+
+                # Wire up a full pipeline with the appropriate mode
+                pipeline = RAGPipeline(config=cfg)
+                pipeline.load_index()
+
+                gm, gf = evaluate_generation(
+                    pipeline    = pipeline,
+                    eval_items  = eval_items,
+                    embedder    = embedder,
+                    gemini_model= judge_model,
+                    mode        = target_cfg["mode"],
+                    max_items   = args.max_gen_items,
+                )
+                gen_results[target_id] = (gm, gf)
+
+    # ── Print terminal report ─────────────────────────────────────────────────
+    print_terminal_report(ablation_results, gen_results, eval_items)
+
+    # ── Save JSON report ──────────────────────────────────────────────────────
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    report_path = args.output_dir / f"results_{timestamp}.json"
+
+    config_snapshot = {
+        "embedding_model":  cfg.embedding_model,
+        "target_chunk_chars": cfg.target_chunk_chars,
+        "overlap_chars":    cfg.overlap_chars,
+        "top_k":            cfg.top_k,
+        "candidates":       cfg.candidates,
+        "rrf_k":            cfg.rrf_k,
+        "max_per_source":   cfg.max_per_source,
+        "llm_backend":      cfg.llm_backend,
+        "temperature":      cfg.temperature,
+        "index_dir":        str(args.index_dir),
+        "eval_items":       len(eval_items),
+        "items_with_gt":    n_with_gt,
+        "judge_model":      FAITHFULNESS_JUDGE_MODEL,
+        "judge_prompt_ver": FAITHFULNESS_JUDGE_PROMPT_VERSION,
+        "timestamp":        timestamp,
+    }
+
+    save_report(ablation_results, gen_results, config_snapshot, report_path)
+    print(f"\n  Report saved → {report_path}")
+    print()
+
+
+if __name__ == "__main__":
+    main()