Add Interpretability tab, fix mandatory verdict logic, demo reset, UI polish

- core/config.py: add BIDDER_NAMES dict (shared across all tabs)
- core/evaluator.py: richer criterion_evaluated audit payload (extracted_value,
llm_confidence, ocr_tier, reason, escalation_reason)
- ui/tab_review.py: store original_verdict + original_extracted_value in
human_review_action audit entries
- ui/tab_bidders.py: fix _overall_verdict to only count mandatory criteria;
add column headers; use friendly company names; show passed/total count
- ui/tab_overview.py: replace text architecture section with ASCII pipeline
diagram; use BIDDER_NAMES in demo loader
- ui/tab_audit.py: richer human-readable display with summary column,
category dots, metric cards, raw payload expander
- ui/tab_interpretability.py: new tab — plain-English per-criterion breakdown
with page-level source citations and inline PDF/image previews; LLM-powered
Q&A with rule-based fallback when API unavailable
- app.py: add Tab 6 (Interpretability); sidebar demo reset button that clears
audit DB + ChromaDB + OCR cache + session in one click; LLM probe cached
once per session

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

app.py

@@ -1,3 +1,5 @@
+import shutil
+
 import streamlit as st
 
 from ui.tab_overview import render as render_overview
@@ -5,6 +7,7 @@ from ui.tab_tender import render as render_tender
 from ui.tab_bidders import render as render_bidders
 from ui.tab_review import render as render_review
 from ui.tab_audit import render as render_audit
+from ui.tab_interpretability import render as render_interpretability
 
 st.set_page_config(
     page_title="TenderIQ",
@@ -14,7 +17,7 @@ st.set_page_config(
 
 
 def _probe_llm() -> str:
-    """Returns 'green', 'amber', or 'red'."""
+    """Probe once per session; returns 'green', 'amber', or 'red'."""
     if st.session_state.get("fallback_active"):
         return "amber"
     if "llm_status" in st.session_state:
@@ -32,6 +35,18 @@ def _probe_llm() -> str:
         return "red"
 
 
+def _reset_demo() -> None:
+    """Clear session, audit DB, ChromaDB, and OCR cache for a clean demo run."""
+    from core import audit
+    from core.config import CHROMA_DIR, OCR_CACHE_DIR
+    audit.clear()
+    shutil.rmtree(CHROMA_DIR, ignore_errors=True)
+    shutil.rmtree(str(OCR_CACHE_DIR), ignore_errors=True)
+    st.cache_resource.clear()
+    for key in list(st.session_state.keys()):
+        del st.session_state[key]
+
+
 # ── Sidebar ──────────────────────────────────────────────────────────────────
 with st.sidebar:
     st.markdown("## ⚖️ TenderIQ")
@@ -49,18 +64,33 @@ with st.sidebar:
         st.caption("Using pre-computed fallback data.")
 
     st.divider()
+
     if st.button("Reset Session", use_container_width=True):
         for key in list(st.session_state.keys()):
             del st.session_state[key]
         st.rerun()
 
+    if st.button("🗑 Reset for Demo", use_container_width=True, type="secondary"):
+        st.session_state["confirm_demo_reset"] = True
+
+    if st.session_state.get("confirm_demo_reset"):
+        st.warning("Clears audit log, vector index, OCR cache, and session. Sure?")
+        col1, col2 = st.columns(2)
+        if col1.button("Yes, reset", type="primary", use_container_width=True):
+            _reset_demo()
+            st.rerun()
+        if col2.button("Cancel", use_container_width=True):
+            st.session_state.pop("confirm_demo_reset", None)
+            st.rerun()
+
 # ── Tabs ─────────────────────────────────────────────────────────────────────
-tab1, tab2, tab3, tab4, tab5 = st.tabs([
+tab1, tab2, tab3, tab4, tab5, tab6 = st.tabs([
     "Overview",
     "Tender Analysis",
     "Bidder Evaluation",
     "Human Review",
     "Audit Log",
+    "Interpretability",
 ])
 
 with tab1:
@@ -77,3 +107,6 @@ with tab4:
 
 with tab5:
     render_audit()
+
+with tab6:
+    render_interpretability()

core/audit.py

@@ -47,6 +47,14 @@ def log(action: str, actor: str = "system", **fields) -> int:
     return row_id
 
 
+def clear() -> None:
+    conn = _conn()
+    conn.execute("DELETE FROM audit_log")
+    conn.execute("DELETE FROM sqlite_sequence WHERE name='audit_log'")
+    conn.commit()
+    conn.close()
+
+
 def query(filters: dict | None = None) -> list[dict]:
     conn = _conn()
     sql = "SELECT * FROM audit_log"

core/config.py

@@ -19,3 +19,9 @@ CHROMA_DIR = str(BASE_DIR / ".chroma")
 AUDIT_DB = str(BASE_DIR / "audit.db")
 PRECOMPUTED_DIR = DATA_DIR / "precomputed"
 OCR_CACHE_DIR = BASE_DIR / ".ocr_cache"
+
+BIDDER_NAMES = {
+    "bidder_a": "Apex Constructions Pvt. Ltd.",
+    "bidder_b": "BuildRight Enterprises",
+    "bidder_c": "Shree Constructions & Services",
+}

core/evaluator.py

@@ -60,7 +60,9 @@ def evaluate(bidder_id: str, criterion: Criterion) -> Verdict:
         )
         audit.log("criterion_evaluated", bidder_id=bidder_id,
                   criterion_id=criterion.id, verdict="needs_review",
-                  combined_confidence=0.0)
+                  llm_verdict="needs_review", extracted_value="",
+                  llm_confidence=0.0, combined_confidence=0.0,
+                  ocr_tier="", escalation_reason="no evidence found", reason=v.reason)
         return v
 
     evidence_dicts = [
@@ -148,9 +150,26 @@ Rules:
         timestamp=_now_iso(),
         review_status="pending",
     )
-    audit.log("criterion_evaluated", bidder_id=bidder_id,
-              criterion_id=criterion.id, verdict=final_verdict,
-              combined_confidence=round(combined, 4))
+    escalation_reason = None
+    if llm_verdict != final_verdict:
+        if combined < CONFIDENCE_REVIEW:
+            escalation_reason = f"auto-escalated: combined confidence {combined:.0%} below threshold"
+        elif combined < CONFIDENCE_HIGH and llm_verdict == "not_eligible":
+            escalation_reason = f"auto-escalated: borderline confidence {combined:.0%} on disqualification"
+
+    audit.log(
+        "criterion_evaluated",
+        bidder_id=bidder_id,
+        criterion_id=criterion.id,
+        verdict=final_verdict,
+        llm_verdict=llm_verdict,
+        extracted_value=extracted_value or "",
+        llm_confidence=round(llm_confidence, 4),
+        combined_confidence=round(combined, 4),
+        ocr_tier=source_type,
+        escalation_reason=escalation_reason or "",
+        reason=reason,
+    )
     return v
 
 

ui/tab_audit.py

@@ -1,14 +1,99 @@
 import io
+import json
 
 import pandas as pd
 import streamlit as st
 
 from core import audit
 
+_ACTION_LABELS = {
+    "criteria_extracted":       "📋 Criteria Extracted",
+    "bidder_processed":         "📥 Bidder Document Indexed",
+    "criterion_evaluated":      "⚖️ Criterion Evaluated",
+    "human_review_action":      "👤 Human Review Action",
+    "precomputed_fallback_used":"⚠️ Fallback Used",
+    "vision_ocr_invoked":       "👁️ Vision OCR Invoked",
+    "smoke_test":               "🧪 Smoke Test",
+}
+
+_ACTION_CATEGORIES = {
+    "criteria_extracted":        "system",
+    "bidder_processed":          "system",
+    "criterion_evaluated":       "system",
+    "human_review_action":       "human",
+    "precomputed_fallback_used": "warning",
+    "vision_ocr_invoked":        "system",
+}
+
+_VERDICT_ICONS = {
+    "eligible":     "✅ Eligible",
+    "not_eligible": "❌ Not Eligible",
+    "needs_review": "⚠️ Needs Review",
+}
+
+
+def _make_summary(row: dict) -> str:
+    action = row.get("action", "")
+    bidder = row.get("bidder_id") or ""
+    crit = row.get("criterion_id") or ""
+    try:
+        p = json.loads(row.get("payload_json") or "{}")
+    except Exception:
+        p = {}
+
+    if action == "criteria_extracted":
+        return f"Extracted {p.get('count', '?')} criteria from {p.get('source', 'tender PDF')}"
+
+    if action == "bidder_processed":
+        return f"{bidder} — {p.get('doc_name', '?')} indexed ({p.get('chunk_count', '?')} chunks)"
+
+    if action == "criterion_evaluated":
+        verdict = _VERDICT_ICONS.get(p.get("verdict", ""), p.get("verdict", "?"))
+        conf = p.get("combined_confidence", "?")
+        conf_str = f"{float(conf):.0%}" if conf != "?" else "?"
+        extracted = p.get("extracted_value", "")
+        esc = p.get("escalation_reason", "")
+        base = f"{bidder} / {crit} → {verdict} (confidence: {conf_str})"
+        if extracted:
+            base += f"  |  Extracted: {extracted}"
+        if esc:
+            base += f"  |  ⚠️ {esc}"
+        return base
+
+    if action == "human_review_action":
+        taken = p.get("action_taken", "?").capitalize()
+        orig = p.get("original_extracted_value", "")
+        edited = p.get("edited_value", "")
+        base = f"Officer {taken}: {bidder} / {crit}"
+        if orig:
+            base += f"  |  Original value: {orig}"
+        if edited:
+            base += f"  →  Edited to: {edited}"
+        return base
+
+    if action == "precomputed_fallback_used":
+        return f"API unavailable — pre-computed data used  |  {p.get('reason', '')}"
+
+    if action == "vision_ocr_invoked":
+        tc = p.get("tesseract_conf", "?")
+        tc_str = f"{float(tc):.0%}" if tc != "?" else "?"
+        return f"{bidder} page {p.get('page', '?')} — Tesseract confidence {tc_str}, escalated to Vision LLM"
+
+    return action
+
+
+def _category_color(category: str) -> str:
+    return {"system": "🔵", "human": "🟢", "warning": "🟡"}.get(category, "⚪")
+
 
 def render() -> None:
     st.header("Audit Log")
+    st.caption(
+        "Every system action and human decision is recorded here. "
+        "This log is the compliance trail — it can be exported and submitted as part of the evaluation record."
+    )
 
+    # ── Filters ──────────────────────────────────────────────────────────────
     col1, col2, col3 = st.columns(3)
     with col1:
         bidder_filter = st.selectbox(
@@ -18,11 +103,24 @@ def render() -> None:
     with col2:
         action_filter = st.selectbox(
             "Filter by action",
-            options=["All", "criteria_extracted", "bidder_processed", "criterion_evaluated",
-                     "human_review_action", "precomputed_fallback_used", "vision_ocr_invoked"],
+            options=["All"] + list(_ACTION_LABELS.keys()),
+            format_func=lambda x: "All" if x == "All" else _ACTION_LABELS.get(x, x),
         )
     with col3:
-        st.markdown(" ")  # spacer
+        if st.button("🗑 Clear Log", type="secondary", use_container_width=True):
+            st.session_state["confirm_clear_audit"] = True
+
+    if st.session_state.get("confirm_clear_audit"):
+        st.warning("This will permanently delete all audit entries. Are you sure?")
+        c1, c2 = st.columns(2)
+        if c1.button("Yes, clear everything", type="primary", use_container_width=True):
+            audit.clear()
+            st.session_state.pop("confirm_clear_audit", None)
+            st.success("Audit log cleared.")
+            st.rerun()
+        if c2.button("Cancel", use_container_width=True):
+            st.session_state.pop("confirm_clear_audit", None)
+            st.rerun()
 
     filters: dict = {}
     if bidder_filter != "All":
@@ -36,17 +134,61 @@ def render() -> None:
         st.info("No audit entries yet. Run an evaluation to generate entries.")
         return
 
+    # ── Summary counts ────────────────────────────────────────────────────────
+    total = len(rows)
+    human_actions = sum(1 for r in rows if r["action"] == "human_review_action")
+    fallbacks = sum(1 for r in rows if r["action"] == "precomputed_fallback_used")
+    vision_ocr = sum(1 for r in rows if r["action"] == "vision_ocr_invoked")
+
+    m1, m2, m3, m4 = st.columns(4)
+    m1.metric("Total entries", total)
+    m2.metric("Human actions", human_actions)
+    m3.metric("Fallback events", fallbacks)
+    m4.metric("Vision OCR calls", vision_ocr)
+
+    st.divider()
+
+    # ── Human-readable table ──────────────────────────────────────────────────
     df = pd.DataFrame(rows)
-    display_cols = ["id", "ts", "action", "actor", "bidder_id", "criterion_id", "payload_json"]
-    display_cols = [c for c in display_cols if c in df.columns]
-    df_display = df[display_cols].copy()
-    df_display["ts"] = df_display["ts"].str[:19].str.replace("T", " ")
 
-    st.markdown(f"**{len(rows)} entries** (newest first)")
-    st.dataframe(df_display, use_container_width=True, hide_index=True)
+    df["Action"] = df["action"].map(lambda x: _ACTION_LABELS.get(x, x))
+    df["Category"] = df["action"].map(
+        lambda x: _category_color(_ACTION_CATEGORIES.get(x, "system"))
+    )
+    df["Summary"] = df.apply(_make_summary, axis=1)
+    df["Timestamp"] = df["ts"].str[:19].str.replace("T", " ")
+    df["Actor"] = df["actor"]
+    df["Bidder"] = df["bidder_id"].fillna("—")
+    df["Criterion"] = df["criterion_id"].fillna("—")
+
+    display = df[["Category", "Timestamp", "Action", "Bidder", "Criterion", "Summary", "Actor"]].copy()
+
+    st.dataframe(
+        display,
+        use_container_width=True,
+        hide_index=True,
+        column_config={
+            "Category":  st.column_config.TextColumn("", width="small"),
+            "Timestamp": st.column_config.TextColumn("Timestamp", width="medium"),
+            "Action":    st.column_config.TextColumn("Action", width="medium"),
+            "Bidder":    st.column_config.TextColumn("Bidder", width="small"),
+            "Criterion": st.column_config.TextColumn("Criterion", width="small"),
+            "Summary":   st.column_config.TextColumn("Summary", width="large"),
+            "Actor":     st.column_config.TextColumn("Actor", width="small"),
+        },
+    )
+
+    # ── Raw detail expander ───────────────────────────────────────────────────
+    with st.expander("Raw payload data (for compliance / full detail)", expanded=False):
+        raw_df = df[["Timestamp", "action", "actor", "bidder_id", "criterion_id", "payload_json"]].copy()
+        raw_df.columns = ["Timestamp", "action", "actor", "bidder_id", "criterion_id", "payload_json"]
+        st.dataframe(raw_df, use_container_width=True, hide_index=True)
 
+    # ── Export ────────────────────────────────────────────────────────────────
+    export_df = df[["Timestamp", "Action", "Actor", "Bidder", "Criterion", "Summary"]].copy()
+    export_df["raw_payload"] = df["payload_json"]
     csv_buf = io.StringIO()
-    df_display.to_csv(csv_buf, index=False)
+    export_df.to_csv(csv_buf, index=False)
     st.download_button(
         label="Export CSV",
         data=csv_buf.getvalue().encode("utf-8"),

ui/tab_bidders.py

@@ -1,17 +1,15 @@
-from pathlib import Path
-
 import streamlit as st
 
 from core import bidder_processor, evaluator
-from core.config import DATA_DIR
+from core.config import BIDDER_NAMES, DATA_DIR
 from core.fallback import load_criteria
 from core.schemas import Criterion
 from ui.components import category_badge, confidence_bar, ocr_tier_badge, verdict_pill
 
 _BIDDER_LABELS = {
-    "bidder_a": "Bidder A — Apex Constructions (Clearly Eligible)",
+    "bidder_a": "Bidder A — Apex Constructions Pvt. Ltd. (Clearly Eligible)",
     "bidder_b": "Bidder B — BuildRight Enterprises (Ineligible: Low Turnover)",
-    "bidder_c": "Bidder C — Shree Constructions (Scanned Cert: Needs Review)",
+    "bidder_c": "Bidder C — Shree Constructions & Services (Scanned Cert: Needs Review)",
 }
 
 
@@ -22,8 +20,12 @@ def _get_criteria() -> list[Criterion]:
     return load_criteria()
 
 
-def _overall_verdict(verdicts: list[dict]) -> str:
-    mandatory = [v for v in verdicts if True]  # all criteria checked
+def _overall_verdict(verdicts: list[dict], crit_map: dict) -> str:
+    """Only mandatory criteria determine overall eligibility."""
+    mandatory = [v for v in verdicts if crit_map.get(v["criterion_id"], None) and
+                 crit_map[v["criterion_id"]].mandatory]
+    if not mandatory:
+        mandatory = verdicts  # fallback if crit_map is missing
     if any(v["verdict"] == "not_eligible" for v in mandatory):
         return "not_eligible"
     if any(v["verdict"] == "needs_review" for v in mandatory):
@@ -52,14 +54,15 @@ def render() -> None:
                 f for f in (DATA_DIR / "bidders" / bidder_id).iterdir()
                 if f.suffix.lower() in {".pdf", ".png", ".jpg"}
             )
-            with st.spinner(f"Processing {bidder_id} documents…"):
+            with st.spinner(f"Processing {BIDDER_NAMES.get(bidder_id, bidder_id)} documents…"):
                 bidder_processor.process_bidder(bidder_id, files)
             verdicts_list = []
             for c in criteria:
                 v = evaluator.evaluate(bidder_id, c)
                 verdicts_list.append(v.model_dump())
                 done += 1
-                progress.progress(done / total, text=f"Evaluated {c.id} for {bidder_id}")
+                progress.progress(done / total,
+                                  text=f"Evaluated {c.id} for {BIDDER_NAMES.get(bidder_id, bidder_id)}")
             verdicts_dict[bidder_id] = verdicts_list
         st.session_state["verdicts"] = verdicts_dict
         progress.empty()
@@ -77,13 +80,34 @@ def render() -> None:
         if bidder_id not in verdicts_data:
             continue
         verdicts = verdicts_data[bidder_id]
-        overall = _overall_verdict(verdicts)
+        overall = _overall_verdict(verdicts, crit_map)
         overall_pill = verdict_pill(overall)
+        friendly = BIDDER_NAMES.get(bidder_id, bidder_id)
+        mandatory_count = sum(1 for v in verdicts
+                              if crit_map.get(v["criterion_id"]) and
+                              crit_map[v["criterion_id"]].mandatory)
+        passed = sum(1 for v in verdicts
+                     if v["verdict"] == "eligible" and
+                     crit_map.get(v["criterion_id"]) and
+                     crit_map[v["criterion_id"]].mandatory)
+
+        with st.container(border=True):
+            st.markdown(
+                f"#### {friendly}  —  Overall: {overall_pill}"
+                f"  <span style='font-size:0.85em; color:grey;'>"
+                f"({passed}/{mandatory_count} mandatory criteria met)</span>",
+                unsafe_allow_html=True,
+            )
+
+            # Column headers
+            hcols = st.columns([3, 2, 2, 2, 1])
+            hcols[0].caption("Criterion")
+            hcols[1].caption("Verdict")
+            hcols[2].caption("Extracted Value")
+            hcols[3].caption("Source / OCR Tier")
+            hcols[4].caption("Category")
+            st.divider()
 
-        with st.expander(
-            f"**{_BIDDER_LABELS.get(bidder_id, bidder_id)}**  —  Overall: {overall_pill}",
-            expanded=True,
-        ):
             for v in verdicts:
                 crit = crit_map.get(v["criterion_id"])
                 crit_title = crit.title if crit else v["criterion_id"]
@@ -105,7 +129,7 @@ def render() -> None:
                 conf = v.get("combined_confidence", 0.0)
                 confidence_bar(conf)
 
-                if v.get("reason") or v.get("source"):
+                if v.get("reason") or (v.get("source") and v["source"].get("snippet")):
                     with st.expander("Details", expanded=False):
                         if v.get("reason"):
                             st.markdown(f"**Reason:** {v['reason']}")

ui/tab_interpretability.py

@@ -0,0 +1,311 @@
+import json
+
+import streamlit as st
+
+from core.config import BIDDER_NAMES, DATA_DIR, MODEL_VERSION
+from core.fallback import load_criteria
+from core.llm_client import LLM, LLMUnavailable
+from core.pdf_utils import render_page_to_image
+from core.schemas import Criterion
+
+_VERDICT_PLAIN = {
+    "eligible":     ("✅", "PASSED",       "green"),
+    "not_eligible": ("❌", "FAILED",       "red"),
+    "needs_review": ("⚠️", "NEEDS REVIEW", "orange"),
+}
+
+_CRITERION_RULE_PLAIN = {
+    "numeric_threshold": lambda r: (
+        f"must be ≥ {r['value']:,} {r.get('unit') or ''}" if r["operator"] == ">="
+        else f"must be ≤ {r['value']:,} {r.get('unit') or ''}"
+    ),
+    "count_threshold": lambda r: f"must have completed at least {int(r['value'])}",
+    "certification_present": lambda _: "valid certificate must be present",
+    "document_present": lambda _: "supporting document must be present",
+}
+
+
+def _get_criteria() -> list[Criterion]:
+    data = st.session_state.get("criteria")
+    if data:
+        return [Criterion(**c) for c in data]
+    return load_criteria()
+
+
+def _plain_explanation(v: dict, crit: Criterion | None) -> str:
+    verdict = v.get("verdict", "")
+    extracted = v.get("extracted_value") or ""
+    reason = v.get("reason") or ""
+    src = v.get("source") or {}
+
+    if not crit:
+        return reason
+
+    icon, label, _ = _VERDICT_PLAIN.get(verdict, ("❓", verdict, "grey"))
+    rule = crit.rule
+
+    if verdict == "eligible":
+        rule_desc = _CRITERION_RULE_PLAIN.get(rule.type, lambda _: "")(rule.model_dump())
+        val_part = f" Found: **{extracted}**." if extracted else ""
+        return f"{icon} **{crit.title}** — {label}.{val_part} {reason}"
+
+    elif verdict == "not_eligible":
+        rule_desc = _CRITERION_RULE_PLAIN.get(rule.type, lambda _: "")(rule.model_dump())
+        val_part = f" Found: **{extracted}** — this does not meet the requirement ({rule_desc})." if extracted else f" Required: {rule_desc}."
+        return f"{icon} **{crit.title}** — {label}.{val_part} {reason}"
+
+    else:  # needs_review
+        val_part = f" Extracted value: **{extracted}**." if extracted else ""
+        return f"{icon} **{crit.title}** — {label}.{val_part} {reason}"
+
+
+def _source_citation(v: dict) -> str | None:
+    src = v.get("source")
+    if not src:
+        return None
+    doc = src.get("doc_name", "")
+    page = src.get("page", "")
+    tier = src.get("source_type", "")
+    tier_labels = {"text_pdf": "typed PDF", "tesseract": "Tesseract OCR",
+                   "vision_llm": "Vision LLM OCR"}
+    return f"📄 **{doc}**, page {page}  ·  read by _{tier_labels.get(tier, tier)}_"
+
+
+def _build_qa_context(bidder_id: str, verdicts: list[dict],
+                       criteria: list[Criterion]) -> str:
+    crit_map = {c.id: c for c in criteria}
+    lines = [
+        f"BIDDER: {BIDDER_NAMES.get(bidder_id, bidder_id)} ({bidder_id})",
+        "",
+        "EVALUATION RESULTS:",
+    ]
+    for v in verdicts:
+        crit = crit_map.get(v["criterion_id"])
+        crit_title = crit.title if crit else v["criterion_id"]
+        mandatory = ("Mandatory" if crit and crit.mandatory else "Optional") if crit else "Unknown"
+        lines.append(
+            f"  {v['criterion_id']} — {crit_title} [{mandatory}]: "
+            f"{v['verdict'].upper()}"
+        )
+        if v.get("extracted_value"):
+            lines.append(f"    Extracted value: {v['extracted_value']}")
+        if v.get("source"):
+            src = v["source"]
+            lines.append(
+                f"    Evidence source: {src.get('doc_name')} page {src.get('page')} "
+                f"(read by {src.get('source_type')})"
+            )
+        if v.get("source") and v["source"].get("snippet"):
+            lines.append(f"    Evidence snippet: \"{v['source']['snippet'][:200]}\"")
+        lines.append(
+            f"    Confidence: {v.get('combined_confidence', 0):.0%}  |  "
+            f"Reason: {v.get('reason', '')}"
+        )
+        if crit:
+            rule = crit.rule
+            rule_desc = _CRITERION_RULE_PLAIN.get(rule.type, lambda _: "")(rule.model_dump())
+            lines.append(f"    Requirement: {rule_desc}")
+        lines.append("")
+    return "\n".join(lines)
+
+
+def _answer_question(question: str, context: str) -> str:
+    system = """You are a procurement compliance assistant helping an evaluation officer
+understand AI-generated eligibility verdicts. Answer questions about the bidder's evaluation
+in plain, professional English. Always cite specific document names and page numbers from the
+evidence. Be concise (2-4 sentences). Do not invent information not present in the context."""
+
+    user = f"""{context}
+
+OFFICER'S QUESTION: {question}
+
+Answer the question based only on the evaluation results above.
+Cite the specific document and page number when referring to evidence."""
+
+    try:
+        llm = LLM()
+        result = llm.chat_json(
+            system + " Return JSON: {\"answer\": \"<your answer>\"}",
+            user,
+        )
+        return result.get("answer", "")
+    except LLMUnavailable:
+        return _rule_based_answer(question, context)
+
+
+def _rule_based_answer(question: str, context: str) -> str:
+    q = question.lower()
+    lines = context.splitlines()
+
+    if any(w in q for w in ["reject", "fail", "not eligible", "disqualif"]):
+        fails = [l for l in lines if "NOT_ELIGIBLE" in l or "NEEDS_REVIEW" in l]
+        if fails:
+            return ("Based on the evaluation: " +
+                    "; ".join(f.strip() for f in fails[:3]) +
+                    ". See the Bidder Evaluation tab for full details.")
+        return "No failing criteria were found in the evaluation."
+
+    if any(w in q for w in ["pass", "eligible", "meet", "satisfy"]):
+        passes = [l for l in lines if "ELIGIBLE" in l and "NOT_ELIGIBLE" not in l]
+        if passes:
+            return ("Criteria passed: " +
+                    "; ".join(f.strip() for f in passes[:3]) + ".")
+        return "No passing criteria were found."
+
+    if any(w in q for w in ["turnover", "financial", "revenue", "c1"]):
+        relevant = [l for l in lines if "C1" in l or "turnover" in l.lower() or
+                    "Extracted value" in l]
+        if relevant:
+            return " ".join(l.strip() for l in relevant[:4])
+
+    return ("I cannot answer that specific question without the live LLM. "
+            "The evaluation summary above contains the full details.")
+
+
+def render() -> None:
+    st.header("Interpretability")
+    st.caption(
+        "Plain-English explanations of why each bidder was evaluated the way it was, "
+        "with full source citations. Ask any question about the evaluation."
+    )
+
+    verdicts_data = st.session_state.get("verdicts", {})
+    if not verdicts_data:
+        st.info("No evaluation results yet. Run the evaluation in Bidder Evaluation tab or "
+                "click **Load Pre-computed Demo** in the Overview tab.")
+        return
+
+    criteria = _get_criteria()
+    crit_map = {c.id: c for c in criteria}
+
+    bidder_id = st.selectbox(
+        "Select bidder",
+        options=list(verdicts_data.keys()),
+        format_func=lambda x: BIDDER_NAMES.get(x, x),
+    )
+
+    verdicts = verdicts_data.get(bidder_id, [])
+    if not verdicts:
+        st.warning("No verdicts available for this bidder.")
+        return
+
+    # ── Overall summary ───────────────────────────────────────────────────────
+    mandatory_verdicts = [v for v in verdicts
+                          if crit_map.get(v["criterion_id"]) and
+                          crit_map[v["criterion_id"]].mandatory]
+    failed = [v for v in mandatory_verdicts if v["verdict"] == "not_eligible"]
+    review = [v for v in mandatory_verdicts if v["verdict"] == "needs_review"]
+    passed = [v for v in mandatory_verdicts if v["verdict"] == "eligible"]
+
+    friendly = BIDDER_NAMES.get(bidder_id, bidder_id)
+
+    if failed:
+        st.error(
+            f"**{friendly} — NOT ELIGIBLE**\n\n"
+            f"Failed {len(failed)} mandatory criterion/criteria. "
+            f"A bidder must meet all mandatory criteria to qualify."
+        )
+    elif review:
+        st.warning(
+            f"**{friendly} — NEEDS REVIEW**\n\n"
+            f"Passed {len(passed)} mandatory criteria, but {len(review)} could not be "
+            f"automatically confirmed and require officer verification."
+        )
+    else:
+        st.success(
+            f"**{friendly} — ELIGIBLE**\n\n"
+            f"All {len(passed)} mandatory criteria satisfied."
+        )
+
+    st.divider()
+
+    # ── Per-criterion plain-English cards ─────────────────────────────────────
+    st.subheader("Criterion-by-Criterion Breakdown")
+
+    for v in verdicts:
+        crit = crit_map.get(v["criterion_id"])
+        _, label, color = _VERDICT_PLAIN.get(v["verdict"], ("❓", v["verdict"], "grey"))
+        mandatory_tag = "🔴 Mandatory" if (crit and crit.mandatory) else "🟡 Optional"
+
+        with st.container(border=True):
+            col_status, col_detail = st.columns([1, 4])
+
+            with col_status:
+                if color == "green":
+                    st.success(label)
+                elif color == "red":
+                    st.error(label)
+                else:
+                    st.warning(label)
+                st.caption(mandatory_tag)
+                conf = v.get("combined_confidence", 0.0)
+                st.caption(f"Confidence: {conf:.0%}")
+
+            with col_detail:
+                explanation = _plain_explanation(v, crit)
+                st.markdown(explanation)
+
+                citation = _source_citation(v)
+                if citation:
+                    st.markdown(citation)
+
+                    # Page preview
+                    src = v.get("source", {})
+                    doc_name = src.get("doc_name", "")
+                    page_no = src.get("page", 1)
+                    bidder_dir = DATA_DIR / "bidders" / bidder_id
+                    doc_path = bidder_dir / doc_name
+
+                    if doc_path.exists() and doc_path.suffix.lower() == ".pdf":
+                        with st.expander(f"View source page ({doc_name}, p{page_no})",
+                                         expanded=False):
+                            try:
+                                img = render_page_to_image(doc_path, page_no)
+                                st.image(img, caption=f"{doc_name} — Page {page_no}",
+                                         use_container_width=True)
+                            except Exception:
+                                st.caption("Page preview unavailable.")
+                    elif doc_path.exists() and doc_path.suffix.lower() in {".png", ".jpg"}:
+                        with st.expander(f"View source image ({doc_name})", expanded=False):
+                            st.image(str(doc_path), caption=doc_name,
+                                     use_container_width=True)
+
+    st.divider()
+
+    # ── Q&A section ───────────────────────────────────────────────────────────
+    st.subheader("Ask About This Evaluation")
+    st.caption(
+        "Ask any question about why this bidder was evaluated the way it was. "
+        "Answers cite specific documents and pages."
+    )
+
+    suggestions = [
+        "Why was this bidder rejected?",
+        "Which criteria did this bidder fail?",
+        "What turnover figure was found and which document was it from?",
+        "Is this bidder ISO certified?",
+        "Why is the turnover verdict in review?",
+    ]
+    with st.expander("Example questions", expanded=False):
+        for s in suggestions:
+            st.markdown(f"- _{s}_")
+
+    question = st.text_input(
+        "Your question",
+        placeholder="e.g. Why was this bidder's turnover flagged for review?",
+        key=f"qa_input_{bidder_id}",
+    )
+
+    if st.button("Get Answer", type="primary", key=f"qa_btn_{bidder_id}"):
+        if not question.strip():
+            st.warning("Please enter a question.")
+        else:
+            context = _build_qa_context(bidder_id, verdicts, criteria)
+            with st.spinner("Looking up the answer…"):
+                answer = _answer_question(question, context)
+
+            st.markdown("**Answer:**")
+            st.info(answer)
+
+            with st.expander("Full evaluation context used to answer", expanded=False):
+                st.code(context, language="text")

ui/tab_overview.py

@@ -1,6 +1,7 @@
 import streamlit as st
 
 from core import audit
+from core.config import BIDDER_NAMES
 from core.fallback import load_criteria
 
 
@@ -30,23 +31,94 @@ def render() -> None:
 
     st.divider()
 
-    st.subheader("How it works")
+    # Architecture diagram
+    st.subheader("System Architecture")
+    st.markdown("""
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                        TenderIQ Pipeline                            │
+└─────────────────────────────────────────────────────────────────────┘
+
+  📄 Tender PDF                      📁 Bidder Documents
+       │                              (PDFs, scans, photos)
+       │                                      │
+       ▼                                      ▼
+ ┌───────────┐                    ┌────────────────────────┐
+ │  DeepSeek │                    │   3-Tier OCR Pipeline  │
+ │    LLM    │                    │  ① PyMuPDF  (typed)   │
+ │ (Stage 1) │                    │  ② Tesseract (scans)  │
+ └───────────┘                    │  ③ Vision LLM (poor)  │
+       │                          └────────────────────────┘
+       │                                      │
+       ▼                                      ▼
+ ┌───────────┐                    ┌────────────────────────┐
+ │ Criteria  │                    │   ChromaDB Vector      │
+ │  C1 – C5  │                    │   Index (per bidder)   │
+ │ (JSON)    │                    └────────────────────────┘
+ └───────────┘                                │
+       │                                      │  semantic search
+       └──────────────────┬───────────────────┘
+                          │
+                          ▼
+               ┌─────────────────────┐
+               │   DeepSeek LLM      │
+               │   (Stage 3 eval)    │
+               │                     │
+               │  evidence → verdict │
+               │  + confidence score │
+               └─────────────────────┘
+                          │
+            ┌─────────────┴──────────────┐
+            │                            │
+            ▼                            ▼
+   confidence ≥ 0.80            confidence < 0.80
+   verdict kept                 downgraded to
+                                needs_review
+                                      │
+                                      ▼
+                             ┌─────────────────┐
+                             │  Human Review   │
+                             │  Queue (Tab 4)  │
+                             └─────────────────┘
+                                      │
+                                      ▼
+                             ┌─────────────────┐
+                             │   Audit Log     │
+                             │  (every action) │
+                             └─────────────────┘
+```
+""")
+
+    st.divider()
+
+    st.subheader("Pipeline Stages")
     col_a, col_b = st.columns(2)
     with col_a:
         st.markdown("""
-**Stage 1 — Extract Criteria**
-DeepSeek LLM reads the tender PDF and extracts each eligibility criterion as structured JSON (category, rule, query hints).
+**① Extract Criteria**
+DeepSeek reads the full tender PDF and extracts each eligibility criterion as structured JSON —
+category, mandatory flag, rule (threshold / certification / count), source clause, and query hints
+for downstream retrieval.
 
-**Stage 2 — OCR & Index Bidder Docs**
-Three-tier OCR: PyMuPDF (typed PDF) → Tesseract → DeepSeek Vision LLM (low-confidence scans). All pages indexed into ChromaDB.
+**② OCR & Index Bidder Documents**
+Three-tier pipeline handles any document format:
+PyMuPDF for typed PDFs (instant, lossless) →
+Tesseract for scans (free, fast) →
+DeepSeek Vision LLM when Tesseract confidence < 65%.
+All text is chunked and indexed into ChromaDB with full provenance metadata.
 """)
     with col_b:
         st.markdown("""
-**Stage 3 — Evaluate per Criterion**
-Vector search retrieves relevant evidence chunks. DeepSeek evaluates eligible / not_eligible / needs_review with a combined confidence score.
+**③ Evaluate per Criterion**
+For each (bidder × criterion) pair: semantic search retrieves the most relevant evidence chunks,
+DeepSeek decides eligible / not_eligible / needs_review with a combined confidence score
+that weights LLM certainty against OCR quality.
+The safety rule: never silently disqualify — borderline cases always go to human review.
 
-**Stage 4 — Human Review & Audit**
-Low-confidence verdicts are routed to the review queue. Every action is logged with timestamp, model version, and payload.
+**④ Human Review & Audit**
+Flagged verdicts surface in the Review Queue with full evidence and source citations.
+Every action — extraction, indexing, evaluation, review — is logged to SQLite with
+timestamp, model version, actor, and payload.
 """)
 
     st.divider()
@@ -59,13 +131,13 @@ Low-confidence verdicts are routed to the review queue. Every action is logged w
             criteria = lc()
             st.session_state["criteria"] = [c.model_dump() for c in criteria]
             verdicts_dict: dict = {}
-            for bidder_id in ["bidder_a", "bidder_b", "bidder_c"]:
+            for bidder_id in BIDDER_NAMES:
                 verdicts_dict[bidder_id] = [
                     load_evaluation(bidder_id, c.id).model_dump()
                     for c in criteria
                 ]
             st.session_state["verdicts"] = verdicts_dict
-            st.success("Pre-computed demo data loaded. Navigate to the other tabs.")
+            st.success("Pre-computed demo loaded. Navigate to the other tabs.")
             st.rerun()
     with col2:
-        st.info("Or go to **Tender Analysis** tab to run the live LLM pipeline.")
+        st.info("Or go to **Tender Analysis** to run the live LLM pipeline.")

ui/tab_review.py

@@ -33,6 +33,11 @@ def render() -> None:
         return
 
     st.markdown(f"**{len(pending_items)} item(s) pending review**")
+    st.caption(
+        "These verdicts require human confirmation before being finalised. "
+        "The certainty bar shows how confident the model is in its decision to flag the item — "
+        "not how likely the bidder meets the criterion."
+    )
     st.divider()
 
     for bidder_id, idx, v in pending_items:
@@ -52,7 +57,7 @@ def render() -> None:
                     st.markdown(f"Source snippet: _{v['source']['snippet']}_")
             with col2:
                 conf = v.get("combined_confidence", 0.0)
-                confidence_bar(conf, "Confidence")
+                confidence_bar(conf, "Certainty in assessment")
 
             btn_col1, btn_col2, btn_col3 = st.columns(3)
             key_prefix = f"review_{bidder_id}_{v['criterion_id']}"
@@ -66,6 +71,9 @@ def render() -> None:
                         bidder_id=bidder_id,
                         criterion_id=v["criterion_id"],
                         action_taken="approved",
+                        original_verdict=v["verdict"],
+                        original_extracted_value=v.get("extracted_value", ""),
+                        combined_confidence=v.get("combined_confidence", 0.0),
                     )
                     st.rerun()
 
@@ -82,7 +90,10 @@ def render() -> None:
                         bidder_id=bidder_id,
                         criterion_id=v["criterion_id"],
                         action_taken="edited",
+                        original_verdict=v["verdict"],
+                        original_extracted_value=v.get("extracted_value", ""),
                         edited_value=edit_val,
+                        combined_confidence=v.get("combined_confidence", 0.0),
                     )
                     st.rerun()
 
@@ -95,5 +106,8 @@ def render() -> None:
                         bidder_id=bidder_id,
                         criterion_id=v["criterion_id"],
                         action_taken="rejected",
+                        original_verdict=v["verdict"],
+                        original_extracted_value=v.get("extracted_value", ""),
+                        combined_confidence=v.get("combined_confidence", 0.0),
                     )
                     st.rerun()