Add agent trace panel, vision extraction, and local Transformers backend.

Replace chat preview with a scrollable pipeline trace, restore PDF/image
vision intake, default to local Transformers extraction, expand the marker
knowledge base, and track hackathon logo assets for deployment. Codex
collaborated on the trace UI, vision pipeline, and deployment workflow.

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

.gitattributes

@@ -34,3 +34,5 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
 *.gguf filter=lfs diff=lfs merge=lfs -text
+assets/logos/*.png filter=lfs diff=lfs merge=lfs -text
+assets/logos/*.webp filter=lfs diff=lfs merge=lfs -text

app.py

@@ -15,6 +15,13 @@ import gradio as gr
 from src.extraction import build_extractor
 from src.interpretation_render import patterns_html
 from src.local_env import load_local_env
+from src.pipeline_trace import (
+    build_pipeline_trace,
+    empty_trace_html,
+    error_trace_html,
+    processing_trace_html,
+    trace_to_html,
+)
 from src.report_pipeline import build_health_report
 
 
@@ -26,21 +33,21 @@ def _boot_log(message: str) -> None:
     elapsed = time.perf_counter() - _BOOT_T0
     print(f"[Blood Test Explainer][{elapsed:0.2f}s] {message}", flush=True)
 
-# The hosted API key field is only relevant when the API backend is active. The current Space
-# path is ZeroGPU, so users should not see model/API configuration controls.
-_API_MODE = os.getenv("EXTRACTOR_BACKEND", "auto").strip().lower() == "api"
+_APP_ROOT = Path(__file__).resolve().parent
+_LOGO_DIR = _APP_ROOT / "assets" / "logos"
 _boot_log("environment loaded")
 
 
 def extract_lab_values(
     uploaded_file: str | None,
-) -> tuple[str, str, Any, str]:
+) -> tuple[str, str, Any, str, str]:
     if not uploaded_file:
         return (
             _status_html("Waiting for a document", "Upload a lab report to begin extraction."),
             empty_report_html("No document uploaded", "Choose a file first, then run extraction again."),
             gr.update(visible=True),
             workflow_phase_html("ready"),
+            empty_trace_html(),
         )
 
     extractor = build_extractor()
@@ -54,11 +61,13 @@ def extract_lab_values(
             empty_report_html("Extraction failed", detail),
             gr.update(visible=True),
             workflow_phase_html("ready"),
+            error_trace_html(detail),
         )
 
     health_report = build_health_report(result)
     summary = health_report["summary"]
     patient = health_report["patient"]
+    steps = build_pipeline_trace(result, health_report, source_path=uploaded_file)
 
     status_text = (
         f"Extracted {summary['total_markers']} lab values and enriched "
@@ -76,11 +85,10 @@ def extract_lab_values(
 
     return (
         _status_html("Extraction complete", status_text),
-        # Per-marker insight comes from the knowledge-graph report; append the cross-marker
-        # patterns (anemia picture, liver cluster, lipid risk) which the per-marker report omits.
         report_html(health_report) + patterns_html(result.tests),
         gr.update(visible=True),
         workflow_phase_html("done"),
+        trace_to_html(steps),
     )
 
 
@@ -101,11 +109,10 @@ def _format_extraction_error(error: Exception) -> str:
             "The llama.cpp backend could not load the GGUF model. That points to a model/runtime "
             "compatibility issue, not a background worker problem."
         )
+    if "hosted openbmb api backend is disabled" in lowered:
+        return "Hosted API extraction is disabled. The app uses local Transformers only."
     if "401" in lowered or "unauthorized" in lowered:
-        return (
-            "The OpenBMB endpoint rejected the request. Check the API key or switch to the local "
-            "ZeroGPU path."
-        )
+        return "Authentication failed for the configured backend."
     if "could not be converted into a report" in lowered:
         return "The model produced output, but it could not be parsed into the extraction schema."
     return primary
@@ -135,26 +142,152 @@ def _display_status_label(status: str) -> str:
     return normalized.title() if normalized else "Unknown"
 
 
-def hero_attribution_html() -> str:
-    items = [
-        ("Codex", "Build with Codex", "CDX", "aria-label=\"Codex logo\""),
-        ("OpenBMB", "Enabled with OpenBMB", "OB", "aria-label=\"OpenBMB logo\""),
-        ("Modal", "Finetuned with Modal", "M", "aria-label=\"Modal logo\""),
-        ("ACG", "Created by researchers at ACG", "ACG", "aria-label=\"ACG logo\""),
+def _logo_data_uri(filename: str) -> str | None:
+    path = _LOGO_DIR / filename
+    if not path.exists():
+        return None
+    mime_type = {
+        ".svg": "image/svg+xml",
+        ".png": "image/png",
+        ".jpg": "image/jpeg",
+        ".jpeg": "image/jpeg",
+        ".webp": "image/webp",
+    }.get(path.suffix.lower(), "application/octet-stream")
+    encoded = base64.b64encode(path.read_bytes()).decode("ascii")
+    return f"data:{mime_type};base64,{encoded}"
+
+
+def _hero_badge_mark_html(slug: str, mark: str, logo_file: str) -> str:
+    logo_uri = _logo_data_uri(logo_file)
+    if not logo_uri:
+        return escape(mark)
+    return (
+        f'<img class="bte-hero-badge-logo" src="{logo_uri}" '
+        f'alt="{escape(slug)} logo" loading="lazy" />'
+    )
+
+
+def hero_hackathon_panel_html() -> str:
+    hf_logo_uri = _logo_data_uri("HF.webp")
+    hf_logo_inner = (
+        f'<img class="bte-title-hf-logo" src="{hf_logo_uri}" alt="Hugging Face logo" loading="lazy" />'
+        if hf_logo_uri
+        else '<span class="bte-title-hf-logo-fallback" aria-hidden="true">HF</span>'
+    )
+    hf_logo_html = f'<span class="bte-title-hf-logo-wrap">{hf_logo_inner}</span>'
+    badges = [
+        (
+            "🔌",
+            "Off the Grid",
+            "Extraction runs on-device through llama.cpp or ZeroGPU with no external inference API.",
+        ),
+        (
+            "🎯",
+            "Well-Tuned",
+            "MiniCPM-V was fine-tuned on Modal and published on Hugging Face for lab report extraction.",
+        ),
+        (
+            "🎨",
+            "Off-Brand",
+            "Custom CSS, HTML reports, and workflow panels push past the default Gradio look.",
+        ),
+        (
+            "🦙",
+            "Llama Champion",
+            "GGUF models run through the llama.cpp runtime on CPU and ZeroGPU paths.",
+        ),
+        (
+            "📡",
+            "Sharing is Caring",
+            "Agent traces, eval artifacts, and model cards are shared on the Hugging Face Hub.",
+        ),
+        (
+            "📓",
+            "Field Notes",
+            "Build notes, runbooks, and deployment logs document what we built and learned.",
+        ),
     ]
-    badges = "\n".join(
+    badge_items = "\n".join(
         f"""
-        <li class=\"bte-hero-badge bte-hero-badge--{escape(slug.lower())}\">
-          <span class=\"bte-hero-badge-mark\" {attrs}>{escape(mark)}</span>
-          <span class=\"bte-hero-badge-text\">{escape(label)}</span>
+        <li class="bte-hack-badge" tabindex="0">
+          <div class="bte-hack-badge-row">
+            <span class="bte-hack-badge-icon" aria-hidden="true">{emoji}</span>
+            <span class="bte-hack-badge-name">{escape(name)}</span>
+          </div>
+          <p class="bte-expand-detail">{escape(detail)}</p>
         </li>
         """
-        for slug, label, mark, attrs in items
+        for emoji, name, detail in badges
     )
     return f"""
-    <ul class=\"bte-hero-attribution\" aria-label=\"Project attributions\">
-      {badges}
-    </ul>
+    <div class="bte-title-hackathon-panel">
+      <section class="bte-title-hf" aria-label="Hackathon project">
+        {hf_logo_html}
+        <p class="bte-title-hf-copy">Project for Build Small Hackathon</p>
+      </section>
+      <div class="bte-title-section-divider" aria-hidden="true"></div>
+      <section class="bte-hack-badges">
+        <p class="bte-title-side-label">Badges Collected</p>
+        <ul class="bte-hack-badges-grid" aria-label="Hackathon badges collected">
+          {badge_items}
+        </ul>
+      </section>
+    </div>
+    """
+
+
+def hero_attribution_html() -> str:
+    items = [
+        (
+            "Codex",
+            "Build with Codex",
+            "CDX",
+            "codex.png",
+            "Codex helped build the app UI, extraction pipeline, deployment scripts, and iteration workflow.",
+        ),
+        (
+            "OpenBMB",
+            "Enabled with OpenBMB",
+            "OB",
+            "openbmb.png",
+            "MiniCPM-V-4.6 reads uploaded lab reports and extracts marker values, units, and status flags.",
+        ),
+        (
+            "Modal",
+            "Finetuned with Modal",
+            "M",
+            "modal.png",
+            "Modal runs LoRA fine-tuning and evaluation jobs that produced the published extraction model.",
+        ),
+        (
+            "ACG",
+            "Created by researchers at ACG",
+            "ACG",
+            "acg.png",
+            "Developed at The American College of Greece for the Hugging Face Build Small Hackathon.",
+        ),
+    ]
+    badge_chunks = []
+    for slug, label, mark, logo_file, detail in items:
+        mark_html = _hero_badge_mark_html(slug, mark, logo_file)
+        badge_chunks.append(
+            f"""
+        <li class="bte-hero-badge bte-hero-badge--{escape(slug.lower())}" tabindex="0">
+          <div class="bte-hero-badge-row">
+            <span class="bte-hero-badge-mark">{mark_html}</span>
+            <span class="bte-hero-badge-text">{escape(label)}</span>
+          </div>
+          <p class="bte-expand-detail">{escape(detail)}</p>
+        </li>
+        """
+        )
+    badges = "\n".join(badge_chunks)
+    return f"""
+    <div class="bte-hero-credits">
+      <ul class="bte-hero-attribution" aria-label="Project attributions">
+        {badges}
+      </ul>
+    </div>
     """
 
 
@@ -195,22 +328,24 @@ def workflow_arrow_html(kind: str) -> str:
     """
 
 
-def show_processing() -> tuple[str, Any, str, str]:
+def show_processing() -> tuple[str, Any, str, str, str]:
     return (
         _status_html("Reading document", "Extracting patient context and markers, then matching them to the knowledge graph.", tone="loading"),
         gr.update(visible=False),
         "",
         workflow_phase_html("processing"),
+        processing_trace_html(),
     )
 
 
-def upload_state(uploaded_file: str | None) -> tuple[Any, Any]:
+def upload_state(uploaded_file: str | None) -> tuple[Any, Any, Any, str, str]:
     if not uploaded_file:
         return (
             gr.update(visible=True),
-            gr.update(value='<p class="bte-upload-hint">Supported formats: PDF</p>', visible=True),
+            gr.update(value='<p class="bte-upload-hint">Supported formats: PDF, PNG, JPEG, WebP</p>', visible=True),
             gr.update(visible=False, value=selected_document_html()),
             workflow_phase_html("ready"),
+            empty_trace_html(),
         )
 
     preview_data_url = _uploaded_file_preview_data_url(uploaded_file)
@@ -219,6 +354,7 @@ def upload_state(uploaded_file: str | None) -> tuple[Any, Any]:
         gr.update(value="", visible=False),
         gr.update(visible=True, value=selected_document_html(preview_data_url=preview_data_url)),
         workflow_phase_html("processing"),
+        processing_trace_html(),
     )
 
 
@@ -266,7 +402,7 @@ def _uploaded_file_preview_data_url(uploaded_file: str) -> str | None:
             if document.page_count == 0:
                 return None
             page = document.load_page(0)
-            pixmap = page.get_pixmap(matrix=fitz.Matrix(2, 2), alpha=False)
+            pixmap = page.get_pixmap(matrix=fitz.Matrix(2.8, 2.8), alpha=False)
             encoded = base64.b64encode(pixmap.tobytes("png")).decode("ascii")
             return f"data:image/png;base64,{encoded}"
 
@@ -334,38 +470,6 @@ def analysis_animation_html() -> str:
     """
 
 
-def result_preview_html() -> str:
-    return """
-    <section class="bte-formation bte-formation--result" aria-label="Clear lab results preview">
-      <div class="bte-formation-stage bte-formation-stage--result">
-        <div class="bte-smart-report">
-          <div class="bte-report-window">
-            <div class="bte-report-header">
-              <strong>12 markers</strong>
-              <small>ready to review</small>
-            </div>
-            <div class="bte-mini-card bte-mini-card--green">
-              <span>Hemoglobin</span>
-              <strong>Normal</strong>
-            </div>
-            <div class="bte-mini-card bte-mini-card--red">
-              <span>Vitamin D</span>
-              <strong>Low</strong>
-            </div>
-            <div class="bte-mini-chart">
-              <span style="height: 34%"></span>
-              <span style="height: 56%"></span>
-              <span style="height: 42%"></span>
-              <span style="height: 74%"></span>
-              <span style="height: 61%"></span>
-            </div>
-          </div>
-        </div>
-      </div>
-    </section>
-    """
-
-
 def _ideal_marker_card(test: dict[str, str]) -> str:
     status = test["status"]
     range_position_value = test.get("range_position", "50")
@@ -899,6 +1003,7 @@ CUSTOM_CSS = """
   --bte-radius: 22px;
   --bte-shadow: 0 14px 34px rgba(17, 24, 39, 0.055);
   --bte-shadow-strong: 0 18px 44px rgba(17, 24, 39, 0.07);
+  --bte-active-ring: linear-gradient(120deg, var(--bte-green), var(--bte-blue), var(--bte-red));
   --bte-rail: min(94vw, 1240px);
 }
 
@@ -1038,15 +1143,15 @@ gradio-app,
   width: var(--bte-rail) !important;
   max-width: var(--bte-rail) !important;
   margin: 0 auto 18px !important;
-  padding: 30px 28px 28px;
+  padding: 28px 28px 26px;
   display: grid;
-  grid-template-columns: minmax(0, 1fr) minmax(280px, 360px);
-  gap: 32px;
-  align-items: center;
+  grid-template-columns: minmax(0, 1.05fr) minmax(250px, 0.95fr) minmax(250px, 0.9fr);
+  gap: 24px 28px;
+  align-items: stretch;
   border: 1px solid rgba(255, 255, 255, 0.42);
   border-radius: var(--bte-radius);
   background:
-    linear-gradient(120deg, rgba(18, 128, 92, 0.98) 0%, rgba(37, 99, 235, 0.95) 58%, rgba(191, 52, 52, 0.82) 100%),
+    linear-gradient(120deg, rgba(191, 52, 52, 0.82) 0%, rgba(37, 99, 235, 0.95) 58%, rgba(18, 128, 92, 0.98) 100%),
     #12805c;
   box-shadow: var(--bte-shadow-strong);
 }
@@ -1064,17 +1169,268 @@ gradio-app,
   color: rgba(255, 255, 255, 0.88);
   -webkit-text-fill-color: rgba(255, 255, 255, 0.88) !important;
   font-size: 16px;
-  max-width: 820px;
+  max-width: none;
   margin: 0;
+  text-align: left;
+}
+
+.bte-title-copy,
+.bte-title-hackathon-wrap,
+.bte-title-credits-wrap,
+.bte-title .bte-title-copy,
+.bte-title .bte-title-hackathon-wrap,
+.bte-title .bte-title-credits-wrap {
+  position: relative;
+  align-self: stretch;
+  min-width: 0;
 }
 
 .bte-title-copy {
+  text-align: left;
+  justify-self: stretch;
+  padding-right: 24px;
+}
+
+.bte-title-hackathon-wrap {
+  padding-right: 24px;
+}
+
+.bte-title-credits-wrap {
+  padding-left: 4px;
+}
+
+.bte-title-copy::after,
+.bte-title-hackathon-wrap::after,
+.bte-title .bte-title-copy::after,
+.bte-title .bte-title-hackathon-wrap::after {
+  content: "";
+  position: absolute;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  width: 1px;
+  background: rgba(255, 255, 255, 0.42);
+  pointer-events: none;
+}
+
+.bte-title-hackathon-panel {
+  display: grid;
+  gap: 0;
+  align-content: start;
+}
+
+.bte-title-hf {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  justify-content: flex-start;
+  gap: 14px;
+  padding-bottom: 18px;
+  text-align: left;
+}
+
+.bte-title-hf-logo-wrap {
+  flex: 0 0 52px;
+  width: 52px;
+  height: 52px;
+  display: grid;
+  place-items: center;
+  overflow: hidden;
+  border-radius: 23%;
+  background: rgba(255, 255, 255, 0.96);
+  box-shadow: 0 4px 14px rgba(17, 24, 39, 0.14);
+}
+
+.bte-title-hf-logo {
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.bte-title-hf-logo-fallback {
+  display: grid;
+  place-items: center;
+  width: 100%;
+  height: 100%;
+  color: #111827;
+  font-size: 18px;
+  font-weight: 800;
+}
+
+.bte-title-hf-copy {
+  margin: 0;
+  flex: 1;
+  min-width: 0;
+  font-size: 10px;
+  font-weight: 800;
+  letter-spacing: 0.07em;
+  line-height: 1.35;
+  text-transform: uppercase;
+  color: rgba(255, 255, 255, 0.88) !important;
+  -webkit-text-fill-color: rgba(255, 255, 255, 0.88) !important;
+}
+
+.bte-title-section-divider {
+  height: 1px;
+  background: rgba(255, 255, 255, 0.34);
+  margin-bottom: 18px;
+}
+
+.bte-title-side-label {
+  margin: 0 0 10px;
+  font-size: 11px;
+  font-weight: 800;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: rgba(255, 255, 255, 0.72) !important;
+  -webkit-text-fill-color: rgba(255, 255, 255, 0.72) !important;
+}
+
+.bte-hack-badges,
+.bte-hack-badges-grid,
+.bte-hero-credits,
+.bte-hero-attribution {
+  overflow: visible;
+}
+
+.bte-hack-badges-grid {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  grid-auto-rows: minmax(36px, auto);
+  align-content: start;
+  gap: 8px 10px;
+}
+
+.bte-hack-badge {
+  display: flex;
+  flex-direction: column;
+  align-items: stretch;
+  gap: 0;
+  width: 100%;
+  max-width: 100%;
+  min-height: 36px;
+  max-height: 36px;
+  min-width: 0;
+  box-sizing: border-box;
+  padding: 8px;
+  border-radius: 12px;
+  background: rgba(255, 255, 255, 0.1);
+  border: 1px solid rgba(255, 255, 255, 0.16);
+  overflow: hidden;
+  cursor: pointer;
+  position: relative;
+  transition:
+    max-height 260ms ease,
+    background 180ms ease,
+    border-color 180ms ease,
+    box-shadow 180ms ease;
+}
+
+.bte-hack-badge:hover,
+.bte-hack-badge:focus-within {
+  max-height: 500px;
+  overflow: visible;
+  z-index: 3;
+  background: rgba(255, 255, 255, 0.18);
+  border-color: rgba(255, 255, 255, 0.32);
+  box-shadow: 0 10px 24px rgba(17, 24, 39, 0.16);
+  outline: none;
+}
+
+.bte-hack-badge-row {
+  display: flex;
+  align-items: center;
+  gap: 7px;
+  min-width: 0;
+  min-height: 18px;
+}
+
+.bte-hack-badge-icon {
+  flex: 0 0 18px;
+  width: 18px;
+  height: 18px;
+  display: grid;
+  place-items: center;
+  font-size: 14px;
+  line-height: 1;
+}
+
+.bte-hack-badge-name {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: #ffffff !important;
+  -webkit-text-fill-color: #ffffff !important;
+  font-size: 10px;
+  line-height: 1.2;
+  font-weight: 700;
+}
+
+.bte-expand-detail {
+  margin: 0;
+  max-height: 0;
+  opacity: 0;
+  overflow: hidden;
+  color: rgba(255, 255, 255, 0.76) !important;
+  -webkit-text-fill-color: rgba(255, 255, 255, 0.76) !important;
+  font-size: 10px !important;
+  line-height: 1.4;
+  font-weight: 400 !important;
+  white-space: normal;
+  transition:
+    max-height 260ms ease,
+    opacity 180ms ease,
+    margin-top 180ms ease;
+}
+
+.bte-title .bte-expand-detail,
+.bte-title .bte-expand-detail * {
+  font-size: 10px !important;
+  font-weight: 400 !important;
+  line-height: 1.4 !important;
+}
+
+.bte-hack-badge:hover .bte-hack-badge-name,
+.bte-hack-badge:focus-within .bte-hack-badge-name,
+.bte-hero-badge:hover .bte-hero-badge-text,
+.bte-hero-badge:focus-within .bte-hero-badge-text {
+  white-space: normal;
+  overflow: visible;
+  text-overflow: clip;
+}
+
+.bte-hack-badge:hover .bte-expand-detail,
+.bte-hack-badge:focus-within .bte-expand-detail {
+  padding-left: 25px;
+}
+
+.bte-hero-badge:hover .bte-expand-detail,
+.bte-hero-badge:focus-within .bte-expand-detail {
+  padding-left: 58px;
+}
+
+.bte-hack-badge:hover .bte-expand-detail,
+.bte-hack-badge:focus-within .bte-expand-detail,
+.bte-hero-badge:hover .bte-expand-detail,
+.bte-hero-badge:focus-within .bte-expand-detail {
+  max-height: 400px;
+  opacity: 1;
+  margin-top: 6px;
+  overflow: visible;
+}
+
+.bte-hero-credits {
   min-width: 0;
 }
 
 .bte-title-attribution-wrap {
   min-width: 0;
-  justify-self: end;
 }
 
 .bte-hero-attribution {
@@ -1086,53 +1442,93 @@ gradio-app,
 }
 
 .bte-hero-badge {
-  display: grid;
-  grid-template-columns: 34px minmax(0, 1fr);
-  gap: 12px;
-  align-items: center;
+  display: flex;
+  flex-direction: column;
+  align-items: stretch;
+  gap: 0;
+  min-height: 54px;
+  max-height: 54px;
   padding: 10px 12px;
   border-radius: 14px;
   background: rgba(255, 255, 255, 0.12);
   border: 1px solid rgba(255, 255, 255, 0.18);
   backdrop-filter: blur(6px);
+  overflow: hidden;
+  cursor: pointer;
+  position: relative;
+  transition:
+    max-height 260ms ease,
+    background 180ms ease,
+    border-color 180ms ease,
+    box-shadow 180ms ease;
+}
+
+.bte-hero-badge:hover,
+.bte-hero-badge:focus-within {
+  max-height: 500px;
+  overflow: visible;
+  z-index: 3;
+  background: rgba(255, 255, 255, 0.18);
+  border-color: rgba(255, 255, 255, 0.32);
+  box-shadow: 0 10px 24px rgba(17, 24, 39, 0.16);
+  outline: none;
+}
+
+.bte-hero-badge-row {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  min-width: 0;
+  min-height: 34px;
 }
 
 .bte-hero-badge-mark {
-  width: 34px;
+  width: 46px;
   height: 34px;
-  border-radius: 11px;
+  flex: 0 0 46px;
   display: grid;
   place-items: center;
-  color: #fff;
+  color: #ffffff;
   font-size: 11px;
   font-weight: 800;
   letter-spacing: 0;
-  background: linear-gradient(135deg, rgba(255, 255, 255, 0.26), rgba(255, 255, 255, 0.08));
-  box-shadow: inset 0 0 0 1px rgba(255, 255, 255, 0.16);
+  background: transparent;
+  box-shadow: none;
+  overflow: visible;
+}
+
+.bte-hero-badge-logo {
+  display: block;
+  width: 34px;
+  max-width: 38px;
+  max-height: 24px;
+  object-fit: contain;
 }
 
 .bte-hero-badge-text {
+  flex: 1 1 auto;
+  min-width: 0;
   color: #ffffff !important;
   -webkit-text-fill-color: #ffffff !important;
   font-size: 13px;
-  line-height: 1.2;
+  line-height: 1.3;
   font-weight: 700;
 }
 
-.bte-hero-badge--codex .bte-hero-badge-mark {
-  background: linear-gradient(135deg, rgba(37, 99, 235, 0.95), rgba(18, 128, 92, 0.92));
-}
-
-.bte-hero-badge--openbmb .bte-hero-badge-mark {
-  background: linear-gradient(135deg, rgba(18, 128, 92, 0.95), rgba(37, 99, 235, 0.92));
+.bte-hero-badge--openbmb .bte-hero-badge-logo {
+  width: auto;
+  max-width: 44px;
+  max-height: 22px;
 }
 
-.bte-hero-badge--modal .bte-hero-badge-mark {
-  background: linear-gradient(135deg, rgba(191, 52, 52, 0.95), rgba(37, 99, 235, 0.9));
+.bte-hero-badge--modal .bte-hero-badge-logo {
+  width: 38px;
+  max-width: 40px;
 }
 
-.bte-hero-badge--acg .bte-hero-badge-mark {
-  background: linear-gradient(135deg, rgba(90, 99, 214, 0.95), rgba(18, 128, 92, 0.9));
+.bte-hero-badge--acg .bte-hero-badge-logo {
+  width: 32px;
+  max-height: 32px;
 }
 
 .bte-title .bte-kicker,
@@ -1153,6 +1549,11 @@ gradio-app,
 .bte-title h1 {
   font-size: clamp(38px, 5vw, 56px) !important;
   line-height: 1.04 !important;
+  text-align: left !important;
+}
+
+.bte-title .bte-kicker {
+  text-align: left !important;
 }
 
 .bte-title > div,
@@ -1203,17 +1604,8 @@ gradio-app,
   padding: 0 !important;
 }
 
-.bte-hero-grid .bte-upload-card {
-  border: 1px solid var(--bte-line) !important;
-  border-radius: var(--bte-radius) !important;
-  padding: 18px !important;
-  background: var(--bte-page) !important;
-  box-shadow: var(--bte-shadow) !important;
-  overflow: hidden !important;
-}
-
-.bte-hero-grid .block:has(.bte-upload-card),
-.bte-hero-grid div:has(> .bte-upload-card) {
+.bte-hero-grid .bte-panel-upload .block:has(.bte-upload-card),
+.bte-hero-grid .bte-panel-upload div:has(> .bte-upload-card) {
   height: 430px !important;
   min-height: 430px !important;
   border: 1px solid var(--bte-line) !important;
@@ -1222,15 +1614,33 @@ gradio-app,
   background: var(--bte-page) !important;
   box-shadow: var(--bte-shadow) !important;
   overflow: hidden !important;
+  display: flex !important;
+  flex-direction: column !important;
 }
 
-.bte-hero-grid .block:has(.bte-upload-card) .bte-upload-card,
-.bte-hero-grid div:has(> .bte-upload-card) > .bte-upload-card {
+.bte-hero-grid .bte-panel-upload .block:has(.bte-upload-card) .bte-shell,
+.bte-hero-grid .bte-panel-upload div:has(> .bte-upload-card) .bte-shell,
+.bte-hero-grid .bte-panel-upload .block:has(.bte-upload-card) .bte-upload-card,
+.bte-hero-grid .bte-panel-upload div:has(> .bte-upload-card) > .bte-upload-card {
   height: 100% !important;
   min-height: 0 !important;
+  flex: 1 1 auto !important;
+  display: flex !important;
+  flex-direction: column !important;
   border: 0 !important;
   padding: 0 !important;
   box-shadow: none !important;
+  background: transparent !important;
+  overflow: hidden !important;
+}
+
+.bte-hero-grid .bte-upload-card:not(.bte-panel-upload .block:has(.bte-upload-card) .bte-upload-card) {
+  border: 1px solid var(--bte-line) !important;
+  border-radius: var(--bte-radius) !important;
+  padding: 18px !important;
+  background: var(--bte-page) !important;
+  box-shadow: var(--bte-shadow) !important;
+  overflow: hidden !important;
 }
 
 .bte-workflow-panel {
@@ -1378,117 +1788,538 @@ gradio-app,
   transition: opacity 220ms ease, filter 220ms ease, box-shadow 220ms ease, transform 220ms ease, border-color 220ms ease, background 220ms ease;
 }
 
-.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="ready"]) ~ .bte-step-row-block .bte-step-heading--upload,
-.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="processing"]) ~ .bte-step-row-block .bte-step-heading--analysis,
-.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="done"]) ~ .bte-step-row-block .bte-step-heading--report {
-  opacity: 1;
-  filter: saturate(1);
-  transform: translateY(-1px);
-  border-color: rgba(37, 99, 235, 0.32);
-  background: linear-gradient(180deg, rgba(37, 99, 235, 0.08), rgba(255, 255, 255, 0.98));
-  box-shadow: 0 16px 34px rgba(37, 99, 235, 0.1);
+.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="ready"]) ~ .bte-step-row-block .bte-step-heading--upload,
+.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="processing"]) ~ .bte-step-row-block .bte-step-heading--analysis,
+.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="done"]) ~ .bte-step-row-block .bte-step-heading--report {
+  opacity: 1;
+  filter: saturate(1.08);
+  transform: translateY(-1px);
+  border: 2px solid transparent;
+  background:
+    linear-gradient(var(--bte-surface), var(--bte-surface)) padding-box,
+    var(--bte-active-ring) border-box;
+  box-shadow: var(--bte-shadow-strong);
+}
+
+.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="ready"]) ~ .bte-step-row-block .bte-step-heading--analysis,
+.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="ready"]) ~ .bte-step-row-block .bte-step-heading--report,
+.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="processing"]) ~ .bte-step-row-block .bte-step-heading--upload,
+.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="processing"]) ~ .bte-step-row-block .bte-step-heading--report,
+.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="done"]) ~ .bte-step-row-block .bte-step-heading--upload,
+.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="done"]) ~ .bte-step-row-block .bte-step-heading--analysis {
+  opacity: 0.38;
+  filter: saturate(0.45);
+  transform: none;
+  background: var(--bte-surface);
+  box-shadow: var(--bte-shadow);
+  border-color: rgba(216, 226, 238, 0.92);
+}
+
+.bte-step-heading span {
+  width: 34px;
+  min-width: 34px;
+  aspect-ratio: 1;
+  display: grid;
+  place-items: center;
+  border-radius: 50%;
+  color: #ffffff !important;
+  -webkit-text-fill-color: #ffffff !important;
+  background: linear-gradient(135deg, var(--bte-green), var(--bte-blue));
+  font-size: 15px;
+  font-weight: 780;
+}
+
+.bte-step-heading span,
+.bte-step-heading span * {
+  color: #ffffff !important;
+  -webkit-text-fill-color: #ffffff !important;
+}
+
+.bte-step-heading h2 {
+  margin: 0 !important;
+  color: var(--bte-ink) !important;
+  font-size: clamp(18px, 2.1vw, 24px) !important;
+  line-height: 1.18 !important;
+  letter-spacing: 0 !important;
+  text-align: left !important;
+}
+
+.bte-panel-upload .bte-upload-card,
+.bte-panel-analysis .bte-formation,
+.bte-panel-result .bte-agent-panel,
+.bte-final-row .bte-report {
+  transition: opacity 220ms ease, filter 220ms ease, box-shadow 220ms ease, transform 220ms ease, border-color 220ms ease, background 220ms ease;
+}
+
+.bte-step-heading--report {
+  margin-top: 0;
+  min-height: 112px;
+  padding: 18px;
+}
+
+.bte-upload-card {
+  height: 100% !important;
+  display: flex;
+  flex-direction: column;
+  justify-content: flex-start;
+  min-height: 0 !important;
+  overflow: hidden !important;
+  position: relative !important;
+}
+
+.bte-panel-upload .bte-upload-dropzone,
+.bte-panel-upload .bte-upload-card > .block:has(.bte-upload-dropzone),
+.bte-panel-upload .bte-upload-card > .form:has(.bte-upload-dropzone) {
+  position: absolute !important;
+  inset: 0 !important;
+  flex: 1 1 auto !important;
+  min-height: 0 !important;
+  display: flex !important;
+  flex-direction: column !important;
+  overflow: hidden !important;
+  border: 0 !important;
+  padding: 0 !important;
+  background: transparent !important;
+  box-shadow: none !important;
+  z-index: 1 !important;
+}
+
+.bte-upload-card:has(.bte-selected-document) .bte-upload-dropzone,
+.bte-upload-card:has(.bte-selected-document) .bte-upload-hint-wrap,
+.bte-upload-card:has(.bte-selected-document) > .block:has(.bte-upload-dropzone),
+.bte-upload-card:has(.bte-selected-document) > .form:has(.bte-upload-dropzone) {
+  display: none !important;
+}
+
+.bte-upload-card:has(.bte-selected-document) .block:has(.bte-selected-document),
+.bte-upload-card:has(.bte-selected-document) .html-container:has(.bte-selected-document) {
+  position: absolute !important;
+  inset: 0 !important;
+  z-index: 5 !important;
+  width: 100% !important;
+  height: 100% !important;
+  margin: 0 !important;
+  padding: 0 !important;
+  border: 0 !important;
+  background: transparent !important;
+  box-shadow: none !important;
+  overflow: hidden !important;
+}
+
+.bte-upload-card:has(.bte-selected-document) .prose.bte-selected-document-wrap,
+.bte-upload-card:has(.bte-selected-document) .html-container:has(.bte-selected-document) > *,
+.bte-upload-card:has(.bte-selected-document) .bte-selected-document,
+.bte-upload-card:has(.bte-selected-document) .bte-selected-preview {
+  height: 100% !important;
+  min-height: 100% !important;
+}
+
+.bte-upload-card:has(.bte-selected-document) .prose:has(.bte-selected-document) {
+  padding: 0 !important;
+  margin: 0 !important;
+  max-width: none !important;
+}
+
+.bte-panel-upload .bte-upload-dropzone > .block,
+.bte-panel-upload .bte-upload-dropzone > .form,
+.bte-panel-upload .bte-upload-dropzone > div {
+  flex: 1 1 auto !important;
+  min-height: 0 !important;
+  display: flex !important;
+  flex-direction: column !important;
+  overflow: hidden !important;
+}
+
+.bte-panel-upload .bte-upload-hint-wrap {
+  flex: 0 0 auto;
+  position: relative !important;
+  z-index: 2 !important;
+  pointer-events: none !important;
+}
+
+.bte-upload-hint {
+  margin: 0 0 12px !important;
+  color: var(--bte-ink) !important;
+  font-size: 18px !important;
+  font-weight: 700 !important;
+  text-align: center !important;
+}
+
+.bte-panel-upload .bte-upload-card .block:has(.bte-uploader),
+.bte-panel-upload .bte-upload-card .form:has(.bte-uploader),
+.bte-panel-upload .bte-shell > .block:has(.bte-uploader),
+.bte-panel-upload .bte-shell > .form:has(.bte-uploader),
+.bte-panel-upload .bte-upload-card > .block:has(.bte-uploader) {
+  flex: 1 1 auto !important;
+  min-height: 0 !important;
+  display: flex !important;
+  flex-direction: column !important;
+  overflow: hidden !important;
+}
+
+.bte-panel-upload .bte-uploader,
+.bte-panel-upload .bte-uploader > div,
+.bte-panel-upload .bte-uploader > div > div,
+.bte-panel-upload .bte-uploader .wrap {
+  flex: 1 1 auto !important;
+  min-height: 0 !important;
+  height: 100% !important;
+  display: flex !important;
+  flex-direction: column !important;
+  overflow: hidden !important;
+}
+
+.bte-formation {
+  width: 100% !important;
+  max-width: 100% !important;
+  height: 430px !important;
+  min-height: 430px;
+  border: 1px solid var(--bte-line);
+  border-radius: var(--bte-radius);
+  padding: 22px;
+  background: var(--bte-surface);
+  box-shadow: var(--bte-shadow);
+  overflow: hidden;
+}
+
+.bte-formation-stage {
+  height: 100%;
+  min-height: 382px;
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+  justify-items: center;
+  align-items: center;
+  gap: 14px;
+}
+
+.bte-formation-stage--analysis .bte-source-doc,
+.bte-formation-stage--result .bte-smart-report,
+.bte-formation-stage--result .bte-report-window {
+  width: 100%;
+}
+
+.bte-panel-analysis .bte-formation--analysis,
+.bte-panel-result .bte-agent-panel {
+  overflow: hidden;
+}
+
+.bte-hero-grid .bte-panel-trace .block:has(.bte-agent-panel),
+.bte-hero-grid .bte-panel-trace div:has(> .bte-agent-panel) {
+  height: 430px !important;
+  min-height: 430px !important;
+  max-height: 430px !important;
+  border: 1px solid var(--bte-line) !important;
+  border-radius: var(--bte-radius) !important;
+  padding: 16px !important;
+  background: var(--bte-page) !important;
+  box-shadow: var(--bte-shadow) !important;
+  overflow: hidden !important;
+  display: flex !important;
+  flex-direction: column !important;
+  box-sizing: border-box !important;
+}
+
+.bte-hero-grid .bte-panel-trace .block:has(.bte-agent-panel) .bte-shell,
+.bte-hero-grid .bte-panel-trace div:has(> .bte-agent-panel) .bte-shell,
+.bte-hero-grid .bte-panel-trace .block:has(.bte-agent-panel) .bte-agent-panel,
+.bte-hero-grid .bte-panel-trace div:has(> .bte-agent-panel) > .bte-agent-panel {
+  height: 100% !important;
+  min-height: 0 !important;
+  flex: 1 1 auto !important;
+  display: flex !important;
+  flex-direction: column !important;
+  border: 0 !important;
+  padding: 0 !important;
+  box-shadow: none !important;
+  background: transparent !important;
+  overflow: hidden !important;
+  gap: 0 !important;
+}
+
+.bte-agent-panel,
+.bte-agent-panel > div,
+.bte-agent-panel > .block,
+.bte-agent-panel > .form {
+  display: flex !important;
+  flex-direction: column !important;
+  flex: 1 1 auto !important;
+  min-height: 0 !important;
+  width: 100% !important;
+}
+
+.bte-agent-panel .block:has(.bte-agent-trace),
+.bte-agent-panel .block:has(.bte-trace-panel),
+.bte-agent-panel .html-container:has(.bte-trace-panel),
+.bte-panel-trace .bte-agent-panel .block,
+.bte-panel-trace .bte-agent-panel .form,
+.bte-panel-trace .bte-agent-panel .wrap,
+.bte-panel-trace .bte-agent-panel .html-container,
+.bte-panel-trace .bte-agent-panel .prose {
+  flex: 1 1 auto !important;
+  min-height: 0 !important;
+  height: 100% !important;
+  max-height: 100% !important;
+  overflow: hidden !important;
+  margin: 0 !important;
+  padding: 0 !important;
+  border: 0 !important;
+  background: transparent !important;
+  box-shadow: none !important;
+  box-sizing: border-box !important;
+  display: flex !important;
+  flex-direction: column !important;
+}
+
+.bte-panel-trace .bte-agent-panel .html-container:has(.bte-trace-panel),
+.bte-panel-trace .bte-agent-panel .prose:has(.bte-trace-panel) {
+  width: 100% !important;
+}
+
+.bte-trace-panel {
+  flex: 1 1 auto !important;
+  height: 100% !important;
+  max-height: 100% !important;
+  min-height: 0 !important;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  padding: 4px 10px 0;
+  box-sizing: border-box;
+}
+
+.bte-trace-panel-header {
+  flex: 0 0 auto;
+  padding: 0 4px 10px;
+  border-bottom: 1px solid var(--bte-line);
+  margin-bottom: 10px;
+}
+
+.bte-trace-panel-header strong {
+  display: block;
+  color: var(--bte-ink);
+  font-size: 18px;
+  line-height: 1.25;
+  padding: 0 2px;
+  overflow: visible;
+  word-break: normal;
+}
+
+.bte-trace-subtitle {
+  margin: 6px 0 0;
+  padding: 0 2px;
+  color: var(--bte-muted);
+  font-size: 13px;
+  line-height: 1.45;
+}
+
+.bte-trace-steps {
+  flex: 1 1 auto;
+  min-height: 0;
+  max-height: calc(430px - 32px - 92px);
+  overflow-x: hidden;
+  overflow-y: auto !important;
+  overscroll-behavior: contain;
+  -webkit-overflow-scrolling: touch;
+  padding: 0 2px 8px 0;
+  scrollbar-gutter: stable;
+}
+
+.bte-trace-steps::-webkit-scrollbar {
+  width: 8px;
+}
+
+.bte-trace-steps::-webkit-scrollbar-thumb {
+  background: #cbd5e1;
+  border-radius: 999px;
+}
+
+.bte-trace-steps::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+.bte-trace-empty {
+  margin: 0;
+  color: var(--bte-muted);
+  font-size: 14px;
+  line-height: 1.5;
+}
+
+.bte-trace-empty--active {
+  color: var(--bte-ink);
+}
+
+.bte-trace-empty--error {
+  color: #b42318;
+}
+
+.bte-trace-status {
+  display: inline-flex;
+  align-items: center;
+  padding: 2px 8px;
+  border-radius: 999px;
+  font-size: 11px;
+  font-weight: 700;
+  letter-spacing: 0.02em;
+  text-transform: uppercase;
+}
+
+.bte-trace-status--complete {
+  color: #067647;
+  background: #ecfdf3;
+  border: 1px solid #abefc6;
+}
+
+.bte-trace-status--running {
+  color: #175cd3;
+  background: #eff8ff;
+  border: 1px solid #b2ddff;
+}
+
+.bte-trace-status--failed {
+  color: #b42318;
+  background: #fef3f2;
+  border: 1px solid #fecdca;
+}
+
+.bte-trace-status--unknown {
+  color: #344054;
+  background: #f2f4f7;
+  border: 1px solid #eaecf0;
+}
+
+.bte-trace-step-summary {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+  gap: 4px;
+  padding: 10px 12px;
+  cursor: pointer;
+  list-style: none;
+}
+
+.bte-trace-step-heading {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+}
+
+.bte-trace-step-meta {
+  color: #475467;
+  font-size: 11px;
+  font-weight: 600;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+}
+
+.bte-trace-meta {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 8px 12px;
+  margin: 0 0 10px;
+  padding: 10px;
+  border: 1px solid #eef2f7;
+  border-radius: 10px;
+  background: #f8fafc;
+}
+
+.bte-trace-meta dt {
+  margin: 0;
+  color: #667085;
+  font-size: 11px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.03em;
 }
 
-.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="ready"]) ~ .bte-step-row-block .bte-step-heading--analysis,
-.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="ready"]) ~ .bte-step-row-block .bte-step-heading--report,
-.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="processing"]) ~ .bte-step-row-block .bte-step-heading--upload,
-.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="processing"]) ~ .bte-step-row-block .bte-step-heading--report,
-.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="done"]) ~ .bte-step-row-block .bte-step-heading--upload,
-.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="done"]) ~ .bte-step-row-block .bte-step-heading--analysis {
-  opacity: 0.38;
-  filter: saturate(0.45);
-  transform: none;
-  background: var(--bte-surface);
-  box-shadow: var(--bte-shadow);
-  border-color: rgba(216, 226, 238, 0.92);
+.bte-trace-meta dd {
+  margin: 2px 0 0;
+  color: #101828;
+  font-size: 12px;
+  line-height: 1.4;
+  white-space: pre-wrap;
+  word-break: break-word;
 }
 
-.bte-step-heading span {
-  width: 34px;
-  min-width: 34px;
-  aspect-ratio: 1;
-  display: grid;
-  place-items: center;
-  border-radius: 50%;
-  color: #ffffff !important;
-  -webkit-text-fill-color: #ffffff !important;
-  background: linear-gradient(135deg, var(--bte-green), var(--bte-blue));
-  font-size: 15px;
-  font-weight: 780;
+.bte-trace-step-summary::-webkit-details-marker {
+  display: none;
 }
 
-.bte-step-heading span,
-.bte-step-heading span * {
-  color: #ffffff !important;
-  -webkit-text-fill-color: #ffffff !important;
+.bte-trace-step {
+  border: 1px solid #e5e7eb;
+  border-radius: 12px;
+  margin-bottom: 8px;
+  background: #fff;
+  overflow: hidden;
 }
 
-.bte-step-heading h2 {
-  margin: 0 !important;
-  color: var(--bte-ink) !important;
-  font-size: clamp(18px, 2.1vw, 24px) !important;
-  line-height: 1.18 !important;
-  letter-spacing: 0 !important;
-  text-align: left !important;
+.bte-trace-step:last-child {
+  margin-bottom: 0;
 }
 
-.bte-panel-upload .bte-upload-card,
-.bte-panel-analysis .bte-formation,
-.bte-panel-result .bte-formation,
-.bte-final-row .bte-report {
-  transition: opacity 220ms ease, filter 220ms ease, box-shadow 220ms ease, transform 220ms ease, border-color 220ms ease, background 220ms ease;
+.bte-trace-step-title {
+  color: var(--bte-ink);
+  font-size: 14px;
+  font-weight: 700;
 }
 
-.bte-step-heading--report {
-  margin-top: 0;
-  min-height: 112px;
-  padding: 18px;
+.bte-trace-step-teaser {
+  color: var(--bte-muted);
+  font-size: 12px;
+  line-height: 1.4;
 }
 
-.bte-upload-card {
-  height: 430px !important;
-  display: flex;
-  flex-direction: column;
-  justify-content: space-between;
-  min-height: 430px;
-  overflow: visible !important;
+.bte-trace-step[open] .bte-trace-step-summary {
+  border-bottom: 1px solid #eef2f7;
+  background: #f8fbff;
 }
 
-.bte-formation {
-  width: 100% !important;
-  max-width: 100% !important;
-  height: 430px !important;
-  min-height: 430px;
-  border: 1px solid var(--bte-line);
-  border-radius: var(--bte-radius);
-  padding: 22px;
-  background: var(--bte-surface);
-  box-shadow: var(--bte-shadow);
-  overflow: hidden;
+.bte-trace-step-body {
+  padding: 10px 12px 12px;
 }
 
-.bte-formation-stage {
-  height: 100%;
-  min-height: 382px;
-  display: grid;
-  grid-template-columns: minmax(0, 1fr);
-  justify-items: center;
-  align-items: center;
-  gap: 14px;
+.bte-trace-summary {
+  margin: 0 0 8px;
+  color: #334155;
+  font-size: 13px;
+  line-height: 1.5;
+  white-space: pre-wrap;
 }
 
-.bte-formation-stage--analysis .bte-source-doc,
-.bte-formation-stage--result .bte-smart-report,
-.bte-formation-stage--result .bte-report-window {
-  width: 100%;
+.bte-trace-subdetails {
+  margin-top: 8px;
+  border: 1px solid #e5e7eb;
+  border-radius: 10px;
+  padding: 8px 10px;
+  background: #f9fafb;
 }
 
-.bte-panel-analysis .bte-formation--analysis,
-.bte-panel-result .bte-formation--result {
-  overflow: visible;
+.bte-trace-subdetails summary {
+  cursor: pointer;
+  font-size: 12px;
+  font-weight: 600;
+  color: #334155;
+}
+
+.bte-trace-subdetails pre {
+  margin: 8px 0 0;
+  padding: 8px;
+  border-radius: 8px;
+  background: #fff;
+  border: 1px solid #e5e7eb;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  font-size: 11px;
+  line-height: 1.45;
+  white-space: pre-wrap;
+  word-break: break-word;
+  max-height: 220px;
+  overflow: auto;
+}
+
+.bte-panel-trace {
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
 }
 
-.bte-panel-result .bte-smart-report,
 .bte-panel-result .bte-mini-card,
 .bte-panel-result .bte-mini-chart span {
   animation-play-state: paused !important;
@@ -1503,39 +2334,58 @@ gradio-app,
 }
 
 .bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="ready"]) ~ .bte-hero-grid .bte-panel-analysis .bte-formation--analysis,
-.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="ready"]) ~ .bte-hero-grid .bte-panel-result .bte-formation--result,
+.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="ready"]) ~ .bte-hero-grid .bte-panel-result .bte-agent-panel,
 .bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="processing"]) ~ .bte-hero-grid .bte-panel-upload .bte-upload-card,
-.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="processing"]) ~ .bte-hero-grid .bte-panel-result .bte-formation--result,
+.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="processing"]) ~ .bte-hero-grid .bte-panel-result .bte-agent-panel,
 .bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="done"]) ~ .bte-hero-grid .bte-panel-upload .bte-upload-card,
 .bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="done"]) ~ .bte-hero-grid .bte-panel-analysis .bte-formation--analysis {
   opacity: 0.42;
   filter: saturate(0.5);
 }
 
-.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="ready"]) ~ .bte-hero-grid .bte-panel-upload .bte-upload-card,
+.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="ready"]) ~ .bte-hero-grid .bte-panel-upload .block:has(.bte-upload-card),
+.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="ready"]) ~ .bte-hero-grid .bte-panel-upload div:has(> .bte-upload-card),
 .bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="processing"]) ~ .bte-hero-grid .bte-panel-analysis .bte-formation--analysis,
-.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="done"]) ~ .bte-hero-grid .bte-panel-result .bte-formation--result {
+.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="done"]) ~ .bte-hero-grid .bte-panel-trace .block:has(.bte-agent-panel),
+.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="done"]) ~ .bte-hero-grid .bte-panel-trace div:has(> .bte-agent-panel) {
   opacity: 1;
-  filter: saturate(1);
+  filter: saturate(1.08);
+  transform: translateY(-1px);
+  border: 2px solid transparent !important;
+  background:
+    linear-gradient(var(--bte-page), var(--bte-page)) padding-box,
+    var(--bte-active-ring) border-box !important;
+  box-shadow: var(--bte-shadow-strong) !important;
+}
+
+.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="ready"]) ~ .bte-hero-grid .bte-panel-upload .block:has(.bte-upload-card) .bte-shell,
+.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="ready"]) ~ .bte-hero-grid .bte-panel-upload .bte-upload-card,
+.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="ready"]) ~ .bte-hero-grid .bte-panel-upload .block:has(.bte-upload-card) .bte-upload-card {
+  border: 0 !important;
+  background: transparent !important;
+  box-shadow: none !important;
+}
+
+.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="processing"]) ~ .bte-hero-grid .bte-panel-analysis .bte-formation--analysis,
+.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="done"]) ~ .bte-hero-grid .bte-panel-trace .block:has(.bte-agent-panel),
+.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="done"]) ~ .bte-hero-grid .bte-panel-trace div:has(> .bte-agent-panel) {
+  background:
+    linear-gradient(var(--bte-surface), var(--bte-surface)) padding-box,
+    var(--bte-active-ring) border-box !important;
 }
 
 .bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="ready"]) ~ .bte-hero-grid .bte-panel-analysis .bte-formation--analysis,
 .bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="done"]) ~ .bte-hero-grid .bte-panel-upload .bte-upload-card,
-.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="ready"]) ~ .bte-hero-grid .bte-panel-result .bte-formation--result,
+.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="ready"]) ~ .bte-hero-grid .bte-panel-result .bte-agent-panel,
 .bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="processing"]) ~ .bte-hero-grid .bte-panel-upload .bte-upload-card,
-.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="processing"]) ~ .bte-hero-grid .bte-panel-result .bte-formation--result,
+.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="processing"]) ~ .bte-hero-grid .bte-panel-result .bte-agent-panel,
 .bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="done"]) ~ .bte-hero-grid .bte-panel-analysis .bte-formation--analysis {
   animation-play-state: paused !important;
 }
 
 .bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="processing"]) ~ .bte-hero-grid .bte-panel-analysis .bte-formation--analysis,
-.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="done"]) ~ .bte-hero-grid .bte-panel-result .bte-formation--result {
-  animation-play-state: running !important;
-}
-
-.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="done"]) ~ .bte-hero-grid .bte-panel-result .bte-smart-report,
-.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="done"]) ~ .bte-hero-grid .bte-panel-result .bte-mini-card,
-.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="done"]) ~ .bte-hero-grid .bte-panel-result .bte-mini-chart span {
+.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="done"]) ~ .bte-hero-grid .bte-panel-trace .block:has(.bte-agent-panel),
+.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="done"]) ~ .bte-hero-grid .bte-panel-trace div:has(> .bte-agent-panel) {
   animation-play-state: running !important;
 }
 
@@ -1547,7 +2397,6 @@ gradio-app,
   animation-play-state: running !important;
 }
 
-.bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="done"]) ~ .bte-hero-grid .bte-panel-result .bte-formation--result .bte-smart-report,
 .bte-workflow-phase:has(.bte-workflow-phase-marker[data-phase="ready"]) ~ .bte-hero-grid .bte-panel-upload .bte-upload-card {
   animation-play-state: paused !important;
 }
@@ -1823,12 +2672,121 @@ gradio-app,
   box-shadow: none !important;
 }
 
-.bte-upload-hint {
-  margin: 0 0 10px !important;
-  color: var(--bte-muted) !important;
-  font-size: 13px !important;
-  font-weight: 650 !important;
-  text-align: center !important;
+.bte-panel-upload .bte-uploader [class*="drop"],
+.bte-panel-upload .bte-uploader [class*="upload"] {
+  flex: 1 1 auto !important;
+  min-height: 0 !important;
+  max-height: 100% !important;
+  display: flex !important;
+  flex-direction: column !important;
+  align-items: center !important;
+  justify-content: center !important;
+  gap: 0 !important;
+  padding: 0 !important;
+  overflow: hidden !important;
+  box-sizing: border-box !important;
+}
+
+.bte-panel-upload .bte-uploader [data-testid="block-label"],
+.bte-panel-upload .bte-uploader [data-testid="status-tracker"],
+.bte-panel-upload .bte-uploader .icon-button-wrapper,
+.bte-panel-upload .bte-uploader .file-preview-holder {
+  display: none !important;
+}
+
+.bte-panel-upload .bte-uploader > button,
+.bte-panel-upload .bte-uploader button[class*="center"] {
+  flex: 1 1 auto !important;
+  width: 100% !important;
+  height: 100% !important;
+  min-height: 0 !important;
+  margin: 0 !important;
+  padding: 0 !important;
+  border: 0 !important;
+  background: transparent !important;
+  box-shadow: none !important;
+  display: flex !important;
+  align-items: center !important;
+  justify-content: center !important;
+  cursor: pointer !important;
+}
+
+.bte-panel-upload .bte-uploader button .wrap:not(:has(.uploading)) {
+  font-size: 0 !important;
+  line-height: 0 !important;
+  color: transparent !important;
+  display: inline-flex !important;
+  align-items: center !important;
+  justify-content: center !important;
+  gap: 0 !important;
+}
+
+.bte-panel-upload .bte-uploader button .or {
+  display: none !important;
+}
+
+.bte-panel-upload .bte-uploader .wrap:has(.uploading),
+.bte-panel-upload .bte-uploader .wrap:has(.progress-bar) {
+  flex: 1 1 auto !important;
+  width: 100% !important;
+  height: 100% !important;
+  min-height: 0 !important;
+  display: flex !important;
+  align-items: center !important;
+  justify-content: center !important;
+  position: relative !important;
+  font-size: 0 !important;
+  color: transparent !important;
+}
+
+.bte-panel-upload .bte-uploader .wrap:has(.uploading) > *,
+.bte-panel-upload .bte-uploader .wrap:has(.progress-bar) > * {
+  display: none !important;
+}
+
+.bte-panel-upload .bte-uploader .wrap:has(.uploading)::before,
+.bte-panel-upload .bte-uploader .wrap:has(.progress-bar)::before {
+  content: "";
+  width: 72px;
+  height: 72px;
+  border-radius: 50%;
+  flex: 0 0 auto;
+  background:
+    radial-gradient(circle at 50% 50%, var(--bte-page) 0 56%, transparent 57%),
+    conic-gradient(from 0deg, var(--bte-green), var(--bte-blue), var(--bte-red), var(--bte-green));
+  animation: bte-spin 1.05s linear infinite;
+  box-shadow: 0 12px 30px rgba(17, 24, 39, 0.08);
+}
+
+.bte-uploader [class*="drop"],
+.bte-uploader [class*="upload"] {
+  min-height: 220px !important;
+}
+
+.bte-panel-upload .bte-uploader svg,
+.bte-panel-upload .bte-shell .icon-wrap,
+.bte-panel-upload .bte-shell .icon-wrap svg {
+  width: 72px !important;
+  height: 72px !important;
+  flex: 0 0 auto !important;
+}
+
+.bte-panel-upload .bte-uploader button .icon-wrap {
+  background: var(--bte-active-ring) !important;
+  -webkit-mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%23000' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4'/%3E%3Cpolyline points='17 8 12 3 7 8'/%3E%3Cline x1='12' y1='3' x2='12' y2='15'/%3E%3C/svg%3E") !important;
+  mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%23000' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4'/%3E%3Cpolyline points='17 8 12 3 7 8'/%3E%3Cline x1='12' y1='3' x2='12' y2='15'/%3E%3C/svg%3E") !important;
+  -webkit-mask-repeat: no-repeat !important;
+  mask-repeat: no-repeat !important;
+  -webkit-mask-position: center !important;
+  mask-position: center !important;
+  -webkit-mask-size: contain !important;
+  mask-size: contain !important;
+}
+
+.bte-panel-upload .bte-uploader button .icon-wrap svg {
+  opacity: 0 !important;
+  visibility: hidden !important;
+  pointer-events: none !important;
 }
 
 .bte-shell .file-preview,
@@ -1841,51 +2799,90 @@ gradio-app,
 .bte-shell [class*="drop"],
 .bte-shell [class*="upload"] {
   background: var(--bte-page) !important;
-  border-color: #d8e2ee !important;
+  border: 0 !important;
   border-radius: 18px !important;
   color: var(--bte-ink) !important;
-}
-
-.bte-uploader [class*="drop"],
-.bte-uploader [class*="upload"] {
-  min-height: 250px !important;
+  box-shadow: none !important;
+  outline: none !important;
+}
+
+.bte-panel-upload .bte-shell .block,
+.bte-panel-upload .bte-shell .form,
+.bte-panel-upload .bte-shell .html-container,
+.bte-panel-upload .bte-uploader,
+.bte-panel-upload .bte-uploader > div,
+.bte-panel-upload .bte-uploader > div > div,
+.bte-panel-upload .bte-uploader [class*="drop"],
+.bte-panel-upload .bte-uploader [class*="upload"],
+.bte-panel-upload .bte-shell [class*="drop"],
+.bte-panel-upload .bte-shell [class*="upload"] {
+  border: 0 !important;
+  outline: none !important;
+  box-shadow: none !important;
 }
 
 .bte-selected-document {
   display: grid;
   grid-template-columns: minmax(0, 1fr);
-  gap: 14px;
+  gap: 0;
   align-items: stretch;
-  min-height: 220px;
-  border: 1px solid #d8e2ee;
-  border-radius: 18px;
-  padding: 22px;
-  background: var(--bte-page);
+  height: 100%;
+  min-height: 100%;
+  border: 0;
+  border-radius: 0;
+  padding: 0;
+  background: transparent;
+}
+
+.bte-upload-card:has(.bte-selected-document) .bte-selected-document {
+  height: 100% !important;
+  min-height: 100% !important;
+  padding: 0 !important;
+  border: 0 !important;
+  background: transparent !important;
 }
 
 .bte-selected-preview {
   position: relative;
-  min-height: 260px;
-  border-radius: 22px;
-  border: 1px solid rgba(216, 226, 238, 0.9);
+  height: 100%;
+  min-height: 100%;
+  border-radius: 14px;
+  border: 0;
   background: var(--bte-page);
   overflow: hidden;
+  display: block;
+}
+
+.bte-upload-card:has(.bte-selected-document) .bte-selected-preview {
+  height: 100% !important;
+  min-height: 100% !important;
+  border: 0 !important;
+  border-radius: 12px !important;
 }
 
 .bte-upload-preview-image,
 .bte-upload-preview-placeholder {
   position: absolute;
-  inset: 18px;
-  border-radius: 20px;
+  inset: 0;
+  border-radius: 12px;
 }
 
 .bte-upload-preview-image {
-  width: calc(100% - 36px);
-  height: calc(100% - 36px);
-  object-fit: cover;
-  filter: blur(1.8px) saturate(0.78) contrast(0.92);
-  transform: scale(1.03);
-  box-shadow: 0 16px 35px rgba(18, 32, 56, 0.08);
+  width: 100%;
+  height: 100%;
+  object-fit: contain;
+  object-position: center center;
+  filter: saturate(0.98) contrast(1.03);
+  transform: none;
+  box-shadow: none;
+}
+
+.bte-upload-card:has(.bte-selected-document) .bte-upload-preview-image {
+  inset: 0 !important;
+  width: 100% !important;
+  height: 100% !important;
+  object-fit: contain !important;
+  object-position: center center !important;
 }
 
 .bte-upload-preview-placeholder {
@@ -1958,9 +2955,8 @@ gradio-app,
   position: absolute;
   inset: 0;
   background:
-    linear-gradient(180deg, rgba(255, 255, 255, 0.16), rgba(255, 255, 255, 0.04)),
-    radial-gradient(circle at 50% 46%, rgba(255, 255, 255, 0.22), rgba(255, 255, 255, 0) 40%);
-  backdrop-filter: blur(1.8px);
+    linear-gradient(180deg, rgba(255, 255, 255, 0.05), rgba(255, 255, 255, 0));
+  pointer-events: none;
 }
 
 .bte-selected-document p:last-child {
@@ -2007,16 +3003,16 @@ gradio-app,
   -webkit-text-fill-color: var(--bte-ink) !important;
 }
 
-.bte-shell [class*="drop"] {
-  border-style: dashed !important;
-  border-width: 2px !important;
-}
-
 .bte-shell svg,
 .bte-shell .icon-wrap {
   color: var(--bte-blue) !important;
 }
 
+.bte-panel-upload .bte-uploader button .icon-wrap {
+  color: transparent !important;
+  -webkit-text-fill-color: transparent !important;
+}
+
 button.bte-action,
 button.bte-action *,
 .bte-action button,
@@ -2608,12 +3604,19 @@ button.bte-action *,
 }
 
 .bte-final-report {
+  --bte-report-stack-gap: 12px;
   width: var(--bte-rail) !important;
   max-width: var(--bte-rail) !important;
   margin: 0 auto !important;
   background: rgb(248, 249, 252) !important;
   align-content: start;
-  gap: 12px;
+  gap: var(--bte-report-stack-gap);
+}
+
+.bte-final-report > .bte-ideal-hero,
+.bte-final-report > .bte-ideal-stats,
+.bte-final-report > .bte-ideal-grid {
+  margin: 0;
 }
 
 .bte-final-report .bte-ideal-marker {
@@ -2630,12 +3633,13 @@ button.bte-action *,
   align-items: center;
   justify-content: space-between;
   gap: 22px;
-  padding: 24px 28px 14px;
+  padding: 24px 28px;
+  margin: 0;
   border: 1px solid rgba(255, 255, 255, 0.42);
   border-radius: var(--bte-radius);
   color: #ffffff;
   background:
-    linear-gradient(120deg, rgba(18, 128, 92, 0.98) 0%, rgba(37, 99, 235, 0.95) 58%, rgba(191, 52, 52, 0.82) 100%),
+    linear-gradient(120deg, rgba(191, 52, 52, 0.82) 0%, rgba(37, 99, 235, 0.95) 58%, rgba(18, 128, 92, 0.98) 100%),
     #12805c;
   box-shadow: 0 6px 16px rgba(17, 24, 39, 0.045);
 }
@@ -2661,7 +3665,7 @@ button.bte-action *,
 .bte-ideal-stats {
   display: grid;
   grid-template-columns: repeat(4, minmax(0, 1fr));
-  gap: 12px;
+  gap: var(--bte-report-stack-gap, 12px);
   margin: 0;
 }
 
@@ -2748,14 +3752,14 @@ button.bte-action *,
   display: grid;
   grid-template-columns: repeat(2, minmax(0, 1fr));
   align-items: start;
-  gap: 12px;
-  margin-top: 14px;
+  gap: var(--bte-report-stack-gap, 12px);
+  margin: 0;
 }
 
 .bte-ideal-column {
   display: grid;
   align-content: start;
-  gap: 12px;
+  gap: var(--bte-report-stack-gap, 12px);
 }
 
 .bte-ideal-doc:has(#bte-filter-ideal:checked) .bte-ideal-marker:not(.bte-ideal-marker--ideal),
@@ -3042,6 +4046,36 @@ button.bte-action *,
     gap: 18px;
   }
 
+  .bte-title-copy {
+    padding-right: 0;
+    padding-bottom: 18px;
+  }
+
+  .bte-title-copy::after,
+  .bte-title-hackathon-wrap::after {
+    display: none;
+  }
+
+  .bte-title-hackathon-wrap {
+    padding-right: 0;
+    padding-bottom: 18px;
+  }
+
+  .bte-title-copy,
+  .bte-title-hackathon-wrap,
+  .bte-title-credits-wrap {
+    border-bottom: 1px solid rgba(255, 255, 255, 0.42);
+  }
+
+  .bte-title-credits-wrap {
+    padding-left: 0;
+    border-bottom: 0;
+  }
+
+  .bte-hack-badges-grid {
+    grid-template-columns: 1fr;
+  }
+
   .bte-title-attribution-wrap {
     justify-self: start;
     width: 100%;
@@ -3157,6 +4191,11 @@ button.bte-action *,
     height: 80px;
   }
 
+  .bte-panel-upload .bte-uploader [class*="drop"],
+  .bte-panel-upload .bte-uploader [class*="upload"] {
+    min-height: 0 !important;
+  }
+
   .bte-uploader [class*="drop"],
   .bte-uploader [class*="upload"] {
     min-height: 210px !important;
@@ -3250,7 +4289,7 @@ with gr.Blocks(title="Blood Test Explainer") as demo:
         "border:0 !important;box-shadow:none !important;padding:0 !important;}</style>"
     )
     with gr.Row(equal_height=True, elem_classes=["bte-title"]):
-        with gr.Column(scale=1, min_width=420, elem_classes=["bte-title-copy"]):
+        with gr.Column(scale=2, min_width=260, elem_classes=["bte-title-copy"]):
             gr.HTML(
                 """
                 <div>
@@ -3260,7 +4299,9 @@ with gr.Blocks(title="Blood Test Explainer") as demo:
                 </div>
                 """
             )
-        with gr.Column(scale=0, min_width=300, elem_classes=["bte-title-attribution-wrap"]):
+        with gr.Column(scale=2, min_width=250, elem_classes=["bte-title-hackathon-wrap"]):
+            gr.HTML(hero_hackathon_panel_html())
+        with gr.Column(scale=0, min_width=260, elem_classes=["bte-title-credits-wrap"]):
             gr.HTML(hero_attribution_html())
 
     workflow_phase = gr.HTML(
@@ -3281,7 +4322,7 @@ with gr.Blocks(title="Blood Test Explainer") as demo:
           </div>
           <div class="bte-step-heading bte-step-heading--report">
             <span>3</span>
-            <h2>Get your blood test results in the clearest possible format</h2>
+            <h2>Review the agent pipeline steps for your blood tests</h2>
           </div>
         </div>
         """,
@@ -3292,10 +4333,10 @@ with gr.Blocks(title="Blood Test Explainer") as demo:
         with gr.Column(scale=4, min_width=320, elem_classes=["bte-workflow-panel", "bte-panel-upload"]):
             with gr.Group(elem_classes=["bte-shell", "bte-upload-card"]):
                 upload_hint = gr.HTML(
-                    '<p class="bte-upload-hint">Supported formats: PDF</p>',
+                    '<p class="bte-upload-hint">Supported formats: PDF, PNG, JPEG, WebP</p>',
                     elem_classes=["bte-upload-hint-wrap"],
                 )
-                with gr.Group() as upload_dropzone:
+                with gr.Group(elem_classes=["bte-upload-dropzone"]) as upload_dropzone:
                     uploaded = gr.File(
                         label="Upload medical test document",
                         file_count="single",
@@ -3303,13 +4344,21 @@ with gr.Blocks(title="Blood Test Explainer") as demo:
                         type="filepath",
                         elem_classes=["bte-uploader"],
                     )
-                selected_document = gr.HTML(selected_document_html(), visible=False)
+                selected_document = gr.HTML(
+                    selected_document_html(),
+                    visible=False,
+                    elem_classes=["bte-selected-document-wrap"],
+                )
 
         with gr.Column(scale=4, min_width=300, elem_classes=["bte-workflow-panel", "bte-panel-analysis"]):
             gr.HTML(analysis_animation_html())
 
-        with gr.Column(scale=4, min_width=300, elem_classes=["bte-workflow-panel", "bte-panel-result"]):
-            gr.HTML(result_preview_html())
+        with gr.Column(scale=4, min_width=300, elem_classes=["bte-workflow-panel", "bte-panel-result", "bte-panel-trace"]):
+            with gr.Group(elem_classes=["bte-shell", "bte-agent-panel"]):
+                agent_trace = gr.HTML(
+                    empty_trace_html(),
+                    elem_classes=["bte-agent-trace"],
+                )
 
     status = gr.HTML(
         _status_html("Ready", "Upload a lab report to create the first interactive extraction draft."),
@@ -3324,17 +4373,17 @@ with gr.Blocks(title="Blood Test Explainer") as demo:
     uploaded.change(
         upload_state,
         inputs=[uploaded],
-        outputs=[upload_dropzone, upload_hint, selected_document, workflow_phase],
+        outputs=[upload_dropzone, upload_hint, selected_document, workflow_phase, agent_trace],
         show_progress="hidden",
     ).then(
         show_processing,
-        outputs=[status, report_panel, report, workflow_phase],
+        outputs=[status, report_panel, report, workflow_phase, agent_trace],
         scroll_to_output=True,
         show_progress="hidden",
     ).then(
         extract_lab_values,
         inputs=[uploaded],
-        outputs=[status, report, report_panel, workflow_phase],
+        outputs=[status, report, report_panel, workflow_phase, agent_trace],
         scroll_to_output=True,
         show_progress="hidden",
     )

kb/cbc_knowledge_graph.json

@@ -39,7 +39,11 @@
     {
       "id": "hemoglobin",
       "display_name": "Hemoglobin",
-      "aliases": ["HGB", "Hb", "Hgb"],
+      "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.",
@@ -51,44 +55,137 @@
       },
       "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}
+          "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}
+          "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.8,
+            "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}
+          "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.8,
+            "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}
+          "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.8,
+            "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."]
+        "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}
+        "child": {
+          "minimal_value": 10.9,
+          "normal_value": 12.95,
+          "maximum_value": 15.0
+        },
+        "teenager": {
+          "minimal_value": 11.9,
+          "normal_value": 14.8,
+          "maximum_value": 17.7
+        },
+        "adult": {
+          "minimal_value": 11.9,
+          "normal_value": 14.8,
+          "maximum_value": 17.7
+        },
+        "elder": {
+          "minimal_value": 11.9,
+          "normal_value": 14.8,
+          "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"]
+      "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"],
+      "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.",
@@ -100,44 +197,129 @@
       },
       "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}
+          "male": {
+            "minimal_value": 3.8,
+            "normal_value": 4.65,
+            "maximum_value": 5.5
+          },
+          "female": {
+            "minimal_value": 3.8,
+            "normal_value": 4.65,
+            "maximum_value": 5.5
+          },
+          "unknown": {
+            "minimal_value": 3.8,
+            "normal_value": 4.65,
+            "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}
+          "male": {
+            "minimal_value": 4.3,
+            "normal_value": 4.95,
+            "maximum_value": 5.6
+          },
+          "female": {
+            "minimal_value": 3.9,
+            "normal_value": 4.5,
+            "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}
+          "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}
+          "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."]
+        "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}
+        "child": {
+          "minimal_value": 3.8,
+          "normal_value": 4.65,
+          "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"]
+      "related_tests": [
+        "hemoglobin",
+        "hct",
+        "mcv"
+      ],
+      "source_ids": [
+        "medlineplus_rbc",
+        "uiowa_cbc_reference"
+      ]
     },
     {
       "id": "hct",
       "display_name": "Hematocrit",
-      "aliases": ["HCT", "PCV", "Packed cell volume"],
+      "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.",
@@ -149,44 +331,128 @@
       },
       "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}
+          "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}
+          "male": {
+            "minimal_value": 37,
+            "normal_value": 43.0,
+            "maximum_value": 49
+          },
+          "female": {
+            "minimal_value": 36,
+            "normal_value": 41.0,
+            "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}
+          "male": {
+            "minimal_value": 40,
+            "normal_value": 46.0,
+            "maximum_value": 52
+          },
+          "female": {
+            "minimal_value": 35,
+            "normal_value": 41.0,
+            "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}
+          "male": {
+            "minimal_value": 40,
+            "normal_value": 46.0,
+            "maximum_value": 52
+          },
+          "female": {
+            "minimal_value": 35,
+            "normal_value": 41.0,
+            "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."]
+        "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}
+        "child": {
+          "minimal_value": 31,
+          "normal_value": 37.5,
+          "maximum_value": 44
+        },
+        "teenager": {
+          "minimal_value": 34,
+          "normal_value": 41.0,
+          "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"]
+      "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"],
+      "aliases": [
+        "MCV"
+      ],
       "category": "CBC red cell index",
       "unit": "fL",
       "description": "MCV measures the average size of red blood cells.",
@@ -197,23 +463,63 @@
         "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."]
+        "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}
+        "child": {
+          "minimal_value": 75,
+          "normal_value": 82.5,
+          "maximum_value": 90
+        },
+        "teenager": {
+          "minimal_value": 79,
+          "normal_value": 87.0,
+          "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"]
+      "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"],
+      "aliases": [
+        "MCH"
+      ],
       "category": "CBC red cell index",
       "unit": "pg",
       "description": "MCH estimates the average amount of hemoglobin in each red blood cell.",
@@ -224,23 +530,59 @@
         "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."]
+        "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}
+        "child": {
+          "minimal_value": 23,
+          "normal_value": 29.0,
+          "maximum_value": 35
+        },
+        "teenager": {
+          "minimal_value": 25,
+          "normal_value": 30.0,
+          "maximum_value": 35
+        },
+        "adult": {
+          "minimal_value": 25,
+          "normal_value": 30.0,
+          "maximum_value": 35
+        },
+        "elder": {
+          "minimal_value": 25,
+          "normal_value": 30.0,
+          "maximum_value": 35
+        }
       },
-      "related_tests": ["mcv", "mchc", "hemoglobin"],
-      "source_ids": ["uiowa_cbc_reference", "uiowa_pediatric_reference", "nih_ods_iron"]
+      "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"],
+      "aliases": [
+        "MCHC"
+      ],
       "category": "CBC red cell index",
       "unit": "g/dL",
       "description": "MCHC estimates the concentration of hemoglobin within red blood cells.",
@@ -251,23 +593,60 @@
         "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."]
+        "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}
+        "child": {
+          "minimal_value": 32,
+          "normal_value": 34.0,
+          "maximum_value": 36
+        },
+        "teenager": {
+          "minimal_value": 32,
+          "normal_value": 34.0,
+          "maximum_value": 36
+        },
+        "adult": {
+          "minimal_value": 32,
+          "normal_value": 34.0,
+          "maximum_value": 36
+        },
+        "elder": {
+          "minimal_value": 32,
+          "normal_value": 34.0,
+          "maximum_value": 36
+        }
       },
-      "related_tests": ["mch", "mcv", "hemoglobin"],
-      "source_ids": ["uiowa_cbc_reference", "uiowa_pediatric_reference"]
+      "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"],
+      "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.",
@@ -278,23 +657,61 @@
         "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."]
+        "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}
+        "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"]
+      "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"],
+      "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.",
@@ -305,23 +722,59 @@
         "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."]
+        "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}
+        "child": {
+          "minimal_value": 35.1,
+          "normal_value": 40.7,
+          "maximum_value": 46.3
+        },
+        "teenager": {
+          "minimal_value": 35.1,
+          "normal_value": 40.7,
+          "maximum_value": 46.3
+        },
+        "adult": {
+          "minimal_value": 35.1,
+          "normal_value": 40.7,
+          "maximum_value": 46.3
+        },
+        "elder": {
+          "minimal_value": 35.1,
+          "normal_value": 40.7,
+          "maximum_value": 46.3
+        }
       },
-      "related_tests": ["mcv", "rdw_cv", "hemoglobin"],
-      "source_ids": ["uiowa_cbc_reference"]
+      "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"],
+      "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.",
@@ -332,23 +785,66 @@
         "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."]
+        "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}
+        "child": {
+          "minimal_value": 5.5,
+          "normal_value": 11.25,
+          "maximum_value": 17.0
+        },
+        "teenager": {
+          "minimal_value": 4.5,
+          "normal_value": 7.75,
+          "maximum_value": 11.0
+        },
+        "adult": {
+          "minimal_value": 3.7,
+          "normal_value": 7.1,
+          "maximum_value": 10.5
+        },
+        "elder": {
+          "minimal_value": 3.7,
+          "normal_value": 7.1,
+          "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"]
+      "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"],
+      "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.",
@@ -359,23 +855,59 @@
         "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."]
+        "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}
+        "child": {
+          "minimal_value": 40,
+          "normal_value": 55.0,
+          "maximum_value": 70
+        },
+        "teenager": {
+          "minimal_value": 40,
+          "normal_value": 55.0,
+          "maximum_value": 70
+        },
+        "adult": {
+          "minimal_value": 40,
+          "normal_value": 55.0,
+          "maximum_value": 70
+        },
+        "elder": {
+          "minimal_value": 40,
+          "normal_value": 55.0,
+          "maximum_value": 70
+        }
       },
-      "related_tests": ["wbc", "gra_absolute"],
-      "source_ids": ["medlineplus_differential", "medlineplus_differential_encyclopedia"]
+      "related_tests": [
+        "wbc",
+        "gra_absolute"
+      ],
+      "source_ids": [
+        "medlineplus_differential",
+        "medlineplus_differential_encyclopedia"
+      ]
     },
     {
       "id": "lym_percent",
       "display_name": "Lymphocytes Percent",
-      "aliases": ["LYM%", "Lymphocyte %", "Lymphocytes"],
+      "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.",
@@ -386,23 +918,59 @@
         "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."]
+        "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}
+        "child": {
+          "minimal_value": 20,
+          "normal_value": 30.0,
+          "maximum_value": 40
+        },
+        "teenager": {
+          "minimal_value": 20,
+          "normal_value": 30.0,
+          "maximum_value": 40
+        },
+        "adult": {
+          "minimal_value": 20,
+          "normal_value": 30.0,
+          "maximum_value": 40
+        },
+        "elder": {
+          "minimal_value": 20,
+          "normal_value": 30.0,
+          "maximum_value": 40
+        }
       },
-      "related_tests": ["wbc", "lym_absolute"],
-      "source_ids": ["medlineplus_differential", "medlineplus_differential_encyclopedia"]
+      "related_tests": [
+        "wbc",
+        "lym_absolute"
+      ],
+      "source_ids": [
+        "medlineplus_differential",
+        "medlineplus_differential_encyclopedia"
+      ]
     },
     {
       "id": "mon_percent",
       "display_name": "Monocytes Percent",
-      "aliases": ["MON%", "Monocyte %", "Monocytes"],
+      "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.",
@@ -413,23 +981,58 @@
         "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."]
+        "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}
+        "child": {
+          "minimal_value": 2,
+          "normal_value": 5.0,
+          "maximum_value": 8
+        },
+        "teenager": {
+          "minimal_value": 2,
+          "normal_value": 5.0,
+          "maximum_value": 8
+        },
+        "adult": {
+          "minimal_value": 2,
+          "normal_value": 5.0,
+          "maximum_value": 8
+        },
+        "elder": {
+          "minimal_value": 2,
+          "normal_value": 5.0,
+          "maximum_value": 8
+        }
       },
-      "related_tests": ["wbc"],
-      "source_ids": ["medlineplus_differential", "medlineplus_differential_encyclopedia"]
+      "related_tests": [
+        "wbc"
+      ],
+      "source_ids": [
+        "medlineplus_differential",
+        "medlineplus_differential_encyclopedia"
+      ]
     },
     {
       "id": "eos_percent",
       "display_name": "Eosinophils Percent",
-      "aliases": ["EOS%", "Eosinophil %", "Eosinophils"],
+      "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.",
@@ -440,23 +1043,59 @@
         "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."]
+        "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}
+        "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"]
+      "related_tests": [
+        "wbc",
+        "bas_percent"
+      ],
+      "source_ids": [
+        "medlineplus_differential",
+        "medlineplus_differential_encyclopedia"
+      ]
     },
     {
       "id": "bas_percent",
       "display_name": "Basophils Percent",
-      "aliases": ["BAS%", "Basophil %", "Basophils"],
+      "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.",
@@ -467,23 +1106,60 @@
         "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."]
+        "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}
+        "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"]
+      "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"],
+      "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.",
@@ -494,23 +1170,61 @@
         "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."]
+        "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}
+        "child": {
+          "minimal_value": 2.0,
+          "normal_value": 5.75,
+          "maximum_value": 9.5
+        },
+        "teenager": {
+          "minimal_value": 1.25,
+          "normal_value": 4.12,
+          "maximum_value": 7.0
+        },
+        "adult": {
+          "minimal_value": 0.875,
+          "normal_value": 2.84,
+          "maximum_value": 4.8
+        },
+        "elder": {
+          "minimal_value": 0.875,
+          "normal_value": 2.84,
+          "maximum_value": 4.8
+        }
       },
-      "related_tests": ["lym_percent", "wbc"],
-      "source_ids": ["uiowa_pediatric_reference", "uchicago_cbc_diff", "medlineplus_differential"]
+      "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"],
+      "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.",
@@ -521,23 +1235,62 @@
         "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."]
+        "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}
+        "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.92,
+          "maximum_value": 6.72
+        },
+        "elder": {
+          "minimal_value": 1.12,
+          "normal_value": 3.92,
+          "maximum_value": 6.72
+        }
       },
-      "related_tests": ["neu_percent", "wbc", "eos_percent", "bas_percent"],
-      "source_ids": ["uiowa_pediatric_reference", "uchicago_cbc_diff", "medlineplus_differential"]
+      "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"],
+      "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.",
@@ -548,23 +1301,63 @@
         "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."]
+        "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}
+        "child": {
+          "minimal_value": 155,
+          "normal_value": 327.5,
+          "maximum_value": 500
+        },
+        "teenager": {
+          "minimal_value": 140,
+          "normal_value": 270.0,
+          "maximum_value": 400
+        },
+        "adult": {
+          "minimal_value": 150,
+          "normal_value": 275.0,
+          "maximum_value": 400
+        },
+        "elder": {
+          "minimal_value": 150,
+          "normal_value": 275.0,
+          "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"]
+      "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"],
+      "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.",
@@ -576,39 +1369,121 @@
       },
       "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}
+          "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}
+          "male": {
+            "minimal_value": 0,
+            "normal_value": 7.5,
+            "maximum_value": 15
+          },
+          "female": {
+            "minimal_value": 0,
+            "normal_value": 10.0,
+            "maximum_value": 20
+          },
+          "unknown": {
+            "minimal_value": 0,
+            "normal_value": 10.0,
+            "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}
+          "male": {
+            "minimal_value": 0,
+            "normal_value": 7.5,
+            "maximum_value": 15
+          },
+          "female": {
+            "minimal_value": 0,
+            "normal_value": 10.0,
+            "maximum_value": 20
+          },
+          "unknown": {
+            "minimal_value": 0,
+            "normal_value": 10.0,
+            "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}
+          "male": {
+            "minimal_value": 0,
+            "normal_value": 10.0,
+            "maximum_value": 20
+          },
+          "female": {
+            "minimal_value": 0,
+            "normal_value": 15.0,
+            "maximum_value": 30
+          },
+          "unknown": {
+            "minimal_value": 0,
+            "normal_value": 15.0,
+            "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."]
+        "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}
+        "child": {
+          "minimal_value": 0,
+          "normal_value": 5.0,
+          "maximum_value": 10
+        },
+        "teenager": {
+          "minimal_value": 0,
+          "normal_value": 10.0,
+          "maximum_value": 20
+        },
+        "adult": {
+          "minimal_value": 0,
+          "normal_value": 10.0,
+          "maximum_value": 20
+        },
+        "elder": {
+          "minimal_value": 0,
+          "normal_value": 15.0,
+          "maximum_value": 30
+        }
       },
-      "related_tests": ["wbc", "hemoglobin"],
-      "source_ids": ["medlineplus_esr", "seattle_childrens_esr", "uchicago_esr_reference", "cleveland_clinic_esr"]
+      "related_tests": [
+        "wbc",
+        "hemoglobin"
+      ],
+      "source_ids": [
+        "medlineplus_esr",
+        "seattle_childrens_esr",
+        "uchicago_esr_reference",
+        "cleveland_clinic_esr"
+      ]
     }
   ]
 }

kb/knowledge_base.py

@@ -65,6 +65,56 @@ KB: dict[str, MarkerKB] = {
         low="A low MCV (small red cells) is classically associated with iron deficiency or thalassemia.",
         questions=("Given my MCV, should we look for an iron or a B12 cause?",),
     ),
+    "MCH": MarkerKB(
+        high="A high MCH usually tracks with large red cells (high MCV) and similar causes such as B12 or folate deficiency.",
+        low="A low MCH usually tracks with small red cells (low MCV) and points toward iron deficiency.",
+        questions=("Does my MCH fit with my MCV and hemoglobin?",),
+    ),
+    "MCHC": MarkerKB(
+        high="A high MCHC may reflect spherocytosis or dehydration-related concentration.",
+        low="A low MCHC is common in iron-deficiency anemia where cells carry less hemoglobin.",
+        questions=("Could iron studies explain my low MCHC?",),
+    ),
+    "RDW": MarkerKB(
+        high="A high RDW means red cells vary more in size; it often appears early in iron, B12, or folate deficiency.",
+        low="A low RDW is usually not clinically significant.",
+        questions=("Does a high RDW suggest a mixed or early deficiency?",),
+    ),
+    "MPV": MarkerKB(
+        high="A high MPV means larger platelets, which can appear when the marrow is making new platelets quickly.",
+        low="A low MPV is usually not a concern on its own.",
+        questions=("Does my MPV fit with my platelet count?",),
+    ),
+    "Absolute Neutrophil Count": MarkerKB(
+        high="A high neutrophil count often accompanies bacterial infection, inflammation, or physical stress.",
+        low="A low neutrophil count raises infection risk and may follow viruses, medications, or bone-marrow issues.",
+        questions=("Could an infection explain my neutrophil count?", "If low, do I need extra precautions?"),
+    ),
+    "Absolute Lymphocyte Count": MarkerKB(
+        high="A high lymphocyte count may follow viral infections or certain immune conditions.",
+        low="A low lymphocyte count can follow stress, steroids, or immune conditions.",
+        questions=("Was this drawn during or after an illness?",),
+    ),
+    "Absolute Monocyte Count": MarkerKB(
+        high="A high monocyte count may appear during recovery from infection or with chronic inflammation.",
+        low="A low monocyte count is rarely significant on its own.",
+        questions=("Does this fit with a recent or ongoing infection?",),
+    ),
+    "Absolute Eosinophil Count": MarkerKB(
+        high="A high eosinophil count is classically linked to allergies, asthma, or parasitic infection.",
+        low="A low eosinophil count is usually not a concern.",
+        questions=("Could allergies or asthma explain this?",),
+    ),
+    "Absolute Basophil Count": MarkerKB(
+        high="A high basophil count is uncommon and may relate to allergy or certain blood disorders.",
+        low="A low basophil count is usually not significant.",
+        questions=("Is this a persistent finding worth rechecking?",),
+    ),
+    "Reticulocyte Count": MarkerKB(
+        high="A high reticulocyte count means the marrow is making extra red cells, often after blood loss or hemolysis.",
+        low="A low reticulocyte count in anemia suggests the marrow is not keeping up with red-cell need.",
+        questions=("Is my body replacing red cells appropriately?",),
+    ),
     # --- Metabolic panel ---
     "Glucose": MarkerKB(
         high="An elevated fasting glucose can indicate prediabetes or diabetes, or simply that the sample was not fasting.",
@@ -116,6 +166,91 @@ KB: dict[str, MarkerKB] = {
         low="May reflect nutrition, liver, or kidney factors.",
         questions=("Does this fit with my albumin level?",),
     ),
+    "Globulin": MarkerKB(
+        high="A high globulin may reflect increased antibodies from infection, inflammation, or immune conditions.",
+        low="A low globulin may reflect reduced antibody production or liver disease.",
+        questions=("Does the albumin/globulin ratio need follow-up?",),
+    ),
+    "Bicarbonate": MarkerKB(
+        high="A high bicarbonate may reflect metabolic alkalosis or compensation for lung issues.",
+        low="A low bicarbonate may reflect metabolic acidosis or severe diarrhea.",
+        questions=("Does this fit with my other electrolytes and symptoms?",),
+    ),
+    "Anion Gap": MarkerKB(
+        high="A high anion gap often points to acid buildup from ketones, lactate, toxins, or kidney failure.",
+        low="A low anion gap is uncommon and usually less urgent.",
+        questions=("Could this relate to dehydration, diabetes, or kidney function?",),
+    ),
+    "Magnesium": MarkerKB(
+        high="A high magnesium is uncommon outside supplements or severe kidney impairment.",
+        low="A low magnesium can cause cramps, tremor, or heart rhythm issues and often accompanies low potassium.",
+        questions=("Should we recheck magnesium and potassium together?",),
+    ),
+    "Phosphate": MarkerKB(
+        high="A high phosphate may relate to kidney disease, low parathyroid activity, or cell breakdown.",
+        low="A low phosphate may relate to malnutrition, alcohol, or overcorrection of vitamin D.",
+        questions=("Does this fit with my calcium and kidney results?",),
+    ),
+    "Uric Acid": MarkerKB(
+        high="A high uric acid is associated with gout and kidney stones and may rise with diet, alcohol, or kidney disease.",
+        low="A low uric acid is usually not a concern.",
+        questions=("Could diet or medications be contributing?",),
+    ),
+    "Serum Iron": MarkerKB(
+        high="A high serum iron may reflect supplements, hemochromatosis, or recent infusion.",
+        low="A low serum iron often accompanies iron-deficiency anemia but varies with recent meals and inflammation.",
+        questions=("Should we interpret this with ferritin and TIBC?",),
+    ),
+    "TIBC": MarkerKB(
+        high="A high TIBC often means the body is trying to bind more iron during iron deficiency.",
+        low="A low TIBC may appear with inflammation or iron overload.",
+        questions=("Does TIBC fit with my ferritin and transferrin saturation?",),
+    ),
+    "Transferrin Saturation": MarkerKB(
+        high="A high saturation may suggest iron overload or excess intake.",
+        low="A low saturation is common in iron deficiency.",
+        questions=("Is this consistent with my ferritin and hemoglobin?",),
+    ),
+    "LDH": MarkerKB(
+        high="LDH is a nonspecific marker of cell damage from hemolysis, liver injury, muscle injury, or malignancy.",
+        low="A low LDH is not typically a concern.",
+        questions=("What might be causing cell turnover or damage?",),
+    ),
+    "Osmolality": MarkerKB(
+        high="A high osmolality may reflect dehydration, high blood sugar, or excess sodium.",
+        low="A low osmolality may reflect overhydration or low sodium.",
+        questions=("Does this match my sodium and glucose?",),
+    ),
+    "Ammonia": MarkerKB(
+        high="A high ammonia may relate to liver disease and can affect mental status.",
+        low="A low ammonia is not typically significant.",
+        questions=("Should liver function be evaluated if ammonia is high?",),
+    ),
+    "Lactate": MarkerKB(
+        high="A high lactate may reflect poor tissue oxygen delivery, sepsis, or strenuous exercise at draw time.",
+        low="A low lactate is not a concern.",
+        questions=("Was the sample handled promptly?", "Could infection or low blood pressure explain this?"),
+    ),
+    "Homocysteine": MarkerKB(
+        high="A high homocysteine may relate to low B vitamins and is linked to vascular risk in research.",
+        low="A low homocysteine is generally favorable.",
+        questions=("Should we check B12 and folate?",),
+    ),
+    "Cystatin C": MarkerKB(
+        high="A high cystatin C suggests reduced kidney filtration, similar to creatinine but less muscle-dependent.",
+        low="A low cystatin C is usually not a concern.",
+        questions=("How does this compare with my creatinine and eGFR?",),
+    ),
+    "Prealbumin": MarkerKB(
+        high="A high prealbumin is uncommon and may reflect steroids or kidney loss of protein.",
+        low="A low prealbumin may reflect recent poor nutrition or inflammation.",
+        questions=("Could nutrition or inflammation be affecting this?",),
+    ),
+    "Beta-2 Microglobulin": MarkerKB(
+        high="A high beta-2 microglobulin may reflect increased cell turnover, kidney impairment, or certain blood conditions.",
+        low="A low beta-2 microglobulin is not typically significant.",
+        questions=("Should this be interpreted with kidney function?",),
+    ),
     # --- Liver enzymes ---
     "ALT": MarkerKB(
         high="ALT is fairly liver-specific; elevations can follow fatty liver, alcohol, medications, or viral hepatitis.",
@@ -142,6 +277,21 @@ KB: dict[str, MarkerKB] = {
         low="A low bilirubin is not a concern.",
         questions=("Is this mild and stable, or does it need follow-up?",),
     ),
+    "Direct Bilirubin": MarkerKB(
+        high="A high direct bilirubin suggests the liver or bile ducts are not processing bilirubin normally.",
+        low="A low direct bilirubin is not a concern.",
+        questions=("Does this point to a liver or bile-duct issue?",),
+    ),
+    "Lipase": MarkerKB(
+        high="A high lipase commonly points to pancreatic inflammation but can rise with other abdominal conditions.",
+        low="A low lipase is not typically significant.",
+        questions=("Could abdominal pain relate to this lipase?",),
+    ),
+    "Amylase": MarkerKB(
+        high="A high amylase may reflect pancreatic or salivary-gland inflammation.",
+        low="A low amylase is rarely significant.",
+        questions=("Should lipase be checked alongside amylase?",),
+    ),
     # --- Lipid panel ---
     "Total Cholesterol": MarkerKB(
         high="A high total cholesterol contributes to cardiovascular risk and is best read alongside LDL, HDL, and your overall risk.",
@@ -163,6 +313,26 @@ KB: dict[str, MarkerKB] = {
         low="A low triglyceride level is generally not a concern.",
         questions=("Was this fasting?", "Would diet changes help?"),
     ),
+    "Non-HDL Cholesterol": MarkerKB(
+        high="Non-HDL cholesterol captures all atherogenic particles and adds to cardiovascular risk.",
+        low="A low non-HDL cholesterol is generally favorable.",
+        questions=("What non-HDL target fits my overall risk?",),
+    ),
+    "Apolipoprotein B": MarkerKB(
+        high="Apo B reflects the number of LDL-like particles and is linked to plaque risk.",
+        low="A low Apo B is generally favorable.",
+        questions=("How does Apo B compare with my LDL?",),
+    ),
+    "Apolipoprotein A-1": MarkerKB(
+        high="A higher Apo A-1 is generally associated with more HDL and lower cardiovascular risk.",
+        low="A low Apo A-1 may accompany low HDL and higher risk.",
+        questions=("Would exercise or not smoking help raise HDL/Apo A-1?",),
+    ),
+    "Lipoprotein(a)": MarkerKB(
+        high="Lp(a) is largely genetic and adds cardiovascular risk independent of LDL.",
+        low="A low Lp(a) is generally favorable.",
+        questions=("Does my family history fit with a high Lp(a)?",),
+    ),
     # --- Thyroid ---
     "TSH": MarkerKB(
         high="A high TSH usually signals an underactive thyroid (the body asking for more hormone).",
@@ -174,6 +344,26 @@ KB: dict[str, MarkerKB] = {
         low="A low Free T4 supports an underactive thyroid picture.",
         questions=("How does this fit with my TSH?",),
     ),
+    "Free T3": MarkerKB(
+        high="A high Free T3 supports an overactive thyroid picture.",
+        low="A low Free T3 may appear in underactive thyroid or severe illness.",
+        questions=("How does Free T3 fit with my TSH and Free T4?",),
+    ),
+    "Total T4": MarkerKB(
+        high="A high Total T4 may reflect hyperthyroidism or high thyroid-binding proteins.",
+        low="A low Total T4 may reflect hypothyroidism or binding-protein changes.",
+        questions=("Should Free T4 be used for interpretation?",),
+    ),
+    "Total T3": MarkerKB(
+        high="A high Total T3 may reflect hyperthyroidism.",
+        low="A low Total T3 may appear in hypothyroidism or non-thyroidal illness.",
+        questions=("Does this match my TSH and Free T3?",),
+    ),
+    "Anti-TPO Antibodies": MarkerKB(
+        high="Anti-TPO antibodies suggest autoimmune thyroid disease such as Hashimoto's.",
+        low="A negative or low Anti-TPO is expected in most people without autoimmune thyroid disease.",
+        questions=("Could this explain my thyroid symptoms or TSH changes?",),
+    ),
     # --- Vitamins / iron ---
     "Vitamin D": MarkerKB(
         high="A very high vitamin D is uncommon and usually from supplements.",
@@ -195,6 +385,166 @@ KB: dict[str, MarkerKB] = {
         low="A low HbA1c is generally not a concern.",
         questions=("Am I in the prediabetes range?", "What changes would lower this?"),
     ),
+    # --- Coagulation ---
+    "Prothrombin Time": MarkerKB(
+        high="A prolonged PT means clotting takes longer and may relate to warfarin, liver disease, or clotting-factor deficiency.",
+        low="A shorter PT is usually not clinically flagged.",
+        questions=("Am I on blood thinners?", "Should INR be checked instead?"),
+    ),
+    "INR": MarkerKB(
+        high="A high INR means slower clotting; it is expected on warfarin but dangerous if unintentionally high.",
+        low="A low INR on warfarin may mean under-anticoagulation.",
+        questions=("What INR range am I aiming for?",),
+    ),
+    "aPTT": MarkerKB(
+        high="A prolonged aPTT may relate to heparin, lupus anticoagulant, or clotting-factor deficiency.",
+        low="A shorter aPTT is rarely flagged alone.",
+        questions=("Am I on heparin or do I bruise easily?",),
+    ),
+    "Fibrinogen": MarkerKB(
+        high="A high fibrinogen may reflect inflammation or increased clotting tendency.",
+        low="A low fibrinogen may increase bleeding risk.",
+        questions=("Could inflammation explain a high fibrinogen?",),
+    ),
+    "D-Dimer": MarkerKB(
+        high="A high D-dimer suggests active clot breakdown but is nonspecific and rises with infection, surgery, or pregnancy.",
+        low="A low D-dimer makes significant clotting less likely in the right clinical context.",
+        questions=("Was this ordered because of leg pain or shortness of breath?",),
+    ),
+    # --- Inflammation / immune ---
+    "C-Reactive Protein": MarkerKB(
+        high="A high CRP indicates inflammation from infection, autoimmune disease, or tissue injury.",
+        low="A low CRP is expected in the absence of significant inflammation.",
+        questions=("Could a recent infection explain this?",),
+    ),
+    "hs-CRP": MarkerKB(
+        high="An elevated hs-CRP adds to cardiovascular risk even when general CRP is low-grade.",
+        low="A low hs-CRP is generally favorable for heart risk.",
+        questions=("What lifestyle changes would lower my cardiovascular risk?",),
+    ),
+    "ESR": MarkerKB(
+        high="A high ESR is a nonspecific sign of inflammation, infection, or autoimmune activity.",
+        low="A low ESR is usually not a concern.",
+        questions=("Does this fit with my symptoms or other inflammatory markers?",),
+    ),
+    "Procalcitonin": MarkerKB(
+        high="A high procalcitonin more specifically suggests bacterial infection.",
+        low="A low procalcitonin makes serious bacterial infection less likely.",
+        questions=("Was this drawn during a fever or suspected infection?",),
+    ),
+    "Complement C3": MarkerKB(
+        high="A high C3 may appear during acute inflammation.",
+        low="A low C3 may appear in active autoimmune disease or complement consumption.",
+        questions=("Should this be read with other immune tests?",),
+    ),
+    "Complement C4": MarkerKB(
+        high="A high C4 is less commonly flagged than low values.",
+        low="A low C4 may appear in autoimmune conditions such as lupus.",
+        questions=("Do my symptoms fit an autoimmune pattern?",),
+    ),
+    "Rheumatoid Factor": MarkerKB(
+        high="A positive rheumatoid factor may appear in rheumatoid arthritis and other conditions.",
+        low="A negative rheumatoid factor does not rule out arthritis.",
+        questions=("Do my joints hurt or swell, especially in the morning?",),
+    ),
+    # --- Cardiac ---
+    "BNP": MarkerKB(
+        high="A high BNP suggests the heart is under strain, as in heart failure or fluid overload.",
+        low="A low BNP makes significant heart failure less likely.",
+        questions=("Do I have shortness of breath or leg swelling?",),
+    ),
+    "Troponin I": MarkerKB(
+        high="A high troponin indicates heart-muscle injury and needs urgent clinical evaluation.",
+        low="A low troponin is expected when there is no heart injury.",
+        questions=("Was chest pain or pressure present when this was drawn?",),
+    ),
+    "Creatine Kinase": MarkerKB(
+        high="A high CK may reflect muscle injury from exercise, trauma, statins, or heart muscle damage.",
+        low="A low CK is not typically significant.",
+        questions=("Did I exercise heavily before the blood draw?", "Am I on a statin?"),
+    ),
+    "CK-MB": MarkerKB(
+        high="A high CK-MB raises concern for heart-muscle injury when troponin is also elevated.",
+        low="A low CK-MB is expected without heart injury.",
+        questions=("Was this checked because of chest symptoms?",),
+    ),
+    # --- Hormones ---
+    "Cortisol": MarkerKB(
+        high="A high cortisol may reflect stress, steroids, Cushing syndrome, or lab timing.",
+        low="A low cortisol may relate to adrenal insufficiency and can cause fatigue or low blood pressure.",
+        questions=("Was this a morning sample?", "Am I on steroid medications?"),
+    ),
+    "Insulin": MarkerKB(
+        high="A high insulin may reflect insulin resistance even when glucose is still normal.",
+        low="A low insulin may appear in type 1 diabetes or long-standing type 2 diabetes.",
+        questions=("Should we assess insulin resistance or diabetes risk?",),
+    ),
+    "Testosterone": MarkerKB(
+        high="A high testosterone may relate to supplements, tumors, or polycystic ovary syndrome in women.",
+        low="A low testosterone may cause fatigue, low libido, or muscle loss in men.",
+        questions=("Could symptoms match my testosterone level?",),
+    ),
+    "Estradiol": MarkerKB(
+        high="A high estradiol may relate to ovarian function, obesity, or hormone therapy.",
+        low="A low estradiol may relate to menopause, ovarian failure, or low body weight.",
+        questions=("Where am I in my cycle or menopause status?",),
+    ),
+    "Prolactin": MarkerKB(
+        high="A high prolactin may cause menstrual changes or milk production and can come from pituitary issues or medications.",
+        low="A low prolactin is usually not a concern.",
+        questions=("Am I on medications that raise prolactin?",),
+    ),
+    "FSH": MarkerKB(
+        high="A high FSH in women often suggests reduced ovarian reserve or menopause; in men it may suggest testicular failure.",
+        low="A low FSH may relate to pituitary or hypothalamic issues.",
+        questions=("Are fertility or menopause questions relevant?",),
+    ),
+    "LH": MarkerKB(
+        high="A high LH may appear at menopause or with polycystic ovary syndrome depending on context.",
+        low="A low LH may relate to pituitary or hypothalamic causes of low sex hormones.",
+        questions=("Should LH be read with FSH and estradiol or testosterone?",),
+    ),
+    "Progesterone": MarkerKB(
+        high="A high progesterone may reflect the luteal phase, pregnancy, or supplementation.",
+        low="A low progesterone may relate to anovulation or luteal-phase deficiency.",
+        questions=("What day of my cycle was this drawn?",),
+    ),
+    "Parathyroid Hormone": MarkerKB(
+        high="A high PTH may drive calcium up in primary hyperparathyroidism or rise appropriately when calcium is low.",
+        low="A low PTH may appear after parathyroid surgery or with high calcium from other causes.",
+        questions=("How does PTH fit with my calcium and vitamin D?",),
+    ),
+    "ACTH": MarkerKB(
+        high="A high ACTH may appear when the adrenal glands are underactive or in certain tumors.",
+        low="A low ACTH may appear with steroid use or pituitary causes of low cortisol.",
+        questions=("Should ACTH be read with cortisol?",),
+    ),
+    "SHBG": MarkerKB(
+        high="A high SHBG binds more testosterone and estrogen, lowering their free fractions.",
+        low="A low SHBG is linked to insulin resistance and higher free androgen activity.",
+        questions=("Should free testosterone be calculated?",),
+    ),
+    "IGF-1": MarkerKB(
+        high="A high IGF-1 may reflect excess growth hormone.",
+        low="A low IGF-1 may reflect growth-hormone deficiency or malnutrition.",
+        questions=("Are height, hands, or jaw changes relevant?",),
+    ),
+    # --- Oncology / screening ---
+    "PSA": MarkerKB(
+        high="A high PSA may come from prostate enlargement, infection, recent procedures, or less commonly cancer.",
+        low="A low PSA is expected and does not rule out all prostate conditions.",
+        questions=("Could recent exercise or infection have raised PSA?", "Is repeat testing planned?"),
+    ),
+    "Folate": MarkerKB(
+        high="A high folate is usually from supplements or fortified foods.",
+        low="A low folate can cause anemia similar to B12 deficiency and affects DNA synthesis.",
+        questions=("Could low folate explain my MCV or anemia?",),
+    ),
+    "Vitamin A": MarkerKB(
+        high="A very high vitamin A is usually from supplements and can be toxic.",
+        low="A low vitamin A may affect vision and immunity and relates to diet or malabsorption.",
+        questions=("Am I taking vitamin A supplements?",),
+    ),
 }
 
 
@@ -249,6 +599,36 @@ PATTERNS: tuple[Pattern, ...] = (
         "high Glucose with high HbA1c",
         "A high spot glucose backed by a high HbA1c is a stronger signal of impaired blood-sugar control than either alone.",
     ),
+    Pattern(
+        "Iron studies pattern",
+        "low Ferritin with low Serum Iron and low Transferrin Saturation",
+        "Low iron stores with low circulating iron and saturation strongly supports iron deficiency as a cause of anemia.",
+    ),
+    Pattern(
+        "Infection / inflammation cluster",
+        "high White Blood Cell Count with high C-Reactive Protein or high Procalcitonin",
+        "Together these suggest an active inflammatory or infectious process worth clinical correlation.",
+    ),
+    Pattern(
+        "Coagulation concern",
+        "prolonged Prothrombin Time or high INR with prolonged aPTT",
+        "Multiple clotting tests abnormal together raise bleeding risk and medication or liver causes should be reviewed.",
+    ),
+    Pattern(
+        "Cardiac strain pattern",
+        "high BNP with high Troponin I",
+        "Elevated heart-strain and injury markers together warrant urgent clinical assessment.",
+    ),
+    Pattern(
+        "Pancreatic enzyme pattern",
+        "high Lipase with high Amylase",
+        "Both pancreatic enzymes elevated together more strongly suggest pancreatic inflammation than either alone.",
+    ),
+    Pattern(
+        "Autoimmune thyroid pattern",
+        "high Anti-TPO Antibodies with abnormal TSH",
+        "Thyroid autoantibodies plus abnormal TSH suggest autoimmune thyroid disease rather than a transient lab variation.",
+    ),
 )
 
 

requirements.txt

@@ -4,13 +4,12 @@ requests==2.32.5
 pillow==12.0.0
 pymupdf==1.26.6
 json-repair==0.60.1
-# ZeroGPU/CUDA path for EXTRACTOR_BACKEND=auto: the app uses the official OpenBMB
-# Transformers pipeline when ACCELERATOR is ZeroGPU, ZERO_GPU=TRUE, or CUDA is visible.
-torch==2.9.1 ; sys_platform == "linux" and platform_machine == "x86_64"
+# Local Transformers vision path (Mac + Linux GPU). Default EXTRACTOR_BACKEND=transformers.
+torch==2.9.1 ; sys_platform == "darwin" or (sys_platform == "linux" and platform_machine == "x86_64")
 transformers[torch]==5.7.0
 accelerate==1.12.0
 bitsandbytes==0.48.2 ; sys_platform == "linux" and platform_machine == "x86_64"
-torchvision==0.24.1 ; sys_platform == "linux" and platform_machine == "x86_64"
+torchvision==0.24.1 ; sys_platform == "darwin" or (sys_platform == "linux" and platform_machine == "x86_64")
 av==16.0.1 ; sys_platform == "linux" and platform_machine == "x86_64"
 # CPU fallback path: install the prebuilt manylinux wheel directly to avoid a source build on Spaces.
 llama-cpp-python @ https://github.com/abetlen/llama-cpp-python/releases/download/v0.3.28/llama_cpp_python-0.3.28-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl ; sys_platform == "linux" and platform_machine == "x86_64"

src/document_processing.py

@@ -1,12 +1,18 @@
 from __future__ import annotations
 
+import base64
+import io
 from pathlib import Path
 
 import fitz
 
-
 SUPPORTED_TEXT_EXTENSIONS = {".txt", ".csv"}
-SUPPORTED_EXTENSIONS = SUPPORTED_TEXT_EXTENSIONS | {".pdf"}
+SUPPORTED_IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg", ".webp", ".tif", ".tiff"}
+SUPPORTED_EXTENSIONS = SUPPORTED_TEXT_EXTENSIONS | SUPPORTED_IMAGE_EXTENSIONS | {".pdf"}
+
+_DEFAULT_MAX_PAGES = 3
+_PDF_RENDER_MATRIX = fitz.Matrix(2.5, 2.5)
+_MAX_IMAGE_EDGE = 2048
 
 
 def validate_upload(path: str) -> Path:
@@ -22,12 +28,31 @@ def validate_upload(path: str) -> Path:
     return file_path
 
 
+def document_intake_metadata(path: str, parts: list[dict]) -> dict[str, object]:
+    """Lightweight intake stats for traces (no base64 payloads)."""
+    extension = Path(path).suffix.lower()
+    image_count = sum(1 for part in parts if part.get("type") == "image_url")
+    text_characters = sum(len(str(part.get("text") or "")) for part in parts if part.get("type") == "text")
+    return {
+        "source_extension": extension,
+        "input_modality": "vision" if image_count else "text",
+        "pages_rendered": image_count if extension == ".pdf" else None,
+        "image_count": image_count,
+        "text_characters": text_characters,
+    }
+
+
 def document_to_payload_parts(path: str, max_pages: int | None = None) -> list[dict]:
+    """Build OpenAI-compatible message parts for vision extraction."""
     file_path = validate_upload(path)
     extension = file_path.suffix.lower()
+    page_limit = _DEFAULT_MAX_PAGES if max_pages is None else max_pages
 
     if extension == ".pdf":
-        return [{"type": "text", "text": _pdf_to_text(file_path, max_pages=max_pages)}]
+        return _pdf_to_image_parts(file_path, max_pages=page_limit)
+
+    if extension in SUPPORTED_IMAGE_EXTENSIONS:
+        return [_image_part(file_path)]
 
     if extension in SUPPORTED_TEXT_EXTENSIONS:
         return [{"type": "text", "text": _read_text_file(file_path)}]
@@ -35,26 +60,41 @@ def document_to_payload_parts(path: str, max_pages: int | None = None) -> list[d
     raise ValueError(f"Unsupported file type `{extension}`.")
 
 
-def _pdf_to_text(file_path: Path, max_pages: int | None) -> str:
-    chunks: list[str] = []
+def _pdf_to_image_parts(file_path: Path, max_pages: int) -> list[dict]:
+    parts: list[dict] = []
     with fitz.open(file_path) as document:
         if document.page_count == 0:
             raise ValueError("The uploaded PDF does not contain any pages.")
 
-        pages_to_read = document.page_count if max_pages is None else min(document.page_count, max_pages)
-        for page_index in range(pages_to_read):
+        pages_to_render = min(document.page_count, max(1, max_pages))
+        for page_index in range(pages_to_render):
             page = document.load_page(page_index)
-            text = page.get_text("text").strip()
-            if text:
-                chunks.append(f"[Page {page_index + 1}]\n{text}")
-
-    text = "\n\n".join(chunks).strip()
-    if not text:
-        raise ValueError(
-            "The uploaded PDF does not contain extractable text. "
-            "Please use a text-based PDF rather than a scanned image."
-        )
-    return text[:30000]
+            pixmap = page.get_pixmap(matrix=_PDF_RENDER_MATRIX, alpha=False)
+            encoded = base64.b64encode(pixmap.tobytes("png")).decode("ascii")
+            parts.append(
+                {
+                    "type": "image_url",
+                    "image_url": {"url": f"data:image/png;base64,{encoded}"},
+                }
+            )
+
+    return parts
+
+
+def _image_part(file_path: Path) -> dict:
+    from PIL import Image, ImageOps
+
+    with Image.open(file_path) as image:
+        image = ImageOps.exif_transpose(image).convert("RGB")
+        image.thumbnail((_MAX_IMAGE_EDGE, _MAX_IMAGE_EDGE))
+        buffer = io.BytesIO()
+        image.save(buffer, format="JPEG", quality=90, optimize=True)
+        encoded = base64.b64encode(buffer.getvalue()).decode("ascii")
+
+    return {
+        "type": "image_url",
+        "image_url": {"url": f"data:image/jpeg;base64,{encoded}"},
+    }
 
 
 def _read_text_file(file_path: Path) -> str:

src/extraction/__init__.py

@@ -1,13 +1,12 @@
 """Extraction backends behind one interface.
 
 `build_extractor()` returns the right backend for the environment:
-  - **auto**: Transformers on ZeroGPU/CUDA; CPU llama.cpp otherwise.
-  - **zerogpu** / **transformers**: force official OpenBMB MiniCPM-V through Transformers.
+  - **transformers** (default): local OpenBMB MiniCPM-V through Transformers.
+  - **auto**: same as transformers.
   - **llamacpp-gpu** / **llama-champion**: force GGUF through llama.cpp.
   - **local**: local llama-server / llama.cpp backends for local experimentation.
-  - **api**: the original OpenBMB hosted endpoint, kept as a dev fallback only.
 
-Default is `auto`.
+The hosted OpenBMB HTTP API is disabled.
 """
 
 from src.extraction.base import Extractor, ExtractionResult

src/extraction/auto.py

@@ -5,85 +5,33 @@ from __future__ import annotations
 import os
 
 from src.extraction.base import Extractor
-from src.extraction.llamacpp_gpu import LlamaCppGPUExtractor
 from src.extraction.zerogpu_transformers import ZeroGPUTransformersExtractor
 
 
 class AutoExtractor:
-    """Use Transformers on ZeroGPU/CUDA, otherwise use CPU llama.cpp."""
+    """Use the local Transformers MiniCPM-V path."""
 
     def __init__(self, model_id: str | None = None) -> None:
         self.model_id = model_id
         self._selected: Extractor | None = None
 
     def extract(self, file_path: str, max_pages: int = 3):
-        backend = self._backend()
-        try:
-            return backend.extract(file_path, max_pages=max_pages)
-        except Exception as exc:
-            if not isinstance(backend, ZeroGPUTransformersExtractor) or not _fallback_enabled():
-                raise
+        return self._backend().extract(file_path, max_pages=max_pages)
 
+    def _backend(self) -> Extractor:
+        if self._selected is None:
+            from src.model_paths import resolve_transformers_model_source
+
+            source = resolve_transformers_model_source(self.model_id)
             print(
-                "[Blood Test Explainer] CUDA Transformers backend failed; "
-                f"falling back to CPU llama.cpp. Inner error: {type(exc).__name__}: {exc}",
+                "[Blood Test Explainer] using Transformers extractor "
+                f"(origin={source.origin}, model={source.model_id})",
                 flush=True,
             )
-            self._selected = LlamaCppGPUExtractor()
-            return self._selected.extract(file_path, max_pages=max_pages)
-
-    def _backend(self) -> Extractor:
-        if self._selected is None:
-            target = runtime_target()
-            print(f"[Blood Test Explainer] auto extractor selected {target}", flush=True)
-            if target == "transformers":
-                self._selected = ZeroGPUTransformersExtractor(model_id=self.model_id)
-            else:
-                self._selected = LlamaCppGPUExtractor()
+            self._selected = ZeroGPUTransformersExtractor(model_id=self.model_id)
         return self._selected
 
 
 def runtime_target() -> str:
-    """Return `transformers` for ZeroGPU/CUDA and `llamacpp` for CPU-only runtime."""
-    if zerogpu_runtime_requested() or cuda_available():
-        return "transformers"
-    return "llamacpp"
-
-
-def zerogpu_runtime_requested() -> bool:
-    """Detect HF ZeroGPU from explicit Space/runtime environment flags.
-
-    ZeroGPU exposes CUDA only inside a `@spaces.GPU` worker, so checking
-    `torch.cuda.is_available()` in normal Gradio app code is not enough.
-    """
-    boolean_flags = ("ZERO_GPU", "SPACES_ZERO_GPU", "HF_ZERO_GPU", "BTE_ZERO_GPU")
-    for name in boolean_flags:
-        value = os.getenv(name, "").strip().lower()
-        if value in {"1", "true", "yes", "on", "zerogpu", "zero-gpu"}:
-            return True
-
-    hardware_flags = ("ACCELERATOR", "BTE_RUNTIME", "BTE_HARDWARE", "SPACE_HARDWARE", "HF_SPACE_HARDWARE")
-    for name in hardware_flags:
-        value = os.getenv(name, "").strip().lower()
-        if "zero" in value and "gpu" in value:
-            return True
-        if value.startswith("zero-"):
-            return True
-
-    return False
-
-
-def cuda_available() -> bool:
-    try:
-        import torch
-    except Exception:
-        return False
-
-    try:
-        return bool(torch.cuda.is_available())
-    except Exception:
-        return False
-
-
-def _fallback_enabled() -> bool:
-    return os.getenv("AUTO_FALLBACK_TO_LLAMACPP", "0").strip().lower() in {"1", "true", "yes", "on"}
+    """Local app always runs through Transformers."""
+    return "transformers"

src/extraction/factory.py

@@ -1,12 +1,14 @@
 """Backend selection.
 
 `EXTRACTOR_BACKEND` env:
-  - `auto`: Transformers on ZeroGPU/CUDA, CPU llama.cpp otherwise.
+  - `transformers` (default): local OpenBMB MiniCPM-V through Transformers.
+  - `auto`: same as `transformers`.
+  - `zerogpu` / `zero-gpu`: alias for `transformers`.
   - `llamacpp-gpu` / `llama-champion`: llama.cpp GGUF badge path.
-  - `zerogpu` / `transformers`: official OpenBMB Transformers backend.
-  - `api`: hosted OpenBMB endpoint (dev fallback only).
   - `local` / `server`: local llama-server backend for local development.
   - `llamacpp`: in-process llama-cpp-python backend for local development.
+
+The hosted OpenBMB HTTP API is disabled in this project.
 """
 
 from __future__ import annotations
@@ -19,40 +21,26 @@ from src.extraction.llamacpp_gpu import LlamaCppGPUExtractor
 from src.extraction.local_minicpmv import LocalMiniCPMVExtractor
 from src.extraction.local_server import LocalServerExtractor
 from src.extraction.zerogpu_transformers import ZeroGPUTransformersExtractor
-from src.openbmb_client import OpenBMBExtractor
+
+_DEFAULT_BACKEND = "transformers"
+_DISABLED_BACKENDS = {"api", "openbmb", "hosted"}
 
 
-def build_extractor(
-    api_url: str | None = None,
-    model: str | None = None,
-    api_key: str | None = None,
-) -> Extractor:
-    backend = os.getenv("EXTRACTOR_BACKEND", "auto").strip().lower()
+def build_extractor(model: str | None = None) -> Extractor:
+    backend = os.getenv("EXTRACTOR_BACKEND", _DEFAULT_BACKEND).strip().lower()
 
-    if backend == "auto":
+    if backend in _DISABLED_BACKENDS:
+        raise ValueError(
+            "The hosted OpenBMB API backend is disabled. "
+            "Use EXTRACTOR_BACKEND=transformers for local MiniCPM-V extraction."
+        )
+
+    if backend in ("auto", "zerogpu", "zero-gpu", "transformers"):
         return AutoExtractor(model_id=model)
     if backend in ("llamacpp-gpu", "gpu-llamacpp", "llama-champion"):
         return LlamaCppGPUExtractor()
-    if backend in ("zerogpu", "zero-gpu", "transformers"):
-        return ZeroGPUTransformersExtractor(model_id=model)
-    if backend == "api":
-        return OpenBMBExtractor(api_url=api_url, model=model, api_key=api_key)
     if backend in ("local", "server", "local-server"):
         return LocalServerExtractor()
     if backend == "llamacpp":
         return LocalMiniCPMVExtractor()
     raise ValueError(f"Unknown EXTRACTOR_BACKEND: {backend}")
-
-
-def _llamacpp_available() -> bool:
-    if not (os.getenv("LOCAL_MODEL_PATH") and os.getenv("LOCAL_MMPROJ_PATH")):
-        return False
-    try:
-        import llama_cpp  # noqa: F401
-    except ImportError:
-        return False
-    return True
-
-
-def _in_process_local_configured() -> bool:
-    return bool(os.getenv("LOCAL_MODEL_PATH") and os.getenv("LOCAL_MMPROJ_PATH"))

src/extraction/llamacpp_gpu.py

@@ -19,10 +19,11 @@ Config (env):
 from __future__ import annotations
 
 import os
+import time
 from functools import lru_cache
 from typing import Any
 
-from src.document_processing import document_to_payload_parts
+from src.document_processing import document_intake_metadata, document_to_payload_parts
 from src.openbmb_client import (
     EXTRACTION_PROMPT,
     ExtractionResult,
@@ -30,6 +31,7 @@ from src.openbmb_client import (
     _normalize_patient,
     _normalize_tests,
     _parse_json_response,
+    summarize_document_parts,
 )
 
 DEFAULT_GGUF_REPO = "openbmb/MiniCPM-V-4.6-gguf"
@@ -62,6 +64,7 @@ class LlamaCppGPUExtractor:
     def extract(self, file_path: str, max_pages: int = 3) -> ExtractionResult:
         parts = document_to_payload_parts(file_path, max_pages=max_pages)
         prompt_text = _compose_prompt(parts)
+        started = time.perf_counter()
         raw = _run_llamacpp_generation(
             prompt_text=prompt_text,
             repo=self.repo,
@@ -70,6 +73,7 @@ class LlamaCppGPUExtractor:
             n_ctx=self.n_ctx,
             n_gpu_layers=self.n_gpu_layers,
         )
+        duration_ms = int((time.perf_counter() - started) * 1000)
         parsed = _parse_json_response(raw)
         return ExtractionResult(
             patient=_normalize_patient(parsed.get("patient", {})),
@@ -79,8 +83,15 @@ class LlamaCppGPUExtractor:
             request_summary={
                 "backend": "llamacpp-gpu",
                 "repo": self.repo,
+                "model": self.model_file,
                 "document_parts": len(parts),
                 "max_pages": max_pages,
+                "extraction_prompt": EXTRACTION_PROMPT,
+                "user_message_preview": summarize_document_parts(parts),
+                **document_intake_metadata(file_path, parts),
+                "composed_prompt": prompt_text,
+                "return_code": 0,
+                "duration_ms": duration_ms,
             },
         )
 
@@ -153,11 +164,60 @@ def _run_llamacpp_generation(
         ) from exc
 
 
+@spaces.GPU(duration=120)
+def _run_llamacpp_chat(
+    messages: list[dict[str, str]],
+    repo: str,
+    model_file: str,
+    max_tokens: int,
+    n_ctx: int,
+    n_gpu_layers: int,
+) -> str:
+    try:
+        model_path = _download(repo, model_file)
+    except Exception as exc:
+        raise RuntimeError(
+            "llama.cpp download failed while preparing the GGUF model: "
+            f"{type(exc).__name__}: {exc}"
+        ) from exc
+
+    try:
+        llm = _load(model_path, n_ctx, n_gpu_layers)
+    except Exception as exc:
+        raise RuntimeError(
+            "The llama.cpp backend could not load the text-only GGUF model for chat. "
+            f"Inner error: {type(exc).__name__}: {exc}"
+        ) from exc
+
+    try:
+        response = llm.create_chat_completion(
+            messages=messages,
+            temperature=0.2,
+            max_tokens=max_tokens,
+        )
+        return str(response["choices"][0]["message"].get("content") or "").strip()
+    except Exception as exc:
+        raise RuntimeError(
+            "llama.cpp chat generation failed. "
+            f"Inner error: {type(exc).__name__}: {exc}"
+        ) from exc
+
+
 def _compose_prompt(parts: list[dict[str, Any]]) -> str:
     text_parts: list[str] = [EXTRACTION_PROMPT]
+    image_count = 0
     for part in parts:
         if part.get("type") == "text":
             text = str(part.get("text", "")).strip()
             if text:
                 text_parts.append(text)
+        elif part.get("type") == "image_url":
+            image_count += 1
+
+    if image_count and len(text_parts) == 1:
+        raise RuntimeError(
+            "The CPU llama.cpp backend cannot analyze image-based documents. "
+            "Use EXTRACTOR_BACKEND=transformers for local vision extraction."
+        )
+
     return "\n\n".join(text_parts)

src/extraction/local_minicpmv.py

@@ -24,9 +24,10 @@ from __future__ import annotations
 
 import json
 import os
+import time
 from functools import lru_cache
 
-from src.document_processing import document_to_payload_parts
+from src.document_processing import document_intake_metadata, document_to_payload_parts
 from src.grammar import extraction_grammar
 from src.openbmb_client import (
     EXTRACTION_PROMPT,
@@ -34,6 +35,7 @@ from src.openbmb_client import (
     _normalize_notes,
     _normalize_patient,
     _normalize_tests,
+    summarize_document_parts,
 )
 
 
@@ -78,12 +80,14 @@ class LocalMiniCPMVExtractor:
         )
         parts = document_to_payload_parts(file_path, max_pages=max_pages)
 
+        started = time.perf_counter()
         response = llm.create_chat_completion(
             messages=[{"role": "user", "content": [{"type": "text", "text": EXTRACTION_PROMPT}, *parts]}],
             grammar=_grammar(),
             temperature=0.0,
             max_tokens=2048,
         )
+        duration_ms = int((time.perf_counter() - started) * 1000)
         raw = response["choices"][0]["message"]["content"] or "{}"
         # GBNF guarantees valid JSON, but never trust a single parse.
         try:
@@ -101,6 +105,10 @@ class LocalMiniCPMVExtractor:
                 "model_path": os.path.basename(self.model_path),
                 "document_parts": len(parts),
                 "max_pages": max_pages,
+                "user_message_preview": summarize_document_parts(parts),
+                **document_intake_metadata(file_path, parts),
+                "return_code": 0,
+                "duration_ms": duration_ms,
             },
         )
 

src/extraction/local_server.py

@@ -23,10 +23,11 @@ Config (env):
 from __future__ import annotations
 
 import os
+import time
 
 import requests
 
-from src.document_processing import document_to_payload_parts
+from src.document_processing import document_intake_metadata, document_to_payload_parts
 from src.grammar import extraction_grammar
 from src.openbmb_client import (
     EXTRACTION_PROMPT,
@@ -35,6 +36,7 @@ from src.openbmb_client import (
     _normalize_patient,
     _normalize_tests,
     _parse_json_response,
+    summarize_document_parts,
 )
 
 DEFAULT_SERVER_URL = "http://127.0.0.1:8080/v1/chat/completions"
@@ -71,12 +73,14 @@ class LocalServerExtractor:
             # Grammar-constrained decoding: output can only be our {tests, notes} schema.
             payload["grammar"] = extraction_grammar()
 
+        started = time.perf_counter()
         response = requests.post(
             self.url,
             json=payload,
             headers={"Content-Type": "application/json"},
             timeout=self.timeout_seconds,
         )
+        duration_ms = int((time.perf_counter() - started) * 1000)
         response.raise_for_status()
 
         raw = _message_content(response.json())
@@ -89,9 +93,15 @@ class LocalServerExtractor:
             request_summary={
                 "backend": "local-server",
                 "url": self.url,
+                "model": self.model,
                 "document_parts": len(parts),
                 "max_pages": max_pages,
                 "grammar": self.use_grammar,
+                "user_message_preview": summarize_document_parts(parts),
+                **document_intake_metadata(file_path, parts),
+                "http_status": response.status_code,
+                "return_code": 0,
+                "duration_ms": duration_ms,
             },
         )
 

src/extraction/text_generation.py

@@ -0,0 +1,59 @@
+"""Shared text-generation helpers for chat (mirrors EXTRACTOR_BACKEND)."""
+
+from __future__ import annotations
+
+import os
+
+from src.extraction.llamacpp_gpu import DEFAULT_GGUF_REPO, DEFAULT_MODEL_FILE
+from src.local_env import load_local_env
+
+load_local_env()
+
+
+def generate_text_chat(messages: list[dict[str, str]], max_tokens: int | None = None) -> str:
+    """Run a text-only chat completion using the configured extraction backend family."""
+    backend = os.getenv("EXTRACTOR_BACKEND", "transformers").strip().lower()
+    token_limit = max_tokens or int(os.getenv("CHAT_MAX_TOKENS", "1024"))
+
+    if backend in {"api", "openbmb", "hosted"}:
+        raise RuntimeError(
+            "Chat via the hosted OpenBMB API is disabled. Use EXTRACTOR_BACKEND=transformers."
+        )
+    if backend in {"auto", "zerogpu", "zero-gpu", "transformers"}:
+        return _transformers_chat(messages, token_limit)
+    if backend in {"llamacpp-gpu", "gpu-llamacpp", "llama-champion", "llamacpp"}:
+        return _llamacpp_chat(messages, token_limit)
+
+    raise RuntimeError(f"Chat is not configured for EXTRACTOR_BACKEND={backend!r}.")
+
+
+def _transformers_chat(messages: list[dict[str, str]], max_tokens: int) -> str:
+    from src.extraction.zerogpu_transformers import _run_zerogpu_generation
+    from src.model_paths import resolve_transformers_model_source
+
+    model_source = resolve_transformers_model_source(os.getenv("ZEROGPU_MODEL_ID"))
+    downsample_mode = (os.getenv("ZEROGPU_DOWNSAMPLE_MODE") or "16x").strip()
+    structured = [{"role": m["role"], "content": m["content"]} for m in messages]
+    return _run_zerogpu_generation(
+        messages=structured,
+        model_source=model_source,
+        max_new_tokens=max_tokens,
+        downsample_mode=downsample_mode,
+    )
+
+
+def _llamacpp_chat(messages: list[dict[str, str]], max_tokens: int) -> str:
+    from src.extraction.llamacpp_gpu import _run_llamacpp_chat
+
+    repo = os.getenv("LLAMACPP_GGUF_REPO", DEFAULT_GGUF_REPO).strip()
+    model_file = os.getenv("LLAMACPP_MODEL_FILE", DEFAULT_MODEL_FILE).strip()
+    n_ctx = int(os.getenv("LLAMACPP_N_CTX", "8192"))
+    n_gpu_layers = int(os.getenv("LLAMACPP_N_GPU_LAYERS", "0"))
+    return _run_llamacpp_chat(
+        messages=messages,
+        repo=repo,
+        model_file=model_file,
+        max_tokens=max_tokens,
+        n_ctx=n_ctx,
+        n_gpu_layers=n_gpu_layers,
+    )

src/extraction/zerogpu_transformers.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import os
 from typing import Any
 
-from src.document_processing import document_to_payload_parts
+from src.document_processing import document_intake_metadata, document_to_payload_parts
 from src.openbmb_client import (
     EXTRACTION_PROMPT,
     ExtractionResult,
@@ -13,13 +13,16 @@ from src.openbmb_client import (
     _normalize_patient,
     _normalize_tests,
     _parse_json_response,
+    summarize_document_parts,
 )
 
+from src.model_paths import TransformersModelSource, resolve_transformers_model_source
+
 DEFAULT_ZEROGPU_MODEL = "openbmb/MiniCPM-V-4.6"
 
 
 class ZeroGPUTransformersExtractor:
-    """Extractor backed by HF ZeroGPU and the OpenBMB Transformers implementation."""
+    """Extractor backed by local or Hub MiniCPM-V Transformers weights."""
 
     def __init__(
         self,
@@ -27,7 +30,8 @@ class ZeroGPUTransformersExtractor:
         max_new_tokens: int = 2048,
         downsample_mode: str = "16x",
     ) -> None:
-        self.model_id = (model_id or os.getenv("ZEROGPU_MODEL_ID") or DEFAULT_ZEROGPU_MODEL).strip()
+        self.model_source = resolve_transformers_model_source(model_id)
+        self.model_id = self.model_source.model_id
         self.max_new_tokens = int(os.getenv("ZEROGPU_MAX_NEW_TOKENS", str(max_new_tokens)))
         self.downsample_mode = (os.getenv("ZEROGPU_DOWNSAMPLE_MODE") or downsample_mode).strip()
 
@@ -37,14 +41,14 @@ class ZeroGPUTransformersExtractor:
             {
                 "role": "user",
                 "content": [
-                    *_to_transformers_content(parts),
                     {"type": "text", "text": EXTRACTION_PROMPT},
+                    *_to_transformers_content(parts),
                 ],
             }
         ]
         raw = _run_zerogpu_generation(
             messages=messages,
-            model_id=self.model_id,
+            model_source=self.model_source,
             max_new_tokens=self.max_new_tokens,
             downsample_mode=self.downsample_mode,
         )
@@ -55,11 +59,17 @@ class ZeroGPUTransformersExtractor:
             notes=_normalize_notes(parsed.get("notes", [])),
             raw_response=raw,
             request_summary={
-                "backend": "zerogpu-transformers",
+                "backend": "transformers",
                 "model": self.model_id,
+                "model_origin": self.model_source.origin,
+                "model_local_only": self.model_source.local_files_only,
                 "document_parts": len(parts),
                 "max_pages": max_pages,
                 "downsample_mode": self.downsample_mode,
+                "extraction_prompt": EXTRACTION_PROMPT,
+                "user_message_preview": summarize_document_parts(parts),
+                **document_intake_metadata(file_path, parts),
+                "messages_preview": _messages_preview(messages),
             },
         )
 
@@ -83,17 +93,58 @@ def _to_transformers_content(parts: list[dict[str, Any]]) -> list[dict[str, str]
     return content
 
 
-def _load_model(model_id: str):
+def _messages_preview(messages: list[dict[str, Any]]) -> str:
+    """Serialize message structure without embedding image data URLs."""
+    preview: list[dict[str, Any]] = []
+    for message in messages:
+        content = message.get("content")
+        if isinstance(content, str):
+            preview.append({"role": message.get("role"), "content": _truncate_preview(content)})
+            continue
+        if not isinstance(content, list):
+            continue
+        items: list[dict[str, str]] = []
+        for item in content:
+            if not isinstance(item, dict):
+                continue
+            if item.get("type") == "image":
+                items.append({"type": "image", "url": "[image omitted]"})
+            elif item.get("type") == "text":
+                items.append({"type": "text", "text": _truncate_preview(str(item.get("text") or ""))})
+            elif item.get("type") == "image_url":
+                items.append({"type": "image_url", "url": "[image omitted]"})
+        preview.append({"role": message.get("role"), "content": items})
+    import json
+
+    return json.dumps(preview, indent=2)
+
+
+def _truncate_preview(text: str, limit: int = 1200) -> str:
+    cleaned = text.strip()
+    if len(cleaned) <= limit:
+        return cleaned
+    return cleaned[: limit - 3] + "..."
+
+
+def _load_model(source: TransformersModelSource):
     import torch
     from transformers import AutoModelForImageTextToText, AutoProcessor
 
-    processor = AutoProcessor.from_pretrained(model_id)
+    from src.model_paths import hub_cache_dir
+
+    pretrained_kwargs: dict[str, Any] = {
+        "trust_remote_code": True,
+        "local_files_only": source.local_files_only,
+    }
+    if not source.local_files_only:
+        pretrained_kwargs["cache_dir"] = str(hub_cache_dir())
+
+    processor = AutoProcessor.from_pretrained(source.model_id, **pretrained_kwargs)
 
-    # 4-bit (NF4) quantization on GPU: earns the quantization badge and roughly quarters the
-    # GPU memory footprint (helps stay within ZeroGPU limits). Set ZEROGPU_QUANTIZE=0 to fall
-    # back to bf16 full precision if bitsandbytes ever misbehaves on the runtime.
     use_4bit = os.getenv("ZEROGPU_QUANTIZE", "1") != "0" and torch.cuda.is_available()
-    load_kwargs: dict[str, Any] = {"device_map": "auto"}
+    load_kwargs: dict[str, Any] = {"device_map": "auto", "trust_remote_code": True, "local_files_only": source.local_files_only}
+    if not source.local_files_only:
+        load_kwargs["cache_dir"] = str(hub_cache_dir())
     if use_4bit:
         from transformers import BitsAndBytesConfig
 
@@ -103,10 +154,14 @@ def _load_model(model_id: str):
             bnb_4bit_compute_dtype=torch.bfloat16,
             bnb_4bit_use_double_quant=True,
         )
+    elif torch.cuda.is_available():
+        load_kwargs["torch_dtype"] = torch.bfloat16
+    elif hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+        load_kwargs["torch_dtype"] = torch.float16
     else:
-        load_kwargs["torch_dtype"] = torch.bfloat16 if torch.cuda.is_available() else "auto"
+        load_kwargs["torch_dtype"] = torch.float32
 
-    model = AutoModelForImageTextToText.from_pretrained(model_id, **load_kwargs)
+    model = AutoModelForImageTextToText.from_pretrained(source.model_id, **load_kwargs)
     model.eval()
     return processor, model
 
@@ -114,10 +169,25 @@ def _load_model(model_id: str):
 _MODEL_CACHE: dict[str, tuple[Any, Any]] = {}
 
 
-def _get_model(model_id: str) -> tuple[Any, Any]:
-    if model_id not in _MODEL_CACHE:
-        _MODEL_CACHE[model_id] = _load_model(model_id)
-    return _MODEL_CACHE[model_id]
+def _cache_key(source: TransformersModelSource) -> str:
+    return f"{source.model_id}|local={int(source.local_files_only)}|origin={source.origin}"
+
+
+def _get_model(source: TransformersModelSource) -> tuple[Any, Any]:
+    from src.model_paths import hub_cache_dir
+
+    key = _cache_key(source)
+    if key not in _MODEL_CACHE:
+        if source.local_files_only:
+            print(f"[Blood Test Explainer] loading local Transformers model from {source.model_id}", flush=True)
+        else:
+            print(
+                f"[Blood Test Explainer] downloading Transformers model {source.model_id} "
+                f"(cache: {hub_cache_dir()}) and loading into memory",
+                flush=True,
+            )
+        _MODEL_CACHE[key] = _load_model(source)
+    return _MODEL_CACHE[key]
 
 
 try:
@@ -137,14 +207,14 @@ except ImportError:  # Local development without the HF Spaces package.
 @spaces.GPU(duration=120)
 def _run_zerogpu_generation(
     messages: list[dict[str, Any]],
-    model_id: str,
+    model_source: TransformersModelSource,
     max_new_tokens: int,
     downsample_mode: str,
 ) -> str:
     import torch
 
     try:
-        processor, model = _get_model(model_id)
+        processor, model = _get_model(model_source)
         inputs = processor.apply_chat_template(
             messages,
             tokenize=True,
@@ -174,6 +244,6 @@ def _run_zerogpu_generation(
         return str(output_text[0]).strip() if output_text else ""
     except Exception as exc:
         raise RuntimeError(
-            "OpenBMB Transformers generation failed on the CUDA/ZeroGPU lane. "
+            "MiniCPM-V Transformers generation failed. "
             f"Inner error: {type(exc).__name__}: {exc}"
         ) from exc

src/local_env.py

@@ -7,6 +7,7 @@ from pathlib import Path
 def load_local_env(path: str = ".env") -> None:
     env_path = Path(path)
     if not env_path.exists():
+        _apply_model_defaults()
         return
 
     for raw_line in env_path.read_text(encoding="utf-8").splitlines():
@@ -20,3 +21,11 @@ def load_local_env(path: str = ".env") -> None:
 
         if key and key not in os.environ:
             os.environ[key] = value
+
+    _apply_model_defaults()
+
+
+def _apply_model_defaults() -> None:
+    from src.model_paths import apply_local_model_defaults
+
+    apply_local_model_defaults()

src/markers.py

@@ -1,9 +1,13 @@
 """Canonical lab-marker reference.
 
 Single source of truth shared by the synthetic-data generator, the evaluation harness,
-and (later) the interpretation knowledge base. Reference ranges are adult, general-population
-defaults for synthetic-data generation and flag computation only; the production KB will carry
-sex/age-specific ranges with citations. These values are for an educational tool, not diagnosis.
+and the interpretation knowledge base. Reference ranges are adult, general-population defaults
+for synthetic-data generation and flag computation only.
+
+CBC marker intervals match `kb/cbc_knowledge_graph.json` → `statistics_per_group_age.adult`
+(the age-only fallback used when patient sex is unknown). Sex/age-specific ranges live in the
+JSON graph and take precedence in the report pipeline when patient context is available.
+These values are for an educational tool, not diagnosis.
 
 Each marker: canonical name, common aliases (for matching extracted text), unit, an adult
 reference interval, a category, and a one-line "what it measures".
@@ -46,15 +50,25 @@ def _fmt(v: float) -> str:
     return str(int(v)) if float(v).is_integer() else f"{v:g}"
 
 
-# ~30 of the most common markers across CBC, metabolic, lipid, thyroid, and vitamins.
+# ~100 of the most common markers across CBC, metabolic, lipid, thyroid, coagulation, hormones, and vitamins.
 MARKERS: tuple[Marker, ...] = (
     # --- Complete blood count ---
-    Marker("Hemoglobin", "g/dL", 13.5, 17.5, "CBC", "oxygen-carrying protein in red blood cells", ("Hgb", "HGB", "Hb")),
-    Marker("Hematocrit", "%", 38.8, 50.0, "CBC", "fraction of blood made up of red cells", ("Hct", "HCT", "PCV")),
-    Marker("White Blood Cell Count", "10^3/uL", 4.5, 11.0, "CBC", "immune cells that fight infection", ("WBC", "Leukocytes", "WBC Count", "TLC", "Total Leucocyte Count")),
+    Marker("Hemoglobin", "g/dL", 11.9, 17.7, "CBC", "oxygen-carrying protein in red blood cells", ("Hgb", "HGB", "Hb")),
+    Marker("Hematocrit", "%", 35, 52, "CBC", "fraction of blood made up of red cells", ("Hct", "HCT", "PCV")),
+    Marker("White Blood Cell Count", "10^3/uL", 3.7, 10.5, "CBC", "immune cells that fight infection", ("WBC", "Leukocytes", "WBC Count", "TLC", "Total Leucocyte Count")),
     Marker("Platelet Count", "10^3/uL", 150, 400, "CBC", "cell fragments that help blood clot", ("Platelets", "PLT")),
-    Marker("Red Blood Cell Count", "10^6/uL", 4.5, 5.9, "CBC", "number of oxygen-carrying red cells", ("RBC", "Erythrocytes")),
-    Marker("MCV", "fL", 80, 100, "CBC", "average size of red blood cells", ("Mean Corpuscular Volume",)),
+    Marker("Red Blood Cell Count", "10^6/uL", 4.0, 6.2, "CBC", "number of oxygen-carrying red cells", ("RBC", "Erythrocytes")),
+    Marker("MCV", "fL", 82, 99, "CBC", "average size of red blood cells", ("Mean Corpuscular Volume",)),
+    Marker("MCH", "pg", 25, 35, "CBC", "average hemoglobin per red blood cell", ("Mean Corpuscular Hemoglobin",)),
+    Marker("MCHC", "g/dL", 32, 36, "CBC", "average hemoglobin concentration in red cells", ("Mean Corpuscular Hemoglobin Concentration",)),
+    Marker("RDW", "%", 9.0, 14.5, "CBC", "variation in red blood cell size", ("Red Cell Distribution Width",)),
+    Marker("MPV", "fL", 7.5, 11.5, "CBC", "average size of platelets", ("Mean Platelet Volume",)),
+    Marker("Absolute Neutrophil Count", "10^3/uL", 1.8, 7.7, "CBC", "count of infection-fighting white cells", ("ANC", "Neutrophils Absolute", "Abs Neutrophils")),
+    Marker("Absolute Lymphocyte Count", "10^3/uL", 0.875, 4.8, "CBC", "count of adaptive immune white cells", ("ALC", "Lymphocytes Absolute", "Abs Lymphocytes")),
+    Marker("Absolute Monocyte Count", "10^3/uL", 0.2, 0.8, "CBC", "count of cleanup and immune white cells", ("AMC", "Monocytes Absolute", "Abs Monocytes")),
+    Marker("Absolute Eosinophil Count", "10^3/uL", 0, 0.5, "CBC", "count of allergy and parasite-related white cells", ("AEC", "Eosinophils Absolute", "Abs Eosinophils")),
+    Marker("Absolute Basophil Count", "10^3/uL", 0, 0.2, "CBC", "count of histamine-related white cells", ("ABC", "Basophils Absolute", "Abs Basophils")),
+    Marker("Reticulocyte Count", "%", 0.5, 2.5, "CBC", "young red cells recently released from bone marrow", ("Retic Count", "Retics")),
     # --- Metabolic panel ---
     Marker("Glucose", "mg/dL", 70, 99, "Metabolic", "blood sugar level", ("Fasting Glucose", "GLU", "Blood Sugar", "FBS", "RBS", "Fasting Blood Sugar")),
     Marker("Creatinine", "mg/dL", 0.7, 1.3, "Metabolic", "kidney-function waste product", ("Cr", "Serum Creatinine")),
@@ -66,25 +80,90 @@ MARKERS: tuple[Marker, ...] = (
     Marker("Calcium", "mg/dL", 8.6, 10.3, "Metabolic", "mineral for bones, nerves, and muscle", ("Ca", "Total Calcium")),
     Marker("Albumin", "g/dL", 3.5, 5.0, "Metabolic", "main protein made by the liver", ("ALB",)),
     Marker("Total Protein", "g/dL", 6.0, 8.3, "Metabolic", "total of all blood proteins", ("TP", "Protein, Total")),
+    Marker("Globulin", "g/dL", 2.0, 3.5, "Metabolic", "non-albumin blood proteins including antibodies", ("Globulins",)),
+    Marker("Bicarbonate", "mmol/L", 22, 28, "Metabolic", "main blood buffer for acid-base balance", ("CO2", "Bicarb", "Total CO2", "Carbon Dioxide")),
+    Marker("Anion Gap", "mEq/L", 7, 13, "Metabolic", "calculated gap from electrolytes suggesting acid-base issues", ("AG",)),
+    Marker("Magnesium", "mg/dL", 1.7, 2.2, "Metabolic", "electrolyte for nerves, muscle, and heart rhythm", ("Mg", "Mg++")),
+    Marker("Phosphate", "mg/dL", 2.5, 4.5, "Metabolic", "mineral for bones, energy, and cell membranes", ("Phosphorus", "PO4", "Inorganic Phosphate")),
+    Marker("Uric Acid", "mg/dL", 3.5, 7.2, "Metabolic", "breakdown product of purines; linked to gout", ("UA", "Urate")),
+    Marker("Serum Iron", "mcg/dL", 60, 170, "Metabolic", "circulating iron available for red-cell production", ("Iron", "Fe", "Iron, Serum")),
+    Marker("TIBC", "mcg/dL", 250, 450, "Metabolic", "blood's capacity to bind and transport iron", ("Total Iron Binding Capacity", "Iron Binding Capacity")),
+    Marker("Transferrin Saturation", "%", 20, 50, "Metabolic", "percent of iron-binding sites occupied", ("TSAT", "Iron Saturation")),
+    Marker("LDH", "U/L", 140, 280, "Metabolic", "enzyme released when cells are damaged", ("Lactate Dehydrogenase",)),
+    Marker("Osmolality", "mOsm/kg", 275, 295, "Metabolic", "concentration of particles in the blood", ("Serum Osmolality",)),
+    Marker("Ammonia", "mcg/dL", 15, 45, "Metabolic", "waste product processed by the liver", ("NH3", "Blood Ammonia")),
+    Marker("Lactate", "mmol/L", 0.5, 2.0, "Metabolic", "byproduct of anaerobic metabolism", ("Lactic Acid", "Lactate, Blood")),
+    Marker("Homocysteine", "umol/L", 5, 15, "Metabolic", "amino acid linked to B-vitamin status and vascular risk", ("Hcy",)),
+    Marker("Cystatin C", "mg/L", 0.53, 0.95, "Metabolic", "kidney-function marker less affected by muscle mass", ("CysC",)),
+    Marker("Prealbumin", "mg/dL", 20, 40, "Metabolic", "short-lived protein reflecting recent nutrition", ("Transthyretin",)),
+    Marker("Beta-2 Microglobulin", "mg/L", 0.7, 1.8, "Metabolic", "small protein from cell turnover; kidney and immune marker", ("B2M", "β2-Microglobulin")),
     # --- Liver enzymes ---
     Marker("ALT", "U/L", 7, 56, "Liver", "liver enzyme released when liver cells are stressed", ("Alanine Aminotransferase", "SGPT")),
     Marker("AST", "U/L", 10, 40, "Liver", "enzyme from liver and muscle cells", ("Aspartate Aminotransferase", "SGOT")),
     Marker("ALP", "U/L", 44, 147, "Liver", "enzyme from liver and bone", ("Alkaline Phosphatase",)),
     Marker("GGT", "U/L", 9, 48, "Liver", "liver enzyme sensitive to bile and alcohol", ("Gamma-Glutamyl Transferase", "Gamma GT")),
     Marker("Total Bilirubin", "mg/dL", 0.1, 1.2, "Liver", "pigment from red-cell breakdown", ("Bilirubin, Total", "TBIL")),
+    Marker("Direct Bilirubin", "mg/dL", 0, 0.3, "Liver", "conjugated bilirubin processed by the liver", ("Conjugated Bilirubin", "DBIL")),
+    Marker("Lipase", "U/L", 0, 160, "Liver", "pancreatic enzyme for fat digestion", ("LPS",)),
+    Marker("Amylase", "U/L", 25, 125, "Liver", "pancreatic and salivary enzyme for starch digestion", ("AMS",)),
     # --- Lipid panel ---
     Marker("Total Cholesterol", "mg/dL", None, 200, "Lipid", "total cholesterol in the blood", ("Cholesterol, Total", "TC")),
     Marker("LDL Cholesterol", "mg/dL", None, 100, "Lipid", "'bad' cholesterol that builds in arteries", ("LDL", "LDL-C")),
     Marker("HDL Cholesterol", "mg/dL", 40, None, "Lipid", "'good' cholesterol that clears arteries", ("HDL", "HDL-C")),
     Marker("Triglycerides", "mg/dL", None, 150, "Lipid", "fat circulating in the blood", ("TG", "Trig")),
+    Marker("Non-HDL Cholesterol", "mg/dL", None, 130, "Lipid", "all cholesterol except HDL; atherogenic fraction", ("Non-HDL-C", "Non HDL Cholesterol")),
+    Marker("Apolipoprotein B", "mg/dL", None, 90, "Lipid", "protein on LDL and related particles", ("Apo B", "ApoB")),
+    Marker("Apolipoprotein A-1", "mg/dL", 120, None, "Lipid", "main protein on HDL particles", ("Apo A-1", "ApoA1")),
+    Marker("Lipoprotein(a)", "mg/dL", None, 30, "Lipid", "genetically influenced LDL-like particle", ("Lp(a)", "Lipoprotein a")),
     # --- Thyroid ---
     Marker("TSH", "mIU/L", 0.4, 4.0, "Thyroid", "pituitary signal that controls the thyroid", ("Thyroid Stimulating Hormone",)),
     Marker("Free T4", "ng/dL", 0.8, 1.8, "Thyroid", "active thyroid hormone, free fraction", ("FT4", "Free Thyroxine")),
+    Marker("Free T3", "pg/mL", 2.3, 4.2, "Thyroid", "active thyroid hormone, free fraction", ("FT3", "Free Triiodothyronine")),
+    Marker("Total T4", "mcg/dL", 4.5, 12.0, "Thyroid", "total thyroxine including bound and free", ("T4", "Thyroxine")),
+    Marker("Total T3", "ng/dL", 80, 200, "Thyroid", "total triiodothyronine including bound and free", ("T3", "Triiodothyronine")),
+    Marker("Anti-TPO Antibodies", "IU/mL", None, 35, "Thyroid", "antibodies against thyroid peroxidase", ("TPO Antibodies", "Thyroid Peroxidase Antibodies", "Anti-TPO")),
     # --- Vitamins / iron ---
     Marker("Vitamin D", "ng/mL", 30, 100, "Vitamin", "vitamin for bone and immune health", ("25-OH Vitamin D", "25-Hydroxyvitamin D", "Vit D")),
     Marker("Vitamin B12", "pg/mL", 200, 900, "Vitamin", "vitamin for nerves and red-cell production", ("B12", "Cobalamin")),
     Marker("Ferritin", "ng/mL", 30, 400, "Vitamin", "stored-iron protein", ("FERR",)),
     Marker("HbA1c", "%", 4.0, 5.6, "Metabolic", "average blood sugar over ~3 months", ("A1c", "Hemoglobin A1c", "Glycated Hemoglobin")),
+    # --- Coagulation ---
+    Marker("Prothrombin Time", "seconds", 11, 13.5, "Coagulation", "time for the clotting cascade to form fibrin", ("PT",)),
+    Marker("INR", "ratio", 0.9, 1.1, "Coagulation", "standardized prothrombin time for warfarin monitoring", ("International Normalized Ratio",)),
+    Marker("aPTT", "seconds", 25, 35, "Coagulation", "time for the intrinsic clotting pathway", ("PTT", "APTT", "Activated Partial Thromboplastin Time")),
+    Marker("Fibrinogen", "mg/dL", 200, 400, "Coagulation", "clotting protein and acute-phase reactant", ("Factor I",)),
+    Marker("D-Dimer", "ng/mL", None, 500, "Coagulation", "breakdown product of clots; elevated when clotting is active", ("D Dimer",)),
+    # --- Inflammation / immune ---
+    Marker("C-Reactive Protein", "mg/L", None, 10, "Inflammation", "general marker of inflammation", ("CRP",)),
+    Marker("hs-CRP", "mg/L", None, 3.0, "Inflammation", "high-sensitivity CRP for cardiovascular risk", ("High-Sensitivity CRP", "High Sensitivity C-Reactive Protein")),
+    Marker("ESR", "mm/hr", 0, 20, "Inflammation", "rate red cells settle; nonspecific inflammation marker", ("Erythrocyte Sedimentation Rate", "Sed Rate")),
+    Marker("Procalcitonin", "ng/mL", None, 0.1, "Inflammation", "marker that rises with bacterial infection", ("PCT",)),
+    Marker("Complement C3", "mg/dL", 90, 180, "Inflammation", "complement protein in immune activation", ("C3",)),
+    Marker("Complement C4", "mg/dL", 10, 40, "Inflammation", "complement protein in immune activation", ("C4",)),
+    Marker("Rheumatoid Factor", "IU/mL", None, 14, "Inflammation", "antibody sometimes seen in autoimmune arthritis", ("RF",)),
+    # --- Cardiac ---
+    Marker("BNP", "pg/mL", None, 100, "Cardiac", "hormone released when the heart is stretched", ("B-Type Natriuretic Peptide", "Brain Natriuretic Peptide")),
+    Marker("Troponin I", "ng/mL", None, 0.04, "Cardiac", "heart-muscle protein released with injury", ("TnI", "High-Sensitivity Troponin I")),
+    Marker("Creatine Kinase", "U/L", 30, 200, "Cardiac", "enzyme from muscle including heart and skeletal", ("CK", "CPK", "Creatine Phosphokinase")),
+    Marker("CK-MB", "ng/mL", None, 5, "Cardiac", "heart-enriched fraction of creatine kinase", ("CKMB", "Creatine Kinase-MB")),
+    # --- Hormones ---
+    Marker("Cortisol", "mcg/dL", 6, 18, "Hormone", "stress hormone from the adrenal glands", ("AM Cortisol", "Serum Cortisol")),
+    Marker("Insulin", "uIU/mL", 2.6, 24.9, "Hormone", "hormone that lowers blood sugar", ("Fasting Insulin",)),
+    Marker("Testosterone", "ng/dL", 300, 1000, "Hormone", "androgen sex hormone", ("Total Testosterone",)),
+    Marker("Estradiol", "pg/mL", 15, 350, "Hormone", "primary estrogen sex hormone", ("E2", "Estrogen")),
+    Marker("Prolactin", "ng/mL", None, 20, "Hormone", "pituitary hormone for lactation and more", ("PRL",)),
+    Marker("FSH", "mIU/mL", 1.5, 12.4, "Hormone", "pituitary signal for egg and sperm production", ("Follicle Stimulating Hormone",)),
+    Marker("LH", "mIU/mL", 1.5, 9.3, "Hormone", "pituitary signal for ovulation and testosterone", ("Luteinizing Hormone",)),
+    Marker("Progesterone", "ng/mL", 0.2, 25, "Hormone", "hormone that supports the uterine lining", ("P4",)),
+    Marker("Parathyroid Hormone", "pg/mL", 15, 65, "Hormone", "hormone that regulates blood calcium", ("PTH", "Intact PTH")),
+    Marker("ACTH", "pg/mL", 7, 63, "Hormone", "pituitary signal that drives cortisol production", ("Adrenocorticotropic Hormone",)),
+    Marker("SHBG", "nmol/L", 10, 80, "Hormone", "protein that binds sex hormones in the blood", ("Sex Hormone Binding Globulin",)),
+    Marker("IGF-1", "ng/mL", 115, 355, "Hormone", "growth factor reflecting growth-hormone activity", ("Insulin-Like Growth Factor 1", "Somatomedin C")),
+    # --- Oncology / screening ---
+    Marker("PSA", "ng/mL", None, 4.0, "Oncology", "prostate-specific protein used in screening", ("Prostate Specific Antigen",)),
+    # --- Vitamins / iron (continued) ---
+    Marker("Folate", "ng/mL", 3, 20, "Vitamin", "B vitamin needed for DNA and red-cell production", ("Folic Acid", "Serum Folate")),
+    Marker("Vitamin A", "mcg/dL", 30, 65, "Vitamin", "fat-soluble vitamin for vision and immunity", ("Retinol",)),
 )
 
 

src/model_paths.py

@@ -0,0 +1,95 @@
+"""Resolve MiniCPM-V Transformers weights: local disk first, Hub download fallback."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+DEFAULT_HF_REPO = "openbmb/MiniCPM-V-4.6"
+
+
+@dataclass(frozen=True)
+class TransformersModelSource:
+    model_id: str
+    local_files_only: bool
+    origin: str
+
+
+def project_root() -> Path:
+    return Path(__file__).resolve().parents[1]
+
+
+def models_dir() -> Path:
+    raw = os.getenv("BTE_MODELS_DIR", "models").strip()
+    path = Path(raw)
+    if not path.is_absolute():
+        path = project_root() / path
+    return path.resolve()
+
+
+def hub_cache_dir() -> Path:
+    cache = models_dir() / ".cache" / "huggingface" / "hub"
+    cache.mkdir(parents=True, exist_ok=True)
+    return cache
+
+
+def apply_local_model_defaults() -> None:
+    """Send Hugging Face downloads to the project models/ cache by default."""
+    models = models_dir()
+    os.environ.setdefault("BTE_MODELS_DIR", str(models))
+    hf_home = models / ".cache" / "huggingface"
+    hf_home.mkdir(parents=True, exist_ok=True)
+    os.environ.setdefault("HF_HOME", str(hf_home))
+    os.environ.setdefault("HUGGINGFACE_HUB_CACHE", str(hub_cache_dir()))
+
+
+def resolve_transformers_model_source(model_id: str | None = None) -> TransformersModelSource:
+    """Use a complete local checkpoint when present; otherwise download and load from Hub."""
+    configured = (model_id or os.getenv("ZEROGPU_MODEL_ID") or DEFAULT_HF_REPO).strip()
+    repo_id = DEFAULT_HF_REPO if configured.startswith(".") or configured.startswith("/") else configured
+
+    explicit = Path(configured).expanduser()
+    if explicit.is_dir() and is_transformers_model_dir(explicit):
+        return TransformersModelSource(str(explicit.resolve()), True, "local-dir")
+
+    for candidate in (
+        models_dir() / "MiniCPM-V-4.6",
+        models_dir() / "openbmb" / "MiniCPM-V-4.6",
+        models_dir() / repo_id.split("/", 1)[-1],
+    ):
+        if is_transformers_model_dir(candidate):
+            return TransformersModelSource(str(candidate.resolve()), True, "local-dir")
+
+    for cache_root in (hub_cache_dir(), Path.home() / ".cache" / "huggingface" / "hub"):
+        snapshot = latest_complete_snapshot(repo_id, cache_root)
+        if snapshot:
+            label = "local-cache" if cache_root == hub_cache_dir() else "local-cache-global"
+            return TransformersModelSource(str(snapshot), True, label)
+
+    return TransformersModelSource(repo_id, False, "hub-download")
+
+
+def is_transformers_model_dir(path: Path) -> bool:
+    if not path.is_dir() or not (path / "config.json").is_file():
+        return False
+    if list(path.glob("*.safetensors")) or list(path.glob("model*.bin")):
+        return True
+    return any(path.glob("model*.safetensors.index.json"))
+
+
+def latest_complete_snapshot(repo_id: str, hub_cache: Path) -> Path | None:
+    if not hub_cache.is_dir():
+        return None
+    repo_dir = hub_cache / f"models--{repo_id.replace('/', '--')}" / "snapshots"
+    if not repo_dir.is_dir():
+        return None
+    snapshots = sorted(
+        (p for p in repo_dir.iterdir() if p.is_dir()),
+        key=lambda p: p.stat().st_mtime,
+        reverse=True,
+    )
+    for snapshot in snapshots:
+        if is_transformers_model_dir(snapshot):
+            return snapshot
+    return None

src/openbmb_client.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import json
 import os
 import re
+import time
 from dataclasses import dataclass, field
 from typing import Any
 
@@ -10,7 +11,7 @@ import requests
 from json_repair import loads as repair_json_loads
 from requests import HTTPError
 
-from src.document_processing import document_to_payload_parts
+from src.document_processing import document_intake_metadata, document_to_payload_parts
 from src.local_env import load_local_env
 
 
@@ -106,6 +107,7 @@ class OpenBMBExtractor:
             "max_tokens": 2048,
         }
 
+        started = time.perf_counter()
         response = requests.post(
             self.api_url,
             headers={
@@ -115,6 +117,7 @@ class OpenBMBExtractor:
             json=payload,
             timeout=self.timeout_seconds,
         )
+        duration_ms = int((time.perf_counter() - started) * 1000)
         try:
             response.raise_for_status()
         except HTTPError as error:
@@ -133,14 +136,33 @@ class OpenBMBExtractor:
             notes=_normalize_notes(parsed.get("notes", [])),
             raw_response=raw_response,
             request_summary={
+                "backend": "api",
                 "api_url": self.api_url,
                 "model": self.model,
                 "document_parts": len(document_parts),
-                "pages": "auto",
+                "pages": max_pages or "auto",
+                "extraction_prompt": EXTRACTION_PROMPT,
+                "user_message_preview": summarize_document_parts(document_parts),
+                **document_intake_metadata(file_path, document_parts),
+                "http_status": response.status_code,
+                "return_code": 0,
+                "duration_ms": duration_ms,
             },
         )
 
 
+def summarize_document_parts(parts: list[dict[str, Any]]) -> dict[str, int]:
+    """Lightweight payload stats for pipeline traces (no base64 blobs)."""
+    image_count = 0
+    text_characters = 0
+    for part in parts:
+        if part.get("type") == "image_url":
+            image_count += 1
+        elif part.get("type") == "text":
+            text_characters += len(str(part.get("text") or ""))
+    return {"image_count": image_count, "text_characters": text_characters}
+
+
 def _extract_message_content(payload: dict[str, Any]) -> str:
     try:
         message = payload["choices"][0]["message"]

src/pipeline_trace.py

@@ -0,0 +1,460 @@
+"""Build a step-by-step trace of the analysis pipeline for the agent trace panel."""
+
+from __future__ import annotations
+
+import html
+import json
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+from src.interpretation import Interpretation, build_interpretation
+from src.openbmb_client import EXTRACTION_PROMPT, ExtractionResult
+
+_MAX_PREVIEW = 2400
+_TRACE_TITLE = "Agent pipeline trace"
+
+_PIPELINE_STEP_DEFS: tuple[tuple[str, str], ...] = (
+    ("document_intake", "Step 1 — Document intake"),
+    ("vision_extraction", "Step 2 — Vision extraction (LLM)"),
+    ("schema_normalization", "Step 3 — Schema normalization"),
+    ("knowledge_graph", "Step 4 — Knowledge graph enrichment"),
+    ("pattern_detection", "Step 5 — Cross-marker pattern detection"),
+)
+
+
+@dataclass(frozen=True)
+class PipelineStep:
+    id: str
+    title: str
+    status: str
+    summary: str
+    return_code: int | None = 0
+    prompt: str | None = None
+    input_preview: str | None = None
+    output_preview: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+def _truncate(text: str | None, limit: int = _MAX_PREVIEW) -> str | None:
+    if not text:
+        return None
+    cleaned = text.strip()
+    if len(cleaned) <= limit:
+        return cleaned
+    return cleaned[: limit - 3].rstrip() + "..."
+
+
+def _marker_preview(tests: list[dict[str, Any]], limit: int = 3) -> str:
+    lines: list[str] = []
+    for test in tests[:limit]:
+        marker = test.get("marker", "?")
+        value = test.get("value", "?")
+        unit = test.get("unit") or ""
+        status = test.get("status") or "unknown"
+        lines.append(f"- {marker}: {value} {unit} ({status})".strip())
+    if len(tests) > limit:
+        lines.append(f"- … and {len(tests) - limit} more")
+    return "\n".join(lines)
+
+
+def build_pipeline_trace(
+    extraction: ExtractionResult,
+    health_report: dict[str, Any],
+    *,
+    source_path: str | None = None,
+) -> list[PipelineStep]:
+    summary = extraction.request_summary or {}
+    patient = health_report.get("patient") or extraction.patient or {}
+    report_summary = health_report.get("summary") or {}
+    interpretation = build_interpretation(extraction.tests)
+
+    backend = summary.get("backend") or summary.get("api_url") or "unknown"
+    file_name = Path(source_path).name if source_path else None
+    runtime_return_code = summary.get("return_code", 0)
+
+    intake_lines = [
+        f"Backend: {backend}",
+        f"Input modality: {summary.get('input_modality', 'unknown')}",
+        f"Document parts: {summary.get('document_parts', '?')}",
+    ]
+    if summary.get("pages_rendered") is not None:
+        intake_lines.append(f"Pages rendered to images: {summary.get('pages_rendered')}")
+    if summary.get("max_pages") is not None:
+        intake_lines.append(f"Max pages: {summary.get('max_pages')}")
+    if file_name:
+        intake_lines.append(f"File: {file_name}")
+    preview = summary.get("user_message_preview") or {}
+    if preview:
+        intake_lines.append(
+            f"Payload preview: {preview.get('image_count', 0)} image(s), "
+            f"{preview.get('text_characters', 0)} text character(s)"
+        )
+
+    steps: list[PipelineStep] = [
+        PipelineStep(
+            id="document_intake",
+            title="Step 1 — Document intake",
+            status="complete",
+            return_code=0,
+            summary="\n".join(intake_lines),
+            input_preview=file_name,
+            metadata={
+                "backend": backend,
+                "document_parts": summary.get("document_parts"),
+                "max_pages": summary.get("max_pages"),
+                "file": file_name,
+                **preview,
+            },
+        ),
+        PipelineStep(
+            id="vision_extraction",
+            title="Step 2 — Vision extraction (LLM)",
+            status="complete",
+            return_code=runtime_return_code,
+            summary=(
+                f"Model/backend: {summary.get('model') or summary.get('repo') or backend}. "
+                f"Extracted structured JSON from the document."
+            ),
+            prompt=summary.get("extraction_prompt") or EXTRACTION_PROMPT,
+            input_preview=_stringify_preview(
+                summary.get("composed_prompt") or summary.get("messages_preview")
+            ),
+            output_preview=_truncate(extraction.raw_response),
+            metadata={
+                "backend": backend,
+                "model": summary.get("model") or summary.get("repo"),
+                "api_url": summary.get("api_url") or summary.get("url"),
+                "http_status": summary.get("http_status"),
+                "duration_ms": summary.get("duration_ms"),
+                "return_code": runtime_return_code,
+                "document_parts": summary.get("document_parts"),
+            },
+        ),
+        PipelineStep(
+            id="schema_normalization",
+            title="Step 3 — Schema normalization",
+            status="complete",
+            return_code=0,
+            summary=(
+                f"Parsed {len(extraction.tests)} marker(s), "
+                f"{len(extraction.notes)} note(s). "
+                f"Patient sex: {patient.get('sex', 'unknown')}; "
+                f"age group: {patient.get('age_group', 'unknown')}."
+            ),
+            output_preview=_marker_preview(extraction.tests),
+            metadata={
+                "markers_parsed": len(extraction.tests),
+                "notes_parsed": len(extraction.notes),
+                "patient_sex": patient.get("sex", "unknown"),
+                "patient_age_group": patient.get("age_group", "unknown"),
+                "notes": extraction.notes[:5],
+            },
+        ),
+        PipelineStep(
+            id="knowledge_graph",
+            title="Step 4 — Knowledge graph enrichment",
+            status="complete",
+            return_code=0,
+            summary=(
+                f"Enriched {report_summary.get('enriched_markers', 0)} of "
+                f"{report_summary.get('total_markers', 0)} marker(s). "
+                f"Unmatched: {len(report_summary.get('unmatched_markers') or [])}."
+            ),
+            output_preview=_truncate(json.dumps(report_summary, indent=2)),
+            metadata={
+                "enriched_markers": report_summary.get("enriched_markers", 0),
+                "total_markers": report_summary.get("total_markers", 0),
+                "unmatched_markers": report_summary.get("unmatched_markers") or [],
+            },
+        ),
+        PipelineStep(
+            id="pattern_detection",
+            title="Step 5 — Cross-marker pattern detection",
+            status="complete",
+            return_code=0,
+            summary=_pattern_summary(interpretation),
+            output_preview=_pattern_output(interpretation),
+            metadata={
+                "flagged_markers": len(interpretation.flagged),
+                "patterns_detected": len(interpretation.patterns),
+                "normal_count": interpretation.normal_count,
+            },
+        ),
+    ]
+    return steps
+
+
+def _stringify_preview(value: Any) -> str | None:
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return _truncate(value)
+    return _truncate(json.dumps(value, indent=2))
+
+
+def _pattern_summary(interpretation: Interpretation) -> str:
+    flagged = len(interpretation.flagged)
+    patterns = len(interpretation.patterns)
+    return (
+        f"Flagged markers: {flagged}. "
+        f"Cross-marker patterns detected: {patterns}. "
+        f"In-range recognized markers: {interpretation.normal_count}."
+    )
+
+
+def _pattern_output(interpretation: Interpretation) -> str | None:
+    if not interpretation.patterns and not interpretation.flagged:
+        return "No flagged markers or cross-marker patterns."
+    lines: list[str] = []
+    for insight in interpretation.flagged[:6]:
+        note = insight.note or "(no KB note)"
+        lines.append(f"- {insight.marker} ({insight.status}): {note}")
+    if len(interpretation.flagged) > 6:
+        lines.append(f"- … and {len(interpretation.flagged) - 6} more flagged marker(s)")
+    for pattern in interpretation.patterns:
+        lines.append(f"- Pattern — {pattern.name}: {pattern.note}")
+    return "\n".join(lines)
+
+
+def _step_teaser(step: PipelineStep) -> str:
+    first_line = step.summary.strip().split("\n", 1)[0]
+    if len(first_line) > 96:
+        return first_line[:93].rstrip() + "..."
+    return first_line
+
+
+def _format_return_code(code: int | None) -> str:
+    if code is None:
+        return "—"
+    return str(code)
+
+
+def _format_meta_value(value: Any) -> str:
+    if value is None:
+        return "—"
+    if isinstance(value, (dict, list)):
+        return json.dumps(value, indent=2)
+    if isinstance(value, float):
+        return f"{value:.2f}"
+    return str(value)
+
+
+def _status_badge(status: str) -> str:
+    css = {
+        "complete": "bte-trace-status--complete",
+        "running": "bte-trace-status--running",
+        "failed": "bte-trace-status--failed",
+    }.get(status, "bte-trace-status--unknown")
+    label = status.replace("_", " ").title()
+    return f'<span class="bte-trace-status {css}">{html.escape(label)}</span>'
+
+
+def _metrics_table(step: PipelineStep) -> str:
+    rows: list[tuple[str, str]] = [
+        ("Status", step.status.replace("_", " ").title()),
+        ("Return code", _format_return_code(step.return_code)),
+    ]
+    skip_keys = {"notes", "unmatched_markers"}
+    for key, value in step.metadata.items():
+        if key in skip_keys or value in (None, "", [], {}):
+            continue
+        label = key.replace("_", " ").title()
+        rows.append((label, _format_meta_value(value)))
+
+    cells = "".join(
+        f"<div><dt>{html.escape(label)}</dt><dd>{html.escape(value)}</dd></div>"
+        for label, value in rows
+    )
+    return f'<dl class="bte-trace-meta">{cells}</dl>'
+
+
+def _trace_block(title: str, body: str, *, subtitle: str | None = None) -> str:
+    subtitle_html = (
+        f'<p class="bte-trace-subtitle">{html.escape(subtitle)}</p>' if subtitle else ""
+    )
+    return f"""
+    <section class="bte-trace-panel" aria-label="Agent pipeline trace">
+      <header class="bte-trace-panel-header">
+        <strong>{html.escape(title)}</strong>
+        {subtitle_html}
+      </header>
+      <div class="bte-trace-steps">
+        {body}
+      </div>
+    </section>
+    """
+
+
+def step_to_html(step: PipelineStep) -> str:
+    sections: list[str] = [
+        _metrics_table(step),
+        f'<p class="bte-trace-summary">{html.escape(step.summary)}</p>',
+    ]
+    if step.prompt:
+        sections.append(
+            '<details class="bte-trace-subdetails">'
+            "<summary>Full prompt</summary>"
+            f"<pre>{html.escape(step.prompt)}</pre>"
+            "</details>"
+        )
+    if step.input_preview:
+        sections.append(
+            '<details class="bte-trace-subdetails">'
+            "<summary>Input preview</summary>"
+            f"<pre>{html.escape(step.input_preview)}</pre>"
+            "</details>"
+        )
+    if step.output_preview:
+        sections.append(
+            '<details class="bte-trace-subdetails">'
+            "<summary>Output preview</summary>"
+            f"<pre>{html.escape(step.output_preview)}</pre>"
+            "</details>"
+        )
+    return f"""
+    <details class="bte-trace-step">
+      <summary class="bte-trace-step-summary">
+        <span class="bte-trace-step-heading">
+          <span class="bte-trace-step-title">{html.escape(step.title)}</span>
+          {_status_badge(step.status)}
+        </span>
+        <span class="bte-trace-step-meta">
+          Return code: {html.escape(_format_return_code(step.return_code))}
+        </span>
+        <span class="bte-trace-step-teaser">{html.escape(_step_teaser(step))}</span>
+      </summary>
+      <div class="bte-trace-step-body">
+        {"".join(sections)}
+      </div>
+    </details>
+    """
+
+
+def trace_to_html(steps: list[PipelineStep]) -> str:
+    body = "".join(step_to_html(step) for step in steps)
+    return _trace_block(
+        _TRACE_TITLE,
+        body,
+        subtitle="Expand any step to inspect status, return code, prompts, and outputs.",
+    )
+
+
+def empty_trace_html() -> str:
+    body = """
+    <p class="bte-trace-empty">
+      Upload a lab report to see every agent pipeline step here.
+    </p>
+    """
+    return _trace_block(_TRACE_TITLE, body)
+
+
+def processing_trace_html() -> str:
+    steps = [
+        PipelineStep(
+            id=step_id,
+            title=title,
+            status="running",
+            return_code=None,
+            summary="Waiting for upstream steps to finish…",
+            metadata={"pipeline_phase": "processing"},
+        )
+        for step_id, title in _PIPELINE_STEP_DEFS
+    ]
+    return _trace_block(
+        _TRACE_TITLE,
+        "".join(step_to_html(step) for step in steps),
+        subtitle="Pipeline running — reading your document and enriching results.",
+    )
+
+
+def error_trace_html(message: str) -> str:
+    failed_step = PipelineStep(
+        id="vision_extraction",
+        title="Step 2 — Vision extraction (LLM)",
+        status="failed",
+        return_code=1,
+        summary=message,
+        metadata={"pipeline_phase": "failed"},
+    )
+    body = step_to_html(failed_step)
+    return _trace_block(
+        _TRACE_TITLE,
+        body,
+        subtitle="Pipeline failed before the report could be generated.",
+    )
+
+
+def step_to_markdown(step: PipelineStep) -> str:
+    parts = [f"**{step.title}**", step.summary]
+    if step.prompt:
+        parts.append(
+            f"<details><summary>Full prompt</summary>\n\n```\n{step.prompt}\n```\n</details>"
+        )
+    if step.input_preview:
+        parts.append(
+            f"<details><summary>Input preview</summary>\n\n```\n{step.input_preview}\n```\n</details>"
+        )
+    if step.output_preview:
+        parts.append(
+            f"<details><summary>Output preview</summary>\n\n```\n{step.output_preview}\n```\n</details>"
+        )
+    return "\n\n".join(parts)
+
+
+def trace_to_chat_messages(steps: list[PipelineStep]) -> list[dict[str, str]]:
+    intro = (
+        "**Analysis pipeline complete.** Below are the agent steps that processed your document."
+    )
+    messages = [{"role": "assistant", "content": intro}]
+    for step in steps:
+        messages.append({"role": "assistant", "content": step_to_markdown(step)})
+    return messages
+
+
+def serialize_steps(steps: list[PipelineStep]) -> list[dict[str, Any]]:
+    return [asdict(step) for step in steps]
+
+
+def interpretation_to_dict(interpretation: Interpretation) -> dict[str, Any]:
+    return {
+        "flagged": [
+            {
+                "marker": item.marker,
+                "value": item.value,
+                "unit": item.unit,
+                "status": item.status,
+                "reference_range": item.reference_range,
+                "note": item.note,
+                "questions": list(item.questions),
+            }
+            for item in interpretation.flagged
+        ],
+        "normal_count": interpretation.normal_count,
+        "patterns": [{"name": p.name, "note": p.note} for p in interpretation.patterns],
+        "disclaimer": interpretation.disclaimer,
+    }
+
+
+def extraction_to_dict(extraction: ExtractionResult) -> dict[str, Any]:
+    return {
+        "patient": extraction.patient,
+        "tests": extraction.tests,
+        "notes": extraction.notes,
+        "raw_response": extraction.raw_response,
+        "request_summary": extraction.request_summary,
+    }
+
+
+def build_session_state(
+    extraction: ExtractionResult,
+    health_report: dict[str, Any],
+    steps: list[PipelineStep],
+) -> dict[str, Any]:
+    interpretation = build_interpretation(extraction.tests)
+    return {
+        "extraction": extraction_to_dict(extraction),
+        "health_report": health_report,
+        "interpretation": interpretation_to_dict(interpretation),
+        "trace_steps": serialize_steps(steps),
+    }

src/results_chat.py

@@ -0,0 +1,156 @@
+"""Context-aware chat about uploaded blood test results."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from src.extraction.text_generation import generate_text_chat
+
+CHAT_SYSTEM_PROMPT = """
+You are an educational assistant helping a patient understand blood test results.
+
+Rules:
+- Use ONLY the patient context, extracted lab values, knowledge-graph enrichment, and grounded
+  interpretation notes provided below.
+- Do not diagnose, prescribe, or invent medical facts not present in the context.
+- Use plain language and say when a clinician should interpret a result in person.
+- If the user asks about something not in the context, say you do not have that information.
+- Keep answers concise unless the user asks for detail.
+""".strip()
+
+_MAX_CONTEXT_CHARS = 8000
+_MAX_HISTORY_TURNS = 6
+
+
+class ResultsChatAssistant:
+    def reply(
+        self,
+        user_message: str,
+        chat_history: list[dict[str, str]] | None,
+        session: dict[str, Any] | None,
+    ) -> str:
+        message = (user_message or "").strip()
+        if not message:
+            return "Please enter a question about your blood test results."
+
+        if not session or not session.get("health_report"):
+            return "Upload and analyze a lab report first, then I can answer questions about your results."
+
+        context = build_chat_context(session)
+        messages = _build_messages(context, chat_history or [], message)
+        try:
+            return generate_text_chat(messages)
+        except Exception as exc:
+            return (
+                "I couldn't generate a chat reply with the current model backend. "
+                f"Details: {exc}"
+            )
+
+
+def build_chat_context(session: dict[str, Any]) -> str:
+    health_report = session.get("health_report") or {}
+    extraction = session.get("extraction") or {}
+    interpretation = session.get("interpretation") or {}
+
+    patient = health_report.get("patient") or extraction.get("patient") or {}
+    markers = health_report.get("markers") or []
+    summary = health_report.get("summary") or {}
+
+    lines: list[str] = [
+        "=== Patient context ===",
+        json.dumps(
+            {
+                "age": patient.get("age"),
+                "age_years": patient.get("age_years"),
+                "age_group": patient.get("age_group"),
+                "sex": patient.get("sex"),
+            },
+            indent=2,
+        ),
+        "",
+        "=== Report summary ===",
+        json.dumps(summary, indent=2),
+        "",
+        "=== Extracted markers ===",
+    ]
+
+    for marker in markers[:40]:
+        lines.append(
+            json.dumps(
+                {
+                    "name": marker.get("display_name") or marker.get("raw_name"),
+                    "value": marker.get("value"),
+                    "unit": marker.get("unit"),
+                    "status": marker.get("status"),
+                    "lab_reference_range": marker.get("lab_reference_range"),
+                    "comparison_basis": (marker.get("comparison") or {}).get("basis"),
+                    "kg_description": ((marker.get("knowledge") or {}).get("description")),
+                    "kg_importance": ((marker.get("knowledge") or {}).get("why_important")),
+                },
+                ensure_ascii=False,
+            )
+        )
+
+    if interpretation.get("flagged"):
+        lines.extend(["", "=== Flagged markers (KB-grounded) ==="])
+        for item in interpretation["flagged"]:
+            lines.append(json.dumps(item, ensure_ascii=False))
+
+    if interpretation.get("patterns"):
+        lines.extend(["", "=== Cross-marker patterns ==="])
+        for item in interpretation["patterns"]:
+            lines.append(json.dumps(item, ensure_ascii=False))
+
+    if extraction.get("notes"):
+        lines.extend(["", "=== Extraction notes ===", json.dumps(extraction["notes"], indent=2)])
+
+    lines.extend(["", "=== Disclaimer ===", interpretation.get("disclaimer", "")])
+
+    context = "\n".join(lines)
+    if len(context) <= _MAX_CONTEXT_CHARS:
+        return context
+    return context[: _MAX_CONTEXT_CHARS - 3].rstrip() + "..."
+
+
+def _build_messages(
+    context: str,
+    chat_history: list[dict[str, str]],
+    user_message: str,
+) -> list[dict[str, str]]:
+    messages: list[dict[str, str]] = [
+        {"role": "system", "content": CHAT_SYSTEM_PROMPT},
+        {"role": "user", "content": f"Blood test context:\n\n{context}"},
+        {
+            "role": "assistant",
+            "content": "I have your blood test context. Ask me anything about these results.",
+        },
+    ]
+
+    recent = _recent_chat_turns(chat_history)
+    messages.extend(recent)
+    messages.append({"role": "user", "content": user_message})
+    return messages
+
+
+def _recent_chat_turns(chat_history: list[dict[str, str]]) -> list[dict[str, str]]:
+    """Keep only user follow-up turns, skipping pipeline trace assistant messages."""
+    turns: list[dict[str, str]] = []
+    for item in chat_history:
+        role = item.get("role")
+        content = str(item.get("content") or "").strip()
+        if not content or role not in {"user", "assistant"}:
+            continue
+        if role == "assistant" and content.startswith("**Step "):
+            continue
+        if role == "assistant" and content.startswith("**Analysis pipeline complete."):
+            continue
+        if role == "assistant" and content.startswith("**Pipeline running"):
+            continue
+        if role == "assistant" and content.startswith("Upload a lab report"):
+            continue
+        turns.append({"role": role, "content": content})
+
+    if len(turns) > _MAX_HISTORY_TURNS * 2:
+        turns = turns[-(_MAX_HISTORY_TURNS * 2) :]
+    return turns

tests/test_document_processing.py

@@ -0,0 +1,93 @@
+import sys
+import tempfile
+from pathlib import Path
+
+import fitz
+from PIL import Image
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from src.document_processing import document_intake_metadata, document_to_payload_parts, validate_upload
+
+
+def test_png_upload_returns_image_url_part():
+    with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as tmp:
+        path = tmp.name
+        Image.new("RGB", (32, 32), color="white").save(path)
+
+    parts = document_to_payload_parts(path)
+    assert len(parts) == 1
+    assert parts[0]["type"] == "image_url"
+    assert parts[0]["image_url"]["url"].startswith("data:image/jpeg;base64,")
+
+
+def test_jpeg_upload_returns_image_url_part():
+    with tempfile.NamedTemporaryFile(suffix=".jpg", delete=False) as tmp:
+        path = tmp.name
+        Image.new("RGB", (24, 24), color="red").save(path, format="JPEG")
+
+    parts = document_to_payload_parts(path)
+    assert len(parts) == 1
+    assert parts[0]["type"] == "image_url"
+
+
+def test_pdf_upload_renders_pages_to_images():
+    with tempfile.NamedTemporaryFile(suffix=".pdf", delete=False) as tmp:
+        path = tmp.name
+        document = fitz.open()
+        page = document.new_page()
+        page.insert_text((72, 72), "Hemoglobin 12.5 g/dL")
+        document.save(path)
+        document.close()
+
+    parts = document_to_payload_parts(path, max_pages=1)
+    assert len(parts) == 1
+    assert parts[0]["type"] == "image_url"
+    assert parts[0]["image_url"]["url"].startswith("data:image/png;base64,")
+
+
+def test_text_upload_still_returns_text_part():
+    with tempfile.NamedTemporaryFile(suffix=".txt", delete=False, mode="w", encoding="utf-8") as tmp:
+        tmp.write("Hemoglobin 13.1 g/dL")
+        path = tmp.name
+
+    parts = document_to_payload_parts(path)
+    assert len(parts) == 1
+    assert parts[0]["type"] == "text"
+    assert "Hemoglobin" in parts[0]["text"]
+
+
+def test_validate_upload_rejects_unknown_extension():
+    with tempfile.NamedTemporaryFile(suffix=".docx", delete=False) as tmp:
+        path = tmp.name
+    try:
+        validate_upload(path)
+        raise AssertionError("expected ValueError")
+    except ValueError as error:
+        assert "Unsupported file type" in str(error)
+
+
+def test_document_intake_metadata_for_pdf():
+    with tempfile.NamedTemporaryFile(suffix=".pdf", delete=False) as tmp:
+        path = tmp.name
+        document = fitz.open()
+        page = document.new_page()
+        page.insert_text((72, 72), "Sample")
+        document.save(path)
+        document.close()
+
+    parts = document_to_payload_parts(path, max_pages=1)
+    metadata = document_intake_metadata(path, parts)
+    assert metadata["input_modality"] == "vision"
+    assert metadata["pages_rendered"] == 1
+    assert metadata["image_count"] == 1
+
+
+if __name__ == "__main__":
+    test_png_upload_returns_image_url_part()
+    test_jpeg_upload_returns_image_url_part()
+    test_pdf_upload_renders_pages_to_images()
+    test_text_upload_still_returns_text_part()
+    test_validate_upload_rejects_unknown_extension()
+    test_document_intake_metadata_for_pdf()
+    print("test_document_processing: ok")

tests/test_model_paths.py

@@ -0,0 +1,43 @@
+import sys
+import tempfile
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from src.model_paths import is_transformers_model_dir, resolve_transformers_model_source
+
+
+def test_resolve_uses_hub_download_when_no_local_weights():
+    with tempfile.TemporaryDirectory() as tmp:
+        source = resolve_transformers_model_source("openbmb/MiniCPM-V-4.6")
+        assert source.local_files_only is False
+        assert source.origin == "hub-download"
+        assert source.model_id == "openbmb/MiniCPM-V-4.6"
+
+
+def test_resolve_uses_local_dir_when_complete():
+    with tempfile.TemporaryDirectory() as tmp:
+        model_dir = Path(tmp) / "MiniCPM-V-4.6"
+        model_dir.mkdir()
+        (model_dir / "config.json").write_text("{}", encoding="utf-8")
+        (model_dir / "model.safetensors").write_bytes(b"test")
+
+        source = resolve_transformers_model_source(str(model_dir))
+        assert source.local_files_only is True
+        assert source.origin == "local-dir"
+        assert Path(source.model_id) == model_dir.resolve()
+
+
+def test_is_transformers_model_dir_requires_weights():
+    with tempfile.TemporaryDirectory() as tmp:
+        model_dir = Path(tmp) / "partial"
+        model_dir.mkdir()
+        (model_dir / "config.json").write_text("{}", encoding="utf-8")
+        assert is_transformers_model_dir(model_dir) is False
+
+
+if __name__ == "__main__":
+    test_resolve_uses_hub_download_when_no_local_weights()
+    test_resolve_uses_local_dir_when_complete()
+    test_is_transformers_model_dir_requires_weights()
+    print("test_model_paths: ok")

tests/test_pipeline_trace.py

@@ -0,0 +1,100 @@
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from src.openbmb_client import EXTRACTION_PROMPT, ExtractionResult
+from src.pipeline_trace import build_pipeline_trace, trace_to_html, trace_to_chat_messages
+from src.report_pipeline import build_health_report
+
+
+def _sample_extraction() -> ExtractionResult:
+    return ExtractionResult(
+        patient={"age": "42y", "age_years": 42.0, "sex": "female", "age_group": "adult"},
+        tests=[
+            {
+                "marker": "Hemoglobin",
+                "value": "11.2",
+                "unit": "g/dL",
+                "reference_range": "12.0-16.0",
+                "status": "low",
+                "source_text": "Hgb 11.2",
+                "confidence": 0.95,
+            },
+            {
+                "marker": "WBC",
+                "value": "6.5",
+                "unit": "10^3/uL",
+                "reference_range": "4.5-11.0",
+                "status": "normal",
+                "source_text": "WBC 6.5",
+                "confidence": 0.9,
+            },
+        ],
+        notes=["Sample note"],
+        raw_response='{"tests":[{"marker":"Hemoglobin","value":"11.2"}]}',
+        request_summary={
+            "backend": "test",
+            "extraction_prompt": EXTRACTION_PROMPT,
+            "document_parts": 2,
+            "http_status": 200,
+            "return_code": 0,
+            "duration_ms": 842,
+            "user_message_preview": {"image_count": 1, "text_characters": 120},
+        },
+    )
+
+
+def test_build_pipeline_trace_has_five_steps():
+    extraction = _sample_extraction()
+    report = build_health_report(extraction)
+    steps = build_pipeline_trace(extraction, report, source_path="/tmp/report.pdf")
+    assert len(steps) == 5
+    assert [step.id for step in steps] == [
+        "document_intake",
+        "vision_extraction",
+        "schema_normalization",
+        "knowledge_graph",
+        "pattern_detection",
+    ]
+
+
+def test_extraction_step_includes_full_prompt():
+    extraction = _sample_extraction()
+    report = build_health_report(extraction)
+    steps = build_pipeline_trace(extraction, report)
+    extraction_step = steps[1]
+    assert extraction_step.prompt == EXTRACTION_PROMPT
+    assert extraction_step.return_code == 0
+    assert extraction_step.metadata["http_status"] == 200
+    assert extraction_step.metadata["duration_ms"] == 842
+
+
+def test_trace_to_html_collapsible_steps():
+    extraction = _sample_extraction()
+    report = build_health_report(extraction)
+    steps = build_pipeline_trace(extraction, report)
+    html = trace_to_html(steps)
+    assert "bte-trace-step" in html
+    assert html.count('<details class="bte-trace-step">') == len(steps)
+    assert "Return code" in html
+    assert "bte-trace-status--complete" in html
+    assert "Full prompt" in html
+
+
+def test_trace_to_chat_messages_shape():
+    extraction = _sample_extraction()
+    report = build_health_report(extraction)
+    steps = build_pipeline_trace(extraction, report)
+    messages = trace_to_chat_messages(steps)
+    assert messages[0]["role"] == "assistant"
+    assert all(msg["role"] == "assistant" for msg in messages)
+    assert len(messages) == len(steps) + 1
+
+
+if __name__ == "__main__":
+    test_build_pipeline_trace_has_five_steps()
+    test_extraction_step_includes_full_prompt()
+    test_trace_to_html_collapsible_steps()
+    test_trace_to_chat_messages_shape()
+    print("test_pipeline_trace: ok")

tests/test_report_pipeline.py

@@ -90,6 +90,50 @@ def test_knowledge_graph_has_sex_guidance_for_every_marker():
     assert all("sex_specific_statistics_per_group_age" in test for test in high)
 
 
+# CBC markers in src/markers.py must match KG adult fallback intervals (fix #3).
+_KG_CBC_MARKER_MAP = {
+    "Hemoglobin": "hemoglobin",
+    "Hematocrit": "hct",
+    "Red Blood Cell Count": "rbc",
+    "White Blood Cell Count": "wbc",
+    "Platelet Count": "plt",
+    "MCV": "mcv",
+    "MCH": "mch",
+    "MCHC": "mchc",
+    "RDW": "rdw_cv",
+    "Absolute Lymphocyte Count": "lym_absolute",
+    "ESR": "esr",
+}
+
+
+def test_knowledge_graph_normal_values_are_midpoints():
+    graph = LabKnowledgeGraph.load()
+    for test in graph.tests:
+        for stats_key in ("statistics_per_group_age",):
+            stats = test.get(stats_key) or {}
+            for vals in stats.values():
+                lo, hi, mid = vals["minimal_value"], vals["maximum_value"], vals["normal_value"]
+                assert mid == round((lo + hi) / 2, 2)
+        sex_stats = test.get("sex_specific_statistics_per_group_age") or {}
+        for group_stats in sex_stats.values():
+            for vals in group_stats.values():
+                lo, hi, mid = vals["minimal_value"], vals["maximum_value"], vals["normal_value"]
+                assert mid == round((lo + hi) / 2, 2)
+
+
+def test_markers_py_cbc_ranges_match_knowledge_graph():
+    from src.markers import MARKERS
+
+    graph = LabKnowledgeGraph.load()
+    by_name = {m.name: m for m in MARKERS}
+    for marker_name, node_id in _KG_CBC_MARKER_MAP.items():
+        marker = by_name[marker_name]
+        node = graph.get(node_id)
+        adult = node["statistics_per_group_age"]["adult"]
+        assert marker.ref_low == adult["minimal_value"], marker_name
+        assert marker.ref_high == adult["maximum_value"], marker_name
+
+
 def test_final_report_bar_uses_kg_min_normal_and_max_values():
     report = build_health_report(
         _result(

tests/test_results_chat.py

@@ -0,0 +1,60 @@
+import sys
+from pathlib import Path
+from unittest.mock import patch
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from src.openbmb_client import ExtractionResult
+from src.pipeline_trace import build_pipeline_trace, build_session_state
+from src.report_pipeline import build_health_report
+from src.results_chat import ResultsChatAssistant, build_chat_context
+
+
+def _session() -> dict:
+    extraction = ExtractionResult(
+        patient={"age_years": 42, "sex": "female"},
+        tests=[
+            {
+                "marker": "Hemoglobin",
+                "value": "11.2",
+                "unit": "g/dL",
+                "reference_range": "12.0-16.0",
+                "status": "low",
+                "confidence": 0.9,
+            }
+        ],
+        notes=[],
+        raw_response="{}",
+        request_summary={"backend": "test", "document_parts": 1},
+    )
+    report = build_health_report(extraction)
+    steps = build_pipeline_trace(extraction, report)
+    return build_session_state(extraction, report, steps)
+
+
+def test_build_chat_context_includes_patient_and_markers():
+    context = build_chat_context(_session())
+    assert "female" in context
+    assert "Hemoglobin" in context
+    assert "Report summary" in context
+
+
+def test_reply_requires_session():
+    assistant = ResultsChatAssistant()
+    reply = assistant.reply("What is low hemoglobin?", [], {})
+    assert "Upload and analyze" in reply
+
+
+def test_reply_uses_llm_when_session_present():
+    assistant = ResultsChatAssistant()
+    session = _session()
+    with patch("src.results_chat.generate_text_chat", return_value="Educational reply."):
+        reply = assistant.reply("Explain my hemoglobin.", [], session)
+    assert reply == "Educational reply."
+
+
+if __name__ == "__main__":
+    test_build_chat_context_includes_patient_and_markers()
+    test_reply_requires_session()
+    test_reply_uses_llm_when_session_present()
+    print("test_results_chat: ok")