diff --git a/docs/HANDOVER_API_PROFILING.md b/docs/HANDOVER_API_PROFILING.md index 8adb4f05..f062ca91 100644 --- a/docs/HANDOVER_API_PROFILING.md +++ b/docs/HANDOVER_API_PROFILING.md @@ -13,16 +13,34 @@ deproven approaches + the meter/shower data-fidelity findings), and the earlier `energy_rating_current`. Headline gauge: `PYTHONPATH=/workspaces/model python scripts/eval_api_sap_accuracy.py`. -| metric | session-3 (`a8e5563a`) | session-4 (`faf29942`) | **session-5 (`58cff932`)** | +| metric | session-3 (`a8e5563a`) | session-4 (`faf29942`) | **session-5 (`19235d11`)** | |--------|------------------|------------------|------------------| | **% \|err\| < 0.5** | 45.1% | 47.6% | **53.1%** | | % \|err\| < 1.0 | 59.4% | 62.6% | **68.0%** | | % \|err\| < 2.0 | 77.7% | 79.6% | **~81%** | -| mean \|err\| | 1.702 | 1.586 | **1.424** | +| mean \|err\| | 1.702 | 1.586 | **1.329** | | median \|err\| | — | — | **0.467** | | computed / raises | 909 / 0 | 909 / 0 | **909 / 0** | | unsupported_schema | 100 (deferred) | 100 (deferred) | 100 (deferred) | +### SESSION-5 — fuel-code collision (anthracite/coal), `19235d11` +The re-audit traced the cohort's WORST cert (2100 anthracite, −61) + the −20/−21 coal cluster to +the **fuel-code collision** (`reference_fuel_code_collision`): the shared price/CO2/PE lookups check +Table-32/12-code membership BEFORE translating the gov-API fuel enum, so API-5 (anthracite) priced at +the bulk-LPG rate (12.19 p) and API-33 (coal) at the electricity-10h rate (7.5 p). KEY constraint +(goldens caught it): code 33 is ALSO the electricity-10h TARIFF code used by the dual-rate CO2/PE +split — so the fix CANNOT live in the shared table functions (breaks golden 000565). Instead +`canonical_fuel_code` (table_32) normalises the colliding SOLID-fuel enums at the **fuel-TYPE +boundary** (`_main_fuel_code`/`_water_heating_fuel_code`): 5→15 anthracite 3.64 p, 33→11 house coal +3.67 p; also fixes `is_electric_fuel_code(33)` mis-flagging coal as electric. Scoped to {5, 33} +(unambiguous large mispricings). mean|err| 1.424→1.329 (2100 −61→−11, residual now FABRIC: 110 905 +kWh demand = a separate area over-statement); within-0.5 flat at 53.1%. **DEFERRED follow-ups:** +dual-fuel API-9 (0.45 p delta, net-neutral, shifts certs in an un-understood direction — needs its own +look); community API-20/25/31 (route through the heat-network standing/CO2 path, NOT `unit_price` — +cert 8536 fuel-31 still mis-prices at 5.5 p electricity → −17). Method: the `decompose_api_cost_error.py` +heat:high/low tail + field-by-field audit of the worst certs surfaced it; `is_electric_fuel_code` +collisions are the tell. + ### THE UNIFYING PRINCIPLE (user, load-bearing) — "unknown insulation → as-built, NOT uninsulated" An EPC insulation field that is UNDETERMINED (thickness `'ND'`/`'AB'`/absent → parsed None, or description "as built / (assumed)") must map to the **age-band default** ("as built"), which is