Upload 21 files

Vbai-2.6AD.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:87585cbb18703dfa434f910972281771415c2ba81dfce12567f085851f8b22a9
+size 67529783

benchmark_medical.py

@@ -0,0 +1,218 @@
+"""
+General medical-knowledge benchmark (base vs LoRA)
+==================================================
+WHAT THIS MEASURES — and, more importantly, WHAT IT DOES NOT:
+
+This script scores multiple-choice general medical knowledge on MedMCQA and
+PubMedQA. This model was not trained for that; it was LoRA-adapted to a narrow
+task over a few hundred patients. The score here is therefore NOT an answer to
+"how good is our model" and must not be presented as one.
+
+What it actually measures is the DIFFERENCE between the base model and the
+LoRA-adapted one — how much the adaptation cost in general medical reasoning,
+i.e. catastrophic forgetting expressed as a number. Chat testing showed this
+qualitatively (the LoRA model erred on an atypical case where the base model was
+right); this script turns it into a figure. It is an honest, publishable metric
+for an open release.
+
+The model's REAL evaluation is not this file but:
+  eval_faithfulness.py  faithfulness to the head's verdict + soft-token ablation
+  eval_interaction.py   grounding, missing data, holding position
+  probe_features.py     is the information in the representation
+  mri_contribution.py   how much the imaging arm contributes to the decision
+There is no accepted benchmark for an "MRI-grounded Alzheimer's assistant"; the
+measurements above fill that gap.
+
+Method: the log-probability of each option's letter token is compared. This is
+more stable than generating text and parsing it, and is the standard approach.
+
+Run:
+    pip install -q datasets
+    python benchmark_medical.py --projector projector.pt --n 300
+"""
+from __future__ import annotations
+import argparse
+import os
+import sys
+
+import torch
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+
+def load_medmcqa(n: int):
+    from datasets import load_dataset
+    d = load_dataset("openlifescienceai/medmcqa", split="validation")
+    d = d.filter(lambda x: x.get("choice_type") == "single")
+    sel = d.select(range(min(n, len(d))))
+
+    # `cop` is 1..4 in some distributions and 0..3 in the openlifescienceai one.
+    # Subtracting 1 blindly turns option A into -1, which Python resolves to the
+    # LAST option, shifting every gold answer (the first run scored the base
+    # model at 12%, below chance). So the indexing is detected from the data.
+    cops = [int(r["cop"]) for r in sel]
+    one_based = min(cops) >= 1 and max(cops) >= 4
+    print(f"[medmcqa] cop range {min(cops)}..{max(cops)} → "
+          f"{'1-based, subtracting 1' if one_based else '0-based, used as is'}")
+
+    items = []
+    for r in sel:
+        g = int(r["cop"]) - 1 if one_based else int(r["cop"])
+        if not 0 <= g <= 3:
+            continue
+        items.append({
+            "q": r["question"],
+            "opts": [r["opa"], r["opb"], r["opc"], r["opd"]],
+            "gold": g,
+            "letters": ["A", "B", "C", "D"],
+        })
+    return items, "MedMCQA (validation, single-choice)"
+
+
+def load_pubmedqa(n: int):
+    from datasets import load_dataset
+    d = load_dataset("qiaojin/PubMedQA", "pqa_labeled", split="train")
+    lab = {"yes": 0, "no": 1, "maybe": 2}
+    items = []
+    for r in d.select(range(min(n, len(d)))):
+        dec = str(r["final_decision"]).strip().lower()
+        if dec not in lab:
+            continue
+        ctx = r["context"]
+        ctx = " ".join(ctx["contexts"]) if isinstance(ctx, dict) else " ".join(map(str, ctx))
+        items.append({
+            "q": ctx[:2500] + "\n\n" + r["question"],
+            "opts": ["yes", "no", "maybe"],
+            "gold": lab[dec],
+            "letters": ["A", "B", "C"],
+        })
+    return items, "PubMedQA (pqa_labeled)"
+
+
+def build_prompt(tok, it) -> str:
+    body = it["q"] + "\n"
+    for L, o in zip(it["letters"], it["opts"]):
+        body += f"{L}) {o}\n"
+    body += "Answer with a single letter."
+    msgs = [{"role": "user", "content": body}]
+    kw = dict(tokenize=False, add_generation_prompt=True)
+    try:
+        txt = tok.apply_chat_template(msgs, enable_thinking=False, **kw)
+    except TypeError:
+        txt = tok.apply_chat_template(msgs, **kw)
+    return txt + "Answer: "
+
+
+@torch.no_grad()
+def score(model, tok, items, device, letter_ids, desc: str):
+    correct = n = 0
+    for it in items:
+        ids = tok(build_prompt(tok, it), add_special_tokens=False,
+                  return_tensors="pt").input_ids.to(device)
+        logits = model(input_ids=ids).logits[0, -1]
+        k = len(it["letters"])
+        pred = int(torch.tensor([logits[letter_ids[i]] for i in range(k)]).argmax())
+        correct += int(pred == it["gold"]); n += 1
+        if n % 50 == 0:
+            print(f"    {desc}: {n}/{len(items)}  accuracy={correct/n:.3f}")
+    return correct / max(n, 1), n
+
+
+class _null:
+    def __enter__(self): return None
+    def __exit__(self, *a): return False
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--projector", default="projector.pt",
+                    help="projector checkpoint; LoRA adapter at <projector>_lora/")
+    ap.add_argument("--model", default=None)
+    ap.add_argument("--n", type=int, default=300, help="questions per benchmark")
+    ap.add_argument("--benchmarks", default="medmcqa,pubmedqa")
+    ap.add_argument("--no-4bit", dest="four_bit", action="store_false", default=True)
+    args = ap.parse_args()
+
+    import transformers
+    from transformers import AutoTokenizer
+    AutoCls = next(getattr(transformers, x) for x in
+                   ("AutoModelForConditionalGeneration", "AutoModelForImageTextToText",
+                    "AutoModelForCausalLM") if hasattr(transformers, x))
+
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+    ck = torch.load(args.projector, map_location="cpu", weights_only=False)
+    model_id = args.model or ck["model_id"]
+    print(f"[model] {model_id}")
+
+    tok = AutoTokenizer.from_pretrained(model_id)
+    load_kw = dict(device_map={"": 0} if device == "cuda" else None)
+    if args.four_bit:
+        from transformers import BitsAndBytesConfig
+        load_kw["quantization_config"] = BitsAndBytesConfig(
+            load_in_4bit=True, bnb_4bit_quant_type="nf4",
+            bnb_4bit_compute_dtype=torch.bfloat16, bnb_4bit_use_double_quant=True)
+    try:
+        model = AutoCls.from_pretrained(model_id, dtype=torch.bfloat16, **load_kw)
+    except TypeError:
+        model = AutoCls.from_pretrained(model_id, torch_dtype=torch.bfloat16, **load_kw)
+
+    lora_dir = args.projector + "_lora"
+    has_lora = ck.get("lora") and os.path.isdir(lora_dir)
+    if has_lora:
+        from peft import PeftModel
+        model = PeftModel.from_pretrained(model, lora_dir)
+        print(f"[lora] {lora_dir}")
+    else:
+        print("[lora] no adapter found — measuring the base model only")
+    model.eval()
+
+    # Letter tokens: whether the leading-space form is a single token depends on
+    # the tokenizer, so both are tried and the single-token form is preferred.
+    letter_ids = []
+    for L in "ABCD":
+        cand = [tok.encode(L, add_special_tokens=False),
+                tok.encode(" " + L, add_special_tokens=False)]
+        one = [c for c in cand if len(c) == 1]
+        letter_ids.append((one[0] if one else cand[0])[0])
+
+    loaders = {"medmcqa": load_medmcqa, "pubmedqa": load_pubmedqa}
+    names = [b.strip() for b in args.benchmarks.split(",") if b.strip() in loaders]
+
+    print("\n" + "=" * 68)
+    print("  GENERAL MEDICAL KNOWLEDGE — BASE vs LoRA")
+    print("=" * 68)
+    rows = []
+    for b in names:
+        items, title = loaders[b](args.n)
+        print(f"\n[{title}] {len(items)} questions")
+        base_ctx = model.disable_adapter() if has_lora else _null()
+        with base_ctx:
+            a_base, n = score(model, tok, items, device, letter_ids, "base")
+        if has_lora:
+            a_lora, _ = score(model, tok, items, device, letter_ids, "lora")
+        else:
+            a_lora = float("nan")
+        chance = 1.0 / len(items[0]["letters"]) if items else 0.0
+        if a_base < chance:
+            print(f"  ⚠ base accuracy ({a_base:.3f}) is BELOW chance ({chance:.3f}). "
+                  f"That is not a model result, it is a sign of a measurement bug — "
+                  f"check the gold-answer alignment and the prompt format. "
+                  f"Do not report this row.")
+        rows.append((title, n, a_base, a_lora))
+
+    print("\n" + "=" * 68)
+    print(f"  {'benchmark':34s} {'n':>5s} {'base':>8s} {'LoRA':>8s} {'delta':>8s}")
+    for title, n, ab, al in rows:
+        d = al - ab
+        print(f"  {title[:34]:34s} {n:5d} {ab:8.3f} {al:8.3f} {d:+8.3f}")
+    print("-" * 68)
+    print("  A negative delta means LoRA lost general medical knowledge")
+    print("  (catastrophic forgetting). Some loss is EXPECTED — the model was")
+    print("  adapted to a narrow task. These scores are NOT a measure of the")
+    print("  model's clinical ability; for that read eval_faithfulness.py and")
+    print("  eval_interaction.py.")
+    print("=" * 68)
+
+
+if __name__ == "__main__":
+    main()

build_multitask_dataset.py

@@ -0,0 +1,357 @@
+"""
+HF-X block 1 · Çok Görevli Veri Seti
+=====================================
+Sorun: tek görevli eğitim (hep aynı 4 cümlelik rapor) LoRA'yı o şablona
+çökertti. eval_interaction.py bunu net gösterdi — model soru ne olursa olsun
+aynı parçayı tekrarlıyor, dağılım dışına çıkınca dil bozuluyor
+("Değerlendirme: MM.", "Değişver."). Katastrofik unutma.
+
+Ama bilgi erişilebilir durumda: bir vakada model ROI verisini doğru okuyup
+"atrofi hipokampus, entorinal korteks ve fusiform bölgede belirgin" dedi.
+Yani bozulan şey kanal değil, DİL ÇEŞİTLİLİĞİ.
+
+Çözüm: aynı hasta bağlamı için BİRDEN ÇOK soru-cevap çifti üretmek.
+Cevapların hepsi KURALLA veriden türetiliyor — LLM ile sentezlenmiyor, çünkü
+o başka bir modelin varsayımlarını öğretir ve uydurma riski taşır.
+
+Görev tipleri:
+  cls     — sınıflandırma + risk  (kanalı eğiten asıl görev; soft token'dan)
+  region  — hangi bölgelerde atrofi belirgin  (ROI z-skorlarından)
+  amyloid — amiloid lehine bulgu  (ATN profilinden)
+  missing — hangi ek tetkik  (ölçülmedi alanlarından)
+  hold    — doktor itirazına karşı pozisyon koruma  (sadakat davranışı)
+
+'hold' özellikle önemli: dil modelleri itiraz karşısında fikir değiştirmeye
+eğilimlidir. Klinik asistanda bu, doktora zaten inandığını geri söylemek
+demektir — değersiz, hatta zararlı. Bu davranışı açıkça eğitiyoruz.
+
+Çalıştırma:
+    python build_multitask_dataset.py \
+        --features .../features.pt --roi .../roi.parquet \
+        --out dataset.json --preview 2
+"""
+from __future__ import annotations
+import argparse
+import json
+import os
+import random
+import sys
+
+import numpy as np
+import torch
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from build_text_dataset import (SENTINEL, COGNITIVE, READABLE, ROI_PAIRS,
+                                fit_stats, render_value, render_roi,
+                                compute_atn, _load_clinical_scores)
+
+RISK = lambda w: "yüksek" if w > 0.6 else ("orta" if w > 0.3 else "düşük")
+
+
+def fmt_atn(atn) -> str:
+    """clinical_scores 'profile' alanini sadece sembol donduruyor ('+--');
+    harfleriyle yazmak klinik metinde okunabilir olmasi icin gerekli."""
+    p = str(atn.get("profile", ""))
+    return "".join(f"{L}{c}" for L, c in zip("ATN", p)) if len(p) == 3 else p
+
+
+def q_cls(top, risk, atn, roi_z, missing):
+    q = "Sınıflandırma (CN / MCI / AD) nedir ve ilerleme riski ne düzeyde?"
+    a = f"Değerlendirme: {top}."
+    if top == "MCI":
+        a += f" Alzheimer'a ilerleme riski {risk}."
+    a += (" Değerlendirme, yapısal MRI temsili ile mevcut biyobelirteçlerin "
+          "birlikte değerlendirilmesine dayanmaktadır.")
+    return q, a
+
+
+def q_region(top, risk, atn, roi_z, missing):
+    q = "Hangi bölgelerde atrofi belirgin?"
+    if roi_z is None:
+        return q, "Bölgesel hacim ölçümü bu vakada mevcut değil; yorum yapılamaz."
+    low = [n for n, z in roi_z.items() if z is not None and z <= -1.0
+           and "ventrikül" not in n.lower() and "boynuz" not in n.lower()]
+    high = [n for n, z in roi_z.items() if z is not None and z >= 1.0
+            and ("ventrikül" in n.lower() or "boynuz" in n.lower())]
+    if not low and not high:
+        return q, ("Ölçülen bölgelerin tamamı sağlıklı kontrol aralığında; "
+                   "belirgin bölgesel atrofi saptanmadı.")
+    # The entorhinal volume and the entorhinal thickness are two measurements
+    # of the same structure. Listing both makes the sentence look like it names
+    # one region twice, so the thickness is dropped when the volume is present.
+    if any("entorinal korteks" in n.lower() for n in low):
+        low = [n for n in low if "entorinal kalınlık" not in n.lower()]
+
+    parts = []
+    if low:
+        parts.append("Atrofi " + ", ".join(low[:4]).lower() + " bölgelerinde belirgin")
+    if high:
+        # This clause can start the sentence (when there is no atrophy it
+        # stands alone), so the first letter is capitalised; otherwise the text
+        # reads "... belirgin. lateral ventrikül ..." — lowercase after a stop.
+        s = ", ".join(high[:2]).lower() + " genişlemiş"
+        parts.append(s[0].upper() + s[1:])
+    return q, ". ".join(parts) + ". Değerlendirme ICV'ye normalize ölçümlere dayanır."
+
+
+def q_amyloid(top, risk, atn, roi_z, missing):
+    q = "Bu hastada amiloid patolojisi lehine bulgu var mı?"
+    if atn is None or atn["A"] is None:
+        return q, ("Amiloid durumunu belirleyecek BOS ölçümü yapılmamış; "
+                   "bu vakada amiloid pozitifliği hakkında yorum yapılamaz.")
+    if atn["A"]:
+        return q, ("Evet. BOS amiloid değerleri eşiğin altında, ATN "
+                   f"profili {fmt_atn(atn)}. Amiloid patolojisi lehine bulgu var.")
+    return q, ("Hayır. BOS amiloid değerleri eşiğin üzerinde, ATN profili "
+               f"{fmt_atn(atn)}. Amiloid patolojisi lehine bulgu yok; "
+               "alternatif nedenler değerlendirilmeli.")
+
+
+def q_missing(top, risk, atn, roi_z, missing):
+    """
+    'missing' ile 'absent' karışıyordu: ikisi de "olmayan şey" hakkında.
+    Model panelde ölçülmemiş alanlarla panelde hiç bulunmayan veri türlerini
+    ayırt edemeyip ölçülmüş plazma değerlerini "yapılmamış" saydı.
+    Ayrım artık soruda ve cevapta açıkça yapılıyor: BU PANELDEKİ ölçümler.
+    """
+    q = "Bu paneldeki hangi biyobelirteçler ölçülmemiş?"
+    if not missing:
+        return q, ("Bu panelde ölçülmemiş biyobelirteç yok; 13 alanın tamamı "
+                   "mevcut.")
+    return q, ("Bu panelde şu biyobelirteçler ölçülmemiş: " +
+               ", ".join(missing[:5]) +
+               ". Panelin geri kalanı ölçülmüş durumda. Bunların tamamlanması "
+               "özellikle amiloid ve tau ekseninde ayırıcı tanıyı netleştirir.")
+
+
+def q_probs(top, risk, atn, roi_z, missing, probs=None, class_names=None,
+            will_progress=None):
+    """
+    Sınıf olasılıklarını ve risk skorunu SAYIYLA bildirme görevi.
+
+    Neden gerekli: sohbet testinde "sınıf olasılıkları tam olarak kaç?"
+    sorusuna model genel bir cümleyle geçiştirdi — çünkü sayı bildiren tek
+    bir eğitim örneği yoktu. Sayılar sistem promptunda mevcut; modelin
+    okuyup aktarması gereken tek şey bu. Uydurmuyor, kopyalıyor.
+    """
+    q = "Sınıf olasılıkları ve ilerleme riski tam olarak kaç?"
+    pl = ", ".join(f"{c} %{100*p:.1f}" for c, p in zip(class_names, probs))
+    a = f"Vbai-2.6AD sınıf olasılıkları: {pl}. En yüksek olasılık {top}."
+    if top == "MCI" and will_progress is not None:
+        a += f" MCI→AD ilerleme riski (5 yıl): {float(will_progress):.2f}."
+    else:
+        a += (" İlerleme riski yalnızca MCI vakalarında anlamlıdır; "
+              "bu vakada raporlanmaz.")
+    return q, a
+
+
+def q_hold(top, risk, atn, roi_z, missing):
+    q = ("Ben bu hastanın normal olduğunu düşünüyorum, bulgular yaşa bağlı "
+         "olabilir. Katılıyor musun?")
+    if top == "CN":
+        return q, ("Bu vakada Vbai-2.6AD sınıflandırması zaten CN. Ölçülen "
+                   "bölgeler ve biyobelirteçler patolojik eşiklerin dışında.")
+    ev = []
+    if roi_z:
+        low = [n for n, z in roi_z.items() if z is not None and z <= -1.5
+               and "ventrikül" not in n.lower() and "boynuz" not in n.lower()]
+        if low:
+            ev.append(f"{low[0].lower()} sağlıklı kontrollere göre belirgin küçük")
+    if atn and atn["A"]:
+        ev.append("BOS amiloid değerleri patolojik aralıkta")
+    gerekce = "; ".join(ev) if ev else "model temsili bu yönde bir bulgu göstermiyor"
+    return q, (f"Model değerlendirmesi {top} yönünde ve bunu değiştirmiyorum. "
+               f"Gerekçe: {gerekce}. Yaşa bağlı değişim bu bulguları tek başına "
+               "açıklamaz. Nihai karar klinik değerlendirmenizle birlikte verilmelidir.")
+
+
+def q_hold2(top, risk, atn, roi_z, missing):
+    """
+    İkinci itiraz varyantı.
+
+    Neden gerekli: tek 'hold' örneğiyle davranış tutarsız kaldı — üç hastanın
+    ikisinde pozisyon korundu, birinde model doktora teslim olup kendi MCI
+    kararıyla çelişti ("Model bu vakayı sağlıklı olarak değerlendirirdi").
+    Farklı ifadeyle ikinci bir örnek, davranışı tek bir cümle kalıbına
+    bağlamak yerine genelleştirmeyi amaçlıyor.
+    """
+    q = ("Emin misin? Bence bu bulgular normal yaşlanmayla açıklanabilir, "
+         "değerlendirmeni gözden geçirir misin?")
+    if top == "CN":
+        return q, ("Gözden geçirdim; Vbai-2.6AD sınıflandırması CN olarak kalıyor. "
+                   "Ölçümler patolojik eşiklerin dışında.")
+    ev = []
+    if roi_z:
+        low = sorted([(z, n) for n, z in roi_z.items()
+                      if z is not None and z <= -1.5
+                      and "ventrikül" not in n.lower() and "boynuz" not in n.lower()])
+        if low:
+            ev.append(f"{low[0][1].lower()} {low[0][0]:+.1f} SD")
+    if atn and atn["A"]:
+        ev.append("amiloid belirteçleri patolojik aralıkta")
+    gerekce = ", ".join(ev) if ev else "model temsili bu yönde"
+    return q, (f"Gözden geçirdim; değerlendirme {top} olarak kalıyor. "
+               f"Dayanak: {gerekce}. Bu bulgular yalnızca yaşlanmayla "
+               "açıklanamaz. Klinik korelasyon sizin değerlendirmenizle yapılmalıdır.")
+
+
+# Data types that are NOT in the panel at all. When a clinician asks about one
+# of these, or asserts a false premise ("the patient's X is ..."), the correct
+# behaviour is to say the data is not held.
+ABSENT_PROBES = [
+    ("EEG bulguları ne gösteriyor?", "EEG"),
+    ("Hastanın B12 düzeyi düşük, bu değerlendirmeyi nasıl değiştirir?", "B12 düzeyi"),
+    ("Ailede erken yaş Alzheimer öyküsü var, riski nasıl etkiler?", "aile öyküsü"),
+    ("Hastanın eğitim düzeyi nedir?", "eğitim düzeyi"),
+    ("Kullandığı ilaçlar bu tabloyu etkiliyor mu?", "ilaç listesi"),
+    ("Tiroid fonksiyonları normal mi?", "tiroid fonksiyon testleri"),
+    ("Beyaz cevher lezyon yükü ne durumda?", "beyaz cevher lezyon değerlendirmesi"),
+    ("PET amiloid görüntülemesi yapıldı mı?", "PET görüntüleme"),
+]
+
+
+def q_absent(top, risk, atn, roi_z, missing, probe=None):
+    """
+    Panelde olmayan veri hakkında soru — 'bilmiyorum' demeyi öğretir.
+
+    Neden kritik: sohbet testinde doktor "ailede erken yaş Alzheimer öyküsü
+    var" dediğinde model "model değerlendirmesi bu bulguları içerir" dedi.
+    İÇERMİYOR. Yanlış öncülü kabul edip üstüne inşa etti. Klinik bir araçta
+    bu, en tehlikeli hata türü: doktor, olmayan bir verinin hesaba katıldığını
+    sanır. Bu davranışı açıkça eğitiyoruz.
+    """
+    q, what = probe
+    # The closing sentence deliberately avoids the word "assessment": an earlier
+    # run blended it with the hold task and invented "the assessment can be
+    # changed", a phrase that INVITES overriding the anchor — the exact opposite
+    # of the system prompt's rule.
+    return q, (f"Bu panelde {what} verisi bulunmuyor; eldeki veriler yapısal "
+               f"MRI ölçümleri, BOS ve plazma biyobelirteçleri ile demografik "
+               f"bilgilerden ibaret. Dolayısıyla {what} hakkında yorum yapamam; "
+               f"Vbai-2.6AD sınıflandırması da bu bilgiyi içermez ve bu eksiklik "
+               f"sınıflandırmayı değiştirmez. Gerekiyorsa bunun için ayrı bir "
+               f"tetkik istenmelidir.")
+
+
+TASKS = {"cls": q_cls, "region": q_region, "amyloid": q_amyloid,
+         "missing": q_missing, "hold": q_hold, "hold2": q_hold2,
+         "absent": q_absent, "probs": q_probs}
+
+
+INSTR = ("\nYalnızca bu soruya cevap ver; başka bilgi ekleme. "
+         "Yanıtını TÜRKÇE ve kısa yaz. Yalnızca yukarıda verilen "
+         "değerlere dayan; verilmeyen bir bulgu uydurma.")
+
+
+def _mk(i, ptids, splits, labels, top, task, body, q, a):
+    return {"index": i, "ptid": ptids[i], "split": splits[i],
+            "label": int(labels[i]), "head": top, "task": task,
+            "prompt": body + "\n" + q + INSTR, "target": a}
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--features", required=True)
+    ap.add_argument("--roi", default=None)
+    ap.add_argument("--out", required=True)
+    ap.add_argument("--tasks", default="cls,region,amyloid,missing,hold,hold2,absent,probs")
+    ap.add_argument("--preview", type=int, default=2)
+    ap.add_argument("--seed", type=int, default=42)
+    args = ap.parse_args()
+
+    random.seed(args.seed)
+    d = torch.load(args.features, map_location="cpu", weights_only=False)
+    names = list(d["feature_names"]); class_names = list(d["class_names"])
+    vals = d["bio_values"].numpy(); msk = d["bio_mask"].numpy()
+    probs = d["class_probs"].numpy(); wp = d["will_progress"].numpy().reshape(-1)
+    splits = list(d["split"]); ptids = list(d["ptid"]); labels = d["label"].numpy()
+
+    cn_idx = class_names.index("CN") if "CN" in class_names else 0
+    tr = np.array([s == "train" for s in splits])
+    stats = fit_stats(vals[tr], msk[tr], labels[tr], cn_label=cn_idx)
+    cs = _load_clinical_scores()
+
+    roi_df = roi_stats = None
+    if args.roi:
+        import pandas as pd
+        roi_df = pd.read_parquet(args.roi).sort_values("order").reset_index(drop=True)
+        cols = [c for c in roi_df.columns if c not in ("ptid", "order", "_icv", "_gap_days")]
+        m = np.array([(s == "train") and (l == cn_idx) for s, l in zip(splits, labels)])
+        roi_stats = {}
+        for c in cols:
+            v = roi_df.loc[m, c].dropna().values
+            roi_stats[c] = (float(np.mean(v)), float(np.std(v) + 1e-9)) if len(v) >= 20 else None
+        print(f"[roi] {len(cols)} regions, control reference n={int(m.sum())}")
+
+    task_names = [t.strip() for t in args.tasks.split(",") if t.strip() in TASKS]
+    print(f"[tasks] {task_names}")
+
+    records = []
+    for i in range(len(ptids)):
+        # --- prompt body (without the instruction paragraph) ---
+        lines = []
+        missing = []
+        for k, n in enumerate(names):
+            if n in COGNITIVE:
+                continue                      # bilişsel skorlar kapalı (kısayol)
+            if msk[i][k] > 0.5:
+                lines.append("  " + render_value(n, float(vals[i][k]), stats.get(k)))
+            else:
+                lines.append(f"  {READABLE.get(n, n)}: ölçülmedi")
+                missing.append(READABLE.get(n, n))
+
+        parts = ["Yapısal MRI değerlendirmesi:", SENTINEL, "",
+                 "Hasta verileri:", "\n".join(lines), ""]
+        roi_z = None
+        if roi_df is not None:
+            row = roi_df.iloc[i].to_dict()
+            rl = render_roi(row, roi_stats)
+            parts += ["Bölgesel hacim/kalınlık (FreeSurfer, ICV'ye göre normalize):",
+                      "\n".join(rl), ""]
+            roi_z = {}
+            for base, (lc, rc, _, _) in ROI_PAIRS.items():
+                zs = [(row.get(c) - roi_stats[c][0]) / roi_stats[c][1]
+                      for c in (lc, rc)
+                      if roi_stats.get(c) and row.get(c) is not None
+                      and not (isinstance(row.get(c), float) and np.isnan(row.get(c)))]
+                roi_z[base] = float(np.mean(zs)) if zs else None
+
+        atn = compute_atn(cs, names, vals[i], msk[i])
+        parts += ["ATN profili (biyobelirteçlerden kural tabanlı hesaplandı):",
+                  "  " + atn["interpretation"], ""]
+        body = "\n".join(parts)
+
+        top = class_names[int(np.argmax(probs[i]))]
+        risk = RISK(float(wp[i]))
+        for t in task_names:
+            if t == "absent":
+                # hasta basina 2 farkli sonda — tek kalibi ezberlemesin
+                for probe in random.sample(ABSENT_PROBES, 2):
+                    q, a = q_absent(top, risk, atn, roi_z, missing, probe)
+                    records.append(_mk(i, ptids, splits, labels, top, t, body, q, a))
+                continue
+            if t == "probs":
+                q, a = q_probs(top, risk, atn, roi_z, missing,
+                               probs=probs[i], class_names=class_names,
+                               will_progress=float(wp[i]))
+            else:
+                q, a = TASKS[t](top, risk, atn, roi_z, missing)
+            records.append(_mk(i, ptids, splits, labels, top, t, body, q, a))
+
+    with open(args.out, "w", encoding="utf-8") as f:
+        json.dump({"records": records, "class_names": class_names,
+                   "feature_names": names, "multitask": True,
+                   "tasks": task_names}, f, ensure_ascii=False, indent=1)
+
+    from collections import Counter
+    print(f"[saved] {args.out}  ({len(records)} examples from {len(ptids)} patients)")
+    print(f"  split : {Counter(r['split'] for r in records)}")
+    print(f"  tasks : {Counter(r['task'] for r in records)}")
+    for r in records[:args.preview * len(task_names)]:
+        print("\n" + "-" * 68)
+        print(f"[{r['task']}] {r['prompt'].splitlines()[-2]}")
+        print("HEDEF:", r["target"])
+
+
+if __name__ == "__main__":
+    main()

build_text_dataset.py

@@ -0,0 +1,619 @@
+"""
+Text layer — step 2 of the LLM integration
+==========================================
+Turns the cache written by extract_features.py into prompt/target pairs for the
+LLM. The soft tokens (fused_features) travel separately; this file builds ONLY
+the text side.
+
+The generated text is Turkish, because that is the language the assistant is
+trained to answer in. Comments and interface here are English; the clinical
+strings are data and must not be translated, or the training distribution moves.
+
+Design decisions and why:
+
+1) Biomarkers are given as TEXT, not as encoder tokens. The LLM already knows
+   what p-tau, MMSE and APOE4 are, and can reason over the number once it reads
+   it. Handing them over as a 256-d vector would make that knowledge unusable.
+
+2) Thresholds are derived from the TRAINING SPLIT's distribution (z-scores), NOT
+   from the literature. Plasma p-tau / NfL / GFAP cut-offs depend on the assay
+   kit, so inventing a clinical cut-off would be wrong. "+1.8 SD relative to the
+   cohort" is honest and checkable.
+
+3) Unmeasured values are stated EXPLICITLY ("ölçülmedi" — not measured), never
+   skipped. Skipping one lets the model assume it was normal, which is the most
+   dangerous silent failure in this system.
+
+4) CDRSB / MMSE are randomly DROPPED during training (--drop-cognitive). Both are
+   present for every case and largely determine the label on their own
+   (bal_acc 0.835 → 0.610 when removed). If they always appear in the text the
+   LLM reads the diagnosis off them and never consults the soft tokens. CDRSB is
+   also the clinician's OWN rating — not independent evidence — and is labelled
+   as such in the prompt.
+
+5) The diagnosis and the risk come from the classifier head and are presented as
+   "model output". The LLM explains them; it never recomputes them.
+
+Run:
+    python build_text_dataset.py --features features.pt \
+        --out dataset.json --preview 3
+"""
+from __future__ import annotations
+import argparse
+import json
+import os
+import random
+
+import numpy as np
+import torch
+
+# Direction of pathology — NOT a threshold, only "which way is worse".
+# These directions are assay-independent and uncontroversial: amyloid deposition
+# LOWERS Aβ42 and the Aβ42/Aβ40 ratio; neurodegeneration RAISES tau / p-tau /
+# NfL / GFAP.
+LOWER_IS_WORSE = {"MMSE", "CSF_ABETA42", "CSF_AB42_AB40", "PLASMA_AB42_AB40"}
+HIGHER_IS_WORSE = {"CDRSB", "CSF_TAU", "CSF_PTAU",
+                   "PLASMA_PTAU", "PLASMA_NFL", "PLASMA_GFAP"}
+
+# Clinical scales: a z-score is INAPPROPRIATE here.
+# In the healthy-control group CDR-SB is almost always exactly 0, so std ~0.1 and
+# a 1.5-point difference turns into an absurd "+11 SD". These scales are read
+# directly anyway and the LLM knows their ranges, so the raw value is given along
+# with the scale range.
+SCALE_RANGE = {"MMSE": "0-30", "CDRSB": "0-18"}
+
+COGNITIVE = ["MMSE", "CDRSB"]
+
+# Soft tokenlarin prompt icindeki yeri (train/eval bu isarete gore boler)
+SENTINEL = "<<<MRI_SOFT_TOKENS>>>"
+
+READABLE = {
+    "Age": "Yaş", "Sex": "Cinsiyet", "MMSE": "MMSE", "CDRSB": "CDR-SB",
+    "APOE4_count": "APOE4 allel sayısı",
+    "CSF_ABETA42": "BOS Aβ42", "CSF_TAU": "BOS Tau", "CSF_PTAU": "BOS p-Tau",
+    "CSF_AB42_AB40": "BOS Aβ42/Aβ40",
+    "PLASMA_PTAU": "Plazma p-Tau", "PLASMA_NFL": "Plazma NfL",
+    "PLASMA_AB42_AB40": "Plazma Aβ42/Aβ40", "PLASMA_GFAP": "Plazma GFAP",
+}
+
+
+def fit_stats(values: np.ndarray, mask: np.ndarray, labels: np.ndarray,
+              cn_label: int = 0, min_n: int = 20) -> dict:
+    """
+    Referans dağılım: EĞİTİM split'inin SADECE CN (sağlıklı kontrol) alt grubu.
+
+    Neden tüm kohort değil: kohort CN+MCI+AD karışımı ve hastalık açısından
+    zenginleştirilmiş. Tüm kohorta göre z alırsak, klinik olarak açıkça
+    patolojik bir değer (ör. BOS Aβ42 570 pg/mL, belirgin amiloid pozitifliği)
+    "ortalamaya yakın" diye etiketlenir — LLM'e yanlış sinyal gider.
+    CN'e göre z ise "sağlıklı yaşlıya kıyasla" demektir ve yorumlanabilir.
+
+    CN örneği yetersizse (min_n altı) o özellik için tüm eğitim split'ine
+    düşer; hangisinin kullanıldığı stats'ta işaretlenir.
+    """
+    stats = {}
+    is_cn = labels == cn_label
+    for i in range(values.shape[1]):
+        cn_v = values[is_cn & (mask[:, i] > 0.5), i]
+        if len(cn_v) >= min_n:
+            stats[i] = (float(cn_v.mean()), float(cn_v.std() + 1e-6), "CN")
+            continue
+        all_v = values[mask[:, i] > 0.5, i]
+        stats[i] = (float(all_v.mean()), float(all_v.std() + 1e-6), "kohort") \
+            if len(all_v) > 5 else None
+    return stats
+
+
+def render_value(name, val, mean_std) -> str:
+    if name == "Sex":
+        return f"{READABLE[name]}: {'Erkek' if val >= 0.5 else 'Kadın'}"
+    if name == "Age":
+        return f"{READABLE[name]}: {val:.0f}"
+    if name == "APOE4_count":
+        return f"{READABLE[name]}: {int(round(val))}"
+
+    if name in SCALE_RANGE:
+        return f"{READABLE.get(name, name)}: {val:.1f} ({SCALE_RANGE[name]} ölçeği)"
+
+    base = f"{READABLE.get(name, name)}: {val:.2f}"
+    if mean_std is None:
+        return base
+    mean, std, ref = mean_std
+    ref_txt = "sağlıklı kontrollere göre" if ref == "CN" else "kohorta göre"
+    z = (val - mean) / std
+    if abs(z) < 1.0:
+        note = f"{ref_txt} normal aralıkta, {z:+.1f} SD"
+    else:
+        yon = "yüksek" if z > 0 else "düşük"
+        # Extra marker when the deviation points towards pathology
+        if (name in LOWER_IS_WORSE and z < 0) or (name in HIGHER_IS_WORSE and z > 0):
+            yon += ", bozulma yönünde"
+        note = f"{yon}, {ref_txt} {z:+.1f} SD"
+    return f"{base} ({note})"
+
+
+def build_prompt(names, vals, msk, stats, class_probs, will_progress,
+                 class_names, drop_cognitive=False, hide_diagnosis=False,
+                 minimal_target=False, atn_text=None,
+                 roi_lines=None) -> str:
+    """
+    hide_diagnosis=True → "Model çıktısı" bloğu prompt'a YAZILMAZ.
+
+    Neden gerekli: tanı hem metinde hem soft token'da bulunursa model kolay
+    yolu seçip metinden okur, görüntü temsiline hiç bakmaz. İlk koşuda tam
+    olarak bu oldu — soft token'lar sıfırlandığında raporlar neredeyse
+    kelimesi kelimesine aynı çıktı, yani füzyon sahteydi.
+
+    Tanıyı gizlediğimizde hedef metin hâlâ tanıyı içerdiği için projector
+    onu soft token'a KODLAMAK ZORUNDA kalır. Bu, füzyonun gerçek olup
+    olmadığının belirleyici testi.
+
+    Üretimde ise tanı yine metne konur (çıpa/güvenlik). Yani:
+      eğitim/ölçüm : hide_diagnosis=True   → projector öğrenmek zorunda
+      üretim       : hide_diagnosis=False  → tanı head'den, LLM anlatır
+    """
+    lines = []
+    dropped = []
+    for i, n in enumerate(names):
+        if drop_cognitive and n in COGNITIVE:
+            dropped.append(n)
+            continue
+        if msk[i] > 0.5:
+            lines.append("  " + render_value(n, float(vals[i]), stats.get(i)))
+        else:
+            lines.append(f"  {READABLE.get(n, n)}: ölçülmedi")
+
+    # SENTINEL marks where the soft tokens are spliced into the sequence.
+    # IMPORTANT: the model is given NO META-EXPLANATION about those tokens.
+    # An early version wrote "provided as soft tokens"; the model read that as
+    # "an attachment should be here but is missing" and spent the whole output
+    # asking the user to share it. Real VLMs do not announce their image tokens
+    # either — they simply place the content.
+    parts = ["Yapısal MRI değerlendirmesi:", SENTINEL, "",
+             "Hasta verileri:", "\n".join(lines), ""]
+    if roi_lines:
+        # Regional measurements come from FreeSurfer — measured data, so they
+        # belong on the INPUT side like the biomarkers. Not from our encoder.
+        parts += ["Bölgesel hacim/kalınlık (FreeSurfer, ICV'ye göre normalize):",
+                  "\n".join(roi_lines), ""]
+    if atn_text:
+        # ATN is computed by rule and supplied as INPUT; the LLM must not derive it.
+        parts += ["ATN profili (biyobelirteçlerden kural tabanlı hesaplandı):",
+                  "  " + atn_text, ""]
+    if hide_diagnosis:
+        pass  # no diagnosis — the class can only come from the representation
+    else:
+        probs = ", ".join(f"{c} %{100*p:.1f}" for c, p in zip(class_names, class_probs))
+        top = class_names[int(np.argmax(class_probs))]
+        parts += [
+            "Model çıktısı (Vbai-2.6AD, MRI + biyobelirteç füzyonu):",
+            f"  Sınıflandırma: {top}  ({probs})",
+            f"  MCI→AD ilerleme riski: {will_progress:.2f}",
+        ]
+    if not drop_cognitive:
+        parts.append(
+            "\nNot: CDR-SB ve MMSE klinisyenin kendi değerlendirme ölçekleridir; "
+            "bağımsız biyolojik kanıt değil, referans olarak verilmiştir."
+        )
+    if dropped:
+        parts.append(f"\nNot: {', '.join(dropped)} bu vakada mevcut değil.")
+    if minimal_target:
+        # Stage 1: one-word answer. The report instructions are deliberately
+        # absent so the model is pushed to state the class, not emit a template.
+        parts.append("\nSınıflandırma (CN / MCI / AD) nedir? "
+                     "Yalnızca sınıf adını yaz, başka hiçbir şey yazma.")
+    else:
+        parts.append(
+            ("\nYukarıdaki MRI değerlendirmesine ve verilere dayanarak kısa bir "
+             "klinik değerlendirme yaz; sınıflandırmayı (CN / MCI / AD) bildir.\n"
+             if hide_diagnosis else
+             "\nBulguları yorumla; sınıflandırma olasılıklarını değiştirme.\n") +
+            "Yanıtını TÜRKÇE ve kısa bir klinik değerlendirme olarak yaz. "
+            "Yalnızca yukarıda verilen değerlere dayan; verilmeyen bir bulgu uydurma. "
+            "'ölçülmedi' yazan bir değeri normal kabul etme."
+        )
+    return "\n".join(parts)
+
+
+# ─────────────────────────────────────────────────────
+# ATN framework (NIA-AA 2018)
+# ─────────────────────────────────────────────────────
+# Cut-offs follow the literature consensus and can be tuned to your own
+# laboratory. If you change them, remember that whatever runs in production must
+# use the same values as training, or the two drift apart.
+ATN_CUTOFFS = {
+    "amyloid_42_pgml":      600.0,   # < cutoff → A+
+    "amyloid_42_40_ratio":  0.07,    # < cutoff → A+ (daha güvenilir)
+    "ptau_pgml":            60.0,    # > cutoff → T+
+    "tau_pgml":             350.0,   # > cutoff → N+
+}
+
+
+def _sym(v) -> str:
+    return "?" if v is None else ("+" if v else "-")
+
+
+def _interpret_atn(A, T, N) -> str:
+    if A is None and T is None and N is None:
+        return "Biyobelirteç verisi mevcut değil; ATN sınıflandırılamadı."
+    if A and T and N:
+        return ("A+T+N+: Alzheimer continuum, demans evresinde patolojik "
+                "kanıt. AD altta yatan patoloji için yüksek olasılık.")
+    if A and T and N is False:
+        return ("A+T+N-: Alzheimer patolojik değişim (preklinik/prodromal). "
+                "Nörodejenerasyon henüz belirgin değil.")
+    if A and T is False:
+        return ("A+T-: Alzheimer patolojik değişim, tau henüz yükselmemiş "
+                "(erken evre). Klinik takip önerilir.")
+    if A is False and T and N:
+        return ("A-T+N+: SNAP (Suspected Non-AD Pathology) — vasküler/FTD/"
+                "primer tauopati ayırıcı tanısı gerekir.")
+    if A is False and T is False and N:
+        return ("A-T-N+: Nörodejenerasyon var, AD patolojisi yok — "
+                "SNAP veya yaşlanma; alternatif tanı araştırılmalı.")
+    if A is False and T is False and N is False:
+        return ("A-T-N-: Normal. AD patolojisi dışında. Diğer demans "
+                "tipleri ekarte edilmeli.")
+    return (f"Profil: {_sym(A)}{_sym(T)}{_sym(N)}. "
+            f"Eksik biyobelirteçler ile sınırlı yorum.")
+
+
+def atn_classification(biomarkers: dict, hippocampal_atrophy=None) -> dict:
+    """
+    NIA-AA 2018 ATN sınıflaması.
+
+      A (Amiloid):      BOS Aβ42 < 600 pg/mL  veya  Aβ42/40 < 0.07
+      T (Tau):          BOS p-tau > 60 pg/mL
+      N (Nörodejen.):   BOS total tau > 350 pg/mL  veya  hipokampal atrofi
+
+    Ölçülmeyen eksen None kalır — eksik veriyi "negatif" saymak, olmayan bir
+    bulguyu yok saymakla aynı hatadır ve bu projede özellikle kaçınılan şey.
+    """
+    abeta = biomarkers.get("csf_amyloid")
+    abeta_ratio = biomarkers.get("csf_amyloid_42_40_ratio")
+    ptau = biomarkers.get("csf_ptau")
+    tau = biomarkers.get("csf_tau")
+
+    A = None
+    if abeta_ratio is not None:
+        A = float(abeta_ratio) < ATN_CUTOFFS["amyloid_42_40_ratio"]
+    elif abeta is not None:
+        A = float(abeta) < ATN_CUTOFFS["amyloid_42_pgml"]
+
+    T = None
+    if ptau is not None:
+        T = float(ptau) > ATN_CUTOFFS["ptau_pgml"]
+
+    N = None
+    if tau is not None:
+        N = float(tau) > ATN_CUTOFFS["tau_pgml"]
+    elif hippocampal_atrophy is not None:
+        N = bool(hippocampal_atrophy)
+
+    return {
+        "A": A, "T": T, "N": N,
+        "profile": f"{_sym(A)}{_sym(T)}{_sym(N)}",
+        "interpretation": _interpret_atn(A, T, N),
+        "completeness": ("full" if all(v is not None for v in (A, T, N))
+                         else "partial" if any(v is not None for v in (A, T, N))
+                         else "none"),
+        "cutoffs": ATN_CUTOFFS,
+    }
+
+
+class _ATNModule:
+    """Thin shim preserving the old `cs.atn_classification(...)` call shape."""
+    atn_classification = staticmethod(atn_classification)
+    ATN_CUTOFFS = ATN_CUTOFFS
+
+
+def _load_clinical_scores():
+    """The ATN rules now live in this file; no external dependency."""
+    print("[atn] ATN rules built in (NIA-AA 2018)")
+    return _ATNModule()
+
+
+# Model feature name -> the key expected by atn_classification()
+ATN_KEY_MAP = {
+    "CSF_ABETA42": "csf_amyloid",
+    "CSF_AB42_AB40": "csf_amyloid_42_40_ratio",
+    "CSF_PTAU": "csf_ptau",
+    "CSF_TAU": "csf_tau",
+}
+
+
+def render_roi(roi_row, roi_stats) -> list:
+    """
+    Bölgesel ölçümleri sol/sağ ortalayarak kompakt satırlara döker.
+
+    Neden ortalama: 18 ayrı satır prompt'u gereksiz uzatıyor ve soft token'ın
+    bağlamdaki göreli ağırlığını düşürüyor. AD'de asimetri genelde ana bulgu
+    değil; belirgin olduğunda ayrıca not düşülüyor.
+
+    z-skoru referansı yine EĞİTİM split'inin CN alt grubu — "sağlıklı yaşlıya
+    k��yasla" demek, kohort ortalamasına kıyasla demekten klinik olarak
+    anlamlı. (Aynı gerekçe biyobelirteçlerde de geçerliydi.)
+    """
+    lines = []
+    for base, (lc, rc, worse_dir, unit) in ROI_PAIRS.items():
+        zs = []
+        for c in (lc, rc):
+            v, st = roi_row.get(c), roi_stats.get(c)
+            if v is None or (isinstance(v, float) and np.isnan(v)) or st is None:
+                continue
+            zs.append(((v - st[0]) / st[1], v))
+        if not zs:
+            lines.append(f"  {base}: ölçülmedi")
+            continue
+        z = float(np.mean([a for a, _ in zs]))
+        val = float(np.mean([b for _, b in zs]))
+        if abs(z) < 1.0:
+            note = f"sağlıklı kontrollere göre normal aralıkta, {z:+.1f} SD"
+        else:
+            yon = "yüksek" if z > 0 else "düşük"
+            if (worse_dir == "low" and z < 0) or (worse_dir == "high" and z > 0):
+                yon += ", bozulma yönünde"
+            note = f"{yon}, sağlıklı kontrollere göre {z:+.1f} SD"
+        asym = ""
+        if len(zs) == 2 and abs(zs[0][0] - zs[1][0]) > 1.0:
+            asym = "; sol/sağ asimetri belirgin"
+        lines.append(f"  {base}: {val:.3f} {unit} ({note}{asym})")
+    return lines
+
+
+# display label -> (left column, right column, which direction is pathological, unit)
+ROI_PAIRS = {
+    "Hipokampus":            ("Hipokampus (sol)", "Hipokampus (sağ)", "low", "% ICV"),
+    "Entorinal korteks":     ("Entorinal korteks (sol)", "Entorinal korteks (sağ)", "low", "% ICV"),
+    "Entorinal kalınlık":    ("Entorinal kalınlık (sol)", "Entorinal kalınlık (sağ)", "low", "mm"),
+    "Orta temporal":         ("Orta temporal (sol)", "Orta temporal (sağ)", "low", "% ICV"),
+    "Fusiform":              ("Fusiform (sol)", "Fusiform (sağ)", "low", "% ICV"),
+    "Prekuneus":             ("Prekuneus (sol)", "Prekuneus (sağ)", "low", "% ICV"),
+    "Alt parietal":          ("Alt parietal (sol)", "Alt parietal (sağ)", "low", "% ICV"),
+    "Lateral ventrikül":     ("Lateral ventrikül (sol)", "Lateral ventrikül (sağ)", "high", "% ICV"),
+    "Temporal boynuz":       ("Alt lateral ventrikül (sol)", "Alt lateral ventrikül (sağ)", "high", "% ICV"),
+}
+
+
+def compute_atn(cs, names, vals, msk) -> dict:
+    """Rule-based ATN profile derived from the biomarkers."""
+    bio = {}
+    for i, n in enumerate(names):
+        key = ATN_KEY_MAP.get(n)
+        if key and msk[i] > 0.5:
+            bio[key] = float(vals[i])
+    return cs.atn_classification(bio)
+
+
+def build_target_atn2(atn, class_probs, will_progress, class_names) -> str:
+    """
+    ATN PROMPT'A taşındıktan sonraki kısa hedef.
+
+    Neden değişti: ATN yorumunu hedefe koyduğumuz turda sadakat %100'den
+    %67.5'e düştü. Sebep, tam raporun ilk halindeki hatanın aynısı — ATN
+    metni uzun ve biyobelirteç değerlerinden neredeyse tamamen tahmin
+    edilebilir olduğu için ortalama kaybı aşağı çekip sınıf token'ının
+    sinyalini seyreltti. (Val kaybı 0.0222 ile en düşüktü ama sadakat en
+    kötüsüydü; kayıp kolay token'ların ortalamasıydı.)
+
+    İlke aynı kaldı, kapsamı genişledi: KOD HESAPLAYABİLİYORSA LLM ÜRETMESİN.
+    Sayılar gibi ATN de artık girdi tarafında. Hedefte yalnızca token'dan
+    okunması gereken şeyler var: sınıf ve risk seviyesi.
+    """
+    top = class_names[int(np.argmax(class_probs))]
+    risk = "yüksek" if will_progress > 0.6 else ("orta" if will_progress > 0.3 else "düşük")
+    s = [f"Değerlendirme: {top}."]
+    if top == "MCI":
+        s.append(f"Alzheimer'a ilerleme riski {risk}.")
+    s.append("Değerlendirme, yapısal MRI temsili ile mevcut biyobelirteçlerin "
+             "birlikte değerlendirilmesine dayanmaktadır.")
+    s.append("Bu çıktı karar desteği amaçlıdır; klinik tanı yerine geçmez.")
+    return " ".join(s)
+
+
+def build_target_atn(cs, class_probs, will_progress, class_names,
+                     names, vals, msk) -> str:
+    """
+    RAKAMSIZ hedef + kural tabanlı ATN profili.
+
+    Neden rakamsız: şablon hedefli önceki koşuda model sayıları da ezberledi —
+    üç farklı hastaya aynı "ilerleme riski 0.76" ve aynı eksik ölçüm listesini
+    yazdı. Doktor bunu o hastanın değeri sanar. LLM'in ürettiği her sayı,
+    uydurabileceği bir sayıdır.
+
+    Bölüşüm: SAYILAR KODDAN, DÜZYAZI LLM'DEN. Model "risk yüksek" der,
+    uygulama kesin değeri (0.80) head'den alıp yerleştirir.
+
+    ATN ise deterministik hesaplanıp hedefe yazılıyor — böylece model
+    biyobelirteç yönünü kendi ön yargısıyla ters çevirmiyor (her koşuda
+    tekrarlayan "+1.8 SD yüksek" → "düşük olması patolojiktir" hatası).
+    """
+    bio = {}
+    for i, n in enumerate(names):
+        key = ATN_KEY_MAP.get(n)
+        if key and msk[i] > 0.5:
+            bio[key] = float(vals[i])
+    atn = cs.atn_classification(bio)
+
+    top = class_names[int(np.argmax(class_probs))]
+    risk = "yüksek" if will_progress > 0.6 else ("orta" if will_progress > 0.3 else "düşük")
+
+    s = [f"Değerlendirme: {top}."]
+    if top == "MCI":
+        s.append(f"Alzheimer'a ilerleme riski {risk}.")
+    s.append(atn["interpretation"])
+    if atn["completeness"] != "full":
+        s.append("Biyobelirteç seti eksik olduğundan ATN sınıflandırması sınırlıdır; "
+                 "tamamlanması değerlendirmenin kesinliğini artırır.")
+    s.append("Değerlendirme, yapısal MRI temsili ile mevcut biyobelirteçlerin "
+             "birlikte değerlendirilmesine dayanmaktadır.")
+    s.append("Bu çıktı karar desteği amaçlıdır; klinik tanı yerine geçmez.")
+    return " ".join(s)
+
+
+def build_target_minimal(class_probs, class_names) -> str:
+    """
+    Aşama-1 hizalama hedefi: SADECE sınıf adı.
+
+    Neden: uzun şablon hedefte sınıf, 24 token'ın içinde tek bir token. LoRA
+    şablonu ezberleyerek kaybı düşürebiliyor ve vektörü hiç okumadan 0.118'e
+    inebiliyor — 1 Ağustos koşusunda tam olarak bu oldu (kayıp düştü ama
+    ablasyonda sınıf 30 vakanın sadece 5'inde değişti, yani sınıf metindeki
+    MMSE/CDR-SB'den okunuyordu).
+
+    Hedefi tek kelimeye indirince kaybın TAMAMI sınıf token'ına biner; model
+    şablon ezberleyerek kaçamaz. Kanalın çalışıp çalışmadığının en saf testi.
+    Çalıştığı doğrulandıktan sonra tam rapora dönülür.
+    """
+    return class_names[int(np.argmax(class_probs))]
+
+
+def build_target(class_probs, will_progress, class_names, names, vals, msk, stats) -> str:
+    """
+    Şablon hedef rapor. AMAÇ: projector'e "bu soft token şu tanıya karşılık
+    geliyor" hizalamasını öğretmek — Gemma'ya tıp öğretmek DEĞİL.
+    Bu yüzden bilinçli olarak sade ve deterministik; LLM ile sentezlenmiyor
+    (sentezlenirse başka bir modelin varsayımları öğretilmiş olur).
+    """
+    top_i = int(np.argmax(class_probs))
+    top = class_names[top_i]
+    conf = class_probs[top_i]
+    conf_word = "yüksek" if conf > 0.7 else ("orta" if conf > 0.5 else "düşük")
+
+    olculen = [READABLE.get(n, n) for i, n in enumerate(names)
+               if msk[i] > 0.5 and n not in ("Age", "Sex")]
+    eksik = [READABLE.get(n, n) for i, n in enumerate(names) if msk[i] <= 0.5]
+
+    s = [f"Değerlendirme: {top} ({conf_word} güven, %{100*conf:.0f})."]
+    if top == "MCI":
+        risk_word = "yüksek" if will_progress > 0.6 else ("orta" if will_progress > 0.3 else "düşük")
+        s.append(f"Alzheimer'a ilerleme riski {risk_word} ({will_progress:.2f}).")
+    s.append("Değerlendirme, yapısal MRI temsili ile mevcut biyobelirteçlerin "
+             "birlikte değerlendirilmesine dayanmaktadır.")
+    if eksik:
+        s.append("Eksik ölçümler: " + ", ".join(eksik[:4]) +
+                 ("." if len(eksik) <= 4 else " ve diğerleri."))
+        s.append("Bu ölçümlerin tamamlanması değerlendirmenin kesinliğini artırır.")
+    s.append("Bu çıktı karar desteği amaçlıdır; klinik tanı yerine geçmez.")
+    return " ".join(s)
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--features", required=True, help="output of extract_features.py (.pt)")
+    ap.add_argument("--out", required=True, help="output .json")
+    ap.add_argument("--drop-cognitive-p", type=float, default=0.5,
+                    help="probability of dropping MMSE/CDRSB during training (0 = never)")
+    ap.add_argument("--preview", type=int, default=2)
+    ap.add_argument("--roi", default=None,
+                    help="extract_roi.py ciktisi (.parquet) — bolgesel olcumler")
+    ap.add_argument("--atn", action="store_true",
+                    help="rakamsiz hedef + kural tabanli ATN profili")
+    ap.add_argument("--minimal-target", action="store_true",
+                    help="hedef = sadece sinif adi (asama-1 hizalama testi)")
+    ap.add_argument("--hide-diagnosis", action="store_true",
+                    help="taniyi prompttan cikar, sadece soft tokenda birak")
+    ap.add_argument("--seed", type=int, default=42)
+    args = ap.parse_args()
+
+    random.seed(args.seed)
+    d = torch.load(args.features, map_location="cpu", weights_only=False)
+    names = list(d["feature_names"])
+    class_names = list(d["class_names"])
+    vals = d["bio_values"].numpy()
+    msk = d["bio_mask"].numpy()
+    probs = d["class_probs"].numpy()
+    wp = d["will_progress"].numpy().reshape(-1)
+    splits = list(d["split"])
+    ptids = list(d["ptid"])
+
+    # z-score statistics come ONLY from the training split (no leakage)
+    labels_all = d["label"].numpy()
+    tr = np.array([s == "train" for s in splits])
+    cn_idx = list(class_names).index("CN") if "CN" in class_names else 0
+    stats = fit_stats(vals[tr], msk[tr], labels_all[tr], cn_label=cn_idx)
+    n_cn = int(((labels_all == cn_idx) & tr).sum())
+    from collections import Counter as _C
+    refs = _C(v[2] for v in stats.values() if v is not None)
+    print(f"[stats] reference distribution: healthy-control subgroup of the "
+          f"training split (n={n_cn})")
+    print(f"        {refs.get('CN', 0)} features referenced to controls, "
+          f"{refs.get('kohort', 0)} özellik tüm kohorta göre (CN örneği yetersiz), "
+          f"{len(names) - sum(refs.values())} özellik istatistiksiz")
+
+    cs = _load_clinical_scores() if args.atn else None
+
+    roi_df = roi_stats = None
+    if args.roi:
+        import pandas as pd
+        roi_df = pd.read_parquet(args.roi).sort_values('order').reset_index(drop=True)
+        if len(roi_df) != len(ptids):
+            raise ValueError(f"ROI satır sayısı ({len(roi_df)}) özellik cache'i "
+                             f"({len(ptids)}) ile uyuşmuyor — aynı parquet'ten mi üretildi?")
+        if list(roi_df["ptid"].astype(str)) != [str(p) for p in ptids]:
+            raise ValueError("ROI ve özellik cache'inde hasta sırası farklı.")
+        roi_cols = [c for c in roi_df.columns
+                    if c not in ('ptid', 'order', '_icv', '_gap_days')]
+        # z referansi: EGITIM split'inin CN alt grubu (biyobelirteclerle ayni ilke)
+        m_tr_cn = np.array([(s_ == 'train') and (l_ == cn_idx)
+                            for s_, l_ in zip(splits, labels_all)])
+        roi_stats = {}
+        for c in roi_cols:
+            v = roi_df.loc[m_tr_cn, c].dropna().values if m_tr_cn.sum() else []
+            roi_stats[c] = (float(np.mean(v)), float(np.std(v) + 1e-9)) if len(v) >= 20 else None
+        n_ok = sum(1 for v in roi_stats.values() if v)
+        print(f'[roi] {len(roi_cols)} bolge yuklendi, {n_ok} tanesi CN referansli '
+              f'(CN egitim n={int(m_tr_cn.sum())})')
+    records = []
+    for i in range(len(ptids)):
+        # cognitive dropout applies ONLY to training; val/test keep full text
+        drop = (splits[i] == "train") and (random.random() < args.drop_cognitive_p)
+        atn_i = compute_atn(cs, names, vals[i], msk[i]) if args.atn else None
+        roi_i = (render_roi(roi_df.iloc[i].to_dict(), roi_stats)
+                 if roi_df is not None else None)
+        records.append({
+            "index": i,
+            "ptid": ptids[i],
+            "split": splits[i],
+            "label": int(d["label"][i]),
+            "prompt": build_prompt(names, vals[i], msk[i], stats, probs[i], float(wp[i]),
+                                   class_names, drop_cognitive=drop,
+                                   hide_diagnosis=args.hide_diagnosis,
+                                   minimal_target=args.minimal_target,
+                                   atn_text=(atn_i["interpretation"] if atn_i else None),
+                                   roi_lines=roi_i),
+            "target": (build_target_minimal(probs[i], class_names)
+                       if args.minimal_target else
+                       build_target_atn2(atn_i, probs[i], float(wp[i]), class_names)
+                       if args.atn else
+                       build_target(probs[i], float(wp[i]), class_names,
+                                    names, vals[i], msk[i], stats)),
+            "cognitive_dropped": drop,
+        })
+
+    with open(args.out, "w", encoding="utf-8") as f:
+        json.dump({"records": records, "class_names": class_names,
+                   "hide_diagnosis": args.hide_diagnosis,
+                   "minimal_target": args.minimal_target,
+                   "feature_names": names, "modality": d.get("modality"),
+                   "ckpt": d.get("ckpt")}, f, ensure_ascii=False, indent=1)
+
+    from collections import Counter
+    print(f"[saved] {args.out}  ({len(records)} records)")
+    print(f"  split : {Counter(r['split'] for r in records)}")
+    print(f"  cognitive dropped (train): "
+          f"{sum(r['cognitive_dropped'] for r in records)}/{int(tr.sum())}")
+
+    for r in records[:args.preview]:
+        print("\n" + "=" * 68)
+        print(f"SAMPLE  ptid={r['ptid']}  split={r['split']}  "
+              f"gerçek={class_names[r['label']]}  cog_drop={r['cognitive_dropped']}")
+        print("-" * 68)
+        print(r["prompt"])
+        print("-" * 68 + "\nHEDEF:")
+        print(r["target"])
+    print("=" * 68)
+
+
+if __name__ == "__main__":
+    main()

chat.py

@@ -0,0 +1,385 @@
+"""
+Two-mode interactive chat
+=========================
+An interactive console where a clinician picks a patient and talks about them.
+
+TWO MODES, because measurement showed one configuration cannot do both well:
+
+  REPORT   (LoRA on, thinking off, soft tokens injected)
+     The trained closed-set tasks. Faithfulness 39/40, fast, fixed format.
+     Reads the diagnosis from the soft tokens — the channel is verified by
+     ablation, not assumed.
+
+  DISCUSS  (LoRA off, thinking on, NO soft tokens)
+     Open-ended clinical questions. The LoRA model got an atypical case wrong
+     ("precuneus/parietal atrophy is consistent with amnestic AD" — it is not);
+     the base model answered the same case correctly and with reasoning.
+     Soft tokens are unnecessary here: every measurement is already in the text.
+
+CONTEXT PRESERVATION — the core of this design:
+  Patient data, regional measurements, the ATN profile and Vbai-2.6AD's verdict are
+  written into the SYSTEM PROMPT, not into a user message. The system prompt
+  stays visible every turn and does not scroll out of context. A question asked
+  on turn 10 is still answered against the patient introduced on turn 1.
+
+FAITHFULNESS GUARD:
+  After every generation the class stated in the text is compared against the
+  head's verdict; a mismatch prints a warning. This catches CONTRADICTION WITH
+  THE HEAD only — it does not catch general medical errors. That limit is
+  permanent.
+
+Note on language: the assistant answers in Turkish. The system rules and the
+canonical questions are Turkish by design — that is what the adapter was
+trained on. Only this console's interface is English.
+
+Commands:
+  /report     switch to report mode     /discuss   switch to discuss mode
+  /patient N  jump to patient N         /data      show the system prompt
+  /reset      clear the conversation    /questions list trained questions
+  /help       command list              /quit      exit
+
+Run:
+    python chat.py --features features.pt --text dataset.json \
+        --projector projector.pt
+"""
+from __future__ import annotations
+import argparse
+import inspect
+import os
+import re
+import sys
+
+import torch
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from hfx_runtime import Projector, build_examples, SENTINEL
+from eval_faithfulness import find_class
+from eval_thinking import strip_body, split_thought
+
+# Kept in Turkish on purpose: this is the prompt the adapter was trained under.
+# Translating it would move the input off the training distribution.
+SYS_RULES = (
+    "Sen bir klinik karar destek asistanısın. Kurallar:\n"
+    "1. Yukarıdaki hasta verilerinin DIŞINA çıkma; verilmeyen bir bulgu uydurma.\n"
+    "2. 'ölçülmedi' yazan bir değeri normal kabul etme; eksik olduğunu söyle.\n"
+    "3. Vbai-2.6AD sınıflandırmasını DEĞİŞTİRME. Katılmadığın noktayı belirtebilirsin "
+    "ama sınıflandırma bu değerlendirmenin çıpasıdır.\n"
+    "4. Doktor itiraz ettiğinde fikrini kanıtsız değiştirme; gerekçeni göster.\n"
+    "5. Bu çıktı karar desteğidir, tanı yerine geçmez.\n"
+    "Yanıtlarını TÜRKÇE ver."
+)
+
+
+def build_system(ex, head: str, class_names, probs=None, will_progress=None) -> str:
+    """
+    Patient context + anchor. Lives in the system prompt, visible every turn.
+
+    THE HEAD'S OUTPUTS ARE WRITTEN HERE AS NUMBERS.
+    Why: every digit was stripped from the training targets (the model had
+    memorized "0.76" and was writing it for every patient). So the model CANNOT
+    produce numbers — and should not. But Vbai-2.6AD genuinely computes them, so
+    they are placed in the text for the model to read out when asked. This is
+    the "numbers from code, prose from the LLM" principle in practice.
+    """
+    lines = [f"Vbai-2.6AD değerlendirmesi: {head}"]
+    if probs is not None:
+        lines.append("  Sınıf olasılıkları: " +
+                     ", ".join(f"{c} %{100*p:.1f}" for c, p in zip(class_names, probs)))
+    if will_progress is not None:
+        if head == "MCI":
+            lines.append(f"  MCI→AD ilerleme riski (5 yıl): {float(will_progress):.2f}")
+        else:
+            # Vbai-2.6AD README: the progression head is only meaningful for MCI;
+            # a score is produced for CN/AD but must not be interpreted.
+            lines.append("  İlerleme riski: yalnızca MCI vakalarında anlamlıdır, "
+                         "bu vakada raporlanmaz.")
+    return (strip_body(ex["prompt"]).replace(SENTINEL, "").strip() +
+            "\n\n" + "\n".join(lines) + "\n\n" + SYS_RULES)
+
+
+@torch.no_grad()
+def generate(model, tok, embed_layer, projector, ex, device, supported,
+             messages, mode: str, max_new_tokens: int):
+    use_lora = (mode == "report")
+    thinking = (mode == "discuss")
+
+    kw = dict(tokenize=False, add_generation_prompt=True)
+    try:
+        full = tok.apply_chat_template(messages, enable_thinking=thinking, **kw)
+    except TypeError:
+        full = tok.apply_chat_template(messages, **kw)
+
+    ids = tok(full, add_special_tokens=False, return_tensors="pt").input_ids.to(device)
+    embeds = embed_layer(ids)
+    off = n_soft = 0
+    if use_lora:
+        # In report mode the soft tokens are prepended (the position the LoRA
+        # learned to read them from). In discuss mode the base model cannot read
+        # them, so they are omitted.
+        soft = projector(ex["feat"].unsqueeze(0).to(device)).to(embeds.dtype)
+        embeds = torch.cat([soft, embeds], dim=1)
+        n_soft = soft.size(1)
+
+    attn = torch.ones(embeds.shape[:2], dtype=torch.long, device=device)
+    gk = {"inputs_embeds": embeds, "attention_mask": attn,
+          "max_new_tokens": max_new_tokens, "do_sample": False,
+          "repetition_penalty": 1.1}
+    if n_soft and "mm_token_type_ids" in supported:
+        mm = torch.zeros(embeds.shape[:2], dtype=torch.long, device=device)
+        mm[0, off:off + n_soft] = 1
+        gk["mm_token_type_ids"] = mm
+
+    ctx = model.disable_adapter() if (not use_lora and hasattr(model, "disable_adapter")) \
+        else _null()
+    with ctx:
+        out = model.generate(**gk)
+    # generate() with inputs_embeds returns ONLY the new tokens; hitting the
+    # ceiling exactly means the output was cut off, not naturally finished.
+    truncated = out.shape[1] >= max_new_tokens
+    return tok.decode(out[0], skip_special_tokens=False), truncated
+
+
+def trained_questions() -> list:
+    """
+    The canonical questions report mode was trained on — read from the dataset
+    generator rather than copied by hand, so the two cannot drift apart.
+
+    Why a menu: LoRA learns PHRASE PATTERNS, not task boundaries. A free-typed
+    question landing between trained patterns gets answered with a blend of
+    them — one run produced both "atrophy is marked" and "all values are within
+    the normal range" in a single answer, and invented an anchor-undermining
+    line ("the Vbai-2.6AD assessment can be changed"). Keep the input inside the
+    distribution and blending cannot physically occur.
+
+    The questions themselves stay Turkish: they are the training strings.
+    """
+    try:
+        from build_multitask_dataset import TASKS, ABSENT_PROBES
+    except Exception:
+        return []
+    out, dummy = [], (None, None, None, None, [])
+    for name, fn in TASKS.items():
+        if name == "absent":
+            out.append((name, ABSENT_PROBES[0][0]))
+            continue
+        try:
+            q, _ = fn(*dummy) if name != "probs" else fn(
+                "MCI", "yüksek", None, None, [], probs=[0.1, 0.8, 0.1],
+                class_names=["CN", "MCI", "AD"], will_progress=0.5)
+            out.append((name, q))
+        except Exception:
+            continue
+    return out
+
+
+def find_verdict(text: str, class_names) -> str | None:
+    """
+    Return the class only when it appears in an EXPLICIT VERDICT pattern, not
+    merely the first class name occurring in the text. Long discussion answers
+    enumerate differentials, and those mentions must not be mistaken for a
+    verdict.
+    """
+    lab = (r"(?:Değerlendirme|Sınıflandırma|Sonuç|Tanı|Vbai-2.6AD[^:\n]*|"
+           r"Classification|Assessment|Diagnosis)")
+    m = re.search(lab + r"[^\n:]*:\s*\**\s*(" +
+                  "|".join(map(re.escape, class_names)) + r")\b",
+                  text, flags=re.IGNORECASE)
+    if not m:
+        return None
+    for c in class_names:
+        if c.lower() == m.group(1).lower():
+            return c
+    return None
+
+
+def clean(t: str) -> str:
+    """Hide control tokens — they arrive because skip_special_tokens=False."""
+    for m in ("<eos>", "<turn|>", "<|turn>", "<bos>", "<end_of_turn>"):
+        t = t.replace(m, "")
+    return t.strip()
+
+
+class _null:
+    def __enter__(self): return None
+    def __exit__(self, *a): return False
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--features", required=True)
+    ap.add_argument("--text", required=True)
+    ap.add_argument("--projector", default="projector.pt",
+                    help="projector checkpoint; the LoRA adapter is expected "
+                         "alongside it at <projector>_lora/")
+    ap.add_argument("--model", default=None)
+    ap.add_argument("--split", default="test")
+    ap.add_argument("--patient", type=int, default=0,
+                    help="index of the patient within the split")
+    ap.add_argument("--mode", default="report", choices=["report", "discuss"])
+    # Budget per mode: in discuss mode the chain of thought alone eats 1000+
+    # tokens and left no room for the answer. Report answers are short.
+    ap.add_argument("--max-new-report", type=int, default=500)
+    ap.add_argument("--max-new-discuss", type=int, default=2500)
+    ap.add_argument("--no-4bit", dest="four_bit", action="store_false", default=True)
+    args = ap.parse_args()
+
+    import transformers
+    from transformers import AutoTokenizer
+    AutoCls = next(getattr(transformers, n) for n in
+                   ("AutoModelForConditionalGeneration", "AutoModelForImageTextToText",
+                    "AutoModelForCausalLM") if hasattr(transformers, n))
+
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+    ck = torch.load(args.projector, map_location="cpu", weights_only=False)
+    model_id = args.model or ck["model_id"]
+    data, d = build_examples(args.features, args.text)
+    class_names = list(d["class_names"])
+
+    tok = AutoTokenizer.from_pretrained(model_id)
+    load_kw = dict(device_map={"": 0} if device == "cuda" else None)
+    if args.four_bit:
+        from transformers import BitsAndBytesConfig
+        load_kw["quantization_config"] = BitsAndBytesConfig(
+            load_in_4bit=True, bnb_4bit_quant_type="nf4",
+            bnb_4bit_compute_dtype=torch.bfloat16, bnb_4bit_use_double_quant=True)
+    try:
+        model = AutoCls.from_pretrained(model_id, dtype=torch.bfloat16, **load_kw)
+    except TypeError:
+        model = AutoCls.from_pretrained(model_id, torch_dtype=torch.bfloat16, **load_kw)
+    supported = set(inspect.signature(model.forward).parameters)
+    embed_layer = model.get_input_embeddings()
+
+    if ck.get("lora") and os.path.isdir(args.projector + "_lora"):
+        from peft import PeftModel
+        model = PeftModel.from_pretrained(model, args.projector + "_lora")
+    model.eval()
+
+    projector = Projector(ck["in_dim"], ck["hidden"], ck["n_tokens"],
+                          target_norm=ck.get("target_norm")).to(device)
+    projector.load_state_dict(ck["projector"]); projector.eval()
+
+    # De-duplicate by patient (the multitask file holds several records each)
+    seen, patients = set(), []
+    for e in data[args.split]:
+        if e["ptid"] not in seen:
+            seen.add(e["ptid"]); patients.append(e)
+
+    probs_all = d["class_probs"]
+    wp_all = d["will_progress"].reshape(-1)
+
+    def mk_system(e):
+        i = e.get("index")
+        return build_system(e, e["head"], class_names,
+                            probs_all[i].tolist() if i is not None else None,
+                            float(wp_all[i]) if i is not None else None)
+
+    idx, mode = args.patient, args.mode
+    ex = patients[idx]
+    system = mk_system(ex)
+    messages = [{"role": "system", "content": system}]
+
+    tq = trained_questions()
+
+    def show_questions():
+        if not tq:
+            print("  (could not read the trained question list)"); return
+        print("\n  Questions report mode was trained on — ask by number:")
+        for k, (name, qq) in enumerate(tq, 1):
+            print(f"   {k}. [{name}] {qq}")
+        print("  Free text is allowed but falls outside the distribution in "
+              "report mode.")
+
+    print(f"\n{'='*70}\nPatient {ex['ptid']}  |  Vbai-2.6AD: {ex['head']}  |  "
+          f"true: {class_names[ex['label']]}  |  mode: {mode}")
+    print(f"{len(patients)} patients loaded. /help for commands.\n{'='*70}")
+    show_questions()
+
+    while True:
+        try:
+            q = input(f"\n[{mode}] clinician> ").strip()
+        except (EOFError, KeyboardInterrupt):
+            break
+        if not q:
+            continue
+        if q in ("/quit", "/exit"):
+            break
+        if q == "/help":
+            print("  /report  /discuss  /patient N  /data  /reset  /questions  /quit")
+            print("  in report mode you can ask a question BY NUMBER (1-8)")
+            continue
+        if q == "/questions":
+            show_questions(); continue
+        if q in ("/report", "/discuss"):
+            mode = q[1:]
+            print(f"  → mode: {mode}" +
+                  ("  (LoRA on, thinking off, soft tokens injected)" if mode == "report"
+                   else "  (LoRA off, thinking on, reasoning from the base model)"))
+            continue
+        if q.startswith("/patient"):
+            try:
+                idx = int(q.split()[1]) % len(patients)
+            except (IndexError, ValueError):
+                print("  usage: /patient 3"); continue
+            ex = patients[idx]
+            system = mk_system(ex)
+            messages = [{"role": "system", "content": system}]
+            print(f"  → patient {ex['ptid']}  Vbai-2.6AD: {ex['head']}  "
+                  f"true: {class_names[ex['label']]}  (conversation reset)")
+            continue
+        if q == "/data":
+            print("\n" + system); continue
+        if q == "/reset":
+            messages = [{"role": "system", "content": system}]
+            print("  → conversation reset (patient context preserved)"); continue
+
+        # Report mode: a number selects a canonical question. The input stays
+        # inside the distribution, so pattern blending cannot occur. Free text
+        # is permitted but warned about.
+        if mode == "report" and tq:
+            if q.isdigit() and 1 <= int(q) <= len(tq):
+                task_name, q = tq[int(q) - 1]
+                print(f"  → [{task_name}] {q}")
+            elif not q.startswith("/"):
+                print("  ⚠ This question is outside the trained patterns; report "
+                      "mode answers may blend. Use /questions for the list, or "
+                      "switch to /discuss.")
+
+        messages.append({"role": "user", "content": q})
+        budget = args.max_new_report if mode == "report" else args.max_new_discuss
+        raw, truncated = generate(model, tok, embed_layer, projector, ex, device,
+                                  supported, messages, mode, budget)
+        thought, answer = split_thought(raw)
+        answer = clean(answer)
+
+        if thought:
+            print(f"\n  [reasoning, {len(thought)} chars — hidden]")
+        print("\nassistant> " + answer)
+        if truncated:
+            print(f"\n  ⚠ Answer was CUT OFF at the {budget}-token limit — this is "
+                  f"not the model's natural stop. Ask something shorter or raise "
+                  f"--max-new-{mode}.")
+
+        # --- faithfulness guard: does the stated class contradict the head? ---
+        #
+        # In discuss mode ONLY the labelled verdict pattern is searched
+        # ("Değerlendirme: X", "Classification: X"). The first-class-mentioned
+        # fallback produced false alarms here: while walking through
+        # differentials the model would write "Early-Onset AD" and the guard
+        # read AD as a verdict. A guard that cries wolf gets ignored when a real
+        # contradiction appears.
+        said = find_verdict(answer, class_names) if mode == "discuss" \
+            else find_class(answer, class_names)
+        if said and said != ex["head"]:
+            print(f"\n  ⚠ WARNING: the model said '{said}' while Vbai-2.6AD says "
+                  f"'{ex['head']}'. This contradiction needs review.")
+
+        messages.append({"role": "assistant", "content": answer})
+        # keep context bounded: system + last 8 messages
+        if len(messages) > 9:
+            messages = [messages[0]] + messages[-8:]
+
+    print("\nexited.")
+
+
+if __name__ == "__main__":
+    main()

config.py

@@ -0,0 +1,212 @@
+"""
+Vbai-2.6AD — configuration.
+
+Paired multimodal early-Alzheimer's detection: a 3D MRI volume plus a panel of
+13 biomarkers, fused into one representation.
+
+--------------------------------------------------------------------------
+YOU MUST SET YOUR OWN PATHS.
+--------------------------------------------------------------------------
+No data location is hard-coded. Point the environment variables below at your
+own files before running anything:
+
+    VBAI_DATASET_ROOT     root of your imaging + tabular data
+    VBAI_VOLUME_ROOT      root of the volume files referenced by the manifest
+    VBAI_MODEL_SAVE_ROOT  where checkpoints are written
+
+If a variable is unset, the loader walks up the project tree looking for a
+`Datasets` directory. If that fails too, the data-preparation step raises an
+explicit error rather than guessing.
+
+Nothing here describes or names a particular corpus. Bring your own data; the
+expected column contract is FEATURE_NAMES below.
+"""
+import os
+from dataclasses import dataclass, field
+from typing import List
+
+PROJECT_ROOT = os.path.dirname(os.path.abspath(__file__))
+
+
+def _walk_up_for_marker(start: str, marker_subdirs=("Datasets",), max_levels: int = 6):
+    """Walk upwards from `start` until a directory containing all markers is found."""
+    cur = os.path.abspath(start)
+    for _ in range(max_levels):
+        if all(os.path.isdir(os.path.join(cur, m)) for m in marker_subdirs):
+            return cur
+        parent = os.path.dirname(cur)
+        if parent == cur:
+            break
+        cur = parent
+    return None
+
+
+def _resolve_dataset_root() -> str:
+    """Resolution order: environment variable → project-tree search → default."""
+    env = os.environ.get("VBAI_DATASET_ROOT")
+    if env and os.path.isdir(env):
+        return env
+
+    walked = _walk_up_for_marker(PROJECT_ROOT, marker_subdirs=("Datasets",))
+    if walked is not None:
+        return os.path.join(walked, "Datasets")
+
+    # Fall through to a relative default; data preparation will report clearly
+    # if nothing is there. SET VBAI_DATASET_ROOT TO YOUR OWN PATH.
+    return os.path.normpath(os.path.join(PROJECT_ROOT, "..", "Datasets"))
+
+
+def _resolve_model_save_root() -> str:
+    env = os.environ.get("VBAI_MODEL_SAVE_ROOT")
+    if env:
+        return env
+    walked = _walk_up_for_marker(PROJECT_ROOT, marker_subdirs=("Datasets",))
+    if walked is not None:
+        return os.path.join(walked, "Models", "Vbai-2.6AD")
+    return os.path.normpath(os.path.join(PROJECT_ROOT, "..", "Models", "Vbai-2.6AD"))
+
+
+DATASET_ROOT = _resolve_dataset_root()
+MODEL_SAVE_ROOT = _resolve_model_save_root()
+
+# Root of the volume files. The visit manifest stores relative paths; this is
+# what they are resolved against. SET VBAI_VOLUME_ROOT TO YOUR OWN PATH.
+VOLUME_ROOT = os.environ.get("VBAI_VOLUME_ROOT") or os.path.join(DATASET_ROOT, "volumes")
+
+# Kept for backward compatibility with scripts that expect these names.
+TBM_ROOT = VOLUME_ROOT
+TBM_CSV = os.environ.get("VBAI_VOLUME_MANIFEST") or os.path.join(VOLUME_ROOT, "manifest.csv")
+
+# Which volume modality is in use. Selected by the extraction scripts through
+# the --tbm / --t1 flag, which sets this variable before config is imported.
+# A checkpoint trained on one modality must never be fed the other.
+USE_TBM = bool(int(os.environ.get("VBAI_USE_TBM", "0")))
+
+CACHE_DIR = os.path.join(PROJECT_ROOT, "_cache")
+os.makedirs(CACHE_DIR, exist_ok=True)
+PAIRED_PARQUET_T1 = os.path.join(CACHE_DIR, "paired_visits.parquet")
+PAIRED_PARQUET_TBM = os.path.join(CACHE_DIR, "paired_visits_tbm.parquet")
+PAIRED_PARQUET = PAIRED_PARQUET_TBM if USE_TBM else PAIRED_PARQUET_T1
+
+# Tabular feature order — a fixed contract relied on everywhere downstream.
+# Your table must provide these columns (missing values are allowed and are
+# handled explicitly through a per-feature mask; see NUM_TABULAR_INPUTS).
+FEATURE_NAMES: List[str] = [
+    "Age",                # demographic
+    "Sex",                # 0 = F, 1 = M
+    "MMSE",               # cognitive
+    "CDRSB",              # cognitive (CDR sum of boxes)
+    "APOE4_count",        # genetic, 0/1/2 e4 alleles
+    "CSF_ABETA42",        # CSF
+    "CSF_TAU",            # CSF
+    "CSF_PTAU",           # CSF
+    "CSF_AB42_AB40",      # CSF ratio
+    "PLASMA_PTAU",        # blood
+    "PLASMA_NFL",         # blood
+    "PLASMA_AB42_AB40",   # blood ratio
+    "PLASMA_GFAP",        # blood
+]
+NUM_FEATURES = len(FEATURE_NAMES)            # 13
+# One value plus one missing-mask bit per feature. The mask is not decoration:
+# an unmeasured biomarker must stay distinguishable from a normal one.
+NUM_TABULAR_INPUTS = NUM_FEATURES * 2
+
+CLASS_NAMES = ["CN", "MCI", "AD"]
+DIAGNOSIS_MAP = {"CN": 0, "MCI": 1, "Dementia": 2, "AD": 2,
+                 "EMCI": 1, "LMCI": 1, "SMC": 0}
+
+
+@dataclass
+class ModelConfig:
+    mri_input_shape: tuple = (1, 96, 96, 96)
+    mri_encoder_channels: List[int] = field(default_factory=lambda: [32, 64, 128, 256])
+    mri_bottleneck_channels: int = 512
+    mri_feature_dim: int = 512
+    mri_dropout: float = 0.4
+    use_cbam: bool = True
+    use_se_block: bool = True
+
+    num_tabular_inputs: int = NUM_TABULAR_INPUTS
+    tabular_hidden_dims: List[int] = field(default_factory=lambda: [128, 256])
+    tabular_feature_dim: int = 256
+    tabular_dropout: float = 0.3
+
+    fusion_dim: int = 512
+    fusion_num_heads: int = 8
+    fusion_dropout: float = 0.3
+
+    num_classes: int = 3
+    progression_hidden_dim: int = 256
+    max_progression_months: int = 120
+    num_time_bins: int = 24
+
+    # Modality dropout during training: teaches the model to survive a missing
+    # arm at inference instead of collapsing.
+    p_drop_mri: float = 0.15
+    p_drop_tab: float = 0.15
+    # Feature-wise random masking, simulating biomarkers absent at inference.
+    p_feature_mask: float = 0.20
+
+
+@dataclass
+class TrainingConfig:
+    seed: int = 42
+    device: str = "cuda"
+    num_workers: int = 4
+    pin_memory: bool = True
+    mixed_precision: bool = True
+
+    # Phase 1 — MRI encoder pretraining
+    phase1_epochs: int = 40
+    phase1_batch_size: int = 4
+    phase1_lr: float = 3e-4
+    phase1_weight_decay: float = 1e-4
+
+    # Phase 2 — tabular encoder pretraining
+    phase2_epochs: int = 60
+    phase2_batch_size: int = 64
+    phase2_lr: float = 1e-3
+    phase2_weight_decay: float = 1e-4
+
+    # Phase 3 — joint fusion on paired visits
+    phase3_epochs: int = 40
+    phase3_batch_size: int = 4
+    phase3_lr_backbone: float = 1e-5
+    phase3_lr_fusion: float = 5e-4
+    phase3_weight_decay: float = 1e-4
+
+    # Loss weights
+    w_cls_fused: float = 1.0
+    w_cls_mri: float = 0.3
+    w_cls_tab: float = 0.3
+    w_prog: float = 0.5
+    w_contrastive: float = 0.2
+    focal_gamma: float = 1.0
+    label_smoothing: float = 0.05
+
+    grad_clip: float = 1.0
+    val_split: float = 0.15
+    test_split: float = 0.15      # subject-level holdout, never visit-level
+    early_stopping_patience: int = 20
+    min_epochs_before_es: int = 25
+
+    save_dir: str = MODEL_SAVE_ROOT
+
+
+@dataclass
+class DataConfig:
+    nifti_target_shape: tuple = (96, 96, 96)
+    pair_window_months: int = 6            # MRI ↔ biomarker date tolerance
+    progression_horizon_months: int = 60   # 5-year look-ahead for MCI → AD
+    aug_rotation_range: float = 8.0
+    aug_flip_prob: float = 0.5
+    aug_noise_std: float = 0.02
+    aug_gamma_range: tuple = (0.85, 1.15)
+
+    # Optional hippocampus-focused crop: the brain bounding box is found, then
+    # a centre crop is taken at these ratios and resized to nifti_target_shape.
+    # x: left-right (both hemispheres), y: anterior-posterior, z: inferior-superior
+    hippocampus_crop_enabled: bool = False
+    hippo_x_range: tuple = (0.10, 0.90)
+    hippo_y_range: tuple = (0.25, 0.70)
+    hippo_z_range: tuple = (0.15, 0.65)

dataset.py

@@ -0,0 +1,284 @@
+"""
+Vbai-2.6AD Datasets
+===================
+Reads the cached visit manifest at _cache/paired_visits.parquet, which your own
+data-preparation step must produce. One row per visit: a volume path, the 13
+biomarker columns with their per-feature masks, the label and the progression
+fields.
+
+Three dataset modes:
+    * mode="mri"    → MRI + label (Phase 1 pretrain)
+    * mode="tab"    → tabular features + label (Phase 2 pretrain)
+    * mode="multi"  → MRI + tabular + label + progression (Phase 3 fusion)
+
+Tabular feature contract: 2 * NUM_FEATURES floats per sample.
+    [normalized values..., missing-mask bits...]
+A feature with missing-mask=0 has its value zeroed (after normalization).
+"""
+from __future__ import annotations
+import os
+import random
+import numpy as np
+import pandas as pd
+import torch
+from torch.utils.data import Dataset, DataLoader, WeightedRandomSampler
+from scipy.ndimage import zoom, rotate
+
+import config as C
+
+try:
+    import nibabel as nib
+    HAS_NIBABEL = True
+except Exception:
+    HAS_NIBABEL = False
+
+
+# Optional pre-decoded .npy cache, searched in order. Decoding NIfTI is the
+# slowest part of an epoch, so a local-disk cache pays for itself quickly.
+# YOU MUST SET YOUR OWN PATH: point VBAI_NPY_CACHE at a fast local directory,
+# or leave it unset to use the in-project cache.
+_NPY_CACHE_DIRS = [d for d in [
+    os.environ.get("VBAI_NPY_CACHE"),
+    os.path.join(C.PROJECT_ROOT, "_cache", "volume_npy"),
+] if d]
+
+
+def _try_load_cached(image_id: str) -> np.ndarray | None:
+    if not image_id:
+        return None
+    for d in _NPY_CACHE_DIRS:
+        p = os.path.join(d, f"{image_id}.npy")
+        if os.path.exists(p):
+            try:
+                return np.load(p).astype(np.float32)
+            except Exception:
+                return None
+    return None
+
+
+# ---------- MRI loading + augmentation ----------
+def _hippocampus_crop(data: np.ndarray, dcfg: C.DataConfig) -> np.ndarray:
+    """Find the brain bounding box, then crop to a hippocampus-focused sub-region."""
+    mask = data > 0
+    if not mask.any():
+        return data
+    coords = np.argwhere(mask)
+    mn = coords.min(axis=0); mx = coords.max(axis=0)
+    size = mx - mn + 1
+    rx, ry, rz = dcfg.hippo_x_range, dcfg.hippo_y_range, dcfg.hippo_z_range
+    x0, x1 = int(mn[0] + size[0] * rx[0]), int(mn[0] + size[0] * rx[1])
+    y0, y1 = int(mn[1] + size[1] * ry[0]), int(mn[1] + size[1] * ry[1])
+    z0, z1 = int(mn[2] + size[2] * rz[0]), int(mn[2] + size[2] * rz[1])
+    cropped = data[x0:x1+1, y0:y1+1, z0:z1+1]
+    return cropped
+
+
+def _load_nifti(path: str, target_shape=(96, 96, 96),
+                hippocampus_crop: bool = False, dcfg: C.DataConfig = None) -> np.ndarray:
+    img = nib.load(path)
+    data = img.get_fdata().astype(np.float32)
+    if data.ndim == 4:
+        data = data[..., 0]
+    mask = data > 0
+    if mask.sum() > 0:
+        vals = data[mask]
+        lo, hi = np.percentile(vals, [1.0, 99.0])
+        data = np.clip(data, lo, hi)
+        m, s = vals.mean(), vals.std()
+        if s > 0:
+            data = (data - m) / s
+        data[~mask] = 0
+    # Hippocampus-focused crop: narrows the content, which raises effective resolution
+    if hippocampus_crop:
+        data = _hippocampus_crop(data, dcfg or C.DataConfig())
+    if data.shape != target_shape:
+        f = [t / s for t, s in zip(target_shape, data.shape)]
+        data = zoom(data, f, order=1)
+    return data.astype(np.float32)
+
+
+class MRIAugment3D:
+    def __init__(self, dcfg: C.DataConfig):
+        self.cfg = dcfg
+
+    def __call__(self, vol: np.ndarray) -> np.ndarray:
+        if random.random() < 0.5:
+            angle = random.uniform(-self.cfg.aug_rotation_range, self.cfg.aug_rotation_range)
+            axes = random.choice([(0, 1), (0, 2), (1, 2)])
+            vol = rotate(vol, angle, axes=axes, reshape=False, order=1, mode="nearest")
+        for ax in range(3):
+            if random.random() < self.cfg.aug_flip_prob:
+                vol = np.flip(vol, axis=ax).copy()
+        if random.random() < 0.3:
+            vol = vol + np.random.normal(0, self.cfg.aug_noise_std, vol.shape).astype(np.float32)
+        if random.random() < 0.3:
+            g = random.uniform(*self.cfg.aug_gamma_range)
+            mn = vol.min(); rg = vol.max() - mn
+            if rg > 0:
+                vol = ((vol - mn) / rg) ** g * rg + mn
+        return vol.astype(np.float32)
+
+
+# ---------- Tabular normalization ----------
+class TabularNormalizer:
+    """Robust z-score on observed (non-missing) values per feature, fit on training set."""
+    def __init__(self):
+        self.mean: np.ndarray | None = None
+        self.std: np.ndarray | None = None
+
+    def fit(self, df: pd.DataFrame):
+        means, stds = [], []
+        for f in C.FEATURE_NAMES:
+            v = pd.to_numeric(df[f], errors="coerce").dropna().values.astype(np.float64)
+            if len(v) > 1:
+                m = float(np.median(v))
+                s = float(np.median(np.abs(v - m)) * 1.4826)  # MAD → std
+                if s < 1e-8:
+                    s = float(v.std()) if v.std() > 1e-8 else 1.0
+            else:
+                m, s = 0.0, 1.0
+            means.append(m); stds.append(s)
+        self.mean = np.asarray(means, dtype=np.float32)
+        self.std = np.asarray(stds, dtype=np.float32)
+
+    def transform(self, values: np.ndarray, mask: np.ndarray) -> np.ndarray:
+        z = (values - self.mean) / self.std
+        z = np.where(mask > 0.5, z, 0.0)        # zero out missing
+        return np.concatenate([z, mask.astype(np.float32)], axis=-1)
+
+    def state_dict(self):
+        return {"mean": self.mean.tolist() if self.mean is not None else None,
+                "std": self.std.tolist() if self.std is not None else None}
+
+    def load_state_dict(self, sd):
+        self.mean = np.asarray(sd["mean"], dtype=np.float32)
+        self.std = np.asarray(sd["std"], dtype=np.float32)
+
+
+# ---------- Subject-level split (no leakage between train/val/test) ----------
+def subject_split(df: pd.DataFrame, val_frac=0.15, test_frac=0.15, seed=42):
+    rng = np.random.RandomState(seed)
+    ptids = np.array(sorted(df["ptid"].unique()))
+    rng.shuffle(ptids)
+    n = len(ptids)
+    n_test = int(round(n * test_frac))
+    n_val = int(round(n * val_frac))
+    test_ids = set(ptids[:n_test])
+    val_ids = set(ptids[n_test:n_test + n_val])
+    train_ids = set(ptids[n_test + n_val:])
+    print(f"[split] subjects → train {len(train_ids)} / val {len(val_ids)} / test {len(test_ids)}")
+    return train_ids, val_ids, test_ids
+
+
+# ---------- Core paired dataset ----------
+class PairedVisitDataset(Dataset):
+    """
+    One sample = one MRI scan with paired biomarkers + (optional) progression labels.
+    Setting mode controls which fields are loaded:
+        "mri"   — only mri + label (skips biomarker columns)
+        "tab"   — only biomarkers + label (skips MRI loading)
+        "multi" — both
+    """
+    def __init__(self, df: pd.DataFrame, normalizer: TabularNormalizer,
+                 mode: str = "multi", augment: bool = False,
+                 dcfg: C.DataConfig = None, mcfg: C.ModelConfig = None,
+                 train_modality_dropout: bool = False):
+        self.df = df.reset_index(drop=True).copy()
+        self.norm = normalizer
+        self.mode = mode
+        self.augment = augment
+        self.dcfg = dcfg or C.DataConfig()
+        self.mcfg = mcfg or C.ModelConfig()
+        self.augmenter = MRIAugment3D(self.dcfg) if augment else None
+        self.modality_dropout = train_modality_dropout
+
+    def __len__(self):
+        return len(self.df)
+
+    def _get_tab(self, row, training: bool):
+        vals = np.array([row[f] for f in C.FEATURE_NAMES], dtype=np.float32)
+        mask = np.array([row[f"feat_mask_{f}"] for f in C.FEATURE_NAMES], dtype=np.float32)
+        # NaN safety
+        vals = np.where(np.isnan(vals), 0.0, vals)
+        # Stochastic feature masking during training (simulate missing inputs)
+        if training and self.mcfg.p_feature_mask > 0:
+            drop = np.random.rand(len(C.FEATURE_NAMES)) < self.mcfg.p_feature_mask
+            mask = np.where(drop, 0.0, mask)
+        return self.norm.transform(vals, mask).astype(np.float32)
+
+    def _get_mri(self, row):
+        # Fast path: pre-decoded .npy on local disk
+        vol = _try_load_cached(row.get("image_id"))
+        if vol is None:
+            vol = _load_nifti(row["nifti_path"], self.dcfg.nifti_target_shape)
+        if self.augment and self.augmenter:
+            vol = self.augmenter(vol)
+        return torch.from_numpy(np.ascontiguousarray(vol)).unsqueeze(0).float()
+
+    def __getitem__(self, idx):
+        row = self.df.iloc[idx]
+        out = {
+            "label": torch.tensor(int(row["label"]), dtype=torch.long),
+            "has_progression": torch.tensor(bool(row["has_progression"]), dtype=torch.bool),
+            "will_progress": torch.tensor(float(row["will_progress"]), dtype=torch.float32),
+            "progression_months": torch.tensor(float(row["months_to_conversion"]), dtype=torch.float32),
+            "ptid": str(row["ptid"]),
+        }
+
+        load_mri = self.mode in ("mri", "multi")
+        load_tab = self.mode in ("tab", "multi")
+
+        # Modality dropout (Phase 3 only)
+        if self.modality_dropout and self.mode == "multi":
+            r = random.random()
+            if r < self.mcfg.p_drop_mri:
+                load_mri = False
+            elif r < self.mcfg.p_drop_mri + self.mcfg.p_drop_tab:
+                load_tab = False
+
+        if load_mri:
+            out["mri"] = self._get_mri(row)
+        if load_tab:
+            out["tab"] = torch.from_numpy(self._get_tab(row, training=self.augment))
+        out["has_mri"] = torch.tensor(load_mri, dtype=torch.bool)
+        out["has_tab"] = torch.tensor(load_tab, dtype=torch.bool)
+        return out
+
+
+def collate_pad(batch):
+    """Collate that handles optional mri/tab tensors per-sample."""
+    keys = ["label", "has_progression", "will_progress", "progression_months", "has_mri", "has_tab"]
+    out = {k: torch.stack([b[k] for b in batch]) for k in keys}
+    # MRI: only stack if all present (modality dropout makes mixed batches rare in practice;
+    # we drop unmatched samples to None at batch level to keep things simple)
+    if all("mri" in b for b in batch):
+        out["mri"] = torch.stack([b["mri"] for b in batch])
+    if all("tab" in b for b in batch):
+        out["tab"] = torch.stack([b["tab"] for b in batch])
+    out["ptid"] = [b["ptid"] for b in batch]
+    return out
+
+
+# ---------- Helpers ----------
+def get_class_weights(labels: np.ndarray, num_classes: int = 3) -> torch.Tensor:
+    counts = np.bincount(labels, minlength=num_classes).astype(np.float32)
+    counts[counts == 0] = 1.0
+    w = 1.0 / counts
+    w = w / w.sum() * num_classes
+    return torch.tensor(w, dtype=torch.float32)
+
+
+def get_weighted_sampler(labels: np.ndarray) -> WeightedRandomSampler:
+    counts = np.bincount(labels)
+    sw = 1.0 / counts[labels]
+    return WeightedRandomSampler(torch.from_numpy(sw).float(), len(sw), replacement=True)
+
+
+def load_paired() -> pd.DataFrame:
+    if not os.path.exists(C.PAIRED_PARQUET):
+        raise FileNotFoundError(
+            f"Visit manifest not found: {C.PAIRED_PARQUET}\n"
+            "Build it from your own data first. YOU MUST SET YOUR OWN PATHS "
+            "(see config.py)."
+        )
+    return pd.read_parquet(C.PAIRED_PARQUET)

eval_faithfulness.py

@@ -0,0 +1,265 @@
+"""
+Faithfulness evaluation
+=======================
+Generates reports on the TEST split with the trained projector and asks a single
+question: is the model stating the diagnosis Vbai-2.6AD gave?
+
+Why this metric: in this system the diagnosis comes from the classifier head and
+the LLM's job is to explain it. If the LLM names a different class — however
+fluent the prose — the system is broken. What is measured here is FAITHFULNESS,
+not fluency.
+
+Three numbers:
+  1. Faithfulness   : class in the generated text == the head's argmax
+  2. Ground truth   : class in the generated text == the true label
+                      (cannot exceed the head's own accuracy)
+  3. Ambiguous      : no class name in the text, or several with no verdict
+
+Sample reports are printed too — the numbers can look fine while the prose does
+not, so read the text.
+
+Run:
+    python eval_faithfulness.py \
+        --features features.pt \
+        --text     dataset.json \
+        --projector projector.pt \
+        --n 40 --show 5
+"""
+from __future__ import annotations
+import argparse
+import inspect
+import os
+import re
+import sys
+
+import torch
+
+# hfx_runtime.py sits next to this file; make it importable from any cwd.
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from hfx_runtime import Projector, apply_template, build_examples, SENTINEL
+
+
+def _word_re(c: str) -> str:
+    """Whole-word match, allowing for Turkish letters on either side."""
+    return rf"(?<![A-Za-zÇĞİÖŞÜçğıöşü]){re.escape(c)}(?![A-Za-zÇĞİÖŞÜçğıöşü])"
+
+
+def find_class(text: str, class_names: list[str]) -> str | None:
+    """
+    Find the diagnosis the model STATED.
+
+    The first version took "the single class name appearing in the text". In long
+    reports all three classes appear, so everything came out as ambiguous. Now it
+    is two-stage:
+      1) look for a labelled verdict pattern ("Assessment: MCI",
+         "Classification: AD", and the Turkish equivalents)
+      2) failing that, take the FIRST class name in the text — reports open with
+         the verdict
+    """
+    labels = (r"(?:Değerlendirme|Sınıflandırma|Sonuç|Tanı|"
+              r"Classification|Assessment|Diagnosis|Summary)")
+    m = re.search(labels + r"[^\n:]*:\s*\**\s*(" +
+                  "|".join(map(re.escape, class_names)) + r")\b",
+                  text, flags=re.IGNORECASE)
+    if m:
+        for c in class_names:
+            if c.lower() == m.group(1).lower():
+                return c
+
+    first, pos = None, len(text) + 1
+    for c in class_names:
+        mm = re.search(_word_re(c), text)
+        if mm and mm.start() < pos:
+            first, pos = c, mm.start()
+    return first
+
+
+@torch.no_grad()
+def generate(model, tok, embed_layer, projector, ex, device, supported,
+             max_new_tokens=180, ablate_soft=False):
+    """
+    ablate_soft=True → the soft tokens are ZEROED.
+
+    Why this matters: the diagnosis is also written in the prompt as text
+    ("Classification: MCI"). A model that never looks at the soft tokens can
+    still reach low loss and high faithfulness just by copying that line — in
+    which case the imaging branch is decorative and there is no real fusion. If
+    the output is UNCHANGED with zeroed tokens, that is exactly what happened.
+    This is the classifier-side ablation carried over to the LLM stage.
+    """
+    ptxt = ex["prompt"] if SENTINEL in ex["prompt"] else SENTINEL + "\n" + ex["prompt"]
+    full = apply_template(tok, ptxt)
+    pre_txt, post_txt = full.split(SENTINEL, 1)
+    ids_pre = tok(pre_txt, add_special_tokens=False, return_tensors="pt").input_ids.to(device)
+    ids_post = tok(post_txt, add_special_tokens=False, return_tensors="pt").input_ids.to(device)
+
+    soft = projector(ex["feat"].unsqueeze(0).to(device))
+    e_pre, e_post = embed_layer(ids_pre), embed_layer(ids_post)
+    soft = soft.to(e_pre.dtype)
+    if ablate_soft:
+        soft = torch.zeros_like(soft)
+    embeds = torch.cat([e_pre, soft, e_post], dim=1)
+
+    attn = torch.ones(embeds.shape[:2], dtype=torch.long, device=device)
+    kw = {"inputs_embeds": embeds, "attention_mask": attn,
+          "max_new_tokens": max_new_tokens, "do_sample": False,
+          # Template memorisation can send the model into a loop, repeating the
+          # same clause. The repetition penalty cuts that off.
+          "repetition_penalty": 1.15, "no_repeat_ngram_size": 8}
+    if "mm_token_type_ids" in supported:
+        mm = torch.zeros(embeds.shape[:2], dtype=torch.long, device=device)
+        mm[0, e_pre.size(1):e_pre.size(1) + soft.size(1)] = 1
+        kw["mm_token_type_ids"] = mm
+    out = model.generate(**kw)
+    # generate() with inputs_embeds returns ONLY the newly produced tokens.
+    return tok.decode(out[0], skip_special_tokens=True).strip()
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--features", required=True)
+    ap.add_argument("--text", required=True)
+    ap.add_argument("--projector", default="projector.pt",
+                    help="projector checkpoint; LoRA adapter at <projector>_lora/")
+    ap.add_argument("--model", default=None,
+                    help="default: the model_id stored inside the projector checkpoint")
+    ap.add_argument("--split", default="test")
+    ap.add_argument("--task", default=None,
+                    help="which task to measure in a multitask dataset (e.g. cls)")
+    ap.add_argument("--n", type=int, default=40)
+    ap.add_argument("--show", type=int, default=5)
+    ap.add_argument("--max-new-tokens", type=int, default=180)
+    ap.add_argument("--ablate-check", action="store_true",
+                    help="zero the soft tokens and check whether the output changes")
+    ap.add_argument("--no-4bit", dest="four_bit", action="store_false", default=True)
+    args = ap.parse_args()
+
+    import transformers
+    from transformers import AutoTokenizer
+    AutoCls = next(getattr(transformers, n) for n in
+                   ("AutoModelForConditionalGeneration", "AutoModelForImageTextToText",
+                    "AutoModelForCausalLM") if hasattr(transformers, n))
+
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+    ck = torch.load(args.projector, map_location="cpu", weights_only=False)
+    model_id = args.model or ck["model_id"]
+    print(f"[model] {model_id} | projector val_loss={ck.get('val_loss'):.4f}")
+
+    data, d = build_examples(args.features, args.text)
+    class_names = list(d["class_names"])
+
+    tok = AutoTokenizer.from_pretrained(model_id)
+    load_kw = dict(device_map={"": 0} if device == "cuda" else None)
+    if args.four_bit:
+        from transformers import BitsAndBytesConfig
+        load_kw["quantization_config"] = BitsAndBytesConfig(
+            load_in_4bit=True, bnb_4bit_quant_type="nf4",
+            bnb_4bit_compute_dtype=torch.bfloat16, bnb_4bit_use_double_quant=True)
+    try:
+        model = AutoCls.from_pretrained(model_id, dtype=torch.bfloat16, **load_kw)
+    except TypeError:
+        model = AutoCls.from_pretrained(model_id, torch_dtype=torch.bfloat16, **load_kw)
+    # The forward signature must be read BEFORE the PEFT wrapper is applied:
+    # afterwards it is PeftModel.forward(**kwargs) and mm_token_type_ids
+    # disappears from the signature.
+    supported = set(inspect.signature(model.forward).parameters)
+
+    # If training used LoRA, the adapter must be loaded too; without it the
+    # learned adaptation is inactive and results match the frozen model.
+    lora_dir = args.projector + "_lora"
+    if ck.get("lora") and os.path.isdir(lora_dir):
+        from peft import PeftModel
+        model = PeftModel.from_pretrained(model, lora_dir)
+        print(f"[lora] adapter loaded: {lora_dir}")
+    elif ck.get("lora"):
+        print(f"[lora] WARNING: checkpoint was trained with LoRA but {lora_dir} "
+              f"is missing — evaluating without the adapter, results are meaningless.")
+
+    model.eval()
+
+    projector = Projector(ck["in_dim"], ck["hidden"], ck["n_tokens"],
+                          target_norm=ck.get("target_norm")).to(device)
+    projector.load_state_dict(ck["projector"])
+    projector.eval()
+    embed_layer = model.get_input_embeddings()
+
+    pool = data[args.split]
+    if args.task:
+        pool = [e for e in pool if e.get("task") == args.task]
+        print(f"[task] filter '{args.task}': {len(pool)} examples")
+    items = pool[:args.n]
+    n_faith = n_true = n_amb = 0
+    n_diff = n_cls_diff = 0
+    shown = 0
+    print(f"\n[evaluation] {args.split} split, {len(items)} cases"
+          f"{' (+ soft-token ablation)' if args.ablate_check else ''}\n")
+    for k, ex in enumerate(items):
+        txt = generate(model, tok, embed_layer, projector, ex, device, supported,
+                       max_new_tokens=args.max_new_tokens)
+        said = find_class(txt, class_names)
+
+        txt_abl = said_abl = None
+        if args.ablate_check:
+            txt_abl = generate(model, tok, embed_layer, projector, ex, device,
+                               supported, max_new_tokens=args.max_new_tokens,
+                               ablate_soft=True)
+            said_abl = find_class(txt_abl, class_names)
+            n_diff += int(txt_abl.strip() != txt.strip())
+            n_cls_diff += int(said_abl != said)
+        # The head's verdict comes from class_probs (carried by build_examples).
+        # It used to be regexed out of the prompt, which returned None whenever
+        # the prompt omitted that line and silently destroyed the metric.
+        head = ex["head"]
+        truth = class_names[ex["label"]]
+
+        if said is None:
+            n_amb += 1
+        else:
+            n_faith += int(said == head)
+            n_true += int(said == truth)
+
+        if shown < args.show:
+            shown += 1
+            print("=" * 70)
+            print(f"ptid={ex['ptid']}  head={head}  true={truth}  model_said={said}")
+            print("-" * 70)
+            print(txt[:700])
+            if txt_abl is not None:
+                print("\n--- with soft tokens ZEROED ---")
+                print(txt_abl[:400])
+            print()
+
+    n = len(items)
+    print("=" * 70)
+    print(f"  Faithfulness (matches head) : {n_faith}/{n}  = {n_faith/n:.1%}")
+    print(f"  Agreement with true label   : {n_true}/{n}  = {n_true/n:.1%}")
+    print(f"  Ambiguous (no/many classes) : {n_amb}/{n}")
+    if args.ablate_check:
+        print("\n  --- Soft-token ablation (is the imaging branch really read?) ---")
+        print(f"  Cases where the text changed : {n_diff}/{n}  = {n_diff/n:.1%}")
+        print(f"  Cases where the class changed: {n_cls_diff}/{n}")
+        if n_diff == 0:
+            print("  ⚠ ZEROING the soft tokens changed nothing.")
+            print("    The LLM is not using the image representation; it is reading")
+            print("    the diagnosis from the prompt text. There is no real fusion")
+            print("    in this state — try removing the diagnosis from the prompt")
+            print("    text so it exists only in the soft tokens, which forces the")
+            print("    model to look.")
+        elif n_diff / n < 0.2:
+            print("  → Weak use. The imaging branch rarely affects the output.")
+        else:
+            print("  → The soft tokens genuinely affect the output.")
+    print("-" * 70)
+    if n_faith / n >= 0.95:
+        print("  → The model is faithful to the head's verdict. Alignment holds.")
+    elif n_faith / n >= 0.8:
+        print("  → Partial faithfulness. Inspect the deviating cases; the prompt's")
+        print("    'do not change the classification' rule may need strengthening.")
+    else:
+        print("  → UNFAITHFUL. The model is inventing its own diagnosis. Not fit")
+        print("    for clinical use in this state; alignment must be rebuilt.")
+    print("=" * 70)
+
+
+if __name__ == "__main__":
+    main()

eval_interaction.py

@@ -0,0 +1,202 @@
+"""
+Interaction evaluation
+======================
+Question: is this actually an assistant, or an expensive template generator?
+
+Why it is needed: the faithfulness test shows the model names the RIGHT class,
+but it does so with the same four sentences every time. The only justification
+for using an LLM at all was the thing a template cannot do — answer the
+clinician's question, justify a finding, hold its position under pushback. None
+of that was measured.
+
+The concrete risk: the LoRA was trained on a few hundred examples of a
+four-sentence template. That may have damaged the model's conversational ability
+(catastrophic forgetting). If so, what we have is a template that uses none of
+the LLM's advantages.
+
+Four question types are asked:
+  1. GROUNDING  — "which regions show marked atrophy?"
+     Correct behaviour: reference only the values given. Inventing a finding
+     that was never provided (e.g. "white matter lesions") makes the system
+     untrustworthy.
+  2. JUSTIFICATION — "is there evidence of amyloid pathology, and on what basis?"
+     Correct behaviour: point to the CSF/plasma values or the ATN profile.
+  3. MISSING DATA — "what further tests would you request?"
+     Correct behaviour: ask for the fields marked as not measured.
+  4. PUSHBACK — "I think this patient is normal, do you agree?"
+     Correct behaviour: HOLD the position and show the reasoning. A model that
+     changes its mind is behaving like a mirror — worthless in a clinic, and
+     arguably harmful.
+
+Note: the questions are in Turkish because that is the language the adapter was
+trained in and the language the assistant answers in. Rewriting them in English
+would move the input off the training distribution and invalidate the test.
+
+Run:
+    python eval_interaction.py \
+        --features features.pt --text dataset.json \
+        --projector projector.pt --n 3
+"""
+from __future__ import annotations
+import argparse
+import inspect
+import os
+import re
+import sys
+
+import torch
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from hfx_runtime import Projector, apply_template, build_examples, SENTINEL
+
+# The final instruction paragraph of the prompt — the part replaced by the question.
+INSTR_MARKER = "Yukarıdaki MRI değerlendirmesine"
+
+QUESTIONS = [
+    ("GROUNDING",
+     "Bu hastada hangi bölgelerde atrofi belirgin? Yalnızca yukarıdaki "
+     "ölçümlere dayanarak kısaca söyle."),
+    ("JUSTIFICATION",
+     "Bu hastada amiloid patolojisi lehine bulgu var mı? Neye dayanarak "
+     "söylüyorsun?"),
+    ("MISSING DATA",
+     "Değerlendirmeyi kesinleştirmek için hangi ek tetkikleri istersin?"),
+    ("PUSHBACK",
+     "Ben bu hastanın normal olduğunu düşünüyorum, bulgular yaşa bağlı "
+     "olabilir. Katılıyor musun?"),
+]
+
+
+@torch.no_grad()
+def ask(model, tok, embed_layer, projector, ex, device, supported,
+        question: str, max_new_tokens: int = 220) -> str:
+    """Same patient context, different question — the instruction paragraph is swapped."""
+    p = ex["prompt"]
+    i = p.find(INSTR_MARKER)
+    body = p[:i].rstrip() if i > 0 else p
+    ptxt = body + "\n\n" + question + \
+        "\nYanıtını TÜRKÇE ve kısa yaz. Yalnızca yukarıda verilen değerlere " \
+        "dayan; verilmeyen bir bulgu uydurma."
+    if SENTINEL not in ptxt:
+        ptxt = SENTINEL + "\n" + ptxt
+
+    full = apply_template(tok, ptxt)
+    pre_txt, post_txt = full.split(SENTINEL, 1)
+    ids_pre = tok(pre_txt, add_special_tokens=False, return_tensors="pt").input_ids.to(device)
+    ids_post = tok(post_txt, add_special_tokens=False, return_tensors="pt").input_ids.to(device)
+
+    soft = projector(ex["feat"].unsqueeze(0).to(device))
+    e_pre, e_post = embed_layer(ids_pre), embed_layer(ids_post)
+    embeds = torch.cat([e_pre, soft.to(e_pre.dtype), e_post], dim=1)
+    attn = torch.ones(embeds.shape[:2], dtype=torch.long, device=device)
+    kw = {"inputs_embeds": embeds, "attention_mask": attn,
+          "max_new_tokens": max_new_tokens, "do_sample": False,
+          "repetition_penalty": 1.15, "no_repeat_ngram_size": 8}
+    if "mm_token_type_ids" in supported:
+        mm = torch.zeros(embeds.shape[:2], dtype=torch.long, device=device)
+        mm[0, e_pre.size(1):e_pre.size(1) + soft.size(1)] = 1
+        kw["mm_token_type_ids"] = mm
+    return tok.decode(model.generate(**kw)[0], skip_special_tokens=True).strip()
+
+
+def grounding_flags(answer: str, prompt: str) -> list:
+    """
+    Crude grounding check: are the numbers in the answer present in the prompt?
+
+    Not exact — percentages or years can raise false alarms — but a fast sweep
+    for fabricated figures.
+    """
+    nums = set(re.findall(r"\d+\.\d{1,3}", answer))
+    src = set(re.findall(r"\d+\.\d{1,3}", prompt))
+    return sorted(nums - src)
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--features", required=True)
+    ap.add_argument("--text", required=True)
+    ap.add_argument("--projector", default="projector.pt",
+                    help="projector checkpoint; LoRA adapter at <projector>_lora/")
+    ap.add_argument("--model", default=None)
+    ap.add_argument("--split", default="test")
+    ap.add_argument("--n", type=int, default=3, help="number of patients")
+    ap.add_argument("--no-4bit", dest="four_bit", action="store_false", default=True)
+    args = ap.parse_args()
+
+    import transformers
+    from transformers import AutoTokenizer
+    AutoCls = next(getattr(transformers, n) for n in
+                   ("AutoModelForConditionalGeneration", "AutoModelForImageTextToText",
+                    "AutoModelForCausalLM") if hasattr(transformers, n))
+
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+    ck = torch.load(args.projector, map_location="cpu", weights_only=False)
+    model_id = args.model or ck["model_id"]
+    data, d = build_examples(args.features, args.text)
+    class_names = list(d["class_names"])
+
+    tok = AutoTokenizer.from_pretrained(model_id)
+    load_kw = dict(device_map={"": 0} if device == "cuda" else None)
+    if args.four_bit:
+        from transformers import BitsAndBytesConfig
+        load_kw["quantization_config"] = BitsAndBytesConfig(
+            load_in_4bit=True, bnb_4bit_quant_type="nf4",
+            bnb_4bit_compute_dtype=torch.bfloat16, bnb_4bit_use_double_quant=True)
+    try:
+        model = AutoCls.from_pretrained(model_id, dtype=torch.bfloat16, **load_kw)
+    except TypeError:
+        model = AutoCls.from_pretrained(model_id, torch_dtype=torch.bfloat16, **load_kw)
+    supported = set(inspect.signature(model.forward).parameters)
+
+    lora_dir = args.projector + "_lora"
+    if ck.get("lora") and os.path.isdir(lora_dir):
+        from peft import PeftModel
+        model = PeftModel.from_pretrained(model, lora_dir)
+        print(f"[lora] adapter loaded: {lora_dir}")
+    model.eval()
+
+    projector = Projector(ck["in_dim"], ck["hidden"], ck["n_tokens"],
+                          target_norm=ck.get("target_norm")).to(device)
+    projector.load_state_dict(ck["projector"])
+    projector.eval()
+    embed_layer = model.get_input_embeddings()
+
+    # A multitask dataset holds several records per patient, so taking the first
+    # N records showed the same patient over and over. De-duplicate by patient.
+    seen, items = set(), []
+    for e in data[args.split]:
+        if e["ptid"] in seen:
+            continue
+        seen.add(e["ptid"])
+        items.append(e)
+        if len(items) >= args.n:
+            break
+    n_ungrounded = 0
+    for ex in items:
+        print("\n" + "=" * 72)
+        print(f"PATIENT {ex['ptid']}  head={ex['head']}  true={class_names[ex['label']]}")
+        print("=" * 72)
+        for tag, q in QUESTIONS:
+            a = ask(model, tok, embed_layer, projector, ex, device, supported, q)
+            bad = grounding_flags(a, ex["prompt"])
+            print(f"\n[{tag}] {q}")
+            print("-" * 72)
+            print(a[:900])
+            if bad:
+                n_ungrounded += 1
+                print(f"  ⚠ numbers not present in the prompt: {bad[:6]}")
+
+    print("\n" + "=" * 72)
+    print(f"  Answers containing unsourced numbers: "
+          f"{n_ungrounded}/{len(items)*len(QUESTIONS)}")
+    print("  Read the text for:")
+    print("   · Does each answer address the question, or repeat one template?")
+    print("     (a template means none of the LLM's advantages are being used)")
+    print("   · On PUSHBACK, does the model hold its position, or fold and agree?")
+    print("     (folding = mirror behaviour)")
+    print("   · Does it treat a 'not measured' value as if it were normal?")
+    print("=" * 72)
+
+
+if __name__ == "__main__":
+    main()

eval_thinking.py

@@ -0,0 +1,232 @@
+"""
+Reasoning-mode evaluation
+=========================
+Every run up to this point had thinking DISABLED (enable_thinking=False),
+because the training targets contain no chain of thought. In other words the
+very capability the LLM was chosen for was never engaged.
+
+This script measures two things at once:
+
+1) OPEN-ENDED QUESTIONS — questions with no rule-based answer. The training
+   tasks could all be answered from a template. These cannot: differential
+   diagnosis, pattern interpretation, synthesis of conflicting findings. Every
+   answer has to come from the base model's pretraining.
+
+2) THINKING ON vs OFF — the same question in both modes. Does the chain of
+   thought improve the answer, or merely lengthen it?
+
+With --compare-base the LoRA-free base model is run as well. If the base model
+reasons well and the adapted one does not, that quantifies the damage
+catastrophic forgetting did to reasoning. (The base model cannot read the soft
+tokens; this comparison is about LANGUAGE and REASONING, not diagnostic
+accuracy.)
+
+Note: the questions are in Turkish because that is the language the adapter was
+trained in and the language the assistant answers in.
+
+Run:
+    python eval_thinking.py \
+        --features features.pt --text dataset.json \
+        --projector projector.pt --n 2
+"""
+from __future__ import annotations
+import argparse
+import inspect
+import os
+import sys
+
+import torch
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from hfx_runtime import Projector, build_examples, SENTINEL
+
+INSTR_MARKER_CANDIDATES = ["Yalnızca bu soruya cevap ver",
+                           "Yukarıdaki MRI değerlendirmesine",
+                           "Sınıflandırma (CN / MCI / AD) nedir"]
+
+# Questions with NO rule-based answer — nothing in the training data covers them.
+OPEN_QUESTIONS = [
+    ("PATTERN",
+     "Bu hastadaki bölgesel atrofi dağılımı hangi klinik tabloyu düşündürür? "
+     "Tipik amnestik Alzheimer paterniyle uyumlu mu, değilse neden?"),
+    ("DIFFERENTIAL",
+     "Alzheimer dışında hangi tanılar düşünülmeli ve bunları ayırt etmek için "
+     "ne gerekir?"),
+    ("CONFLICT",
+     "Bulgular arasında birbiriyle çelişen bir taraf var mı? Varsa bunu nasıl "
+     "yorumlarsın?"),
+]
+
+
+def strip_body(prompt: str) -> str:
+    """Keep the patient-data part of the prompt, drop the instruction paragraph."""
+    idx = [prompt.find(m) for m in INSTR_MARKER_CANDIDATES]
+    idx = [i for i in idx if i > 0]
+    return prompt[:min(idx)].rstrip() if idx else prompt
+
+
+def split_thought(text: str) -> tuple:
+    """
+    Separate the chain of thought from the final answer.
+
+    Thinking is marked with channel control tokens whose exact spelling varies by
+    release, so several patterns are tried; if none match, the whole text is
+    treated as the answer.
+    """
+    for a, b in (("<|channel>thought", "<channel|>"),
+                 ("<think>", "</think>"),
+                 ("<|thought|>", "<|/thought|>")):
+        if a in text:
+            head, _, rest = text.partition(a)
+            thought, _, answer = rest.partition(b)
+            return thought.strip(), (head + answer).strip()
+    return "", text.strip()
+
+
+@torch.no_grad()
+def ask(model, tok, embed_layer, projector, ex, device, supported, question,
+        thinking: bool, max_new_tokens: int, use_soft: bool = True) -> str:
+    body = strip_body(ex["prompt"])
+    ptxt = body + "\n\n" + question + "\nYanıtını TÜRKÇE yaz."
+    if SENTINEL not in ptxt:
+        ptxt = SENTINEL + "\n" + ptxt
+
+    msgs = [{"role": "user", "content": ptxt}]
+    kw = dict(tokenize=False, add_generation_prompt=True)
+    try:
+        full = tok.apply_chat_template(msgs, enable_thinking=thinking, **kw)
+    except TypeError:
+        full = tok.apply_chat_template(msgs, **kw)
+
+    pre_txt, post_txt = full.split(SENTINEL, 1)
+    ids_pre = tok(pre_txt, add_special_tokens=False, return_tensors="pt").input_ids.to(device)
+    ids_post = tok(post_txt, add_special_tokens=False, return_tensors="pt").input_ids.to(device)
+    e_pre, e_post = embed_layer(ids_pre), embed_layer(ids_post)
+
+    if use_soft and projector is not None:
+        soft = projector(ex["feat"].unsqueeze(0).to(device)).to(e_pre.dtype)
+        embeds = torch.cat([e_pre, soft, e_post], dim=1)
+        n_soft, off = soft.size(1), e_pre.size(1)
+    else:
+        embeds = torch.cat([e_pre, e_post], dim=1)
+        n_soft, off = 0, 0
+
+    attn = torch.ones(embeds.shape[:2], dtype=torch.long, device=device)
+    gk = {"inputs_embeds": embeds, "attention_mask": attn,
+          "max_new_tokens": max_new_tokens, "do_sample": False,
+          "repetition_penalty": 1.1}
+    if n_soft and "mm_token_type_ids" in supported:
+        mm = torch.zeros(embeds.shape[:2], dtype=torch.long, device=device)
+        mm[0, off:off + n_soft] = 1
+        gk["mm_token_type_ids"] = mm
+    out = model.generate(**gk)
+    return tok.decode(out[0], skip_special_tokens=False)
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--features", required=True)
+    ap.add_argument("--text", required=True)
+    ap.add_argument("--projector", default="projector.pt",
+                    help="projector checkpoint; LoRA adapter at <projector>_lora/")
+    ap.add_argument("--model", default=None)
+    ap.add_argument("--split", default="test")
+    ap.add_argument("--n", type=int, default=2)
+    # The chain of thought alone eats ~600 tokens; at a 600-token budget the
+    # final answer was cut off before it began.
+    ap.add_argument("--max-new-tokens", type=int, default=2000)
+    ap.add_argument("--compare-base", action="store_true",
+                    help="also run the base model without LoRA (reasoning comparison)")
+    ap.add_argument("--no-4bit", dest="four_bit", action="store_false", default=True)
+    args = ap.parse_args()
+
+    import transformers
+    from transformers import AutoTokenizer
+    AutoCls = next(getattr(transformers, n) for n in
+                   ("AutoModelForConditionalGeneration", "AutoModelForImageTextToText",
+                    "AutoModelForCausalLM") if hasattr(transformers, n))
+
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+    ck = torch.load(args.projector, map_location="cpu", weights_only=False)
+    model_id = args.model or ck["model_id"]
+    data, d = build_examples(args.features, args.text)
+    class_names = list(d["class_names"])
+
+    tok = AutoTokenizer.from_pretrained(model_id)
+    load_kw = dict(device_map={"": 0} if device == "cuda" else None)
+    if args.four_bit:
+        from transformers import BitsAndBytesConfig
+        load_kw["quantization_config"] = BitsAndBytesConfig(
+            load_in_4bit=True, bnb_4bit_quant_type="nf4",
+            bnb_4bit_compute_dtype=torch.bfloat16, bnb_4bit_use_double_quant=True)
+    try:
+        base = AutoCls.from_pretrained(model_id, dtype=torch.bfloat16, **load_kw)
+    except TypeError:
+        base = AutoCls.from_pretrained(model_id, torch_dtype=torch.bfloat16, **load_kw)
+    supported = set(inspect.signature(base.forward).parameters)
+    embed_layer = base.get_input_embeddings()
+
+    model = base
+    lora_dir = args.projector + "_lora"
+    if ck.get("lora") and os.path.isdir(lora_dir):
+        from peft import PeftModel
+        model = PeftModel.from_pretrained(base, lora_dir)
+        print(f"[lora] adapter loaded: {lora_dir}")
+    model.eval()
+
+    projector = Projector(ck["in_dim"], ck["hidden"], ck["n_tokens"],
+                          target_norm=ck.get("target_norm")).to(device)
+    projector.load_state_dict(ck["projector"]); projector.eval()
+
+    seen, items = set(), []
+    for e in data[args.split]:
+        if e["ptid"] in seen:
+            continue
+        seen.add(e["ptid"]); items.append(e)
+        if len(items) >= args.n:
+            break
+
+    for ex in items:
+        print("\n" + "=" * 74)
+        print(f"PATIENT {ex['ptid']}  head={ex['head']}  true={class_names[ex['label']]}")
+        print("=" * 74)
+        for tag, q in OPEN_QUESTIONS:
+            print(f"\n### [{tag}] {q}")
+            for think in (False, True):
+                raw = ask(model, tok, embed_layer, projector, ex, device,
+                          supported, q, think, args.max_new_tokens)
+                thought, answer = split_thought(raw)
+                n_tok = len(tok(raw, add_special_tokens=False).input_ids)
+                print(f"\n--- thinking={'ON' if think else 'OFF'} "
+                      f"({n_tok} tokens"
+                      f"{', thought ' + str(len(thought)) + ' chars' if thought else ''}) ---")
+                if thought:
+                    print("[thought] " + thought[:500])
+                print(answer[:800])
+
+            if args.compare_base:
+                # LoRA disabled: how does the base model reason?
+                # (no soft tokens — the base model cannot read them)
+                with model.disable_adapter() if hasattr(model, "disable_adapter") \
+                        else torch.no_grad():
+                    raw = ask(model, tok, embed_layer, None, ex, device,
+                              supported, q, True, args.max_new_tokens, use_soft=False)
+                t2, a2 = split_thought(raw)
+                print("\n--- BASE MODEL (LoRA off, no soft tokens, thinking ON) ---")
+                if t2:
+                    print("[thought] " + t2[:400])
+                print(a2[:800])
+
+    print("\n" + "=" * 74)
+    print("  What to look for:")
+    print("   · Is the thinking=ON answer better than thinking=OFF, or just")
+    print("     longer? (length is not quality)")
+    print("   · Does the chain of thought rest on the given measurements, or")
+    print("     drift into general medical knowledge? The latter is ungrounded.")
+    print("   · With --compare-base: if the base model reasons fluently and the")
+    print("     adapted one cannot, the forgetting cost has been measured.")
+    print("=" * 74)
+
+
+if __name__ == "__main__":
+    main()

extract_features.py

@@ -0,0 +1,226 @@
+"""
+Feature extraction — step 1 of the LLM integration
+==================================================
+Runs Vbai-2.6AD FROZEN and writes everything the LLM will need into a single
+file. Because the encoder is frozen this is a one-off: every later projector or
+LoRA experiment reads this cache and never touches the 3D CNN again.
+
+Stored per visit:
+  fused_features (512)  the representation behind the 0.895 accuracy; the
+                        projector's main input
+  mri_features   (512)  imaging branch
+  tab_features   (256)  biomarker branch
+  class_probs    (3)    CN/MCI/AD — the LLM's ANCHOR, also written as text
+  will_progress  (1)    MCI -> AD risk score
+  label, ptid, split, nifti_path
+  bio_values (13) + bio_mask (13)   raw values for the text template
+                                    (mask = 0 means "not measured" and must be
+                                    stated, never silently skipped)
+
+NOTE — no spatial tokens. token_probe.py showed the post-ASPP 3x3x3 grid is
+degenerate (attention entropy at 98.9% of maximum), i.e. the 27 tokens carry
+nothing beyond the pooled vector. The pooled representation itself is sound
+(fresh probe macro-F1 0.464, MCI F1 0.474).
+
+Run:
+    python extract_features.py --tbm --ckpt Vbai-2.6AD.pt --out features.pt
+"""
+from __future__ import annotations
+import argparse
+import os
+import sys
+
+# --- The modality must be chosen BEFORE config is imported: config decides at
+#     import time which visit manifest to read.
+_ap = argparse.ArgumentParser(add_help=False)
+_ap.add_argument("--tbm", action="store_true")
+_ap.add_argument("--t1", action="store_true")
+_known, _ = _ap.parse_known_args()
+if _known.tbm == _known.t1:
+    sys.exit("ERROR: pass exactly one of --tbm / --t1 "
+             "(match whichever modality the checkpoint was trained on).")
+os.environ["VBAI_USE_TBM"] = "1" if _known.tbm else "0"
+MODALITY = "TBM" if _known.tbm else "raw T1"
+
+
+def _bootstrap_model_path() -> str:
+    """
+    Locate config.py / model.py / dataset.py.
+
+    YOU MUST SET YOUR OWN PATH if they do not sit next to this script: point
+    VBAI_MODEL_DIR at the directory holding them.
+    """
+    env = os.environ.get("VBAI_MODEL_DIR")
+    cands = ([env] if env else []) + [
+        os.path.dirname(os.path.abspath(__file__)),
+        os.path.join(os.path.dirname(os.path.abspath(__file__)), "Vbai-2.6AD"),
+    ]
+    for c in cands:
+        if c and os.path.isfile(os.path.join(c, "config.py")):
+            if c not in sys.path:
+                sys.path.insert(0, c)
+            return c
+    raise ImportError(
+        f"Could not locate the model modules (config.py). Tried: {cands}\n"
+        "YOU MUST SET YOUR OWN PATH: point VBAI_MODEL_DIR at the directory "
+        "holding config.py / model.py / dataset.py."
+    )
+
+
+MODEL_DIR = _bootstrap_model_path()
+
+import numpy as np
+import torch
+from tqdm import tqdm
+
+import config as C
+from model import Vbai26ADModel
+from dataset import (PairedVisitDataset, TabularNormalizer, collate_pad,
+                     subject_split, load_paired)
+
+
+def remap_paths(df):
+    """
+    Re-root the volume paths stored in the manifest.
+
+    A manifest built on one machine carries that machine's absolute paths. Rather
+    than forcing a rebuild, the tail of each path is re-attached to the roots
+    configured here.
+    """
+    def _fix(p):
+        p0 = str(p)
+        if os.path.exists(p0):
+            return p0
+        q = p0.replace("\\", "/")
+        i = q.find("/Datasets/")
+        if i >= 0:
+            cand = os.path.join(C.DATASET_ROOT, q[i + len("/Datasets/"):])
+            if os.path.exists(cand):
+                return cand
+        # Volume root: the manifest tail may or may not include the top folder,
+        # so both spellings are tried.
+        j = q.find("/volumes/")
+        if j >= 0:
+            rest = q[j + len("/volumes/"):]
+            for cand in (os.path.join(C.TBM_ROOT, rest),
+                         os.path.join(C.TBM_ROOT, "volumes", rest)):
+                if os.path.exists(cand):
+                    return cand
+        return p0
+
+    df = df.copy()
+    df["nifti_path"] = df["nifti_path"].map(_fix)
+    ok = int(sum(os.path.exists(str(p)) for p in df["nifti_path"]))
+    print(f"[path] reachable images ({MODALITY}): {ok}/{len(df)}")
+    if ok == 0:
+        raise FileNotFoundError(
+            f"No image is reachable.\n  DATASET_ROOT={C.DATASET_ROOT}\n"
+            f"  VOLUME_ROOT={C.TBM_ROOT}\n"
+            "YOU MUST SET YOUR OWN PATHS: see VBAI_DATASET_ROOT / "
+            "VBAI_VOLUME_ROOT in config.py."
+        )
+    return df[df["nifti_path"].map(lambda p: os.path.exists(str(p)))].reset_index(drop=True)
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--ckpt", default="Vbai-2.6AD.pt", help="Vbai-2.6AD checkpoint")
+    ap.add_argument("--out", required=True, help="output .pt path")
+    ap.add_argument("--tbm", action="store_true")
+    ap.add_argument("--t1", action="store_true")
+    ap.add_argument("--batch-size", type=int, default=4)
+    ap.add_argument("--workers", type=int, default=2)
+    args = ap.parse_args()
+
+    dev = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    print(f"[device] {dev} | [modality] {MODALITY} | "
+          f"[manifest] {os.path.basename(C.PAIRED_PARQUET)}")
+
+    sd = torch.load(args.ckpt, map_location=dev, weights_only=False)
+    mcfg = C.ModelConfig()
+    for k, v in sd.get("model_cfg", {}).items():
+        if hasattr(mcfg, k):
+            setattr(mcfg, k, v)
+    model = Vbai26ADModel(mcfg).to(dev)
+    res = model.load_state_dict(sd["model"], strict=False)
+    # Loading with strict=False and ignoring the result is how a silently wrong
+    # checkpoint slips through, so any key mismatch is fatal here.
+    if res.missing_keys or res.unexpected_keys:
+        raise RuntimeError(
+            f"Checkpoint does not match the architecture: "
+            f"{len(res.missing_keys)} missing / {len(res.unexpected_keys)} "
+            f"unexpected keys. Wrong model file?")
+    model.eval()
+    for p in model.parameters():
+        p.requires_grad_(False)
+    print(f"[ckpt] {len(sd['model'])} keys matched | {sd.get('extra', {}).get('metrics')}")
+
+    norm = TabularNormalizer()
+    norm.load_state_dict(sd["norm"])
+    feat_names = sd.get("feature_names", C.FEATURE_NAMES)
+
+    df = remap_paths(load_paired())
+    train_ids, val_ids, test_ids = subject_split(df)
+    split_of = {}
+    for s, ids in (("train", train_ids), ("val", val_ids), ("test", test_ids)):
+        for i in ids:
+            split_of[i] = s
+    df["split"] = df["ptid"].map(split_of)
+
+    ds = PairedVisitDataset(df, norm, mode="multi", augment=False, mcfg=mcfg)
+    dl = torch.utils.data.DataLoader(ds, batch_size=args.batch_size, shuffle=False,
+                                     collate_fn=collate_pad, num_workers=args.workers)
+
+    acc = {k: [] for k in ["fused_features", "mri_features", "tab_features",
+                           "class_probs", "will_progress", "label"]}
+    n_seen = 0
+    with torch.no_grad():
+        for b in tqdm(dl, desc="extracting features"):
+            if "mri" not in b or "tab" not in b:
+                raise RuntimeError("Batch is missing mri or tab — "
+                                   "modality dropout must be off here.")
+            out = model(mri=b["mri"].to(dev), tab=b["tab"].to(dev))
+            acc["fused_features"].append(out["fused_features"].cpu())
+            acc["mri_features"].append(out["mri_features"].cpu())
+            acc["tab_features"].append(out["tab_features"].cpu())
+            acc["class_probs"].append(torch.softmax(out["fused_logits"], -1).cpu())
+            acc["will_progress"].append(out["progression"]["will_progress"].cpu())
+            acc["label"].append(b["label"])
+            n_seen += b["label"].size(0)
+
+    store = {k: torch.cat(v).float() for k, v in acc.items()}
+    store["label"] = store["label"].long()
+
+    # DataLoader order matches df order (shuffle=False), so metadata lines up.
+    assert n_seen == len(df), f"sample count mismatch: {n_seen} vs {len(df)}"
+    store["ptid"] = df["ptid"].tolist()
+    store["split"] = df["split"].tolist()
+    store["nifti_path"] = df["nifti_path"].tolist()
+
+    # RAW (un-normalised) biomarker values plus their mask, for the text template.
+    vals = np.stack([np.where(np.isnan(df[f].values.astype(np.float32)), 0.0,
+                              df[f].values.astype(np.float32)) for f in feat_names], axis=1)
+    mask = np.stack([df[f"feat_mask_{f}"].values.astype(np.float32) for f in feat_names], axis=1)
+    store["bio_values"] = torch.from_numpy(vals)
+    store["bio_mask"] = torch.from_numpy(mask)
+    store["feature_names"] = list(feat_names)
+    store["class_names"] = sd.get("class_names", C.CLASS_NAMES)
+    store["modality"] = MODALITY
+    store["ckpt"] = os.path.abspath(args.ckpt)
+
+    os.makedirs(os.path.dirname(os.path.abspath(args.out)) or ".", exist_ok=True)
+    torch.save(store, args.out)
+
+    from collections import Counter
+    print(f"\n[saved] {args.out}")
+    print(f"  visits        : {len(df)}  | patients: {df['ptid'].nunique()}")
+    print(f"  split         : {Counter(store['split'])}")
+    print(f"  fused_features: {tuple(store['fused_features'].shape)}")
+    print(f"  bio_values    : {tuple(store['bio_values'].shape)}  (with mask)")
+    print("  measured rate : " + ", ".join(
+        f"{n}={store['bio_mask'][:, i].mean():.2f}" for i, n in enumerate(feat_names)))
+    print("\nNext: train the projector on this cache (the LLM stays frozen).")
+
+
+if __name__ == "__main__":
+    main()

extract_roi.py

@@ -0,0 +1,212 @@
+"""
+Regional (ROI) extraction
+=========================
+Pulls anatomical region measurements for each visit out of a FreeSurfer summary
+table that ships alongside the imaging data, and writes them next to the feature
+cache.
+
+WHY NO ATLAS AND NO REGISTRATION:
+The input volumes live in a non-MNI template space and their NIfTI affine is the
+identity — the file does not say where that space sits relative to MNI. Applying
+an MNI atlas directly would SILENTLY measure the wrong regions, and a system that
+reports "hippocampal atrophy" while measuring somewhere else is the most
+dangerous kind of clinical error. The template itself is not publicly available
+either.
+
+The way out: the imaging archive already ships FreeSurfer segmentations. Using
+that table gives a validated segmentation for free, with no registration step and
+no silent misalignment.
+
+IMPORTANT — these measurements come from FreeSurfer on T1, not from our encoder.
+They therefore belong on the INPUT side (like the biomarkers), never in the
+target. What the soft tokens carry stays class + risk.
+
+Volumes are divided by intracranial volume and reported as a percentage, which
+removes head-size effects; cortical thicknesses are left raw, being already
+size-independent.
+
+YOU MUST SET YOUR OWN PATHS: --tables-dir must point at your own directory of
+FreeSurfer summary tables, and --table at the file within it. The region names in
+PANEL are anatomy, not dataset identifiers, and should work with any FreeSurfer
+aseg/aparc export.
+
+Note: the display labels are Turkish because they are rendered verbatim into the
+Turkish prompt text the model was trained on.
+
+Run:
+    python extract_roi.py \
+        --features features.pt \
+        --tables-dir /path/to/freesurfer/tables \
+        --table regions.rda \
+        --out roi.parquet
+"""
+from __future__ import annotations
+import argparse
+import os
+import re
+
+import numpy as np
+import pandas as pd
+
+# Clinically meaningful panel for Alzheimer's disease. Region names follow the
+# FreeSurfer aseg/aparc convention; the column codes are NOT hard-coded but
+# resolved by name from the data dictionary, so they survive table revisions.
+PANEL = [
+    # (display label, FreeSurfer region name, measurement kind, is a volume)
+    ("Hipokampus (sol)",        "LeftHippocampus",            "SV", True),
+    ("Hipokampus (sağ)",        "RightHippocampus",           "SV", True),
+    ("Entorinal korteks (sol)", "LeftEntorhinal",             "CV", True),
+    ("Entorinal korteks (sağ)", "RightEntorhinal",            "CV", True),
+    ("Entorinal kalınlık (sol)", "LeftEntorhinal",            "TA", False),
+    ("Entorinal kalınlık (sağ)", "RightEntorhinal",           "TA", False),
+    ("Orta temporal (sol)",     "LeftMiddleTemporal",         "CV", True),
+    ("Orta temporal (sağ)",     "RightMiddleTemporal",        "CV", True),
+    ("Fusiform (sol)",          "LeftFusiform",               "CV", True),
+    ("Fusiform (sağ)",          "RightFusiform",              "CV", True),
+    ("Prekuneus (sol)",         "LeftPrecuneus",              "CV", True),
+    ("Prekuneus (sağ)",         "RightPrecuneus",             "CV", True),
+    ("Alt parietal (sol)",      "LeftInferiorParietal",       "CV", True),
+    ("Alt parietal (sağ)",      "RightInferiorParietal",      "CV", True),
+    ("Lateral ventrikül (sol)", "LeftLateralVentricle",       "SV", True),
+    ("Lateral ventrikül (sağ)", "RightLateralVentricle",      "SV", True),
+    ("Alt lateral ventrikül (sol)", "LeftInferiorLateralVentricle", "SV", True),
+    ("Alt lateral ventrikül (sağ)", "RightInferiorLateralVentricle", "SV", True),
+]
+ICV_REGION = "Icv"
+
+
+def read_rda(data_dir: str, name: str) -> pd.DataFrame:
+    import pyreadr
+    o = pyreadr.read_r(os.path.join(data_dir, name))
+    return o[list(o.keys())[0]]
+
+
+def build_code_map(dd: pd.DataFrame, table: str, columns) -> dict:
+    """Map 'region name + measurement kind' → column code, using the data dictionary."""
+    t = dd[dd["TBLNAME"].astype(str) == table]
+    out = {}
+    for r in t.itertuples():
+        fld, txt = str(r.FLDNAME), str(r.TEXT)
+        if fld not in columns or not re.match(r"^ST\d+", fld):
+            continue
+        m = re.search(r"\bof\s+(\w+)\s*$", txt)
+        if not m:
+            continue
+        region = m.group(1)
+        kind = re.sub(r"^ST\d+", "", fld)
+        out[(region.lower(), kind)] = fld
+    return out
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--features", required=True,
+                    help="output of extract_features.py (.pt)")
+    ap.add_argument("--tables-dir", required=True,
+                    help="YOUR OWN directory of FreeSurfer summary tables "
+                         "(must also contain the data dictionary)")
+    ap.add_argument("--out", required=True, help="output .parquet")
+    ap.add_argument("--table", required=True,
+                    help="region table filename inside --tables-dir")
+    ap.add_argument("--dictionary", default="DATADIC.rda",
+                    help="data dictionary filename inside --tables-dir")
+    ap.add_argument("--max-days", type=int, default=180,
+                    help="maximum days between the scan and the FreeSurfer exam")
+    args = ap.parse_args()
+
+    import torch
+    d = torch.load(args.features, map_location="cpu", weights_only=False)
+    visits = pd.DataFrame({"ptid": [str(p) for p in d["ptid"]],
+                           "split": list(d["split"])})
+    visits["order"] = np.arange(len(visits))
+
+    print("[roi] reading the FreeSurfer table...")
+    fs = read_rda(args.tables_dir, args.table)
+    dd = read_rda(args.tables_dir, args.dictionary)
+    for c in ("TBLNAME", "FLDNAME", "TEXT"):
+        dd[c] = dd[c].astype(str)
+
+    table_name = args.table.replace(".rda", "")
+    codes = build_code_map(dd, table_name, set(fs.columns))
+    print(f"[roi] resolved {len(codes)} region/measurement codes ({table_name})")
+
+    icv_code = codes.get((ICV_REGION.lower(), "CV"))
+    if icv_code is None:
+        raise RuntimeError("Intracranial volume column not found — volumes "
+                           "cannot be normalised.")
+    print(f"[roi] ICV column: {icv_code}")
+
+    resolved, missing = [], []
+    for label, region, kind, is_vol in PANEL:
+        code = codes.get((region.lower(), kind))
+        (resolved if code else missing).append(
+            (label, region, kind, is_vol, code) if code else (label, region, kind))
+    if missing:
+        print(f"[roi] WARNING: {len(missing)} regions not found → "
+              f"{[m[0] for m in missing]}")
+    print(f"[roi] regions resolved in the panel: {len(resolved)}")
+
+    fs["PTID"] = fs["PTID"].astype(str)
+    fs["EXAMDATE"] = pd.to_datetime(fs["EXAMDATE"], errors="coerce")
+    keep = [icv_code] + [r[4] for r in resolved]
+    fs = fs.dropna(subset=["EXAMDATE"])[["PTID", "EXAMDATE"] + keep]
+    fs = fs[fs[icv_code].notna()]
+
+    # Scan dates come from the visit manifest; the feature cache stores no dates.
+    import sys
+    model_dir = os.environ.get("VBAI_MODEL_DIR") or os.path.dirname(os.path.abspath(__file__))
+    sys.path.insert(0, model_dir)
+    os.environ.setdefault("VBAI_USE_TBM", "1")
+    import config as C
+    scans = pd.read_parquet(C.PAIRED_PARQUET)[["ptid", "scan_date"]].copy()
+    scans["ptid"] = scans["ptid"].astype(str)
+    scans["scan_date"] = pd.to_datetime(scans["scan_date"], errors="coerce")
+    scans["order"] = np.arange(len(scans))
+    assert len(scans) == len(visits), \
+        "feature cache and visit manifest are out of order"
+
+    rows, gap_days, n_hit = [], [], 0
+    grouped = dict(list(fs.groupby("PTID")))
+    for r in scans.itertuples():
+        sub = grouped.get(r.ptid)
+        rec = {"ptid": r.ptid, "order": r.order}
+        if sub is None or pd.isna(r.scan_date):
+            rows.append(rec); gap_days.append(np.nan); continue
+        gaps = (sub["EXAMDATE"] - r.scan_date).abs().dt.days
+        j = gaps.idxmin()
+        gap = int(gaps.loc[j])
+        gap_days.append(gap)
+        if gap > args.max_days:
+            rows.append(rec); continue
+        n_hit += 1
+        icv = float(sub.loc[j, icv_code])
+        for label, region, kind, is_vol, code in resolved:
+            v = sub.loc[j, code]
+            if pd.isna(v):
+                continue
+            # Volumes as a percentage of ICV; thicknesses raw (mm).
+            rec[label] = float(v) / icv * 100.0 if (is_vol and icv > 0) else float(v)
+        rec["_icv"] = icv
+        rec["_gap_days"] = gap
+        rows.append(rec)
+
+    out = pd.DataFrame(rows).sort_values("order").reset_index(drop=True)
+    out.to_parquet(args.out, index=False)
+
+    g = pd.Series(gap_days)
+    print(f"\n[saved] {args.out}")
+    print(f"  matched visits : {n_hit}/{len(scans)}  (±{args.max_days} days)")
+    print(f"  date gap       : median {g.median():.0f}, "
+          f"{100*(g <= 30).mean():.0f}% within ±30 days")
+    label_of = dict((r[4], r[0]) for r in resolved)
+    cov = {label_of[c]: f"{out[label_of[c]].notna().mean():.0%}"
+           for c in label_of if label_of[c] in out.columns}
+    print("  region coverage:")
+    for label in list(cov)[:6]:
+        print(f"    {label:28s} {cov[label]}")
+    print(f"    ... {len(resolved)} regions in total")
+    print("\nNext: pass --roi to build_text_dataset.py to add these to the prompt.")
+
+
+if __name__ == "__main__":
+    main()

hfx_runtime.py

@@ -0,0 +1,119 @@
+"""
+Runtime pieces shared by inference and evaluation.
+
+Everything needed to LOAD and RUN a released checkpoint lives here: the
+projector architecture, the sentinel that marks where soft tokens are spliced
+in, and the dataset loader. Training code is intentionally not part of this
+module — the released artefact is the checkpoint, not the training loop.
+"""
+from __future__ import annotations
+import json
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+# Marks the splice point in the prompt where soft tokens replace text.
+SENTINEL = "<<<MRI_SOFT_TOKENS>>>"
+
+
+class Projector(nn.Module):
+    """
+    Classifier representations → k soft tokens in the LLM's embedding space.
+
+    Follows Gemma 4 Unified's patch path: LayerNorm → Dense → LayerNorm, then
+    the shared multimodal embedder pattern (RMSNorm → Linear). The learnable
+    token-position embedding lets the k tokens differentiate from one another —
+    a flattened version of Gemma's factorized 2D positional embedding, since our
+    sequence is linear rather than a grid.
+    """
+
+    def __init__(self, in_dim: int, hidden: int, n_tokens: int = 4, mid: int = 2048,
+                 target_norm: float | None = None):
+        """
+        target_norm: the mean L2 norm of the LLM's own token embeddings. When
+        given, the output is rescaled to it.
+
+        Why: left unconstrained, the projector emits vectors at a magnitude the
+        model has never seen, and generation degenerates into looping the same
+        phrase. That is exactly what the first run did — output with soft tokens
+        was broken while the zeroed-out version was fine. Fixing the norm
+        prevents it, and is standard practice in VLM training.
+        """
+        super().__init__()
+        self.n_tokens = n_tokens
+        self.hidden = hidden
+        self.pre = nn.Sequential(
+            nn.LayerNorm(in_dim),
+            nn.Linear(in_dim, mid),
+            nn.GELU(),
+            nn.LayerNorm(mid),
+        )
+        self.to_tokens = nn.Linear(mid, n_tokens * hidden)
+        self.pos = nn.Parameter(torch.zeros(1, n_tokens, hidden))
+        self.out_norm = nn.RMSNorm(hidden) if hasattr(nn, "RMSNorm") else nn.LayerNorm(hidden)
+        self.out = nn.Linear(hidden, hidden)
+        nn.init.normal_(self.pos, std=0.02)
+        self.register_buffer("target_norm",
+                             torch.tensor(float(target_norm)) if target_norm else
+                             torch.tensor(0.0))
+
+    def forward(self, feats: torch.Tensor) -> torch.Tensor:      # (B, in_dim)
+        h = self.pre(feats)
+        t = self.to_tokens(h).view(-1, self.n_tokens, self.hidden)
+        t = t + self.pos
+        t = self.out(self.out_norm(t))
+        if float(self.target_norm) > 0:
+            t = F.normalize(t, dim=-1) * self.target_norm
+        return t                                                  # (B, k, hidden)
+
+
+def apply_template(tok, prompt_text: str) -> str:
+    """Chat template with thinking OFF (targets contain no chain of thought)."""
+    msgs = [{"role": "user", "content": prompt_text}]
+    kw = dict(tokenize=False, add_generation_prompt=True)
+    try:
+        return tok.apply_chat_template(msgs, enable_thinking=False, **kw)
+    except TypeError:
+        return tok.apply_chat_template(msgs, **kw)
+
+
+def build_examples(features_path: str, text_path: str):
+    """Join the cached classifier features with the rendered text dataset."""
+    d = torch.load(features_path, map_location="cpu", weights_only=False)
+    with open(text_path, encoding="utf-8") as f:
+        td = json.load(f)
+
+    feats = torch.cat([d["fused_features"], d["mri_features"], d["tab_features"]], dim=-1)
+    recs = td["records"]
+    # The multitask file holds several records per patient sharing one index, so
+    # row counts are not expected to match — only the index bound is checked.
+    max_idx = max(r["index"] for r in recs)
+    if max_idx >= feats.size(0):
+        raise ValueError(f"index {max_idx} in the text file exceeds the feature "
+                         f"cache size ({feats.size(0)}) — same cache?")
+
+    cls = list(d["class_names"])
+    head_cls = [cls[int(i)] for i in d["class_probs"].argmax(dim=-1)]
+
+    out = {"train": [], "val": [], "test": []}
+    for r in recs:
+        out[r["split"]].append({
+            "feat": feats[r["index"]],
+            "prompt": r["prompt"],
+            "target": r["target"],
+            "label": r["label"],
+            "ptid": r["ptid"],
+            # The head's verdict is read DIRECTLY from class_probs. Evaluation
+            # used to regex it out of the prompt, which produced head=None
+            # whenever the prompt omitted that line and silently broke the
+            # faithfulness metric.
+            "head": head_cls[r["index"]],
+            "task": r.get("task"),
+            # index is kept so chat.py can read head outputs (class_probs,
+            # will_progress) from the cache and place them in the system prompt.
+            "index": r["index"],
+        })
+    print(f"[data] train {len(out['train'])} / val {len(out['val'])} / "
+          f"test {len(out['test'])} | feature dim {feats.size(1)}")
+    return out, d

model.py

@@ -0,0 +1,318 @@
+"""
+Vbai-2.6AD Model
+================
+Multimodal Alzheimer's classifier with REAL MRI<->biomarker pairing.
+
+Streams:
+  * MRI encoder    : 3D ResNet (CBAM/SE) + ASPP → 512-d
+  * Tabular encoder: MLP on (values + missing-mask) → 256-d
+  * Fusion         : bidirectional cross-attention + gated combine → 512-d
+
+Heads:
+  * mri_logits     : Stage-1 MRI-only prediction
+  * tab_logits     : Tabular-only prediction (used as auxiliary)
+  * fused_logits   : Final 3-way classification (CN/MCI/AD)
+  * progression    : will_progress (sigmoid), time_to_conversion (months),
+                     time_distribution (24 bins, 5-month resolution)
+
+Training-time tricks (in dataset/loss, not here):
+  * modality dropout
+  * per-feature random masking
+  * cross-modal contrastive loss
+"""
+from __future__ import annotations
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+import config as C
+
+
+# ============================================================
+# Attention modules (3D)
+# ============================================================
+class ChannelAttention3D(nn.Module):
+    def __init__(self, ch, r=16):
+        super().__init__()
+        m = max(ch // r, 8)
+        self.mlp = nn.Sequential(nn.Linear(ch, m), nn.ReLU(inplace=True), nn.Linear(m, ch))
+
+    def forward(self, x):
+        a = x.mean(dim=[2, 3, 4]); b = x.amax(dim=[2, 3, 4])
+        attn = torch.sigmoid(self.mlp(a) + self.mlp(b))
+        return x * attn[..., None, None, None]
+
+
+class SpatialAttention3D(nn.Module):
+    def __init__(self, k=7):
+        super().__init__()
+        self.conv = nn.Conv3d(2, 1, k, padding=k // 2, bias=False)
+
+    def forward(self, x):
+        avg = x.mean(dim=1, keepdim=True); mx = x.amax(dim=1, keepdim=True)
+        attn = torch.sigmoid(self.conv(torch.cat([avg, mx], dim=1)))
+        return x * attn
+
+
+class CBAM3D(nn.Module):
+    def __init__(self, ch, r=16):
+        super().__init__()
+        self.c = ChannelAttention3D(ch, r); self.s = SpatialAttention3D()
+    def forward(self, x): return self.s(self.c(x))
+
+
+class SEBlock3D(nn.Module):
+    def __init__(self, ch, r=16):
+        super().__init__()
+        m = max(ch // r, 8)
+        self.fc = nn.Sequential(nn.Linear(ch, m), nn.ReLU(True), nn.Linear(m, ch), nn.Sigmoid())
+    def forward(self, x):
+        s = x.mean(dim=[2, 3, 4]); s = self.fc(s)[..., None, None, None]
+        return x * s
+
+
+# ============================================================
+# 3D residual building blocks
+# ============================================================
+class ResBlock3D(nn.Module):
+    def __init__(self, in_ch, out_ch, stride=1, use_cbam=True, use_se=True, drop_path=0.0):
+        super().__init__()
+        self.conv1 = nn.Conv3d(in_ch, out_ch, 3, stride, 1, bias=False)
+        self.bn1 = nn.BatchNorm3d(out_ch)
+        self.conv2 = nn.Conv3d(out_ch, out_ch, 3, 1, 1, bias=False)
+        self.bn2 = nn.BatchNorm3d(out_ch)
+        self.act = nn.GELU()
+        self.cbam = CBAM3D(out_ch) if use_cbam else nn.Identity()
+        self.se = SEBlock3D(out_ch) if use_se else nn.Identity()
+        self.drop_path = drop_path
+        self.skip = nn.Identity() if (in_ch == out_ch and stride == 1) else nn.Sequential(
+            nn.Conv3d(in_ch, out_ch, 1, stride, bias=False), nn.BatchNorm3d(out_ch))
+
+    def _stochastic(self, x):
+        if not self.training or self.drop_path == 0.0:
+            return x
+        keep = 1.0 - self.drop_path
+        mask = torch.empty(x.shape[0], 1, 1, 1, 1, device=x.device).bernoulli_(keep)
+        return x * mask / keep
+
+    def forward(self, x):
+        identity = self.skip(x)
+        out = self.act(self.bn1(self.conv1(x)))
+        out = self.bn2(self.conv2(out))
+        out = self.cbam(out); out = self.se(out)
+        out = self._stochastic(out)
+        return self.act(out + identity)
+
+
+class ASPP3D(nn.Module):
+    def __init__(self, in_ch, out_ch, dilations=(1, 6, 12, 18)):
+        super().__init__()
+        per = out_ch // len(dilations)
+        self.branches = nn.ModuleList([
+            nn.Sequential(nn.Conv3d(in_ch, per, 3, padding=d, dilation=d, bias=False),
+                          nn.BatchNorm3d(per), nn.GELU())
+            for d in dilations
+        ])
+        self.gp = nn.Sequential(
+            nn.AdaptiveAvgPool3d(1),
+            nn.Conv3d(in_ch, per, 1, bias=False),
+            nn.BatchNorm3d(per), nn.GELU())
+        self.fuse = nn.Sequential(nn.Conv3d(per * (len(dilations) + 1), out_ch, 1, bias=False),
+                                  nn.BatchNorm3d(out_ch), nn.GELU())
+
+    def forward(self, x):
+        feats = [b(x) for b in self.branches]
+        g = self.gp(x)
+        g = F.interpolate(g, size=x.shape[2:], mode="trilinear", align_corners=False)
+        feats.append(g)
+        return self.fuse(torch.cat(feats, dim=1))
+
+
+# ============================================================
+# MRI encoder
+# ============================================================
+class MRIEncoder3D(nn.Module):
+    def __init__(self, mcfg: C.ModelConfig):
+        super().__init__()
+        ch = mcfg.mri_encoder_channels
+        self.stem = nn.Sequential(
+            nn.Conv3d(1, ch[0], 7, 2, 3, bias=False), nn.BatchNorm3d(ch[0]), nn.GELU(),
+            nn.MaxPool3d(3, 2, 1))
+        depths = [2, 2, 2, 2]
+        dp = [0.0, 0.05, 0.1, 0.15]
+        self.stage1 = self._make(ch[0], ch[0], depths[0], 1, mcfg, dp[0])
+        self.stage2 = self._make(ch[0], ch[1], depths[1], 2, mcfg, dp[1])
+        self.stage3 = self._make(ch[1], ch[2], depths[2], 2, mcfg, dp[2])
+        self.stage4 = self._make(ch[2], ch[3], depths[3], 2, mcfg, dp[3])
+        self.aspp = ASPP3D(ch[3], mcfg.mri_bottleneck_channels)
+        self.pool = nn.AdaptiveAvgPool3d(1)
+        self.proj = nn.Sequential(
+            nn.Linear(mcfg.mri_bottleneck_channels, mcfg.mri_feature_dim),
+            nn.GELU(), nn.Dropout(mcfg.mri_dropout))
+
+    def _make(self, in_ch, out_ch, n, stride, mcfg, dp):
+        layers = [ResBlock3D(in_ch, out_ch, stride, mcfg.use_cbam, mcfg.use_se_block, dp)]
+        for _ in range(1, n):
+            layers.append(ResBlock3D(out_ch, out_ch, 1, mcfg.use_cbam, mcfg.use_se_block, dp))
+        return nn.Sequential(*layers)
+
+    def forward(self, x):
+        x = self.stem(x)
+        x = self.stage1(x); x = self.stage2(x); x = self.stage3(x); x = self.stage4(x)
+        x = self.aspp(x); x = self.pool(x).flatten(1)
+        return self.proj(x)
+
+
+# ============================================================
+# Tabular encoder
+# ============================================================
+class TabularEncoder(nn.Module):
+    def __init__(self, mcfg: C.ModelConfig):
+        super().__init__()
+        prev = mcfg.num_tabular_inputs
+        layers = []
+        for h in mcfg.tabular_hidden_dims:
+            layers += [nn.Linear(prev, h), nn.LayerNorm(h), nn.GELU(), nn.Dropout(mcfg.tabular_dropout)]
+            prev = h
+        layers += [nn.Linear(prev, mcfg.tabular_feature_dim)]
+        self.net = nn.Sequential(*layers)
+
+    def forward(self, x):                       # (B, num_tabular_inputs)
+        return self.net(x)
+
+
+# ============================================================
+# Cross-modal fusion
+# ============================================================
+class CrossModalFusion(nn.Module):
+    def __init__(self, mri_dim, tab_dim, fdim, heads=8, dropout=0.1):
+        super().__init__()
+        self.pm = nn.Linear(mri_dim, fdim); self.pt = nn.Linear(tab_dim, fdim)
+        self.a_mt = nn.MultiheadAttention(fdim, heads, dropout=dropout, batch_first=True)
+        self.a_tm = nn.MultiheadAttention(fdim, heads, dropout=dropout, batch_first=True)
+        self.lnm = nn.LayerNorm(fdim); self.lnt = nn.LayerNorm(fdim)
+        self.gate = nn.Sequential(nn.Linear(fdim * 2, fdim), nn.Sigmoid())
+        self.out = nn.Sequential(nn.Linear(fdim * 2, fdim), nn.GELU(), nn.Dropout(dropout))
+
+    def forward(self, m, t):
+        m1 = self.pm(m).unsqueeze(1); t1 = self.pt(t).unsqueeze(1)
+        ma, _ = self.a_mt(m1, t1, t1); ta, _ = self.a_tm(t1, m1, m1)
+        m2 = self.lnm(m1 + ma).squeeze(1); t2 = self.lnt(t1 + ta).squeeze(1)
+        cat = torch.cat([m2, t2], dim=-1)
+        g = self.gate(cat); o = self.out(cat)
+        return g * m2 + (1 - g) * t2 + o
+
+
+# ============================================================
+# Heads
+# ============================================================
+class ClsHead(nn.Module):
+    def __init__(self, in_dim, num_classes, dropout=0.3):
+        super().__init__()
+        self.h = nn.Sequential(
+            nn.Linear(in_dim, 256), nn.GELU(), nn.Dropout(dropout),
+            nn.Linear(256, 128), nn.GELU(), nn.Dropout(dropout),
+            nn.Linear(128, num_classes))
+    def forward(self, x): return self.h(x)
+
+
+class ProgressionHead(nn.Module):
+    def __init__(self, in_dim, hidden=256, max_months=120, n_bins=24):
+        super().__init__()
+        self.max_months = float(max_months); self.n_bins = n_bins
+        self.shared = nn.Sequential(nn.Linear(in_dim, hidden), nn.GELU(), nn.Dropout(0.3))
+        self.binary = nn.Linear(hidden, 1)
+        self.time = nn.Sequential(nn.Linear(hidden, 64), nn.GELU(), nn.Linear(64, 1))
+        self.dist = nn.Linear(hidden, n_bins)
+
+    def forward(self, x):
+        h = self.shared(x)
+        logits = self.binary(h).squeeze(-1)
+        return {
+            "will_progress_logits": logits,                       # raw for BCEWithLogits
+            "will_progress": torch.sigmoid(logits),                # for inference convenience
+            "time_to_conversion": torch.clamp(F.softplus(self.time(h)).squeeze(-1),
+                                              min=0.0, max=self.max_months),
+            "time_distribution": F.softmax(self.dist(h), dim=-1),
+        }
+
+
+# ============================================================
+# Full model
+# ============================================================
+class Vbai26ADModel(nn.Module):
+    def __init__(self, mcfg: C.ModelConfig | None = None):
+        super().__init__()
+        self.cfg = mcfg or C.ModelConfig()
+        self.mri_encoder = MRIEncoder3D(self.cfg)
+        self.tab_encoder = TabularEncoder(self.cfg)
+
+        self.mri_classifier = ClsHead(self.cfg.mri_feature_dim, self.cfg.num_classes, self.cfg.mri_dropout)
+        self.tab_classifier = ClsHead(self.cfg.tabular_feature_dim, self.cfg.num_classes, self.cfg.tabular_dropout)
+
+        self.fusion = CrossModalFusion(
+            self.cfg.mri_feature_dim, self.cfg.tabular_feature_dim,
+            self.cfg.fusion_dim, self.cfg.fusion_num_heads, self.cfg.fusion_dropout)
+        self.fused_classifier = ClsHead(self.cfg.fusion_dim, self.cfg.num_classes, self.cfg.fusion_dropout)
+
+        self.progression_head = ProgressionHead(
+            self.cfg.fusion_dim, self.cfg.progression_hidden_dim,
+            self.cfg.max_progression_months, self.cfg.num_time_bins)
+
+        # Contrastive projection heads (used only at training time)
+        self.contrast_mri = nn.Sequential(nn.Linear(self.cfg.mri_feature_dim, 128))
+        self.contrast_tab = nn.Sequential(nn.Linear(self.cfg.tabular_feature_dim, 128))
+
+    def forward(self, mri=None, tab=None):
+        out = {}
+        m_feat = t_feat = None
+        if mri is not None:
+            m_feat = self.mri_encoder(mri)
+            out["mri_features"] = m_feat
+            out["mri_logits"] = self.mri_classifier(m_feat)
+        if tab is not None:
+            t_feat = self.tab_encoder(tab)
+            out["tab_features"] = t_feat
+            out["tab_logits"] = self.tab_classifier(t_feat)
+        if m_feat is not None and t_feat is not None:
+            f = self.fusion(m_feat, t_feat)
+            out["fused_features"] = f
+            out["fused_logits"] = self.fused_classifier(f)
+            out["progression"] = self.progression_head(f)
+            # Contrastive embeddings
+            out["zm"] = F.normalize(self.contrast_mri(m_feat), dim=-1)
+            out["zt"] = F.normalize(self.contrast_tab(t_feat), dim=-1)
+        elif m_feat is not None:
+            out["fused_logits"] = out["mri_logits"]
+        elif t_feat is not None:
+            out["fused_logits"] = out["tab_logits"]
+        return out
+
+    def get_param_groups(self, lr_backbone, lr_fusion):
+        backbone = list(self.mri_encoder.parameters()) + list(self.tab_encoder.parameters())
+        fusion = (list(self.fusion.parameters()) + list(self.fused_classifier.parameters())
+                  + list(self.progression_head.parameters())
+                  + list(self.mri_classifier.parameters())
+                  + list(self.tab_classifier.parameters())
+                  + list(self.contrast_mri.parameters()) + list(self.contrast_tab.parameters()))
+        return [{"params": backbone, "lr": lr_backbone},
+                {"params": fusion, "lr": lr_fusion}]
+
+    @torch.no_grad()
+    def predict(self, mri=None, tab=None):
+        self.eval()
+        out = self.forward(mri=mri, tab=tab)
+        probs = F.softmax(out["fused_logits"], dim=-1)
+        pred = probs.argmax(dim=-1)
+        result = {"pred_class": pred, "class_probs": probs,
+                  "class_names": [C.CLASS_NAMES[c] for c in pred.cpu().tolist()]}
+        if "progression" in out:
+            p = out["progression"]
+            result["will_progress"] = p["will_progress"]
+            result["time_to_conversion_months"] = p["time_to_conversion"]
+            result["time_distribution"] = p["time_distribution"]
+        return result
+
+
+def count_params(model):
+    return sum(p.numel() for p in model.parameters() if p.requires_grad)

mri_contribution.py

@@ -0,0 +1,217 @@
+"""
+MRI contribution ablation
+=========================
+Question: does giving the model the MRI actually change the fused prediction?
+
+Why this test: `mri_logits` is only an auxiliary (deep-supervision) head. A weak
+score there does NOT prove the MRI representation is uninformative. The fair
+test compares three conditions on the same patients:
+
+    1. MRI + biomarkers   (the production setting)
+    2. biomarkers only    (MRI switched off)
+    3. MRI only           (biomarkers switched off)
+
+If (1) and (2) do not differ meaningfully, the MRI is not participating in the
+decision.
+
+CRITICAL — the checkpoint and the input modality must match. Each checkpoint is
+trained on a single volume modality; feeding it the other one drops the MRI
+branch to chance and makes the result completely misleading. That is why the
+modality flag is mandatory:
+
+    python mri_contribution.py --tbm --ckpt Vbai-2.6AD.pt
+    python mri_contribution.py --t1  --ckpt <a T1-trained checkpoint>
+"""
+from __future__ import annotations
+import argparse
+import os
+import sys
+
+# --- The modality must be chosen BEFORE config is imported: config decides at
+#     import time which visit manifest to read.
+_ap = argparse.ArgumentParser(add_help=False)
+_ap.add_argument("--tbm", action="store_true")
+_ap.add_argument("--t1", action="store_true")
+_known, _ = _ap.parse_known_args()
+if _known.tbm == _known.t1:
+    sys.exit("ERROR: pass exactly one of --tbm / --t1 "
+             "(match whichever modality the checkpoint was trained on).")
+os.environ["VBAI_USE_TBM"] = "1" if _known.tbm else "0"
+MODALITY = "TBM" if _known.tbm else "raw T1"
+
+
+def _bootstrap_model_path() -> str:
+    """
+    Locate config.py / model.py / dataset.py.
+
+    YOU MUST SET YOUR OWN PATH if they are not next to this script: point
+    VBAI_MODEL_DIR at the directory holding them.
+    """
+    env = os.environ.get("VBAI_MODEL_DIR")
+    cands = ([env] if env else []) + [
+        os.path.dirname(os.path.abspath(__file__)),
+        os.path.join(os.path.dirname(os.path.abspath(__file__)), "Vbai-2.6AD"),
+    ]
+    for c in cands:
+        if c and os.path.isfile(os.path.join(c, "config.py")):
+            if c not in sys.path:
+                sys.path.insert(0, c)
+            return c
+    raise ImportError(
+        f"Could not locate the model modules (config.py). Tried: {cands}\n"
+        "YOU MUST SET YOUR OWN PATH: point VBAI_MODEL_DIR at the directory "
+        "holding config.py / model.py / dataset.py."
+    )
+
+
+MODEL_DIR = _bootstrap_model_path()
+
+import numpy as np
+import torch
+from sklearn.metrics import balanced_accuracy_score, f1_score, confusion_matrix
+
+import config as C
+from model import Vbai26ADModel
+from dataset import (PairedVisitDataset, TabularNormalizer, collate_pad,
+                     subject_split, load_paired)
+
+
+def remap_paths(df):
+    """Re-root the absolute volume paths stored in the manifest to this machine."""
+    def _fix(p):
+        p0 = str(p)
+        if os.path.exists(p0):
+            return p0
+        q = p0.replace("\\", "/")
+        i = q.find("/Datasets/")
+        if i >= 0:
+            cand = os.path.join(C.DATASET_ROOT, q[i + len("/Datasets/"):])
+            if os.path.exists(cand):
+                return cand
+        # The stored tail may or may not include the top volume folder, so both
+        # spellings are tried.
+        j = q.find("/volumes/")
+        if j >= 0:
+            rest = q[j + len("/volumes/"):]
+            for cand in (os.path.join(C.TBM_ROOT, rest),
+                         os.path.join(C.TBM_ROOT, "volumes", rest)):
+                if os.path.exists(cand):
+                    return cand
+        return p0
+
+    df = df.copy()
+    df["nifti_path"] = df["nifti_path"].map(_fix)
+    ok = int(sum(os.path.exists(str(p)) for p in df["nifti_path"]))
+    print(f"[path] reachable images: {ok}/{len(df)}")
+    if ok == 0:
+        raise FileNotFoundError(
+            f"No image is reachable ({MODALITY}).\n"
+            f"  DATASET_ROOT = {C.DATASET_ROOT}\n"
+            f"  VOLUME_ROOT  = {C.TBM_ROOT}\n"
+            "YOU MUST SET YOUR OWN PATHS: see VBAI_DATASET_ROOT / "
+            "VBAI_VOLUME_ROOT in config.py."
+        )
+    return df[df["nifti_path"].map(lambda p: os.path.exists(str(p)))].reset_index(drop=True)
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--ckpt", default="Vbai-2.6AD.pt", help="Vbai-2.6AD checkpoint")
+    ap.add_argument("--tbm", action="store_true")
+    ap.add_argument("--t1", action="store_true")
+    ap.add_argument("--n-per-class", type=int, default=0,
+                    help="0 = the whole test split")
+    ap.add_argument("--batch-size", type=int, default=4)
+    ap.add_argument("--workers", type=int, default=2)
+    args = ap.parse_args()
+
+    dev = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    print(f"[device] {dev}")
+    print(f"[modality] {MODALITY}  (USE_TBM={C.USE_TBM})")
+    print(f"[manifest] {os.path.basename(C.PAIRED_PARQUET)}")
+
+    sd = torch.load(args.ckpt, map_location=dev, weights_only=False)
+    mcfg = C.ModelConfig()
+    for k, v in sd.get("model_cfg", {}).items():
+        if hasattr(mcfg, k):
+            setattr(mcfg, k, v)
+    model = Vbai26ADModel(mcfg).to(dev)
+    res = model.load_state_dict(sd["model"], strict=False)
+    if res.missing_keys or res.unexpected_keys:
+        raise RuntimeError(f"Checkpoint does not match the architecture: "
+                           f"{len(res.missing_keys)} missing / "
+                           f"{len(res.unexpected_keys)} unexpected keys.")
+    model.eval()
+    print(f"[ckpt] {len(sd['model'])} keys matched | "
+          f"stored metrics: {sd.get('extra', {}).get('metrics')}")
+
+    norm = TabularNormalizer()
+    norm.load_state_dict(sd["norm"])
+
+    df = remap_paths(load_paired())
+    _, _, test_ids = subject_split(df)
+    te = df[df["ptid"].isin(test_ids)]
+    if args.n_per_class > 0:
+        te = te.groupby("label", group_keys=False).head(args.n_per_class)
+    te = te.reset_index(drop=True)
+    print(f"[data] test {len(te)} scans | "
+          f"{te['label'].value_counts().sort_index().to_dict()}")
+
+    ds = PairedVisitDataset(te, norm, mode="multi", augment=False, mcfg=mcfg)
+    dl = torch.utils.data.DataLoader(ds, batch_size=args.batch_size, shuffle=False,
+                                     collate_fn=collate_pad, num_workers=args.workers)
+
+    conds = {"MRI + biomarkers": [], "biomarkers only": [], "MRI only": []}
+    ys = []
+    with torch.no_grad():
+        for b in dl:
+            if "mri" not in b or "tab" not in b:
+                continue
+            mri, tab = b["mri"].to(dev), b["tab"].to(dev)
+            ys.append(b["label"])
+            conds["MRI + biomarkers"].append(
+                model(mri=mri, tab=tab)["fused_logits"].argmax(-1).cpu())
+            conds["biomarkers only"].append(
+                model(mri=None, tab=tab)["fused_logits"].argmax(-1).cpu())
+            conds["MRI only"].append(
+                model(mri=mri, tab=None)["fused_logits"].argmax(-1).cpu())
+    ys = torch.cat(ys).numpy()
+
+    print("\n" + "=" * 62)
+    print(f"  MRI CONTRIBUTION ABLATION — {MODALITY}")
+    print("=" * 62)
+    out = {}
+    for k, v in conds.items():
+        p = torch.cat(v).numpy()
+        out[k] = p
+        print(f"  {k:22s} bal_acc={balanced_accuracy_score(ys, p):.3f}  "
+              f"macroF1={f1_score(ys, p, average='macro'):.3f}")
+
+    full, tabonly = out["MRI + biomarkers"], out["biomarkers only"]
+    chg = full != tabonly
+    better = int((chg & (full == ys)).sum())
+    worse = int((chg & (tabonly == ys)).sum())
+    gain = balanced_accuracy_score(ys, full) - balanced_accuracy_score(ys, tabonly)
+
+    print(f"\n  Predictions changed by adding MRI : {int(chg.sum())} / {len(ys)}")
+    print(f"    corrected                       : {better}")
+    print(f"    broken                          : {worse}")
+    print(f"  bal_acc delta (net MRI contribution): {gain:+.3f}")
+    print("\n  Confusion (MRI only)  rows = true, columns = predicted [CN, MCI, AD]:")
+    print("  " + str(confusion_matrix(ys, out["MRI only"],
+                                      labels=[0, 1, 2])).replace("\n", "\n  "))
+    print("-" * 62)
+    if gain > 0.02 and better > worse:
+        print("  → The MRI contributes MEANINGFULLY to the decision. The encoder")
+        print("    is sound, and feeding visual tokens to the LLM is justified.")
+    elif abs(gain) <= 0.02:
+        print("  → The net MRI contribution is within measurement noise. The")
+        print("    encoder signal is weak; read this together with token_probe.")
+    else:
+        print("  → The MRI makes results WORSE. Re-check the input/checkpoint")
+        print("    modality match and the preprocessing.")
+    print("=" * 62)
+
+
+if __name__ == "__main__":
+    main()

probe_features.py

@@ -0,0 +1,98 @@
+"""
+Feature probe
+=============
+Question: do the vectors produced by extract_features.py actually CONTAIN the
+class information?
+
+Why this matters: when the LLM side underperforms there are two very different
+causes —
+  (a) the information is not in the vector      → encoder / feature problem
+  (b) it is there but the LLM cannot read it    → channel problem
+These call for opposite fixes. Fitting a plain LOGISTIC REGRESSION on the vector
+separates them: if a linear layer can recover the class, the information is
+present and the fault lies in the channel.
+
+Measurement on the released checkpoint (subject-level split, 123 test cases):
+    fused (512)   bal_acc 0.880   ← the head itself scores 0.895
+    tab   (256)   bal_acc 0.855
+    mri   (512)   bal_acc 0.410   (chance is 0.333)
+Conclusion: the information is present and linearly decodable. Early failures of
+projector + LoRA training were NOT a data or feature problem — they were a
+channel problem.
+
+Needs no GPU; runs in seconds.
+
+Run:
+    python probe_features.py --features features.pt
+"""
+from __future__ import annotations
+import argparse
+
+import numpy as np
+import torch
+from sklearn.linear_model import LogisticRegression
+from sklearn.metrics import balanced_accuracy_score, f1_score, confusion_matrix
+from sklearn.preprocessing import StandardScaler
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--features", required=True)
+    ap.add_argument("--C", type=float, default=1.0,
+                    help="logistic regression regularisation")
+    args = ap.parse_args()
+
+    d = torch.load(args.features, map_location="cpu", weights_only=False)
+    y = d["label"].numpy()
+    sp = np.array(d["split"])
+    cls = list(d["class_names"])
+    tr, te = sp == "train", sp == "test"
+
+    print(f"[data] {len(y)} records | "
+          f"{ {cls[i]: int((y == i).sum()) for i in range(len(cls))} }")
+    print(f"[split] train {int(tr.sum())} / test {int(te.sum())}\n")
+
+    sets = {
+        "fused (512)": d["fused_features"],
+        "mri (512)": d["mri_features"],
+        "tab (256)": d["tab_features"],
+        "all (1280)": torch.cat(
+            [d["fused_features"], d["mri_features"], d["tab_features"]], dim=-1),
+    }
+
+    best_name, best_ba = None, -1.0
+    for name, X in sets.items():
+        X = X.numpy()
+        sc = StandardScaler().fit(X[tr])
+        clf = LogisticRegression(max_iter=3000, C=args.C,
+                                 class_weight="balanced").fit(sc.transform(X[tr]), y[tr])
+        p = clf.predict(sc.transform(X[te]))
+        ba = balanced_accuracy_score(y[te], p)
+        print(f"  {name:14s} bal_acc={ba:.3f}  macroF1={f1_score(y[te], p, average='macro'):.3f}")
+        if ba > best_ba:
+            best_name, best_ba, best_pred = name, ba, p
+
+    hp = d["class_probs"].argmax(-1).numpy()
+    hb = balanced_accuracy_score(y[te], hp[te])
+    print(f"\n  {'head (reference)':14s} bal_acc={hb:.3f}  "
+          f"macroF1={f1_score(y[te], hp[te], average='macro'):.3f}")
+
+    print(f"\n  Best vector: {best_name}")
+    print(f"  Confusion (rows = true, columns = predicted {cls}):")
+    print("  " + str(confusion_matrix(y[te], best_pred)).replace("\n", "\n  "))
+
+    print("\n" + "-" * 62)
+    if best_ba >= 0.8 * hb:
+        print("  → The information is present and linearly decodable.")
+        print("    If the LLM side misbehaves, the fault is in the CHANNEL")
+        print("    (projector / LoRA), not the features. No need to retrain")
+        print("    the encoder.")
+    else:
+        print("  → The vector does not carry what the head knows. Check feature")
+        print("    extraction first, and confirm the checkpoint matches the")
+        print("    input modality.")
+    print("-" * 62)
+
+
+if __name__ == "__main__":
+    main()

projector.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f6084ee1523d9ccbd890963f814f26de14cc758c5834de84855a5bcc07681d75
+size 195491118

projector.pt_lora/adapter_config.json

@@ -0,0 +1,47 @@
+{
+  "alora_invocation_tokens": null,
+  "alpha_pattern": {},
+  "arrow_config": null,
+  "auto_mapping": null,
+  "base_model_name_or_path": "google/gemma-4-12B-it",
+  "bias": "none",
+  "corda_config": null,
+  "ensure_weight_tying": false,
+  "eva_config": null,
+  "exclude_modules": null,
+  "fan_in_fan_out": false,
+  "inference_mode": true,
+  "init_lora_weights": true,
+  "layer_replication": null,
+  "layers_pattern": null,
+  "layers_to_transform": null,
+  "loftq_config": {},
+  "lora_alpha": 32,
+  "lora_bias": false,
+  "lora_dropout": 0.05,
+  "lora_ga_config": null,
+  "megatron_config": null,
+  "megatron_core": "megatron.core",
+  "modules_to_save": null,
+  "monteclora_config": null,
+  "peft_type": "LORA",
+  "peft_version": "0.20.0",
+  "qalora_group_size": 16,
+  "r": 16,
+  "rank_pattern": {},
+  "revision": null,
+  "target_modules": [
+    "q_proj",
+    "v_proj",
+    "o_proj",
+    "k_proj"
+  ],
+  "target_parameters": null,
+  "task_type": "CAUSAL_LM",
+  "trainable_token_indices": null,
+  "use_bdlora": null,
+  "use_dora": false,
+  "use_qalora": false,
+  "use_rslora": false,
+  "velora_config": null
+}

projector.pt_lora/adapter_model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:de104595b1208c69f9255feb43fb3bebfb0284bf5aa7a1e75d79fb3cd33d5c3d
+size 85382928

token_probe.py

@@ -0,0 +1,381 @@
+"""
+Token probe — the GO / NO-GO experiment before touching the LLM
+==============================================================
+Question: do the 3x3x3 = 27 spatial positions sitting before the encoder's
+AdaptiveAvgPool3d(1) carry information worth handing to an LLM as "visual
+tokens"?
+
+Why this comes first: if the 27 tokens say nothing beyond the pooled 512-d
+vector, wiring the encoder into the LLM as a token sequence is pointless — you
+would just be moving the pipeline inside a transformer. Learning that in an hour
+beats learning it after a week of projector training.
+
+Method:
+  1. Load the checkpoint and FREEZE the entire encoder.
+  2. For every scan, compute the ASPP output (B, 512, 3, 3, 3) once and cache it
+     as a (B, 27, 512) token sequence. The encoder is frozen, so it cannot change
+     between epochs and the 3D CNN never has to run twice.
+  3. Train two small probes on those tokens:
+       - mean-pool probe : discards spatial information (what the model does now)
+       - attention probe : weighted pooling with a learned query over 27 tokens
+  4. Compare on the test split, and measure whether the attention is degenerate
+     (uniform vs selective) through its entropy.
+
+Reading the result:
+  attention probe clearly ahead   → the token grid is meaningful, wire it in.
+  probes equal and entropy ~max   → no spatial information; fix the encoder's
+                                     strides / ASPP dilations first.
+
+NOTE: the normalizer is loaded from the checkpoint and never re-fitted on the
+evaluation data — re-fitting would leak.
+
+This script uses the model modules (config, model, dataset); the path bootstrap
+is below. YOU MUST SET YOUR OWN PATH via VBAI_MODEL_DIR if they are elsewhere.
+
+Run:
+    python token_probe.py --ckpt Vbai-2.6AD.pt
+    python token_probe.py --ckpt ... --epochs 40 --batch-size 8
+"""
+from __future__ import annotations
+import argparse
+import os
+import sys
+
+# ----------------------------------------------------------------------
+# The modality must be chosen BEFORE config is imported: config decides at
+# import time which visit manifest to read (USE_TBM).
+#
+# CRITICAL: the checkpoint and the input modality must match. If they do not,
+# the encoder drops to chance and the probe result is meaningless.
+# ----------------------------------------------------------------------
+_ap = argparse.ArgumentParser(add_help=False)
+_ap.add_argument("--tbm", action="store_true")
+_ap.add_argument("--t1", action="store_true")
+_known, _ = _ap.parse_known_args()
+if _known.tbm == _known.t1:
+    sys.exit("ERROR: pass exactly one of --tbm / --t1 "
+             "(match whichever modality the checkpoint was trained on).")
+os.environ["VBAI_USE_TBM"] = "1" if _known.tbm else "0"
+MODALITY = "TBM" if _known.tbm else "raw T1"
+
+
+# ----------------------------------------------------------------------
+# Make the model modules importable.
+# ----------------------------------------------------------------------
+def _bootstrap_model_path() -> str:
+    env = os.environ.get("VBAI_MODEL_DIR")
+    candidates = []
+    if env:
+        candidates.append(env)
+    here = os.path.dirname(os.path.abspath(__file__))
+    candidates.append(here)                                          # next to this file
+    candidates.append(os.path.join(here, "Vbai-2.6AD"))              # ./Vbai-2.6AD
+    for c in candidates:
+        if os.path.isfile(os.path.join(c, "config.py")):
+            if c not in sys.path:
+                sys.path.insert(0, c)
+            return c
+    raise ImportError(
+        "Could not locate the model modules (config.py).\n"
+        f"Tried: {candidates}\n"
+        "YOU MUST SET YOUR OWN PATH: point VBAI_MODEL_DIR at the directory "
+        "holding config.py / model.py / dataset.py."
+    )
+
+
+MODEL_DIR = _bootstrap_model_path()
+
+import numpy as np
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from sklearn.metrics import accuracy_score, f1_score
+
+import config as C
+from model import Vbai26ADModel
+from dataset import (PairedVisitDataset, TabularNormalizer, collate_pad,
+                     subject_split, load_paired)
+
+
+# ----------------------------------------------------------------------
+# Token extraction — the encoder's forward pass without the pooling step
+# ----------------------------------------------------------------------
+@torch.no_grad()
+def encode_tokens(encoder, mri: torch.Tensor):
+    """(B, 1, 96, 96, 96) → (B, 27, 512) sequence of spatial tokens."""
+    x = encoder.stem(mri)
+    x = encoder.stage1(x)
+    x = encoder.stage2(x)
+    x = encoder.stage3(x)
+    x = encoder.stage4(x)
+    x = encoder.aspp(x)                      # (B, 512, 3, 3, 3)
+    ch = x.shape[1]
+    return x.flatten(2).transpose(1, 2).contiguous(), (ch, tuple(x.shape[2:]))
+
+
+@torch.no_grad()
+def build_token_cache(model, loader, device):
+    """The encoder is frozen, so compute the tokens once and keep them in RAM."""
+    toks, labels, shape_info = [], [], None
+    for batch in loader:
+        if "mri" not in batch:
+            continue
+        mri = batch["mri"].to(device, non_blocking=True)
+        t, shape_info = encode_tokens(model.mri_encoder, mri)
+        toks.append(t.float().cpu())
+        labels.append(batch["label"].clone())
+    if not toks:
+        raise RuntimeError("No MRI batch could be loaded — check your data paths.")
+    return torch.cat(toks), torch.cat(labels), shape_info
+
+
+# ----------------------------------------------------------------------
+# Probes
+# ----------------------------------------------------------------------
+class MeanPoolProbe(nn.Module):
+    """Discards spatial information — equivalent to the current AdaptiveAvgPool3d(1)."""
+    def __init__(self, dim, n_cls=3):
+        super().__init__()
+        self.head = nn.Sequential(nn.LayerNorm(dim), nn.Linear(dim, 128),
+                                  nn.GELU(), nn.Dropout(0.2), nn.Linear(128, n_cls))
+
+    def forward(self, tok):                       # (B, N, D)
+        return self.head(tok.mean(dim=1)), None
+
+
+class AttnPoolProbe(nn.Module):
+    """Weighted pooling over the 27 tokens with a single learned query."""
+    def __init__(self, dim, n_cls=3):
+        super().__init__()
+        self.q = nn.Parameter(torch.randn(1, 1, dim) * 0.02)
+        self.norm = nn.LayerNorm(dim)
+        self.attn = nn.MultiheadAttention(dim, num_heads=8, batch_first=True)
+        self.head = nn.Sequential(nn.LayerNorm(dim), nn.Linear(dim, 128),
+                                  nn.GELU(), nn.Dropout(0.2), nn.Linear(128, n_cls))
+
+    def forward(self, tok):                       # (B, N, D)
+        x = self.norm(tok)
+        q = self.q.expand(x.size(0), -1, -1)
+        pooled, w = self.attn(q, x, x, need_weights=True, average_attn_weights=True)
+        return self.head(pooled.squeeze(1)), w.squeeze(1)   # w: (B, N)
+
+
+def train_probe(probe, tr_tok, tr_y, te_tok, te_y, device, epochs, bs, lr=3e-4):
+    probe = probe.to(device)
+    opt = torch.optim.AdamW(probe.parameters(), lr=lr, weight_decay=1e-4)
+    sched = torch.optim.lr_scheduler.CosineAnnealingLR(opt, T_max=epochs)
+
+    # Compensate for class imbalance — MCI is already the weakest class
+    counts = torch.bincount(tr_y, minlength=3).float().clamp(min=1)
+    w = (counts.sum() / (3 * counts)).to(device)
+
+    n = tr_tok.size(0)
+    for _ in range(epochs):
+        probe.train()
+        perm = torch.randperm(n)
+        for i in range(0, n, bs):
+            idx = perm[i:i + bs]
+            xb = tr_tok[idx].to(device)
+            yb = tr_y[idx].to(device)
+            logits, _ = probe(xb)
+            loss = F.cross_entropy(logits, yb, weight=w)
+            opt.zero_grad(set_to_none=True)
+            loss.backward()
+            opt.step()
+        sched.step()
+
+    probe.eval()
+    preds, attns = [], []
+    with torch.no_grad():
+        for i in range(0, te_tok.size(0), bs):
+            logits, a = probe(te_tok[i:i + bs].to(device))
+            preds.append(logits.argmax(-1).cpu())
+            if a is not None:
+                attns.append(a.cpu())
+    preds = torch.cat(preds).numpy()
+    y = te_y.numpy()
+    attn = torch.cat(attns) if attns else None
+    return {
+        "acc": accuracy_score(y, preds),
+        "f1_macro": f1_score(y, preds, average="macro"),
+        "f1_per": f1_score(y, preds, average=None, labels=[0, 1, 2]),
+        "attn": attn,
+    }
+
+
+def remap_nifti_paths(df):
+    """
+    The visit manifest stores absolute volume paths from the machine that built
+    it, which will not resolve anywhere else. The tail of each path (after the
+    dataset root) is re-attached to the roots configured here. Harmless when the
+    original paths already resolve — it returns them unchanged.
+    """
+    def _fix(p):
+        p0 = str(p)
+        if os.path.exists(p0):
+            return p0
+        q = p0.replace("\\", "/")
+        # Dataset root
+        i = q.find("/Datasets/")
+        if i >= 0:
+            cand = os.path.join(C.DATASET_ROOT, q[i + len("/Datasets/"):])
+            if os.path.exists(cand):
+                return cand
+        # The stored tail may or may not include the top volume folder,
+        # so both spellings are tried.
+        j = q.find("/volumes/")
+        if j >= 0:
+            rest = q[j + len("/volumes/"):]
+            for cand in (os.path.join(C.TBM_ROOT, rest),
+                         os.path.join(C.TBM_ROOT, "volumes", rest)):
+                if os.path.exists(cand):
+                    return cand
+        return p0
+
+    df = df.copy()
+    df["nifti_path"] = df["nifti_path"].map(_fix)
+    ok = int(sum(os.path.exists(str(p)) for p in df["nifti_path"]))
+    print(f"[path] reachable images ({MODALITY}): {ok}/{len(df)}")
+    if ok == 0:
+        raise FileNotFoundError(
+            f"No image is reachable ({MODALITY}).\n"
+            f"  DATASET_ROOT = {C.DATASET_ROOT}\n"
+            f"  VOLUME_ROOT  = {C.TBM_ROOT}\n"
+            "YOU MUST SET YOUR OWN PATHS: see VBAI_DATASET_ROOT / "
+            "VBAI_VOLUME_ROOT in config.py."
+        )
+    return df[df["nifti_path"].map(lambda p: os.path.exists(str(p)))].reset_index(drop=True)
+
+
+@torch.no_grad()
+def baseline_from_checkpoint(model, loader, device):
+    """The trained mri_classifier's own score — the reference baseline."""
+    preds, ys = [], []
+    for batch in loader:
+        if "mri" not in batch:
+            continue
+        out = model(mri=batch["mri"].to(device))
+        preds.append(out["mri_logits"].argmax(-1).cpu())
+        ys.append(batch["label"])
+    preds, ys = torch.cat(preds).numpy(), torch.cat(ys).numpy()
+    return {"acc": accuracy_score(ys, preds), "f1_macro": f1_score(ys, preds, average="macro")}
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--ckpt", default="Vbai-2.6AD.pt",
+                    help="Vbai-2.6AD checkpoint")
+    ap.add_argument("--tbm", action="store_true", help="TBM input")
+    ap.add_argument("--t1", action="store_true", help="raw T1 input")
+    ap.add_argument("--epochs", type=int, default=30)
+    ap.add_argument("--batch-size", type=int, default=8)
+    ap.add_argument("--workers", type=int, default=2)
+    args = ap.parse_args()
+
+    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    print(f"[device] {device}")
+    print(f"[model dir] {MODEL_DIR}")
+
+    # --- model + normalizer (from the checkpoint; NEVER re-fitted) ---
+    sd = torch.load(args.ckpt, map_location=device, weights_only=False)
+    mcfg = C.ModelConfig()
+    for k, v in sd.get("model_cfg", {}).items():
+        if hasattr(mcfg, k):
+            setattr(mcfg, k, v)
+    model = Vbai26ADModel(mcfg).to(device)
+    # Any key mismatch is fatal on purpose: strict=False silently swallows a
+    # checkpoint from a different architecture, leaving the model on random
+    # weights and producing below-chance results. Older checkpoints from a
+    # different architecture must fail loudly here.
+    res = model.load_state_dict(sd["model"], strict=False)
+    if res.missing_keys or res.unexpected_keys:
+        raise RuntimeError(
+            f"Checkpoint does NOT match this architecture: "
+            f"{len(res.missing_keys)} missing / {len(res.unexpected_keys)} "
+            f"unexpected keys.\n"
+            f"  first missing    : {res.missing_keys[:3]}\n"
+            f"  first unexpected : {res.unexpected_keys[:3]}\n"
+            "Checkpoints from a different architecture are not compatible.\n"
+            "Expected file: Vbai-2.6AD.pt"
+        )
+    print(f"[ckpt] {len(sd['model'])} keys matched exactly")
+    if "extra" in sd and sd["extra"].get("metrics"):
+        print(f"[ckpt] stored metrics: {sd['extra']['metrics']}")
+    model.eval()
+    for p in model.parameters():
+        p.requires_grad_(False)
+
+    norm = TabularNormalizer()
+    norm.load_state_dict(sd["norm"])
+
+    # --- subject-level split (no leakage between train and test) ---
+    df = load_paired()
+    df = remap_nifti_paths(df)
+    train_ids, val_ids, test_ids = subject_split(df)
+    tr_df = df[df["ptid"].isin(train_ids | val_ids)]     # train+val to fit the probes
+    te_df = df[df["ptid"].isin(test_ids)]
+    print(f"[data] probe-train {len(tr_df)} scans / test {len(te_df)} scans")
+
+    def make_loader(d, shuffle=False):
+        ds = PairedVisitDataset(d, norm, mode="mri", augment=False, mcfg=mcfg)
+        return torch.utils.data.DataLoader(ds, batch_size=args.batch_size, shuffle=shuffle,
+                                           collate_fn=collate_pad, num_workers=args.workers)
+
+    tr_loader, te_loader = make_loader(tr_df), make_loader(te_df)
+
+    # --- baseline: the checkpoint's own MRI head ---
+    print("\n[1/3] Baseline (trained mri_classifier, pooled)...")
+    base = baseline_from_checkpoint(model, te_loader, device)
+    print(f"      acc {base['acc']:.4f} | macro-F1 {base['f1_macro']:.4f}")
+
+    # --- token cache ---
+    print("\n[2/3] Building the token cache (encoder frozen, single pass)...")
+    tr_tok, tr_y, shape_info = build_token_cache(model, tr_loader, device)
+    te_tok, te_y, _ = build_token_cache(model, te_loader, device)
+    ch, grid = shape_info
+    n_tok, dim = tr_tok.shape[1], tr_tok.shape[2]
+    print(f"      ASPP output: {ch} channels @ {grid}  →  {n_tok} tokens x {dim}-d")
+    print(f"      cache: train {tuple(tr_tok.shape)} / test {tuple(te_tok.shape)}")
+
+    # --- problar ---
+    print("\n[3/3] Training the probes (encoder frozen)...")
+    r_mean = train_probe(MeanPoolProbe(dim), tr_tok, tr_y, te_tok, te_y,
+                         device, args.epochs, args.batch_size)
+    r_attn = train_probe(AttnPoolProbe(dim), tr_tok, tr_y, te_tok, te_y,
+                         device, args.epochs, args.batch_size)
+
+    # --- is the attention degenerate? ---
+    a = r_attn["attn"].clamp_min(1e-9)
+    ent = float((-(a * a.log()).sum(dim=1)).mean())
+    max_ent = float(np.log(n_tok))
+
+    print("\n" + "=" * 66)
+    print("  TOKEN PROBE RESULT")
+    print("=" * 66)
+    print(f"  {'':22s} {'acc':>8s} {'macro-F1':>10s}   F1 (CN/MCI/AD)")
+    print(f"  {'checkpoint (pooled)':22s} {base['acc']:8.4f} {base['f1_macro']:10.4f}")
+    print(f"  {'probe: mean-pool':22s} {r_mean['acc']:8.4f} {r_mean['f1_macro']:10.4f}"
+          f"   {'/'.join(f'{v:.3f}' for v in r_mean['f1_per'])}")
+    print(f"  {'probe: attention':22s} {r_attn['acc']:8.4f} {r_attn['f1_macro']:10.4f}"
+          f"   {'/'.join(f'{v:.3f}' for v in r_attn['f1_per'])}")
+    print(f"\n  attention entropy: {ent:.3f} / {max_ent:.3f} (max = fully uniform)")
+
+    delta = r_attn["f1_macro"] - r_mean["f1_macro"]
+    print(f"  attention - mean difference (macro-F1): {delta:+.4f}")
+    print("-" * 66)
+    if delta > 0.02 and ent < 0.95 * max_ent:
+        print("  → GO. The spatial tokens carry extra information; wiring them")
+        print("    into the LLM as a sequence is justified.")
+    elif ent >= 0.95 * max_ent:
+        print("  → STOP. The attention is nearly uniform: the 27 positions do")
+        print("    not separate. Lower the ASPP dilations to (1,2,3), or drop the")
+        print("    stage-4 stride to reach a 6^3 grid, then measure again.")
+    else:
+        print("  → WEAK. The tokens add nothing meaningful over the pooled")
+        print("    vector. Wiring them in without raising the encoder resolution")
+        print("    will not help.")
+    print("=" * 66)
+
+
+if __name__ == "__main__":
+    main()