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

backend/faithfulness.py

@@ -55,7 +55,7 @@ HALLUCINATION_LOG = LOG_DIR / "hallucinations.jsonl"
 # higher here than they would be for Voyage. Re-tune if changing embedding model.
 # Lowered 2026-05-13 based on eval data showing too-aggressive refusal at 0.40:
 # many real questions retrieve top chunks at 0.30-0.38 that DO contain the answer.
-MIN_TOP_SCORE = 0.30  # below this we refuse outright (BGE-small cosine similarity)
+MIN_TOP_SCORE = 0.18  # below this we refuse outright (BGE-small cosine similarity)
 MIN_AVG_SCORE = 0.22  # average of top 5 must be above this
 
 

backend/main.py

@@ -516,6 +516,36 @@ class MarketplaceResponse(BaseModel):
     insurers_indexed: int
 
 
+@app.get("/api/scorecard/methodology")
+async def scorecard_methodology():
+    """Transparency endpoint — returns the 6-criterion blueprint with weights,
+    consumer rationale, fields driving each sub-score, and regulatory anchors.
+
+    Frontend renders this inside PolicyDetailModal so the user can see exactly
+    how the headline number is computed and which of the 48 HealthPolicy fields
+    feed into which criterion.
+    """
+    from backend.scorecard import METHODOLOGY_BLUEPRINT, WEIGHTS, SCORED_FIELDS
+    return {
+        "weights": WEIGHTS,
+        "scored_fields_count": len(SCORED_FIELDS),
+        "total_schema_fields": 48,
+        "criteria": METHODOLOGY_BLUEPRINT,
+        "grade_thresholds": {
+            "A": "≥85 — strong all-rounder",
+            "B": "70–84 — good with a few gaps",
+            "C": "55–69 — check trade-offs",
+            "D": "40–54 — material concerns",
+            "F": "<40 — significant gaps",
+        },
+        "scoring_approach": (
+            "Rules-based (deterministic), no LLM-in-the-loop. Each criterion produces a "
+            "0–100 sub-score from concrete schema fields; the overall score is the weighted "
+            "average. Weights adapt to user profile when age/parents/budget are known."
+        ),
+    }
+
+
 def _build_corpus_url_index() -> dict[str, str]:
     """Parse data/corpus_urls.md and return {policy_id: source_url}. Used to
     backfill source_pdf_url when the LLM extraction didn't capture it."""

backend/scorecard.py

@@ -281,6 +281,146 @@ WEIGHTS = {
 }
 
 
+# ----------------------------------------------------------------------------
+# METHODOLOGY BLUEPRINT — the buyer-facing transparency layer
+# ----------------------------------------------------------------------------
+# Maps each of the 6 sub-scores to:
+#   - the consumer rationale (why this matters in plain English)
+#   - the concrete policy fields that drive its score (subset of the 48-field
+#     HealthPolicy schema)
+#   - the regulatory / industry anchors that justify the weight
+# Used by /api/scorecard/methodology to render a customer-centric explanation
+# of how the headline number is computed.
+METHODOLOGY_BLUEPRINT = [
+    {
+        "name": "Coverage Breadth",
+        "weight_pct": 22,
+        "consumer_question": "When I actually need to claim, what's covered vs what's not?",
+        "why_it_matters": (
+            "Determines whether your hospital bill is fully reimbursed or whether you pay "
+            "out-of-pocket for gaps like AYUSH, maternity, newborn care, or ambulance."
+        ),
+        "fields_driving_score": [
+            {"field": "ayush_coverage", "rule": "AYUSH covered → +8"},
+            {"field": "day_care_treatments_count", "rule": "≥400 procedures → +10, ≥200 → +6, <100 → −5"},
+            {"field": "maternity_coverage", "rule": "Covered → +6"},
+            {"field": "newborn_coverage", "rule": "Covered → +4"},
+            {"field": "organ_donor_expenses", "rule": "Covered → +4"},
+            {"field": "ambulance_cover", "rule": "Covered → +3"},
+            {"field": "domiciliary_treatment", "rule": "Covered → +4"},
+            {"field": "preventive_health_checkup", "rule": "Free → +3"},
+            {"field": "pre_hospitalization_days", "rule": "≥60 days → +4"},
+            {"field": "post_hospitalization_days", "rule": "≥90 days → +4"},
+        ],
+        "anchors": [
+            "IRDAI Health Insurance Master Circular 2024 — emphasises comprehensive cover",
+            "Acko buying guide: coverage breadth most-cited buyer concern",
+        ],
+    },
+    {
+        "name": "Cost Predictability",
+        "weight_pct": 20,
+        "consumer_question": "Will I face surprise bills I can't plan for?",
+        "why_it_matters": (
+            "Co-pay forces you to pay a % of every claim; room-rent capping reduces what gets "
+            "reimbursed; sub-limits cap specific treatments below your sum insured. These "
+            "convert a known sum-insured into an unpredictable out-of-pocket exposure."
+        ),
+        "fields_driving_score": [
+            {"field": "copayment_pct", "rule": "0% → +0, 10% → −5, 20%+ → −12"},
+            {"field": "room_rent_capping", "rule": "No limit → +6, capped → −5 to −10"},
+            {"field": "deductible_amount", "rule": "₹0 → +0, ≥₹1L → −8"},
+            {"field": "sub_limits", "rule": "No condition-specific caps → +5"},
+            {"field": "icu_charges_capping", "rule": "No cap → +3"},
+        ],
+        "anchors": [
+            "IRDAI Master Circular — disclosure norms on co-pay/sub-limits",
+            "Common consumer complaint themes (IRDAI complaint logs)",
+        ],
+    },
+    {
+        "name": "Waiting-Period Friction",
+        "weight_pct": 18,
+        "consumer_question": "How soon can I actually use this policy if something happens?",
+        "why_it_matters": (
+            "Initial waiting period (30 days typical), pre-existing-disease waiting "
+            "(commonly 24–48 months), and maternity waits delay claims. Shorter is better — "
+            "especially for older buyers or those with diabetes/hypertension."
+        ),
+        "fields_driving_score": [
+            {"field": "initial_waiting_period_days", "rule": "≤30 days → 0, >30 days → −3"},
+            {"field": "pre_existing_disease_waiting_months", "rule": "≤24mo → +10, 36mo → 0, ≥48mo → −15"},
+            {"field": "maternity_waiting_months", "rule": "≤24mo → +5, ≥36mo → −5"},
+            {"field": "specific_disease_waiting_months", "rule": "≤24mo → +3"},
+        ],
+        "anchors": [
+            "IRDAI standard product specifications (Arogya Sanjeevani UIN guideline: 36-month PED max)",
+            "PolicyBazaar comparison data: 24-month PED is the buyer benchmark",
+        ],
+    },
+    {
+        "name": "Claim Experience",
+        "weight_pct": 20,
+        "consumer_question": "Will the insurer actually pay when I claim?",
+        "why_it_matters": (
+            "Coverage on paper means nothing if claims get denied or take weeks. We measure "
+            "cashless network reach, IRDAI's published Claim Settlement Ratio (CSR), the "
+            "complaint count per 10,000 policies, and how fast cashless pre-auth happens."
+        ),
+        "fields_driving_score": [
+            {"field": "cashless_treatment_supported", "rule": "Yes → +5"},
+            {"field": "network_hospital_count", "rule": "≥10,000 → +10, ≥5,000 → +5, <2,000 → −5"},
+            {"field": "claim_settlement_ratio (IRDAI)", "rule": "≥95% → +12, 90–95 → +6, <85% → −10"},
+            {"field": "complaints_per_10k_policies (IRDAI)", "rule": "<5 → +4, >20 → −8"},
+            {"field": "tat_cashless_authorization_hours", "rule": "≤2h → +4, ≥24h → −4"},
+        ],
+        "anchors": [
+            "IRDAI Annual Report 2023-24 — published CSR per insurer",
+            "IRDAI Grievance Redressal handbook — complaints/10K is the regulator's own metric",
+        ],
+    },
+    {
+        "name": "Renewal Protection",
+        "weight_pct": 12,
+        "consumer_question": "Can I keep this policy when I'm 70 and need it most?",
+        "why_it_matters": (
+            "Health insurance only works if you can keep renewing. Lifelong renewability is "
+            "the IRDAI default since 2020, but entry-age caps and porting friction still "
+            "matter. Buyers who don't check this often lose cover when claims rise."
+        ),
+        "fields_driving_score": [
+            {"field": "max_renewal_age", "rule": "Lifelong → +12, 80 → +6, ≤70 → −5"},
+            {"field": "max_entry_age", "rule": "≥65 → +4 (more buyers eligible)"},
+            {"field": "guaranteed_renewability", "rule": "Stated explicitly → +4"},
+        ],
+        "anchors": [
+            "IRDAI Master Circular 2024 — lifelong renewability mandate",
+            "IRDAI Portability Regulations 2020",
+        ],
+    },
+    {
+        "name": "Bonus & Loyalty",
+        "weight_pct": 8,
+        "consumer_question": "What do I get for staying claim-free and renewing year after year?",
+        "why_it_matters": (
+            "Claim-free years should compound value: most policies give 20–50% No-Claim Bonus "
+            "and some restore the sum insured on exhaustion. Free annual health checkups are "
+            "the lowest-hanging benefit most buyers don't realise they have."
+        ),
+        "fields_driving_score": [
+            {"field": "no_claim_bonus_pct", "rule": "≥50% → +8, ≥25% → +4"},
+            {"field": "restoration_benefit", "rule": "Present → +6"},
+            {"field": "preventive_health_checkup", "rule": "Free annually → +3"},
+            {"field": "wellness_program_present", "rule": "Yes → +2"},
+        ],
+        "anchors": [
+            "IRDAI 'Cumulative Bonus' rules — capped at 100% under standard products",
+            "Industry NCB best-practice (PolicyBazaar comparison standards)",
+        ],
+    },
+]
+
+
 def grade_for(score: int) -> tuple[str, str]:
     """Return (letter, one-line summary tone)."""
     if score >= 85: return "A", "Strong all-rounder — solid pick for the buyer."

frontend/src/app/page.tsx

@@ -3,6 +3,7 @@
 import { useEffect, useRef, useState } from "react";
 import {
   audioBlobURLFromBase64,
+  BACKEND_URL,
   Citation,
   ChatMessage,
   CompareResponse,
@@ -1360,6 +1361,94 @@ function PolicyCard({
   );
 }
 
+type MethodologyResponse = {
+  weights: Record<string, number>;
+  scored_fields_count: number;
+  total_schema_fields: number;
+  criteria: Array<{
+    name: string;
+    weight_pct: number;
+    consumer_question: string;
+    why_it_matters: string;
+    fields_driving_score: Array<{ field: string; rule: string }>;
+    anchors: string[];
+  }>;
+  grade_thresholds: Record<string, string>;
+  scoring_approach: string;
+};
+
+function MethodologyExpander() {
+  const [open, setOpen] = useState(false);
+  const [data, setData] = useState<MethodologyResponse | null>(null);
+  useEffect(() => {
+    if (open && !data) {
+      fetch(`${BACKEND_URL}/api/scorecard/methodology`)
+        .then((r) => r.json())
+        .then(setData)
+        .catch(() => setData(null));
+    }
+  }, [open, data]);
+  return (
+    <div className="mt-3 border border-[var(--border)] rounded-lg bg-[var(--card)]">
+      <button
+        onClick={() => setOpen(!open)}
+        className="w-full text-left px-3 py-2 text-xs font-semibold flex items-center justify-between hover:bg-[var(--muted)]"
+      >
+        <span>How is this score computed? <span className="text-[var(--muted-foreground)] font-normal">(48 fields → 6 criteria, with weights)</span></span>
+        <span className="text-[var(--muted-foreground)]">{open ? "−" : "+"}</span>
+      </button>
+      {open && (
+        <div className="px-3 pb-3 space-y-3 text-xs border-t border-[var(--border)] pt-3">
+          {!data && <div className="text-[var(--muted-foreground)] py-2">Loading methodology…</div>}
+          {data && (
+            <>
+              <p className="text-[var(--muted-foreground)] leading-snug">
+                {data.scoring_approach} The blueprint below shows which fields drive each criterion and what regulatory or buyer-research source justifies the weight.
+              </p>
+              {data.criteria.map((c) => (
+                <div key={c.name} className="border border-[var(--border)] rounded-md p-2.5 bg-[var(--muted)]">
+                  <div className="flex items-baseline justify-between mb-1">
+                    <span className="text-xs font-bold">{c.name}</span>
+                    <span className="text-[10px] font-mono text-[var(--primary)]">{c.weight_pct}% of overall</span>
+                  </div>
+                  <div className="text-[11px] text-[var(--foreground)] italic mb-1">"{c.consumer_question}"</div>
+                  <div className="text-[11px] text-[var(--muted-foreground)] mb-2 leading-snug">{c.why_it_matters}</div>
+                  <details className="text-[11px]">
+                    <summary className="cursor-pointer text-[var(--primary)] hover:underline mb-1">
+                      {c.fields_driving_score.length} fields drive this score
+                    </summary>
+                    <ul className="mt-1 space-y-0.5 pl-2">
+                      {c.fields_driving_score.map((f, i) => (
+                        <li key={i} className="text-[10px]">
+                          <code className="text-[var(--primary)]">{f.field}</code>
+                          <span className="text-[var(--muted-foreground)]"> — {f.rule}</span>
+                        </li>
+                      ))}
+                    </ul>
+                  </details>
+                  {c.anchors.length > 0 && (
+                    <details className="text-[11px] mt-1">
+                      <summary className="cursor-pointer text-[var(--muted-foreground)] hover:text-[var(--foreground)]">
+                        Why this weight? {c.anchors.length} source{c.anchors.length === 1 ? "" : "s"}
+                      </summary>
+                      <ul className="mt-1 space-y-0.5 pl-2 text-[10px] text-[var(--muted-foreground)]">
+                        {c.anchors.map((a, i) => <li key={i}>· {a}</li>)}
+                      </ul>
+                    </details>
+                  )}
+                </div>
+              ))}
+              <div className="text-[10px] text-[var(--muted-foreground)] pt-1 border-t border-[var(--border)]">
+                Grade bands: A ≥85, B 70–84, C 55–69, D 40–54, F &lt;40. Overall = weighted average of the 6 sub-scores (weights re-tuned to buyer profile when known).
+              </div>
+            </>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
 function Stat({ label, value }: { label: string; value: string }) {
   return (
     <div>
@@ -1586,6 +1675,7 @@ function PolicyDetailModal({ policy, onClose }: { policy: MarketplacePolicy; onC
                 </div>
               </div>
               <ScorecardCard sc={sc} />
+              <MethodologyExpander />
             </div>
           )}
 

tools/extract_policy_text.py

@@ -0,0 +1,52 @@
+"""Extract text from policy PDFs to a text cache for curating policy_facts JSON."""
+import os, sys
+import pdfplumber
+
+BASE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+CACHE = "/tmp/claude/policy_extract/text_cache"
+os.makedirs(CACHE, exist_ok=True)
+
+PDFS = [
+    ("aditya-birla", "rag/corpus/aditya-birla/activ-assure-diamond__wordings.pdf"),
+    ("aditya-birla", "rag/corpus/aditya-birla/activ-one__brochure.pdf"),
+    ("bajaj-allianz", "rag/corpus/bajaj-allianz/health-guard-gold-individual__wordings.pdf"),
+    ("bajaj-allianz", "rag/corpus/bajaj-allianz/extra-care-plus__wordings.pdf"),
+    ("care-health", "rag/corpus/care-health/care-supreme__wordings.pdf"),
+    ("care-health", "rag/corpus/care-health/care-classic__wordings.pdf"),
+    ("care-health", "rag/corpus/care-health/care-senior__brochure.pdf"),
+    ("hdfc-ergo", "rag/corpus/hdfc-ergo/my-optima-secure__wordings.pdf"),
+    ("hdfc-ergo", "rag/corpus/hdfc-ergo/optima-restore__brochure.pdf"),
+    ("icici-lombard", "rag/corpus/icici-lombard/elevate__wordings.pdf"),
+    ("icici-lombard", "rag/corpus/icici-lombard/health-shield-360-retail__wordings.pdf"),
+    ("icici-lombard", "rag/corpus/icici-lombard/complete-health-insurance-health-shield__wordings.pdf"),
+    ("manipalcigna", "rag/corpus/manipalcigna/prohealth-insurance-all-variants__wordings.pdf"),
+    ("manipalcigna", "rag/corpus/manipalcigna/prohealth-select__wordings.pdf"),
+    ("new-india", "rag/corpus/new-india/new-india-floater-mediclaim-policy__wordings.pdf"),
+    ("niva-bupa", "rag/corpus/niva-bupa/reassure-2-0__wordings.pdf"),
+    ("niva-bupa", "rag/corpus/niva-bupa/senior-first__wordings.pdf"),
+    ("niva-bupa", "rag/corpus/niva-bupa/health-companion__wordings.pdf"),
+    ("star-health", "rag/corpus/star-health/family-health-optima__wordings.pdf"),
+    ("star-health", "rag/corpus/star-health/star-comprehensive__wordings.pdf"),
+    ("tata-aig", "rag/corpus/tata-aig/medicare-premier__wordings.pdf"),
+    ("tata-aig", "rag/corpus/tata-aig/medicare__wordings.pdf"),
+]
+
+for insurer, rel in PDFS:
+    src = os.path.join(BASE, rel)
+    name = os.path.basename(rel).replace(".pdf", ".txt")
+    dst = os.path.join(CACHE, f"{insurer}__{name}")
+    if os.path.exists(dst):
+        print(f"skip {os.path.basename(dst)}")
+        continue
+    if not os.path.exists(src):
+        print(f"MISSING {src}")
+        continue
+    try:
+        with pdfplumber.open(src) as pdf:
+            text = "\n".join((p.extract_text() or "") for p in pdf.pages)
+        with open(dst, "w", encoding="utf-8") as f:
+            f.write(text)
+        print(f"OK {os.path.basename(dst)} ({len(text)} chars)")
+    except Exception as e:
+        print(f"ERR {src}: {e}")
+print("Done.")