UI improvements + specs.md update

CLAUDE.md

@@ -2,6 +2,13 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+## Workflow gate (READ FIRST)
+
+Before changing anything, read **`SPEC.md`** — it defines the mandatory process:
+sanity tests (`tests/test_sanity.py`) must pass before any commit (enforced by
+the git pre-commit hook installed via `bash scripts/install-hooks.sh`), and the
+**How To Guide** tab in `ui/app.py` must be updated on any user-facing UI change.
+
 ## Project
 
 **G.U.I.D.E.** (Grievance Utility for Information Extraction, Drafting and Enrichment) — a privacy-first consumer complaint assistant for Indian consumers. Users describe their complaint in plain language; the system redacts PII locally, drafts a formal letter, and routes to the correct Indian regulatory authority.

scripts/hooks/pre-commit

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# G.U.I.D.E. pre-commit gate — runs the sanity suite (SPEC.md §3-4).
+# No code may be committed while these fail. Bypass only with --no-verify.
+set -euo pipefail
+
+ROOT="$(git rev-parse --show-toplevel)"
+cd "$ROOT"
+
+if [ -x ".venv/bin/python" ]; then
+  PY=".venv/bin/python"
+else
+  PY="python3"
+fi
+
+echo "[pre-commit] Running G.U.I.D.E. sanity tests ($PY)…"
+if ! "$PY" -m pytest tests/test_sanity.py -q; then
+  echo ""
+  echo "[pre-commit] ❌ Sanity tests failed — commit aborted (see SPEC.md)."
+  echo "[pre-commit]    Fix the failures, or bypass with 'git commit --no-verify'"
+  echo "[pre-commit]    (only in a genuine emergency; the change is then not Done)."
+  exit 1
+fi
+echo "[pre-commit] ✅ Sanity tests passed."

scripts/install-hooks.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Install the G.U.I.D.E. git hooks (SPEC.md §4). Idempotent — run anytime.
+set -euo pipefail
+
+ROOT="$(git rev-parse --show-toplevel)"
+SRC="$ROOT/scripts/hooks/pre-commit"
+DST="$ROOT/.git/hooks/pre-commit"
+
+if [ ! -f "$SRC" ]; then
+  echo "❌ $SRC not found." >&2
+  exit 1
+fi
+
+cp "$SRC" "$DST"
+chmod +x "$DST"
+echo "✅ Installed pre-commit hook → $DST"
+echo "   It runs tests/test_sanity.py and blocks commits if they fail."

src/api/routes.py

@@ -53,6 +53,48 @@ logger = logging.getLogger(__name__)
 
 router = APIRouter(prefix="/api")
 
+
+def _llm_http_error(exc: Exception) -> HTTPException:
+    """Translate an LLM/agent exception into a calm, user-friendly HTTPException.
+
+    The raw exception is already logged by the caller (logger.exception); this
+    only shapes the message the UI shows verbatim. Anthropic surfaces transient
+    capacity issues as an 'Overloaded' APIStatusError (HTTP 529) and rate limits
+    as RateLimitError (429) — both are temporary and worth a retry.
+    """
+    name = type(exc).__name__
+    text = str(exc).lower()
+    if "overloaded" in text or name == "OverloadedError" or "529" in text:
+        return HTTPException(
+            status_code=503,
+            detail=("Claude (the AI service) is briefly overloaded with requests. "
+                    "Please wait a few seconds and send your message again — your "
+                    "conversation is saved."),
+        )
+    if name == "RateLimitError" or "rate limit" in text or "429" in text:
+        return HTTPException(
+            status_code=429,
+            detail=("The AI service is handling a high volume of requests right now. "
+                    "Please wait about a minute and try again."),
+        )
+    if name == "APITimeoutError" or "timeout" in text or "timed out" in text:
+        return HTTPException(
+            status_code=504,
+            detail=("The AI took too long to respond. Please try sending your "
+                    "message again."),
+        )
+    if name == "AuthenticationError" or "authentication" in text or "401" in text:
+        return HTTPException(
+            status_code=502,
+            detail=("The assistant isn't configured correctly on the server "
+                    "(authentication failed). Please contact the site operator."),
+        )
+    return HTTPException(
+        status_code=502,
+        detail=("The AI service ran into an unexpected error. Please try again in "
+                "a moment; if it keeps happening, try rephrasing your message."),
+    )
+
 # Upload directory inside the project root — survives server restarts unlike
 # tempfile.gettempdir() which macOS can purge between sessions.
 _UPLOAD_DIR = Path(__file__).resolve().parent.parent.parent / "uploads"
@@ -159,7 +201,7 @@ async def send_message(session_id: str, req: MessageRequest):
         )
     except Exception as exc:
         logger.exception("CMA error in session %s", session_id)
-        raise HTTPException(status_code=500, detail=str(exc)) from exc
+        raise _llm_http_error(exc) from exc
 
     # 3. Persist conversation turn
     session_store.append_history(session_id, "user", redacted_text)
@@ -318,7 +360,7 @@ async def validate_entities(session_id: str, req: ValidateEntitiesRequest):
         )
     except Exception as exc:
         logger.exception("confirm_entities error in session %s", session_id)
-        raise HTTPException(status_code=500, detail=str(exc)) from exc
+        raise _llm_http_error(exc) from exc
 
     # The [USER CONFIRMED] message and the draft reply are both part of history
     confirmed_marker = f"[USER CONFIRMED]: {req.entities}"
@@ -351,7 +393,7 @@ async def escalation_guide(session_id: str):
         reply: str = await run_in_threadpool(session.agent.generate_escalation)
     except Exception as exc:
         logger.exception("generate_escalation error in session %s", session_id)
-        raise HTTPException(status_code=500, detail=str(exc)) from exc
+        raise _llm_http_error(exc) from exc
 
     session_store.append_history(session_id, "user", "[Generate escalation guide]")
     session_store.append_history(session_id, "assistant", reply)
@@ -409,7 +451,7 @@ async def classify_debug(req: ClassifyRequest):
     try:
         result = await run_in_threadpool(classify, req.text)
     except Exception as exc:
-        raise HTTPException(status_code=500, detail=str(exc)) from exc
+        raise _llm_http_error(exc) from exc
 
     return ClassifyResponse(
         domain=result.domain,
@@ -428,7 +470,7 @@ async def extract_debug(req: ExtractRequest):
     try:
         entities = await run_in_threadpool(extract_entities, req.text)
     except Exception as exc:
-        raise HTTPException(status_code=500, detail=str(exc)) from exc
+        raise _llm_http_error(exc) from exc
 
     return ExtractResponse(
         entities=[EntityOut(**dataclasses.asdict(e)) for e in entities]

tests/test_sanity.py

@@ -0,0 +1,178 @@
+"""
+G.U.I.D.E. sanity suite — the fast, must-pass gate that runs before every commit.
+
+These tests deliberately avoid loading ML checkpoints, the spaCy model, the
+Anthropic API, or the network. They catch the classes of regression we have
+actually hit while iterating on the UI/API:
+
+  * the Gradio app graph failing to build (output/intput-count or scope bugs),
+  * the API request/response schemas breaking,
+  * the three privacy/export features (redaction reveal, audit trail, PDF)
+    silently breaking,
+  * the privacy redactor contract (RedactionResult.spans) changing,
+  * the friendly LLM-error mapping regressing,
+  * and — per SPEC.md — the **How To Guide** tab drifting out of sync whenever a
+    user-facing tab is added or renamed.
+
+Run with:  python -m pytest tests/test_sanity.py -q
+This is wired into the git pre-commit hook (see SPEC.md). If any of these fail,
+the commit is blocked.
+"""
+
+from __future__ import annotations
+
+import importlib
+import re
+import sys
+import tempfile
+from pathlib import Path
+
+import pytest
+
+_ROOT = Path(__file__).resolve().parent.parent
+_UI = _ROOT / "ui"
+for _p in (str(_ROOT), str(_UI)):
+    if _p not in sys.path:
+        sys.path.insert(0, _p)
+
+
+@pytest.fixture(scope="module")
+def app_module():
+    """Import ui/app.py once for the whole module."""
+    return importlib.import_module("app")
+
+
+# ---------------------------------------------------------------------------
+# 1. The Gradio app graph must build (catches event/component wiring bugs).
+# ---------------------------------------------------------------------------
+
+def test_ui_app_builds(app_module):
+    demo = app_module.build_app()
+    assert demo is not None
+    assert type(demo).__name__ == "Blocks"
+
+
+# ---------------------------------------------------------------------------
+# 2. API schemas import and validate.
+# ---------------------------------------------------------------------------
+
+def test_api_models_and_routes_import():
+    from src.api import models, routes  # noqa: F401
+
+    msg = models.MessageResponse(
+        reply="hi", pii_redacted=True, pii_types_found=["PERSON"],
+        original_text="a", redacted_text="b",
+        redactions=[models.RedactionSpanOut(
+            entity_type="PERSON", original="a", placeholder="<PERSON>",
+            start=0, end=1)],
+    )
+    assert msg.redactions[0].placeholder == "<PERSON>"
+
+    audit = models.AuditResponse(session_id="s", entries=[models.AuditEntry(
+        timestamp="t", event="outbound_to_anthropic", description="d",
+        transmitted_text="b", pii_types_found=["PERSON"], pii_count=1,
+        leak_check="passed")])
+    assert audit.entries[0].leak_check == "passed"
+
+
+# ---------------------------------------------------------------------------
+# 3. Privacy redactor contract — RedactionResult must carry per-span reveal data.
+# ---------------------------------------------------------------------------
+
+def test_redactor_result_contract():
+    from src.privacy.redactor import RedactionResult, RedactionSpan
+
+    r = RedactionResult(redacted_text="x")
+    assert hasattr(r, "spans") and r.spans == []
+    span = RedactionSpan(entity_type="PERSON", original="Ravi",
+                         placeholder="<PERSON>", start=0, end=4)
+    assert span.placeholder == "<PERSON>"
+
+
+# ---------------------------------------------------------------------------
+# 4. Feature helpers: redaction reveal, audit render, PDF export.
+# ---------------------------------------------------------------------------
+
+def test_redaction_reveal_html(app_module):
+    resp = {
+        "original_text": "I am Ravi, phone 9876543210.",
+        "redacted_text": "I am <PERSON>, phone <PHONE_NUMBER>.",
+        "redactions": [
+            {"entity_type": "PERSON", "original": "Ravi",
+             "placeholder": "<PERSON>", "start": 5, "end": 9},
+            {"entity_type": "PHONE_NUMBER", "original": "9876543210",
+             "placeholder": "<PHONE_NUMBER>", "start": 17, "end": 27},
+        ],
+    }
+    html = app_module._render_redaction_html(resp)
+    assert "Ravi" in html and "&lt;PERSON&gt;" in html
+    assert "2 personal identifier" in html
+    # Nothing stripped → panel hidden.
+    assert app_module._render_redaction_html({"redactions": []}) == ""
+
+
+def test_audit_render(app_module):
+    assert "No activity yet" in app_module._render_audit_html([])
+    entries = [{
+        "timestamp": "2026-06-23T12:30:01+00:00", "event": "outbound_to_anthropic",
+        "description": "Message sent to Claude API — 1 personal identifier stripped.",
+        "transmitted_text": "I am <PERSON>", "pii_types_found": ["PERSON"],
+        "pii_count": 1, "leak_check": "passed",
+    }]
+    out = app_module._render_audit_html(entries)
+    assert "0 raw identifiers transmitted" in out
+
+
+def test_pdf_export(app_module):
+    draft = ("Subject: Test complaint\n\nTo,\nThe Grievance Officer\n\n"
+             "Dear Sir/Madam,\n\nThis is a test.\n\nYours sincerely,\n<PERSON>")
+    out = tempfile.mktemp(suffix=".pdf")
+    app_module._build_pdf(draft, out)
+    data = Path(out).read_bytes()
+    assert data[:5] == b"%PDF-" and len(data) > 800
+
+
+# ---------------------------------------------------------------------------
+# 5. Friendly LLM-error mapping (overloaded / rate-limit / timeout).
+# ---------------------------------------------------------------------------
+
+def test_llm_error_mapping():
+    from src.api.routes import _llm_http_error
+
+    assert _llm_http_error(Exception("Overloaded")).status_code == 503
+    assert _llm_http_error(Exception("rate limit exceeded")).status_code == 429
+    assert _llm_http_error(Exception("Request timed out")).status_code == 504
+    overloaded = _llm_http_error(Exception("Overloaded"))
+    assert "overloaded" in overloaded.detail.lower()
+
+
+# ---------------------------------------------------------------------------
+# 6. SPEC rule: the "How To Guide" tab must mention every user-facing tab.
+#    This fails the moment a tab is added/renamed without updating the guide.
+# ---------------------------------------------------------------------------
+
+def _plain(label: str) -> str:
+    """Strip emoji/punctuation from a tab label → its plain name."""
+    return re.sub(r"[^A-Za-z ]", "", label).strip()
+
+
+def test_how_to_guide_lists_every_tab():
+    src = (_UI / "app.py").read_text(encoding="utf-8")
+    labels = re.findall(r'gr\.Tab\("([^"]+)"\)', src)
+    assert labels, "No gr.Tab(...) definitions found — did the UI structure change?"
+
+    guide_start = src.index('gr.Tab("📖 How To Guide")')
+    guide_end = src.index('gr.Tab("💬 Chat")')
+    guide_text = src[guide_start:guide_end]
+
+    # Every tab except the guide itself and the technical About tab must be
+    # described in the How To Guide.
+    skip = {"How To Guide", "About"}
+    missing = [
+        _plain(lbl) for lbl in labels
+        if _plain(lbl) not in skip and _plain(lbl) not in guide_text
+    ]
+    assert not missing, (
+        f"The 'How To Guide' tab does not mention these tabs: {missing}. "
+        "Per SPEC.md, update the How To Guide whenever you add or rename a tab."
+    )

ui/app.py

@@ -206,27 +206,38 @@ _THEME = gr.themes.Soft(
 # on <body>; our custom CSS variables cascade from there too, so one class flip
 # restyles both Gradio's components and our bespoke hero/reveal/audit panels.
 # The choice is persisted in localStorage and restored on load.
+# Apply the `dark` class to every element Gradio might key off (html / body /
+# gradio-app) so the toggle is robust regardless of which one its theme reads.
+_THEME_APPLY_FN = """
+  function _guideApplyTheme(dark) {
+    [document.documentElement, document.body,
+     document.querySelector('gradio-app')].forEach(function (el) {
+      if (el) el.classList.toggle('dark', dark);
+    });
+    var b = document.querySelector('#theme-toggle button');
+    if (b) b.textContent = dark ? '☀️  Light' : '🌙  Dark';
+  }
+"""
+
 _THEME_TOGGLE_JS = """() => {
-  const isDark = document.body.classList.toggle('dark');
-  const app = document.querySelector('gradio-app');
-  if (app) app.classList.toggle('dark', isDark);
-  const b = document.querySelector('#theme-toggle button');
-  if (b) b.textContent = isDark ? '☀️  Light' : '🌙  Dark';
-  try { localStorage.setItem('guide-theme', isDark ? 'dark' : 'light'); } catch (e) {}
-}"""
+  %s
+  const dark = !document.documentElement.classList.contains('dark');
+  _guideApplyTheme(dark);
+  try { localStorage.setItem('guide-theme', dark ? 'dark' : 'light'); } catch (e) {}
+}""" % _THEME_APPLY_FN
 
 _THEME_LOAD_JS = """() => {
-  // Light is the default: only go dark when the user explicitly chose it before.
+  %s
+  // Light is the DEFAULT: go dark only if the user explicitly chose it before.
   let pref = 'light';
   try { pref = localStorage.getItem('guide-theme') || 'light'; } catch (e) {}
-  const isDark = pref === 'dark';
-  const app = document.querySelector('gradio-app');
-  // Force-clear any system/Gradio-applied dark unless the saved choice is dark.
-  document.body.classList.toggle('dark', isDark);
-  if (app) app.classList.toggle('dark', isDark);
-  const b = document.querySelector('#theme-toggle button');
-  if (b) b.textContent = isDark ? '☀️  Light' : '🌙  Dark';
-}"""
+  const dark = pref === 'dark';
+  // Re-assert a few times to override any system/Gradio dark applied late
+  // during hydration, which would otherwise leave the page dark by default.
+  _guideApplyTheme(dark);
+  setTimeout(() => _guideApplyTheme(dark), 60);
+  setTimeout(() => _guideApplyTheme(dark), 250);
+}""" % _THEME_APPLY_FN
 
 # ── API helpers ──────────────────────────────────────────────────────────────
 
@@ -286,6 +297,27 @@ def _api_audit(session_id: str) -> dict:
     return r.json()
 
 
+def _http_error_detail(exc: "requests.exceptions.HTTPError", fallback: str) -> str:
+    """Pull the backend's user-friendly `detail` from an HTTPError, else fallback.
+
+    The API maps LLM-provider hiccups (overloaded / rate-limited / timeout) to a
+    calm `detail` string, so the UI can show it verbatim.
+    """
+    try:
+        detail = (exc.response.json() or {}).get("detail", "")
+    except Exception:
+        detail = ""
+    if not detail:
+        code = getattr(getattr(exc, "response", None), "status_code", None)
+        if code == 503:
+            detail = ("Claude is briefly overloaded. Please wait a few seconds "
+                      "and try again.")
+        elif code == 429:
+            detail = ("The AI is rate-limiting requests right now. Please wait a "
+                      "moment and try again.")
+    return detail or fallback
+
+
 # ── Display helpers ──────────────────────────────────────────────────────────
 
 # Presidio placeholders look like <PERSON>, <EMAIL_ADDRESS>, <PHONE_NUMBER>.
@@ -736,16 +768,17 @@ def build_app() -> gr.Blocks:
 
 | Tab | What it does |
 |-----|-------------|
-| 💬 **Chat** | Describe your complaint in plain language and optionally attach a receipt, bill, or screenshot. G.U.I.D.E. asks follow-up questions, reads any attached document automatically, and collects all the details needed for your letter. |
+| 💬 **Chat** | Describe your complaint in plain language and optionally attach a receipt, bill, or screenshot. G.U.I.D.E. asks follow-up questions, reads any attached document automatically, and collects all the details needed for your letter. The 🔒 **“See what we protected”** panel shows, side by side, exactly which personal details were removed before anything reached the AI. |
 | ✅ **Verify Entities** | Review and correct the key details G.U.I.D.E. extracted from your complaint. Once you click **Confirm & Generate Draft**, your letter is created. |
-| 📄 **Complaint Draft** | Your ready-to-send formal complaint letter. Copy it to your clipboard or download it as a text file. |
+| 📄 **Complaint Draft** | Your ready-to-send formal complaint letter. Copy it to your clipboard or download it as a **.txt** or a formatted **PDF**. |
 | 🏛️ **Escalation Guide** | Tells you exactly which authority to contact — NCH, TRAI, RBI Ombudsman, IRDAI — with direct links to their complaint portals. |
+| 🔒 **Privacy Audit** | A timestamped record of every time your data was transmitted or processed, with a verified *“0 raw identifiers transmitted”* guarantee — so you can confirm your private details never left this server unprotected. |
 
 ---
 
 ## 🔒 Your Privacy
 
-> **Your details stay private.** Before your complaint is processed, personal information — your name, phone number, Aadhaar number, PAN, and bank account details — is automatically removed on this server. The AI only ever sees placeholders like `<PERSON>` or `<PHONE_NUMBER>`, never your real data. The 🔒 badge in the Chat tab confirms when this has happened.
+> **Your details stay private.** Before your complaint is processed, personal information — your name, phone number, Aadhaar number, PAN, and bank account details — is automatically removed on this server. The AI only ever sees placeholders like `<PERSON>` or `<PHONE_NUMBER>`, never your real data. The 🔒 badge in the Chat tab confirms when this has happened, the **“See what we protected”** panel shows you precisely what was removed, and the **🔒 Privacy Audit** tab keeps a full transmission log you can inspect at any time.
 
 ---
 
@@ -1080,8 +1113,16 @@ the IISc Deep Learning course project.
                     "⚠️ Cannot reach the G.U.I.D.E. backend at "
                     "http://localhost:8000. Please start the API server."
                 )
+            except requests.exceptions.HTTPError as exc:
+                # Backend maps LLM provider issues (overloaded / rate-limited /
+                # timeout) to a friendly `detail` — show it as-is.
+                return _err("⚠️ " + _http_error_detail(
+                    exc,
+                    "The assistant couldn't process that just now. "
+                    "Please try again in a moment.",
+                ))
             except Exception as exc:
-                return _err(f"⚠️ Error: {exc}")
+                return _err(f"⚠️ Something went wrong: {exc}")
 
             reply   = resp.get("reply", "")
             pii_hit = resp.get("pii_redacted", False)
@@ -1200,12 +1241,10 @@ the IISc Deep Learning course project.
             except requests.exceptions.ConnectionError:
                 return _err("⚠️ Cannot reach the backend.")
             except requests.exceptions.HTTPError as exc:
-                detail = ""
-                try:
-                    detail = exc.response.json().get("detail", "")
-                except Exception:
-                    pass
-                return _err(f"⚠️ Confirmation failed: {detail or exc}")
+                return _err("⚠️ " + _http_error_detail(
+                    exc,
+                    "Couldn't generate the draft just now. Please try again in a moment.",
+                ))
             except Exception as exc:
                 return _err(f"⚠️ Error: {exc}")
 
@@ -1267,14 +1306,11 @@ the IISc Deep Learning course project.
             try:
                 resp = _api_escalation_guide(sid)
             except requests.exceptions.HTTPError as exc:
-                detail = ""
-                try:
-                    detail = exc.response.json().get("detail", "")
-                except Exception:
-                    pass
                 return _keep(
-                    f"⚠️ Escalation guide failed: {detail or exc}\n\n"
-                    'You can ask G.U.I.D.E. "What should I do next?" in the Chat tab.'
+                    "⚠️ " + _http_error_detail(
+                        exc,
+                        "Couldn't fetch the escalation guide just now.",
+                    ) + '\n\nYou can ask G.U.I.D.E. "What should I do next?" in the Chat tab.'
                 )
             except Exception as exc:
                 return _keep(