Add knowledge graph health report pipeline

Co-authored-by: Codex <chatgpt-codex-connector[bot]@users.noreply.github.com>

README.md

@@ -33,6 +33,16 @@ The long-term vision is to make medical paperwork less intimidating and help peo
 
 The first version focuses only on extraction: upload a lab report and convert it into structured raw values such as marker name, value, unit, reference range, status, source snippet, and confidence.
 
+## Current Pipeline
+
+The app now runs extraction and deterministic knowledge-graph enrichment:
+
+1. The extractor reads an uploaded image, PDF, or text document and returns patient context plus raw lab values.
+2. `src.report_pipeline.build_health_report` resolves marker aliases against `kb/cbc_knowledge_graph.json`, selects age/sex-aware reference context, and merges marker explanations, importance, and food/exercise/supplement guidance.
+3. `app.py` renders the enriched report as the final health-report UI.
+
+The knowledge graph is educational context, not diagnosis. The lab-provided reference range remains the primary comparison when it is available.
+
 Local setup:
 
 ```bash

app.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import os
+import re
 from html import escape
 from typing import Any
 
@@ -8,6 +9,7 @@ import gradio as gr
 
 from src.local_env import load_local_env
 from src.extraction import build_extractor
+from src.report_pipeline import build_health_report
 
 
 load_local_env()
@@ -38,13 +40,27 @@ def extract_lab_values(
             gr.update(visible=True),
         )
 
-    status_text = f"Extracted {len(result.tests)} lab values."
+    health_report = build_health_report(result)
+    summary = health_report["summary"]
+    patient = health_report["patient"]
+
+    status_text = (
+        f"Extracted {summary['total_markers']} lab values and enriched "
+        f"{summary['enriched_markers']} from the knowledge graph."
+    )
+    patient_bits = []
+    if patient.get("age"):
+        patient_bits.append(f"age {patient['age']}")
+    if patient.get("sex") and patient["sex"] != "unknown":
+        patient_bits.append(patient["sex"])
+    if patient_bits:
+        status_text += " Patient context: " + ", ".join(patient_bits) + "."
     if result.notes:
         status_text += " Notes: " + " ".join(result.notes[:3])
 
     return (
         _status_html("Extraction complete", status_text),
-        report_html(result.tests, result.notes),
+        report_html(health_report),
         gr.update(visible=True),
     )
 
@@ -60,7 +76,7 @@ def _status_html(title: str, detail: str, tone: str = "success") -> str:
 
 def show_processing() -> tuple[str, Any, str]:
     return (
-        _status_html("Reading document", "Extracting markers, values, units, ranges, and confidence signals.", tone="loading"),
+        _status_html("Reading document", "Extracting patient context and markers, then matching them to the knowledge graph.", tone="loading"),
         gr.update(visible=True),
         loading_report_html(),
     )
@@ -91,7 +107,7 @@ def selected_document_html(filename: str | None = None) -> str:
       <div>
         <p class="bte-kicker">Document loaded</p>
         <h3>{escape(filename)}</h3>
-        <p>Ready to extract markers, values, units, ranges, and confidence signals.</p>
+        <p>Ready to extract markers, patient context, values, units, ranges, and confidence signals.</p>
       </div>
     </section>
     """
@@ -122,7 +138,7 @@ def loading_report_html() -> str:
       <div class="bte-loading-copy">
         <p class="bte-kicker">Extraction in progress</p>
         <h2>Reading your test results</h2>
-        <p>The model is locating markers, values, units, reference ranges, and status flags. The full report will appear here when extraction is complete.</p>
+        <p>The model is locating patient context, markers, values, units, reference ranges, and status flags. The knowledge graph report will appear when enrichment is complete.</p>
       </div>
       <div class="bte-loading-stack" aria-hidden="true">
         <div><span></span><strong></strong></div>
@@ -346,65 +362,84 @@ def _ideal_marker_card(test: dict[str, str]) -> str:
     """
 
 
-def report_html(tests: list[dict[str, Any]], notes: list[str]) -> str:
-    total = len(tests)
-    high = _count_status(tests, "high")
-    low = _count_status(tests, "low")
-    abnormal = _count_status(tests, "abnormal")
-    normal = _count_status(tests, "normal")
-    needs_review = high + low + abnormal
+def report_html(report: dict[str, Any]) -> str:
+    markers = list(report.get("markers") or [])
+    summary = report.get("summary") or {}
+    patient = report.get("patient") or {}
 
-    cards = "\n".join(_marker_card(test) for test in tests) or _empty_marker_card()
-    notes_html = "".join(f"<li>{escape(note)}</li>" for note in notes[:6])
-    notes_block = f"<ul>{notes_html}</ul>" if notes_html else "<p>No extraction notes returned.</p>"
+    total = int(summary.get("total_markers") or len(markers))
+    final_statuses = [_final_status_for_marker(marker) for marker in markers]
+    ideal = final_statuses.count("ideal")
+    normal = final_statuses.count("normal")
+    bad = final_statuses.count("bad")
+    patient_context = _final_patient_context(patient)
+
+    left_cards = "\n".join(
+        _final_marker_card(marker) for index, marker in enumerate(markers) if index % 2 == 0
+    )
+    right_cards = "\n".join(
+        _final_marker_card(marker) for index, marker in enumerate(markers) if index % 2 == 1
+    )
+    if not left_cards and not right_cards:
+        left_cards = _empty_final_marker_card()
 
     return f"""
-    <section class="bte-report">
-      <header class="bte-report-hero">
+    <section class="bte-ideal-doc bte-final-report">
+      <header class="bte-ideal-hero">
         <div>
-          <p class="bte-kicker">Lab extraction report</p>
-          <h2>{total} markers found</h2>
-          <p>Review the extracted values before using them for interpretation. This draft is an extraction view only.</p>
-        </div>
-        <div class="bte-score">
-          <span>{needs_review}</span>
-          <small>need review</small>
+          <p class="bte-kicker">Final health report</p>
+          <h2>Final health report reference</h2>
+          <p>Generated from the uploaded lab report, matched to the knowledge graph, and enriched with age and sex context. {escape(patient_context)}</p>
         </div>
       </header>
 
-      <div class="bte-metrics">
-        {_metric("Total", total, "All extracted markers")}
-        {_metric("Review", needs_review, "High, low, or abnormal")}
-        {_metric("Normal", normal, "Marked normal")}
-        {_metric("Unknown", max(total - needs_review - normal, 0), "Needs confirmation")}
-      </div>
+      <input class="bte-ideal-filter" type="radio" name="bte-final-filter" id="bte-final-filter-total" checked>
+      <input class="bte-ideal-filter" type="radio" name="bte-final-filter" id="bte-final-filter-ideal">
+      <input class="bte-ideal-filter" type="radio" name="bte-final-filter" id="bte-final-filter-normal">
+      <input class="bte-ideal-filter" type="radio" name="bte-final-filter" id="bte-final-filter-bad">
 
-      <div class="bte-status-strip">
-        {_pill("High", high, "high")}
-        {_pill("Low", low, "low")}
-        {_pill("Abnormal", abnormal, "abnormal")}
-        {_pill("Normal", normal, "normal")}
+      <div class="bte-ideal-stats">
+        <label class="bte-ideal-stat bte-ideal-stat--total" for="bte-final-filter-total">
+          <span>{total}</span>
+          <strong>Total tests</strong>
+        </label>
+        <label class="bte-ideal-stat bte-ideal-stat--ideal" for="bte-final-filter-ideal">
+          <span>{ideal}</span>
+          <strong>Ideal</strong>
+        </label>
+        <label class="bte-ideal-stat bte-ideal-stat--normal" for="bte-final-filter-normal">
+          <span>{normal}</span>
+          <strong>Normal</strong>
+        </label>
+        <label class="bte-ideal-stat bte-ideal-stat--bad" for="bte-final-filter-bad">
+          <span>{bad}</span>
+          <strong>Bad</strong>
+        </label>
       </div>
 
-      <div class="bte-report-grid">
-        <section class="bte-marker-list">
-          {cards}
-        </section>
-        <aside class="bte-report-aside">
-          <h3>Extraction notes</h3>
-          {notes_block}
-          <div class="bte-disclaimer">
-            <strong>Draft only</strong>
-            <span>These are raw extracted values, not medical advice. Confirm values against the original document.</span>
-          </div>
-        </aside>
+      <div class="bte-ideal-grid">
+        <div class="bte-ideal-column">
+          {left_cards}
+        </div>
+        <div class="bte-ideal-column">
+          {right_cards}
+        </div>
       </div>
     </section>
     """
 
 
-def _count_status(tests: list[dict[str, Any]], status: str) -> int:
-    return sum(1 for test in tests if str(test.get("status") or "").lower() == status)
+def _patient_context_html(patient: dict[str, Any]) -> str:
+    age = _text(patient.get("age"), "Not extracted")
+    age_group = _text(patient.get("age_group"), "adult")
+    sex = _text(patient.get("sex"), "unknown")
+    return f"""
+    <dl class="bte-patient-context">
+      <div><dt>Age</dt><dd>{escape(age)}</dd></div>
+      <div><dt>Age group</dt><dd>{escape(age_group.title())}</dd></div>
+      <div><dt>Sex</dt><dd>{escape(sex.title())}</dd></div>
+    </dl>
+    """
 
 
 def _metric(label: str, value: int, caption: str) -> str:
@@ -422,13 +457,25 @@ def _pill(label: str, value: int, tone: str) -> str:
 
 
 def _marker_card(test: dict[str, Any]) -> str:
-    marker = _text(test.get("marker"), "Unknown marker")
+    marker = _preferred_marker_label(test)
+    raw_name = _text(test.get("raw_name"), marker)
     value = _text(test.get("value"), "-")
     unit = _text(test.get("unit"), "")
-    reference = _text(test.get("reference_range"), "Reference range not extracted")
+    reference = _reference_label(test)
     status = _text(test.get("status"), "unknown").lower()
-    source = _text(test.get("source_text"), "No source snippet returned.")
     confidence = _confidence_percent(test.get("confidence"))
+    comparison = test.get("comparison") or {}
+    range_position = escape(str(comparison.get("range_position", 50)))
+    knowledge = test.get("knowledge") or {}
+    source = _text(test.get("source_text"), "No source snippet returned.")
+    description = _text(knowledge.get("description"), "No knowledge graph description available for this marker.")
+    why = _text(knowledge.get("why_important"), "No knowledge graph importance note available for this marker.")
+    instructions = knowledge.get("instructions_to_improve") or {}
+    sex_context = knowledge.get("sex_significance") or {}
+    sex_summary = _text(sex_context.get("summary"), "No major sex-specific interpretation note is stored for this marker.")
+    stats_text = _statistics_text(test)
+    derived = _text(test.get("derived_status"), "unknown")
+    extracted = _text(test.get("extracted_status"), "unknown")
 
     return f"""
     <details class="bte-marker bte-marker--{escape(status)}" open>
@@ -444,17 +491,259 @@ def _marker_card(test: dict[str, Any]) -> str:
         <span class="bte-marker-status">{escape(status.title())}</span>
       </summary>
       <div class="bte-marker-body">
-        <div>
-          <span>Confidence</span>
+        <div class="bte-marker-evidence">
+          <span>Extraction confidence</span>
           <div class="bte-confidence"><i style="width: {confidence}%"></i></div>
           <small>{confidence}%</small>
+          <span>Raw marker</span>
+          <small>{escape(raw_name)}</small>
+          <span>Status check</span>
+          <small>Extracted: {escape(extracted.title())}. Calculated: {escape(derived.title())}.</small>
+          <blockquote>{escape(source)}</blockquote>
+        </div>
+        <div class="bte-marker-insights">
+          <div class="bte-range-scale bte-range-scale--report" style="--value-position: {range_position}%; --value-position-number: {range_position}">
+            <div class="bte-range-value">
+              <strong>{escape(value)}</strong>
+              <small>{escape(unit)}</small>
+            </div>
+            <div class="bte-range-track" aria-hidden="true">
+              <span>Low</span>
+              <span>Reference</span>
+              <span>High</span>
+            </div>
+          </div>
+          <div class="bte-insight-grid">
+            {_insight_block("Measures", description)}
+            {_insight_block("Why it matters", why)}
+            {_insight_block("Selected range", stats_text)}
+            {_insight_block("Sex context", sex_summary)}
+          </div>
+          <div class="bte-guidance">
+            {_guidance_column("Food", instructions.get("food"))}
+            {_guidance_column("Exercise", instructions.get("exercises"))}
+            {_guidance_column("Supplements", instructions.get("supplements"))}
+          </div>
         </div>
-        <blockquote>{escape(source)}</blockquote>
       </div>
     </details>
     """
 
 
+def _final_marker_card(test: dict[str, Any]) -> str:
+    marker = _preferred_marker_label(test)
+    value = _text(test.get("value"), "-")
+    unit = _text(test.get("unit"), "")
+    status = _final_status_for_marker(test)
+    range_position = escape(str(_final_range_position(test)))
+    knowledge = test.get("knowledge") or {}
+    instructions = knowledge.get("instructions_to_improve") or {}
+    description = _text(knowledge.get("description"), "No knowledge graph description available for this marker.")
+    why = _text(knowledge.get("why_important"), "No knowledge graph importance note available for this marker.")
+    improve = _final_improvement_text(instructions)
+    context = _final_context_text(test)
+
+    return f"""
+    <article class="bte-ideal-marker bte-ideal-marker--{escape(status)}">
+      <div class="bte-ideal-marker-head">
+        <div class="bte-ideal-title-line">
+          <h3>{escape(marker)}</h3>
+          <span class="bte-ideal-status">{escape(status.title())}</span>
+        </div>
+        <div class="bte-range-scale" style="--value-position: {range_position}%; --value-position-number: {range_position}">
+          <div class="bte-range-value">
+            <strong>{escape(value)}</strong>
+            <small>{escape(unit)}</small>
+          </div>
+          <div class="bte-range-track" aria-hidden="true">
+            <span>Bad</span>
+            <span>Normal</span>
+            <span>Good</span>
+          </div>
+        </div>
+      </div>
+      <div class="bte-ideal-marker-body">
+        <div>
+          <span>Measures</span>
+          <p>{escape(description)}</p>
+        </div>
+        <div>
+          <span>Why it matters</span>
+          <p>{escape(why)}</p>
+        </div>
+        <div>
+          <span>How to improve</span>
+          <p>{escape(improve)}</p>
+        </div>
+        <div>
+          <span>Reference context</span>
+          <p>{escape(context)}</p>
+        </div>
+      </div>
+    </article>
+    """
+
+
+def _final_status_for_marker(marker: dict[str, Any]) -> str:
+    quality = _final_quality(marker)
+    if quality is None:
+        status = _text(marker.get("status"), "unknown").lower()
+        if status in {"low", "high", "abnormal"}:
+            return "bad"
+        return "normal"
+    return quality["status"]
+
+
+def _preferred_marker_label(marker: dict[str, Any]) -> str:
+    canonical = _text(marker.get("display_name"), "Unknown marker")
+    raw_name = _text(marker.get("raw_name"), "")
+    if _looks_like_marker_abbreviation(raw_name, canonical):
+        return raw_name
+    return canonical
+
+
+def _looks_like_marker_abbreviation(raw_name: str, canonical: str) -> bool:
+    raw = raw_name.strip()
+    if not raw or raw.casefold() == canonical.strip().casefold():
+        return False
+    if len(raw) > 16:
+        return False
+
+    compact = re.sub(r"[\s._-]+", "", raw)
+    letters = [char for char in compact if char.isalpha()]
+    if not letters:
+        return False
+
+    if any(symbol in raw for symbol in ("%#",)):
+        return True
+    if "/" in raw and len(compact) <= 12:
+        return True
+
+    uppercase_ratio = sum(char.isupper() for char in letters) / len(letters)
+    if len(compact) <= 10 and uppercase_ratio >= 0.6:
+        return True
+
+    # Common lab shorthand is often title-cased, e.g. Hct or Plt.
+    canonical_is_descriptive = len(canonical) > len(raw) + 3 or " " in canonical
+    return canonical_is_descriptive and len(compact) <= 5 and raw[0].isupper()
+
+
+def _final_range_position(marker: dict[str, Any]) -> int:
+    quality = _final_quality(marker)
+    if quality is not None:
+        return quality["position"]
+
+    return int((marker.get("comparison") or {}).get("range_position") or 50)
+
+
+def _final_quality(marker: dict[str, Any]) -> dict[str, Any] | None:
+    values = _final_reference_values(marker)
+    numeric = _final_numeric_value(marker)
+    if values is None or numeric is None:
+        return None
+
+    low, normal, high = values
+    if high <= low:
+        return None
+
+    if numeric < low:
+        distance = (low - numeric) / max(normal - low, high - low, 1.0)
+        return {"status": "bad", "position": max(6, min(30, round(26 - distance * 18)))}
+    if numeric > high:
+        distance = (numeric - high) / max(high - normal, high - low, 1.0)
+        return {"status": "bad", "position": max(6, min(30, round(26 - distance * 18)))}
+
+    if numeric <= normal:
+        side_width = normal - low
+    else:
+        side_width = high - normal
+
+    if side_width <= 0:
+        closeness = 1.0
+    else:
+        closeness = 1 - abs(numeric - normal) / side_width
+    closeness = max(0.0, min(1.0, closeness))
+
+    if closeness >= 0.7:
+        # Good/ideal zone: the closer the patient is to the KG normal value, the fuller the bar.
+        position = 68 + (closeness - 0.7) / 0.3 * 26
+        return {"status": "ideal", "position": max(68, min(94, round(position)))}
+
+    # Normal zone: in range, but not close enough to the KG normal value to call it ideal.
+    position = 38 + closeness / 0.7 * 26
+    return {"status": "normal", "position": max(38, min(64, round(position)))}
+
+
+def _final_reference_values(marker: dict[str, Any]) -> tuple[float, float, float] | None:
+    selection = marker.get("reference_selection") or {}
+    values = selection.get("values") or {}
+    try:
+        low = float(values["minimal_value"])
+        normal = float(values["normal_value"])
+        high = float(values["maximum_value"])
+    except (KeyError, TypeError, ValueError):
+        return None
+    if high <= low:
+        return None
+    return low, normal, high
+
+
+def _final_numeric_value(marker: dict[str, Any]) -> float | None:
+    try:
+        return float(marker.get("numeric_value"))
+    except (TypeError, ValueError):
+        return None
+
+
+def _final_improvement_text(instructions: dict[str, Any]) -> str:
+    parts = []
+    for label, key in (("Food", "food"), ("Exercise", "exercises"), ("Supplements", "supplements")):
+        items = instructions.get(key)
+        if isinstance(items, list) and items:
+            parts.append(f"{label}: {' '.join(str(item) for item in items[:2])}")
+    return " ".join(parts) or "No improvement guidance is stored for this marker."
+
+
+def _final_context_text(marker: dict[str, Any]) -> str:
+    reference = _reference_label(marker)
+    sex_context = ((marker.get("knowledge") or {}).get("sex_significance") or {}).get("summary")
+    confidence = _confidence_percent(marker.get("confidence"))
+    source = _text(marker.get("source_text"), "")
+    parts = [reference, f"Extraction confidence: {confidence}%."]
+    if sex_context:
+        parts.append(str(sex_context))
+    if source:
+        parts.append(f"Source row: {source}")
+    return " ".join(parts)
+
+
+def _final_patient_context(patient: dict[str, Any]) -> str:
+    age = _text(patient.get("age"), "")
+    sex = _text(patient.get("sex"), "")
+    age_group = _text(patient.get("age_group"), "")
+    parts = []
+    if age:
+        parts.append(f"Age: {age}")
+    if sex and sex != "unknown":
+        parts.append(f"Sex: {sex.title()}")
+    if age_group:
+        parts.append(f"Group: {age_group.title()}")
+    return " | ".join(parts)
+
+
+def _empty_final_marker_card() -> str:
+    return """
+    <article class="bte-ideal-marker bte-ideal-marker--normal">
+      <div class="bte-ideal-marker-head">
+        <div class="bte-ideal-title-line">
+          <h3>No markers extracted yet</h3>
+          <span class="bte-ideal-status">Normal</span>
+        </div>
+      </div>
+    </article>
+    """
+
+
 def _empty_marker_card() -> str:
     return """
     <div class="bte-marker-empty">
@@ -463,6 +752,69 @@ def _empty_marker_card() -> str:
     """
 
 
+def _reference_label(test: dict[str, Any]) -> str:
+    lab_range = _text(test.get("lab_reference_range"), "")
+    if lab_range:
+        return f"Lab range: {lab_range}"
+    return _statistics_text(test)
+
+
+def _statistics_text(test: dict[str, Any]) -> str:
+    selection = test.get("reference_selection") or {}
+    values = selection.get("values") or {}
+    low = values.get("minimal_value")
+    normal = values.get("normal_value")
+    high = values.get("maximum_value")
+    if low is None and high is None:
+        return "No knowledge graph range available."
+    age_group = _text(selection.get("age_group"), "adult").title()
+    sex = _text(selection.get("sex"), "not_applied").replace("_", " ").title()
+    unit = _text(test.get("unit"), "")
+    return f"{age_group}, {sex}: {low} min / {normal} typical / {high} max {unit}".strip()
+
+
+def _insight_block(label: str, text: str) -> str:
+    return f"""
+    <div>
+      <span>{escape(label)}</span>
+      <p>{escape(text)}</p>
+    </div>
+    """
+
+
+def _guidance_column(label: str, items: Any) -> str:
+    if not isinstance(items, list) or not items:
+        body = "<li>No guidance stored for this marker.</li>"
+    else:
+        body = "".join(f"<li>{escape(str(item))}</li>" for item in items[:3])
+    return f"""
+    <div>
+      <strong>{escape(label)}</strong>
+      <ul>{body}</ul>
+    </div>
+    """
+
+
+def _source_links(markers: list[dict[str, Any]], sources: dict[str, str]) -> str:
+    source_ids: list[str] = []
+    for marker in markers:
+        knowledge = marker.get("knowledge") or {}
+        for source_id in knowledge.get("source_ids") or []:
+            if source_id not in source_ids:
+                source_ids.append(source_id)
+
+    links = []
+    for source_id in source_ids[:8]:
+        url = sources.get(source_id)
+        if not url:
+            continue
+        links.append(f'<li><a href="{escape(url)}" target="_blank" rel="noreferrer">{escape(source_id)}</a></li>')
+
+    if not links:
+        return "<p>No source links available for matched markers.</p>"
+    return f"<ul>{''.join(links)}</ul>"
+
+
 def _text(value: Any, fallback: str) -> str:
     if value is None:
         return fallback
@@ -818,7 +1170,9 @@ gradio-app,
 .bte-status-row,
 .bte-status-row > div,
 .bte-ideal-row,
-.bte-ideal-row > div {
+.bte-ideal-row > div,
+.bte-final-row,
+.bte-final-row > div {
   width: var(--bte-rail) !important;
   max-width: var(--bte-rail) !important;
   margin-left: auto !important;
@@ -834,7 +1188,10 @@ gradio-app,
 .bte-status-row .block,
 .bte-ideal-row .prose,
 .bte-ideal-row .html-container,
-.bte-ideal-row .block {
+.bte-ideal-row .block,
+.bte-final-row .prose,
+.bte-final-row .html-container,
+.bte-final-row .block {
   padding: 0 !important;
   margin: 0 !important;
   background: transparent !important;
@@ -1775,6 +2132,78 @@ button.bte-action *,
   color: var(--bte-muted);
 }
 
+.bte-marker-evidence {
+  display: grid;
+  align-content: start;
+  gap: 8px;
+}
+
+.bte-marker-evidence > span {
+  color: var(--bte-ink);
+  font-size: 12px;
+  font-weight: 760;
+  text-transform: uppercase;
+}
+
+.bte-marker-insights {
+  min-width: 0;
+  display: grid;
+  gap: 14px;
+}
+
+.bte-range-scale--report {
+  padding: 12px 0 4px;
+}
+
+.bte-insight-grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 10px;
+}
+
+.bte-insight-grid div {
+  min-width: 0;
+  padding-top: 10px;
+  border-top: 1px solid var(--bte-line);
+}
+
+.bte-insight-grid span,
+.bte-guidance strong {
+  display: block;
+  margin-bottom: 6px;
+  color: var(--bte-ink);
+  font-size: 12px;
+  font-weight: 760;
+  text-transform: uppercase;
+}
+
+.bte-insight-grid p {
+  margin: 0;
+  color: var(--bte-muted);
+  font-size: 14px;
+  line-height: 1.48;
+}
+
+.bte-guidance {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 10px;
+}
+
+.bte-guidance div {
+  min-width: 0;
+  padding-top: 10px;
+  border-top: 1px solid var(--bte-line);
+}
+
+.bte-guidance ul {
+  margin: 0;
+  padding-left: 18px;
+  color: var(--bte-muted);
+  font-size: 13px;
+  line-height: 1.45;
+}
+
 .bte-confidence {
   height: 8px;
   border-radius: 999px;
@@ -1815,6 +2244,39 @@ button.bte-action *,
   color: var(--bte-muted);
 }
 
+.bte-report-aside a {
+  color: var(--bte-blue);
+  overflow-wrap: anywhere;
+}
+
+.bte-patient-context {
+  display: grid;
+  gap: 8px;
+  margin: 0 0 16px;
+}
+
+.bte-patient-context div {
+  display: flex;
+  justify-content: space-between;
+  gap: 12px;
+  padding-bottom: 8px;
+  border-bottom: 1px solid var(--bte-line);
+}
+
+.bte-patient-context dt {
+  color: var(--bte-muted);
+  font-size: 12px;
+  font-weight: 760;
+  text-transform: uppercase;
+}
+
+.bte-patient-context dd {
+  margin: 0;
+  color: var(--bte-ink);
+  font-weight: 650;
+  text-align: right;
+}
+
 .bte-disclaimer {
   display: grid;
   gap: 4px;
@@ -1840,6 +2302,12 @@ button.bte-action *,
   background: transparent;
 }
 
+.bte-final-report {
+  width: var(--bte-rail) !important;
+  max-width: var(--bte-rail) !important;
+  margin: 0 auto !important;
+}
+
 .bte-ideal-hero {
   display: flex;
   align-items: center;
@@ -1920,7 +2388,11 @@ button.bte-action *,
 .bte-ideal-doc:has(#bte-filter-total:checked) .bte-ideal-stat--total,
 .bte-ideal-doc:has(#bte-filter-ideal:checked) .bte-ideal-stat--ideal,
 .bte-ideal-doc:has(#bte-filter-normal:checked) .bte-ideal-stat--normal,
-.bte-ideal-doc:has(#bte-filter-bad:checked) .bte-ideal-stat--bad {
+.bte-ideal-doc:has(#bte-filter-bad:checked) .bte-ideal-stat--bad,
+.bte-ideal-doc:has(#bte-final-filter-total:checked) .bte-ideal-stat--total,
+.bte-ideal-doc:has(#bte-final-filter-ideal:checked) .bte-ideal-stat--ideal,
+.bte-ideal-doc:has(#bte-final-filter-normal:checked) .bte-ideal-stat--normal,
+.bte-ideal-doc:has(#bte-final-filter-bad:checked) .bte-ideal-stat--bad {
   border-color: transparent;
   background:
     linear-gradient(var(--bte-stat-bg), var(--bte-stat-bg)) padding-box,
@@ -1974,7 +2446,10 @@ button.bte-action *,
 
 .bte-ideal-doc:has(#bte-filter-ideal:checked) .bte-ideal-marker:not(.bte-ideal-marker--ideal),
 .bte-ideal-doc:has(#bte-filter-normal:checked) .bte-ideal-marker:not(.bte-ideal-marker--normal),
-.bte-ideal-doc:has(#bte-filter-bad:checked) .bte-ideal-marker:not(.bte-ideal-marker--bad) {
+.bte-ideal-doc:has(#bte-filter-bad:checked) .bte-ideal-marker:not(.bte-ideal-marker--bad),
+.bte-ideal-doc:has(#bte-final-filter-ideal:checked) .bte-ideal-marker:not(.bte-ideal-marker--ideal),
+.bte-ideal-doc:has(#bte-final-filter-normal:checked) .bte-ideal-marker:not(.bte-ideal-marker--normal),
+.bte-ideal-doc:has(#bte-final-filter-bad:checked) .bte-ideal-marker:not(.bte-ideal-marker--bad) {
   display: none;
 }
 
@@ -2281,10 +2756,18 @@ button.bte-action *,
   .bte-hero-grid > :nth-child(3),
   .bte-run-status,
   .bte-report-anchor,
-  .bte-ideal-doc {
+  .bte-ideal-row {
     display: none !important;
   }
 
+  .bte-final-report {
+    display: grid !important;
+    width: calc(100vw - 88px) !important;
+    max-width: calc(100vw - 88px) !important;
+    margin-left: 0 !important;
+    margin-right: 0 !important;
+  }
+
   .bte-workflow-panel--upload,
   .bte-workflow-panel--analysis {
     min-width: 0 !important;
@@ -2406,6 +2889,11 @@ button.bte-action *,
     grid-template-columns: 1fr;
   }
 
+  .bte-insight-grid,
+  .bte-guidance {
+    grid-template-columns: 1fr;
+  }
+
   .bte-marker-value {
     text-align: left;
   }
@@ -2445,7 +2933,7 @@ with gr.Blocks(title="Blood Test Explainer") as demo:
                 <div>
                   <p class="bte-kicker">Clinical clarity from raw documents</p>
                   <h1>Blood Test Explainer</h1>
-                  <p>Upload a lab report and turn dense medical paperwork into a polished extraction report with raw markers, values, units, reference ranges, and confidence signals.</p>
+                  <p>Upload a lab report and turn dense medical paperwork into a polished health report with extracted values, age and sex context, and knowledge graph explanations.</p>
                 </div>
                 """
             )
@@ -2507,7 +2995,7 @@ with gr.Blocks(title="Blood Test Explainer") as demo:
         show_progress="hidden",
     )
 
-    with gr.Group(visible=False, elem_classes=["bte-report-panel"]) as report_panel:
+    with gr.Group(visible=False, elem_classes=["bte-report-panel", "bte-final-row"]) as report_panel:
         report = gr.HTML(empty_report_html())
 
     run_button.click(

kb/cbc_knowledge_graph.json

@@ -0,0 +1,614 @@
+{
+  "schema_version": "1.1",
+  "title": "Complete Blood Count Knowledge Graph",
+  "purpose": "Educational knowledge graph for CBC markers mentioned in the GNU Health laboratory report sample. It is intended for explanation agents, not diagnosis or treatment.",
+  "medical_disclaimer": "Reference intervals vary by laboratory method, sex, pregnancy status, altitude, acute illness, medications, and clinical context. Abnormal values should be interpreted by a qualified clinician.",
+  "age_group_definitions": {
+    "child": "1-12 years, excluding neonates/infants when a source gave separate infant intervals",
+    "teenager": "13-17 years",
+    "adult": "18-64 years",
+    "elder": "65+ years; adult CBC intervals are reused unless a source provides an elder-specific or sex-specific threshold"
+  },
+  "sex_definitions": {
+    "male": "Patient sex category as reported by the lab or patient record. Do not infer from name.",
+    "female": "Patient sex category as reported by the lab or patient record. Pregnancy, menstruation, menopause, and hormone therapy can change interpretation.",
+    "unknown": "Use when sex is absent, unclear, nonbinary, or not safely mappable to a binary lab reference interval. Prefer the lab-provided reference range and show a caution."
+  },
+  "sex_significance_policy": "Agents should extract patient sex when present and pass it through the pipeline. For markers with sex_specific_statistics_per_group_age, prefer the sex-specific interval over the age-only fallback. If sex is unknown or the patient context does not fit binary lab intervals, use the lab's own reference range first and explain that sex-specific interpretation may require clinician review.",
+  "statistics_method": "For each age group, minimal_value and maximum_value represent the lower and upper educational reference interval endpoints. normal_value is the midpoint of that interval, rounded to 2 decimals where useful. Age-only statistics are fallback ranges; sex_specific_statistics_per_group_age is preferred when present and patient sex is known.",
+  "sources": {
+    "medlineplus_cbc": "https://medlineplus.gov/lab-tests/complete-blood-count-cbc/",
+    "medlineplus_rbc": "https://medlineplus.gov/lab-tests/red-blood-cell-rbc-count/",
+    "medlineplus_differential": "https://medlineplus.gov/lab-tests/blood-differential/",
+    "medlineplus_differential_encyclopedia": "https://medlineplus.gov/ency/article/003657.htm",
+    "medlineplus_esr": "https://medlineplus.gov/lab-tests/erythrocyte-sedimentation-rate-esr/",
+    "uiowa_cbc_reference": "https://www.healthcare.uiowa.edu/path_handbook/handbook/test299.html",
+    "uiowa_pediatric_reference": "https://www.healthcare.uiowa.edu/path_handbook/appendix/heme/pediatric_normals.html",
+    "seattle_childrens_hematocrit": "https://seattlechildrenslab.testcatalog.org/show/LAB289--1",
+    "seattle_childrens_platelet": "https://seattlechildrenslab.testcatalog.org/show/LAB301-1",
+    "seattle_childrens_esr": "https://seattlechildrenslab.testcatalog.org/show/LAB322-1",
+    "uchicago_cbc_diff": "https://uchicagomedlabs.testcatalog.org/show/CBCDIFF-1",
+    "uchicago_esr_reference": "https://uchicagomedlabs.testcatalog.org/show/ESR-1",
+    "cleveland_clinic_esr": "https://my.clevelandclinic.org/health/diagnostics/17747-sed-rate-erythrocyte-sedimentation-rate-or-esr-test",
+    "nih_ods_iron": "https://ods.od.nih.gov/factsheets/Iron-HealthProfessional/",
+    "nih_ods_b12": "https://ods.od.nih.gov/factsheets/VitaminB12-HealthProfessional/",
+    "nih_ods_folate": "https://ods.od.nih.gov/factsheets/Folate-HealthProfessional/",
+    "cdc_physical_activity": "https://www.cdc.gov/physical-activity-basics/guidelines/index.html"
+  },
+  "tests": [
+    {
+      "id": "hemoglobin",
+      "display_name": "Hemoglobin",
+      "aliases": ["HGB", "Hb", "Hgb"],
+      "category": "CBC red cell marker",
+      "unit": "g/dL",
+      "description": "Hemoglobin is the iron-containing protein inside red blood cells that carries oxygen from the lungs to body tissues.",
+      "why_important": "It is a core screen for anemia, blood loss, dehydration-related concentration changes, and disorders affecting oxygen delivery.",
+      "sex_significance": {
+        "level": "high",
+        "summary": "Adult and post-pubertal male reference intervals are typically higher than female intervals. Pregnancy and menstruation can further affect interpretation.",
+        "pipeline_guidance": "If patient sex is known, prefer sex_specific_statistics_per_group_age for comparison. If sex is unknown, nonbinary, pregnancy is possible, or hormone therapy is relevant, prefer the lab-provided reference range and include a clinician-context caution."
+      },
+      "sex_specific_statistics_per_group_age": {
+        "child": {
+          "male": {"minimal_value": 10.9, "normal_value": 12.95, "maximum_value": 15.0},
+          "female": {"minimal_value": 10.9, "normal_value": 12.95, "maximum_value": 15.0},
+          "unknown": {"minimal_value": 10.9, "normal_value": 12.95, "maximum_value": 15.0}
+        },
+        "teenager": {
+          "male": {"minimal_value": 13.2, "normal_value": 15.45, "maximum_value": 17.7},
+          "female": {"minimal_value": 11.9, "normal_value": 13.7, "maximum_value": 15.5},
+          "unknown": {"minimal_value": 11.9, "normal_value": 14.35, "maximum_value": 17.7}
+        },
+        "adult": {
+          "male": {"minimal_value": 13.2, "normal_value": 15.45, "maximum_value": 17.7},
+          "female": {"minimal_value": 11.9, "normal_value": 13.7, "maximum_value": 15.5},
+          "unknown": {"minimal_value": 11.9, "normal_value": 14.35, "maximum_value": 17.7}
+        },
+        "elder": {
+          "male": {"minimal_value": 13.2, "normal_value": 15.45, "maximum_value": 17.7},
+          "female": {"minimal_value": 11.9, "normal_value": 13.7, "maximum_value": 15.5},
+          "unknown": {"minimal_value": 11.9, "normal_value": 14.35, "maximum_value": 17.7}
+        }
+      },
+      "instructions_to_improve": {
+        "food": ["If low, emphasize iron-rich foods such as lean meat, fish, poultry, legumes, tofu, spinach, and iron-fortified grains.", "Pair plant iron with vitamin C foods such as citrus, berries, peppers, or tomatoes to improve absorption.", "Include folate and vitamin B12 sources such as leafy greens, beans, eggs, dairy, fish, and fortified foods."],
+        "exercises": ["Use moderate aerobic activity and strength training as tolerated to support cardiovascular fitness.", "Avoid unusually intense training until unexplained anemia, shortness of breath, dizziness, or fatigue has been evaluated."],
+        "supplements": ["Discuss iron, vitamin B12, or folate testing and supplementation with a clinician before starting.", "Avoid iron supplements unless deficiency or clinical need is confirmed, because excess iron can be harmful."]
+      },
+      "statistics_per_group_age": {
+        "child": {"minimal_value": 10.9, "normal_value": 12.95, "maximum_value": 15.0},
+        "teenager": {"minimal_value": 11.9, "normal_value": 14.35, "maximum_value": 17.7},
+        "adult": {"minimal_value": 11.9, "normal_value": 14.45, "maximum_value": 17.7},
+        "elder": {"minimal_value": 11.9, "normal_value": 14.45, "maximum_value": 17.7}
+      },
+      "related_tests": ["rbc", "hct", "mcv", "mch", "mchc", "rdw_cv", "rdw_sd"],
+      "source_ids": ["medlineplus_cbc", "uiowa_cbc_reference", "uiowa_pediatric_reference", "nih_ods_iron", "nih_ods_b12", "nih_ods_folate"]
+    },
+    {
+      "id": "rbc",
+      "display_name": "Red Blood Cell Count",
+      "aliases": ["RBC", "Erythrocyte count", "Red cell count"],
+      "category": "CBC red cell marker",
+      "unit": "10^6/uL",
+      "description": "RBC count measures the number of red blood cells in a volume of blood.",
+      "why_important": "Red blood cells carry hemoglobin and oxygen; low or high counts can point toward anemia, blood loss, dehydration, lung or heart disease, marrow disorders, or other conditions.",
+      "sex_significance": {
+        "level": "high",
+        "summary": "Adult and adolescent male RBC intervals are usually higher than female intervals.",
+        "pipeline_guidance": "Use sex_specific_statistics_per_group_age when sex is known. For unknown or context-sensitive sex data, compare against the lab-provided range and avoid overcalling status from a broad fallback interval."
+      },
+      "sex_specific_statistics_per_group_age": {
+        "child": {
+          "male": {"minimal_value": 3.8, "normal_value": 4.6, "maximum_value": 5.5},
+          "female": {"minimal_value": 3.8, "normal_value": 4.6, "maximum_value": 5.5},
+          "unknown": {"minimal_value": 3.8, "normal_value": 4.6, "maximum_value": 5.5}
+        },
+        "teenager": {
+          "male": {"minimal_value": 4.3, "normal_value": 4.95, "maximum_value": 5.6},
+          "female": {"minimal_value": 3.9, "normal_value": 4.55, "maximum_value": 5.1},
+          "unknown": {"minimal_value": 3.9, "normal_value": 4.75, "maximum_value": 5.6}
+        },
+        "adult": {
+          "male": {"minimal_value": 4.5, "normal_value": 5.35, "maximum_value": 6.2},
+          "female": {"minimal_value": 4.0, "normal_value": 4.6, "maximum_value": 5.2},
+          "unknown": {"minimal_value": 4.0, "normal_value": 5.1, "maximum_value": 6.2}
+        },
+        "elder": {
+          "male": {"minimal_value": 4.5, "normal_value": 5.35, "maximum_value": 6.2},
+          "female": {"minimal_value": 4.0, "normal_value": 4.6, "maximum_value": 5.2},
+          "unknown": {"minimal_value": 4.0, "normal_value": 5.1, "maximum_value": 6.2}
+        }
+      },
+      "instructions_to_improve": {
+        "food": ["Support red blood cell production with iron, protein, folate, and vitamin B12 containing foods.", "Hydrate regularly; dehydration can concentrate blood counts and make RBC appear higher.", "Limit heavy alcohol intake because it can interfere with nutrition and marrow function."],
+        "exercises": ["Maintain regular aerobic activity and resistance training if cleared for exercise.", "If RBC is high with headaches, dizziness, sleep apnea symptoms, or smoking history, seek medical evaluation rather than trying to lower it with exercise alone."],
+        "supplements": ["Use iron, B12, or folate only when deficiency is suspected or confirmed.", "Do not use performance-enhancing drugs or unsupervised erythropoietin-like products."]
+      },
+      "statistics_per_group_age": {
+        "child": {"minimal_value": 3.8, "normal_value": 4.6, "maximum_value": 5.5},
+        "teenager": {"minimal_value": 3.9, "normal_value": 4.75, "maximum_value": 5.6},
+        "adult": {"minimal_value": 4.0, "normal_value": 5.1, "maximum_value": 6.2},
+        "elder": {"minimal_value": 4.0, "normal_value": 5.1, "maximum_value": 6.2}
+      },
+      "related_tests": ["hemoglobin", "hct", "mcv"],
+      "source_ids": ["medlineplus_rbc", "uiowa_cbc_reference"]
+    },
+    {
+      "id": "hct",
+      "display_name": "Hematocrit",
+      "aliases": ["HCT", "PCV", "Packed cell volume"],
+      "category": "CBC red cell marker",
+      "unit": "%",
+      "description": "Hematocrit is the percentage of whole blood volume made up of red blood cells.",
+      "why_important": "It helps evaluate anemia, blood loss, dehydration, and conditions that change red cell concentration.",
+      "sex_significance": {
+        "level": "high",
+        "summary": "Male hematocrit reference intervals are typically higher than female intervals after puberty. Pregnancy and menstruation can affect interpretation.",
+        "pipeline_guidance": "Use sex_specific_statistics_per_group_age when sex is known. If sex is unknown or pregnancy/hormone context is relevant, show the lab reference range as primary and mark the KG range as educational."
+      },
+      "sex_specific_statistics_per_group_age": {
+        "child": {
+          "male": {"minimal_value": 31, "normal_value": 37.5, "maximum_value": 44},
+          "female": {"minimal_value": 31, "normal_value": 37.5, "maximum_value": 44},
+          "unknown": {"minimal_value": 31, "normal_value": 37.5, "maximum_value": 44}
+        },
+        "teenager": {
+          "male": {"minimal_value": 37, "normal_value": 43, "maximum_value": 49},
+          "female": {"minimal_value": 36, "normal_value": 41, "maximum_value": 46},
+          "unknown": {"minimal_value": 36, "normal_value": 42.5, "maximum_value": 49}
+        },
+        "adult": {
+          "male": {"minimal_value": 40, "normal_value": 46, "maximum_value": 52},
+          "female": {"minimal_value": 35, "normal_value": 41, "maximum_value": 47},
+          "unknown": {"minimal_value": 35, "normal_value": 43.5, "maximum_value": 52}
+        },
+        "elder": {
+          "male": {"minimal_value": 40, "normal_value": 46, "maximum_value": 52},
+          "female": {"minimal_value": 35, "normal_value": 41, "maximum_value": 47},
+          "unknown": {"minimal_value": 35, "normal_value": 43.5, "maximum_value": 52}
+        }
+      },
+      "instructions_to_improve": {
+        "food": ["For low values, support red cell production with iron, B12, folate, protein, and overall adequate calories.", "For high values, maintain hydration and avoid smoking exposure when possible.", "Ask a clinician about causes before making major diet changes."],
+        "exercises": ["Follow general activity guidelines if well; conditioning supports oxygen use but does not replace evaluation for anemia.", "Pause strenuous activity and seek care for chest pain, fainting, severe shortness of breath, or marked fatigue."],
+        "supplements": ["Discuss iron/B12/folate supplementation only when deficiency or risk is present.", "Avoid unsupervised iron if hematocrit is high."]
+      },
+      "statistics_per_group_age": {
+        "child": {"minimal_value": 31, "normal_value": 37.5, "maximum_value": 44},
+        "teenager": {"minimal_value": 34, "normal_value": 41, "maximum_value": 48},
+        "adult": {"minimal_value": 35, "normal_value": 43.5, "maximum_value": 52},
+        "elder": {"minimal_value": 35, "normal_value": 43.5, "maximum_value": 52}
+      },
+      "related_tests": ["hemoglobin", "rbc"],
+      "source_ids": ["medlineplus_cbc", "uiowa_cbc_reference", "uiowa_pediatric_reference", "seattle_childrens_hematocrit"]
+    },
+    {
+      "id": "mcv",
+      "display_name": "Mean Corpuscular Volume",
+      "aliases": ["MCV"],
+      "category": "CBC red cell index",
+      "unit": "fL",
+      "description": "MCV measures the average size of red blood cells.",
+      "why_important": "Small cells may suggest iron-related or thalassemia patterns; large cells may suggest B12, folate, alcohol, liver, thyroid, medication, or marrow-related patterns.",
+      "sex_significance": {
+        "level": "low",
+        "summary": "MCV is usually interpreted with age and lab method rather than sex. Sex still matters indirectly because hemoglobin, RBC, and hematocrit ranges differ by sex.",
+        "pipeline_guidance": "Use the age-group interval unless the report provides a sex-specific lab range. Keep nearby red-cell markers sex-aware."
+      },
+      "instructions_to_improve": {
+        "food": ["If low, ensure adequate iron intake and pair plant iron with vitamin C.", "If high, ensure adequate B12 and folate intake from animal foods, fortified foods, leafy greens, and legumes.", "Reduce heavy alcohol intake if relevant."],
+        "exercises": ["Exercise does not directly normalize MCV, but regular activity supports overall metabolic health.", "Avoid overtraining if anemia symptoms are present."],
+        "supplements": ["Discuss iron studies, B12, folate, thyroid, and liver evaluation before supplementing.", "Use B12 or folate supplements when dietary intake, absorption risk, or testing supports the need."]
+      },
+      "statistics_per_group_age": {
+        "child": {"minimal_value": 75, "normal_value": 82.5, "maximum_value": 90},
+        "teenager": {"minimal_value": 79, "normal_value": 87, "maximum_value": 95},
+        "adult": {"minimal_value": 82, "normal_value": 90.5, "maximum_value": 99},
+        "elder": {"minimal_value": 82, "normal_value": 90.5, "maximum_value": 99}
+      },
+      "related_tests": ["hemoglobin", "mch", "mchc", "rdw_cv", "rdw_sd"],
+      "source_ids": ["medlineplus_cbc", "uiowa_cbc_reference", "nih_ods_iron", "nih_ods_b12", "nih_ods_folate"]
+    },
+    {
+      "id": "mch",
+      "display_name": "Mean Corpuscular Hemoglobin",
+      "aliases": ["MCH"],
+      "category": "CBC red cell index",
+      "unit": "pg",
+      "description": "MCH estimates the average amount of hemoglobin in each red blood cell.",
+      "why_important": "It helps classify anemia patterns and is interpreted with hemoglobin, MCV, MCHC, and RDW.",
+      "sex_significance": {
+        "level": "low",
+        "summary": "MCH is generally not separated by sex in common CBC reference tables, but interpretation depends on sex-aware hemoglobin and RBC context.",
+        "pipeline_guidance": "Use the age-group interval unless the lab report includes a sex-specific range."
+      },
+      "instructions_to_improve": {
+        "food": ["Support hemoglobin production with iron-rich foods, protein, B12, and folate.", "Pair plant iron with vitamin C and avoid taking tea or coffee with iron-rich meals if iron deficiency is a concern.", "Maintain balanced meals rather than focusing on one nutrient only."],
+        "exercises": ["Use gentle-to-moderate activity if anemia symptoms are mild and cleared by a clinician.", "Delay intense endurance training when unexplained low red-cell indices are present."],
+        "supplements": ["Discuss iron, B12, and folate supplementation based on lab confirmation.", "Avoid stacking multiple blood-building supplements without clinician guidance."]
+      },
+      "statistics_per_group_age": {
+        "child": {"minimal_value": 23, "normal_value": 29, "maximum_value": 35},
+        "teenager": {"minimal_value": 25, "normal_value": 30, "maximum_value": 35},
+        "adult": {"minimal_value": 25, "normal_value": 30, "maximum_value": 35},
+        "elder": {"minimal_value": 25, "normal_value": 30, "maximum_value": 35}
+      },
+      "related_tests": ["mcv", "mchc", "hemoglobin"],
+      "source_ids": ["uiowa_cbc_reference", "uiowa_pediatric_reference", "nih_ods_iron"]
+    },
+    {
+      "id": "mchc",
+      "display_name": "Mean Corpuscular Hemoglobin Concentration",
+      "aliases": ["MCHC"],
+      "category": "CBC red cell index",
+      "unit": "g/dL",
+      "description": "MCHC estimates the concentration of hemoglobin within red blood cells.",
+      "why_important": "It helps characterize red-cell color/concentration patterns and can support anemia workups.",
+      "sex_significance": {
+        "level": "low",
+        "summary": "MCHC is typically interpreted using a shared reference interval across male and female patients.",
+        "pipeline_guidance": "Use the age-group interval unless the lab report provides a sex-specific range."
+      },
+      "instructions_to_improve": {
+        "food": ["For low values, focus on iron adequacy plus B12, folate, protein, and vitamin C-supported absorption.", "For high values, do not try to self-correct with diet; confirm with repeat testing and clinical review.", "Hydration and balanced nutrition support reliable results."],
+        "exercises": ["Exercise does not directly change MCHC; stay active within symptom limits.", "Seek care before strenuous exercise if anemia symptoms are significant."],
+        "supplements": ["Use iron only when iron deficiency is likely or confirmed.", "Discuss persistent abnormal MCHC with a clinician because it can reflect lab artifacts or specific red-cell disorders."]
+      },
+      "statistics_per_group_age": {
+        "child": {"minimal_value": 32, "normal_value": 34, "maximum_value": 36},
+        "teenager": {"minimal_value": 32, "normal_value": 34, "maximum_value": 36},
+        "adult": {"minimal_value": 32, "normal_value": 34, "maximum_value": 36},
+        "elder": {"minimal_value": 32, "normal_value": 34, "maximum_value": 36}
+      },
+      "related_tests": ["mch", "mcv", "hemoglobin"],
+      "source_ids": ["uiowa_cbc_reference", "uiowa_pediatric_reference"]
+    },
+    {
+      "id": "rdw_cv",
+      "display_name": "Red Cell Distribution Width - CV",
+      "aliases": ["RDW-CV", "RDWCV", "RDW"],
+      "category": "CBC red cell index",
+      "unit": "%",
+      "description": "RDW-CV describes variation in red blood cell size as a coefficient of variation.",
+      "why_important": "Higher RDW can help identify mixed red-cell populations and may support evaluation for iron, B12, folate, recent bleeding, or recovery from anemia.",
+      "sex_significance": {
+        "level": "low",
+        "summary": "RDW-CV is usually interpreted without a major sex split, but the causes of abnormal RDW can overlap with sex-relevant conditions such as menstruation, pregnancy, and iron deficiency.",
+        "pipeline_guidance": "Use age-group statistics as fallback and interpret alongside sex-aware hemoglobin, RBC, hematocrit, and iron-related context."
+      },
+      "instructions_to_improve": {
+        "food": ["Support steady red-cell production with iron, B12, folate, protein, and adequate calories.", "Include a mix of leafy greens, legumes, fortified grains, seafood, eggs, dairy, and lean meats as appropriate.", "Address restrictive diets with clinician or dietitian support."],
+        "exercises": ["Regular activity supports general health but does not directly normalize RDW.", "Avoid overtraining if iron deficiency or anemia is suspected."],
+        "supplements": ["Consider supplements only after identifying the relevant deficiency.", "Ask about iron studies, ferritin, B12, folate, and reticulocyte count when RDW is abnormal."]
+      },
+      "statistics_per_group_age": {
+        "child": {"minimal_value": 9.0, "normal_value": 11.75, "maximum_value": 14.5},
+        "teenager": {"minimal_value": 9.0, "normal_value": 11.75, "maximum_value": 14.5},
+        "adult": {"minimal_value": 9.0, "normal_value": 11.75, "maximum_value": 14.5},
+        "elder": {"minimal_value": 9.0, "normal_value": 11.75, "maximum_value": 14.5}
+      },
+      "related_tests": ["mcv", "hemoglobin", "rdw_sd"],
+      "source_ids": ["uiowa_cbc_reference", "nih_ods_iron", "nih_ods_b12", "nih_ods_folate"]
+    },
+    {
+      "id": "rdw_sd",
+      "display_name": "Red Cell Distribution Width - SD",
+      "aliases": ["RDW-SD", "RDWSD"],
+      "category": "CBC red cell index",
+      "unit": "fL",
+      "description": "RDW-SD measures the width of the red-cell size distribution in femtoliters.",
+      "why_important": "It complements RDW-CV and MCV by showing how varied red-cell sizes are.",
+      "sex_significance": {
+        "level": "low",
+        "summary": "RDW-SD is generally not interpreted with separate male and female thresholds, but abnormal results should be considered with sex-aware red-cell markers.",
+        "pipeline_guidance": "Use age-group statistics as fallback and defer to the lab reference range if it is sex-specific."
+      },
+      "instructions_to_improve": {
+        "food": ["Follow the same red-cell nutrition pattern used for RDW-CV: iron, B12, folate, protein, and balanced calories.", "Correcting the cause of abnormal red-cell production is more important than targeting RDW-SD directly.", "Maintain hydration before routine blood draws unless instructed otherwise."],
+        "exercises": ["Regular moderate activity is reasonable when symptoms allow.", "Avoid intense training until unexplained anemia, dizziness, or shortness of breath is reviewed."],
+        "supplements": ["Supplement only for documented or likely deficiency.", "Discuss persistent abnormalities with a clinician, especially when hemoglobin or MCV is also abnormal."]
+      },
+      "statistics_per_group_age": {
+        "child": {"minimal_value": 35.1, "normal_value": 40.75, "maximum_value": 46.3},
+        "teenager": {"minimal_value": 35.1, "normal_value": 40.75, "maximum_value": 46.3},
+        "adult": {"minimal_value": 35.1, "normal_value": 40.75, "maximum_value": 46.3},
+        "elder": {"minimal_value": 35.1, "normal_value": 40.75, "maximum_value": 46.3}
+      },
+      "related_tests": ["mcv", "rdw_cv", "hemoglobin"],
+      "source_ids": ["uiowa_cbc_reference"]
+    },
+    {
+      "id": "wbc",
+      "display_name": "White Blood Cell Count",
+      "aliases": ["WBC", "Leukocyte count", "White cell count"],
+      "category": "CBC white cell marker",
+      "unit": "10^3/uL",
+      "description": "WBC count measures the total number of white blood cells in blood.",
+      "why_important": "White blood cells are central to immune defense; high or low counts can reflect infection, inflammation, medication effects, immune disorders, marrow conditions, or treatment effects.",
+      "sex_significance": {
+        "level": "low",
+        "summary": "Common adult WBC reference intervals are often the same for male and female patients. Pregnancy and some medications can change interpretation.",
+        "pipeline_guidance": "Use the age-group interval unless the lab report gives a sex- or pregnancy-specific range."
+      },
+      "instructions_to_improve": {
+        "food": ["There is no food that reliably corrects WBC count by itself; prioritize adequate calories, protein, fruits, vegetables, and hydration.", "Food safety matters if WBC is very low or immune suppression is present; ask a clinician about precautions.", "Limit heavy alcohol intake because it may impair immune and marrow function."],
+        "exercises": ["Follow general activity guidelines when well; rest during fever or acute infection.", "Avoid strenuous exercise during significant illness or very abnormal counts until medically reviewed."],
+        "supplements": ["Do not use immune-boosting supplements as a substitute for evaluation.", "Review medications and supplements with a clinician if WBC is abnormal."]
+      },
+      "statistics_per_group_age": {
+        "child": {"minimal_value": 5.5, "normal_value": 11.0, "maximum_value": 17.0},
+        "teenager": {"minimal_value": 4.5, "normal_value": 8.25, "maximum_value": 11.0},
+        "adult": {"minimal_value": 3.7, "normal_value": 7.6, "maximum_value": 10.5},
+        "elder": {"minimal_value": 3.7, "normal_value": 7.6, "maximum_value": 10.5}
+      },
+      "related_tests": ["neu_percent", "lym_percent", "mon_percent", "eos_percent", "bas_percent", "lym_absolute", "gra_absolute"],
+      "source_ids": ["medlineplus_cbc", "medlineplus_differential", "uiowa_cbc_reference", "uiowa_pediatric_reference"]
+    },
+    {
+      "id": "neu_percent",
+      "display_name": "Neutrophils Percent",
+      "aliases": ["NEU%", "Neutrophil %", "Neutrophils"],
+      "category": "CBC differential",
+      "unit": "%",
+      "description": "Neutrophil percentage is the share of white blood cells that are neutrophils, the most common WBC type and a major defense against infection.",
+      "why_important": "It helps interpret infection, inflammation, stress responses, medication effects, and marrow function, especially when paired with absolute neutrophil count.",
+      "sex_significance": {
+        "level": "low",
+        "summary": "Neutrophil percentage is usually interpreted without separate male and female ranges. Pregnancy, acute stress, and medications can affect values.",
+        "pipeline_guidance": "Use the age-group interval and prioritize the lab-provided range if pregnancy or other sex-specific context is documented."
+      },
+      "instructions_to_improve": {
+        "food": ["Support immune health with adequate protein, fruits, vegetables, whole grains, and hydration.", "There is no diet that directly normalizes neutrophil percentage; treat the cause.", "Practice food safety if a clinician says neutrophils are dangerously low."],
+        "exercises": ["Rest during acute infection or fever.", "Resume moderate activity gradually after illness; intense exercise can transiently shift white-cell patterns."],
+        "supplements": ["Avoid self-treating abnormal neutrophils with supplements.", "Discuss medication effects, infections, and need for repeat CBC or absolute neutrophil count with a clinician."]
+      },
+      "statistics_per_group_age": {
+        "child": {"minimal_value": 40, "normal_value": 50, "maximum_value": 60},
+        "teenager": {"minimal_value": 40, "normal_value": 50, "maximum_value": 60},
+        "adult": {"minimal_value": 40, "normal_value": 50, "maximum_value": 60},
+        "elder": {"minimal_value": 40, "normal_value": 50, "maximum_value": 60}
+      },
+      "related_tests": ["wbc", "gra_absolute"],
+      "source_ids": ["medlineplus_differential", "medlineplus_differential_encyclopedia"]
+    },
+    {
+      "id": "lym_percent",
+      "display_name": "Lymphocytes Percent",
+      "aliases": ["LYM%", "Lymphocyte %", "Lymphocytes"],
+      "category": "CBC differential",
+      "unit": "%",
+      "description": "Lymphocyte percentage is the share of white blood cells that are lymphocytes, including B cells and T cells.",
+      "why_important": "It helps evaluate immune patterns such as viral infections, chronic inflammation, immune suppression, and some blood disorders.",
+      "sex_significance": {
+        "level": "low",
+        "summary": "Lymphocyte percentage is generally interpreted with shared reference intervals across sex categories.",
+        "pipeline_guidance": "Use the age-group interval unless the source report provides a sex-specific or pregnancy-specific range."
+      },
+      "instructions_to_improve": {
+        "food": ["Maintain adequate protein, micronutrients, and calories to support immune cell production.", "Use a varied dietary pattern rather than targeting lymphocyte percentage directly.", "Seek evaluation for persistent abnormal values instead of relying on diet alone."],
+        "exercises": ["Moderate regular activity supports immune resilience.", "Avoid heavy training during acute illness or unexplained low counts."],
+        "supplements": ["Do not use supplements to force lymphocyte changes.", "Discuss abnormal lymphocyte percentage with a clinician, especially if absolute lymphocyte count is also abnormal."]
+      },
+      "statistics_per_group_age": {
+        "child": {"minimal_value": 20, "normal_value": 30, "maximum_value": 40},
+        "teenager": {"minimal_value": 20, "normal_value": 30, "maximum_value": 40},
+        "adult": {"minimal_value": 20, "normal_value": 30, "maximum_value": 40},
+        "elder": {"minimal_value": 20, "normal_value": 30, "maximum_value": 40}
+      },
+      "related_tests": ["wbc", "lym_absolute"],
+      "source_ids": ["medlineplus_differential", "medlineplus_differential_encyclopedia"]
+    },
+    {
+      "id": "mon_percent",
+      "display_name": "Monocytes Percent",
+      "aliases": ["MON%", "Monocyte %", "Monocytes"],
+      "category": "CBC differential",
+      "unit": "%",
+      "description": "Monocyte percentage is the share of white blood cells that are monocytes, immune cells involved in clearing germs and dead cells and coordinating immune response.",
+      "why_important": "It can support evaluation of infections, chronic inflammation, recovery from infection, and some blood or marrow disorders.",
+      "sex_significance": {
+        "level": "low",
+        "summary": "Monocyte percentage is usually not split by sex in routine CBC differential interpretation.",
+        "pipeline_guidance": "Use the age-group interval unless the lab report gives a sex-specific range."
+      },
+      "instructions_to_improve": {
+        "food": ["Eat enough protein and a varied diet to support immune function.", "No specific food reliably lowers or raises monocyte percentage.", "Persistent abnormalities should prompt review for infection, inflammation, medications, or other causes."],
+        "exercises": ["Use regular moderate exercise for general immune and metabolic health.", "Rest when acutely ill or febrile."],
+        "supplements": ["Avoid immune supplements as a replacement for medical evaluation.", "Review supplement and medication use if monocytes are persistently abnormal."]
+      },
+      "statistics_per_group_age": {
+        "child": {"minimal_value": 2, "normal_value": 5, "maximum_value": 8},
+        "teenager": {"minimal_value": 2, "normal_value": 5, "maximum_value": 8},
+        "adult": {"minimal_value": 2, "normal_value": 5, "maximum_value": 8},
+        "elder": {"minimal_value": 2, "normal_value": 5, "maximum_value": 8}
+      },
+      "related_tests": ["wbc"],
+      "source_ids": ["medlineplus_differential", "medlineplus_differential_encyclopedia"]
+    },
+    {
+      "id": "eos_percent",
+      "display_name": "Eosinophils Percent",
+      "aliases": ["EOS%", "Eosinophil %", "Eosinophils"],
+      "category": "CBC differential",
+      "unit": "%",
+      "description": "Eosinophil percentage is the share of white blood cells that are eosinophils, cells involved in allergies, asthma-related inflammation, and parasite defense.",
+      "why_important": "It can point toward allergic disease, asthma activity, drug reactions, parasitic infection, or inflammatory conditions when interpreted with symptoms.",
+      "sex_significance": {
+        "level": "low",
+        "summary": "Eosinophil percentage is typically interpreted without separate male and female thresholds.",
+        "pipeline_guidance": "Use the age-group interval unless the report provides a sex-specific range."
+      },
+      "instructions_to_improve": {
+        "food": ["No food directly normalizes eosinophils; identify allergies or triggers when clinically relevant.", "Maintain an anti-inflammatory dietary pattern with fruits, vegetables, whole grains, and adequate protein.", "Avoid foods only when a true allergy or clinician-guided elimination plan exists."],
+        "exercises": ["Exercise according to tolerance; people with asthma symptoms should follow their asthma action plan.", "Avoid exercising through wheezing, severe allergy symptoms, or acute illness."],
+        "supplements": ["Do not self-treat elevated eosinophils with supplements.", "Discuss allergy, asthma, parasite exposure, and medication review with a clinician."]
+      },
+      "statistics_per_group_age": {
+        "child": {"minimal_value": 1, "normal_value": 2.5, "maximum_value": 4},
+        "teenager": {"minimal_value": 1, "normal_value": 2.5, "maximum_value": 4},
+        "adult": {"minimal_value": 1, "normal_value": 2.5, "maximum_value": 4},
+        "elder": {"minimal_value": 1, "normal_value": 2.5, "maximum_value": 4}
+      },
+      "related_tests": ["wbc", "bas_percent"],
+      "source_ids": ["medlineplus_differential", "medlineplus_differential_encyclopedia"]
+    },
+    {
+      "id": "bas_percent",
+      "display_name": "Basophils Percent",
+      "aliases": ["BAS%", "Basophil %", "Basophils"],
+      "category": "CBC differential",
+      "unit": "%",
+      "description": "Basophil percentage is the share of white blood cells that are basophils, cells that release mediators during allergic and asthma-related reactions.",
+      "why_important": "Basophils are usually a small fraction of WBCs; persistent elevation can be relevant in allergy, inflammation, or some marrow disorders.",
+      "sex_significance": {
+        "level": "low",
+        "summary": "Basophil percentage is typically interpreted without separate male and female thresholds.",
+        "pipeline_guidance": "Use the age-group interval unless the lab report provides a sex-specific range."
+      },
+      "instructions_to_improve": {
+        "food": ["No diet directly targets basophils.", "If allergies are relevant, avoid confirmed triggers and maintain balanced nutrition.", "Seek medical review for persistent elevation rather than self-treating."],
+        "exercises": ["Exercise as tolerated; avoid exposure-triggered activity if asthma or allergic symptoms are active.", "Rest during acute allergic or inflammatory episodes if symptoms are significant."],
+        "supplements": ["Avoid supplement-only management for abnormal basophils.", "Review medications, allergy history, and repeat testing with a clinician when needed."]
+      },
+      "statistics_per_group_age": {
+        "child": {"minimal_value": 0.5, "normal_value": 0.75, "maximum_value": 1},
+        "teenager": {"minimal_value": 0.5, "normal_value": 0.75, "maximum_value": 1},
+        "adult": {"minimal_value": 0.5, "normal_value": 0.75, "maximum_value": 1},
+        "elder": {"minimal_value": 0.5, "normal_value": 0.75, "maximum_value": 1}
+      },
+      "related_tests": ["wbc", "eos_percent"],
+      "source_ids": ["medlineplus_differential", "medlineplus_differential_encyclopedia"]
+    },
+    {
+      "id": "lym_absolute",
+      "display_name": "Absolute Lymphocyte Count",
+      "aliases": ["LYM#", "Lymphocyte #", "Absolute lymphocytes", "ALC"],
+      "category": "CBC differential absolute count",
+      "unit": "10^3/uL",
+      "description": "Absolute lymphocyte count is the number of lymphocytes in a volume of blood.",
+      "why_important": "It is often more clinically useful than lymphocyte percentage because percentages can shift when other WBC types rise or fall.",
+      "sex_significance": {
+        "level": "low",
+        "summary": "Absolute lymphocyte count is generally interpreted with shared male and female reference intervals.",
+        "pipeline_guidance": "Use the age-group interval unless the report gives a sex-specific range."
+      },
+      "instructions_to_improve": {
+        "food": ["Support immune cell production with adequate calories, protein, and micronutrient-rich foods.", "Food cannot reliably correct abnormal absolute lymphocytes by itself.", "If immunosuppressed, ask about food safety guidance."],
+        "exercises": ["Use moderate regular activity when well.", "Avoid intense exercise during acute infection, fever, or severe fatigue."],
+        "supplements": ["Do not use immune supplements to self-correct lymphocyte count.", "Discuss persistent low or high ALC with a clinician, especially with infections, weight loss, night sweats, or medication changes."]
+      },
+      "statistics_per_group_age": {
+        "child": {"minimal_value": 2.0, "normal_value": 5.75, "maximum_value": 9.5},
+        "teenager": {"minimal_value": 1.25, "normal_value": 3.63, "maximum_value": 7.0},
+        "adult": {"minimal_value": 0.875, "normal_value": 2.19, "maximum_value": 3.3},
+        "elder": {"minimal_value": 0.875, "normal_value": 2.19, "maximum_value": 3.3}
+      },
+      "related_tests": ["lym_percent", "wbc"],
+      "source_ids": ["uiowa_pediatric_reference", "uchicago_cbc_diff", "medlineplus_differential"]
+    },
+    {
+      "id": "gra_absolute",
+      "display_name": "Absolute Granulocyte Count",
+      "aliases": ["GRA#", "Granulocyte #", "Absolute granulocytes", "ANC when neutrophil-dominant"],
+      "category": "CBC differential absolute count",
+      "unit": "10^3/uL",
+      "description": "GRA# is a lab-reported absolute granulocyte count. Granulocytes include neutrophils, eosinophils, and basophils; in many CBC reports this value is mainly driven by neutrophils.",
+      "why_important": "It helps summarize infection-fighting granulocytes and may approximate neutrophil burden, but exact meaning depends on the analyzer and lab report.",
+      "sex_significance": {
+        "level": "low",
+        "summary": "Absolute granulocyte or neutrophil-dominant counts are usually interpreted without separate male and female thresholds. Pregnancy and acute stress can affect granulocyte counts.",
+        "pipeline_guidance": "Use the age-group interval and lab-provided reference range; do not infer sex-specific status unless the source range provides it."
+      },
+      "instructions_to_improve": {
+        "food": ["No food directly normalizes granulocyte count; support immune health with balanced nutrition and adequate protein.", "If counts are very low, ask about infection prevention and food safety precautions.", "Hydration and rest during illness can support recovery but do not replace evaluation."],
+        "exercises": ["Rest during fever or acute infection.", "Resume regular moderate activity after recovery and medical clearance if counts are significantly abnormal."],
+        "supplements": ["Avoid self-treatment with immune supplements.", "Ask whether the lab means granulocytes broadly or absolute neutrophil count, and whether repeat CBC/differential is needed."]
+      },
+      "statistics_per_group_age": {
+        "child": {"minimal_value": 1.5, "normal_value": 5.0, "maximum_value": 8.5},
+        "teenager": {"minimal_value": 1.7, "normal_value": 4.6, "maximum_value": 7.5},
+        "adult": {"minimal_value": 1.12, "normal_value": 3.36, "maximum_value": 6.72},
+        "elder": {"minimal_value": 1.12, "normal_value": 3.36, "maximum_value": 6.72}
+      },
+      "related_tests": ["neu_percent", "wbc", "eos_percent", "bas_percent"],
+      "source_ids": ["uiowa_pediatric_reference", "uchicago_cbc_diff", "medlineplus_differential"]
+    },
+    {
+      "id": "plt",
+      "display_name": "Platelet Count",
+      "aliases": ["PLT", "Platelets", "Thrombocytes"],
+      "category": "CBC platelet marker",
+      "unit": "10^3/uL",
+      "description": "Platelet count measures small blood cell fragments that help form clots and stop bleeding.",
+      "why_important": "Low platelets can increase bleeding risk; high platelets can occur with inflammation, iron deficiency, recovery from bleeding, or marrow disorders and may affect clotting risk.",
+      "sex_significance": {
+        "level": "low",
+        "summary": "Many adult CBC references use the same platelet interval for male and female patients. Pregnancy, menstruation-related iron deficiency, inflammation, and medications can affect interpretation.",
+        "pipeline_guidance": "Use the age-group interval unless the lab report provides a sex- or pregnancy-specific range. Surface pregnancy and bleeding-risk caveats when relevant."
+      },
+      "instructions_to_improve": {
+        "food": ["Eat a balanced pattern with adequate protein, iron, folate, and B12 to support marrow production.", "If platelets are high with low iron markers, iron-rich foods may matter, but the cause should be confirmed.", "Avoid heavy alcohol intake because it can lower platelet production."],
+        "exercises": ["If platelets are very low, avoid contact sports or high-impact activities until cleared.", "Use regular moderate activity when platelet count and symptoms allow."],
+        "supplements": ["Avoid aspirin-like or blood-thinning supplements unless clinician-approved, especially with low platelets or bleeding symptoms.", "Discuss iron, B12, or folate only when deficiency is suspected or confirmed."]
+      },
+      "statistics_per_group_age": {
+        "child": {"minimal_value": 155, "normal_value": 342.5, "maximum_value": 500},
+        "teenager": {"minimal_value": 140, "normal_value": 270, "maximum_value": 400},
+        "adult": {"minimal_value": 150, "normal_value": 275, "maximum_value": 400},
+        "elder": {"minimal_value": 150, "normal_value": 275, "maximum_value": 400}
+      },
+      "related_tests": ["wbc", "hemoglobin"],
+      "source_ids": ["medlineplus_cbc", "uiowa_cbc_reference", "seattle_childrens_platelet", "nih_ods_iron", "nih_ods_b12", "nih_ods_folate"]
+    },
+    {
+      "id": "esr",
+      "display_name": "Erythrocyte Sedimentation Rate",
+      "aliases": ["ESR", "Sed rate", "Westergren ESR"],
+      "category": "Inflammation marker",
+      "unit": "mm/hr",
+      "description": "ESR measures how quickly red blood cells settle in a tube over one hour.",
+      "why_important": "A faster sedimentation rate can be a nonspecific sign of inflammation, infection, autoimmune disease, some cancers, or blood disorders. ESR alone does not diagnose the cause.",
+      "sex_significance": {
+        "level": "high",
+        "summary": "ESR reference thresholds commonly differ by sex and increase with age; female thresholds are often higher than male thresholds.",
+        "pipeline_guidance": "Use sex_specific_statistics_per_group_age when sex is known. ESR is nonspecific, so the UI should avoid diagnosis and should mention that anemia, pregnancy, age, and other conditions can affect results."
+      },
+      "sex_specific_statistics_per_group_age": {
+        "child": {
+          "male": {"minimal_value": 0, "normal_value": 6.5, "maximum_value": 13},
+          "female": {"minimal_value": 0, "normal_value": 6.5, "maximum_value": 13},
+          "unknown": {"minimal_value": 0, "normal_value": 6.5, "maximum_value": 13}
+        },
+        "teenager": {
+          "male": {"minimal_value": 0, "normal_value": 7.5, "maximum_value": 15},
+          "female": {"minimal_value": 0, "normal_value": 10, "maximum_value": 20},
+          "unknown": {"minimal_value": 0, "normal_value": 10, "maximum_value": 20}
+        },
+        "adult": {
+          "male": {"minimal_value": 0, "normal_value": 7.5, "maximum_value": 15},
+          "female": {"minimal_value": 0, "normal_value": 10, "maximum_value": 20},
+          "unknown": {"minimal_value": 0, "normal_value": 10, "maximum_value": 20}
+        },
+        "elder": {
+          "male": {"minimal_value": 0, "normal_value": 10, "maximum_value": 20},
+          "female": {"minimal_value": 0, "normal_value": 15, "maximum_value": 30},
+          "unknown": {"minimal_value": 0, "normal_value": 15, "maximum_value": 30}
+        }
+      },
+      "instructions_to_improve": {
+        "food": ["Use a balanced dietary pattern emphasizing vegetables, fruits, whole grains, legumes, nuts, fish, and adequate protein.", "Reduce heavy alcohol intake and ultra-processed foods if they are major parts of the diet.", "Address the medical cause of inflammation; diet alone may not normalize ESR."],
+        "exercises": ["Regular moderate activity can support inflammatory and cardiovascular health when appropriate.", "Avoid strenuous exercise during acute illness, fever, or unexplained inflammatory symptoms."],
+        "supplements": ["Do not use supplements to hide or self-treat unexplained inflammation.", "Discuss whether CRP, repeat ESR, or condition-specific testing is appropriate; review all supplements and medications because some can affect results."]
+      },
+      "statistics_per_group_age": {
+        "child": {"minimal_value": 0, "normal_value": 5, "maximum_value": 10},
+        "teenager": {"minimal_value": 0, "normal_value": 10, "maximum_value": 20},
+        "adult": {"minimal_value": 0, "normal_value": 10, "maximum_value": 20},
+        "elder": {"minimal_value": 0, "normal_value": 15, "maximum_value": 30}
+      },
+      "related_tests": ["wbc", "hemoglobin"],
+      "source_ids": ["medlineplus_esr", "seattle_childrens_esr", "uchicago_esr_reference", "cleveland_clinic_esr"]
+    }
+  ]
+}

src/extraction/local_minicpmv.py

@@ -32,6 +32,7 @@ from src.openbmb_client import (
     EXTRACTION_PROMPT,
     ExtractionResult,
     _normalize_notes,
+    _normalize_patient,
     _normalize_tests,
 )
 
@@ -91,6 +92,7 @@ class LocalMiniCPMVExtractor:
             parsed = {}
 
         return ExtractionResult(
+            patient=_normalize_patient(parsed.get("patient", {})),
             tests=_normalize_tests(parsed.get("tests", [])),
             notes=_normalize_notes(parsed.get("notes", [])),
             raw_response=raw,

src/extraction/local_server.py

@@ -32,6 +32,7 @@ from src.openbmb_client import (
     EXTRACTION_PROMPT,
     ExtractionResult,
     _normalize_notes,
+    _normalize_patient,
     _normalize_tests,
     _parse_json_response,
 )
@@ -81,6 +82,7 @@ class LocalServerExtractor:
         raw = _message_content(response.json())
         parsed = _parse_json_response(raw)
         return ExtractionResult(
+            patient=_normalize_patient(parsed.get("patient", {})),
             tests=_normalize_tests(parsed.get("tests", [])),
             notes=_normalize_notes(parsed.get("notes", [])),
             raw_response=raw,

src/grammar.py

@@ -1,7 +1,7 @@
 """GBNF grammar for the extraction schema.
 
 Grammar-constrained decoding makes the local model **physically unable** to emit anything but
-a valid `{tests:[...], notes:[...]}` object in our exact schema. For a small model this is the
+a valid `{patient:{...}, tests:[...], notes:[...]}` object in our exact schema. For a small model this is the
 single biggest reliability lever: no parse failures, no stray prose, no hallucinated keys.
 Passed to llama.cpp via `LlamaGrammar.from_string(...)`.
 """
@@ -9,7 +9,13 @@ Passed to llama.cpp via `LlamaGrammar.from_string(...)`.
 from __future__ import annotations
 
 EXTRACTION_GRAMMAR = r"""
-root    ::= "{" ws "\"tests\"" ws ":" ws tests ws "," ws "\"notes\"" ws ":" ws notes ws "}"
+root    ::= "{" ws "\"patient\"" ws ":" ws patient ws "," ws "\"tests\"" ws ":" ws tests ws "," ws "\"notes\"" ws ":" ws notes ws "}"
+
+patient ::= "{" ws
+            "\"age\"" ws ":" ws strornull ws "," ws
+            "\"age_years\"" ws ":" ws numberornull ws "," ws
+            "\"sex\"" ws ":" ws sex ws
+            "}"
 
 tests   ::= "[" ws ( test ( ws "," ws test )* )? ws "]"
 test    ::= "{" ws
@@ -25,7 +31,9 @@ test    ::= "{" ws
 notes   ::= "[" ws ( string ( ws "," ws string )* )? ws "]"
 
 status  ::= "\"low\"" | "\"normal\"" | "\"high\"" | "\"abnormal\"" | "\"unknown\""
+sex     ::= "\"male\"" | "\"female\"" | "\"unknown\""
 strornull ::= string | "null"
+numberornull ::= number | "null"
 string  ::= "\"" char* "\""
 char    ::= [^"\\] | "\\" ["\\/bfnrt]
 number  ::= "-"? ("0" | [1-9] [0-9]*) ("." [0-9]+)?

src/knowledge_graph.py

@@ -0,0 +1,126 @@
+"""Knowledge-graph lookup and reference selection for lab markers."""
+
+from __future__ import annotations
+
+import json
+import re
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+
+ROOT = Path(__file__).resolve().parents[1]
+DEFAULT_KNOWLEDGE_GRAPH_PATH = ROOT / "kb" / "cbc_knowledge_graph.json"
+
+
+class LabKnowledgeGraph:
+    """Small deterministic lookup layer over the JSON knowledge graph."""
+
+    def __init__(self, payload: dict[str, Any]) -> None:
+        self.payload = payload
+        self.tests: list[dict[str, Any]] = list(payload.get("tests", []))
+        self._by_id = {str(test.get("id", "")).casefold(): test for test in self.tests}
+        self._alias_index = self._build_alias_index()
+
+    @classmethod
+    def load(cls, path: str | Path = DEFAULT_KNOWLEDGE_GRAPH_PATH) -> "LabKnowledgeGraph":
+        graph_path = Path(path)
+        return cls(json.loads(graph_path.read_text(encoding="utf-8")))
+
+    def resolve(self, marker_name: str | None) -> dict[str, Any] | None:
+        """Return the graph node matching a raw marker name or alias."""
+        for key in _candidate_keys(marker_name):
+            match = self._alias_index.get(key)
+            if match is not None:
+                return match
+        return None
+
+    def get(self, marker_id: str | None) -> dict[str, Any] | None:
+        if not marker_id:
+            return None
+        return self._by_id.get(str(marker_id).casefold())
+
+    def select_statistics(
+        self,
+        node: dict[str, Any],
+        age_group: str,
+        sex: str,
+    ) -> dict[str, Any] | None:
+        """Select the best statistics block for age/sex context.
+
+        Sex-specific ranges are preferred when available. The JSON keeps an
+        `unknown` sex bucket for high-impact markers, and age-only statistics
+        remain the compatibility fallback for every marker.
+        """
+        normalized_sex = sex if sex in {"male", "female"} else "unknown"
+        sex_stats = node.get("sex_specific_statistics_per_group_age")
+        if isinstance(sex_stats, dict):
+            group_stats = sex_stats.get(age_group)
+            if isinstance(group_stats, dict):
+                values = group_stats.get(normalized_sex) or group_stats.get("unknown")
+                if isinstance(values, dict):
+                    return {
+                        "basis": "sex_specific_statistics_per_group_age",
+                        "age_group": age_group,
+                        "sex": normalized_sex,
+                        "values": values,
+                    }
+
+        age_stats = node.get("statistics_per_group_age", {})
+        values = age_stats.get(age_group)
+        if isinstance(values, dict):
+            return {
+                "basis": "statistics_per_group_age",
+                "age_group": age_group,
+                "sex": "not_applied",
+                "values": values,
+            }
+        return None
+
+    def _build_alias_index(self) -> dict[str, dict[str, Any]]:
+        index: dict[str, dict[str, Any]] = {}
+        for test in self.tests:
+            names = [
+                test.get("id"),
+                test.get("display_name"),
+                *(test.get("aliases") or []),
+            ]
+            for name in names:
+                for key in _candidate_keys(name):
+                    index.setdefault(key, test)
+        return index
+
+
+@lru_cache(maxsize=1)
+def default_knowledge_graph() -> LabKnowledgeGraph:
+    return LabKnowledgeGraph.load()
+
+
+def _candidate_keys(value: str | None) -> list[str]:
+    if value is None:
+        return []
+
+    text = str(value).strip()
+    if not text:
+        return []
+
+    pieces = {text}
+    pieces.add(re.sub(r"\([^)]*\)", "", text).strip())
+
+    for inner in re.findall(r"\(([^)]*)\)", text):
+        pieces.add(inner)
+        pieces.update(part.strip() for part in re.split(r"[/,;]", inner))
+
+    keys: list[str] = []
+    for piece in pieces:
+        key = _marker_key(piece)
+        if key and key not in keys:
+            keys.append(key)
+    return keys
+
+
+def _marker_key(value: str) -> str:
+    normalized = value.casefold()
+    normalized = normalized.replace("µ", "u").replace("μ", "u")
+    normalized = normalized.replace("percent", "%").replace("number", "#")
+    return re.sub(r"[^a-z0-9%#]+", "", normalized)

src/openbmb_client.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import json
 import os
 import re
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import Any
 
 import requests
@@ -25,6 +25,11 @@ You are extracting laboratory test results from a medical document.
 
 Return only valid JSON with this exact shape:
 {
+  "patient": {
+    "age": "string or null",
+    "age_years": 0.0,
+    "sex": "male | female | unknown"
+  },
   "tests": [
     {
       "marker": "string",
@@ -42,6 +47,9 @@ Return only valid JSON with this exact shape:
 Rules:
 - Extract pure lab values only.
 - Do not diagnose, interpret, recommend food, supplements, or exercise.
+- Extract patient age and sex only when visibly present in the document.
+- Normalize sex to "male", "female", or "unknown"; do not infer sex from the patient's name.
+- Use null for age and age_years when age is missing.
 - Do not invent missing values.
 - Preserve the units and reference ranges exactly as shown when possible.
 - If a marker is unreadable, omit it or add a short note.
@@ -56,6 +64,7 @@ class ExtractionResult:
     notes: list[str]
     raw_response: str
     request_summary: dict[str, Any]
+    patient: dict[str, Any] = field(default_factory=dict)
 
 
 class OpenBMBExtractor:
@@ -119,6 +128,7 @@ class OpenBMBExtractor:
         parsed = _parse_json_response(raw_response)
 
         return ExtractionResult(
+            patient=_normalize_patient(parsed.get("patient", {})),
             tests=_normalize_tests(parsed.get("tests", [])),
             notes=_normalize_notes(parsed.get("notes", [])),
             raw_response=raw_response,
@@ -237,6 +247,20 @@ def _normalize_notes(value: Any) -> list[str]:
     return [str(note).strip() for note in value if str(note).strip()]
 
 
+def _normalize_patient(value: Any) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        return {"age": None, "age_years": None, "sex": "unknown"}
+
+    age = _optional_string(value.get("age") or value.get("age_text") or value.get("patient_age"))
+    age_years = _optional_float(value.get("age_years"))
+    sex = _normalize_sex(value.get("sex") or value.get("patient_sex") or value.get("gender"))
+    return {
+        "age": age,
+        "age_years": age_years,
+        "sex": sex,
+    }
+
+
 def _optional_string(value: Any) -> str | None:
     if value is None:
         return None
@@ -244,6 +268,24 @@ def _optional_string(value: Any) -> str | None:
     return text or None
 
 
+def _optional_float(value: Any) -> float | None:
+    if value is None or value == "":
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _normalize_sex(value: Any) -> str:
+    text = str(value or "").strip().casefold()
+    if text in {"m", "male"}:
+        return "male"
+    if text in {"f", "female"}:
+        return "female"
+    return "unknown"
+
+
 def _confidence(value: Any) -> float:
     try:
         score = float(value)

src/report_pipeline.py

@@ -0,0 +1,320 @@
+"""Extraction-to-health-report pipeline.
+
+This module keeps the agentic part focused on reading the document. Everything after that is
+deterministic: marker resolution, age/sex reference selection, status comparison, and shaping the
+object consumed by the UI.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from src.knowledge_graph import LabKnowledgeGraph, default_knowledge_graph
+from src.openbmb_client import ExtractionResult
+
+
+AGE_GROUPS = ("child", "teenager", "adult", "elder")
+KNOWN_STATUSES = {"low", "normal", "high", "abnormal", "unknown"}
+
+
+def build_health_report(
+    extraction: ExtractionResult,
+    knowledge_graph: LabKnowledgeGraph | None = None,
+) -> dict[str, Any]:
+    """Merge extracted lab values with knowledge-graph context for rendering."""
+    graph = knowledge_graph or default_knowledge_graph()
+    patient = normalize_patient(getattr(extraction, "patient", {}))
+    markers = [
+        enrich_marker(test, patient=patient, knowledge_graph=graph)
+        for test in extraction.tests
+    ]
+
+    status_counts = _status_counts(markers)
+    enriched_count = sum(1 for marker in markers if marker.get("knowledge") is not None)
+    unmatched = [
+        marker["raw_name"]
+        for marker in markers
+        if marker.get("knowledge") is None
+    ]
+
+    return {
+        "patient": patient,
+        "markers": markers,
+        "notes": list(extraction.notes),
+        "summary": {
+            "total_markers": len(markers),
+            "enriched_markers": enriched_count,
+            "unmatched_markers": unmatched,
+            "status_counts": status_counts,
+            "needs_review": (
+                status_counts.get("high", 0)
+                + status_counts.get("low", 0)
+                + status_counts.get("abnormal", 0)
+            ),
+        },
+        "knowledge_graph": {
+            "schema_version": graph.payload.get("schema_version"),
+            "title": graph.payload.get("title"),
+            "medical_disclaimer": graph.payload.get("medical_disclaimer"),
+            "sex_significance_policy": graph.payload.get("sex_significance_policy"),
+            "sources": graph.payload.get("sources", {}),
+        },
+        "request_summary": extraction.request_summary,
+        "raw_response": extraction.raw_response,
+    }
+
+
+def enrich_marker(
+    extracted: dict[str, Any],
+    patient: dict[str, Any],
+    knowledge_graph: LabKnowledgeGraph,
+) -> dict[str, Any]:
+    raw_name = _text(extracted.get("marker"), "Unknown marker")
+    node = knowledge_graph.resolve(raw_name)
+    numeric_value = parse_numeric_value(extracted.get("value"))
+    extracted_status = normalize_status(extracted.get("status"))
+    lab_interval = parse_reference_interval(extracted.get("reference_range"))
+    kg_selection = (
+        knowledge_graph.select_statistics(node, patient["age_group"], patient["sex"])
+        if node is not None
+        else None
+    )
+    kg_interval = _interval_from_statistics(kg_selection)
+
+    comparison_interval = lab_interval or kg_interval
+    reference_basis = "lab_reference_range" if lab_interval else "knowledge_graph"
+    derived_status = status_from_interval(numeric_value, comparison_interval)
+    final_status = extracted_status if extracted_status != "unknown" else (derived_status or "unknown")
+
+    return {
+        "raw_name": raw_name,
+        "canonical_id": node.get("id") if node else None,
+        "display_name": node.get("display_name") if node else raw_name,
+        "value": _text(extracted.get("value"), "-"),
+        "numeric_value": numeric_value,
+        "unit": _text(extracted.get("unit"), node.get("unit", "") if node else ""),
+        "lab_reference_range": _optional_text(extracted.get("reference_range")),
+        "status": final_status,
+        "extracted_status": extracted_status,
+        "derived_status": derived_status or "unknown",
+        "confidence": _confidence(extracted.get("confidence")),
+        "source_text": _optional_text(extracted.get("source_text")),
+        "comparison": {
+            "basis": reference_basis,
+            "interval": comparison_interval,
+            "range_position": range_position(numeric_value, comparison_interval),
+        },
+        "reference_selection": kg_selection,
+        "knowledge": _knowledge_payload(node),
+    }
+
+
+def normalize_patient(value: Any) -> dict[str, Any]:
+    source = value if isinstance(value, dict) else {}
+    raw_age = (
+        source.get("age")
+        or source.get("age_text")
+        or source.get("age_years")
+        or source.get("patient_age")
+    )
+    age_years = parse_age_years(source.get("age_years"))
+    if age_years is None:
+        age_years = parse_age_years(raw_age)
+
+    sex = normalize_sex(source.get("sex") or source.get("patient_sex") or source.get("gender"))
+    return {
+        "age": _optional_text(raw_age),
+        "age_years": age_years,
+        "age_group": age_group_for(age_years),
+        "sex": sex,
+        "raw": source,
+    }
+
+
+def parse_age_years(value: Any) -> float | None:
+    if value is None:
+        return None
+    if isinstance(value, (int, float)):
+        return float(value) if value >= 0 else None
+
+    text = str(value).strip().casefold()
+    if not text:
+        return None
+
+    # Common report format: "25y 10m 26d".
+    years = _first_number_before(text, ("y", "yr", "yrs", "year", "years"))
+    months = _first_number_before(text, ("mo", "mos", "month", "months", "m"))
+    days = _first_number_before(text, ("d", "day", "days"))
+    if years is not None or months is not None or days is not None:
+        return round((years or 0.0) + (months or 0.0) / 12 + (days or 0.0) / 365.25, 2)
+
+    match = re.search(r"\d+(?:\.\d+)?", text)
+    if match:
+        parsed = float(match.group(0))
+        return parsed if parsed >= 0 else None
+    return None
+
+
+def normalize_sex(value: Any) -> str:
+    if value is None:
+        return "unknown"
+    text = str(value).strip().casefold()
+    if text in {"m", "male", "man", "boy"}:
+        return "male"
+    if text in {"f", "female", "woman", "girl"}:
+        return "female"
+    return "unknown"
+
+
+def age_group_for(age_years: float | None) -> str:
+    if age_years is None:
+        return "adult"
+    if age_years < 13:
+        return "child"
+    if age_years < 18:
+        return "teenager"
+    if age_years < 65:
+        return "adult"
+    return "elder"
+
+
+def parse_numeric_value(value: Any) -> float | None:
+    if value is None:
+        return None
+    if isinstance(value, (int, float)):
+        return float(value)
+    match = re.search(r"-?\d+(?:,\d{3})*(?:\.\d+)?", str(value))
+    if not match:
+        return None
+    try:
+        return float(match.group(0).replace(",", ""))
+    except ValueError:
+        return None
+
+
+def parse_reference_interval(value: Any) -> dict[str, float | None] | None:
+    text = _optional_text(value)
+    if not text:
+        return None
+
+    cleaned = text.casefold().replace("–", "-").replace("—", "-")
+    numbers = [float(match.replace(",", "")) for match in re.findall(r"\d+(?:,\d{3})*(?:\.\d+)?", cleaned)]
+    if len(numbers) >= 2 and re.search(r"\d\s*-\s*\d", cleaned):
+        low, high = numbers[0], numbers[1]
+        return {"low": min(low, high), "high": max(low, high)}
+
+    if numbers and re.search(r"(up to|less than|<|<=|≤|below)", cleaned):
+        return {"low": None, "high": numbers[0]}
+
+    if numbers and re.search(r"(greater than|>|>=|≥|above|at least)", cleaned):
+        return {"low": numbers[0], "high": None}
+
+    return None
+
+
+def status_from_interval(
+    value: float | None,
+    interval: dict[str, float | None] | None,
+) -> str | None:
+    if value is None or not interval:
+        return None
+    low = interval.get("low")
+    high = interval.get("high")
+    if low is not None and value < low:
+        return "low"
+    if high is not None and value > high:
+        return "high"
+    return "normal"
+
+
+def range_position(
+    value: float | None,
+    interval: dict[str, float | None] | None,
+) -> int:
+    if value is None or not interval:
+        return 50
+    low = interval.get("low")
+    high = interval.get("high")
+    if low is not None and high is not None and high > low:
+        return _clamp_percent((value - low) / (high - low) * 100)
+    if high is not None and high > 0:
+        return _clamp_percent(value / high * 100)
+    if low is not None and low > 0:
+        return _clamp_percent(value / low * 100)
+    return 50
+
+
+def normalize_status(value: Any) -> str:
+    status = str(value or "unknown").strip().casefold()
+    if status in {"l", "lo"}:
+        return "low"
+    if status in {"h", "hi"}:
+        return "high"
+    if status in {"ok", "within range", "in range"}:
+        return "normal"
+    return status if status in KNOWN_STATUSES else "unknown"
+
+
+def _knowledge_payload(node: dict[str, Any] | None) -> dict[str, Any] | None:
+    if node is None:
+        return None
+    return {
+        "description": node.get("description"),
+        "why_important": node.get("why_important"),
+        "instructions_to_improve": node.get("instructions_to_improve") or {},
+        "sex_significance": node.get("sex_significance") or {},
+        "related_tests": node.get("related_tests") or [],
+        "source_ids": node.get("source_ids") or [],
+        "category": node.get("category"),
+        "unit": node.get("unit"),
+    }
+
+
+def _interval_from_statistics(selection: dict[str, Any] | None) -> dict[str, float | None] | None:
+    if not selection:
+        return None
+    values = selection.get("values") or {}
+    low = values.get("minimal_value")
+    high = values.get("maximum_value")
+    if low is None and high is None:
+        return None
+    return {"low": float(low) if low is not None else None, "high": float(high) if high is not None else None}
+
+
+def _first_number_before(text: str, suffixes: tuple[str, ...]) -> float | None:
+    suffix_pattern = "|".join(re.escape(suffix) for suffix in suffixes)
+    match = re.search(rf"(\d+(?:\.\d+)?)\s*(?:{suffix_pattern})\b", text)
+    return float(match.group(1)) if match else None
+
+
+def _status_counts(markers: list[dict[str, Any]]) -> dict[str, int]:
+    counts = {status: 0 for status in sorted(KNOWN_STATUSES)}
+    for marker in markers:
+        status = normalize_status(marker.get("status"))
+        counts[status] = counts.get(status, 0) + 1
+    return counts
+
+
+def _text(value: Any, fallback: str) -> str:
+    text = _optional_text(value)
+    return text if text is not None else fallback
+
+
+def _optional_text(value: Any) -> str | None:
+    if value is None:
+        return None
+    text = str(value).strip()
+    return text or None
+
+
+def _confidence(value: Any) -> float:
+    try:
+        score = float(value)
+    except (TypeError, ValueError):
+        return 0.0
+    return max(0.0, min(1.0, score))
+
+
+def _clamp_percent(value: float) -> int:
+    return max(0, min(100, round(value)))

tests/test_report_pipeline.py

@@ -0,0 +1,122 @@
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from src.knowledge_graph import LabKnowledgeGraph  # noqa: E402
+from src.openbmb_client import ExtractionResult  # noqa: E402
+from src.report_pipeline import build_health_report, normalize_patient, parse_reference_interval  # noqa: E402
+from app import _final_range_position, _final_status_for_marker, _preferred_marker_label  # noqa: E402
+
+
+def _result(tests, patient=None):
+    return ExtractionResult(
+        patient=patient or {},
+        tests=tests,
+        notes=[],
+        raw_response="{}",
+        request_summary={},
+    )
+
+
+def test_patient_age_and_sex_are_normalized():
+    patient = normalize_patient({"age": "25y 10m 26d", "sex": "Female"})
+    assert patient["age_group"] == "adult"
+    assert patient["sex"] == "female"
+    assert patient["age_years"] and patient["age_years"] > 25
+
+
+def test_reference_interval_parser_handles_common_lab_formats():
+    assert parse_reference_interval("3.5-5.50") == {"low": 3.5, "high": 5.5}
+    assert parse_reference_interval("Up to 15") == {"low": None, "high": 15.0}
+    assert parse_reference_interval("< 20") == {"low": None, "high": 20.0}
+
+
+def test_report_enriches_extracted_marker_with_knowledge_graph():
+    report = build_health_report(
+        _result(
+            [
+                {
+                    "marker": "RBC",
+                    "value": "3.3",
+                    "unit": "10^6/uL",
+                    "reference_range": "3.5-5.50",
+                    "status": "low",
+                    "source_text": "RBC 3.3 3.5-5.50",
+                    "confidence": 0.91,
+                }
+            ],
+            patient={"age": "25y 10m 26d", "sex": "Female"},
+        )
+    )
+    marker = report["markers"][0]
+    assert marker["canonical_id"] == "rbc"
+    assert marker["knowledge"]["description"]
+    assert marker["comparison"]["basis"] == "lab_reference_range"
+    assert marker["status"] == "low"
+    assert marker["reference_selection"]["sex"] == "female"
+    assert marker["reference_selection"]["values"]["maximum_value"] == 5.2
+
+
+def test_report_uses_sex_specific_kg_range_when_lab_range_is_missing():
+    report = build_health_report(
+        _result(
+            [
+                {
+                    "marker": "Hemoglobin",
+                    "value": "12.7",
+                    "unit": "g/dL",
+                    "reference_range": None,
+                    "status": "unknown",
+                    "confidence": 1,
+                }
+            ],
+            patient={"age_years": 42, "sex": "male"},
+        )
+    )
+    marker = report["markers"][0]
+    assert marker["comparison"]["basis"] == "knowledge_graph"
+    assert marker["derived_status"] == "low"
+    assert marker["status"] == "low"
+    assert marker["reference_selection"]["sex"] == "male"
+
+
+def test_knowledge_graph_has_sex_guidance_for_every_marker():
+    graph = LabKnowledgeGraph.load()
+    assert graph.tests
+    assert all("sex_significance" in test for test in graph.tests)
+    high = [test for test in graph.tests if test["sex_significance"]["level"] == "high"]
+    assert {test["id"] for test in high} == {"hemoglobin", "rbc", "hct", "esr"}
+    assert all("sex_specific_statistics_per_group_age" in test for test in high)
+
+
+def test_final_report_bar_uses_kg_min_normal_and_max_values():
+    report = build_health_report(
+        _result(
+            [
+                {"marker": "RBC", "value": "3.3", "unit": "10^6/uL", "status": "normal", "confidence": 1},
+                {"marker": "WBC", "value": "6.7", "unit": "10^3/uL", "status": "normal", "confidence": 1},
+            ],
+            patient={"age_years": 25, "sex": "female"},
+        )
+    )
+    rbc, wbc = report["markers"]
+    assert _final_status_for_marker(rbc) == "bad"
+    assert 6 <= _final_range_position(rbc) <= 30
+    assert _final_status_for_marker(wbc) == "ideal"
+    assert 68 <= _final_range_position(wbc) <= 94
+
+
+def test_final_report_prefers_lab_abbreviations_when_extracted():
+    assert _preferred_marker_label(
+        {"raw_name": "RBC", "display_name": "Red Blood Cell Count"}
+    ) == "RBC"
+    assert _preferred_marker_label(
+        {"raw_name": "Hct", "display_name": "Hematocrit"}
+    ) == "Hct"
+    assert _preferred_marker_label(
+        {"raw_name": "NEU%", "display_name": "Neutrophils Percent"}
+    ) == "NEU%"
+    assert _preferred_marker_label(
+        {"raw_name": "Hemoglobin", "display_name": "Hemoglobin"}
+    ) == "Hemoglobin"