LabLens / lablens /flagger.py
Imene-ee's picture
Upload 19 files
dab7db2 verified
Raw History Blame Contribute Delete
4.04 kB
"""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)