feat: gentler fine-tune + diversified synth data + interpretation engine + before/after eval

- modal_finetune: lower LR (2e-5) + warmup, 1 epoch, tunable hyperparams; re-runnable merge.
- synth_reports: section-grouped/varied layouts + ref-range/theme/demographic diversity to fix overfitting that regressed real-report extraction.
- modal_eval: Modal before/after eval (base vs fine-tuned) on the labeled reports.
- kb/knowledge_base + interpretation: grounded per-marker insight + cross-marker patterns (Phase 3).

kb/knowledge_base.py

@@ -0,0 +1,288 @@
+"""Grounded interpretation knowledge base (Phase 3).
+
+The model does NOT invent medical facts. It extracts values (vision) and then *phrases* the facts
+stored here. Every interpretation the app shows is grounded in this file, which is in turn based on
+the reference material under kb/references/ (psap_reference_values.pdf, nbme_reference_values.pdf)
+and standard general-population clinical references.
+
+This is an EDUCATIONAL tool, not a diagnosis. Entries describe common, well-established
+associations only ("a high value may be associated with ..."), never a diagnosis or treatment.
+Canonical marker names + reference ranges live in src/markers.py (single source of truth).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from src.markers import Marker, resolve
+
+DISCLAIMER = (
+    "This is general educational information, not a medical diagnosis. Only a qualified clinician "
+    "can interpret your results in the context of your history, symptoms, and other tests."
+)
+
+
+@dataclass(frozen=True)
+class MarkerKB:
+    """What a high/low value commonly relates to, plus questions to bring to a doctor."""
+
+    high: str
+    low: str
+    questions: tuple[str, ...] = field(default_factory=tuple)
+
+
+# Per-marker grounded facts. "" for a direction means it is not typically clinically flagged there
+# (e.g. a low LDL is generally favorable). Keep statements associative and educational.
+KB: dict[str, MarkerKB] = {
+    # --- Complete blood count ---
+    "Hemoglobin": MarkerKB(
+        high="May be associated with dehydration, smoking, living at high altitude, or less commonly the body making too many red cells.",
+        low="A low hemoglobin is the hallmark of anemia, which can stem from iron, B12 or folate deficiency, blood loss, or chronic disease.",
+        questions=("Could this explain my tiredness or shortness of breath?", "Should we check iron, B12, or folate?"),
+    ),
+    "Hematocrit": MarkerKB(
+        high="Often tracks with hemoglobin; may reflect dehydration or increased red-cell production.",
+        low="Usually moves with hemoglobin and points toward anemia or recent blood loss.",
+        questions=("Does this match my hemoglobin result?",),
+    ),
+    "White Blood Cell Count": MarkerKB(
+        high="A high white count commonly accompanies infection or inflammation, physical stress, or certain medications; rarely it reflects a blood disorder.",
+        low="A low white count can follow viral infections, some medications, or affect the immune system's ability to fight infection.",
+        questions=("Could a recent infection explain this?", "Do we need to recheck it once I'm well?"),
+    ),
+    "Platelet Count": MarkerKB(
+        high="May rise with inflammation, infection, iron deficiency, or after the spleen is removed.",
+        low="A low platelet count can increase bruising or bleeding and may relate to infections, medications, or the bone marrow.",
+        questions=("Should I avoid anything that thins my blood until this is checked?",),
+    ),
+    "Red Blood Cell Count": MarkerKB(
+        high="May reflect dehydration, smoking, or increased red-cell production.",
+        low="Often part of the anemia picture alongside low hemoglobin/hematocrit.",
+        questions=("Does this fit with my hemoglobin and MCV?",),
+    ),
+    "MCV": MarkerKB(
+        high="A high MCV (large red cells) is classically associated with B12 or folate deficiency, alcohol, or thyroid issues.",
+        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?",),
+    ),
+    # --- Metabolic panel ---
+    "Glucose": MarkerKB(
+        high="An elevated fasting glucose can indicate prediabetes or diabetes, or simply that the sample was not fasting.",
+        low="A low glucose can cause shakiness or lightheadedness and may relate to fasting, medications, or how the sample was handled.",
+        questions=("Was this a fasting sample?", "Should we confirm with an HbA1c?"),
+    ),
+    "Creatinine": MarkerKB(
+        high="A high creatinine suggests the kidneys are filtering less efficiently; muscle mass, dehydration, and some medications also raise it.",
+        low="A low creatinine is usually not a concern and can reflect lower muscle mass.",
+        questions=("What does this mean for my kidney function (eGFR)?",),
+    ),
+    "eGFR": MarkerKB(
+        high="A higher eGFR generally indicates better kidney filtration.",
+        low="A low eGFR indicates reduced kidney filtration and is usually interpreted together with creatinine over time.",
+        questions=("Is this a one-off or a trend?", "Should any of my medications be dose-adjusted?"),
+    ),
+    "Blood Urea Nitrogen": MarkerKB(
+        high="BUN can rise with dehydration, a high-protein diet, or reduced kidney function.",
+        low="A low BUN is rarely significant; it can reflect low protein intake or overhydration.",
+        questions=("Does my BUN-to-creatinine ratio suggest dehydration?",),
+    ),
+    "Sodium": MarkerKB(
+        high="High sodium usually reflects dehydration or fluid balance, not dietary salt alone.",
+        low="Low sodium is one of the most common electrolyte abnormalities and relates to fluid balance, medications, or hormones.",
+        questions=("Could my medications or fluid intake be affecting this?",),
+    ),
+    "Potassium": MarkerKB(
+        high="High potassium can affect heart rhythm and may relate to kidney function or medications; it can also be falsely high from the blood draw.",
+        low="Low potassium can cause muscle weakness or cramps and often relates to fluid loss or diuretics.",
+        questions=("Should this be rechecked given how it affects the heart?",),
+    ),
+    "Chloride": MarkerKB(
+        high="Usually moves with sodium and acid-base balance.",
+        low="Usually moves with sodium and acid-base balance.",
+        questions=("Does this fit with my sodium and bicarbonate?",),
+    ),
+    "Calcium": MarkerKB(
+        high="High calcium can relate to the parathyroid glands, vitamin D, or other conditions and is worth following up.",
+        low="Low calcium can relate to vitamin D, the parathyroid glands, or low albumin (which carries calcium).",
+        questions=("Should we check vitamin D or parathyroid hormone?",),
+    ),
+    "Albumin": MarkerKB(
+        high="A high albumin most often reflects dehydration.",
+        low="A low albumin can reflect nutrition, inflammation, or liver/kidney conditions.",
+        questions=("Could this be related to my diet or another result?",),
+    ),
+    "Total Protein": MarkerKB(
+        high="May reflect dehydration or increased production of certain proteins.",
+        low="May reflect nutrition, liver, or kidney factors.",
+        questions=("Does this fit with my albumin level?",),
+    ),
+    # --- Liver enzymes ---
+    "ALT": MarkerKB(
+        high="ALT is fairly liver-specific; elevations can follow fatty liver, alcohol, medications, or viral hepatitis.",
+        low="A low ALT is not typically a concern.",
+        questions=("Could a medication or fatty liver explain this?", "Should we recheck in a few weeks?"),
+    ),
+    "AST": MarkerKB(
+        high="AST rises with liver stress but also comes from muscle; the AST/ALT pattern helps point to a cause.",
+        low="A low AST is not typically a concern.",
+        questions=("Does the AST/ALT ratio suggest a specific cause?",),
+    ),
+    "ALP": MarkerKB(
+        high="A high alkaline phosphatase can come from the liver/bile ducts or from bone; growth and pregnancy also raise it.",
+        low="A low ALP is uncommon and rarely significant.",
+        questions=("Is this from my liver or my bones?",),
+    ),
+    "GGT": MarkerKB(
+        high="GGT is sensitive to bile-duct issues and alcohol; it helps clarify whether a high ALP is from the liver.",
+        low="A low GGT is not a concern.",
+        questions=("Does my GGT help explain my ALP?",),
+    ),
+    "Total Bilirubin": MarkerKB(
+        high="A mildly high bilirubin is often benign (e.g. Gilbert's syndrome) but can relate to the liver or red-cell breakdown.",
+        low="A low bilirubin is not a concern.",
+        questions=("Is this mild and stable, or does it need follow-up?",),
+    ),
+    # --- 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.",
+        low="A low total cholesterol is generally not a concern.",
+        questions=("What is my overall cardiovascular risk?", "Diet/lifestyle first, or is medication warranted?"),
+    ),
+    "LDL Cholesterol": MarkerKB(
+        high="LDL ('bad' cholesterol) is the main driver of plaque buildup; targets depend on your personal risk.",
+        low="A low LDL is generally favorable.",
+        questions=("What LDL target is right for my risk level?",),
+    ),
+    "HDL Cholesterol": MarkerKB(
+        high="A higher HDL ('good' cholesterol) is generally protective.",
+        low="A low HDL is associated with higher cardiovascular risk; exercise and not smoking help raise it.",
+        questions=("Would lifestyle changes help raise my HDL?",),
+    ),
+    "Triglycerides": MarkerKB(
+        high="High triglycerides relate to diet, alcohol, weight, and blood-sugar control, and add to cardiovascular risk.",
+        low="A low triglyceride level is generally not a concern.",
+        questions=("Was this fasting?", "Would diet changes help?"),
+    ),
+    # --- Thyroid ---
+    "TSH": MarkerKB(
+        high="A high TSH usually signals an underactive thyroid (the body asking for more hormone).",
+        low="A low TSH usually signals an overactive thyroid.",
+        questions=("Should we confirm with a Free T4?", "Could symptoms like fatigue or weight change relate to this?"),
+    ),
+    "Free T4": MarkerKB(
+        high="A high Free T4 supports an overactive thyroid picture.",
+        low="A low Free T4 supports an underactive thyroid picture.",
+        questions=("How does this fit with my TSH?",),
+    ),
+    # --- Vitamins / iron ---
+    "Vitamin D": MarkerKB(
+        high="A very high vitamin D is uncommon and usually from supplements.",
+        low="Low vitamin D is common and relates to bone and immune health; sunlight and diet/supplements affect it.",
+        questions=("Should I supplement, and at what dose?",),
+    ),
+    "Vitamin B12": MarkerKB(
+        high="A high B12 is usually from supplements and rarely a concern on its own.",
+        low="Low B12 can cause fatigue, nerve symptoms, and large red cells (high MCV); diet and absorption matter.",
+        questions=("Could this explain my tiredness or tingling?", "Do we need to check absorption?"),
+    ),
+    "Ferritin": MarkerKB(
+        high="Ferritin rises with inflammation as well as iron overload, so a high value is read in context.",
+        low="A low ferritin is the most specific sign of low iron stores and a common cause of anemia.",
+        questions=("Does my ferritin explain my hemoglobin and MCV?", "Should we look for a source of iron loss?"),
+    ),
+    "HbA1c": MarkerKB(
+        high="A high HbA1c reflects higher average blood sugar over ~3 months and is used to screen for prediabetes and diabetes.",
+        low="A low HbA1c is generally not a concern.",
+        questions=("Am I in the prediabetes range?", "What changes would lower this?"),
+    ),
+}
+
+
+@dataclass(frozen=True)
+class Pattern:
+    """A cross-marker pattern the interpretation layer can surface (Phase 3.3)."""
+
+    name: str
+    when: str  # human-readable trigger description (logic lives in the interpretation module)
+    note: str
+
+
+# Cross-marker patterns: clusters that mean more together than any single value.
+PATTERNS: tuple[Pattern, ...] = (
+    Pattern(
+        "Anemia picture",
+        "low Hemoglobin with low Hematocrit (and often low RBC)",
+        "These low red-cell values together suggest anemia; MCV and ferritin help point to the cause (iron vs B12/folate).",
+    ),
+    Pattern(
+        "Iron-deficiency pattern",
+        "low Ferritin with low MCV (microcytic) and low Hemoglobin",
+        "Small red cells plus low iron stores are a classic iron-deficiency pattern worth discussing with a clinician.",
+    ),
+    Pattern(
+        "B12/folate pattern",
+        "high MCV (macrocytic) with low Vitamin B12",
+        "Large red cells alongside low B12 point toward a B12 or folate cause rather than iron.",
+    ),
+    Pattern(
+        "Liver cluster",
+        "elevated ALT and/or AST, sometimes with ALP and GGT",
+        "Several liver enzymes elevated together raise the question of liver stress; the AST/ALT and ALP/GGT patterns help localize it.",
+    ),
+    Pattern(
+        "Lipid / cardiovascular risk",
+        "high LDL or Triglycerides with low HDL",
+        "This lipid combination raises cardiovascular risk and is best interpreted with your overall risk profile.",
+    ),
+    Pattern(
+        "Kidney-function pattern",
+        "high Creatinine with low eGFR (and sometimes high BUN)",
+        "Together these suggest reduced kidney filtration; trend over time matters more than a single reading.",
+    ),
+    Pattern(
+        "Thyroid pattern",
+        "high TSH with low Free T4 (underactive) or low TSH with high Free T4 (overactive)",
+        "TSH and Free T4 read together indicate whether the thyroid is under- or over-active.",
+    ),
+    Pattern(
+        "Glycemic 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.",
+    ),
+)
+
+
+def interpret(marker_name: str, status: str) -> str | None:
+    """Return the grounded educational note for a marker at a given status, or None.
+
+    `status` is one of 'high', 'low', 'normal' (as produced by Marker.status_for / extraction).
+    Returns None when there is nothing flagged to say (normal, or no benign-direction note).
+    """
+    marker = resolve(marker_name)
+    if marker is None:
+        return None
+    entry = KB.get(marker.name)
+    if entry is None:
+        return None
+    if status == "high":
+        return entry.high or None
+    if status == "low":
+        return entry.low or None
+    return None
+
+
+def questions_for(marker_name: str) -> tuple[str, ...]:
+    """Doctor-questions to surface for a flagged marker (Phase 3.4)."""
+    marker = resolve(marker_name)
+    if marker is None:
+        return ()
+    entry = KB.get(marker.name)
+    return entry.questions if entry else ()
+
+
+def coverage() -> tuple[int, int]:
+    """(markers with KB entries, total canonical markers) — for a quick completeness check."""
+    from src.markers import MARKERS
+
+    covered = sum(1 for m in MARKERS if m.name in KB)
+    return covered, len(MARKERS)

src/interpretation.py

@@ -0,0 +1,135 @@
+"""Interpretation engine (Phase 3.2–3.4): turn extracted values into grounded insight.
+
+The model extracts the numbers; THIS module decides what is worth saying, and every word of
+medical content comes from the knowledge base (kb/knowledge_base.py), never invented. Output:
+  - per-marker insight cards for flagged (high/low) markers, with doctor-questions  [3.2, 3.4]
+  - cross-marker patterns that mean more together than alone                         [3.3]
+  - an educational disclaimer
+
+Pure functions + plain dataclasses so the app can render them and the eval can test them.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from kb.knowledge_base import DISCLAIMER, PATTERNS, interpret, questions_for
+from src.markers import resolve
+
+_PATTERN_NOTE = {p.name: p.note for p in PATTERNS}
+
+
+@dataclass(frozen=True)
+class MarkerInsight:
+    marker: str            # canonical name
+    value: str
+    unit: str | None
+    status: str            # "low" | "high"
+    reference_range: str
+    note: str | None       # grounded educational note from the KB
+    questions: tuple[str, ...] = field(default_factory=tuple)
+
+
+@dataclass(frozen=True)
+class PatternInsight:
+    name: str
+    note: str
+
+
+@dataclass(frozen=True)
+class Interpretation:
+    flagged: tuple[MarkerInsight, ...]   # abnormal markers only
+    normal_count: int                    # how many recognized markers were in range
+    patterns: tuple[PatternInsight, ...]
+    disclaimer: str = DISCLAIMER
+
+    @property
+    def has_findings(self) -> bool:
+        return bool(self.flagged or self.patterns)
+
+
+def _num(value: object) -> float | None:
+    """Pull the first numeric token out of a value like '12.3', '12.3 *', or '< 0.5'."""
+    if value is None:
+        return None
+    m = re.search(r"-?\d+(?:\.\d+)?", str(value))
+    return float(m.group(0)) if m else None
+
+
+def _status_of(test: dict, marker) -> str:
+    """Trust the model's status when valid, else compute it from value vs the marker's range."""
+    status = str(test.get("status") or "").strip().lower()
+    if status in {"low", "normal", "high"}:
+        return status
+    value = _num(test.get("value"))
+    if value is not None:
+        return marker.status_for(value)
+    return "unknown"
+
+
+def build_interpretation(tests: list[dict]) -> Interpretation:
+    """Build the grounded interpretation from a list of extracted test dicts."""
+    flagged: list[MarkerInsight] = []
+    normal = 0
+    status_by_marker: dict[str, str] = {}
+
+    for test in tests:
+        marker = resolve(str(test.get("marker") or ""))
+        if marker is None:
+            continue  # unknown marker -> we don't invent meaning for it
+        status = _status_of(test, marker)
+        status_by_marker[marker.name] = status
+        if status in {"low", "high"}:
+            flagged.append(
+                MarkerInsight(
+                    marker=marker.name,
+                    value=str(test.get("value") or "").strip(),
+                    unit=(test.get("unit") or marker.unit),
+                    status=status,
+                    reference_range=marker.ref_range_text(),
+                    note=interpret(marker.name, status),
+                    questions=questions_for(marker.name),
+                )
+            )
+        elif status == "normal":
+            normal += 1
+
+    return Interpretation(
+        flagged=tuple(flagged),
+        normal_count=normal,
+        patterns=tuple(_detect_patterns(status_by_marker)),
+    )
+
+
+def _detect_patterns(s: dict[str, str]) -> list[PatternInsight]:
+    """Apply the cross-marker pattern logic (the human-readable triggers live in the KB)."""
+    out: list[PatternInsight] = []
+
+    def at(name: str, *statuses: str) -> bool:
+        return s.get(name) in statuses
+
+    liver_high = sum(at(m, "high") for m in ("ALT", "AST", "ALP", "GGT"))
+
+    if at("Hemoglobin", "low") and at("Hematocrit", "low"):
+        out.append(_pattern("Anemia picture"))
+    if at("Ferritin", "low") and at("MCV", "low"):
+        out.append(_pattern("Iron-deficiency pattern"))
+    if at("MCV", "high") and at("Vitamin B12", "low"):
+        out.append(_pattern("B12/folate pattern"))
+    if liver_high >= 2:
+        out.append(_pattern("Liver cluster"))
+    if (at("LDL Cholesterol", "high") or at("Triglycerides", "high")) and at("HDL Cholesterol", "low"):
+        out.append(_pattern("Lipid / cardiovascular risk"))
+    if at("Creatinine", "high") and at("eGFR", "low"):
+        out.append(_pattern("Kidney-function pattern"))
+    if (at("TSH", "high") and at("Free T4", "low")) or (at("TSH", "low") and at("Free T4", "high")):
+        out.append(_pattern("Thyroid pattern"))
+    if at("Glucose", "high") and at("HbA1c", "high"):
+        out.append(_pattern("Glycemic pattern"))
+
+    return out
+
+
+def _pattern(name: str) -> PatternInsight:
+    return PatternInsight(name=name, note=_PATTERN_NOTE[name])

train/modal_eval.py

@@ -0,0 +1,120 @@
+"""Before/after extraction eval on Modal — the OpenBMB proof.
+
+Runs the labeled reports through the BASE and the FINE-TUNED model on a GPU and reports the
+field-level accuracy jump. The model runs through the same ZeroGPU/Transformers backend the Space
+uses (here `@spaces.GPU` is a no-op because the `spaces` package isn't installed, so generation
+runs directly on the Modal GPU).
+
+    modal run train/modal_eval.py::compare --finetuned-id dimitriskalligaridis/blood-test-minicpmv-4_6
+
+Writes eval/before_after.json locally; render the chart with:  python eval/make_chart.py
+"""
+
+from __future__ import annotations
+
+import modal
+
+app = modal.App("blood-test-eval")
+
+image = (
+    modal.Image.debian_slim(python_version="3.11")
+    .apt_install("git")
+    .pip_install(
+        "torch",
+        "torchvision",
+        "transformers[torch]>=5.7.0",
+        "accelerate",
+        "pillow",
+        "pymupdf",
+        "av",
+        "requests",
+        "json-repair",
+    )
+    # NOTE: deliberately no `spaces` package -> @spaces.GPU is a no-op -> runs on the Modal GPU.
+    .add_local_dir("src", "/root/app/src")
+    .add_local_dir("kb", "/root/app/kb")
+    .add_local_dir("eval", "/root/app/eval")
+)
+
+hf_cache = modal.Volume.from_name("blood-test-hf-cache", create_if_missing=True)
+
+
+@app.function(
+    image=image,
+    gpu="A100",
+    timeout=60 * 60,
+    volumes={"/root/.cache/huggingface": hf_cache},
+    secrets=[modal.Secret.from_name("huggingface-secret")],
+)
+def eval_model(model_id: str, labels_rel: str = "eval/data/real/labels.jsonl") -> dict:
+    """Run the configured model over the labeled reports and return field-level metrics."""
+    import json
+    import os
+    import sys
+    from pathlib import Path
+
+    sys.path.insert(0, "/root/app")
+    os.environ["ZEROGPU_QUANTIZE"] = "0"  # bf16 — a clean, representative eval
+
+    from src.eval_scoring import format_metrics, score
+    # Import the ZeroGPU backend directly (not via the factory) so we don't pull in the llama.cpp
+    # backend, which isn't installed in this eval image.
+    from src.extraction.zerogpu_transformers import ZeroGPUTransformersExtractor
+
+    labels_path = Path("/root/app") / labels_rel
+    gold = [json.loads(ln) for ln in labels_path.read_text(encoding="utf-8").splitlines() if ln.strip()]
+    extractor = ZeroGPUTransformersExtractor(model_id=model_id)
+    base_dir = labels_path.parent
+
+    preds: list[dict] = []
+    for i, row in enumerate(gold):
+        image_path = str((base_dir / row["image"]).resolve())
+        try:
+            result = extractor.extract(image_path, max_pages=3)
+            preds.append({"tests": result.tests})
+            print(f"[{i}] {row['image']}: {len(result.tests)} markers")
+        except Exception as error:  # a failed report is a miss, keep going
+            print(f"[{i}] {row['image']}: FAILED — {error}")
+            preds.append({"tests": []})
+
+    m = score(gold, preds)
+    print(f"\n=== {model_id} ===\n{format_metrics(m)}\n")
+    return {
+        "model": model_id,
+        "n": len(gold),
+        "precision": m.precision,
+        "recall": m.recall,
+        "f1": m.f1,
+        "value_acc": m.value_acc,
+        "unit_acc": m.unit_acc,
+        "status_acc": m.status_acc,
+        "tp": m.tp,
+        "fp": m.fp,
+        "fn": m.fn,
+        "matched": m.matched,
+    }
+
+
+@app.local_entrypoint()
+def compare(
+    finetuned_id: str,
+    base_id: str = "openbmb/MiniCPM-V-4.6",
+    labels_rel: str = "eval/data/real/labels.jsonl",
+) -> None:
+    """Eval base vs fine-tuned and write the before/after numbers for the chart."""
+    import json
+    from pathlib import Path
+
+    base = eval_model.remote(base_id, labels_rel)
+    fine = eval_model.remote(finetuned_id, labels_rel)
+
+    metrics = ("f1", "recall", "precision", "value_acc", "unit_acc", "status_acc")
+    print(f"\n  Extraction before/after — {base['n']} labeled reports\n")
+    print(f"  {'metric':<12}{'base':>9}{'fine-tuned':>14}{'delta':>10}")
+    for key in metrics:
+        b, f = base[key], fine[key]
+        print(f"  {key:<12}{b:>9.3f}{f:>14.3f}{('+' if f >= b else '') + f'{f - b:.3f}':>10}")
+
+    out = Path("eval/before_after.json")
+    out.write_text(json.dumps({"base": base, "finetuned": fine}, indent=2), encoding="utf-8")
+    print(f"\n  wrote {out}  ->  render the chart with:  python eval/make_chart.py\n")

train/modal_finetune.py

@@ -57,7 +57,7 @@ hf_cache = modal.Volume.from_name("blood-test-hf-cache", create_if_missing=True)
     timeout=6 * 60 * 60,
     volumes={"/adapters": adapters, "/root/.cache/huggingface": hf_cache},
 )
-def train(n: int = 4000, epochs: int = 2, seed: int = 13) -> str:
+def train(n: int = 2000, epochs: int = 1, lr: float = 2e-5, seed: int = 13) -> str:
     import os
     import subprocess
     import sys
@@ -87,7 +87,11 @@ def train(n: int = 4000, epochs: int = 2, seed: int = 13) -> str:
         "--num_train_epochs", str(epochs),
         "--lora_rank", "16",
         "--lora_alpha", "32",
-        "--learning_rate", "1e-4",
+        # Gentle LoRA: a low LR + warmup nudges output format without overwriting the base model's
+        # vision-extraction ability (the previous 1e-4 / 2-epoch run memorized the synthetic data
+        # and regressed on real reports). Tune via --lr.
+        "--learning_rate", str(lr),
+        "--warmup_ratio", "0.1",
         "--per_device_train_batch_size", "2",
         "--gradient_accumulation_steps", "8",
         "--max_length", "2048",
@@ -105,8 +109,8 @@ def train(n: int = 4000, epochs: int = 2, seed: int = 13) -> str:
 
 
 @app.local_entrypoint()
-def main(n: int = 4000, epochs: int = 2) -> None:
-    path = train.remote(n=n, epochs=epochs)
+def main(n: int = 2000, epochs: int = 1, lr: float = 2e-5) -> None:
+    path = train.remote(n=n, epochs=epochs, lr=lr)
     print(f"\nLoRA adapters saved to Modal volume 'blood-test-adapters' at {path}")
     print("Next: merge the adapter into the base model and push it to the Hub:")
     print("  modal run train/modal_finetune.py::merge --repo-id <owner>/<model-name>")
@@ -137,16 +141,18 @@ def merge_and_push(repo_id: str, adapter_dir: str = "/adapters/minicpmv-lab-lora
     if not checkpoints:
         raise RuntimeError(f"No LoRA checkpoints found under {adapter_dir}")
     latest = checkpoints[-1]
-    print(f"Merging LoRA checkpoint: {latest}")
-
-    env = {**os.environ, "USE_HF": "1"}
-    # ms-swift merges the adapter into the base model; the merged weights land in <ckpt>-merged.
-    subprocess.run(["swift", "export", "--adapters", latest, "--merge_lora", "true"], check=True, env=env)
-
-    merged = sorted(glob.glob(f"{adapter_dir}/v*/checkpoint-*-merged"), key=os.path.getmtime)
-    if not merged:
-        raise RuntimeError("swift export did not produce a *-merged directory")
-    merged_dir = merged[-1]
+    merged_dir = f"{latest}-merged"
+
+    if os.path.isdir(merged_dir):
+        # Re-run after a push failure: reuse the already-merged weights (swift export refuses to
+        # overwrite an existing dir), so we go straight to the upload.
+        print(f"Reusing already-merged model: {merged_dir}")
+    else:
+        print(f"Merging LoRA checkpoint: {latest}")
+        env = {**os.environ, "USE_HF": "1"}
+        subprocess.run(["swift", "export", "--adapters", latest, "--merge_lora", "true"], check=True, env=env)
+        if not os.path.isdir(merged_dir):
+            raise RuntimeError(f"swift export did not produce {merged_dir}")
     print(f"Merged model directory: {merged_dir}")
 
     from huggingface_hub import HfApi

train/synth_reports.py

@@ -87,11 +87,57 @@ _LAYOUTS = [
     {"cols": ["test", "result", "unit", "ref"]},
     {"cols": ["test", "result", "ref", "flag"]},       # unit folded into result
     {"cols": ["test", "flag", "result", "unit", "ref"]},
+    {"cols": ["test", "result", "ref"]},               # minimal, no flag
+    {"cols": ["test", "result", "unit", "flag", "ref"]},
 ]
 _COL_LABEL = {"test": "Test", "result": "Result", "unit": "Units",
               "ref": "Reference Range", "flag": "Flag"}
 _FLAG_TEXT = {"low": "L", "high": "H", "normal": ""}
 
+# Palette themes: (header-band fill, accent text color) — diversity across "labs".
+_THEMES = [
+    ((243, 246, 250), (20, 28, 40)),
+    ((237, 244, 238), (24, 54, 36)),
+    ((245, 240, 248), (52, 28, 60)),
+    ((250, 245, 238), (70, 44, 16)),
+    ((255, 255, 255), (15, 15, 15)),   # plain / scanned look
+]
+_PANEL_TITLES = [
+    "Comprehensive Metabolic & Hematology Panel", "Laboratory Report",
+    "Blood Test Results", "Clinical Chemistry & CBC", "Pathology Report",
+]
+# Section headers (by category) are decorations the model must NOT extract as markers — this is
+# exactly the real-report failure where "BLOOD INDICES" got read as a marker.
+_SECTION_LABEL = {
+    "CBC": "Complete Blood Count (CBC)", "Metabolic": "Metabolic Panel",
+    "Liver": "Liver Function Tests", "Lipid": "Lipid Profile",
+    "Thyroid": "Thyroid Function", "Vitamin": "Vitamins & Iron Studies",
+}
+
+
+def _fmt_ref(marker: Marker, rng: random.Random) -> str:
+    """Reference ranges as real labs print them (varied separators / bounds / brackets)."""
+    lo, hi = marker.ref_low, marker.ref_high
+    if lo is not None and hi is not None:
+        sep = rng.choice([" - ", "-", " – ", " to "])
+        s = f"{_fmt_num(lo)}{sep}{_fmt_num(hi)}"
+        return f"[{s}]" if rng.random() < 0.12 else s
+    if hi is not None:
+        return rng.choice([f"< {_fmt_num(hi)}", f"<{_fmt_num(hi)}", f"Up to {_fmt_num(hi)}", f"0 - {_fmt_num(hi)}"])
+    if lo is not None:
+        return rng.choice([f"> {_fmt_num(lo)}", f">{_fmt_num(lo)}", f">= {_fmt_num(lo)}"])
+    return ""
+
+
+def _demo_line(rng: random.Random) -> str:
+    age, sex = rng.randint(19, 84), rng.choice(["Male", "Female", "M", "F"])
+    return rng.choice([
+        f"Patient: [SAMPLE]    Age/Sex: {age}/{sex}    Collected: 2026-03-14",
+        f"Name: [SAMPLE]   Age: {age} Years   Sex: {sex}",
+        f"[SAMPLE] · {age}{'M' if sex in ('Male', 'M') else 'F'} · Specimen: Serum",
+        "Patient: [SAMPLE]    DOB: [SAMPLE]    Collected: 2026-03-14",
+    ])
+
 
 def _make_report(rng: random.Random) -> tuple[list[dict], dict]:
     """Pick markers + values; return (gold tests, layout/style config)."""
@@ -102,22 +148,26 @@ def _make_report(rng: random.Random) -> tuple[list[dict], dict]:
         v = sample_value(rng, m)
         status = m.status_for(v)
         # Alias variety: sometimes use an alias as the printed name.
-        printed = rng.choice((m.name,) + m.aliases) if (m.aliases and rng.random() < 0.4) else m.name
+        printed = rng.choice((m.name,) + m.aliases) if (m.aliases and rng.random() < 0.45) else m.name
         tests.append({
             "marker": printed,
             "canonical": m.name,
+            "category": m.category,
             "value": _round_for(m, v),
             "unit": m.unit,
-            "reference_range": m.ref_range_text(),
+            "reference_range": _fmt_ref(m, rng),
             "status": status,
         })
     style = {
         "layout": rng.choice(_LAYOUTS),
         "lab": rng.choice(LAB_NAMES),
-        "stripe": rng.random() < 0.6,
+        "stripe": rng.random() < 0.55,
         "grid": rng.random() < 0.5,
-        "fold_unit": False,
-        "base": rng.randint(15, 17),
+        "sectioned": rng.random() < 0.55,
+        "theme": rng.choice(_THEMES),
+        "title": rng.choice(_PANEL_TITLES),
+        "demo": _demo_line(rng),
+        "base": rng.randint(14, 18),
     }
     return tests, style
 
@@ -142,6 +192,21 @@ def _fmt_num(v) -> str:
     return str(int(f)) if f.is_integer() else f"{f:g}"
 
 
+def _ordered_rows(tests: list[dict], sectioned: bool) -> list[tuple[str, object]]:
+    """Display rows. When sectioned, group markers by category under a section header (a
+    decoration that is NOT in the gold), teaching the model to skip such headers."""
+    if not sectioned:
+        return [("data", t) for t in tests]
+    by_cat: dict[str, list[dict]] = {}
+    for t in tests:
+        by_cat.setdefault(t["category"], []).append(t)
+    rows: list[tuple[str, object]] = []
+    for cat, items in by_cat.items():
+        rows.append(("section", _SECTION_LABEL.get(cat, cat)))
+        rows.extend(("data", t) for t in items)
+    return rows
+
+
 def render(tests: list[dict], style: dict) -> tuple[Image.Image, list[dict]]:
     """Render the report to an image; return (image, gold tests with source_text)."""
     cols = list(style["layout"]["cols"])
@@ -149,30 +214,31 @@ def render(tests: list[dict], style: dict) -> tuple[Image.Image, list[dict]]:
     W = 1000
     pad = 48
     base = style["base"]
+    band, accent = style["theme"]
     f_h1, f_h2, f_th, f_td = _font(30, True), _font(15), _font(14, True), _font(base)
+    f_sec = _font(base + 1, True)
 
     # Column widths (proportional, tuned per column type).
     weight = {"test": 0.34, "result": 0.18, "unit": 0.14, "ref": 0.26, "flag": 0.08}
     avail = W - 2 * pad
     widths = {c: int(avail * weight[c]) for c in cols}
-    # Normalize to fill width.
     scale = avail / sum(widths.values())
     widths = {c: int(w * scale) for c, w in widths.items()}
 
+    display = _ordered_rows(tests, style.get("sectioned", False))
     row_h = base + 16
     header_h = 150
     table_top = header_h + 30
-    H = table_top + row_h * (len(tests) + 1) + pad
+    H = table_top + row_h * (len(display) + 1) + pad
 
     img = Image.new("RGB", (W, H), "white")
     d = ImageDraw.Draw(img)
 
     # Header band.
-    d.rectangle([0, 0, W, header_h], fill=(243, 246, 250))
-    d.text((pad, 40), style["lab"], font=f_h1, fill=(20, 28, 40))
-    d.text((pad, 88), "Patient: [SAMPLE]    DOB: [SAMPLE]    Collected: 2026-03-14",
-           font=f_h2, fill=(90, 100, 115))
-    d.text((pad, 112), "Comprehensive Metabolic & Hematology Panel", font=f_h2, fill=(90, 100, 115))
+    d.rectangle([0, 0, W, header_h], fill=band)
+    d.text((pad, 40), style["lab"], font=f_h1, fill=accent)
+    d.text((pad, 88), style["demo"], font=f_h2, fill=(90, 100, 115))
+    d.text((pad, 112), style["title"], font=f_h2, fill=(90, 100, 115))
 
     # Column header row.
     x = pad
@@ -182,11 +248,16 @@ def render(tests: list[dict], style: dict) -> tuple[Image.Image, list[dict]]:
         x += widths[c]
     d.line([pad, y + row_h - 4, W - pad, y + row_h - 4], fill=(190, 200, 212), width=2)
 
-    # Rows.
+    # Rows (data + section decorations).
     gold = []
-    for i, t in enumerate(tests):
-        y = table_top + row_h * (i + 1)
-        if style["stripe"] and i % 2 == 1:
+    for di, (kind, payload) in enumerate(display, start=1):
+        y = table_top + row_h * di
+        if kind == "section":
+            d.rectangle([pad, y, W - pad, y + row_h], fill=(232, 237, 243))
+            d.text((pad + 6, y + 3), str(payload), font=f_sec, fill=accent)
+            continue
+        t = payload
+        if style["stripe"] and di % 2 == 1:
             d.rectangle([pad, y, W - pad, y + row_h], fill=(248, 250, 252))
         x = pad
         row_pieces = []