"""Deterministic flagging. No LLM is involved in deciding what is abnormal or urgent. Rules, in order: 0. Values outside physiologically possible bounds are marked CHECK (likely misread). 1. Critical thresholds from the catalog (converted to canonical units) always win. They escalate to an "urgent" banner. 2. Otherwise the report's own printed reference range decides low / high / normal. 3. If the report printed no range, the catalog's typical adult range is used and the result is marked as such, so the UI can say the range is generic. 4. If the unit can't be understood, critical checks are skipped and the flag uses only the printed range; if there is none, the flag is UNKNOWN. 5. If the lab printed an H/L marker that disagrees with the computed flag, the result becomes CHECK: a misread value must never come out as reassuring. """ from __future__ import annotations from .catalog import load_catalog from .models import Analysis, Flag, FlaggedResult, Result def flag_result(r: Result) -> FlaggedResult: catalog = load_catalog() fr = FlaggedResult(**r.model_dump()) td = catalog.get(r.test_key) if r.test_key else None canonical = td.to_canonical(r.value, r.unit) if td else None fr.canonical_value = round(canonical, 4) if canonical is not None else None # 0. Implausible values are almost always reading errors (dropped decimal, stray digit). # Never call them normal and never escalate on them: ask the user to check. if td and canonical is not None and not (td.plausible[0] <= canonical <= td.plausible[1]): fr.flag = Flag.CHECK fr.reason = "value outside what is physically possible; please check it against your report" return fr # 1. Critical values (only when we are sure of the unit). if td and canonical is not None: crit_low = td.critical.get("low") crit_high = td.critical.get("high") if crit_low is not None and canonical < crit_low: fr.flag = Flag.CRITICAL_LOW fr.reason = f"below critical threshold {crit_low} {td.canonical_unit}" return fr if crit_high is not None and canonical > crit_high: fr.flag = Flag.CRITICAL_HIGH fr.reason = f"above critical threshold {crit_high} {td.canonical_unit}" return fr # 2./3. Reference range: report first, catalog fallback. low, high, value = r.ref_low, r.ref_high, r.value if low is None and high is None: if td and canonical is not None: low, high = td.typical_range value = canonical fr.ref_source = "catalog" fr.ref_low, fr.ref_high = low, high else: fr.flag = Flag.UNKNOWN fr.ref_source = "none" fr.reason = "no reference range on the report and unit not recognized" return fr if low is not None and value < low: fr.flag, fr.reason = Flag.LOW, f"{value:g} is below {low:g}" elif high is not None and value > high: fr.flag, fr.reason = Flag.HIGH, f"{value:g} is above {high:g}" else: fr.flag, fr.reason = Flag.NORMAL, "within range" # 5. Cross-check with the lab's own H/L marker. If the lab marked the value abnormal # but the numbers we read say otherwise, something was misread: never reassure. m = r.report_marker if m and ((fr.flag == Flag.NORMAL) or (m == "H" and fr.flag == Flag.LOW) or (m == "L" and fr.flag == Flag.HIGH)): fr.flag = Flag.CHECK fr.reason = f"the lab marked this value '{m}' but the numbers read disagree; please check" return fr def flag_all(results: list[Result], language: str = "en", unmatched: list[str] | None = None, method: str = "") -> Analysis: flagged = [flag_result(r) for r in results] urgent = any(f.flag in (Flag.CRITICAL_LOW, Flag.CRITICAL_HIGH) for f in flagged) return Analysis(language=language, results=flagged, unmatched_lines=unmatched or [], urgent=urgent, extraction_method=method)