Spaces:
Sleeping
Sleeping
Claude Code
fix(pricing+scoring): rebuild premium engine to 0 logical violations + classification, faithfulness, links, writing
f266901 | # Premium Dependency Map | |
| | Field | Value | | |
| | --- | --- | | |
| | Document type | Dependency / change-cascade map (data + code) | | |
| | Subject data file | `40-data/premiums/illustrative_premiums.json` | | |
| | Generated (this doc) | 2026-05-18 | | |
| | Companion | [`premium-source-map.md`](premium-source-map.md) (per-sample provenance) | | |
| | Source of truth for chain | `backend/premium_calculator.py`, `backend/brain_tools.py`, `backend/main.py`, `backend/scorecard.py` | | |
| ## 0. Purpose | |
| This document is the **change-cascade contract for the premium pipeline**. It exists so a future edit to the curated JSON, a calculator helper, an API contract, or the reviews/scorecard parity surface does not silently break a downstream consumer. | |
| Every node below names: **what it consumes**, **what depends on it**, and an explicit **"if you change X you must re-verify Y"** rule. Function and constant names are taken verbatim from the source files (read 2026-05-18); they are not paraphrased. | |
| ## 1. The pricing chain (end to end) | |
| ``` | |
| 40-data/premiums/illustrative_premiums.json | |
| │ (base_premiums{}, scaling_factors{}) | |
| ▼ | |
| premium_calculator._load_data() [reads + json.loads the file; {} on any error] | |
| ▼ | |
| premium_calculator._canonical_sample_key() [resolve recommended/marketplace id → base_premiums key] | |
| │ ├─ _SAMPLE_DOCTYPE_SUFFIXES (__brochure/__cis/__wordings/__prospectus/__policy) | |
| │ └─ _KNOWN_BAD_SAMPLE_KEYS (currently EMPTY frozenset — quarantine mechanism, retained) | |
| ▼ | |
| premium_calculator._plausible_samples() [type-aware ₹/lakh sanity guard, via _per_lakh_band()] | |
| ▼ | |
| premium_calculator._interpolate_from_samples() [nearest sample in (age, log SI) space] | |
| ▼ | |
| premium_calculator.estimate() [#38 FULL ratio-normalization + OUTPUT plausibility ceiling] | |
| │ └─ NO-sample path → _attribute_base_factor() (product-TYPE model; no JSON I/O) | |
| ▼ | |
| premium_calculator.bulk_estimate() [calls estimate() per policy on the curated path; | |
| │ flat ₹500/lakh × type-factor on the no-sample path] | |
| ▼ | |
| premium_calculator.estimate_premium_band() [prices the 26-policy _DEFAULT_BAND_POLICY_IDS basket; | |
| │ p25–p75 interquartile via resolve_profile_sum_insured()] | |
| ▼ | |
| backend/main.py POST /api/premium/estimate (PremiumEstimateRequest → PremiumEstimateResponse) | |
| POST /api/premium/bulk (PremiumBulkRequest → PremiumBulkResponse) | |
| GET /api/profile/predicted-premium-band (→ PredictedPremiumBandResponse) | |
| ▼ | |
| frontend/src/lib/api.ts postPremiumEstimate() / PremiumEstimateResponse | |
| ▼ | |
| frontend/src/components/PolicyPremiumWidget.tsx (point + ±15% band + methodology line + SI disclosure) | |
| └─ embedded in PolicyCompareModal.tsx; header chip in app/page.tsx (premiumBand state) | |
| ``` | |
| Parallel, independent chain (claim-experience parity, **not** premium-priced): | |
| ``` | |
| 40-data/reviews/<slug>.json | |
| ▼ | |
| brain_tools._insurer_reviews(slug) [cached read; None if missing] | |
| ▼ | |
| scorecard.score_claim_experience(p, insurer_reviews=…) [IRDAI CSR + complaints/10k → sub-score] | |
| ▼ | |
| scorecard.build_scorecard(data, insurer_reviews=…, profile=…) | |
| ├─ recommendation path: brain_tools._scorecard_signal() → cited-card grade | |
| └─ marketplace path: main.py /api/policies/all → marketplace grade | |
| ▼ PARITY INVARIANT (tests/test_scorecard_parity.py): cited-card GRADE LETTER == marketplace GRADE LETTER | |
| ``` | |
| ## 2. Node-by-node dependency contract | |
| ### 2.1 `40-data/premiums/illustrative_premiums.json` | |
| - **Consumes:** nothing — it is the single source of truth. Top-level keys: `last_updated`, `methodology`, `sources_consulted`, `notes`, `base_premiums` (100 entries), `scaling_factors`, `link_rot_repairs`. | |
| - **Depended on by:** `_load_data()` (the ONLY reader), and transitively everything below it. Also documented by [`premium-source-map.md`](premium-source-map.md). | |
| - **Sample shape (post-harvest):** evidenced samples carry `age`, `sum_insured_inr`, `city_tier`, `smoker`, `family_size`, `annual_premium_inr`, `source_url`, `source_quote`, `source_quality`, `fetched_on` (+ optional `source_note`/`derivation_note`/`variant`). 194 evidenced samples across 73 entries; 27 entries are model-only. | |
| - **If you change X you must re-verify Y:** | |
| - Change/add a `samples[]` entry → re-run `_plausible_samples()` mentally against `_per_lakh_band()` for that policy type (comprehensive 250–6500/L; top-up 10–800/L; benefit plans unbounded). A sample outside the band is silently dropped, so the policy may regress to the model path. | |
| - Change a `base_premiums` **key** → re-verify `_canonical_sample_key()` still resolves the marketplace/recommended id (suffix + single-hyphen forms) AND that the key appears in `_DEFAULT_BAND_POLICY_IDS` if it should be in the header basket. | |
| - Change `scaling_factors` (age/SI/city/floater/smoker/PED multipliers) → re-verify the **#38 ratio-normalization** in `estimate()`: it divides the sample's own multipliers out and re-applies the user's, so a changed factor moves every curated-path estimate. Re-run `tests/test_premium_attribute_and_normalization.py` + `tests/test_premium_reconciliation.py`. | |
| - Edit/add/remove any evidenced sample → **regenerate [`premium-source-map.md`](premium-source-map.md) §1 counts and §2/§3 tables in the same commit** (the JSON is the single source of truth for both docs). | |
| ### 2.2 `premium_calculator._load_data()` | |
| - **Consumes:** `PREMIUM_DATA` path (`settings.DATA_DIR / "premiums" / "illustrative_premiums.json"`). | |
| - **Depended on by:** `estimate()`, `bulk_estimate()` (each call re-reads — no module cache). | |
| - **If you change X:** moving/renaming the JSON, or breaking its JSON validity, makes `_load_data()` return `{}` **silently** → every policy falls to `FALLBACK_*` constants (no exception, no log). Re-verify by calling `estimate(policy_id=...)` for a known-curated policy and asserting `base_sample_used is not None`. | |
| ### 2.3 `premium_calculator._canonical_sample_key()` | |
| - **Consumes:** the incoming `policy_id`, `base_premiums` keys, `_SAMPLE_DOCTYPE_SUFFIXES`, `_KNOWN_BAD_SAMPLE_KEYS`. | |
| - **Depended on by:** `estimate()` (sample lookup) **and** `bulk_estimate()` (the `if _canonical_sample_key(pid, …) is not None` branch decides curated-anchor vs flat-base). Both must agree or the widget and the per-policy panel diverge. | |
| - **If you change X:** add a doctype suffix or change the hyphen-normalization → re-verify BOTH call sites resolve the same key (a mismatch reintroduces the ₹33,700 collision / the SBI Arogya Supreme double-floater bug). `_KNOWN_BAD_SAMPLE_KEYS` is currently the empty frozenset (SBI Arogya Supreme was unquarantined 2026-05-18 after its bad brochure-extract was physically replaced with real SBI rate-chart figures); to re-quarantine a proven-bad entry, add its key here AND note it in the source map. | |
| ### 2.4 `premium_calculator._per_lakh_band()` / `_plausible_samples()` | |
| - **Consumes:** `policy_id` substring (type detection), each sample's `sum_insured_inr` + `annual_premium_inr`. | |
| - **Depended on by:** `estimate()` (input guard before interpolation) **and** the **OUTPUT plausibility ceiling** at the end of `estimate()` (ceiling = `_hi_b * 1.5`). | |
| - **If you change X:** widening/narrowing a band → re-verify (a) no real evidenced sample is now dropped (would silently demote a policy to the model path) and (b) the output ceiling still trips only on genuinely broken data. The product-type substrings (`top-up`, `hospital-cash`, `cancer`, `critical-illness`, …) are matched against the lowercased `policy_id`; renaming a key can flip a plan between bands. | |
| ### 2.5 `premium_calculator._attribute_base_factor()` — the no-sample path | |
| - **Consumes:** `policy_id` substring only. No JSON I/O — deterministic on the id. | |
| - **Depended on by:** `estimate()` (no-sample branch), `bulk_estimate()` (flat-base `flat_base = BULK_BASE_INR_PER_LAKH * si_lakhs * _attribute_base_factor(pid)`), and therefore every one of the **27 model-only entries** in the source map §3. | |
| - **Returns:** super-top-up/top-up 0.35×, hospital-cash/fixed-benefit 0.30×, cancer/critical-illness 0.55×, `sanjeevani` 0.70×, comprehensive 1.0× (no regression for the dominant type). | |
| - **If you change X:** changing a factor moves every model-only policy of that type AND the flat-base widget number. Re-verify against the type-band so a model-only estimate stays inside `_per_lakh_band()`; re-run `tests/test_premium_attribute_and_normalization.py`. **Provenance label:** model-path estimates carry the methodology string *"Indicative estimate modelled from this plan's product type … NOT a quote"* — if you ever anchor a model-only policy to a real sample, move it out of source-map §3 into §2 and the label flips to the *"Anchored to a verified public-quote sample"* variant automatically (driven by `sample_used is not None`). | |
| ### 2.6 `premium_calculator.estimate()` | |
| - **Consumes:** `_load_data()`, `_canonical_sample_key()`, `_plausible_samples()`, `_interpolate_from_samples()`, `scaling_factors`, the B6/D2/KI-275 loadings (`_health_loading`, `_existing_cover_loading`, `_parents_loading`, `_copay_discount`, `_family_history_loading`, `_copay_multiplier`). | |
| - **Depended on by:** `bulk_estimate()` (curated path calls `estimate()` directly), `POST /api/premium/estimate`, and indirectly the header band (`estimate_premium_band → bulk_estimate → estimate`). | |
| - **Two critical internal invariants:** | |
| 1. **#38 full ratio-normalization** — the sample's own age/SI/city/family multipliers are divided out, then the user's profile is applied exactly once by the unconditional city/floater/smoker/PED block. Sample `family_size` is HEADCOUNT (1=individual); `estimate()`'s floater key is dependents-beyond-self (`max(0, headcount-1)`). Breaking this re-introduces double-counted floater (the SBI ₹149,800 bug). | |
| 2. **OUTPUT plausibility ceiling** — if a sample-anchored point still exceeds `_per_lakh_band(...)[1] * 1.5` per lakh after normalization+loadings, it drops `sample_used`/`sources` and falls back to the policy-blind model base. | |
| - **If you change X:** changing the loading order, the normalization, or the ceiling → re-run BOTH `tests/test_premium_reconciliation.py` and `tests/test_premium_attribute_and_normalization.py`; the header-band p25–p75 contract depends on `estimate()` being stable. | |
| ### 2.7 `premium_calculator.bulk_estimate()` / `estimate_premium_band()` | |
| - **Consumes:** `bulk_estimate()` calls `estimate()` on the curated path; `estimate_premium_band()` calls `bulk_estimate()` over `_DEFAULT_BAND_POLICY_IDS` (26 policies) and `resolve_profile_sum_insured()` for the shared SI. | |
| - **Depended on by:** `POST /api/premium/bulk`, `GET /api/profile/predicted-premium-band`, the PolicyCompareModal widget, and the header "Premium range" chip. | |
| - **SI contract (KI-278):** `resolve_profile_sum_insured()` precedence (`desired_sum_insured_inr ?? existing_cover_inr ?? ₹10L`, snapped to ₹50k) MUST stay byte-identical to `PremiumCalculatorPanel`'s slider seed (`frontend/src/app/page.tsx` ~L2417) and `PolicyPremiumWidget`'s `initialSumInsured`. The chip band is the **p25–p75 interquartile** of the basket, NOT raw min–max. | |
| - **If you change X:** | |
| - Add/remove a policy in `_DEFAULT_BAND_POLICY_IDS` → re-verify each id resolves via `_canonical_sample_key()` (else it silently uses the flat path) and re-check the chip band is still a sane range. | |
| - Change the SI precedence on either side → change BOTH `resolve_profile_sum_insured()` and the page.tsx slider seed in the same commit, else header ≠ panel returns. Re-run `tests/test_premium_reconciliation.py`. | |
| ### 2.8 API layer (`backend/main.py`) | |
| - **Consumes:** `estimate`, `bulk_estimate`, `estimate_premium_band`, `unpublished_si_disclosure`, `_policy_corroborated_si`. | |
| - **Depended on by:** `frontend/src/lib/api.ts` (`postPremiumEstimate`, `PremiumEstimateResponse` type), `PolicyPremiumWidget.tsx`, `PolicyCompareModal.tsx`, `app/page.tsx` (`premiumBand`). | |
| - **Contract surfaces that must not drift:** `PremiumEstimateResponse.base_sample_used` (widget shows/hides its "Estimate" badge off this — it is `e.base_sample_used is not None`), `methodology` (rendered verbatim under the estimate), `sources` (the source URLs), `sum_insured_disclosure` (rendered verbatim only when `_policy_corroborated_si(...).kind == "none"`). `predicted-premium-band` feeds the profile dict via `brain_tools.SLOT_UNION` with the answered-only gate (`profile.asked`). | |
| - **If you change X:** renaming/removing a response field → update `frontend/src/lib/api.ts` types + every `.tsx` consumer in the same commit. Changing `tenure_years`/`deductible_inr` snapping uses `BULK_TENURE_MULT`/`BULK_DEDUCTIBLE_DISCOUNT` from the calculator — keep them in sync. | |
| ### 2.9 Reviews → scorecard claim-experience PARITY chain | |
| - **Consumes:** `40-data/reviews/<slug>.json` → `brain_tools._insurer_reviews(slug)` (cached; `None` if missing) → `scorecard.score_claim_experience(p, insurer_reviews=…)` → `scorecard.build_scorecard(data, insurer_reviews=…, profile=…)`. | |
| - **Two paths that MUST stay in parity:** | |
| - **Recommendation / cited-card grade:** `brain_tools._scorecard_signal()` builds `data` via `_merge_curated(extracted, curated)` (KI-PARITY 2026-05-18 — curated-only made the cited grade systematically lower), resolves `slug`, passes `_insurer_reviews(slug)` into `build_scorecard`. | |
| - **Marketplace grade:** `/api/policies/all` builds `build_scorecard` on the full curated+reviews layer. | |
| - **PARITY INVARIANT:** the cited-card **grade letter** must equal the marketplace **grade letter** for the same policy. Locked by `tests/test_scorecard_parity.py` (overall scores may differ by a few points because the marketplace overlays `EXTRACTED_DIR`; the LETTER, which `_recommendation_fit` gates on, must match). | |
| - **If you change X:** | |
| - Edit a `40-data/reviews/<slug>.json` `claim_metrics` value → re-verify `score_claim_experience()` band thresholds (CSR ≥95 +20, ≥90 +12, ≥85 +5, ≥75 −6, else −20; complaints/10k ≤10 +8 … >45 −16) and re-run `tests/test_scorecard_parity.py` — a CSR/complaints change can flip the sub-score enough to move the grade letter, which must move identically on BOTH paths. | |
| - Change `_scorecard_signal()`'s data assembly (`_merge_curated`, `_candidate_stems`, slug derivation) → re-run `tests/test_scorecard_parity.py`; divergence makes the recommendation path drop policies (empty `citations` → CitedPolicyCards never render). | |
| - This chain is **independent of premium pricing** — it does NOT read `illustrative_premiums.json`. Document it here only because it shares the source-methodology + dependency-map treatment and the same `_insurer_reviews`/scorecard machinery. | |
| ## 3. Quick "change X → re-verify Y" lookup | |
| | If you change… | You must re-verify… | Tests / docs to re-run | | |
| | --- | --- | --- | | |
| | A `samples[]` entry / a premium figure | `_plausible_samples` band, `_interpolate_from_samples` nearest pick, `estimate()` #38 normalization | `test_premium_reconciliation.py`, `test_premium_attribute_and_normalization.py`, regenerate `premium-source-map.md` | | |
| | A `base_premiums` key name | `_canonical_sample_key` both call sites, `_DEFAULT_BAND_POLICY_IDS` membership, `_per_lakh_band`/`_attribute_base_factor` substring match | `test_premium_reconciliation.py`, source map §2/§3 | | |
| | `scaling_factors` multipliers | `estimate()` ratio-normalization output, header band | both premium tests | | |
| | `_attribute_base_factor` | every model-only entry + flat-base widget, type-band sanity | `test_premium_attribute_and_normalization.py`, source map §3 | | |
| | `resolve_profile_sum_insured` precedence | page.tsx slider seed byte-identity, header == panel | `test_premium_reconciliation.py` | | |
| | A `PremiumEstimateResponse` field | `frontend/src/lib/api.ts` types, `PolicyPremiumWidget.tsx`, `PolicyCompareModal.tsx`, `page.tsx` | frontend typecheck/build | | |
| | `_DEFAULT_BAND_POLICY_IDS` | each id resolves via `_canonical_sample_key`, chip band sanity | `test_premium_reconciliation.py` | | |
| | `40-data/reviews/<slug>.json` claim_metrics | `score_claim_experience` thresholds, cited-grade == marketplace-grade | `test_scorecard_parity.py` | | |
| | `_scorecard_signal` data assembly | parity invariant (grade letter both paths) | `test_scorecard_parity.py` | | |
| | Move/rename/corrupt the JSON | `_load_data()` returns `{}` SILENTLY → all-fallback | manual `estimate()` smoke on a known-curated id | | |
| ## 4. Regeneration | |
| Both this map and [`premium-source-map.md`](premium-source-map.md) are derived from the same single source of truth (`40-data/premiums/illustrative_premiums.json`) plus the code chain above. After any premium-harvest or calculator-contract change, update the affected §2 node contract and the §3 lookup row in the **same commit** as the code/data change — the "if you change X you must re-verify Y" rules are only useful if they stay in lockstep with the chain. | |