Deploy MedAI backend to Hugging Face Space

.dockerignore

@@ -0,0 +1,23 @@
+# Keep the image small and the build fast — never copy these in
+venv/
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+.git/
+.gitignore
+*.bak
+*.ipynb
+notebooks/
+
+# Training / data artifacts not needed to serve
+test_images/
+data/
+datasets/
+outputs/
+roi-outputs/
+*.csv
+*.zip
+
+# Local frontend (served separately on Truehost)
+frontend/

.gitattributes

@@ -0,0 +1,6 @@
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text
+*.gif filter=lfs diff=lfs merge=lfs -text
+*.webp filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,14 @@
+venv/
+.venv/
+__pycache__/
+*.pyc
+*.bak
+.DS_Store
+test_images/
+data/
+datasets/
+outputs/
+*.zip
+.env
+.test_tmp/
+training_log.csv

Dockerfile

@@ -0,0 +1,33 @@
+# MedAI backend — Hugging Face Spaces (Docker SDK)
+FROM python:3.11-slim
+
+# System libraries needed by OpenCV (libgl/libglib) and PyTorch (libgomp)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        libglib2.0-0 libgl1 libgomp1 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Hugging Face Spaces runs the container as uid 1000
+RUN useradd -m -u 1000 user
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH \
+    PYTHONUNBUFFERED=1 \
+    USE_LLM_MODEL=false
+WORKDIR /home/user/app
+
+# Install CPU-only PyTorch first (the default CUDA build is ~2 GB larger and unused here)
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir \
+        torch==2.3.1 torchvision==0.18.1 \
+        --index-url https://download.pytorch.org/whl/cpu
+
+# Install the rest of the serving dependencies (layer cached unless this file changes)
+COPY --chown=user:user requirements-deploy.txt .
+RUN pip install --no-cache-dir -r requirements-deploy.txt
+
+# Copy the application code + model weights
+COPY --chown=user:user . .
+
+# HF Spaces expects the app on port 7860
+EXPOSE 7860
+CMD ["uvicorn", "api.main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,32 @@
+---
+title: MedAI Breast Cancer Platform
+emoji: 🩺
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+app_port: 7860
+pinned: false
+license: mit
+---
+
+# MedAI — Backend API
+
+FastAPI backend for the MedAI dual-modality breast-cancer platform:
+
+- **Histopathology** — DenseNet-121 fine-tuned on PCam (~88.0% accuracy, 87.5% sensitivity)
+- **Mammography** — ensemble of 3× EfficientNet-B4 on RSNA (patient-level AUC 0.8443)
+- **Shared** — Grad-CAM heatmaps, audience-aware explanations, Groq-powered chat assistant
+
+**Research / educational use only — not a medical device and not a substitute for professional diagnosis.**
+
+## Key endpoints
+- `GET /health`
+- `POST /predict`, `POST /explain/visual` — histopathology
+- `POST /mammogram/predict`, `POST /mammogram/visual` — mammography
+- `POST /chat/stream` — streaming chat (Groq)
+
+## Configuration
+Set these as **Space secrets** (Settings → Variables and secrets):
+- `GROQ_API_KEY` — required for the chat assistant
+- `CHAT_MODEL` *(optional)* — defaults to `openai/gpt-oss-120b`
+- `USE_LLM_MODEL` *(optional)* — leave `false` to use the lightweight template explainer

api/main.py

@@ -0,0 +1,744 @@
+"""
+api/main.py
+───────────
+FastAPI layer exposing the breast cancer classifier as an HTTP API.
+
+Endpoints
+─────────
+  GET  /health                — Liveness check
+  POST /predict               — Single image inference (histopathology)
+  POST /predict/batch         — Multi-image batch inference
+  POST /explain               — Prediction + LLM natural language report
+  POST /explain/visual        — Prediction + Grad-CAM heatmap (base64 PNG)
+  POST /chat                  — Conversational follow-up
+  POST /mammogram/predict     — Mammogram inference (3-model ensemble)
+  POST /mammogram/explain     — Mammogram + LLM explanation
+  POST /mammogram/visual      — Mammogram + Grad-CAM + LLM explanation
+
+Run locally
+───────────
+  uvicorn api.main:app --host 0.0.0.0 --port 8000 --reload
+
+Env vars
+────────
+  WEIGHTS_PATH       model/weights.pth               (histopathology)
+  MAMMO_WEIGHTS_DIR  Directory of ensemble members   (default: model)
+  MAMMO_THRESHOLD    Ensemble decision threshold     (default: 0.5)
+  DEVICE             "cuda" | "mps" | "cpu"          (default: auto)
+  CONFIDENCE_THR     Float in [0,1]                  (default: 0.5)
+  USE_LLM_MODEL      "true" | "false"                (default: false)
+  LLM_MODEL_NAME     HuggingFace model id            (default: flan-t5-base)
+  GRADCAM_ALPHA      Heatmap blend opacity 0–1       (default: 0.5)
+"""
+
+from __future__ import annotations
+
+import base64
+import io
+import logging
+import math
+import os
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+import torch
+from fastapi import FastAPI, File, HTTPException, Query, UploadFile, status
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel, Field
+from PIL import Image
+
+# Ensure project root is on PYTHONPATH when running from repo root
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from model.inference             import BreastCancerInferencePipeline
+from model.mammogram_inference   import MammogramInferencePipeline
+from model.mammogram_ensemble    import MammogramEnsemble
+from explainability.gradcam            import GradCAM
+from explainability.mammogram_gradcam  import MammogramGradCAM
+from explainability.chat_pipeline   import DualModelChatPipeline, create_pipeline
+from explainability.llm_explain import LLMExplainer, ChatEngine
+from explainability.llm_chat import stream_chat, llm_available
+
+# ── Logging ───────────────────────────────────────────────────────────────────
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+# ── FastAPI app ───────────────────────────────────────────────────────────────
+app = FastAPI(
+    title="MedAI — Breast Cancer Analysis Platform",
+    description=(
+        "DenseNet-121 histopathology classifier and 3-model EfficientNet-B4 "
+        "mammogram ensemble, with Grad-CAM explainability and LLM explanation. "
+        "Research and educational use only. Not a standalone diagnostic tool."
+    ),
+    version="2.1.0",
+    docs_url="/docs",
+    redoc_url="/redoc",
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["GET", "POST"],
+    allow_headers=["*"],
+)
+
+
+# ── Module singletons ─────────────────────────────────────────────────────────
+_pipeline:       BreastCancerInferencePipeline | None              = None
+_mammo_pipeline: "MammogramEnsemble | MammogramInferencePipeline | None" = None
+_gradcam:        GradCAM | None                                    = None
+_llm_explainer:  LLMExplainer | None                               = None
+_chat_engine:    ChatEngine | None                                 = None
+_chat_pipeline:  DualModelChatPipeline | None                      = None
+
+
+@app.on_event("startup")
+def _load_pipeline() -> None:
+    global _pipeline, _mammo_pipeline
+    weights = os.getenv("WEIGHTS_PATH", "model/weights.pth")
+    device  = os.getenv("DEVICE", None)
+    thr     = float(os.getenv("CONFIDENCE_THR", "0.5"))
+
+    weights_path = Path(weights) if Path(weights).exists() else None
+    if weights_path is None:
+        logger.warning(
+            "weights.pth not found at '%s'. "
+            "Running with ImageNet-pretrained backbone only.", weights,
+        )
+
+    _pipeline = BreastCancerInferencePipeline(
+        weights_path=weights_path,
+        device=device,
+        confidence_threshold=thr,
+    )
+    logger.info("Histopathology pipeline ready on device: %s", _pipeline.device)
+
+    # ── Mammogram: prefer the 3-model ensemble; fall back to single-view ──────
+    mammo_dir = Path(os.getenv("MAMMO_WEIGHTS_DIR", "model"))
+    mammo_thr = float(os.getenv("MAMMO_THRESHOLD", "0.5"))
+    members   = [mammo_dir / f"model_s{s}.pth" for s in (42, 123, 999)]
+    present   = [p for p in members if p.exists()]
+
+    if present:
+        _mammo_pipeline = MammogramEnsemble(
+            weight_paths = present,
+            device       = device,
+            threshold    = mammo_thr,
+        )
+        logger.info(
+            "Mammogram ENSEMBLE ready on %s (%d members, threshold=%.2f)",
+            _mammo_pipeline.device, len(present), mammo_thr,
+        )
+    else:
+        legacy = mammo_dir / "mammogram_weights.pth"
+        _mammo_pipeline = MammogramInferencePipeline(
+            weights_path = legacy if legacy.exists() else None,
+            device       = device,
+        )
+        logger.warning(
+            "Ensemble members not found in '%s'. Falling back to single-view "
+            "pipeline (%s).", mammo_dir,
+            "trained weights" if legacy.exists() else "ImageNet init",
+        )
+
+    logger.info("Grad-CAM and LLM explainer load on first /explain request.")
+
+
+def _get_mammo_pipeline():
+    if _mammo_pipeline is None:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Mammogram pipeline not ready.",
+        )
+    return _mammo_pipeline
+
+
+def _get_pipeline() -> BreastCancerInferencePipeline:
+    if _pipeline is None:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Model pipeline is not ready. Try again shortly.",
+        )
+    return _pipeline
+
+
+def _get_gradcam() -> GradCAM:
+    """Lazy-load GradCAM on first explainability request (histopathology)."""
+    global _gradcam
+    if _gradcam is None:
+        pipeline = _get_pipeline()
+        alpha = float(os.getenv("GRADCAM_ALPHA", "0.5"))
+        logger.info("Initialising Grad-CAM module (device=%s, alpha=%.2f)...",
+                    pipeline.device, alpha)
+        _gradcam = GradCAM(
+            model  = pipeline.model,
+            device = str(pipeline.device),
+            alpha  = alpha,
+        )
+        logger.info("Grad-CAM ready.")
+    return _gradcam
+
+
+def _get_llm() -> LLMExplainer:
+    global _llm_explainer
+    if _llm_explainer is None:
+        use_llm    = os.getenv("USE_LLM_MODEL", "false").lower() == "true"
+        model_name = os.getenv("LLM_MODEL_NAME", "google/flan-t5-base")
+        logger.info(
+            "Initialising LLM explainer (use_llm=%s, model=%s)...",
+            use_llm, model_name if use_llm else "template-engine",
+        )
+        _llm_explainer = LLMExplainer(model_name=model_name, use_llm=use_llm)
+        logger.info("LLM explainer ready (engine=%s).",
+                    "flan-t5" if use_llm else "template")
+    return _llm_explainer
+
+
+def _get_chat_engine() -> ChatEngine:
+    global _chat_engine
+    if _chat_engine is None:
+        _chat_engine = ChatEngine()
+        logger.info("ChatEngine fallback ready.")
+    return _chat_engine
+
+
+def _get_chat_pipeline() -> "DualModelChatPipeline | None":
+    global _chat_pipeline
+    if _chat_pipeline is None:
+        _chat_pipeline = create_pipeline()
+        if _chat_pipeline:
+            logger.info("Dual pipeline ready: BioMedLM + Llama 3.2 (Groq)")
+        else:
+            logger.info(
+                "Dual pipeline not available — set GROQ_API_KEY + HF_TOKEN "
+                "to enable BioMedLM + Llama 3.2. Using ChatEngine fallback."
+            )
+    return _chat_pipeline
+
+
+# ── Response schemas ──────────────────────────────────────────────────────────
+
+class PredictionResponse(BaseModel):
+    prediction: str        = Field(..., examples=["malignant"])
+    confidence: float      = Field(..., ge=0.0, le=1.0, examples=[0.875])
+    logits:     list[float]= Field(
+        ...,
+        description="Raw pre-softmax scores [benign, malignant]",
+        examples=[[-2.14, 3.87]],
+    )
+    disclaimer: str = Field(
+        default=("Research / educational use only. "
+                 "Not a standalone diagnostic tool.")
+    )
+
+
+class ExplainResponse(PredictionResponse):
+    summary:    str = Field(..., description="Plain-language summary of the prediction")
+    detail:     str = Field(..., description="Deeper explanation with confidence context")
+    audience:   str = Field(..., description="Target audience the explanation is tailored for")
+    engine:     str = Field(..., description="'flan-t5' if LLM ran, 'template' if fallback")
+
+
+class VisualExplainResponse(ExplainResponse):
+    overlay_b64:      str   = Field(..., description="Base64 PNG of Grad-CAM overlay")
+    heatmap_b64:      str   = Field(..., description="Base64 PNG of raw Grad-CAM heatmap")
+    spatial_summary:  str   = Field(..., description="Regions that drove the prediction")
+    heatmap_mean:     float = Field(..., description="Mean activation value [0,1]")
+    heatmap_max:      float = Field(..., description="Peak activation value [0,1]")
+
+
+class HealthResponse(BaseModel):
+    status:          str
+    device:          str
+    gradcam_loaded:  bool
+    llm_loaded:      bool
+    llm_engine:      str
+    mammogram_mode:  str
+    chat_llm:        str
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+ACCEPTED_MIME = {"image/jpeg", "image/png", "image/tiff", "image/bmp"}
+
+
+def _validate_and_open(upload: UploadFile) -> Image.Image:
+    if upload.content_type not in ACCEPTED_MIME:
+        raise HTTPException(
+            status_code=status.HTTP_415_UNSUPPORTED_MEDIA_TYPE,
+            detail=f"Unsupported file type: {upload.content_type}. "
+                   f"Accepted: {', '.join(ACCEPTED_MIME)}",
+        )
+    data = upload.file.read()
+    try:
+        return Image.open(io.BytesIO(data)).convert("RGB")
+    except Exception as exc:
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail=f"Could not decode image: {exc}",
+        ) from exc
+
+
+def _serialize(result: dict) -> dict:
+    return {
+        "prediction": result["prediction"],
+        "confidence": result["confidence"],
+        "logits":     result["logits"].squeeze().tolist(),
+    }
+
+
+def _pil_to_b64(img: Image.Image, fmt: str = "PNG") -> str:
+    buf = io.BytesIO()
+    img.save(buf, format=fmt)
+    return base64.b64encode(buf.getvalue()).decode("utf-8")
+
+
+def _heatmap_to_pil(heatmap) -> Image.Image:
+    import numpy as np
+    arr = (heatmap * 255).astype(np.uint8)
+    return Image.fromarray(arr, mode="L")
+
+
+def _ensemble_logits(result: dict) -> list[float]:
+    """
+    The ensemble returns averaged probabilities, not raw logits. Synthesize
+    log-probabilities so the response schema and the /chat context (which
+    expects [benign, malignant] scores) stay backward-compatible.
+    """
+    mal = float(result.get("malignant_probability", result.get("confidence", 0.5)))
+    ben = 1.0 - mal
+    return [round(math.log(max(ben, 1e-6)), 6),
+            round(math.log(max(mal, 1e-6)), 6)]
+
+
+def _is_ensemble(pipeline) -> bool:
+    return isinstance(pipeline, MammogramEnsemble)
+
+
+class PatientRecord(BaseModel):
+    name:             str = Field(default="", description="Patient name")
+    age:              int = Field(default=0,  description="Patient age")
+    sex:              str = Field(default="", description="Male / Female / Other")
+    medical_history:  str = Field(default="", description="Relevant medical history")
+    symptoms:         str = Field(default="", description="Current symptoms or concerns")
+    previous_scans:   str = Field(default="", description="Previous imaging history")
+
+
+class ChatRequest(BaseModel):
+    message:         str
+    audience:        str   = Field(default="clinician",
+                                   description="clinician | researcher | patient")
+    prediction:      str   = Field(default="")
+    confidence:      float = Field(default=0.0, ge=0.0, le=1.0)
+    logits:          list[float] = Field(default=[0.0, 0.0])
+    spatial_summary: str   = Field(default="")
+    history:         list  = Field(default_factory=list)
+    patient:         PatientRecord = Field(default_factory=PatientRecord)
+
+
+class ChatResponse(BaseModel):
+    response:  str
+    audience:  str
+
+
+# ── Endpoints ─────────────────────────────────────────────────────────────────
+
+@app.get("/health", response_model=HealthResponse, tags=["Meta"])
+def health() -> HealthResponse:
+    pipeline = _get_pipeline()
+    llm_engine = "not_loaded"
+    if _llm_explainer is not None:
+        llm_engine = "flan-t5" if _llm_explainer.use_llm else "template"
+
+    mammo_mode = "not_loaded"
+    if _mammo_pipeline is not None:
+        mammo_mode = "ensemble" if _is_ensemble(_mammo_pipeline) else "single-view"
+
+    import os
+    avail, provider = llm_available()
+    model = os.getenv("CHAT_MODEL") or ("openai/gpt-oss-120b" if provider == "groq" else provider)
+    chat_llm = f"{provider}/{model}" if avail else f"{provider}/no_api_key"
+
+    return HealthResponse(
+        status         = "ok",
+        device         = str(pipeline.device),
+        gradcam_loaded = _gradcam is not None,
+        llm_loaded     = _llm_explainer is not None,
+        llm_engine     = llm_engine,
+        mammogram_mode = mammo_mode,
+        chat_llm       = chat_llm,
+    )
+
+
+@app.post("/predict", response_model=PredictionResponse, tags=["Inference"])
+def predict(file: UploadFile = File(...)) -> PredictionResponse:
+    pipeline = _get_pipeline()
+    image    = _validate_and_open(file)
+    try:
+        result = pipeline.predict(image)
+    except Exception as exc:
+        logger.exception("Inference error")
+        raise HTTPException(500, detail=f"Inference failed: {exc}") from exc
+    return PredictionResponse(**_serialize(result))
+
+
+@app.post("/predict/batch", response_model=List[PredictionResponse], tags=["Inference"])
+def predict_batch(files: List[UploadFile] = File(...)) -> list[PredictionResponse]:
+    if len(files) > 16:
+        raise HTTPException(400, detail="Batch size exceeds maximum of 16 images.")
+    pipeline = _get_pipeline()
+    images   = [_validate_and_open(f) for f in files]
+    try:
+        results = pipeline.predict_batch(images)
+    except Exception as exc:
+        logger.exception("Batch inference error")
+        raise HTTPException(500, detail=f"Batch inference failed: {exc}") from exc
+    return [PredictionResponse(**_serialize(r)) for r in results]
+
+
+@app.post("/explain", response_model=ExplainResponse, tags=["Explainability"])
+def explain(
+    file:     UploadFile = File(...),
+    audience: str        = Query(default="clinician",
+                                 enum=["clinician", "researcher", "patient"]),
+) -> ExplainResponse:
+    pipeline = _get_pipeline()
+    llm      = _get_llm()
+    image    = _validate_and_open(file)
+    try:
+        prediction = pipeline.predict(image)
+    except Exception as exc:
+        logger.exception("Inference error in /explain")
+        raise HTTPException(500, detail=f"Inference failed: {exc}") from exc
+    try:
+        report = llm.explain(prediction, audience=audience)
+    except Exception as exc:
+        logger.exception("LLM explanation error in /explain")
+        raise HTTPException(500, detail=f"Explanation generation failed: {exc}") from exc
+    return ExplainResponse(
+        **_serialize(prediction),
+        summary  = report["summary"],
+        detail   = report["detail"],
+        audience = report["audience"],
+        engine   = report["engine"],
+    )
+
+
+@app.post("/explain/visual", response_model=VisualExplainResponse, tags=["Explainability"])
+def explain_visual(
+    file:      UploadFile    = File(...),
+    audience:  str           = Query(default="clinician",
+                                     enum=["clinician", "researcher", "patient"]),
+    class_idx: Optional[int] = Query(default=None, ge=0, le=1),
+) -> VisualExplainResponse:
+    llm   = _get_llm()
+    cam   = _get_gradcam()
+    image = _validate_and_open(file)
+    try:
+        cam_result = cam.explain(image, class_idx=class_idx)
+    except Exception as exc:
+        logger.exception("Grad-CAM error in /explain/visual")
+        raise HTTPException(500, detail=f"Grad-CAM failed: {exc}") from exc
+    try:
+        report = llm.explain_with_gradcam(cam_result, audience=audience)
+    except Exception as exc:
+        logger.exception("LLM explanation error in /explain/visual")
+        raise HTTPException(500, detail=f"Explanation generation failed: {exc}") from exc
+
+    import numpy as np
+    heatmap = cam_result["heatmap"]
+    overlay = cam_result["overlay"]
+    return VisualExplainResponse(
+        **_serialize(cam_result),
+        summary         = report["summary"],
+        detail          = report["detail"],
+        audience        = report["audience"],
+        engine          = report["engine"],
+        overlay_b64     = _pil_to_b64(overlay),
+        heatmap_b64     = _pil_to_b64(_heatmap_to_pil(heatmap)),
+        spatial_summary = LLMExplainer._summarise_heatmap(heatmap),
+        heatmap_mean    = round(float(np.mean(heatmap)), 6),
+        heatmap_max     = round(float(np.max(heatmap)), 6),
+    )
+
+
+@app.post("/chat", response_model=ChatResponse, tags=["Explainability"])
+def chat(request: ChatRequest) -> ChatResponse:
+    logits = request.logits if len(request.logits) >= 2 else [0.0, 0.0]
+    patient_dict = {}
+    if request.patient:
+        patient_dict = {
+            "name":            request.patient.name,
+            "age":             request.patient.age,
+            "sex":             request.patient.sex,
+            "medical_history": request.patient.medical_history,
+            "symptoms":        request.patient.symptoms,
+            "previous_scans":  request.patient.previous_scans,
+        }
+
+    pipeline = _get_chat_pipeline()
+    if pipeline:
+        try:
+            response_text = pipeline.respond(
+                message         = request.message,
+                audience        = request.audience,
+                prediction      = request.prediction,
+                confidence      = request.confidence,
+                benign_logit    = logits[0],
+                malignant_logit = logits[1],
+                spatial_summary = request.spatial_summary,
+                history         = request.history,
+                patient         = patient_dict,
+            )
+            if response_text:
+                return ChatResponse(response=response_text, audience=request.audience)
+        except Exception as e:
+            logger.warning("Dual pipeline error (%s) — falling back to ChatEngine.", e)
+
+    _get_llm()
+    engine = _get_chat_engine()
+    response_text = engine.respond(
+        message         = request.message,
+        audience        = request.audience,
+        prediction      = request.prediction,
+        confidence      = request.confidence,
+        benign_logit    = logits[0],
+        malignant_logit = logits[1],
+        spatial_summary = request.spatial_summary,
+        history         = request.history,
+        patient         = patient_dict,
+    )
+    return ChatResponse(response=response_text, audience=request.audience)
+
+
+class LLMChatRequest(BaseModel):
+    messages:        list  = Field(default_factory=list,
+                                    description="[{role: 'user'|'assistant', content: str}, ...]")
+    audience:        str   = Field(default="clinician")
+    prediction:      str   = Field(default="")
+    confidence:      float = Field(default=0.0, ge=0.0, le=1.0)
+    logits:          list[float] = Field(default=[0.0, 0.0])
+    spatial_summary: str   = Field(default="")
+    birads:          str   = Field(default="")
+
+
+@app.post("/chat/stream", tags=["Explainability"])
+def chat_stream(req: LLMChatRequest):
+    """Real LLM assistant with token streaming (Claude or GPT via env config)."""
+    context = {
+        "prediction":      req.prediction,
+        "confidence":      req.confidence,
+        "logits":          req.logits,
+        "spatial_summary": req.spatial_summary,
+        "birads":          req.birads,
+    } if req.prediction else None
+
+    def generate():
+        try:
+            for token in stream_chat(req.messages, context=context, audience=req.audience):
+                yield token
+        except Exception as e:  # noqa: BLE001
+            logger.warning("LLM chat stream error: %s", e)
+            yield f"\n[Assistant error: {e}]"
+
+    return StreamingResponse(generate(), media_type="text/plain; charset=utf-8")
+
+class MammogramResponse(BaseModel):
+    prediction:  str
+    confidence:  float
+    logits:      list[float]
+    birads:      str
+    modality:    str = "mammogram"
+    per_model:   Optional[list[float]] = Field(
+        default=None,
+        description="Per-member malignant probabilities (ensemble mode only)",
+    )
+    n_models:    Optional[int] = Field(
+        default=None, description="Number of ensemble members averaged",
+    )
+    disclaimer:  str = (
+        "AI-assisted mammogram analysis. Research use only. "
+        "Not a substitute for radiologist review or clinical diagnosis."
+    )
+
+
+class MammogramExplainResponse(MammogramResponse):
+    summary:    str
+    detail:     str
+    audience:   str
+    engine:     str
+
+
+class MammogramVisualResponse(MammogramExplainResponse):
+    overlay_b64:     str
+    heatmap_b64:     str
+    spatial_summary: str
+    heatmap_mean:    float
+    heatmap_max:     float
+
+
+def _run_mammo_predict(pipeline, image: Image.Image, tta: bool) -> dict:
+    """Unified prediction → dict with prediction/confidence/logits/birads/etc."""
+    if _is_ensemble(pipeline):
+        result = pipeline.predict_tta(image) if tta else pipeline.predict(image)
+        return {
+            "prediction": result["prediction"],
+            "confidence": result["confidence"],
+            "logits":     _ensemble_logits(result),
+            "birads":     result["birads"],
+            "modality":   result.get("modality", "mammogram_ensemble"),
+            "per_model":  result.get("per_model"),
+            "n_models":   result.get("n_models"),
+        }
+    # Legacy single-view pipeline (returns logits tensor)
+    result = pipeline.predict(image)
+    return {
+        "prediction": result["prediction"],
+        "confidence": result["confidence"],
+        "logits":     result["logits"].squeeze().tolist(),
+        "birads":     result["birads"],
+        "modality":   result.get("modality", "mammogram"),
+        "per_model":  None,
+        "n_models":   None,
+    }
+
+
+@app.post("/mammogram/predict",
+          response_model=MammogramResponse,
+          tags=["Mammogram"])
+def mammogram_predict(
+    file: UploadFile = File(...),
+    tta:  bool       = Query(default=False,
+                             description="Test-time augmentation (ensemble only) — "
+                                         "slower, slightly more accurate"),
+) -> MammogramResponse:
+    """
+    Classify a mammogram using the 3-model EfficientNet-B4 ensemble.
+    Returns prediction, confidence, BI-RADS suggestion, and per-member probs.
+    """
+    pipeline = _get_mammo_pipeline()
+    image    = _validate_and_open(file)
+    try:
+        result = _run_mammo_predict(pipeline, image, tta)
+    except Exception as exc:
+        logger.exception("Mammogram inference error")
+        raise HTTPException(500, detail=f"Mammogram inference failed: {exc}") from exc
+    return MammogramResponse(**result)
+
+
+@app.post("/mammogram/explain",
+          response_model=MammogramExplainResponse,
+          tags=["Mammogram"])
+def mammogram_explain(
+    file:     UploadFile = File(...),
+    audience: str        = Query(default="clinician",
+                                 enum=["clinician", "researcher", "patient"]),
+    tta:      bool       = Query(default=False),
+) -> MammogramExplainResponse:
+    """Classify a mammogram (ensemble) and generate an audience-specific explanation."""
+    pipeline = _get_mammo_pipeline()
+    llm      = _get_llm()
+    image    = _validate_and_open(file)
+
+    try:
+        result = _run_mammo_predict(pipeline, image, tta)
+    except Exception as exc:
+        raise HTTPException(500, detail=f"Mammogram inference failed: {exc}") from exc
+
+    explain_input = {
+        "prediction": result["prediction"],
+        "confidence": result["confidence"],
+        "logits":     torch.tensor([result["logits"]]),
+        "birads":     result["birads"],
+    }
+    try:
+        report = llm.explain(explain_input, audience=audience, modality="mammogram")
+    except Exception as exc:
+        raise HTTPException(500, detail=f"Explanation failed: {exc}") from exc
+
+    return MammogramExplainResponse(
+        **result,
+        summary  = report["summary"],
+        detail   = report["detail"],
+        audience = report["audience"],
+        engine   = report["engine"],
+    )
+
+
+@app.post("/mammogram/visual",
+          response_model=MammogramVisualResponse,
+          tags=["Mammogram"])
+def mammogram_visual(
+    file:      UploadFile    = File(...),
+    audience:  str           = Query(default="clinician",
+                                     enum=["clinician", "researcher", "patient"]),
+    class_idx: Optional[int] = Query(default=None, ge=0, le=1),
+) -> MammogramVisualResponse:
+    """
+    Full mammogram analysis: ensemble prediction + Grad-CAM + LLM explanation.
+
+    Grad-CAM is inherently a single-model technique, so the heatmap is computed
+    on the strongest ensemble member (the most representative saliency map),
+    while the prediction label/confidence uses the full ensemble average.
+    """
+    import numpy as np
+
+    pipeline = _get_mammo_pipeline()
+    llm      = _get_llm()
+    image    = _validate_and_open(file)
+
+    # Authoritative label/confidence from the full ensemble
+    try:
+        pred = _run_mammo_predict(pipeline, image, tta=False)
+    except Exception as exc:
+        raise HTTPException(500, detail=f"Mammogram inference failed: {exc}") from exc
+
+    # Grad-CAM on the representative single model (EfficientNet-specific)
+    cam_model = pipeline.cam_model if _is_ensemble(pipeline) else pipeline.model
+    try:
+        alpha = float(os.getenv("GRADCAM_ALPHA", "0.5"))
+        mammo_cam = MammogramGradCAM(model=cam_model, device=str(pipeline.device), alpha=alpha)
+        cam_result = mammo_cam.explain(image, class_idx=class_idx)
+    except Exception as exc:
+        logger.exception("Mammogram Grad-CAM error")
+        raise HTTPException(
+            500,
+            detail=(f"Grad-CAM failed: {exc}. The /mammogram/predict endpoint "
+                    f"still works without the heatmap."),
+        ) from exc
+
+    # Make the LLM explanation reflect the ENSEMBLE verdict (authoritative),
+    # while the heatmap stays the representative member's saliency map.
+    cam_result["prediction"] = pred["prediction"]
+    cam_result["confidence"] = pred["confidence"]
+    cam_result["logits"]     = torch.tensor([pred["logits"]])
+    cam_result["birads"]     = pred["birads"]
+
+    try:
+        report = llm.explain_with_gradcam(cam_result, audience=audience, modality="mammogram")
+    except Exception as exc:
+        raise HTTPException(500, detail=f"Explanation failed: {exc}") from exc
+
+    heatmap = cam_result["heatmap"]
+    overlay = cam_result["overlay"]
+    return MammogramVisualResponse(
+        prediction      = pred["prediction"],
+        confidence      = pred["confidence"],
+        logits          = pred["logits"],
+        birads          = pred["birads"],
+        modality        = pred["modality"],
+        per_model       = pred["per_model"],
+        n_models        = pred["n_models"],
+        summary         = report["summary"],
+        detail          = report["detail"],
+        audience        = report["audience"],
+        engine          = report["engine"],
+        overlay_b64     = _pil_to_b64(overlay),
+        heatmap_b64     = _pil_to_b64(_heatmap_to_pil(heatmap)),
+        spatial_summary = LLMExplainer._summarise_heatmap(heatmap),
+        heatmap_mean    = round(float(np.mean(heatmap)), 6),
+        heatmap_max     = round(float(np.max(heatmap)), 6),
+    )

explainability/chat_pipeline.py

@@ -0,0 +1,568 @@
+"""
+explainability/chat_pipeline.py
+────────────────────────────────
+Dual-model conversational pipeline for the MedAI chat assistant.
+
+Architecture
+────────────
+  Stage 1 — BioMedLM  (HuggingFace Inference API, free)
+    ↓  Enriches the scan context with clinical knowledge:
+       medical terminology, risk factors, differential diagnosis,
+       clinical recommendations, and pathology context.
+
+  Stage 2 — Llama 3.2  (Groq API, free tier)
+    ↓  Takes BioMedLM's enrichment + patient record + scan results
+       and produces a warm, natural, human-like conversation response
+       tailored to the selected audience.
+
+Why two models
+──────────────
+  BioMedLM knows medicine deeply — it was trained on PubMed abstracts
+  and biomedical literature. It understands BRCA1, BI-RADS categories,
+  nuclear atypia, ductal carcinoma, and thousands of clinical concepts.
+
+  Llama 3.2 is a world-class conversational model — it produces warm,
+  empathetic, natural language. It can switch between clinical colleague
+  tone, researcher-level technical depth, and patient-friendly plain English.
+
+  Together: BioMedLM provides the medical substance.
+            Llama 3.2 provides the human voice.
+
+Environment variables required
+──────────────────────────────
+  GROQ_API_KEY   — from console.groq.com (free, no card)
+  HF_TOKEN       — from huggingface.co/settings/tokens (free)
+
+Fallback behaviour
+──────────────────
+  If BioMedLM fails (cold start, rate limit) → Llama 3.2 runs alone.
+  If Groq fails (rate limit)                 → deterministic ChatEngine.
+  If both fail                               → ChatEngine always responds.
+  The system never returns an empty response.
+
+Install
+───────
+  pip install groq requests
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+from typing import Optional
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+
+# ╔══════════════════════════════════════════════════════════════════════════════╗
+# ║  STAGE 1 — BioMedLM ENRICHER (HuggingFace Inference API)                   ║
+# ╚══════════════════════════════════════════════════════════════════════════════╝
+
+class BioMedEnricher:
+    """
+    Calls BioMedLM via the HuggingFace free Inference API to extract
+    clinically relevant context from the scan and patient data.
+
+    BioMedLM (stanford-crfm/BioMedLM) is a 2.7B GPT-style model trained
+    on PubMed abstracts. It generates medical text continuations, which
+    we use to enrich the context before Llama 3.2 formulates the response.
+
+    Parameters
+    ----------
+    hf_token : str
+        HuggingFace access token. Free at huggingface.co/settings/tokens.
+    timeout : int
+        HTTP timeout in seconds. Default 20.
+    max_retries : int
+        Retries if model is loading (cold start returns 503). Default 2.
+    """
+
+    MODEL_URL = (
+        "https://router.huggingface.co/hf-inference/models/stanford-crfm/BioMedLM"
+    )
+
+    def __init__(
+        self,
+        hf_token:    str,
+        timeout:     int = 20,
+        max_retries: int = 2,
+    ) -> None:
+        self.headers     = {"Authorization": f"Bearer {hf_token}"}
+        self.timeout     = timeout
+        self.max_retries = max_retries
+
+    def enrich(
+        self,
+        prediction:      str,
+        confidence:      float,
+        benign_logit:    float,
+        malignant_logit: float,
+        spatial_summary: str,
+        patient:         dict,
+        question:        str,
+    ) -> str:
+        """
+        Generate a clinical enrichment passage using BioMedLM.
+
+        Builds a structured medical prompt, sends it to the HuggingFace
+        Inference API, and returns the generated clinical context.
+
+        Returns empty string if the API call fails — the pipeline
+        continues without enrichment in that case.
+        """
+        prompt = self._build_prompt(
+            prediction, confidence, benign_logit, malignant_logit,
+            spatial_summary, patient, question
+        )
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                resp = requests.post(
+                    self.MODEL_URL,
+                    headers = self.headers,
+                    json    = {
+                        "inputs": prompt,
+                        "parameters": {
+                            "max_new_tokens":       180,
+                            "temperature":          0.3,   # low temp for factual output
+                            "repetition_penalty":   1.3,
+                            "return_full_text":     False, # only return generated part
+                        },
+                    },
+                    timeout = self.timeout,
+                )
+
+                # Model loading (cold start) — wait and retry
+                if resp.status_code == 503:
+                    data = resp.json()
+                    wait = data.get("estimated_time", 8)
+                    logger.info(
+                        "BioMedLM loading (cold start) — waiting %.0fs (attempt %d/%d)",
+                        wait, attempt + 1, self.max_retries + 1
+                    )
+                    time.sleep(min(wait, 15))
+                    continue
+
+                if resp.status_code != 200:
+                    logger.warning(
+                        "BioMedLM API error %d: %s", resp.status_code, resp.text[:200]
+                    )
+                    return ""
+
+                result = resp.json()
+
+                # HF returns list of dicts or a single dict
+                if isinstance(result, list) and result:
+                    generated = result[0].get("generated_text", "")
+                elif isinstance(result, dict):
+                    generated = result.get("generated_text", "")
+                else:
+                    return ""
+
+                # Clean up — remove the prompt prefix if model echoes it
+                if generated.startswith(prompt):
+                    generated = generated[len(prompt):]
+
+                enrichment = generated.strip()
+                if enrichment:
+                    logger.info("BioMedLM enrichment: %d words", len(enrichment.split()))
+                return enrichment
+
+            except requests.exceptions.Timeout:
+                logger.warning("BioMedLM request timed out (attempt %d)", attempt + 1)
+            except Exception as e:
+                logger.warning("BioMedLM error: %s", e)
+                return ""
+
+        return ""
+
+    def _build_prompt(
+        self,
+        prediction:      str,
+        confidence:      float,
+        benign_logit:    float,
+        malignant_logit: float,
+        spatial_summary: str,
+        patient:         dict,
+        question:        str,
+    ) -> str:
+        """Build a medical text prompt for BioMedLM completion."""
+        pct    = f"{confidence:.1%}"
+        margin = abs(malignant_logit - benign_logit)
+        name   = patient.get("name", "")
+        age    = patient.get("age", 0)
+        hist   = patient.get("medical_history", "")
+        symp   = patient.get("symptoms", "")
+
+        patient_ctx = ""
+        if age:
+            patient_ctx += f"Patient age: {age}."
+        if hist:
+            patient_ctx += f" Medical history: {hist}."
+        if symp:
+            patient_ctx += f" Current symptoms: {symp}."
+
+        return (
+            f"Histopathology AI result: {prediction.upper()} ({pct} confidence). "
+            f"Logit margin: {margin:.3f}. "
+            f"Grad-CAM spatial findings: {spatial_summary or 'not available'}. "
+            f"{patient_ctx} "
+            f"Clinical question: {question}. "
+            f"Medical assessment and clinical implications:"
+        )
+
+
+# ╔══════════════════════════════════════════════════════════════════════════════╗
+# ║  STAGE 2 — LLAMA 3.2 via GROQ (conversational response)                    ║
+# ╚══════════════════════════════════════════════════════════════════════════════╝
+
+class GroqChat:
+    """
+    Calls Llama 3.2 via the Groq API to generate a natural, human-like
+    conversational response.
+
+    Groq uses custom LPU chips that are ~5x faster than standard GPU inference.
+    Responses typically arrive in 0.2–0.5 seconds on the free tier.
+
+    Free tier limits (as of 2025):
+    - Llama 3.2 3B: 30 requests/min, 500 requests/day
+    - Llama 3.1 8B: 30 requests/min, 6,000 tokens/min
+
+    Parameters
+    ----------
+    api_key : str
+        Groq API key. Free at console.groq.com (no card required).
+    model : str
+        Groq model identifier. Default: llama-3.2-3b-preview.
+    """
+
+    # Audience-specific system prompts — each produces a different voice
+    SYSTEM_PROMPTS = {
+        "clinician": (
+            "You are a specialist AI assistant for the MedAI breast cancer analysis platform, "
+            "speaking with a consultant radiologist or clinical specialist. "
+            "Be precise, collegial, and technically accurate. Use clinical terminology naturally. "
+            "Reference BI-RADS categories, biopsy recommendations, logit margins, and sensitivity "
+            "metrics where relevant. Be direct — clinicians appreciate concise, information-dense responses. "
+            "Always acknowledge the AI-assisted nature of the analysis and the need for clinical confirmation."
+        ),
+        "researcher": (
+            "You are a specialist AI assistant for the MedAI breast cancer analysis platform, "
+            "speaking with an ML researcher. Be technical and precise. "
+            "Discuss logit scores, softmax probabilities, decision boundaries, model architecture "
+            "(DenseNet-121, 7.22M params), training methodology (OneCycleLR max_lr=3e-3, Mixup α=0.4, "
+            "StainJitter HED, label_smoothing=0.1, pos_weight=1.469), and calibration freely. "
+            "Reference the PCam dataset (220,025 deduplicated patches), test accuracy 88.0%, "
+            "test sensitivity 87.5% (epoch 13 checkpoint, selected by val_sensitivity). "
+            "Be rigorous and engage at a peer level."
+        ),
+        "patient": (
+            "You are a warm, empathetic AI assistant for the MedAI breast cancer analysis platform, "
+            "speaking with a patient who has no medical background. "
+            "Use plain English — no jargon, no acronyms, no intimidating terminology. "
+            "Be genuinely human and warm. Acknowledge their emotions. Use simple analogies. "
+            "If the patient seems worried, be reassuring without being dismissive. "
+            "If they ask about something serious, be honest but kind. "
+            "Always remind them that their doctor makes all final decisions — you are a support tool, not a doctor. "
+            "Address them by name if you know it. Keep sentences short and clear."
+        ),
+    }
+
+    def __init__(
+        self,
+        api_key: str,
+        model:   str = "llama-3.1-8b-instant",
+    ) -> None:
+        try:
+            from groq import Groq
+            self._client = Groq(api_key=api_key)
+            self._model  = model
+            self._ok     = True
+            logger.info("Groq client initialised (model=%s)", model)
+        except ImportError:
+            logger.warning(
+                "groq package not installed. Run: pip install groq"
+            )
+            self._ok = False
+
+    def generate(
+        self,
+        audience:          str,
+        user_message:      str,
+        scan_context:      str,
+        patient_context:   str,
+        biomedlm_context:  str,
+        history:           list,
+    ) -> str:
+        """
+        Generate a conversational response using Llama 3.2 via Groq.
+
+        Parameters
+        ----------
+        audience          : clinician | researcher | patient
+        user_message      : the user's question
+        scan_context      : structured scan result summary
+        patient_context   : patient name, age, history, symptoms
+        biomedlm_context  : clinical enrichment from BioMedLM (may be empty)
+        history           : list of prior {"role", "content"} dicts
+
+        Returns
+        -------
+        str — Llama 3.2 response, or empty string if Groq call fails.
+        """
+        if not self._ok:
+            return ""
+
+        system = self.SYSTEM_PROMPTS.get(audience, self.SYSTEM_PROMPTS["clinician"])
+
+        # Build the context block injected into the system prompt
+        context_block = f"\n\nCURRENT SCAN CONTEXT:\n{scan_context}"
+        if patient_context:
+            context_block += f"\n\nPATIENT INFORMATION:\n{patient_context}"
+        if biomedlm_context:
+            context_block += (
+                f"\n\nCLINICAL ENRICHMENT (from BioMedLM medical knowledge model):\n"
+                f"{biomedlm_context}\n"
+                f"Use the above medical context to inform your response where relevant."
+            )
+        context_block += (
+            "\n\nIMPORTANT: Keep your response focused and conversational. "
+            "2-4 sentences for simple questions, more for complex ones. "
+            "Be specific — reference the actual scan numbers, not generic statements. "
+            "Sound like a knowledgeable colleague, not a textbook."
+        )
+
+        system_with_context = system + context_block
+
+        # Build message history (last 6 turns for context window efficiency)
+        messages = []
+        for turn in (history or [])[-6:]:
+            if isinstance(turn, dict) and "role" in turn and "content" in turn:
+                messages.append({
+                    "role":    turn["role"],
+                    "content": turn["content"],
+                })
+        messages.append({"role": "user", "content": user_message})
+
+        try:
+            response = self._client.chat.completions.create(
+                model       = self._model,
+                messages    = [{"role": "system", "content": system_with_context}] + messages,
+                max_tokens  = 512,
+                temperature = 0.75,
+                top_p       = 0.9,
+            )
+            text = response.choices[0].message.content.strip()
+            logger.info(
+                "Groq response: %d words (model=%s)", len(text.split()), self._model
+            )
+            return text
+
+        except Exception as e:
+            logger.warning("Groq API error: %s", e)
+            return ""
+
+
+# ╔══════════════════════════════════════════════════════════════════════════════╗
+# ║  DUAL-MODEL PIPELINE ORCHESTRATOR                                           ║
+# ╚══════════════════════════════════════════════════════════════════════════════╝
+
+class DualModelChatPipeline:
+    """
+    Orchestrates BioMedLM + Llama 3.2 for human-quality medical chat.
+
+    Stage 1: BioMedLM enriches the context with clinical knowledge.
+    Stage 2: Llama 3.2 produces a natural, audience-specific response.
+
+    Graceful degradation:
+    - BioMedLM failure → Llama 3.2 runs without enrichment (still good)
+    - Groq failure     → falls back to deterministic ChatEngine
+    - Both fail        → ChatEngine always produces a response
+
+    Parameters
+    ----------
+    groq_key : str
+        Groq API key (GROQ_API_KEY env var). Free at console.groq.com.
+    hf_token : str
+        HuggingFace token (HF_TOKEN env var). Free at huggingface.co.
+    groq_model : str
+        Groq model to use. Default: llama-3.2-3b-preview.
+    """
+
+    def __init__(
+        self,
+        groq_key:   str,
+        hf_token:   str,
+        groq_model: str = "llama-3.1-8b-instant",
+    ) -> None:
+        self.biomedlm = BioMedEnricher(hf_token=hf_token)
+        self.llama    = GroqChat(api_key=groq_key, model=groq_model)
+        logger.info(
+            "DualModelChatPipeline ready (BioMedLM + %s via Groq)", groq_model
+        )
+
+    def respond(
+        self,
+        message:         str,
+        audience:        str,
+        prediction:      str,
+        confidence:      float,
+        benign_logit:    float,
+        malignant_logit: float,
+        spatial_summary: str  = "",
+        history:         list = None,
+        patient:         dict = None,
+    ) -> str:
+        """
+        Generate a human-like chat response using the dual-model pipeline.
+
+        Parameters
+        ----------
+        message         : user's question
+        audience        : clinician | researcher | patient
+        prediction      : benign | malignant
+        confidence      : float [0, 1]
+        benign_logit    : raw logit for benign class
+        malignant_logit : raw logit for malignant class
+        spatial_summary : Grad-CAM text description
+        history         : conversation history [{"role", "content"}]
+        patient         : patient record dict
+
+        Returns
+        -------
+        str — response text, or empty string if both models fail.
+        """
+        patient = patient or {}
+        history = history or []
+        margin  = abs(malignant_logit - benign_logit)
+        pct     = f"{confidence:.1%}"
+
+        # ── Build structured scan context ─────────────────────────────────────
+        scan_context = (
+            f"Prediction: {prediction.upper()}\n"
+            f"Confidence: {pct}\n"
+            f"Logits: benign={benign_logit:.4f}, malignant={malignant_logit:.4f}\n"
+            f"Decision margin: {margin:.4f} "
+            f"({'clear separation' if margin > 1.5 else 'near boundary — borderline'})\n"
+            f"Grad-CAM: {spatial_summary or 'not available'}\n"
+            f"Model: DenseNet-121 | Accuracy: 88.0% | Sensitivity: 87.5%"
+        )
+
+        # ── Build patient context ─────────────────────────────────────────────
+        patient_context = self._build_patient_context(patient)
+
+        # ── Stage 1: BioMedLM enrichment (best-effort) ───────────────────────
+        logger.info("Stage 1: BioMedLM enrichment...")
+        biomedlm_context = ""
+        try:
+            biomedlm_context = self.biomedlm.enrich(
+                prediction      = prediction,
+                confidence      = confidence,
+                benign_logit    = benign_logit,
+                malignant_logit = malignant_logit,
+                spatial_summary = spatial_summary,
+                patient         = patient,
+                question        = message,
+            )
+        except Exception as e:
+            logger.warning("BioMedLM enrichment failed: %s — continuing without it.", e)
+
+        if biomedlm_context:
+            logger.info("Stage 1 complete: BioMedLM provided %d words of enrichment.",
+                        len(biomedlm_context.split()))
+        else:
+            logger.info("Stage 1: No BioMedLM enrichment — Llama 3.2 will run standalone.")
+
+        # ── Stage 2: Llama 3.2 via Groq ──────────────────────────────────────
+        logger.info("Stage 2: Llama 3.2 via Groq (audience=%s)...", audience)
+        response = self.llama.generate(
+            audience         = audience,
+            user_message     = message,
+            scan_context     = scan_context,
+            patient_context  = patient_context,
+            biomedlm_context = biomedlm_context,
+            history          = history,
+        )
+
+        if response:
+            logger.info("Stage 2 complete: %d word response generated.", len(response.split()))
+            return response
+
+        # ── Both failed ───────────────────────────────────────────────────────
+        logger.warning("Both models failed — ChatEngine fallback will handle this.")
+        return ""
+
+    @staticmethod
+    def _build_patient_context(patient: dict) -> str:
+        """Format patient record into a clean context string."""
+        parts = []
+        if patient.get("name"):
+            parts.append(f"Name: {patient['name']}")
+        if patient.get("age"):
+            parts.append(f"Age: {patient['age']}")
+        if patient.get("sex"):
+            parts.append(f"Sex: {patient['sex']}")
+        if patient.get("medical_history"):
+            parts.append(f"Medical history: {patient['medical_history']}")
+        if patient.get("symptoms"):
+            parts.append(f"Current symptoms: {patient['symptoms']}")
+        if patient.get("previous_scans"):
+            parts.append(f"Previous scans: {patient['previous_scans']}")
+        return "\n".join(parts)
+
+
+# ── Factory function ──────────────────────────────────────────────────────────
+
+def create_pipeline(
+    groq_key:   Optional[str] = None,
+    hf_token:   Optional[str] = None,
+    groq_model: str           = "llama-3.1-8b-instant",
+) -> Optional[DualModelChatPipeline]:
+    """
+    Create a DualModelChatPipeline if both API keys are available.
+
+    Reads from environment variables if keys are not passed directly.
+    Returns None if either key is missing — the caller should fall back
+    to the deterministic ChatEngine.
+
+    Usage
+    -----
+    # Set env vars before starting the server:
+    export GROQ_API_KEY="gsk_..."
+    export HF_TOKEN="hf_..."
+
+    # In Python:
+    pipeline = create_pipeline()
+    if pipeline:
+        response = pipeline.respond(...)
+    else:
+        response = chat_engine.respond(...)
+    """
+    groq_key = groq_key or os.getenv("GROQ_API_KEY", "")
+    hf_token = hf_token or os.getenv("HF_TOKEN", "")
+
+    if not groq_key:
+        logger.info(
+            "GROQ_API_KEY not set — dual pipeline disabled. "
+            "Get a free key at console.groq.com"
+        )
+        return None
+
+    if not hf_token:
+        logger.info(
+            "HF_TOKEN not set — BioMedLM enrichment disabled. "
+            "Llama 3.2 will run without medical enrichment. "
+            "Get a free token at huggingface.co/settings/tokens"
+        )
+        # Can still run with just Groq — BioMedEnricher will return ""
+        # if called without a valid token
+        hf_token = ""
+
+    return DualModelChatPipeline(
+        groq_key   = groq_key,
+        hf_token   = hf_token,
+        groq_model = groq_model,
+    )

explainability/gradcam.py

@@ -0,0 +1,340 @@
+"""
+explainability/gradcam.py
+─────────────────────────
+Gradient-weighted Class Activation Mapping (Grad-CAM) for the
+BreastCancerClassifier.
+
+What it does
+────────────
+Grad-CAM answers the question:
+  "Which regions of this histopathology image most influenced
+   the model's prediction?"
+
+It hooks into the last DenseNet feature layer (denseblock4 → norm5),
+computes gradients of the predicted class score with respect to those
+spatial feature maps, then produces a colour heatmap the same size as
+the input image showing the most diagnostically relevant regions.
+
+How it connects to the existing architecture
+────────────────────────────────────────────
+  model/model.py       → GradCAM wraps BreastCancerClassifier
+                          Uses model.features (DenseNet backbone)
+                          Uses model.classifier (head)
+                          Uses model.pool (global avg pool)
+                          Does NOT modify any of them
+
+  model/inference.py   → GradCAM.explain() accepts the same image
+                          formats as BreastCancerInferencePipeline.predict()
+                          Returns logits compatible with inference output
+
+  utils/preprocessing  → GradCAM uses ImagePreprocessor internally
+
+Usage
+─────
+    import sys
+    sys.path.insert(0, "/path/to/medical-ai")
+
+    from model.model          import BreastCancerClassifier
+    from explainability        import GradCAM
+
+    model    = BreastCancerClassifier(pretrained=False)
+    # model.load_state_dict(torch.load("model/weights.pth")["state_dict"])
+
+    cam      = GradCAM(model)
+    result   = cam.explain("slide.png")
+
+    # result = {
+    #   "prediction"  : "malignant",
+    #   "confidence"  : 0.934,
+    #   "logits"      : tensor([[-2.14, 3.87]]),
+    #   "heatmap"     : np.ndarray  shape (224, 224)  values [0, 1]
+    #   "overlay"     : PIL.Image   heatmap blended on original image
+    #   "cam_raw"     : np.ndarray  unresized raw cam before upscale
+    # }
+
+    result["overlay"].save("gradcam_output.png")
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Optional, Union
+
+import numpy as np
+import torch
+import torch.nn as nn
+from PIL import Image
+
+# Allow running from any working directory
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+
+from utils.preprocessing import ImagePreprocessor
+
+# Label map — must match model/inference.py
+LABEL_MAP = {0: "benign", 1: "malignant"}
+
+# Colour map for heatmap overlay (BGR → RGB matplotlib-style jet)
+# Pre-computed jet colourmap: value in [0,1] → (R, G, B) in [0, 255]
+def _jet_colormap(value: float) -> tuple[int, int, int]:
+    """Map a scalar in [0,1] to an RGB colour using the jet colourmap."""
+    v = float(np.clip(value, 0.0, 1.0))
+    r = int(np.clip(1.5 - abs(4 * v - 3), 0, 1) * 255)
+    g = int(np.clip(1.5 - abs(4 * v - 2), 0, 1) * 255)
+    b = int(np.clip(1.5 - abs(4 * v - 1), 0, 1) * 255)
+    return r, g, b
+
+
+def _apply_jet_colormap(heatmap: np.ndarray) -> np.ndarray:
+    """
+    Convert a (H, W) float array in [0, 1] to a (H, W, 3) uint8 RGB array
+    using the jet colourmap. Avoids matplotlib dependency.
+    """
+    h, w = heatmap.shape
+    rgb  = np.zeros((h, w, 3), dtype=np.uint8)
+    for i in range(h):
+        for j in range(w):
+            rgb[i, j] = _jet_colormap(heatmap[i, j])
+    return rgb
+
+
+class GradCAM:
+    """
+    Grad-CAM for BreastCancerClassifier.
+
+    Hooks into the final DenseNet feature layer (norm5 — the batch norm
+    after denseblock4) to capture spatial activations and their gradients.
+    This layer produces (B, 1024, 7, 7) feature maps — the same tensor
+    that model.get_feature_maps() returns, now with gradient tracking.
+
+    Parameters
+    ----------
+    model : BreastCancerClassifier
+        The model to explain. Must be the same BreastCancerClassifier
+        from model/model.py — no modifications needed.
+    device : str | None
+        "cuda", "mps", or "cpu". Auto-detected if None.
+    target_layer : str
+        Name of the layer in model.features to hook.
+        Default "norm5" = final BatchNorm after denseblock4.
+        This is the deepest spatial layer before global pooling.
+    alpha : float
+        Blend weight for the overlay image. 0.0 = original only,
+        1.0 = heatmap only. Default 0.5.
+    """
+
+    def __init__(
+        self,
+        model:        "BreastCancerClassifier",
+        device:       Optional[str] = None,
+        target_layer: str           = "norm5",
+        alpha:        float         = 0.5,
+    ) -> None:
+        self.device       = self._resolve_device(device)
+        self.alpha        = alpha
+        self.preprocessor = ImagePreprocessor()
+
+        # Set model to eval — Grad-CAM still needs gradients but not
+        # dropout randomness. eval() disables dropout, keeps grad flow.
+        self.model = model.eval().to(self.device)
+
+        # ── Hook storage ──────────────────────────────────────────────────────
+        # These are filled by the forward and backward hooks on each call.
+        self._activations: Optional[torch.Tensor] = None
+        self._gradients:   Optional[torch.Tensor] = None
+
+        # ── Register hooks on the target layer ───────────────────────────────
+        # target_layer is a named layer inside model.features (DenseNet backbone)
+        # "norm5" is the final BatchNorm, output shape: (B, 1024, 7, 7)
+        target = dict(model.features.named_modules())[target_layer]
+
+        # Forward hook: fires after the layer's forward() — captures activations
+        target.register_forward_hook(self._save_activations)
+
+        # Backward hook: fires after gradients flow back — captures gradients
+        target.register_full_backward_hook(self._save_gradients)
+
+    # ── Hook callbacks ────────────────────────────────────────────────────────
+
+    def _save_activations(self, module, input, output) -> None:
+        """Called automatically after the target layer's forward pass."""
+        # Detach from graph — we only need the values, not to backprop through
+        # the stored activations themselves
+        self._activations = output.detach()
+
+    def _save_gradients(self, module, grad_input, grad_output) -> None:
+        """Called automatically during backward pass through the target layer."""
+        # grad_output[0] = gradients w.r.t. the layer's output tensor
+        self._gradients = grad_output[0].detach()
+
+    # ── Main API ──────────────────────────────────────────────────────────────
+
+    def explain(
+        self,
+        image: Union[str, Path, "Image.Image", np.ndarray, torch.Tensor],
+        class_idx: Optional[int] = None,
+    ) -> dict:
+        """
+        Run Grad-CAM on a single histopathology image.
+
+        Parameters
+        ----------
+        image : any format accepted by ImagePreprocessor
+            The histopathology patch or slide to explain.
+        class_idx : int | None
+            Which class to generate the heatmap for.
+            None (default) = use the predicted class (argmax).
+            0 = benign,  1 = malignant.
+
+        Returns
+        -------
+        dict
+            {
+                "prediction"  : str          — "benign" | "malignant"
+                "confidence"  : float        — probability of predicted class
+                "logits"      : Tensor[1,2]  — raw pre-softmax scores
+                "heatmap"     : ndarray      — (224,224) float in [0,1]
+                "overlay"     : PIL.Image    — heatmap blended onto image
+                "cam_raw"     : ndarray      — (7,7) unresized raw CAM
+            }
+        """
+        # ── Preprocess ────────────────────────────────────────────────────────
+        tensor = self.preprocessor(image).to(self.device)   # (1, 3, 224, 224)
+
+        # Keep original image for overlay (denormalize for display)
+        original_pil = self._tensor_to_pil(tensor[0])
+
+        # ── Forward pass WITH gradients ───────────────────────────────────────
+        # We cannot use torch.inference_mode() here — Grad-CAM requires
+        # gradients to flow backward through the network.
+        # model.eval() is still set so dropout is off.
+        tensor.requires_grad_(True)
+
+        output = self.model(tensor)          # {"logits": (1,2), "probs": (1,2)}
+        logits = output["logits"]            # (1, 2)
+        probs  = output["probs"]             # (1, 2)
+
+        # ── Determine target class ────────────────────────────────────────────
+        if class_idx is None:
+            class_idx = int(torch.argmax(probs, dim=1).item())
+
+        confidence  = float(probs[0, class_idx].item())
+        prediction  = LABEL_MAP[class_idx]
+
+        # ── Backward pass — gradients of class score w.r.t. feature maps ─────
+        self.model.zero_grad()
+
+        # Score for the target class — scalar
+        class_score = logits[0, class_idx]
+        class_score.backward()               # fills self._gradients via hook
+
+        # ── Compute Grad-CAM weights ──────────────────────────────────────────
+        # gradients: (1, 1024, 7, 7) — how much each spatial location in each
+        #            channel affected the class score
+        # Global average pool the gradients → (1, 1024, 1, 1)
+        # This gives the importance weight for each of the 1024 channels
+        weights = self._gradients.mean(dim=(2, 3), keepdim=True)  # (1, 1024, 1, 1)
+
+        # activations: (1, 1024, 7, 7) — what the layer actually responded to
+        # Weighted sum across channels → (1, 1, 7, 7)
+        # Each of 1024 channels is multiplied by its importance weight
+        cam = (weights * self._activations).sum(dim=1, keepdim=True)  # (1, 1, 7, 7)
+
+        # ── Post-process ──────────────────────────────────────────────────────
+        # ReLU: keep only positive contributions — negative means the region
+        # pushed AGAINST the predicted class, which we don't visualize
+        cam = torch.relu(cam)
+
+        # Convert to numpy, remove batch and channel dims → (7, 7)
+        cam_raw = cam[0, 0].cpu().numpy()
+
+        # Normalize to [0, 1]
+        cam_min, cam_max = cam_raw.min(), cam_raw.max()
+        if cam_max > cam_min:
+            cam_norm = (cam_raw - cam_min) / (cam_max - cam_min)
+        else:
+            cam_norm = np.zeros_like(cam_raw)
+
+        # Upsample from 7×7 to 224×224 using PIL (no scipy dependency)
+        heatmap = self._upsample_cam(cam_norm, size=(224, 224))
+
+        # ── Build overlay ─────────────────────────────────────────────────────
+        overlay = self._build_overlay(original_pil, heatmap)
+
+        return {
+            "prediction": prediction,
+            "confidence": round(confidence, 6),
+            "logits":     logits.detach().cpu(),
+            "heatmap":    heatmap,                # (224, 224) float [0, 1]
+            "overlay":    overlay,                # PIL.Image
+            "cam_raw":    cam_raw,                # (7, 7)   raw before upsample
+        }
+
+    # ── Helpers ───────────────────────────────────────────────────────────────
+
+    def _upsample_cam(self, cam: np.ndarray, size: tuple[int, int]) -> np.ndarray:
+        """
+        Upsample a (7, 7) CAM to the target size using PIL bilinear resize.
+        Returns a float32 ndarray normalized to [0, 1].
+        """
+        cam_uint8 = (cam * 255).astype(np.uint8)
+        cam_pil   = Image.fromarray(cam_uint8, mode="L")
+        cam_pil   = cam_pil.resize(size, Image.BILINEAR)
+        return np.array(cam_pil, dtype=np.float32) / 255.0
+
+    def _build_overlay(
+        self,
+        original: "Image.Image",
+        heatmap:  np.ndarray,
+    ) -> "Image.Image":
+        """
+        Blend the jet-coloured heatmap onto the original image.
+
+        Parameters
+        ----------
+        original : PIL.Image  — original image at 224×224
+        heatmap  : ndarray    — (224, 224) float in [0, 1]
+
+        Returns
+        -------
+        PIL.Image  — RGBA blended result
+        """
+        # Colour the heatmap using jet colourmap
+        jet_rgb = _apply_jet_colormap(heatmap)    # (224, 224, 3) uint8
+        jet_pil = Image.fromarray(jet_rgb, mode="RGB")
+
+        # Ensure original is RGB
+        original_rgb = original.convert("RGB")
+
+        # Blend: overlay = (1 - alpha) * original + alpha * heatmap
+        overlay = Image.blend(original_rgb, jet_pil, alpha=self.alpha)
+        return overlay
+
+    @staticmethod
+    def _tensor_to_pil(tensor: torch.Tensor) -> "Image.Image":
+        """
+        Convert a (3, H, W) normalized tensor back to a PIL Image for display.
+        Reverses ImageNet normalization so the image looks natural.
+        """
+        # ImageNet mean / std — same constants as preprocessing.py
+        mean = torch.tensor([0.485, 0.456, 0.406]).view(3, 1, 1)
+        std  = torch.tensor([0.229, 0.224, 0.225]).view(3, 1, 1)
+
+        # Denormalize: x_original = x_normalized * std + mean
+        img = tensor.detach().cpu() * std + mean
+        img = img.clamp(0, 1)
+
+        # Convert to uint8 PIL Image
+        arr = (img.permute(1, 2, 0).numpy() * 255).astype(np.uint8)
+        return Image.fromarray(arr, mode="RGB")
+
+    @staticmethod
+    def _resolve_device(device: Optional[str]) -> torch.device:
+        if device is not None:
+            return torch.device(device)
+        if torch.cuda.is_available():
+            return torch.device("cuda")
+        if torch.backends.mps.is_available():
+            return torch.device("mps")
+        return torch.device("cpu")

explainability/llm_chat.py

@@ -0,0 +1,188 @@
+"""
+explainability/llm_chat.py
+───────────────────────────
+A real conversational LLM for the platform's AI assistant — defaults to
+GROQ (free, no credit card), with Anthropic / OpenAI as optional providers.
+Streams tokens so the assistant behaves like ChatGPT, while staying grounded
+in this platform's models, metrics, and the current scan context.
+
+Why Groq
+────────
+  Groq's free tier serves open-source models (Llama 3.3 70B etc.) on very
+  fast LPU hardware, with no credit card. It's OpenAI-API-compatible, so it
+  works as a drop-in via the OpenAI SDK pointed at Groq's base URL. Unlike
+  Ollama it needs no GPU server of your own — ideal for a deployed website.
+
+Configuration (environment variables)
+──────────────────────────────────────
+  CHAT_PROVIDER   "groq" (default) | "anthropic" | "openai"
+  CHAT_MODEL      model id. Defaults:
+                    groq      → llama-3.3-70b-versatile   (ChatGPT-quality)
+                                (use llama-3.1-8b-instant for higher limits)
+                    anthropic → claude-3-5-haiku-latest
+                    openai    → gpt-4o-mini
+  GROQ_API_KEY        required for groq      (console.groq.com — free)
+  ANTHROPIC_API_KEY   required for anthropic (paid)
+  OPENAI_API_KEY      required for openai    (paid)
+
+Install the SDK (Groq uses the OpenAI SDK):
+  pip install openai          # for groq or openai
+  pip install anthropic       # only if you choose anthropic
+
+Deployment
+──────────
+  Set GROQ_API_KEY as an environment variable / secret on your host
+  (Render, Railway, Fly, a VPS, etc.). NEVER put the key in the frontend.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Iterator
+
+GROQ_BASE_URL = "https://api.groq.com/openai/v1"
+
+SYSTEM_PROMPT = """You are MedAI's assistant — a sharp, articulate expert in medical-imaging AI, deep learning, and radiology, with broad general knowledge. You think clearly and engage like a thoughtful senior colleague (in the spirit of ChatGPT or Claude): you reason through problems, give intuition and concrete examples, use analogies, structure substantial answers with headers and lists, and anticipate the next question.
+
+You live inside MedAI, a research platform for breast-cancer detection from medical images. When asked about "this platform", ground answers in these facts:
+- Histopathology: a DenseNet-121 CNN trained on PatchCamelyon (PCam) — H&E-stained lymph-node patches. ~88.0% accuracy, 87.5% sensitivity. Explained with Grad-CAM.
+- Mammography: a 3-model EfficientNet-B4 ensemble trained on RSNA 2022. 0.84 AUC, 70.1% sensitivity, 82.4% specificity on the RSNA validation set. Explained with Grad-CAM.
+- An experiment adding breast-ROI cropping + external CBIS-DDSM data reduced performance (cross-domain film-vs-digital shift plus overfitting), so the platform kept the un-cropped RSNA-only ensemble.
+
+You are NOT limited to reciting those facts. Discuss the underlying ML and medicine in real depth — architectures, training methods, loss functions, class imbalance, metrics (AUC, sensitivity/specificity, calibration, operating points), Grad-CAM, BI-RADS, dataset pitfalls, external validation, regulatory paths, deployment — and answer broader questions intelligently. Bring genuine insight: explain *why*, not just *what*.
+
+Style:
+- You are in a CHAT panel, not a document. Keep replies conversational and reasonably brief — usually a few short paragraphs, with bullet or numbered lists where they genuinely help. Expand into depth only when the question truly calls for it.
+- Do NOT use markdown tables. The chat panel is narrow (often mobile) and cannot render them — they come out as garbled pipes. Convey the same information as short paragraphs or bullet lists instead.
+- Use light markdown only: **bold**, bullet/numbered lists, and `inline code`. Use ## headers sparingly and only in genuinely long answers. Don't turn a chat reply into a multi-section report with FAQs unless the user explicitly asks for that.
+- Be direct and concrete; explain the "why" and name tradeoffs rather than padding.
+
+Safety (non-negotiable):
+- This is a research/educational tool — NOT a medical device, NOT a diagnosis. Never tell anyone they do or don't have cancer, and never give definitive clinical advice; a qualified clinician makes the call. Be honest about limits (e.g. 70% mammogram sensitivity means roughly 1 in 3 cancers can be missed).
+- Do not treat the model's confidence score as a calibrated probability of being correct — the model is not calibrated. Say it "leans toward" a label or is "not certain", rather than quoting the percentage as a literal chance of error (e.g. don't say "76% confidence means a 24% chance it's wrong").
+- Adapt tone to the audience when indicated — clinician (clinical framing, BI-RADS, workup), researcher (ML/technical depth), patient (plain, calm, reassuring; encourage seeing their doctor) — while staying clear and professional.
+"""
+
+
+def _default_model(provider: str) -> str:
+    return {
+        "groq":      "openai/gpt-oss-120b",
+        "anthropic": "claude-3-5-haiku-latest",
+        "openai":    "gpt-4o-mini",
+    }.get(provider, "openai/gpt-oss-120b")
+
+
+def llm_available() -> tuple[bool, str]:
+    """Return (available, provider) — whether an API key is configured."""
+    provider = os.getenv("CHAT_PROVIDER", "groq").lower()
+    key = {
+        "groq":      "GROQ_API_KEY",
+        "anthropic": "ANTHROPIC_API_KEY",
+        "openai":    "OPENAI_API_KEY",
+    }.get(provider, "GROQ_API_KEY")
+    return (bool(os.getenv(key)), provider)
+
+
+def _context_block(context: dict | None, audience: str) -> str:
+    lines = [f"Audience mode: {audience}."]
+    if context:
+        pred = context.get("prediction")
+        if pred:
+            conf = context.get("confidence", 0.0)
+            lines.append(
+                f"Current scan in view — model prediction: {pred} "
+                f"({conf*100:.1f}% confidence)."
+            )
+            logits = context.get("logits") or []
+            if len(logits) >= 2:
+                lines.append(f"Raw logits: benign={logits[0]:.3f}, malignant={logits[1]:.3f}.")
+            spatial = context.get("spatial_summary")
+            if spatial:
+                lines.append(f"Grad-CAM spatial finding: {spatial}")
+            birads = context.get("birads")
+            if birads:
+                lines.append(f"Suggested BI-RADS: {birads}.")
+    else:
+        lines.append("No scan is currently loaded; answer about the platform or general concepts.")
+    return "\n".join(lines)
+
+
+def _openai_compatible_stream(system: str, messages: list[dict], model: str,
+                              base_url: str | None, api_key_env: str) -> Iterator[str]:
+    """Shared streamer for OpenAI-compatible endpoints (OpenAI and Groq)."""
+    try:
+        from openai import OpenAI
+    except ImportError:
+        yield "The OpenAI SDK isn't installed. Run: pip install openai"
+        return
+    try:
+        kwargs = {}
+        if base_url:
+            kwargs["base_url"] = base_url
+        kwargs["api_key"] = os.getenv(api_key_env)
+        client = OpenAI(**kwargs)
+        stream = client.chat.completions.create(
+            model=model,
+            messages=[{"role": "system", "content": system}] + messages,
+            max_tokens=2048, temperature=0.6, stream=True,
+        )
+        for chunk in stream:
+            delta = chunk.choices[0].delta.content
+            if delta:
+                yield delta
+    except Exception as e:  # noqa: BLE001
+        yield f"\n[LLM error: {e}]"
+
+
+def _anthropic_stream(system: str, messages: list[dict], model: str) -> Iterator[str]:
+    try:
+        import anthropic
+    except ImportError:
+        yield "The Anthropic SDK isn't installed. Run: pip install anthropic"
+        return
+    try:
+        client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY
+        with client.messages.stream(
+            model=model, max_tokens=1024, system=system, messages=messages,
+        ) as stream:
+            for text in stream.text_stream:
+                yield text
+    except Exception as e:  # noqa: BLE001
+        yield f"\n[LLM error: {e}]"
+
+
+def stream_chat(
+    messages: list[dict],
+    context: dict | None = None,
+    audience: str = "clinician",
+) -> Iterator[str]:
+    """
+    Stream an assistant reply token-by-token.
+
+    messages: list of {"role": "user"|"assistant", "content": str} (history,
+              ending with the latest user turn).
+    context:  optional dict with prediction/confidence/logits/spatial_summary/birads.
+    """
+    available, provider = llm_available()
+    if not available:
+        key = {"groq": "GROQ_API_KEY", "anthropic": "ANTHROPIC_API_KEY",
+               "openai": "OPENAI_API_KEY"}.get(provider, "GROQ_API_KEY")
+        yield (f"The AI assistant needs an API key. Get a free one at "
+               f"console.groq.com, then set {key} in the environment and restart "
+               f"the API (CHAT_PROVIDER defaults to 'groq').")
+        return
+
+    system = SYSTEM_PROMPT + "\n\n" + _context_block(context, audience)
+    clean = [{"role": m["role"], "content": str(m["content"])}
+             for m in messages if m.get("role") in ("user", "assistant") and m.get("content")]
+    if not clean:
+        clean = [{"role": "user", "content": "Hello"}]
+
+    model = os.getenv("CHAT_MODEL", _default_model(provider))
+
+    if provider == "anthropic":
+        yield from _anthropic_stream(system, clean, model)
+    elif provider == "openai":
+        yield from _openai_compatible_stream(system, clean, model, None, "OPENAI_API_KEY")
+    else:  # groq (default)
+        yield from _openai_compatible_stream(system, clean, model, GROQ_BASE_URL, "GROQ_API_KEY")

explainability/llm_explain.py

@@ -0,0 +1,1125 @@
+"""
+explainability/llm_explain.py
+──────────────────────────────
+Local LLM-powered natural language explanation of model predictions.
+Built from scratch using HuggingFace Transformers — no external API,
+no API key, runs entirely on your machine.
+
+Architecture
+────────────
+  Tokenizer  : AutoTokenizer  (google/flan-t5-base)
+  Model      : T5ForConditionalGeneration
+  Inference  : beam search, greedy decode, or sampling
+  Fallback   : deterministic template engine (works with no model at all)
+
+FLAN-T5 was chosen because:
+  - Instruction-tuned  → responds well to structured prompts
+  - No API key needed  → fully self-contained
+  - Reasonable size    → flan-t5-base is ~250 MB, runs on CPU
+  - Medical text       → handles clinical terminology cleanly
+  - You've used it before in RialoLens AI Explainer Engine
+
+Model variants (pass as model_name)
+────────────────────────────────────
+  "google/flan-t5-small"   ~80 MB   fastest, lowest quality
+  "google/flan-t5-base"    ~250 MB  ← default, good balance
+  "google/flan-t5-large"   ~780 MB  better quality, needs more RAM
+  "google/flan-t5-xl"      ~3 GB    best quality, needs GPU
+
+How it connects to the existing architecture
+────────────────────────────────────────────
+  model/inference.py        → consumes its prediction dict output
+  explainability/gradcam.py → optionally consumes Grad-CAM result dict
+  No existing files are modified.
+
+Usage
+─────
+    from model.inference    import BreastCancerInferencePipeline
+    from explainability     import GradCAM, LLMExplainer
+
+    pipeline = BreastCancerInferencePipeline("model/weights.pth")
+    result   = pipeline.predict("slide.png")
+
+    # Basic explanation
+    llm    = LLMExplainer()                        # downloads model once
+    report = llm.explain(result, audience="clinician")
+    print(report["summary"])
+
+    # With Grad-CAM spatial context
+    cam        = GradCAM(pipeline.model)
+    cam_result = cam.explain("slide.png")
+    report     = llm.explain_with_gradcam(cam_result, audience="patient")
+    print(report["detail"])
+
+Install
+───────
+  pip install transformers sentencepiece accelerate
+"""
+
+from __future__ import annotations
+
+import sys
+import textwrap
+from pathlib import Path
+from typing import Literal, Optional
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+
+# Audience type
+Audience = Literal["clinician", "researcher", "patient"]
+
+
+# ╔══════════════════════════════════════════════════════════════════════════════╗
+# ║  FLAN-T5 BACKBONE                                                           ║
+# ╚══════════════════════════════════════════════════════════════════════════════╝
+
+class FlanT5Engine:
+    """
+    Thin wrapper around FLAN-T5 for text generation.
+
+    Downloads the model once on first use and caches it to
+    ~/.cache/huggingface/hub (HuggingFace default).
+
+    Parameters
+    ----------
+    model_name : str
+        HuggingFace model identifier. Default: google/flan-t5-base
+    device : str
+        "cuda", "mps", or "cpu". Auto-detected if None.
+    max_new_tokens : int
+        Maximum tokens to generate per explanation. Default 256.
+    """
+
+    def __init__(
+        self,
+        model_name:     str           = "google/flan-t5-large",
+        device:         Optional[str] = None,
+        max_new_tokens: int           = 256,
+    ) -> None:
+        self.model_name     = model_name
+        self.max_new_tokens = max_new_tokens
+        self.device         = self._resolve_device(device)
+
+        self._tokenizer = None
+        self._model     = None
+
+    # ── Lazy loading — model loads on first generate() call ──────────────────
+
+    def _load(self) -> None:
+        """Download / load tokenizer and model into memory."""
+        if self._model is not None:
+            return   # already loaded
+
+        try:
+            from transformers import AutoTokenizer, T5ForConditionalGeneration
+        except ImportError:
+            raise ImportError(
+                "transformers not installed.\n"
+                "Run: pip install transformers sentencepiece"
+            )
+
+        import torch
+
+        print(f"[LLMExplainer] Loading {self.model_name} …")
+        print(f"[LLMExplainer] Device: {self.device}")
+        print("[LLMExplainer] First run downloads ~250 MB, cached afterwards.")
+
+        self._tokenizer = AutoTokenizer.from_pretrained(self.model_name)
+
+        self._model = T5ForConditionalGeneration.from_pretrained(
+            self.model_name,
+            torch_dtype=torch.float16 if self.device != "cpu" else torch.float32,
+        ).to(self.device)
+
+        self._model.eval()
+        print(f"[LLMExplainer] Model ready.")
+
+    def generate(self, prompt: str) -> str:
+        """
+        Generate text from a prompt using FLAN-T5.
+
+        Parameters
+        ----------
+        prompt : str
+            Instruction-style prompt in the T5 format.
+
+        Returns
+        -------
+        str — generated text, decoded and stripped.
+        """
+        import torch
+
+        self._load()
+
+        inputs = self._tokenizer(
+            prompt,
+            return_tensors="pt",
+            truncation=True,
+            max_length=512,           # T5 input limit
+        ).to(self.device)
+
+        with torch.inference_mode():
+            output_ids = self._model.generate(
+                **inputs,
+                max_new_tokens  = self.max_new_tokens,
+                num_beams       = 4,          # beam search — better quality
+                early_stopping  = True,
+                no_repeat_ngram_size = 3,     # reduce repetition
+                length_penalty  = 1.2,        # encourage longer outputs
+            )
+
+        decoded = self._tokenizer.decode(
+            output_ids[0],
+            skip_special_tokens=True,
+        )
+        return decoded.strip()
+
+    def generate_chat(self, prompt: str) -> str:
+        """
+        Generate a conversational chat response using FLAN-T5.
+
+        Uses temperature sampling instead of beam search to produce
+        natural, varied, human-sounding responses rather than mechanical outputs.
+
+        Parameters
+        ----------
+        prompt : str
+            Conversational prompt with full context and instruction.
+
+        Returns
+        -------
+        str — generated text, decoded and stripped.
+        """
+        import torch
+
+        self._load()
+
+        inputs = self._tokenizer(
+            prompt,
+            return_tensors = "pt",
+            truncation     = True,
+            max_length     = 512,
+        ).to(self.device)
+
+        with torch.inference_mode():
+            output_ids = self._model.generate(
+                **inputs,
+                max_new_tokens       = 400,
+                do_sample            = True,    # sampling for natural variety
+                temperature          = 0.8,     # slightly creative but still coherent
+                top_p                = 0.92,    # nucleus sampling
+                no_repeat_ngram_size = 3,
+                repetition_penalty   = 1.3,
+            )
+
+        decoded = self._tokenizer.decode(
+            output_ids[0],
+            skip_special_tokens = True,
+        )
+        return decoded.strip()
+
+    @staticmethod
+    def _resolve_device(device: Optional[str]) -> str:
+        import torch
+        if device is not None:
+            return device
+        if torch.cuda.is_available():
+            return "cuda"
+        if torch.backends.mps.is_available():
+            return "mps"
+        return "cpu"
+
+
+# ╔══════════════════════════════════════════════════════════════════════════════╗
+# ║  TEMPLATE ENGINE — deterministic fallback                                   ║
+# ╚══════════════════════════════════════════════════════════════════════════════╝
+
+class TemplateEngine:
+    """
+    Audience-aware deterministic explanation engine.
+    Produces genuinely different content for clinician, researcher, and patient.
+    """
+
+    TIERS = [
+        (0.95, "very high",  "very high confidence"),
+        (0.85, "high",       "high confidence"),
+        (0.70, "moderate",   "moderate confidence"),
+        (0.55, "borderline", "borderline confidence — treat with caution"),
+        (0.00, "low",        "low confidence — result unreliable without further review"),
+    ]
+
+    def confidence_tier(self, conf: float) -> tuple[str, str]:
+        for threshold, label, desc in self.TIERS:
+            if conf >= threshold:
+                return label, desc
+        return "low", "low confidence"
+
+    # Modality-specific facts so explanations name the right model, dataset,
+    # reviewer, and sample type. Histopathology = DenseNet/PCam/pathologist;
+    # mammogram = EfficientNet-B4 ensemble/RSNA/radiologist.
+    MODALITY = {
+        "histopathology": {
+            "model":        "DenseNet-121",
+            "sample":       "patch",
+            "sample_plain": "tissue sample",
+            "metrics":      "87.5% sensitivity and 88.0% accuracy on the held-out PCam test set",
+            "reviewer":     "pathologist",
+            "correlation":  "histomorphological correlation",
+            "pos_action":   "tissue biopsy and full clinical assessment",
+            "neg_action":   "Routine 12-month follow-up is appropriate if clinically indicated.",
+            "imaging_desc": "checks tissue under a microscope",
+            "abnormal":     "abnormal cells",
+            "model_full":   "DenseNet-121 (7.22M params) fine-tuned on 220,025 "
+                            "deduplicated PCam patches",
+            "train_detail": "OneCycleLR (max_lr=3e-3), Mixup (α=0.4), StainJitter "
+                            "(HED, strength=0.05), label smoothing (0.1), "
+                            "CrossEntropyLoss (pos_weight=1.469)",
+            "metrics_short":"Best test sensitivity: 87.5%, accuracy: 88.0%",
+        },
+        "mammogram": {
+            "model":        "the EfficientNet-B4 ensemble",
+            "sample":       "mammogram",
+            "sample_plain": "mammogram",
+            "metrics":      "0.84 AUC (70.1% sensitivity, 82.4% specificity) on the "
+                            "RSNA validation set",
+            "reviewer":     "radiologist",
+            "correlation":  "radiological correlation",
+            "pos_action":   "a diagnostic mammographic work-up and possible biopsy",
+            "neg_action":   "Routine screening follow-up is appropriate per BI-RADS guidance.",
+            "imaging_desc": "reviews the breast X-ray image",
+            "abnormal":     "an abnormal area",
+            "model_full":   "a 3-model EfficientNet-B4 ensemble trained on the RSNA 2022 "
+                            "mammography dataset (54,706 images)",
+            "train_detail": "3× EfficientNet-B4 (seeds 42/123/999), WeightedRandomSampler "
+                            "for class balance, AMP mixed precision, CrossEntropyLoss "
+                            "(weight=[1,5]), predictions averaged across members",
+            "metrics_short":"Ensemble AUC: 0.84 (sensitivity 70.1%, specificity 82.4%)",
+        },
+    }
+
+    def build(
+        self,
+        prediction:      str,
+        confidence:      float,
+        benign_logit:    float,
+        malignant_logit: float,
+        audience:        Audience,
+        gradcam_context: Optional[str] = None,
+        modality:        str           = "histopathology",
+        birads:          Optional[str] = None,
+    ) -> tuple[str, str]:
+        tier_label, tier_desc = self.confidence_tier(confidence)
+        pct        = f"{confidence:.1%}"
+        margin     = abs(malignant_logit - benign_logit)
+        is_mal     = prediction == "malignant"
+        cam        = gradcam_context or ""
+        f          = self.MODALITY.get(modality, self.MODALITY["histopathology"])
+
+        # ── CLINICIAN ─────────────────────────────────────────────────────────
+        if audience == "clinician":
+            # Use the caller-supplied BI-RADS (from the ensemble) when available,
+            # otherwise fall back to a confidence-derived suggestion.
+            birad = birads or (
+                "BI-RADS 4B — Suspicious" if is_mal and confidence >= 0.75 else
+                "BI-RADS 4A — Low suspicion" if is_mal else
+                "BI-RADS 2 — Benign finding"
+            )
+            boundary = (
+                "The decision margin of {:.3f} indicates a clear separation "
+                "from the decision boundary, supporting diagnostic reliability.".format(margin)
+                if margin > 1.5 else
+                "The decision margin of {:.3f} places this case near the "
+                "classification boundary — a borderline result requiring careful "
+                "{}.".format(margin, f["correlation"])
+            )
+            cam_line = (
+                f" Grad-CAM spatial analysis: {cam}"
+                if cam else
+                " Grad-CAM spatial attention maps are available for region-level review."
+            )
+            summary = (
+                f"{f['model']} classified this {f['sample']} as "
+                f"{'MALIGNANT' if is_mal else 'BENIGN'} at {pct} ({tier_desc}). "
+                f"Raw logits: benign = {benign_logit:.4f}, malignant = {malignant_logit:.4f} "
+                f"(margin: {margin:.4f}). "
+                f"Suggested {birad}."
+            )
+            detail = (
+                f"{boundary}"
+                f"{cam_line} "
+                f"Underlying model performance: {f['metrics']}. "
+                f"{('A positive result warrants ' + f['pos_action'] + '.') if is_mal else f['neg_action']} "
+                f"This output is AI-assisted and must not replace {f['reviewer']} review."
+            )
+
+        # ── RESEARCHER ────────────────────────────────────────────────────────
+        elif audience == "researcher":
+            softmax_b = round(1 / (1 + 2.718 ** (malignant_logit - benign_logit)), 4)
+            softmax_m = round(1 - softmax_b, 4)
+            cam_line  = f" Grad-CAM activation summary: {cam}" if cam else ""
+            summary = (
+                f"Classification output: {prediction.upper()} "
+                f"[softmax({benign_logit:.4f}, {malignant_logit:.4f}) = "
+                f"({softmax_b:.4f}, {softmax_m:.4f})]. "
+                f"Argmax class = {'1 (malignant)' if is_mal else '0 (benign)'}. "
+                f"Decision margin |Δlogit| = {margin:.4f} "
+                f"({'above' if margin > 1.5 else 'below'} the 1.5 heuristic threshold "
+                f"for high-confidence separation)."
+            )
+            detail = (
+                f"Model: {f['model_full']}. Training: {f['train_detail']}. "
+                f"{f['metrics_short']}. "
+                f"Softmax probabilities are uncalibrated — no temperature scaling applied."
+                f"{cam_line}"
+            )
+
+        # ── PATIENT ───────────────────────────────────────────────────────────
+        else:
+            sample = f["sample_plain"]
+            if is_mal:
+                if confidence >= 0.85:
+                    summary = (
+                        f"The AI system flagged an area in this {sample} that looks "
+                        f"unusual, and it is fairly confident about this ({pct}). "
+                        f"This is a signal that a doctor should take a closer look — "
+                        f"it does not mean you definitely have cancer."
+                    )
+                    detail = (
+                        f"Think of this AI like a second set of eyes that {f['imaging_desc']}. "
+                        f"It spotted a pattern it associates with {f['abnormal']} in this {sample}. "
+                        f"{'The AI was also looking at the ' + cam.split('.')[0].lower() + ' area most closely.' if cam else ''} "
+                        f"Your doctor will review this result and decide the right next step — "
+                        f"this might be a follow-up scan or a biopsy. Please do not worry "
+                        f"until you have spoken with your healthcare provider. "
+                        f"This AI tool is for screening only, not a final diagnosis."
+                    )
+                else:
+                    summary = (
+                        f"The AI system found something in this {sample} that it "
+                        f"wasn't entirely sure about ({pct} confidence). "
+                        f"The result is uncertain and will need your doctor's review "
+                        f"before any conclusions are drawn."
+                    )
+                    detail = (
+                        f"This means the AI could not clearly decide whether the {sample} "
+                        f"looks normal or abnormal — it is on the borderline. "
+                        f"This happens sometimes with difficult cases. "
+                        f"Your doctor is the right person to interpret this alongside "
+                        f"your full medical history and any other tests. "
+                        f"This AI tool is a screening aid only, not a diagnosis."
+                    )
+            else:
+                summary = (
+                    f"The AI system found no signs of an abnormality in this {sample} "
+                    f"({pct} confidence). This is a reassuring result."
+                )
+                detail = (
+                    f"The AI {f['imaging_desc']} and did not find features it associates "
+                    f"with cancer. "
+                    f"This is a good sign, but all AI results should be confirmed by "
+                    f"your doctor as part of your complete care. "
+                    f"{'The AI was paying attention to ' + cam.split('.')[0].lower() + '.' if cam else ''} "
+                    f"Please keep any follow-up appointments your doctor recommends. "
+                    f"This AI tool is for screening only, not a final diagnosis."
+                )
+
+        detail = detail.strip()
+        return summary, detail
+
+
+# ╔══════════════════════════════════════════════════════════════════════════════╗
+# ║  PROMPT BUILDER                                                             ║
+# ╚══════════════════════════════════════════════════════════════════════════════╝
+
+class PromptBuilder:
+    """
+    Builds FLAN-T5 instruction prompts from structured prediction data.
+
+    FLAN-T5 responds best to explicit task instructions in the format:
+      "Task description: [context]. Answer:"
+    """
+
+    AUDIENCE_CONTEXT = {
+        "clinician": (
+            "a clinical pathologist who needs precise technical details, "
+            "logit scores, confidence calibration, and clinical caveats"
+        ),
+        "researcher": (
+            "an ML researcher who wants to understand the model's decision "
+            "in terms of logit scores, softmax probabilities, and feature analysis"
+        ),
+        "patient": (
+            "a patient with no medical background who needs a clear, "
+            "compassionate explanation without jargon"
+        ),
+    }
+
+    def build(
+        self,
+        prediction:      str,
+        confidence:      float,
+        benign_logit:    float,
+        malignant_logit: float,
+        audience:        Audience,
+        gradcam_context: Optional[str] = None,
+    ) -> str:
+        """Construct the instruction prompt for FLAN-T5."""
+
+        tier = (
+            "high" if confidence >= 0.85 else
+            "moderate" if confidence >= 0.70 else
+            "low"
+        )
+
+        cam_section = (
+            f" The Grad-CAM spatial analysis shows: {gradcam_context}"
+            if gradcam_context else ""
+        )
+
+        prompt = textwrap.dedent(f"""
+            Explain a breast cancer AI classifier result to {self.AUDIENCE_CONTEXT[audience]}.
+
+            Model result:
+            - Prediction: {prediction.upper()}
+            - Confidence: {confidence:.1%} ({tier} confidence)
+            - Benign logit score: {benign_logit:.3f}
+            - Malignant logit score: {malignant_logit:.3f}{cam_section}
+
+            Write a clear 3-sentence explanation of what this result means,
+            what the confidence level implies, and remind the reader this is
+            a research tool that requires clinical confirmation.
+
+            Explanation:
+        """).strip()
+
+        return prompt
+
+
+# ╔══════════════════════════════════════════════════════════════════════════════╗
+# ║  MAIN EXPLAINER CLASS                                                       ║
+# ╚══════════════════════════════════════════════════════════════════════════════╝
+
+class LLMExplainer:
+    """
+    Local LLM-powered natural language explainer for breast cancer predictions.
+
+    Uses FLAN-T5 running entirely on your machine — no API key, no internet
+    connection required after the initial model download.
+
+    Falls back to a deterministic template engine if:
+      - use_llm=False is passed
+      - transformers is not installed
+      - The model fails to generate meaningful output
+
+    Parameters
+    ----------
+    model_name : str
+        HuggingFace FLAN-T5 variant. Default: google/flan-t5-base (~250 MB).
+    device : str | None
+        "cuda", "mps", or "cpu". Auto-detected if None.
+    max_new_tokens : int
+        Max tokens per generated explanation. Default 256.
+    use_llm : bool
+        Set False to skip FLAN-T5 and use the template engine directly.
+        Useful for fast testing or environments without GPU/internet.
+    """
+
+    DISCLAIMER = (
+        "Research and educational use only. "
+        "Not a standalone diagnostic tool. "
+        "Clinical confirmation by a qualified pathologist is required."
+    )
+
+    def __init__(
+        self,
+        model_name:     str           = "google/flan-t5-large",
+        device:         Optional[str] = None,
+        max_new_tokens: int           = 256,
+        use_llm:        bool          = True,
+    ) -> None:
+        self.use_llm         = use_llm
+        self._prompt_builder = PromptBuilder()
+        self._template       = TemplateEngine()
+
+        if use_llm:
+            self._llm = FlanT5Engine(
+                model_name     = model_name,
+                device         = device,
+                max_new_tokens = max_new_tokens,
+            )
+        else:
+            self._llm = None
+            print("[LLMExplainer] Running in template-only mode (use_llm=False).")
+
+    # ── Public API ────────────────────────────────────────────────────────────
+
+    def explain(
+        self,
+        prediction: dict,
+        audience:   Audience = "clinician",
+        modality:   str      = "histopathology",
+    ) -> dict:
+        """
+        Generate a natural language explanation from an inference.py output dict.
+
+        Parameters
+        ----------
+        prediction : dict
+            Output from a predict() call:
+            {"prediction": str, "confidence": float, "logits": Tensor[1,2],
+             "birads": str (optional)}
+        audience : "clinician" | "researcher" | "patient"
+        modality : "histopathology" | "mammogram"
+
+        Returns
+        -------
+        dict
+            {
+                "summary"    : str   — plain-language summary
+                "detail"     : str   — deeper explanation with confidence context
+                "disclaimer" : str   — standard research disclaimer
+                "audience"   : str   — target audience
+                "engine"     : str   — "flan-t5" | "template"
+            }
+        """
+        pred, conf, b_logit, m_logit = self._unpack(prediction)
+        birads = prediction.get("birads") if isinstance(prediction, dict) else None
+        return self._generate(pred, conf, b_logit, m_logit, audience,
+                              gradcam_context=None, modality=modality, birads=birads)
+
+    def explain_with_gradcam(
+        self,
+        gradcam_result: dict,
+        audience:       Audience = "clinician",
+        modality:       str      = "histopathology",
+    ) -> dict:
+        """
+        Generate an explanation that incorporates Grad-CAM spatial findings.
+
+        Parameters
+        ----------
+        gradcam_result : dict
+            Output from a GradCAM.explain() call:
+            {"prediction", "confidence", "logits", "heatmap", "birads"(optional), ...}
+        audience : "clinician" | "researcher" | "patient"
+        modality : "histopathology" | "mammogram"
+
+        Returns
+        -------
+        Same schema as explain() — adds spatial activation context.
+        """
+        pred, conf, b_logit, m_logit = self._unpack(gradcam_result)
+        gradcam_context = self._summarise_heatmap(gradcam_result["heatmap"])
+        birads = gradcam_result.get("birads") if isinstance(gradcam_result, dict) else None
+        return self._generate(pred, conf, b_logit, m_logit, audience,
+                              gradcam_context=gradcam_context, modality=modality,
+                              birads=birads)
+
+    # ── Internal generation flow ──────────────────────────────────────────────
+
+    def _generate(
+        self,
+        prediction:      str,
+        confidence:      float,
+        benign_logit:    float,
+        malignant_logit: float,
+        audience:        Audience,
+        gradcam_context: Optional[str],
+        modality:        str           = "histopathology",
+        birads:          Optional[str] = None,
+    ) -> dict:
+        """
+        Core generation method. Tries FLAN-T5 first, falls back to template.
+        """
+        summary, detail = self._template.build(
+            prediction      = prediction,
+            confidence      = confidence,
+            benign_logit    = benign_logit,
+            malignant_logit = malignant_logit,
+            audience        = audience,
+            gradcam_context = gradcam_context,
+            modality        = modality,
+            birads          = birads,
+        )
+        engine_used = "template"
+
+        # ── Optional FLAN-T5 enhancement ─────────────────────────────────────
+        if self.use_llm and self._llm is not None:
+            try:
+                prompt = self._prompt_builder.build(
+                    prediction      = prediction,
+                    confidence      = confidence,
+                    benign_logit    = benign_logit,
+                    malignant_logit = malignant_logit,
+                    audience        = audience,
+                    gradcam_context = gradcam_context,
+                )
+                generated = self._llm.generate(prompt)
+                if len(generated.split()) >= 20:
+                    # Append FLAN-T5 output to template detail — don't replace it
+                    detail = detail + " " + generated.strip()
+                    engine_used = "flan-t5"
+            except Exception as e:
+                print(f"[LLMExplainer] FLAN-T5 enhancement failed ({e}) — template only.")
+
+        return {
+            "summary":     summary,
+            "detail":      detail,
+            "disclaimer":  self.DISCLAIMER,
+            "audience":    audience,
+            "engine":      engine_used,
+        }
+
+    # ── Helpers ───────────────────────────────────────────────────────────────
+
+    @staticmethod
+    def _unpack(prediction: dict) -> tuple[str, float, float, float]:
+        """Extract prediction, confidence, and logit values from output dict."""
+        import torch
+
+        pred       = prediction["prediction"]
+        confidence = float(prediction["confidence"])
+        logits     = prediction["logits"]
+
+        # Handle Tensor or list
+        if isinstance(logits, torch.Tensor):
+            vals = logits.squeeze().tolist()
+        else:
+            vals = list(logits)
+
+        if isinstance(vals, float):
+            vals = [vals, vals]
+
+        return pred, confidence, round(vals[0], 4), round(vals[1], 4)
+
+    @staticmethod
+    def _split_generated(text: str, gradcam_context: Optional[str]) -> tuple[str, str]:
+        """
+        Split FLAN-T5 output into summary and detail.
+        Uses sentence boundary: first 2 sentences → summary, rest → detail.
+        """
+        import re
+        sentences = re.split(r'(?<=[.!?])\s+', text.strip())
+        sentences = [s.strip() for s in sentences if s.strip()]
+
+        if len(sentences) >= 3:
+            summary = " ".join(sentences[:2])
+            detail  = " ".join(sentences[2:])
+        elif len(sentences) == 2:
+            summary = sentences[0]
+            detail  = sentences[1]
+        else:
+            summary = text
+            detail  = ""
+
+        if gradcam_context and gradcam_context not in detail:
+            detail += f" Spatial analysis: {gradcam_context}"
+
+        return summary, detail
+
+    @staticmethod
+    def _summarise_heatmap(heatmap) -> str:
+        """
+        Convert a (224, 224) Grad-CAM heatmap into a spatial text description.
+        Divides into 3×3 grid, reports regions with activation above threshold.
+        """
+        import numpy as np
+
+        h, w      = heatmap.shape
+        grid_h    = h // 3
+        grid_w    = w // 3
+        threshold = 0.6
+
+        region_names = [
+            ["top-left",    "top-centre",    "top-right"],
+            ["middle-left", "centre",        "middle-right"],
+            ["bottom-left", "bottom-centre", "bottom-right"],
+        ]
+
+        hot_regions = []
+        for row in range(3):
+            for col in range(3):
+                patch = heatmap[
+                    row * grid_h : (row + 1) * grid_h,
+                    col * grid_w : (col + 1) * grid_w,
+                ]
+                if float(patch.mean()) > threshold:
+                    hot_regions.append(
+                        f"{region_names[row][col]} ({patch.mean():.2f})"
+                    )
+
+        overall_mean = float(heatmap.mean())
+        overall_max  = float(heatmap.max())
+
+        if hot_regions:
+            return (
+                f"High activation in: {', '.join(hot_regions)}. "
+                f"Mean={overall_mean:.3f}, peak={overall_max:.3f}. "
+                f"These regions most influenced the prediction."
+            )
+        return (
+            f"No dominant activation region detected. "
+            f"Mean={overall_mean:.3f}, peak={overall_max:.3f}. "
+            f"Prediction driven by diffuse low-level features."
+        )
+
+
+
+# ╔══════════════════════════════════════════════════════════════════════════════╗
+# ║  CHAT ENGINE — human-like conversational responses via FLAN-T5              ║
+# ╚══════════════════════════════════════════════════════════════════════════════╝
+
+class ChatEngine:
+    """
+    Human-like conversational response engine powered by FLAN-T5-large.
+
+    Uses carefully designed prompts to make FLAN-T5 respond naturally —
+    like a knowledgeable colleague — rather than producing stiff templated text.
+
+    Each response incorporates:
+    - Patient name, age, and medical history (if provided)
+    - Specific scan numbers (confidence, logits, decision margin)
+    - Grad-CAM spatial findings
+    - Audience-appropriate tone and vocabulary
+    - Conversation history for multi-turn context
+
+    Falls back to rich deterministic responses if FLAN-T5 is not loaded.
+    """
+
+    def __init__(self, llm: "FlanT5Engine | None" = None) -> None:
+        self.llm = llm
+
+    def respond(
+        self,
+        message:         str,
+        audience:        str,
+        prediction:      str,
+        confidence:      float,
+        benign_logit:    float,
+        malignant_logit: float,
+        spatial_summary: str            = "",
+        history:         list           = None,
+        patient:         dict           = None,
+    ) -> str:
+        """
+        Generate a human-like conversational response.
+
+        Parameters
+        ----------
+        message         : the user's question
+        audience        : clinician | researcher | patient
+        prediction      : benign | malignant
+        confidence      : float [0, 1]
+        benign_logit    : raw logit for benign class
+        malignant_logit : raw logit for malignant class
+        spatial_summary : Grad-CAM text description
+        history         : list of prior {"role", "content"} dicts
+        patient         : dict with name, age, sex, medical_history, symptoms, previous_scans
+        """
+        patient   = patient or {}
+        history   = history or []
+        is_mal    = prediction == "malignant"
+        pct       = f"{confidence:.1%}"
+        margin    = abs(malignant_logit - benign_logit)
+        name      = patient.get("name", "")
+        age       = patient.get("age", 0)
+        p_history = patient.get("medical_history", "")
+        symptoms  = patient.get("symptoms", "")
+
+        # Try FLAN-T5 first
+        if self.llm is not None:
+            try:
+                prompt = self._build_prompt(
+                    message, audience, prediction, confidence,
+                    benign_logit, malignant_logit, spatial_summary,
+                    history, patient, is_mal, pct, margin
+                )
+                response = self.llm.generate_chat(prompt)
+                if len(response.split()) >= 15:
+                    return response
+            except Exception as e:
+                print(f"[ChatEngine] FLAN-T5 failed ({e}) — using fallback.")
+
+        # Fallback: rich deterministic responses
+        return self._fallback(
+            message, audience, prediction, confidence,
+            benign_logit, malignant_logit, spatial_summary,
+            is_mal, pct, margin, name, age, p_history, symptoms
+        )
+
+    # ── Prompt builder ────────────────────────────────────────────────────────
+
+    def _build_prompt(
+        self, message, audience, prediction, confidence,
+        b_logit, m_logit, cam, history, patient,
+        is_mal, pct, margin
+    ) -> str:
+        """Build a FLAN-T5 conversational prompt with full context."""
+
+        name    = patient.get("name", "")
+        age     = patient.get("age", 0)
+        sex     = patient.get("sex", "")
+        hist    = patient.get("medical_history", "")
+        symp    = patient.get("symptoms", "")
+        scans   = patient.get("previous_scans", "")
+
+        patient_ctx = ""
+        if name or age or hist or symp:
+            patient_ctx = f"""
+Patient: {name or 'Anonymous'}{', age ' + str(age) if age else ''}{', ' + sex if sex else ''}.
+{('Medical history: ' + hist) if hist else ''}
+{('Symptoms: ' + symp) if symp else ''}
+{('Previous scans: ' + scans) if scans else ''}
+""".strip()
+
+        audience_style = {
+            "clinician": (
+                "a consultant radiologist. Use clinical terminology. "
+                "Be precise and collegial. Reference BI-RADS, logit margins, "
+                "and clinical decision context naturally."
+            ),
+            "researcher": (
+                "an ML researcher. Be technical. Reference softmax probabilities, "
+                "logit values, model architecture (DenseNet-121), training methodology "
+                "(OneCycleLR, Mixup, StainJitter), and calibration naturally."
+            ),
+            "patient": (
+                "a patient with no medical background. Be warm, empathetic, and clear. "
+                "Use plain English. No jargon. Acknowledge their feelings. "
+                "Be reassuring but honest. Address them by name if you know it."
+            ),
+        }.get(audience, "a medical professional")
+
+        history_ctx = ""
+        if history:
+            recent = history[-4:]
+            lines = [('User' if h.get('role')=='user' else 'Assistant')+': '+h.get('content','') for h in recent]
+            history_ctx = 'Previous exchanges: ' + ' | '.join(lines)
+
+        prompt = f"""You are a knowledgeable and empathetic AI medical assistant for the MedAI platform.
+You are speaking to {audience_style}
+
+Scan result:
+- Classification: {prediction.upper()} ({pct} confidence)
+- Logit scores: benign={b_logit:.4f}, malignant={m_logit:.4f} (margin={margin:.4f})
+- Grad-CAM: {cam or 'Not available'}
+- Model accuracy: 88.0%, sensitivity: 87.5%
+{patient_ctx}
+{history_ctx}
+
+The person asks: "{message}"
+
+Respond naturally and warmly in 2-4 sentences. Be specific — reference the actual numbers. Sound like a knowledgeable colleague, not a robot. End with a brief reminder that clinical confirmation is required.
+
+Response:"""
+
+        return prompt.strip()
+
+    # ── Fallback: rich deterministic responses ────────────────────────────────
+
+    def _fallback(
+        self, message, audience, prediction, confidence,
+        b_logit, m_logit, cam, is_mal, pct, margin,
+        name, age, p_history, symptoms
+    ) -> str:
+        """Rich, human-sounding deterministic responses as fallback."""
+        msg  = message.lower()
+        addr = f"{name.split()[0]}, " if name else ""
+        scan = f"{'malignant' if is_mal else 'benign'} at {pct} confidence"
+
+        if audience == "patient":
+            return self._patient_fallback(msg, is_mal, pct, margin, cam, addr, name, confidence, symptoms)
+        elif audience == "researcher":
+            return self._researcher_fallback(msg, is_mal, pct, b_logit, m_logit, margin, cam)
+        else:
+            return self._clinician_fallback(msg, is_mal, pct, b_logit, m_logit, margin, cam, confidence, p_history)
+
+    def _patient_fallback(self, msg, is_mal, pct, margin, cam, addr, name, conf, symptoms) -> str:
+        if any(k in msg for k in ["worry","worried","scared","serious","cancer","bad"]):
+            if is_mal:
+                return (
+                    f"{addr}I completely understand why you might feel anxious right now — "
+                    f"that's a very natural reaction. What I can tell you is that this AI "
+                    f"flagged something that needs a closer look, and your doctor is the right "
+                    f"person to interpret this alongside your full clinical picture. "
+                    f"Many findings like this turn out to be benign on further investigation. "
+                    f"Please don't make any decisions until you've spoken with your healthcare provider."
+                )
+            else:
+                return (
+                    f"{addr}I can hear that this has been worrying for you. "
+                    f"The good news is that the AI found no signs of abnormal tissue in this sample — "
+                    f"that's a reassuring result. Of course, your doctor will want to confirm this "
+                    f"as part of your overall care, but this is genuinely positive."
+                )
+        if any(k in msg for k in ["mean","understand","explain","what is","tell me"]):
+            if is_mal:
+                return (
+                    f"{addr}think of the AI like a very experienced set of eyes that has studied "
+                    f"thousands of tissue samples. It noticed patterns in this image — at {pct} confidence — "
+                    f"that it has learned to associate with abnormal cells. "
+                    f"That said, this is a screening tool, not a diagnosis. "
+                    f"Your doctor will look at this result together with everything else they know about you."
+                )
+            else:
+                return (
+                    f"{addr}the AI examined the patterns in this tissue sample and found that they "
+                    f"look consistent with normal, healthy tissue — it's {pct} confident in that assessment. "
+                    f"That's a really good sign. Your doctor will confirm this at your next appointment."
+                )
+        if any(k in msg for k in ["next","step","do","happen","biopsy","test"]):
+            if is_mal:
+                return (
+                    f"{addr}the most important next step is to have a conversation with your doctor "
+                    f"about this result as soon as possible. They may recommend additional imaging "
+                    f"or a biopsy — which is a small, simple procedure to collect a tiny tissue sample "
+                    f"for a laboratory to examine more closely. "
+                    f"Please don't let anxiety about what might happen stop you from making that appointment."
+                )
+            else:
+                return (
+                    f"{addr}with a reassuring result like this, your doctor will likely recommend "
+                    f"continuing with your routine screening schedule. Do mention this result at your "
+                    f"next appointment so it becomes part of your medical record. "
+                    f"Is there anything else you'd like to understand about what this means?"
+                )
+        if any(k in msg for k in ["accurate","right","trust","sure","certain","reliable"]):
+            return (
+                f"{addr}that's a really important question to ask. The AI was correct on {pct} "
+                f"of test cases it hadn't seen before — which is good, but not perfect. "
+                f"No AI system is 100% accurate, which is exactly why your doctor always "
+                f"reviews the result before any clinical decision is made. "
+                f"Think of it as a very thorough first opinion."
+            )
+        if any(k in msg for k in ["heatmap","colour","color","red","highlighted","image","overlay"]):
+            return (
+                f"{addr}the coloured image you're seeing is called a Grad-CAM heatmap. "
+                f"The red and orange areas show where the AI was paying the most attention "
+                f"when it made its decision — those are the parts of the tissue it found "
+                f"most significant. Blue areas were largely ignored. "
+                + (f"In your scan, the AI was particularly focused on {cam.split('.')[0].lower()}." if cam else
+                   "Your doctor can use this to understand exactly what the AI was looking at.")
+            )
+        # Generic fallback
+        return (
+            f"{addr}I'm here to help you make sense of this result. "
+            f"The AI classified this sample as {'potentially abnormal' if is_mal else 'normal-looking'} "
+            f"at {pct} confidence. "
+            f"You can ask me things like 'what does this mean?', 'should I be worried?', "
+            f"or 'what happens next?' — and I'll do my best to explain clearly and honestly."
+        )
+
+    def _clinician_fallback(self, msg, is_mal, pct, b_logit, m_logit, margin, cam, conf, p_history) -> str:
+        birad = ("BI-RADS 4B (Suspicious)" if conf >= 0.75 else "BI-RADS 4A (Low suspicion)") if is_mal else "BI-RADS 2 (Benign)"
+        boundary = ("clear decision boundary" if margin > 1.5 else "near the decision boundary — borderline case")
+
+        if any(k in msg for k in ["why","reason","basis","how","drove"]):
+            return (
+                f"The classifier scored this patch {'malignant' if is_mal else 'benign'} based on "
+                f"DenseNet-121 feature activations — logits benign={b_logit:.4f}, malignant={m_logit:.4f}, "
+                f"margin={margin:.4f} ({boundary}). "
+                + (f"Grad-CAM identifies high activation in {cam.split('.')[0].lower()}, suggesting those "
+                   f"spatial regions drove the classification." if cam else
+                   f"Grad-CAM overlay is available in the heatmap tab for region-level review.") +
+                f" Clinical correlation with morphological features is warranted."
+            )
+        if any(k in msg for k in ["birad","bi-rad","category","score","stage"]):
+            return (
+                f"Based on an AI confidence of {pct} and a logit margin of {margin:.3f}, "
+                f"a suggested starting point is {birad}. "
+                f"This is an AI-assisted recommendation only — final BI-RADS assignment "
+                f"requires full clinical, imaging, and patient history correlation by the "
+                f"responsible radiologist. "
+                + (f"Relevant history: {p_history[:100]}..." if p_history else "")
+            )
+        if any(k in msg for k in ["biopsy","next","action","recommend","management"]):
+            if is_mal:
+                return (
+                    f"With a {pct} confidence malignant classification and a logit margin of {margin:.3f}, "
+                    f"{'tissue biopsy for histological confirmation is recommended' if conf >= 0.70 else 'short-interval follow-up imaging (6 months) may be appropriate given the borderline confidence'}. "
+                    f"Full clinical workup — including prior imaging comparison and patient history — "
+                    f"should precede any intervention decision."
+                )
+            else:
+                return (
+                    f"With a {pct} confidence benign result and margin {margin:.3f}, "
+                    f"routine follow-up per standard screening protocol is appropriate. "
+                    f"If clinical suspicion remains high despite the AI result, "
+                    f"conventional workup should proceed independently of this output."
+                )
+        if any(k in msg for k in ["confident","confidence","reliable","calibrat"]):
+            return (
+                f"The softmax confidence of {pct} is uncalibrated — no temperature scaling "
+                f"or isotonic regression was applied post-hoc. The underlying model achieved "
+                f"87.5% sensitivity and 88.0% accuracy on 32,768 held-out PCam patches. "
+                f"{'A margin of ' + str(round(margin,3)) + ' above 1.5 indicates strong separation from the decision boundary.' if margin > 1.5 else 'A margin of ' + str(round(margin,3)) + ' below 1.5 suggests caution — this is a borderline result.'}"
+            )
+        if any(k in msg for k in ["gradcam","grad-cam","heatmap","attention","region"]):
+            return (
+                f"Grad-CAM computed ∂score_{('malignant' if is_mal else 'benign')}/∂A_k across "
+                f"the norm5 feature layer (1024×7×7 spatial maps), globally average-pooled "
+                f"to derive channel importance weights. "
+                + (f"High-activation regions: {cam} — these locations contributed most to the "
+                   f"classification. The overlay is viewable in the Grad-CAM tab." if cam else
+                   "No dominant activation region detected — prediction driven by diffuse features.")
+            )
+        return (
+            f"The model returned {'malignant' if is_mal else 'benign'} at {pct} confidence "
+            f"(logits: b={b_logit:.4f}, m={m_logit:.4f}, margin={margin:.4f}). "
+            f"I can elaborate on BI-RADS scoring, biopsy guidance, Grad-CAM interpretation, "
+            f"confidence calibration, or model performance — what would be most useful?"
+        )
+
+    def _researcher_fallback(self, msg, is_mal, pct, b_logit, m_logit, margin, cam) -> str:
+        softmax_b = round(1 / (1 + 2.718 ** (m_logit - b_logit)), 4)
+        softmax_m = round(1 - softmax_b, 4)
+
+        if any(k in msg for k in ["logit","score","raw","softmax","probability","output"]):
+            return (
+                f"Raw logits: [benign={b_logit:.6f}, malignant={m_logit:.6f}]. "
+                f"After softmax: [P(benign)={softmax_b:.4f}, P(malignant)={softmax_m:.4f}]. "
+                f"|Δlogit| = {margin:.6f} — "
+                f"{'above the empirical 1.5 threshold for high-confidence separation' if margin > 1.5 else 'below 1.5, suggesting proximity to the decision boundary'}. "
+                f"No temperature scaling or calibration applied post-hoc."
+            )
+        if any(k in msg for k in ["gradcam","grad-cam","gradient","activation","feature","saliency"]):
+            return (
+                f"Grad-CAM implementation: forward hook on model.features.norm5 (B×1024×7×7). "
+                f"Backward pass computes ∂score_{{'malignant' if is_mal else 'benign'}}/∂A_k for each channel k. "
+                f"Global average pooling of gradients gives weights α_k. "
+                f"CAM = ReLU(Σ_k α_k · A_k), bilinearly upsampled 7×7 → 224×224. "
+                + (f"Spatial summary: {cam}." if cam else "No dominant activation detected.")
+            )
+        if any(k in msg for k in ["train","architecture","model","densenet","weight","epoch"]):
+            return (
+                f"DenseNet-121 (7,219,330 params) fine-tuned on 220,025 deduplicated PCam patches. "
+                f"Training: OneCycleLR(max_lr=3e-3, pct_start=0.3), Mixup(α=0.4), "
+                f"StainJitter(HED, strength=0.05), LabelSmoothing(0.1), "
+                f"CrossEntropyLoss(pos_weight=1.469). "
+                f"Checkpoint selection by val_sensitivity — best epoch 13/20, val_sens=0.903, "
+                f"test_sens=0.875, test_acc=0.880."
+            )
+        if any(k in msg for k in ["dataset","pcam","camelyon","dedup","duplicate","balance"]):
+            return (
+                f"PatchCamelyon: 262,144 raw training patches → 220,025 after MD5 deduplication "
+                f"(42,119 removed, 83.9% retention). "
+                f"The original dataset was artificially balanced by duplicating malignant patches — "
+                f"post-dedup true distribution: benign=130,908, malignant=89,117 (pos_weight=1.469). "
+                f"Deduplication was the single largest contributor to the +6.8pp sensitivity improvement."
+            )
+        if any(k in msg for k in ["calibrat","uncertain","temperature","reliability","ece"]):
+            return (
+                f"P({('malignant' if is_mal else 'benign')})={pct} is an uncalibrated softmax output. "
+                f"No temperature scaling, Platt scaling, or isotonic regression was applied. "
+                f"ECE was not computed on this checkpoint. "
+                f"For reliable probability estimates, recommend fitting calibration on a held-out set "
+                f"using sklearn.calibration.CalibratedClassifierCV or manual temperature scaling on logits."
+            )
+        return (
+            f"Output: {('malignant' if is_mal else 'benign').upper()} | "
+            f"logits=[{b_logit:.4f}, {m_logit:.4f}] | softmax=[{softmax_b:.4f}, {softmax_m:.4f}] | "
+            f"|Δlogit|={margin:.4f}. "
+            f"I can go deeper on logit analysis, Grad-CAM implementation, model architecture, "
+            f"dataset statistics, or calibration. What would you like to explore?"
+        )

explainability/mammogram_gradcam.py

@@ -0,0 +1,175 @@
+"""
+explainability/mammogram_gradcam.py
+────────────────────────────────────
+Grad-CAM for the EfficientNet-B4 mammogram models.
+
+Why a separate class from gradcam.py?
+─────────────────────────────────────
+The histopathology GradCAM in gradcam.py is hardwired for DenseNet-121:
+  • it hooks model.features["norm5"]      — EfficientNet has no norm5
+  • it expects model(x) → {"logits","probs"} dict
+  • it preprocesses at 224×224            — mammograms train at 384×384
+
+The mammogram ensemble members (model/mammogram_ensemble.py::_Model) are
+EfficientNet-B4 with a .feat / .pool / .head structure and a bare-tensor
+forward. This class targets that architecture directly.
+
+It hooks the final EfficientNet feature block (model.feat), which outputs
+(B, 1792, 12, 12) at 384×384 input, computes gradient-weighted activations
+for the target class, and upsamples to a 384×384 heatmap + overlay.
+
+Returns the same dict schema the API expects:
+  prediction, confidence, logits (Tensor[1,2]), heatmap (384²), overlay (PIL), cam_raw
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Union
+
+import numpy as np
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from PIL import Image
+from torchvision import transforms
+
+LABEL_MAP = {0: "benign", 1: "malignant"}
+MEAN = [0.485, 0.456, 0.406]
+STD  = [0.229, 0.224, 0.225]
+INPUT_SIZE = 384   # mammogram models were trained at 384×384
+
+
+def _jet_colormap_vectorized(heatmap: np.ndarray) -> np.ndarray:
+    """(H,W) float [0,1] → (H,W,3) uint8 RGB via jet colourmap. Vectorised."""
+    v = np.clip(heatmap, 0.0, 1.0)
+    r = np.clip(1.5 - np.abs(4 * v - 3), 0, 1)
+    g = np.clip(1.5 - np.abs(4 * v - 2), 0, 1)
+    b = np.clip(1.5 - np.abs(4 * v - 1), 0, 1)
+    return (np.stack([r, g, b], axis=-1) * 255).astype(np.uint8)
+
+
+class MammogramGradCAM:
+    """
+    Grad-CAM for a single EfficientNet-B4 mammogram model.
+
+    Parameters
+    ----------
+    model : the _Model instance (or any module exposing `.feat`).
+    device : "cuda" | "mps" | "cpu". Auto-detected if None.
+    alpha : overlay blend weight. Default 0.5.
+    """
+
+    def __init__(
+        self,
+        model:  nn.Module,
+        device: Optional[str] = None,
+        alpha:  float         = 0.5,
+    ) -> None:
+        self.device = self._resolve_device(device)
+        self.alpha  = alpha
+        self.model  = model.eval().to(self.device)
+
+        self.transform = transforms.Compose([
+            transforms.Resize((INPUT_SIZE, INPUT_SIZE)),
+            transforms.ToTensor(),
+            transforms.Normalize(MEAN, STD),
+        ])
+
+        self._activations: Optional[torch.Tensor] = None
+        self._gradients:   Optional[torch.Tensor] = None
+
+        # Hook the final EfficientNet feature block.
+        # model.feat is the EfficientNet `features` Sequential; its output is
+        # the deepest spatial feature map before global pooling.
+        target = self._find_target_layer(model)
+        target.register_forward_hook(self._save_activations)
+        target.register_full_backward_hook(self._save_gradients)
+
+    @staticmethod
+    def _find_target_layer(model: nn.Module) -> nn.Module:
+        """Locate the conv feature module to hook."""
+        if hasattr(model, "feat"):
+            return model.feat          # ensemble _Model
+        if hasattr(model, "features"):
+            return model.features      # torchvision-style EfficientNet
+        raise AttributeError(
+            "Model has neither `.feat` nor `.features` — cannot attach Grad-CAM."
+        )
+
+    # ── Hook callbacks ──────────────────────────────────────────────────────
+    def _save_activations(self, module, inp, out) -> None:
+        self._activations = out.detach()
+
+    def _save_gradients(self, module, grad_in, grad_out) -> None:
+        self._gradients = grad_out[0].detach()
+
+    # ── Main API ────────────────────────────────────────────────────────────
+    def explain(
+        self,
+        image:     Union[Image.Image, str],
+        class_idx: Optional[int] = None,
+    ) -> dict:
+        if isinstance(image, str):
+            image = Image.open(image).convert("RGB")
+        else:
+            image = image.convert("RGB")
+
+        tensor = self.transform(image).unsqueeze(0).to(self.device)
+        tensor.requires_grad_(True)
+
+        # Forward — _Model returns a bare (1,2) logits tensor
+        logits = self.model(tensor)
+        if isinstance(logits, dict):           # tolerate dict-returning models
+            logits = logits["logits"]
+        probs = torch.softmax(logits, dim=1)
+
+        if class_idx is None:
+            class_idx = int(torch.argmax(probs, dim=1).item())
+        confidence = float(probs[0, class_idx].item())
+        prediction = LABEL_MAP[class_idx]
+
+        # Backward — gradients of the class score w.r.t. feature maps
+        self.model.zero_grad()
+        logits[0, class_idx].backward()
+
+        # Grad-CAM: channel weights = mean gradient over spatial dims
+        weights = self._gradients.mean(dim=(2, 3), keepdim=True)        # (1,C,1,1)
+        cam     = (weights * self._activations).sum(dim=1, keepdim=True)# (1,1,h,w)
+        cam     = torch.relu(cam)
+
+        cam_raw = cam[0, 0].cpu().numpy()
+        mn, mx  = cam_raw.min(), cam_raw.max()
+        cam_norm = (cam_raw - mn) / (mx - mn) if mx > mn else np.zeros_like(cam_raw)
+
+        heatmap = self._upsample(cam_norm, (INPUT_SIZE, INPUT_SIZE))
+        overlay = self._build_overlay(image.resize((INPUT_SIZE, INPUT_SIZE)), heatmap)
+
+        return {
+            "prediction": prediction,
+            "confidence": round(confidence, 6),
+            "logits":     logits.detach().cpu(),
+            "heatmap":    heatmap,
+            "overlay":    overlay,
+            "cam_raw":    cam_raw,
+        }
+
+    # ── Helpers ─────────────────────────────────────────────────────────────
+    @staticmethod
+    def _upsample(cam: np.ndarray, size: tuple[int, int]) -> np.ndarray:
+        t  = torch.from_numpy(cam).float()[None, None]
+        up = F.interpolate(t, size=size, mode="bilinear", align_corners=False)
+        return up[0, 0].numpy()
+
+    def _build_overlay(self, original: Image.Image, heatmap: np.ndarray) -> Image.Image:
+        jet = Image.fromarray(_jet_colormap_vectorized(heatmap), mode="RGB")
+        return Image.blend(original.convert("RGB"), jet, alpha=self.alpha)
+
+    @staticmethod
+    def _resolve_device(device: Optional[str]) -> torch.device:
+        if device is not None:
+            return torch.device(device)
+        if torch.cuda.is_available():
+            return torch.device("cuda")
+        if torch.backends.mps.is_available():
+            return torch.device("mps")
+        return torch.device("cpu")

frontend/index.html

@@ -0,0 +1,1073 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8"/>
+<meta name="viewport" content="width=device-width,initial-scale=1.0"/>
+<title>MedAI — Breast Cancer Analysis Platform</title>
+<link rel="preconnect" href="https://fonts.googleapis.com"/>
+<link href="https://fonts.googleapis.com/css2?family=Syne:wght@400;600;700;800&family=Sora:wght@300;400;500;600&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet"/>
+<style>
+*,*::before,*::after{box-sizing:border-box;margin:0;padding:0}
+:root{
+  --bg:#06070A;--bg2:#0E1016;--bg3:#161922;
+  --border:rgba(255,255,255,.08);--border2:rgba(255,255,255,.14);
+  --text:#e8f0ff;--muted:rgba(232,240,255,.66);
+  --teal:#2E8BF5;--teal-dim:rgba(46,139,245,.15);--teal-lt:#A8CBFF;
+  --red:#E24B4A;--red-dim:rgba(226,75,74,.15);
+  --radius:10px;
+}
+body{font-family:'Sora',sans-serif;background:var(--bg);color:var(--text);min-height:100vh;font-size:14px;line-height:1.6}
+button{cursor:pointer;font-family:'Sora',sans-serif}
+.nav{display:flex;align-items:center;justify-content:space-between;padding:14px 32px;border-bottom:.5px solid var(--border);background:var(--bg);position:sticky;top:0;z-index:100}
+.logo{width:34px;height:34px;border-radius:9px;background:var(--teal);display:flex;align-items:center;justify-content:center;font-family:'Syne',sans-serif;font-weight:800;font-size:16px;color:#EAF2FF}
+.nav-title{font-family:'Syne',sans-serif;font-weight:800;font-size:17px}
+.nav-badge{font-size:10px;padding:2px 8px;border-radius:4px;background:var(--teal-dim);color:var(--teal-lt);font-weight:600}
+.nbtn{padding:7px 16px;border-radius:7px;border:.5px solid transparent;background:transparent;color:var(--muted);font-size:13px;transition:all .15s}
+.nbtn:hover{background:var(--bg2);color:var(--text)}
+.nbtn.active{background:var(--teal-dim);color:var(--teal-lt);border-color:rgba(46,139,245,.3)}
+.btn-p{padding:9px 20px;border-radius:8px;border:none;font-size:13px;font-weight:600;background:var(--teal);color:#EAF2FF;transition:background .15s}
+.btn-p:hover{background:#1C72DE}
+.btn-p:disabled{opacity:.5;cursor:not-allowed}
+.btn-o{padding:9px 20px;border-radius:8px;border:.5px solid var(--border2);font-size:13px;background:transparent;color:var(--text);transition:background .15s}
+.btn-o:hover{background:var(--bg2)}
+.page{padding:36px 32px;max-width:1200px;margin:0 auto}
+.hidden{display:none!important}
+.card{background:var(--bg2);border:.5px solid var(--border);border-radius:var(--radius);padding:20px}
+.card-sm{background:var(--bg2);border:.5px solid var(--border);border-radius:8px;padding:14px}
+.slabel{font-size:11px;font-weight:600;letter-spacing:.12em;text-transform:uppercase;color:var(--teal);margin-bottom:8px}
+.h1{font-family:'Syne',sans-serif;font-weight:800;font-size:40px;line-height:1.1}
+.h2{font-family:'Syne',sans-serif;font-weight:700;font-size:26px}
+.mono{font-family:'JetBrains Mono',monospace}
+.f{display:flex}.fc{display:flex;flex-direction:column}
+.ac{align-items:center}.jb{justify-content:space-between}
+.g6{gap:6px}.g8{gap:8px}.g10{gap:10px}.g12{gap:12px}.g16{gap:16px}.g24{gap:24px}
+.mt8{margin-top:8px}.mt12{margin-top:12px}.mt16{margin-top:16px}.mt20{margin-top:20px}.mt24{margin-top:24px}
+.g2{display:grid;grid-template-columns:1fr 1fr;gap:16px}
+.g4{display:grid;grid-template-columns:repeat(4,1fr);gap:12px}
+.bdanger{display:inline-flex;align-items:center;gap:6px;padding:5px 12px;border-radius:7px;background:var(--red-dim);color:#F09595;font-size:13px;font-weight:600;border:.5px solid rgba(226,75,74,.3)}
+.bsafe{display:inline-flex;align-items:center;gap:6px;padding:5px 12px;border-radius:7px;background:var(--teal-dim);color:var(--teal-lt);font-size:13px;font-weight:600;border:.5px solid rgba(46,139,245,.3)}
+.bteal{display:inline-flex;align-items:center;gap:6px;padding:4px 12px;border-radius:20px;background:var(--teal-dim);color:var(--teal-lt);font-size:12px;font-weight:500}
+.dlive{width:7px;height:7px;border-radius:50%;background:var(--teal);animation:pulse 1.5s ease infinite;flex-shrink:0}
+.upload-zone{border:1.5px dashed var(--border2);border-radius:var(--radius);padding:40px 24px;text-align:center;position:relative;transition:all .2s}
+.upload-zone:hover{border-color:var(--teal);background:var(--teal-dim)}
+.upload-zone input[type=file]{position:absolute;inset:0;opacity:0;width:100%;cursor:pointer}
+.tab-bar{display:flex;gap:4px;border-bottom:.5px solid var(--border);margin-bottom:20px}
+.tab{padding:8px 16px;font-size:13px;background:none;border:none;border-bottom:2px solid transparent;color:var(--muted);transition:all .15s}
+.tab:hover{color:var(--text)}
+.tab.active{color:var(--teal-lt);border-bottom-color:var(--teal)}
+.cbar{height:6px;border-radius:3px;background:var(--bg3);overflow:hidden}
+.cfill{height:100%;border-radius:3px;transition:width .6s ease}
+.mrow{display:flex;justify-content:space-between;align-items:center;padding:9px 0;border-bottom:.5px solid var(--border)}
+.mrow:last-child{border-bottom:none}
+.simg{width:100%;aspect-ratio:1;border-radius:var(--radius);object-fit:cover;background:var(--bg3);border:.5px solid var(--border);display:block}
+.scan-tile{width:100%;aspect-ratio:1;object-fit:cover;border-radius:var(--radius);border:.5px solid var(--border);background:var(--bg3);display:block}
+.scan-ph{width:100%;aspect-ratio:1;border-radius:var(--radius);border:.5px solid var(--border);background:var(--bg3);display:none;flex-direction:column;align-items:center;justify-content:center;gap:6px;color:var(--muted);font-size:12px}
+.scan-cap{font-size:10px;color:var(--muted);margin-top:6px;text-align:center}
+.sph{width:100%;aspect-ratio:1;border-radius:var(--radius);background:var(--bg3);border:.5px solid var(--border);display:flex;align-items:center;justify-content:center;flex-direction:column;gap:8px;color:var(--muted);font-size:13px}
+.aud-sel{background:var(--bg3);border:.5px solid var(--border2);border-radius:7px;padding:7px 12px;color:var(--text);font-family:'Sora',sans-serif;font-size:13px;outline:none}
+.aud-sel:focus{border-color:var(--teal)}
+.chat-panel{border:.5px solid var(--border);border-radius:var(--radius);overflow:hidden;margin-top:24px}
+.chat-head{padding:12px 18px;border-bottom:.5px solid var(--border);display:flex;align-items:center;justify-content:space-between;background:var(--bg2)}
+.chat-body{height:280px;overflow-y:auto;padding:14px;display:flex;flex-direction:column;gap:10px}
+.mai{align-self:flex-start;max-width:85%;background:var(--bg2);border:.5px solid var(--border);border-radius:10px 10px 10px 3px;padding:10px 14px;font-size:12.5px;line-height:1.65;animation:fi .25s ease;white-space:pre-wrap}
+.muser{align-self:flex-end;max-width:85%;background:var(--teal);color:#EAF2FF;border-radius:10px 10px 3px 10px;padding:10px 14px;font-size:12.5px;line-height:1.65;animation:fi .25s ease}
+.mai.md{white-space:normal}
+.mai.md p{margin:0 0 8px}
+.mai.md p:last-child{margin-bottom:0}
+.mai.md h3,.mai.md h4,.mai.md h5{font-family:'Syne',sans-serif;margin:11px 0 6px;line-height:1.3;color:var(--text)}
+.mai.md h3{font-size:15px}.mai.md h4{font-size:13.5px}.mai.md h5{font-size:12.5px}
+.mai.md ul,.mai.md ol{margin:4px 0 8px;padding-left:18px}
+.mai.md li{margin:2px 0}
+.mai.md code{background:var(--bg3);padding:1px 5px;border-radius:4px;font-family:'JetBrains Mono',monospace;font-size:11.5px}
+.mai.md pre{background:var(--bg3);border:.5px solid var(--border);border-radius:8px;padding:10px;overflow-x:auto;margin:8px 0}
+.mai.md pre code{background:none;padding:0}
+.mai.md strong{color:var(--text);font-weight:600}
+.chat-foot{padding:10px 14px;border-top:.5px solid var(--border);display:flex;gap:8px;background:var(--bg2)}
+.cinp{flex:1;padding:8px 12px;border-radius:7px;border:.5px solid var(--border2);background:var(--bg3);color:var(--text);font-size:12.5px;font-family:'Sora',sans-serif;outline:none}
+.cinp:focus{border-color:var(--teal)}
+.chip-row{padding:8px 14px;border-top:.5px solid var(--border);display:flex;gap:6px;flex-wrap:wrap;background:var(--bg2)}
+.chip{padding:5px 10px;border-radius:16px;border:.5px solid var(--border2);font-size:11px;background:transparent;color:var(--muted);font-family:'Sora',sans-serif;transition:all .15s;white-space:nowrap}
+.chip:hover{border-color:var(--teal);color:var(--teal-lt);background:var(--teal-dim)}
+.td{display:inline-block;width:6px;height:6px;border-radius:50%;background:var(--teal);margin:0 2px;animation:pulse 1s ease infinite}
+.td:nth-child(2){animation-delay:.2s}.td:nth-child(3){animation-delay:.4s}
+.fcard{background:var(--bg2);border:.5px solid var(--border);border-radius:var(--radius);padding:20px;transition:border-color .2s}
+.fcard:hover{border-color:var(--teal)}
+.ficon{width:40px;height:40px;border-radius:10px;background:var(--teal-dim);display:flex;align-items:center;justify-content:center;margin-bottom:12px;font-size:18px}
+.svgi{width:20px;height:20px;stroke:var(--teal-lt);fill:none;stroke-width:1.6;stroke-linecap:round;stroke-linejoin:round}
+.site-footer{max-width:1200px;margin:24px auto 0;padding:0 32px 40px}
+.footer-disc{background:var(--red-dim);color:#F09595;border:.5px solid rgba(226,75,74,.25);border-radius:8px;padding:11px 16px;font-size:12.5px;font-weight:600;text-align:center;margin-bottom:22px}
+.footer-row{display:flex;justify-content:space-between;align-items:center;gap:20px;flex-wrap:wrap;border-top:.5px solid var(--border);padding-top:22px}
+.site-footer a{color:var(--teal-lt);text-decoration:none}
+.site-footer a:hover{text-decoration:underline}
+.result-banner{display:flex;align-items:center;justify-content:space-between;padding:16px 18px;border-radius:var(--radius);border:.5px solid var(--border2)}
+.result-banner.benign{background:var(--teal-dim);border-color:rgba(46,139,245,.4)}
+.result-banner.suspicious{background:var(--red-dim);border-color:rgba(226,75,74,.4)}
+.rb-verdict{display:flex;align-items:center;gap:9px;font-family:'Syne',sans-serif;font-weight:800;font-size:22px;letter-spacing:.01em}
+.result-banner.benign .rb-verdict{color:var(--teal-lt)}
+.result-banner.suspicious .rb-verdict{color:#F4A6A6}
+.rb-conf{text-align:right;line-height:1.1}
+.rb-conf .rb-num{font-family:'JetBrains Mono',monospace;font-size:23px;font-weight:600}
+.rb-conf .rb-lbl{font-size:10px;text-transform:uppercase;letter-spacing:.14em;color:var(--muted);margin-top:2px}
+.model-chip{display:inline-flex;align-items:center;gap:8px;font-size:11px;color:var(--muted);font-family:'JetBrains Mono',monospace;background:var(--bg3);padding:6px 11px;border-radius:6px;border:.5px solid var(--border)}
+.adv{border-top:.5px solid var(--border);padding-top:10px}
+.adv summary{cursor:pointer;font-size:11px;color:var(--muted);letter-spacing:.04em;list-style:none;user-select:none;display:flex;align-items:center;gap:6px}
+.adv summary::-webkit-details-marker{display:none}
+.adv summary::before{content:'▸';transition:transform .15s}
+.adv[open] summary::before{transform:rotate(90deg)}
+.adv summary:hover{color:var(--text)}
+.modbar{display:inline-flex;gap:4px;background:var(--bg2);border:.5px solid var(--border);border-radius:9px;padding:4px;margin-bottom:24px}
+.modbtn{padding:7px 18px;border-radius:6px;border:none;background:transparent;color:var(--muted);font-size:13px;font-weight:500;font-family:'Sora',sans-serif;cursor:pointer;transition:all .15s}
+.modbtn:hover{color:var(--text)}
+.modbtn.active{background:var(--teal-dim);color:var(--teal-lt)}
+.sample-row{display:flex;gap:12px;margin-top:10px;flex-wrap:wrap}
+.sample{cursor:pointer;border:.5px solid var(--border);border-radius:8px;padding:8px;background:var(--bg2);transition:border-color .2s;text-align:center;width:106px}
+.sample:hover{border-color:var(--teal)}
+.sample img{width:90px;height:90px;object-fit:cover;border-radius:6px;display:block;background:var(--bg3)}
+.sample span{display:block;font-size:11px;color:var(--muted);margin-top:6px}
+.api-bar{background:var(--bg3);border:.5px solid var(--border);border-radius:8px;padding:12px 16px;font-size:12px;display:flex;align-items:center;gap:10px;margin-bottom:24px}
+.api-inp{background:transparent;border:none;outline:none;color:var(--teal-lt);font-family:'JetBrains Mono',monospace;font-size:12px;flex:1}
+.sn{font-family:'Syne',sans-serif;font-weight:800;font-size:28px;color:var(--teal)}
+.stepn{width:32px;height:32px;border-radius:50%;background:var(--teal);display:flex;align-items:center;justify-content:center;font-family:'Syne',sans-serif;font-weight:700;font-size:13px;color:#EAF2FF;flex-shrink:0}
+.pform{background:var(--bg2);border:.5px solid var(--border);border-radius:var(--radius);padding:16px;margin-bottom:16px}
+.pform-grid{display:grid;grid-template-columns:1fr 1fr;gap:10px}
+.pinp{width:100%;padding:8px 10px;border-radius:7px;border:.5px solid var(--border2);background:var(--bg3);color:var(--text);font-size:12px;font-family:'Sora',sans-serif;outline:none}
+.pinp:focus{border-color:var(--teal)}
+.plabel{font-size:11px;color:var(--muted);margin-bottom:4px;display:block}
+.ptextarea{width:100%;padding:8px 10px;border-radius:7px;border:.5px solid var(--border2);background:var(--bg3);color:var(--text);font-size:12px;font-family:'Sora',sans-serif;outline:none;resize:vertical;min-height:60px}
+.ptextarea:focus{border-color:var(--teal)}
+.ptoggle{display:flex;align-items:center;gap:8px;cursor:pointer;font-size:12px;color:var(--muted);margin-bottom:12px;user-select:none}
+.ptoggle:hover{color:var(--text)}
+.ebox{font-size:12px;color:#F09595;background:var(--red-dim);border:.5px solid rgba(226,75,74,.3);border-radius:7px;padding:10px 14px;margin-top:8px}
+@keyframes pulse{0%,100%{opacity:1}50%{opacity:.4}}
+@keyframes fi{from{opacity:0;transform:translateY(5px)}to{opacity:1;transform:translateY(0)}}
+@keyframes spin{to{transform:rotate(360deg)}}
+</style>
+</head>
+<body>
+
+<nav class="nav">
+  <div class="f ac g10">
+    <div class="logo">M</div>
+    <span class="nav-title">MedAI</span>
+    <span class="nav-badge">v2.0</span>
+  </div>
+  <div class="f g6">
+    <button class="nbtn active" id="nb-platform"  onclick="show('platform')">Platform</button>
+    <button class="nbtn"        id="nb-dashboard" onclick="show('dashboard')">Dashboard</button>
+    <button class="nbtn"        id="nb-assistant" onclick="show('assistant')">AI Assistant</button>
+    <button class="nbtn"        id="nb-research"  onclick="show('research')">Research</button>
+  </div>
+  <div class="f g8 ac">
+    <button class="btn-o" style="font-size:12px;display:flex;align-items:center;gap:7px" onclick="checkHealth()">
+      <span id="apidot" style="width:7px;height:7px;border-radius:50%;background:#555;display:inline-block"></span><span id="apistatus">API status</span>
+    </button>
+    <button class="btn-p" onclick="show('dashboard')">Open dashboard →</button>
+  </div>
+</nav>
+
+<!-- PLATFORM -->
+<div id="v-platform" class="page">
+  <div style="display:grid;grid-template-columns:1fr 1fr;gap:48px;align-items:center;padding-bottom:48px;border-bottom:.5px solid var(--border)">
+    <div>
+      <div class="bteal" style="margin-bottom:18px">Histopathology · Mammography · Explainable AI</div>
+      <h1 class="h1">AI-powered breast cancer intelligence platform</h1>
+      <p style="color:var(--muted);margin-top:14px;font-size:15px;max-width:480px">Research-grade breast cancer detection across two modalities — histopathology and mammography — with explainable AI. Upload a tissue patch or a mammogram and receive a prediction, a spatial heatmap, and a natural-language report in seconds.</p>
+      <div class="f g12 mt24">
+        <button class="btn-p" style="font-size:14px;padding:11px 24px" onclick="show('dashboard')">Open dashboard →</button>
+        <button class="btn-o" style="font-size:14px;padding:11px 24px" onclick="show('assistant')">Try AI assistant</button>
+      </div>
+      <div class="f g24 mt24" style="flex-wrap:wrap">
+        <div>
+          <div class="slabel" style="margin-bottom:8px">Histopathology module</div>
+          <div class="f g24">
+            <div><div class="sn">88.0%</div><div style="font-size:12px;color:var(--muted);margin-top:2px">Test accuracy</div></div>
+            <div><div class="sn">87.5%</div><div style="font-size:12px;color:var(--muted);margin-top:2px">Sensitivity</div></div>
+          </div>
+        </div>
+        <div>
+          <div class="slabel" style="margin-bottom:8px">Mammography module</div>
+          <div class="f g24">
+            <div><div class="sn">0.8443</div><div style="font-size:12px;color:var(--muted);margin-top:2px">Patient-level AUC</div></div>
+          </div>
+        </div>
+      </div>
+    </div>
+    <div>
+      <div class="mono" style="font-size:10px;color:var(--muted);margin-bottom:6px">SCAN VIEWER</div>
+      <div style="display:grid;grid-template-columns:1fr 1fr;gap:10px">
+        <div>
+          <img src="samples/histo-tumor.png" alt="Histopathology patch" class="scan-tile" onerror="this.style.display='none';this.nextElementSibling.style.display='flex'"/>
+          <div class="scan-ph"><svg class="svgi" style="width:30px;height:30px" viewBox="0 0 24 24"><circle cx="8" cy="8" r="2.4"/><circle cx="16" cy="8" r="2.4"/><circle cx="8" cy="16" r="2.4"/><circle cx="16" cy="16" r="2.4"/></svg><span>Histopathology</span></div>
+          <div class="scan-cap">Histopathology · H&amp;E patch</div>
+        </div>
+        <div>
+          <img src="samples/mammo-cancer.png" alt="Mammogram" class="scan-tile" onerror="this.style.display='none';this.nextElementSibling.style.display='flex'"/>
+          <div class="scan-ph"><svg class="svgi" style="width:30px;height:30px" viewBox="0 0 24 24"><path d="M4 20c0-7 4-12 8-12s8 5 8 12"/><circle cx="14" cy="13" r="2"/></svg><span>Mammography</span></div>
+          <div class="scan-cap">Mammography · DICOM view</div>
+        </div>
+      </div>
+      <div class="mono" style="font-size:10px;color:var(--muted);margin:12px 0 6px">SAMPLE RESULT — ILLUSTRATIVE</div>
+      <div class="g2">
+        <div class="card-sm"><div style="font-size:10px;color:var(--muted);margin-bottom:4px" class="mono">PREDICTION</div><div class="bdanger">⚠ MALIGNANT</div></div>
+        <div class="card-sm"><div style="font-size:10px;color:var(--muted);margin-bottom:4px" class="mono">CONFIDENCE</div><div style="font-family:'Syne',sans-serif;font-weight:800;font-size:22px;color:var(--red)">0.94</div></div>
+      </div>
+    </div>
+  </div>
+  <div style="padding:48px 0;border-bottom:.5px solid var(--border)">
+    <div class="slabel">Platform capabilities</div>
+    <h2 class="h2" style="margin-bottom:28px">Two detection modules, one explainable platform</h2>
+
+    <div class="slabel" style="margin-bottom:12px;color:var(--teal-lt)">Histopathology module</div>
+    <div style="display:grid;grid-template-columns:repeat(3,1fr);gap:14px">
+      <div class="fcard"><div class="ficon"><svg class="svgi" viewBox="0 0 24 24"><path d="M12 2 2 7l10 5 10-5z"/><path d="m2 17 10 5 10-5"/><path d="m2 12 10 5 10-5"/></svg></div><div style="font-weight:600;font-size:14px;margin-bottom:6px">DenseNet-121</div><div style="font-size:12px;color:var(--muted);line-height:1.5">~7.2M-parameter CNN fine-tuned on 220K deduplicated PCam H&amp;E tissue patches.</div></div>
+      <div class="fcard"><div class="ficon"><svg class="svgi" viewBox="0 0 24 24"><path d="M12 2.5S5 9 5 14a7 7 0 0 0 14 0c0-5-7-11.5-7-11.5z"/></svg></div><div style="font-weight:600;font-size:14px;margin-bottom:6px">StainJitter (H&amp;E)</div><div style="font-size:12px;color:var(--muted);line-height:1.5">Stain augmentation in HED colour space, reducing lab-specific staining overfitting.</div></div>
+      <div class="fcard"><div class="ficon"><svg class="svgi" viewBox="0 0 24 24"><circle cx="12" cy="12" r="9"/><circle cx="12" cy="12" r="5"/><circle cx="12" cy="12" r="1"/></svg></div><div style="font-weight:600;font-size:14px;margin-bottom:6px">Sensitivity-first</div><div style="font-size:12px;color:var(--muted);line-height:1.5">Checkpoints selected by validation sensitivity — tuned to catch malignant patches.</div></div>
+    </div>
+
+    <div class="slabel" style="margin:24px 0 12px;color:var(--teal-lt)">Mammography module</div>
+    <div style="display:grid;grid-template-columns:repeat(3,1fr);gap:14px">
+      <div class="fcard"><div class="ficon"><svg class="svgi" viewBox="0 0 24 24"><rect x="9" y="2" width="6" height="6" rx="1"/><rect x="2" y="16" width="6" height="6" rx="1"/><rect x="16" y="16" width="6" height="6" rx="1"/><path d="M12 8v4M5 16v-2h14v2"/></svg></div><div style="font-weight:600;font-size:14px;margin-bottom:6px">EfficientNet-B4 ensemble</div><div style="font-size:12px;color:var(--muted);line-height:1.5">Three EfficientNet-B4 models (seeds 42 / 123 / 999) trained on RSNA data, averaged at inference.</div></div>
+      <div class="fcard"><div class="ficon"><svg class="svgi" viewBox="0 0 24 24"><rect x="3" y="3" width="18" height="18" rx="2"/><circle cx="9" cy="9" r="2"/><path d="m21 15-3.6-3.6a2 2 0 0 0-2.8 0L6 21"/></svg></div><div style="font-weight:600;font-size:14px;margin-bottom:6px">DICOM + VOI LUT</div><div style="font-size:12px;color:var(--muted);line-height:1.5">Native DICOM loading with VOI-LUT windowing. Also accepts PNG, JPG and TIFF.</div></div>
+      <div class="fcard"><div class="ficon"><svg class="svgi" viewBox="0 0 24 24"><rect x="8" y="2" width="8" height="4" rx="1"/><path d="M16 4h2a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h2"/><path d="m9 13 2 2 4-4"/></svg></div><div style="font-weight:600;font-size:14px;margin-bottom:6px">BI-RADS scoring</div><div style="font-size:12px;color:var(--muted);line-height:1.5">Suggested BI-RADS category (2–5) from malignancy probability. Radiologist confirmation required.</div></div>
+    </div>
+
+    <div class="slabel" style="margin:24px 0 12px;color:var(--teal-lt)">Shared platform layers — both modules</div>
+    <div style="display:grid;grid-template-columns:repeat(4,1fr);gap:14px">
+      <div class="fcard"><div class="ficon"><svg class="svgi" viewBox="0 0 24 24"><path d="M8.5 14.5A2.5 2.5 0 0 0 11 12c0-1.38-.5-2-1-3-1.07-2.14-.22-4.05 2-6 .5 2.5 2 4.9 4 6.5 2 1.6 3 3.5 3 5.5a7 7 0 1 1-14 0c0-1.15.43-2.29 1-3a2.5 2.5 0 0 0 2.5 2.5z"/></svg></div><div style="font-weight:600;font-size:14px;margin-bottom:6px">Grad-CAM heatmaps</div><div style="font-size:12px;color:var(--muted);line-height:1.5">Spatial attention maps showing which regions drove each prediction.</div></div>
+      <div class="fcard"><div class="ficon"><svg class="svgi" viewBox="0 0 24 24"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><path d="M14 2v6h6M16 13H8M16 17H8M10 9H8"/></svg></div><div style="font-weight:600;font-size:14px;margin-bottom:6px">LLM explanation</div><div style="font-size:12px;color:var(--muted);line-height:1.5">FLAN-T5 / BioMedLM / Llama 3.2 reports in clinician, researcher or patient modes.</div></div>
+      <div class="fcard"><div class="ficon"><svg class="svgi" viewBox="0 0 24 24"><path d="M21 11.5a8.38 8.38 0 0 1-.9 3.8 8.5 8.5 0 0 1-7.6 4.7 8.38 8.38 0 0 1-3.8-.9L3 21l1.9-5.7a8.38 8.38 0 0 1-.9-3.8 8.5 8.5 0 0 1 4.7-7.6 8.38 8.38 0 0 1 3.8-.9h.5a8.48 8.48 0 0 1 8 8z"/></svg></div><div style="font-weight:600;font-size:14px;margin-bottom:6px">Chat assistant</div><div style="font-size:12px;color:var(--muted);line-height:1.5">Ask follow-up questions about any result, in clinician, researcher or patient mode.</div></div>
+      <div class="fcard"><div class="ficon"><svg class="svgi" viewBox="0 0 24 24"><path d="m12 14 4-4"/><path d="M3.34 19a10 10 0 1 1 17.32 0"/></svg></div><div style="font-weight:600;font-size:14px;margin-bottom:6px">Confidence scores</div><div style="font-size:12px;color:var(--muted);line-height:1.5">Calibrated probability scores with raw logits and decision margin.</div></div>
+    </div>
+  </div>
+  <div style="padding:48px 0">
+    <div class="slabel">How it works</div>
+    <h2 class="h2" style="margin-bottom:28px">From scan to report in five steps</h2>
+    <div class="fc g16" style="max-width:600px">
+      <div class="f ac g16"><div class="stepn">1</div><div><div style="font-weight:600;font-size:14px;margin-bottom:3px">Upload a scan</div><div style="font-size:12px;color:var(--muted)">Histology patch (PNG / JPG / TIFF) or mammogram (DICOM / PNG) — drag and drop onto the dashboard</div></div></div>
+      <div class="f ac g16"><div class="stepn">2</div><div><div style="font-weight:600;font-size:14px;margin-bottom:3px">AI detection</div><div style="font-size:12px;color:var(--muted)">Routed by modality — DenseNet-121 for histology patches, the EfficientNet-B4 ensemble for mammograms</div></div></div>
+      <div class="f ac g16"><div class="stepn">3</div><div><div style="font-weight:600;font-size:14px;margin-bottom:3px">Grad-CAM overlay</div><div style="font-size:12px;color:var(--muted)">Spatial heatmap generated showing the regions that drove the prediction</div></div></div>
+      <div class="f ac g16"><div class="stepn">4</div><div><div style="font-weight:600;font-size:14px;margin-bottom:3px">LLM explanation</div><div style="font-size:12px;color:var(--muted)">Audience-tailored natural language report</div></div></div>
+      <div class="f ac g16"><div class="stepn">5</div><div><div style="font-weight:600;font-size:14px;margin-bottom:3px">Chat and review</div><div style="font-size:12px;color:var(--muted)">Ask follow-up questions in the inline chat assistant</div></div></div>
+    </div>
+  </div>
+</div>
+
+<!-- DASHBOARD -->
+<div id="v-dashboard" class="page hidden">
+  <div class="f ac jb" style="margin-bottom:24px">
+    <div><h2 class="h2">Analysis dashboard</h2><p id="dash-sub" style="color:var(--muted);font-size:13px;margin-top:3px">Upload a histopathology patch to run the full pipeline</p></div>
+    <div class="f g8 ac">
+      <span style="font-size:12px;color:var(--muted)">Audience:</span>
+      <select class="aud-sel" id="audience">
+        <option value="clinician">Clinician</option>
+        <option value="researcher">Researcher</option>
+        <option value="patient">Patient</option>
+      </select>
+    </div>
+  </div>
+
+    <div class="modbar">
+    <button class="modbtn active" id="mod-histo" onclick="switchModality('histo')">Histopathology</button>
+    <button class="modbtn" id="mod-mammo" onclick="switchModality('mammo')">Mammogram</button>
+  </div>
+  <div id="dash-histo">
+  <div style="display:grid;grid-template-columns:1fr 1fr;gap:24px;align-items:start">
+    <div>
+      <div class="tab-bar">
+        <button class="tab active" onclick="switchTab('upload',this)">Upload scan</button>
+        <button class="tab"        onclick="switchTab('overlay',this)">Grad-CAM overlay</button>
+        <button class="tab"        onclick="switchTab('raw',this)">Raw heatmap</button>
+      </div>
+      <!-- Patient record (collapsible) -->
+      <div id="pform-wrap">
+        <div class="ptoggle" onclick="togglePatient()">
+          <span id="ptoggle-icon">▶</span>
+          <span>Patient record <span style="font-size:10px;color:var(--teal);margin-left:4px">(optional — improves chat responses)</span></span>
+        </div>
+        <div id="pform-body" class="pform hidden">
+          <div class="pform-grid">
+            <div><label class="plabel">Full name</label><input class="pinp" id="p-name" placeholder="e.g. Amara Nwosu"/></div>
+            <div><label class="plabel">Age</label><input class="pinp" id="p-age" type="number" placeholder="e.g. 52"/></div>
+            <div><label class="plabel">Sex</label>
+              <select class="pinp" id="p-sex">
+                <option value="">Not specified</option>
+                <option>Female</option><option>Male</option><option>Other</option>
+              </select>
+            </div>
+            <div><label class="plabel">Previous scans</label><input class="pinp" id="p-scans" placeholder="e.g. Mammogram 2023 — normal"/></div>
+          </div>
+          <div style="margin-top:10px"><label class="plabel">Medical history</label><textarea class="ptextarea" id="p-history" placeholder="e.g. Family history of breast cancer, BRCA1 carrier, previous lumpectomy 2020..."></textarea></div>
+          <div style="margin-top:10px"><label class="plabel">Current symptoms / reason for scan</label><textarea class="ptextarea" id="p-symptoms" placeholder="e.g. Palpable lump in upper outer quadrant, noticed 3 weeks ago..."></textarea></div>
+        </div>
+      </div>
+
+      <div id="t-upload">
+        <div class="upload-zone" ondragover="event.preventDefault()" ondrop="event.preventDefault();loadFile(event.dataTransfer.files[0])">
+          <input type="file" accept="image/*" onchange="loadFile(this.files[0])"/>
+          <div style="font-size:32px;margin-bottom:10px">📤</div>
+          <div style="font-size:14px;font-weight:600;margin-bottom:6px">Drop a histopathology patch here</div>
+          <div style="font-size:12px;color:var(--muted)">PNG · JPG · TIFF · BMP</div>
+        </div>
+        <div id="preview-wrap" class="hidden mt16">
+          <img id="preview-img" class="simg" alt="Uploaded scan"/>
+          <div class="card-sm mt8" style="font-size:12px;color:var(--muted)" id="preview-name"></div>
+        </div>
+      </div>
+      <div id="t-overlay" class="hidden">
+        <div id="oph" class="sph"><div style="font-size:32px">🌡</div><div>Grad-CAM overlay</div><div style="font-size:11px;opacity:.6">Run analysis first</div></div>
+        <img id="oimg" class="simg hidden" alt="Overlay"/>
+        <div id="ostats" class="g2 mt12 hidden">
+          <div class="card-sm"><div style="font-size:10px;color:var(--muted);margin-bottom:3px">Mean activation</div><div class="mono" id="hmean" style="font-size:15px;font-weight:600">—</div></div>
+          <div class="card-sm"><div style="font-size:10px;color:var(--muted);margin-bottom:3px">Peak activation</div><div class="mono" id="hmax" style="font-size:15px;font-weight:600">—</div></div>
+        </div>
+      </div>
+      <div id="t-raw" class="hidden">
+        <div id="rph" class="sph"><div style="font-size:32px">📊</div><div>Raw heatmap</div><div style="font-size:11px;opacity:.6">Greyscale activation map</div></div>
+        <img id="rimg" class="simg hidden" alt="Heatmap"/>
+      </div>
+      <div class="f g8 mt16">
+        <button class="btn-p" id="abtn" style="flex:1" onclick="runAnalysis()" disabled>Analyse scan</button>
+        <button class="btn-o" onclick="resetAll()">Reset</button>
+      </div>
+      <div id="errbox" class="ebox hidden"></div>
+    </div>
+
+    <div>
+      <div id="rph2" class="card f ac" style="min-height:420px;justify-content:center;flex-direction:column;gap:8px;color:var(--muted)">
+        <div style="font-size:32px">🤖</div>
+        <div style="font-size:14px">Upload a scan and click Analyse</div>
+        <div style="font-size:12px;opacity:.6">Results appear here</div>
+      </div>
+      <div id="rpanel" class="hidden">
+        <div class="card">
+          <div class="slabel">AI prediction</div>
+          <div class="f ac jb mt8">
+            <div id="pbadge"></div>
+            <div class="mono" id="pconf" style="font-size:26px;font-weight:700"></div>
+          </div>
+          <div style="font-size:11px;color:var(--muted);margin:10px 0 5px">Confidence</div>
+          <div class="cbar"><div class="cfill" id="cfill" style="width:0%"></div></div>
+          <div class="g2 mt16" style="gap:10px">
+            <div><div style="font-size:11px;color:var(--muted);margin-bottom:3px">Logit · benign</div><div class="mono" id="lg0" style="font-size:14px;font-weight:600">—</div></div>
+            <div><div style="font-size:11px;color:var(--muted);margin-bottom:3px">Logit · malignant</div><div class="mono" id="lg1" style="font-size:14px;font-weight:600">—</div></div>
+          </div>
+        </div>
+        <div class="card mt16">
+          <div class="slabel">LLM explanation</div>
+          <div class="f ac g8 mt8 mb12" style="margin-bottom:12px">
+            <div class="dlive"></div>
+            <span class="mono" style="font-size:11px;color:var(--muted)" id="englab">template</span>
+            <span style="font-size:11px;color:var(--muted)" id="audlab"></span>
+          </div>
+          <div id="rsum" style="font-size:13px;line-height:1.65;padding-bottom:12px;border-bottom:.5px solid var(--border)"></div>
+          <div id="rdet" class="mt12" style="font-size:12px;color:var(--muted);line-height:1.6"></div>
+          <div id="rdisc" class="mt12" style="font-size:11px;color:#F09595;background:var(--red-dim);padding:8px 12px;border-radius:6px;border:.5px solid rgba(226,75,74,.2)"></div>
+        </div>
+        <div id="spatcard" class="card mt16 hidden">
+          <div class="slabel">Spatial analysis</div>
+          <div id="rspat" class="mt8" style="font-size:12px;color:var(--muted);line-height:1.6"></div>
+        </div>
+        <div class="mt12">
+          <button class="chip" onclick="document.getElementById('rawjson').classList.toggle('hidden')">Show raw JSON</button>
+          <pre id="rawjson" class="hidden mono" style="margin-top:10px;font-size:10px;color:var(--muted);background:var(--bg3);border:.5px solid var(--border);border-radius:7px;padding:12px;overflow-x:auto;white-space:pre-wrap;word-break:break-all;max-height:200px;overflow-y:auto"></pre>
+        </div>
+      </div>
+    </div>
+  </div>
+
+  <!-- Inline chat -->
+  <div id="chatwrap" class="hidden">
+    <div class="chat-panel">
+      <div class="chat-head">
+        <div class="f ac g10">
+          <div style="width:28px;height:28px;border-radius:7px;background:var(--teal-dim);display:flex;align-items:center;justify-content:center;font-size:13px">🤖</div>
+          <div>
+            <div style="font-weight:600;font-size:13px">AI assistant — ask follow-up questions about this scan</div>
+            <div class="f ac g6 mt8" style="margin-top:4px"><div class="dlive"></div><span class="mono" style="font-size:10px;color:var(--muted)" id="chatmode">Clinician mode</span></div>
+          </div>
+        </div>
+        <div id="chipbar" class="f g6" style="flex-wrap:wrap;justify-content:flex-end;max-width:440px"></div>
+      </div>
+      <div class="chat-body" id="chatbody"></div>
+      <div class="chat-foot">
+        <input class="cinp" id="chatin" placeholder="Ask a follow-up question about this scan..." onkeydown="if(event.key==='Enter')sendChat()"/>
+        <button class="btn-p" style="padding:8px 16px;font-size:12px" onclick="sendChat()">Ask</button>
+      </div>
+    </div>
+  </div>
+  <div style="margin-top:24px">
+    <div class="slabel">Try a sample — click to analyse</div>
+    <div class="sample-row">
+      <div class="sample" onclick="loadSample('samples/histo-tumor.png','histo-tumor.png','histo')">
+        <img src="samples/histo-tumor.png" alt="tumor patch"/><span>Tumor patch</span>
+      </div>
+      <div class="sample" onclick="loadSample('samples/histo-normal.png','histo-normal.png','histo')">
+        <img src="samples/histo-normal.png" alt="normal patch"/><span>Normal patch</span>
+      </div>
+    </div>
+  </div>
+  </div>
+  <div id="dash-mammo" class="hidden">
+  <div style="display:grid;grid-template-columns:1fr 1fr;gap:24px;align-items:start">
+    <div>
+      <div class="tab-bar">
+        <button class="tab active" onclick="switchMammoTab('upload',this)">Upload mammogram</button>
+        <button class="tab"        onclick="switchMammoTab('overlay',this)">Grad-CAM overlay</button>
+        <button class="tab"        onclick="switchMammoTab('raw',this)">Raw heatmap</button>
+      </div>
+      <div id="mt-upload">
+        <div class="upload-zone" ondragover="event.preventDefault()" ondrop="event.preventDefault();loadMammo(event.dataTransfer.files[0])">
+          <input type="file" accept="image/*,.dcm,.dicom" onchange="loadMammo(this.files[0])"/>
+          <svg class="svgi" style="width:30px;height:30px;margin-bottom:10px;stroke:var(--teal-lt)" viewBox="0 0 24 24"><path d="M12 16V4m0 0L8 8m4-4 4 4"/><path d="M4 16v2a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-2"/></svg>
+          <div style="font-size:14px;font-weight:600;margin-bottom:6px">Drop a mammogram here</div>
+          <div style="font-size:12px;color:var(--muted)">PNG · JPG · TIFF · DICOM (.dcm)</div>
+        </div>
+        <div id="mammo-preview-wrap" class="hidden mt16">
+          <img id="mammo-preview-img" class="simg" alt="Mammogram"/>
+          <div class="card-sm mt8" style="font-size:12px;color:var(--muted)" id="mammo-preview-name"></div>
+        </div>
+      </div>
+      <div id="mt-overlay" class="hidden">
+        <div id="moph" class="sph"><div style="font-size:32px">🌡</div><div>Grad-CAM overlay</div><div style="font-size:11px;opacity:.6">Run analysis first</div></div>
+        <img id="moimg" class="simg hidden" alt="Mammogram overlay"/>
+      </div>
+      <div id="mt-raw" class="hidden">
+        <div id="mrph" class="sph"><div style="font-size:32px">📊</div><div>Raw heatmap</div></div>
+        <img id="mrimg" class="simg hidden" alt="Mammogram heatmap"/>
+      </div>
+      <div class="f g8 mt16">
+        <button class="btn-p" id="mammo-btn" style="flex:1" onclick="runMammo()" disabled>Analyse mammogram</button>
+        <button class="btn-o" onclick="resetMammo()">Reset</button>
+      </div>
+      <div id="mammo-err" class="ebox hidden"></div>
+    </div>
+
+    <div>
+      <div id="mammo-rph" class="card f ac" style="min-height:420px;justify-content:center;flex-direction:column;gap:10px;color:var(--muted)">
+        <svg class="svgi" style="width:34px;height:34px;stroke:var(--muted)" viewBox="0 0 24 24"><rect x="3" y="3" width="18" height="18" rx="2"/><path d="M3 9h18M9 3v18"/></svg>
+        <div style="font-size:14px">Upload a mammogram and click Analyse</div>
+        <div style="font-size:12px;opacity:.6">Supports DICOM, PNG, and JPG</div>
+      </div>
+      <div id="mammo-rpanel" class="hidden">
+        <div class="card">
+          <div class="slabel">AI prediction</div>
+          <div id="mammo-banner" class="result-banner mt8">
+            <div class="rb-verdict" id="mammo-pbadge">—</div>
+            <div class="rb-conf"><div class="rb-num" id="mammo-pconf">—</div><div class="rb-lbl">confidence</div></div>
+          </div>
+          <div class="cbar mt16"><div class="cfill" id="mammo-cfill" style="width:0%"></div></div>
+          <div class="model-chip mt12" id="mammo-modelchip">AUC 0.84 · Sens 70% · Spec 82% · RSNA validation</div>
+          <div class="mt12 card-sm" style="background:var(--bg3)">
+            <div style="font-size:11px;color:var(--muted);margin-bottom:4px">BI-RADS suggestion</div>
+            <div id="mammo-birads" style="font-weight:600;font-size:13px"></div>
+          </div>
+          <details class="adv mt12">
+            <summary>Advanced — raw model outputs</summary>
+            <div class="g2" style="gap:10px;margin-top:4px">
+              <div><div style="font-size:11px;color:var(--muted);margin-bottom:3px">Logit · benign</div><div class="mono" id="mammo-lg0" style="font-size:14px;font-weight:600">—</div></div>
+              <div><div style="font-size:11px;color:var(--muted);margin-bottom:3px">Logit · malignant</div><div class="mono" id="mammo-lg1" style="font-size:14px;font-weight:600">—</div></div>
+            </div>
+          </details>
+        </div>
+        <div class="card mt16">
+          <div class="slabel">LLM explanation</div>
+          <div class="f ac g8 mt8" style="margin-bottom:12px">
+            <div class="dlive"></div>
+            <span class="mono" style="font-size:11px;color:var(--muted)" id="mammo-eng">AI summary</span>
+          </div>
+          <div id="mammo-sum" style="font-size:13px;line-height:1.65;padding-bottom:12px;border-bottom:.5px solid var(--border)"></div>
+          <div id="mammo-det" class="mt12" style="font-size:12px;color:var(--muted);line-height:1.6"></div>
+          <div id="mammo-disc" class="mt12" style="font-size:11px;color:#F09595;background:var(--red-dim);padding:8px 12px;border-radius:6px;border:.5px solid rgba(226,75,74,.2)"></div>
+        </div>
+      </div>
+    </div>
+  </div>
+
+  <div id="mammochatwrap" class="hidden" style="margin-top:24px">
+    <div class="chat-panel">
+      <div class="chat-head">
+        <div class="f ac g10">
+          <div style="width:28px;height:28px;border-radius:7px;background:var(--teal-dim);display:flex;align-items:center;justify-content:center"><svg class="svgi" viewBox="0 0 24 24"><path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/></svg></div>
+          <div>
+            <div style="font-weight:600;font-size:13px">AI assistant — ask about this mammogram</div>
+            <div class="f ac g6" style="margin-top:4px"><div class="dlive"></div><span class="mono" style="font-size:10px;color:var(--muted)">powered by gpt-oss-120b</span></div>
+          </div>
+        </div>
+        <div class="f g6" style="flex-wrap:wrap;justify-content:flex-end;max-width:440px">
+          <button class="chip" onclick="askMammo('Why was this mammogram classified this way?')">Why this result?</button>
+          <button class="chip" onclick="askMammo('What does the suggested BI-RADS category mean for next steps?')">BI-RADS</button>
+          <button class="chip" onclick="askMammo('What is the Grad-CAM heatmap showing here?')">Heatmap</button>
+          <button class="chip" onclick="askMammo('Given 70% sensitivity, how should this result be interpreted cautiously?')">Reliability</button>
+        </div>
+      </div>
+      <div class="chat-body" id="mammochatbody"></div>
+      <div class="chat-foot">
+        <input class="cinp" id="mammochatin" placeholder="Ask a follow-up about this mammogram..." onkeydown="if(event.key==='Enter')sendMammoChat()"/>
+        <button class="btn-p" style="padding:8px 16px;font-size:12px" onclick="sendMammoChat()">Ask</button>
+      </div>
+    </div>
+  </div>
+
+  <!-- Info panel -->
+  <div style="display:grid;grid-template-columns:repeat(3,1fr);gap:14px;margin-top:32px">
+    <div class="fcard"><div class="ficon"><svg class="svgi" viewBox="0 0 24 24"><rect x="3" y="3" width="18" height="18" rx="2"/><path d="M3 9h18M9 3v18"/></svg></div><div style="font-weight:600;font-size:14px;margin-bottom:6px">EfficientNet-B4</div><div style="font-size:12px;color:var(--muted);line-height:1.5">19M parameter CNN scaled for 512×512 full-field mammography. RSNA 2022 competition-proven architecture.</div></div>
+    <div class="fcard"><div class="ficon"><svg class="svgi" viewBox="0 0 24 24"><rect x="5" y="3" width="14" height="18" rx="2"/><path d="M9 3h6v3H9zM8 11h8M8 15h6"/></svg></div><div style="font-weight:600;font-size:14px;margin-bottom:6px">BI-RADS scoring</div><div style="font-size:12px;color:var(--muted);line-height:1.5">Automatic BI-RADS category suggestion (2–5) based on malignancy probability. Requires radiologist confirmation.</div></div>
+    <div class="fcard"><div class="ficon"><svg class="svgi" viewBox="0 0 24 24"><path d="M3 7a2 2 0 0 1 2-2h4l2 2h8a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/></svg></div><div style="font-weight:600;font-size:14px;margin-bottom:6px">DICOM support</div><div style="font-size:12px;color:var(--muted);line-height:1.5">Native DICOM (.dcm) loading with VOI LUT windowing. Also accepts PNG, JPG, and TIFF formats.</div></div>
+  </div>
+
+  <div class="card mt20" style="background:var(--bg3)">
+    <div style="font-size:12px;color:var(--muted);line-height:1.6">
+      <strong style="color:var(--text)">Research &amp; educational use only.</strong>
+      This EfficientNet-B4 ensemble (0.84 AUC, ~70% sensitivity / ~82% specificity on RSNA validation) is a research prototype — not a medical device and not a diagnosis. All outputs must be reviewed by a qualified radiologist.
+    </div>
+  </div>
+
+  <div style="margin-top:24px">
+    <div class="slabel">Try a sample — click to analyse</div>
+    <div class="sample-row">
+      <div class="sample" onclick="loadSample('samples/mammo-cancer.png','mammo-cancer.png','mammo')">
+        <img src="samples/mammo-cancer.png" alt="cancer case"/><span>Cancer case</span>
+      </div>
+      <div class="sample" onclick="loadSample('samples/mammo-benign.png','mammo-benign.png','mammo')">
+        <img src="samples/mammo-benign.png" alt="benign case"/><span>Benign case</span>
+      </div>
+    </div>
+  </div>
+  </div>
+</div>
+
+<!-- ASSISTANT -->
+<div id="v-assistant" class="page hidden">
+  <div style="display:grid;grid-template-columns:1fr 300px;gap:20px;align-items:start">
+    <div class="card" style="padding:0;overflow:hidden;display:flex;flex-direction:column;height:560px">
+      <div style="padding:14px 18px;border-bottom:.5px solid var(--border);display:flex;align-items:center;gap:10px">
+        <div style="width:32px;height:32px;border-radius:8px;background:var(--teal-dim);display:flex;align-items:center;justify-content:center;font-size:16px">🤖</div>
+        <div>
+          <div style="font-weight:600;font-size:14px">AI radiology assistant</div>
+          <div class="f ac g6 mt8" style="margin-top:4px"><div class="dlive"></div><span class="mono" style="font-size:10px;color:var(--muted)">DenseNet-121 · FLAN-T5 · Grad-CAM</span></div>
+        </div>
+      </div>
+      <div class="chat-body" id="asstbody" style="height:auto;flex:1"></div>
+      <div class="chip-row">
+        <button class="chip" onclick="askAsst('Why might a scan be classified as malignant?')">Why malignant?</button>
+        <button class="chip" onclick="askAsst('Explain what Grad-CAM shows')">Grad-CAM</button>
+        <button class="chip" onclick="askAsst('What does 87.5% sensitivity mean?')">Sensitivity</button>
+        <button class="chip" onclick="askAsst('How does FLAN-T5 generate explanations?')">How LLM works</button>
+      </div>
+      <div class="chat-foot">
+        <input class="cinp" id="asstinp" placeholder="Ask about the model, training, or a scan..." onkeydown="if(event.key==='Enter')sendAsst()"/>
+        <button class="btn-p" style="padding:8px 16px;font-size:12px" onclick="sendAsst()">Send</button>
+      </div>
+    </div>
+    <div class="fc g12">
+      <div class="card">
+        <div class="slabel">Quick topics</div>
+        <div class="fc g4 mt8">
+          <div onclick="askAsst('Explain the DenseNet-121 architecture')" style="padding:7px 8px;border-radius:6px;cursor:pointer;font-size:12px;color:var(--muted)" onmouseover="this.style.background='var(--bg3)'" onmouseout="this.style.background='transparent'">› DenseNet-121 architecture</div>
+          <div onclick="askAsst('What is StainJitter and why does it help?')" style="padding:7px 8px;border-radius:6px;cursor:pointer;font-size:12px;color:var(--muted)" onmouseover="this.style.background='var(--bg3)'" onmouseout="this.style.background='transparent'">› StainJitter augmentation</div>
+          <div onclick="askAsst('Explain OneCycleLR and why it helped training')" style="padding:7px 8px;border-radius:6px;cursor:pointer;font-size:12px;color:var(--muted)" onmouseover="this.style.background='var(--bg3)'" onmouseout="this.style.background='transparent'">› OneCycleLR scheduler</div>
+          <div onclick="askAsst('Explain PCam dataset deduplication')" style="padding:7px 8px;border-radius:6px;cursor:pointer;font-size:12px;color:var(--muted)" onmouseover="this.style.background='var(--bg3)'" onmouseout="this.style.background='transparent'">› PCam deduplication</div>
+          <div onclick="askAsst('How does Mixup augmentation work?')" style="padding:7px 8px;border-radius:6px;cursor:pointer;font-size:12px;color:var(--muted)" onmouseover="this.style.background='var(--bg3)'" onmouseout="this.style.background='transparent'">› Mixup augmentation</div>
+          <div onclick="askAsst('What improved sensitivity from 80% to 87.5%?')" style="padding:7px 8px;border-radius:6px;cursor:pointer;font-size:12px;color:var(--muted)" onmouseover="this.style.background='var(--bg3)'" onmouseout="this.style.background='transparent'">› Training improvements</div>
+        </div>
+      </div>
+      <div class="card">
+        <div class="slabel">Connect live scan</div>
+        <p style="font-size:12px;color:var(--muted);margin-top:8px;line-height:1.6">Run an analysis in the dashboard first, then return here to ask questions about that specific scan.</p>
+        <button class="btn-p" style="width:100%;margin-top:12px;font-size:12px" onclick="show('dashboard')">Open dashboard →</button>
+      </div>
+    </div>
+  </div>
+</div>
+
+<!-- RESEARCH -->
+<div id="v-research" class="page hidden">
+  <div class="slabel">Model card</div>
+  <h2 class="h2" style="margin-bottom:28px">Architecture, datasets &amp; methodology</h2>
+
+  <div class="slabel" style="margin-bottom:12px;color:var(--teal-lt)">Histopathology module</div>
+  <div class="g2">
+    <div class="fcard"><div style="font-weight:600;font-size:15px;margin-bottom:10px">DenseNet-121 backbone</div><div style="font-size:13px;color:var(--muted);line-height:1.6">~7.2M-parameter CNN pretrained on ImageNet. Dense-block feature reuse across layers. Custom head: BN→Dropout(0.4)→Linear(1024→256)→ReLU→BN→Dropout(0.3)→Linear(256→2).</div></div>
+    <div class="fcard"><div style="font-weight:600;font-size:15px;margin-bottom:10px">PatchCamelyon (PCam)</div><div style="font-size:13px;color:var(--muted);line-height:1.6">H&amp;E patches from Camelyon16 slides. After MD5 deduplication: 220,025 unique samples (benign 130,908 / malignant 89,117 → pos_weight 1.469). Patient-disjoint train / val / test splits.</div></div>
+    <div class="fcard"><div style="font-weight:600;font-size:15px;margin-bottom:10px">Training methodology</div><div style="font-size:13px;color:var(--muted);line-height:1.6">OneCycleLR (max_lr 3e-3, pct_start 0.3) · Mixup (α 0.4) · StainJitter (HED, strength 0.05) · label smoothing 0.1 · checkpoint by validation sensitivity.</div></div>
+    <div class="fcard"><div style="font-weight:600;font-size:15px;margin-bottom:10px">Histopathology results</div><div style="font-size:13px;color:var(--muted);line-height:1.6">Held-out test: 88.0% accuracy, 87.5% sensitivity (val sensitivity 90.3%, best epoch 13/20). Improvement vs baseline +6.8pp (80.7% → 87.5%).</div></div>
+  </div>
+
+  <div class="slabel" style="margin:28px 0 12px;color:var(--teal-lt)">Mammography module</div>
+  <div class="g2">
+    <div class="fcard"><div style="font-weight:600;font-size:15px;margin-bottom:10px">EfficientNet-B4 ensemble</div><div style="font-size:13px;color:var(--muted);line-height:1.6">Three EfficientNet-B4 models (seeds 42 / 123 / 999), probabilities averaged at inference. Member AUCs 0.7989 / 0.8254 / 0.8083.</div></div>
+    <div class="fcard"><div style="font-weight:600;font-size:15px;margin-bottom:10px">RSNA dataset &amp; preprocessing</div><div style="font-size:13px;color:var(--muted);line-height:1.6">RSNA Screening Mammography (2022). DICOM decoding with VOI-LUT windowing, resized for full-field input. Held-out patient-level validation split.</div></div>
+    <div class="fcard"><div style="font-weight:600;font-size:15px;margin-bottom:10px">Mammography results</div><div style="font-size:13px;color:var(--muted);line-height:1.6">Ensemble patient-level AUC 0.8443 · sensitivity 70.1% · specificity 82.4% (threshold 0.50). Suggested BI-RADS 2–5 derived from malignancy probability.</div></div>
+    <div class="fcard"><div style="font-weight:600;font-size:15px;margin-bottom:10px">Negative ablations</div><div style="font-size:13px;color:var(--muted);line-height:1.6">Breast-ROI cropping reduced AUC (~0.14 drop, aspect-ratio distortion); adding external CBIS-DDSM data hurt (film-vs-digital domain shift). The un-cropped, RSNA-only ensemble is final.</div></div>
+  </div>
+
+  <div class="slabel" style="margin:28px 0 12px;color:var(--teal-lt)">Shared layers — both modules</div>
+  <div class="g2">
+    <div class="fcard"><div style="font-weight:600;font-size:15px;margin-bottom:10px">Grad-CAM explainability</div><div style="font-size:13px;color:var(--muted);line-height:1.6">Gradients backpropagated w.r.t. the predicted class at the final conv block → global-average-pooled channel weights → weighted feature sum → ReLU → bilinear upsample to input resolution.</div></div>
+    <div class="fcard"><div style="font-weight:600;font-size:15px;margin-bottom:10px">LLM explanation layer</div><div style="font-size:13px;color:var(--muted);line-height:1.6">FLAN-T5-large / BioMedLM / Llama 3.2 with a deterministic template engine. Three audience modes (clinician, researcher, patient) with genuinely different content.</div></div>
+  </div>
+</div>
+
+<footer class="site-footer">
+  <div class="footer-disc">Research use only. Not a medical device and not a substitute for professional diagnosis.</div>
+  <div class="footer-row">
+    <div>
+      <div style="font-weight:600;color:var(--text)">MedAI — dual-modality breast cancer detection</div>
+      <div style="font-size:12px;color:var(--muted);margin-top:3px">Histopathology (DenseNet-121) + mammography (EfficientNet-B4 ensemble) · by Lateef Olatunji</div>
+    </div>
+    <div class="f g16 ac" style="flex-wrap:wrap;font-size:13px">
+      <a href="https://github.com/Relixsx" target="_blank" rel="noopener">GitHub</a>
+      <a href="mailto:relixsx@gmail.com">Contact</a>
+      <a href="#" onclick="show('research');return false;">Model card</a>
+      <span style="color:var(--muted)">MIT License</span>
+    </div>
+  </div>
+</footer>
+
+<script>
+  // ── Backend API base URL ───────────────────────────────────────────
+  // Local dev: leave blank — the app uses http://localhost:8000.
+  // Deployment: set to your backend's public URL (e.g. "https://api.example.com"),
+  //   or leave blank to call the same origin the page is served from.
+  window.MEDAI_API_URL =
+    (location.hostname === "localhost" || location.hostname === "127.0.0.1" || location.protocol === "file:")
+      ? ""                                    // local dev → uses http://localhost:8000
+      : "https://relixsx-medai.hf.space";     // deployed → Hugging Face Space backend
+</script>
+
+<script>
+var currentFile = null;
+var scanResult  = null;
+
+function togglePatient(){
+  var body=document.getElementById('pform-body');
+  var icon=document.getElementById('ptoggle-icon');
+  var hidden=body.classList.contains('hidden');
+  body.classList.toggle('hidden',!hidden);
+  icon.textContent=hidden?'▼':'▶';
+}
+
+var mammoFile = null;
+var mammoResult = null;
+
+function switchMammoTab(name,btn){
+  ['upload','overlay','raw'].forEach(function(t){document.getElementById('mt-'+t).classList.toggle('hidden',t!==name);});
+  document.querySelectorAll('#dash-mammo .tab').forEach(function(b){b.classList.remove('active');});
+  btn.classList.add('active');
+}
+
+function loadMammo(file){
+  if(!file)return;
+  mammoFile=file;
+  var r=new FileReader();
+  r.onload=function(e){
+    document.getElementById('mammo-preview-img').src=e.target.result;
+    document.getElementById('mammo-preview-name').textContent=file.name+' · '+(file.size/1024).toFixed(1)+' KB';
+    document.getElementById('mammo-preview-wrap').classList.remove('hidden');
+    document.getElementById('mammo-btn').disabled=false;
+  };
+  r.readAsDataURL(file);
+  document.getElementById('mammo-rph').style.display='';
+  document.getElementById('mammo-rpanel').classList.add('hidden');
+}
+
+function resetMammo(){
+  mammoFile=null; mammoResult=null;
+  document.getElementById('mammo-preview-wrap').classList.add('hidden');
+  document.getElementById('mammo-btn').disabled=true;
+  document.getElementById('mammo-rph').style.display='';
+  document.getElementById('mammo-rpanel').classList.add('hidden');
+  document.getElementById('mammo-err').classList.add('hidden');
+  ['mo','mr'].forEach(function(p){
+    document.getElementById(p+'img').classList.add('hidden');
+    document.getElementById(p+'ph').style.display='';
+  });
+}
+
+function runMammo(){
+  if(!mammoFile)return;
+  var btn=document.getElementById('mammo-btn'), err=document.getElementById('mammo-err');
+  btn.disabled=true; btn.textContent='Analysing...'; err.classList.add('hidden');
+  var aud=document.getElementById('audience').value;
+  var fd=new FormData(); fd.append('file',mammoFile);
+  fetch(getApi()+'/mammogram/visual?audience='+aud,{method:'POST',body:fd})
+    .then(function(r){
+      if(!r.ok)return r.json().then(function(e){throw new Error(e.detail||r.statusText);});
+      return r.json();
+    })
+    .then(function(d){mammoResult=d; renderMammo(d);})
+    .catch(function(e){err.textContent='Error: '+e.message; err.classList.remove('hidden');})
+    .finally(function(){btn.disabled=false; btn.textContent='Analyse mammogram';});
+}
+
+function renderMammo(d){
+  var mal=d.prediction==='malignant';
+  var banner=document.getElementById('mammo-banner');
+  banner.className='result-banner mt8 '+(mal?'suspicious':'benign');
+  var icon=mal
+    ? '<svg class="svgi" style="stroke:#F4A6A6" viewBox="0 0 24 24"><path d="M12 9v4m0 4h.01M10.3 3.9 1.8 18a2 2 0 0 0 1.7 3h17a2 2 0 0 0 1.7-3L13.7 3.9a2 2 0 0 0-3.4 0z"/></svg>'
+    : '<svg class="svgi" style="stroke:var(--teal-lt)" viewBox="0 0 24 24"><path d="M20 6 9 17l-5-5"/></svg>';
+  document.getElementById('mammo-pbadge').innerHTML=icon+(mal?'Suspicious':'Benign');
+  var pct=(d.confidence*100).toFixed(1)+'%';
+  document.getElementById('mammo-pconf').textContent=pct;
+  var cf=document.getElementById('mammo-cfill'); cf.style.width=pct;
+  cf.style.background=mal?'var(--red)':'var(--teal)';
+  document.getElementById('mammo-birads').textContent=d.birads||'—';
+  document.getElementById('mammo-lg0').textContent=d.logits[0].toFixed(4);
+  document.getElementById('mammo-lg1').textContent=d.logits[1].toFixed(4);
+  document.getElementById('mammo-eng').textContent=(d.engine && d.engine!=='template')?d.engine:'AI summary';
+  document.getElementById('mammo-sum').textContent=d.summary||'';
+  document.getElementById('mammo-det').textContent=d.detail||'';
+  document.getElementById('mammo-disc').textContent=d.disclaimer||'';
+  var mcw=document.getElementById('mammochatwrap');
+  if(mcw){ mcw.classList.remove('hidden'); mammoChatHistory=[]; document.getElementById('mammochatbody').innerHTML=''; }
+  if(d.overlay_b64){
+    var oi=document.getElementById('moimg'); oi.src='data:image/png;base64,'+d.overlay_b64; oi.classList.remove('hidden');
+    document.getElementById('moph').style.display='none';
+  }
+  if(d.heatmap_b64){
+    var ri=document.getElementById('mrimg'); ri.src='data:image/png;base64,'+d.heatmap_b64; ri.classList.remove('hidden');
+    document.getElementById('mrph').style.display='none';
+  }
+  document.getElementById('mammo-rph').style.display='none';
+  document.getElementById('mammo-rpanel').classList.remove('hidden');
+}
+
+function getApi(){
+  var u=(window.MEDAI_API_URL||'').replace(/\/$/,'');
+  if(u) return u;
+  var h=location.hostname;
+  if(location.protocol==='file:' || h==='localhost' || h==='127.0.0.1') return 'http://localhost:8000';
+  return location.origin;
+}
+window.addEventListener('load', checkHealth);
+
+function show(name){
+  ['platform','dashboard','assistant','research'].forEach(function(v){
+    document.getElementById('v-'+v).classList.toggle('hidden',v!==name);
+    if(document.getElementById('nb-'+v))document.getElementById('nb-'+v).classList.toggle('active',v===name);
+  });
+}
+
+function switchModality(name){
+  document.getElementById('dash-histo').classList.toggle('hidden',name!=='histo');
+  document.getElementById('dash-mammo').classList.toggle('hidden',name!=='mammo');
+  document.getElementById('mod-histo').classList.toggle('active',name==='histo');
+  document.getElementById('mod-mammo').classList.toggle('active',name==='mammo');
+  var sub=document.getElementById('dash-sub');
+  if(sub)sub.textContent = name==='mammo'
+    ? 'EfficientNet-B4 mammogram classifier \u00b7 BI-RADS scoring \u00b7 Grad-CAM'
+    : 'Upload a histopathology patch to run the full pipeline';
+}
+
+function checkHealth(){
+  var dot=document.getElementById('apidot'), st=document.getElementById('apistatus');
+  if(dot){dot.style.background='#888'; dot.style.animation='none';}
+  if(st)st.textContent='Checking…';
+  fetch(getApi()+'/health')
+    .then(function(r){if(!r.ok)throw 0; return r.json();})
+    .then(function(){
+      if(dot){dot.style.background='#2E8BF5'; dot.style.animation='pulse 1.5s ease infinite';}
+      if(st)st.textContent='API online';
+    })
+    .catch(function(){
+      if(dot){dot.style.background='#E24B4A'; dot.style.animation='none';}
+      if(st)st.textContent='API offline';
+    });
+}
+
+function loadSample(url,name,modality){
+  fetch(url).then(function(r){
+    if(!r.ok)throw new Error('not found');
+    return r.blob();
+  }).then(function(blob){
+    var file=new File([blob],name,{type:blob.type||'image/png'});
+    if(modality==='mammo'){ if(typeof switchModality==='function')switchModality('mammo'); loadMammo(file); setTimeout(runMammo,200); }
+    else { if(typeof switchModality==='function')switchModality('histo'); loadFile(file); setTimeout(runAnalysis,200); }
+    window.scrollTo({top:0,behavior:'smooth'});
+  }).catch(function(){
+    alert('Could not load the sample image.\n\nIf you opened the page directly (file://), browsers block loading local images. Serve it over HTTP instead:\n\n  cd frontend\n  python3 -m http.server 5500\n\nthen open http://localhost:5500\n\nAlso make sure frontend/samples/ contains the image files.');
+  });
+}
+
+function loadFile(file){
+  if(!file)return;
+  currentFile=file;
+  var r=new FileReader();
+  r.onload=function(e){
+    document.getElementById('preview-img').src=e.target.result;
+    document.getElementById('preview-name').textContent=file.name+' · '+(file.size/1024).toFixed(1)+' KB';
+    document.getElementById('preview-wrap').classList.remove('hidden');
+    document.getElementById('abtn').disabled=false;
+  };
+  r.readAsDataURL(file);
+  resetResults();
+}
+
+function switchTab(name,btn){
+  ['upload','overlay','raw'].forEach(function(t){document.getElementById('t-'+t).classList.toggle('hidden',t!==name);});
+  document.querySelectorAll('#dash-histo .tab').forEach(function(b){b.classList.remove('active');});
+  btn.classList.add('active');
+}
+
+function resetAll(){
+  currentFile=null; scanResult=null;
+  document.getElementById('preview-wrap').classList.add('hidden');
+  document.getElementById('abtn').disabled=true;
+  document.getElementById('chatwrap').classList.add('hidden');
+  resetResults();
+  ['o','r'].forEach(function(p){
+    document.getElementById(p+'img').classList.add('hidden');
+    document.getElementById(p+'ph').style.display='';
+  });
+  document.getElementById('ostats').classList.add('hidden');
+}
+
+function resetResults(){
+  document.getElementById('rph2').style.display='';
+  document.getElementById('rpanel').classList.add('hidden');
+  document.getElementById('errbox').classList.add('hidden');
+  document.getElementById('rawjson').classList.add('hidden');
+}
+
+function runAnalysis(){
+  if(!currentFile)return;
+  var btn=document.getElementById('abtn'), err=document.getElementById('errbox');
+  btn.disabled=true; btn.textContent='Analysing...'; err.classList.add('hidden');
+  var aud=document.getElementById('audience').value;
+  var fd=new FormData(); fd.append('file',currentFile);
+  fetch(getApi()+'/explain/visual?audience='+aud,{method:'POST',body:fd})
+    .then(function(r){
+      if(!r.ok)return r.json().then(function(e){throw new Error(e.detail||r.statusText);});
+      return r.json();
+    })
+    .then(function(d){scanResult=d; renderResults(d,aud);})
+    .catch(function(e){err.textContent='Error: '+e.message; err.classList.remove('hidden');})
+    .finally(function(){btn.disabled=false; btn.textContent='Analyse scan';});
+}
+
+function renderResults(d,aud){
+  var badge=document.getElementById('pbadge');
+  badge.innerHTML=d.prediction==='malignant'?'<span class="bdanger">⚠ Malignant</span>':'<span class="bsafe">✓ Benign</span>';
+  var pct=(d.confidence*100).toFixed(1)+'%';
+  var pc=document.getElementById('pconf'); pc.textContent=pct; pc.style.color=d.prediction==='malignant'?'var(--red)':'var(--teal)';
+  var cf=document.getElementById('cfill'); cf.style.width=pct; cf.style.background=d.prediction==='malignant'?'var(--red)':'var(--teal)';
+  document.getElementById('lg0').textContent=d.logits[0].toFixed(4);
+  document.getElementById('lg1').textContent=d.logits[1].toFixed(4);
+  document.getElementById('englab').textContent=d.engine;
+  document.getElementById('audlab').textContent='· '+aud;
+  document.getElementById('rsum').textContent=d.summary;
+  document.getElementById('rdet').textContent=d.detail;
+  document.getElementById('rdisc').textContent=d.disclaimer;
+  if(d.spatial_summary){document.getElementById('rspat').textContent=d.spatial_summary; document.getElementById('spatcard').classList.remove('hidden');}
+  if(d.overlay_b64){
+    var oi=document.getElementById('oimg'); oi.src='data:image/png;base64,'+d.overlay_b64; oi.classList.remove('hidden');
+    document.getElementById('oph').style.display='none'; document.getElementById('ostats').classList.remove('hidden');
+    document.getElementById('hmean').textContent=(d.heatmap_mean*100).toFixed(1)+'%';
+    document.getElementById('hmax').textContent=(d.heatmap_max*100).toFixed(1)+'%';
+  }
+  if(d.heatmap_b64){
+    var ri=document.getElementById('rimg'); ri.src='data:image/png;base64,'+d.heatmap_b64; ri.classList.remove('hidden');
+    document.getElementById('rph').style.display='none';
+  }
+  document.getElementById('rawjson').textContent=JSON.stringify(d,null,2);
+  document.getElementById('rph2').style.display='none';
+  document.getElementById('rpanel').classList.remove('hidden');
+  openChat(d,aud);
+}
+
+var CHIPS={
+  clinician:['Why this result?','BI-RADS score?','Biopsy needed?','Grad-CAM regions','Model accuracy'],
+  researcher:['Logit math','Grad-CAM method','Training details','Dataset stats','Calibration?'],
+  patient:['Should I worry?','What does this mean?','What happens next?','How accurate?','Explain heatmap'],
+};
+
+function openChat(result,aud){
+  document.getElementById('chatmode').textContent=aud.charAt(0).toUpperCase()+aud.slice(1)+' mode';
+  var bar=document.getElementById('chipbar'); bar.innerHTML='';
+  (CHIPS[aud]||CHIPS.clinician).forEach(function(q){
+    var b=document.createElement('button'); b.className='chip'; b.textContent=q;
+    b.onclick=function(){sendChatMsg(q);}; bar.appendChild(b);
+  });
+  var msgs=document.getElementById('chatbody'); msgs.innerHTML='';
+  var greets={
+    clinician:'Analysis complete. '+result.prediction.toUpperCase()+' at '+(result.confidence*100).toFixed(1)+'% confidence. What would you like to explore further?',
+    researcher:'Output: '+result.prediction.toUpperCase()+' | logits=['+result.logits.map(function(l){return l.toFixed(4);}).join(', ')+'] | P='+result.confidence.toFixed(4)+'. Ask me anything about the model internals.',
+    patient:result.prediction==='malignant'?"The AI flagged something in this sample. I'm here to help you understand what this means. What would you like to know?"
+      :"Good news — the AI found no signs of abnormal tissue. Do you have any questions?",
+  };
+  addCMsg(greets[aud]||greets.clinician,'ai');
+  document.getElementById('chatwrap').classList.remove('hidden');
+  document.getElementById('chatwrap').scrollIntoView({behavior:'smooth',block:'nearest'});
+}
+
+function addCMsg(text,role){
+  var msgs=document.getElementById('chatbody');
+  var d=document.createElement('div'); d.className=role==='ai'?'mai':'muser'; d.textContent=text;
+  msgs.appendChild(d); msgs.scrollTop=msgs.scrollHeight;
+}
+
+function showTypingC(){
+  var msgs=document.getElementById('chatbody');
+  var d=document.createElement('div'); d.className='mai'; d.id='typingc';
+  d.innerHTML='<span class="td"></span><span class="td"></span><span class="td"></span>';
+  msgs.appendChild(d); msgs.scrollTop=msgs.scrollHeight;
+}
+function removeTypingC(){var e=document.getElementById('typingc');if(e)e.remove();}
+
+function sendChat(){
+  var inp=document.getElementById('chatin'), msg=inp.value.trim();
+  if(!msg||!scanResult)return; inp.value=''; sendChatMsg(msg);
+}
+
+function sendChatMsg(message){
+  if(!scanResult)return;
+  addCMsg(message,'user'); showTypingC();
+  var aud=document.getElementById('audience').value;
+  var patient={
+    name:document.getElementById('p-name').value,
+    age:parseInt(document.getElementById('p-age').value)||0,
+    sex:document.getElementById('p-sex').value,
+    medical_history:document.getElementById('p-history').value,
+    symptoms:document.getElementById('p-symptoms').value,
+    previous_scans:document.getElementById('p-scans').value,
+  };
+  fetch(getApi()+'/chat',{
+    method:'POST', headers:{'Content-Type':'application/json'},
+    body:JSON.stringify({message:message,audience:aud,prediction:scanResult.prediction,
+      confidence:scanResult.confidence,logits:scanResult.logits,
+      spatial_summary:scanResult.spatial_summary||'',history:[],patient:patient}),
+  })
+    .then(function(r){return r.json();})
+    .then(function(d){removeTypingC(); addCMsg(d.response||'No response.','ai');})
+    .catch(function(e){removeTypingC(); addCMsg('Error: '+e.message,'ai');});
+}
+
+var KB={
+  'why might a scan be classified as malignant':'DenseNet-121 flags a scan as malignant when it detects feature patterns associated with cancerous tissue — irregular nuclear morphology, high cell density, distorted architecture. The Grad-CAM overlay shows exactly which spatial regions triggered these activations.',
+  'explain what grad-cam shows':"Grad-CAM backpropagates the class score's gradient through the final convolutional layer (norm5, 1024×7×7 maps). Channel importance weights are computed via global average pooling of gradients, then used to create a weighted sum of feature maps. ReLU removes negative activations. The result is upsampled to 224×224 and overlaid using a jet colourmap — red = high attention, blue = low attention.",
+  'what does 87.5% sensitivity mean':'Sensitivity of 87.5% means the model correctly identifies 87.5% of actual malignant patches. The 12.5% are missed tumour patches (false negatives). For cancer screening, sensitivity is the most critical metric — missing a cancer is far worse than a false alarm.',
+  'how does flan-t5 generate explanations':'FLAN-T5-large (~780MB) runs entirely locally. The LLMExplainer builds a structured prompt with prediction, confidence, logits, and Grad-CAM spatial findings. A deterministic TemplateEngine provides audience-specific structure; FLAN-T5 supplements with natural language.',
+  'explain the densenet-121 architecture':'DenseNet-121 has 4 dense blocks where every layer receives feature maps from ALL preceding layers via concatenation. This enables feature reuse, reduces vanishing gradients, and allows learning both low-level and high-level features simultaneously.',
+  'what is stainji':'StainJitter perturbs H&E stain concentrations in HED colour space using the Ruifrok & Johnston deconvolution matrix. It randomly scales and shifts each stain channel then reconstructs RGB, simulating real-world staining variation between labs.',
+  'explain onecyclelr':'OneCycleLR ramps the learning rate from low up to max_lr (3e-3) over the first 30% of training, then cosine-anneals back to near zero — stepping every batch. This is why the model kept improving through epoch 13 instead of peaking at epoch 1-2.',
+  'explain pcam dataset deduplication':'The original PCam dataset has 262,144 training images appearing perfectly 50/50 balanced. After MD5 dedup: 220,025 unique samples. Hidden truth: 42,119 duplicate malignant patches were removed, revealing the real distribution is 60% benign / 40% malignant (pos_weight=1.469).',
+  'how does mixup augmentation work':'Mixup blends two training images: mixed = λ·imageA + (1-λ)·imageB with labels also blended. λ is sampled from Beta(0.4, 0.4). This forces the model to learn smooth decision boundaries rather than memorising hard boundaries around specific training examples.',
+  'what improved sensitivity':'Three changes drove sensitivity from 80.7% to 87.5%: (1) PCam deduplication — fixed hidden class imbalance; (2) OneCycleLR — model found better minima and kept improving through epoch 13; (3) Checkpoint by val_sensitivity — stopped selecting low-sensitivity checkpoints.',
+};
+
+function askAsst(q){document.getElementById('asstinp').value=q; sendAsst();}
+
+var asstHistory=[];
+
+function fmtMd(t){
+  var s=t.replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;');
+  var blocks=[];
+  s=s.replace(/```([\s\S]*?)```/g,function(m,c){
+    blocks.push('<pre><code>'+c.replace(/^\n+|\n+$/g,'')+'</code></pre>');
+    return '\u0001'+(blocks.length-1)+'\u0001';
+  });
+  function inline(x){
+    return x.replace(/\*\*([^*]+)\*\*/g,'<strong>$1</strong>')
+            .replace(/`([^`]+)`/g,'<code>$1</code>');
+  }
+  var lines=s.split('\n'), out=[], i=0;
+  while(i<lines.length){
+    var ln=lines[i], ph=ln.match(/^\u0001(\d+)\u0001$/);
+    if(ph){ out.push(blocks[+ph[1]]); i++; continue; }
+    var h=ln.match(/^(#{1,5})\s+(.*)$/);
+    if(h){ var lv=Math.min(h[1].length+2,5); out.push('<h'+lv+'>'+inline(h[2])+'</h'+lv+'>'); i++; continue; }
+    if(/^\s*[-*]\s+/.test(ln)){
+      var ul=[];
+      while(i<lines.length && /^\s*[-*]\s+/.test(lines[i])){ ul.push('<li>'+inline(lines[i].replace(/^\s*[-*]\s+/,''))+'</li>'); i++; }
+      out.push('<ul>'+ul.join('')+'</ul>'); continue;
+    }
+    if(/^\s*\d+\.\s+/.test(ln)){
+      var ol=[];
+      while(i<lines.length && /^\s*\d+\.\s+/.test(lines[i])){ ol.push('<li>'+inline(lines[i].replace(/^\s*\d+\.\s+/,''))+'</li>'); i++; }
+      out.push('<ol>'+ol.join('')+'</ol>'); continue;
+    }
+    if(ln.trim()===''){ i++; continue; }
+    var para=[ln]; i++;
+    while(i<lines.length && lines[i].trim()!=='' &&
+          !/^(#{1,5}\s|\s*[-*]\s|\s*\d+\.\s)/.test(lines[i]) &&
+          !/^\u0001\d+\u0001$/.test(lines[i])){ para.push(lines[i]); i++; }
+    out.push('<p>'+inline(para.join(' '))+'</p>');
+  }
+  return out.join('');
+}
+
+function sendAsst(){
+  var inp=document.getElementById('asstinp'), msg=inp.value.trim();
+  if(!msg)return; inp.value='';
+  addAMsg(msg,'user');
+  asstHistory.push({role:'user',content:msg});
+  var bubble=addAMsg('','ai'); bubble.classList.add('md'); bubble.textContent='…';
+  fetch(getApi()+'/chat/stream',{
+    method:'POST', headers:{'Content-Type':'application/json'},
+    body:JSON.stringify({messages:asstHistory, audience:'clinician'})
+  }).then(function(r){
+    if(!r.ok||!r.body){ bubble.textContent='Error: '+(r.statusText||'no response'); return; }
+    var reader=r.body.getReader(), dec=new TextDecoder(), acc='';
+    bubble.textContent='';
+    function pump(){
+      return reader.read().then(function(res){
+        if(res.done){ asstHistory.push({role:'assistant',content:acc}); return; }
+        acc+=dec.decode(res.value,{stream:true});
+        bubble.innerHTML=fmtMd(acc);
+        var b=document.getElementById('asstbody'); b.scrollTop=b.scrollHeight;
+        return pump();
+      });
+    }
+    return pump();
+  }).catch(function(e){ bubble.textContent='Error: '+e.message; });
+}
+
+function addAMsg(text,role){
+  var msgs=document.getElementById('asstbody');
+  var d=document.createElement('div'); d.className=role==='ai'?'mai':'muser'; d.textContent=text;
+  msgs.appendChild(d); msgs.scrollTop=msgs.scrollHeight;
+  return d;
+}
+
+var mammoChatHistory=[];
+function askMammo(q){ document.getElementById('mammochatin').value=q; sendMammoChat(); }
+function addMMsg(text,role){
+  var b=document.getElementById('mammochatbody');
+  var d=document.createElement('div'); d.className=role==='ai'?'mai':'muser'; d.textContent=text;
+  b.appendChild(d); b.scrollTop=b.scrollHeight; return d;
+}
+function sendMammoChat(){
+  var inp=document.getElementById('mammochatin'), msg=inp.value.trim();
+  if(!msg||!mammoResult)return; inp.value='';
+  addMMsg(msg,'user');
+  mammoChatHistory.push({role:'user',content:msg});
+  var bubble=addMMsg('','ai'); bubble.classList.add('md'); bubble.textContent='…';
+  var aud=document.getElementById('audience')?document.getElementById('audience').value:'clinician';
+  fetch(getApi()+'/chat/stream',{
+    method:'POST', headers:{'Content-Type':'application/json'},
+    body:JSON.stringify({
+      messages:mammoChatHistory, audience:aud,
+      prediction:mammoResult.prediction||'',
+      confidence:mammoResult.confidence||0,
+      logits:mammoResult.logits||[0,0],
+      birads:mammoResult.birads||'',
+      spatial_summary:mammoResult.spatial_summary||mammoResult.detail||''
+    })
+  }).then(function(r){
+    if(!r.ok||!r.body){ bubble.textContent='Error: '+(r.statusText||'no response'); return; }
+    var reader=r.body.getReader(), dec=new TextDecoder(), acc=''; bubble.textContent='';
+    function pump(){ return reader.read().then(function(res){
+      if(res.done){ mammoChatHistory.push({role:'assistant',content:acc}); return; }
+      acc+=dec.decode(res.value,{stream:true}); bubble.innerHTML=fmtMd(acc);
+      var b=document.getElementById('mammochatbody'); b.scrollTop=b.scrollHeight; return pump();
+    });}
+    return pump();
+  }).catch(function(e){ bubble.textContent='Error: '+e.message; });
+}
+
+addAMsg("Hello, I'm your AI radiology assistant. I can explain the model, training methodology, Grad-CAM, and more. What would you like to know?",'ai');
+checkHealth();
+</script>
+</body>
+</html>

modal_mammogram.py

@@ -0,0 +1,858 @@
+"""
+modal_mammogram.py
+───────────────────
+Research-grade EfficientNet-B4 mammogram training — five innovations:
+
+  1. Multi-View Patient Fusion   — Siamese EfficientNet + ViewAttentionFusion
+  2. Focal Loss                  — α=0.25, γ=2, handles 1.5% cancer rate
+  3. Mixed Precision (AMP)       — 2× faster, GradScaler
+  4. Test-Time Augmentation      — in mammogram_inference.py
+  5. Progressive Resizing        — 256→384→512 curriculum
+
+Datasets:
+  Training:         RSNA 2022 (USA, Kaggle)         54,706 images
+  External val:     VinDr-Mammo (Vietnam, Kaggle)   20,000 images
+
+Run:
+  modal run modal_mammogram.py                  # full training
+  modal run modal_mammogram.py --debug          # 5%, 2 epochs
+  modal run modal_mammogram.py --skip-phase1    # resume phase 2
+"""
+
+from __future__ import annotations
+
+import csv
+import json
+import logging
+import os
+import time
+from pathlib import Path
+
+import modal
+
+# ── Modal app ──────────────────────────────────────────────────────────────────
+app = modal.App("medai-mammogram-research")
+
+image = (
+    modal.Image.debian_slim(python_version="3.11")
+    .pip_install(
+        "torch==2.2.0", "torchvision==0.17.0",
+        "numpy<2.0", "pillow",
+        "pydicom", "pylibjpeg", "python-gdcm",
+        "kaggle", "pandas", "scikit-learn",
+        "scipy", "tqdm", "matplotlib",
+    )
+    .apt_install("libgomp1", "unzip", "wget")
+
+)
+
+rsna_vol   = modal.Volume.from_name("rsna-mammogram-cache",  create_if_missing=True)
+vindr_vol  = modal.Volume.from_name("vindr-mammo-cache",     create_if_missing=True)
+out_vol    = modal.Volume.from_name("mammogram-outputs",     create_if_missing=True)
+
+DATA_RSNA  = "/data/rsna"
+DATA_VINDR = "/data/vindr"
+OUT_DIR    = "/outputs"
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s  %(levelname)-8s %(message)s",
+    datefmt="%H:%M:%S",
+)
+logger = logging.getLogger(__name__)
+
+
+# ── DICOM loader ───────────────────────────────────────────────────────────────
+def _dicom_to_rgb(path: str):
+    import numpy as np, pydicom
+    from PIL import Image
+    from pydicom.pixel_data_handlers.util import apply_voi_lut
+    dcm = pydicom.dcmread(path)
+    try:
+        arr = apply_voi_lut(dcm.pixel_array, dcm)
+    except Exception:
+        arr = dcm.pixel_array.astype(np.float32)
+    arr = arr.astype(np.float32)
+    mn, mx = arr.min(), arr.max()
+    if mx > mn:
+        arr = (arr - mn) / (mx - mn) * 255.0
+    arr = arr.astype(np.uint8)
+    if getattr(dcm, "PhotometricInterpretation", "") == "MONOCHROME1":
+        arr = 255 - arr
+    if arr.ndim == 2:
+        arr = np.stack([arr, arr, arr], axis=-1)
+    return Image.fromarray(arr, mode="RGB")
+
+
+# ── Metrics ────────────────────────────────────────────────────────────────────
+def compute_metrics(y_true, y_prob, threshold=0.5):
+    import numpy as np
+    from sklearn.metrics import roc_auc_score, confusion_matrix, f1_score
+    y_true = np.array(y_true)
+    y_prob = np.array(y_prob)
+    y_pred = (y_prob >= threshold).astype(int)
+    auc = roc_auc_score(y_true, y_prob) if len(set(y_true)) > 1 else 0.0
+    cm  = confusion_matrix(y_true, y_pred)
+    tn, fp, fn, tp = cm.ravel() if cm.size == 4 else (0, 0, 0, 0)
+    return {
+        "auc":         round(float(auc), 4),
+        "sensitivity": round(tp / max(tp + fn, 1), 4),
+        "specificity": round(tn / max(tn + fp, 1), 4),
+        "ppv":         round(tp / max(tp + fp, 1), 4),
+        "npv":         round(tn / max(tn + fn, 1), 4),
+        "accuracy":    round((tp + tn) / max(len(y_true), 1), 4),
+        "f1":          round(float(f1_score(y_true, y_pred, zero_division=0)), 4),
+        "n_pos":       int(y_true.sum()),
+        "n_neg":       int((1 - y_true).sum()),
+    }
+
+
+def youden_threshold(y_true, y_prob):
+    import numpy as np
+    from sklearn.metrics import roc_curve
+    fpr, tpr, thr = roc_curve(y_true, y_prob)
+    j = tpr - fpr
+    return float(thr[np.argmax(j)])
+
+
+def bootstrap_auc_ci(y_true, y_prob, n=1000):
+    import numpy as np
+    from sklearn.metrics import roc_auc_score
+    rng = np.random.default_rng(42)
+    y_true, y_prob = np.array(y_true), np.array(y_prob)
+    aucs = []
+    for _ in range(n):
+        idx = rng.integers(0, len(y_true), len(y_true))
+        yt, yp = y_true[idx], y_prob[idx]
+        if len(set(yt)) > 1:
+            aucs.append(roc_auc_score(yt, yp))
+    return round(float(np.percentile(aucs, 2.5)), 4), round(float(np.percentile(aucs, 97.5)), 4)
+
+
+# ── Training function ──────────────────���───────────────────────────────────────
+@app.function(
+    image=image, gpu="a10g", timeout=86400,
+    volumes={DATA_RSNA: rsna_vol, DATA_VINDR: vindr_vol, OUT_DIR: out_vol},
+    secrets=[modal.Secret.from_name("kaggle"), modal.Secret.from_name("physionet")],
+
+)
+def train(
+    phase1_epochs: int   = 5,
+    phase2_epochs: int   = 15,
+    batch_size:    int   = 8,
+    phase1_lr:     float = 3e-4,
+    phase2_lr:     float = 5e-5,
+    max_lr:        float = 1e-3,
+    focal_alpha:   float = 0.25,
+    focal_gamma:   float = 2.0,
+    skip_phase1:   bool  = False,
+    debug:         bool  = False,
+    seed:          int   = 42,
+    num_workers:   int   = 4,
+) -> dict:
+
+    import random, sys
+    import numpy as np
+    import pandas as pd
+    import torch
+    import torch.nn as nn
+    from PIL import Image
+    from sklearn.model_selection import train_test_split
+    from torch.optim import AdamW
+    from torch.optim.lr_scheduler import OneCycleLR
+    from torch.utils.data import Dataset, DataLoader
+    from torchvision import transforms
+
+    os.environ["PYTORCH_CUDA_ALLOC_CONF"] = "expandable_segments:True"
+    random.seed(seed)
+    np.random.seed(seed)
+    torch.manual_seed(seed)
+    torch.cuda.manual_seed_all(seed)
+
+    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    if torch.cuda.is_available():
+        logger.info("GPU : %s", torch.cuda.get_device_name(0))
+        logger.info("VRAM: %.1f GB",
+                    torch.cuda.get_device_properties(0).total_memory / 1e9)
+
+    logger.info("=" * 70)
+    logger.info("  EfficientNet-B4 Mammogram Training — 5 Innovations")
+    logger.info("  1. Multi-view patient fusion  (Siamese + Attention)")
+    logger.info("  2. Focal Loss                 (α=%.2f, γ=%.1f)",
+                focal_alpha, focal_gamma)
+    logger.info("  3. Mixed Precision AMP        (GradScaler)")
+    logger.info("  4. TTA                        (inference — mammogram_inference.py)")
+    logger.info("  5. Progressive Resizing       (256→384→512)")
+    logger.info("  Train:    RSNA 2022 (USA)")
+    logger.info("  Ext val:  VinDr-Mammo (Vietnam)")
+    logger.info("=" * 70)
+
+    # ── Download datasets ──────────────────────────────────────────────────────
+    import subprocess
+
+    rsna_dir  = Path(DATA_RSNA)
+    vindr_dir = Path(DATA_VINDR)
+
+    if not (rsna_dir / "train.csv").exists():
+        logger.info("Downloading RSNA 2022 (~300 GB)...")
+        os.makedirs(str(rsna_dir), exist_ok=True)
+
+        # Delete any partial zip on the volume from previous failed run
+        for old_zip in [rsna_dir / "rsna-breast-cancer-detection.zip"]:
+            if old_zip.exists():
+                logger.info("Removing partial zip from previous run...")
+                os.remove(str(old_zip))
+
+        # Download zip to /tmp (ephemeral container storage, not the volume)
+        # Volume only stores unzipped files (~300GB), not zip+unzipped (~570GB)
+        logger.info("Downloading zip to /tmp...")
+        subprocess.run([
+            "kaggle", "competitions", "download",
+            "-c", "rsna-breast-cancer-detection",
+            "-p", "/tmp",
+        ], check=True)
+
+        import glob as _glob
+        zips = _glob.glob("/tmp/*.zip")
+        tmp_zip = zips[0] if zips else "/tmp/rsna-breast-cancer-detection.zip"
+
+        logger.info("Unzipping to volume (%s)...", rsna_dir)
+        subprocess.run(["unzip", "-q", tmp_zip, "-d", str(rsna_dir)], check=True)
+
+        os.remove(tmp_zip)
+        logger.info("Done — zip removed from /tmp.")
+        rsna_vol.commit()
+
+    if not (vindr_dir / "breast-level_annotations.csv").exists():
+        logger.info("Downloading VinDr-Mammo from PhysioNet (~70 GB)...")
+        os.makedirs(str(vindr_dir), exist_ok=True)
+        pn_user = os.environ.get("PHYSIONET_USERNAME", "")
+        pn_pass = os.environ.get("PHYSIONET_PASSWORD", "")
+        # Download only CSV annotations first (fast, ~1MB)
+        for csv_file in ["breast-level_annotations.csv", "finding_annotations.csv"]:
+            subprocess.run([
+                "wget", "-N", "-c", "-q",
+                f"--user={pn_user}",
+                f"--password={pn_pass}",
+                "-P", str(vindr_dir),
+                f"https://physionet.org/files/vindr-mammo/1.0.0/{csv_file}",
+            ], check=True)
+
+        # Download DICOM images recursively — skip HTML pages
+        subprocess.run([
+            "wget", "-r", "-N", "-c", "-np", "-q",
+            "--accept=*.dicom,*.dcm",
+            "--reject=*.html,*.php,index*,robots*",
+            f"--user={pn_user}",
+            f"--password={pn_pass}",
+            "-P", str(vindr_dir),
+            "https://physionet.org/files/vindr-mammo/1.0.0/images/",
+        ], check=True)
+        import shutil
+        nested = vindr_dir / "physionet.org" / "files" / "vindr-mammo" / "1.0.0"
+        if nested.exists():
+            for item in nested.iterdir():
+                shutil.move(str(item), str(vindr_dir / item.name))
+            shutil.rmtree(str(vindr_dir / "physionet.org"))
+        vindr_vol.commit()
+        logger.info("VinDr-Mammo downloaded from PhysioNet.")
+
+    # ── Load and prepare RSNA labels ───────────────────────────────────────────
+    rsna_df = pd.read_csv(rsna_dir / "train.csv")
+    logger.info("RSNA — %d images | cancer rate: %.1f%%",
+                len(rsna_df), 100 * rsna_df["cancer"].mean())
+
+    if debug:
+        rsna_df = rsna_df.sample(frac=0.05, random_state=seed).reset_index(drop=True)
+        phase1_epochs = min(2, phase1_epochs)
+        phase2_epochs = min(2, phase2_epochs)
+        logger.info("DEBUG: %d RSNA samples", len(rsna_df))
+
+    # ── Innovation 1: Build multi-view pairs ───────────────────────────────────
+    # Group by patient + laterality to get CC+MLO pairs
+    # Each case = one breast = (CC image, MLO image, cancer label)
+    logger.info("Building multi-view pairs (patient × laterality)...")
+    cases = []
+    view_col = "view" if "view" in rsna_df.columns else None
+
+    if view_col and "laterality" in rsna_df.columns:
+        for (pid, lat), grp in rsna_df.groupby(["patient_id", "laterality"]):
+            cc_rows  = grp[grp[view_col] == "CC"]
+            mlo_rows = grp[grp[view_col] == "MLO"]
+            label    = int(grp["cancer"].max())
+            if len(cc_rows) > 0 and len(mlo_rows) > 0:
+                cases.append({
+                    "patient_id":  pid,
+                    "laterality":  lat,
+                    "cc_img":      cc_rows.iloc[0]["image_id"],
+                    "mlo_img":     mlo_rows.iloc[0]["image_id"],
+                    "label":       label,
+                    "has_pair":    True,
+                })
+            else:
+                # Single view fallback — duplicate for both inputs
+                any_row = grp.iloc[0]
+                cases.append({
+                    "patient_id":  pid,
+                    "laterality":  lat,
+                    "cc_img":      any_row["image_id"],
+                    "mlo_img":     any_row["image_id"],
+                    "label":       label,
+                    "has_pair":    False,
+                })
+    else:
+        # Dataset doesn't have view column — fall back to single-view
+        logger.warning("No 'view' column found — using single-view mode.")
+        for _, row in rsna_df.iterrows():
+            cases.append({
+                "patient_id":  row["patient_id"],
+                "laterality":  row.get("laterality", "L"),
+                "cc_img":      row["image_id"],
+                "mlo_img":     row["image_id"],
+                "label":       int(row["cancer"]),
+                "has_pair":    False,
+            })
+
+    cases_df = pd.DataFrame(cases)
+    paired   = cases_df["has_pair"].sum()
+    logger.info("Multi-view pairs built: %d total (%d with CC+MLO, %d single-view)",
+                len(cases_df), paired, len(cases_df) - paired)
+
+    train_cases, val_cases = train_test_split(
+        cases_df, test_size=0.15,
+        stratify=cases_df["label"], random_state=seed,
+    )
+    logger.info("Train cases: %d | Val cases: %d",
+                len(train_cases), len(val_cases))
+
+    # ── Load VinDr external validation ────────────────────────────────────────
+    vindr_csv = vindr_dir / "breast-level_annotations.csv"
+    vindr_df  = pd.read_csv(vindr_csv)
+    bc        = "breast_birads" if "breast_birads" in vindr_df.columns else "birads"
+    vindr_df["label"] = vindr_df[bc].map({
+        "BI-RADS 1": 0, "BI-RADS 2": 0,
+        "BI-RADS 4": 1, "BI-RADS 5": 1,
+        1: 0, 2: 0, 4: 1, 5: 1,
+    })
+    vindr_df = vindr_df.dropna(subset=["label"])
+    split_col = "split" if "split" in vindr_df.columns else None
+    if split_col:
+        vindr_ext = vindr_df[vindr_df[split_col] == "test"].reset_index(drop=True)
+    else:
+        _, vindr_ext = train_test_split(
+            vindr_df, test_size=0.2, stratify=vindr_df["label"], random_state=seed
+        )
+    logger.info("VinDr external val: %d images | cancer: %.1f%%",
+                len(vindr_ext), 100 * vindr_ext["label"].mean())
+
+    # ── Innovation 5: Progressive resizing transforms ──────────────────────────
+    IMGNET = ([0.485, 0.456, 0.406], [0.229, 0.224, 0.225])
+
+    def make_train_tf(size):
+        return transforms.Compose([
+            transforms.Resize((size, size)),
+            transforms.RandomHorizontalFlip(),
+            transforms.RandomVerticalFlip(p=0.2),
+            transforms.RandomRotation(10),
+            transforms.ColorJitter(brightness=0.15, contrast=0.15),
+            transforms.RandomAffine(0, translate=(0.05, 0.05), scale=(0.95, 1.05)),
+            transforms.ToTensor(),
+            transforms.Normalize(*IMGNET),
+        ])
+
+    def make_val_tf(size=512):
+        return transforms.Compose([
+            transforms.Resize((size, size)),
+            transforms.ToTensor(),
+            transforms.Normalize(*IMGNET),
+        ])
+
+    # Progressive resizing schedule:
+    # Phase 1 (epochs 1-5):        256×256
+    # Phase 2 first half:           384×384
+    # Phase 2 second half:          512×512
+    def get_size_for_epoch(epoch, p1_epochs, p2_epochs, is_phase2):
+        if not is_phase2:
+            return 256
+        midpoint = p2_epochs // 2
+        if epoch <= midpoint:
+            return 384
+        return 512
+
+    # ── Dataset classes ────────────────────────────────────────────────────────
+    class MultiViewDataset(Dataset):
+        def __init__(self, cases_df, img_dir, transform, size):
+            self.cases    = cases_df.reset_index(drop=True)
+            self.img_dir  = Path(img_dir)
+            self.transform = transform
+            self.size     = size
+
+        def _load(self, patient_id, image_id):
+            path = self.img_dir / "train_images" / str(patient_id) / f"{image_id}.dcm"
+            try:
+                return _dicom_to_rgb(str(path))
+            except Exception as e:
+                logger.warning("Load error %s: %s", path.name, e)
+                return Image.new("RGB", (self.size, self.size), 0)
+
+        def __len__(self):
+            return len(self.cases)
+
+        def __getitem__(self, idx):
+            row    = self.cases.iloc[idx]
+            cc_img = self._load(row["patient_id"], row["cc_img"])
+            mlo_img = self._load(row["patient_id"], row["mlo_img"])
+            label  = int(row["label"])
+            return (
+                self.transform(cc_img),
+                self.transform(mlo_img),
+                label,
+            )
+
+    class VinDrDataset(Dataset):
+        def __init__(self, df, img_dir, transform):
+            self.df        = df.reset_index(drop=True)
+            self.img_dir   = Path(img_dir)
+            self.transform = transform
+
+        def __len__(self):
+            return len(self.df)
+
+        def __getitem__(self, idx):
+            row    = self.df.iloc[idx]
+            study  = str(row.get("study_id", ""))
+            img_id = str(row.get("image_id", ""))
+            label  = int(row["label"])
+            for ext in [".dicom", ".dcm"]:
+                path = self.img_dir / "images" / study / f"{img_id}{ext}"
+                if path.exists():
+                    break
+            try:
+                img = _dicom_to_rgb(str(path))
+            except Exception:
+                img = Image.new("RGB", (512, 512), 0)
+            return self.transform(img), label
+
+    val_tf_512 = make_val_tf(512)
+
+    # ── Class weight and Focal Loss ────────────────────────────────────────────
+    n_pos      = int(train_cases["label"].sum())
+    n_neg      = len(train_cases) - n_pos
+    pos_weight = torch.tensor([n_neg / max(n_pos, 1)], device=device)
+    logger.info("Class weight: %.1f (cancer: %.1f%%)",
+                pos_weight.item(), 100 * n_pos / len(train_cases))
+
+    # ── Inline model definitions (no file mounting needed) ──────────────────
+    import torch.nn as nn
+    import torch.nn.functional as F
+    from torchvision import models
+    from torchvision.models import EfficientNet_B4_Weights
+
+    class FocalLoss(nn.Module):
+        def __init__(self, alpha=0.25, gamma=2.0, pos_weight=None, label_smoothing=0.1):
+            super().__init__()
+            self.alpha = alpha; self.gamma = gamma
+            self.pos_weight = pos_weight; self.label_smoothing = label_smoothing
+        def forward(self, logits, targets):
+            ce = F.cross_entropy(logits, targets, weight=self.pos_weight,
+                                 label_smoothing=self.label_smoothing, reduction="none")
+            pt = torch.exp(-ce)
+            return (self.alpha * (1 - pt) ** self.gamma * ce).mean()
+
+    class ViewAttentionFusion(nn.Module):
+        def __init__(self, dim=1792):
+            super().__init__()
+            self.gate = nn.Sequential(
+                nn.Linear(dim*2, dim//4), nn.ReLU(inplace=True),
+                nn.Dropout(0.2), nn.Linear(dim//4, 2))
+            self.residual_w = nn.Parameter(torch.tensor(0.5))
+        def forward(self, cc, mlo):
+            w = torch.softmax(self.gate(torch.cat([cc, mlo], -1)), -1)
+            att = w[:,0:1]*cc + w[:,1:2]*mlo
+            s   = torch.sigmoid(self.residual_w)
+            return s*att + (1-s)*0.5*(cc+mlo)
+
+    class MultiViewMammogramClassifier(nn.Module):
+        def __init__(self, pretrained=True, freeze_backbone=False, dropout_rate=0.4):
+            super().__init__()
+            weights = EfficientNet_B4_Weights.IMAGENET1K_V1 if pretrained else None
+            bb = models.efficientnet_b4(weights=weights)
+            self.features = bb.features; self.avgpool = bb.avgpool
+            if freeze_backbone:
+                for p in self.features.parameters(): p.requires_grad = False
+            self.fusion = ViewAttentionFusion(1792)
+            self.classifier = nn.Sequential(
+                nn.BatchNorm1d(1792), nn.Dropout(dropout_rate),
+                nn.Linear(1792, 512), nn.ReLU(inplace=True),
+                nn.BatchNorm1d(512), nn.Dropout(dropout_rate*0.75),
+                nn.Linear(512, 2))
+        def encode(self, x):
+            return torch.flatten(self.avgpool(self.features(x)), 1)
+        def forward(self, cc, mlo):
+            logits = self.classifier(self.fusion(self.encode(cc), self.encode(mlo)))
+            return {"logits": logits, "probs": torch.softmax(logits, 1)}
+        def forward_single(self, x):
+            return self.forward(x, x)
+
+    # Innovation 2: Focal Loss
+    def make_criterion():
+        return FocalLoss(
+            alpha           = focal_alpha,
+            gamma           = focal_gamma,
+            pos_weight      = torch.tensor(
+                [1.0, pos_weight.item()], device=device
+            ),
+            label_smoothing = 0.1,
+        )
+
+    # ── Training epoch (AMP + multi-view) ─────────────────────────────────────
+    def run_train_epoch(model, loader, criterion, optimizer, scheduler, scaler):
+        """Innovation 3: AMP mixed precision training."""
+        model.train()
+        total_loss = tp = total = pos = 0
+        with torch.enable_grad():
+            for cc_imgs, mlo_imgs, labels in loader:
+                cc_imgs  = cc_imgs.to(device, non_blocking=True)
+                mlo_imgs = mlo_imgs.to(device, non_blocking=True)
+                labels   = labels.long().to(device, non_blocking=True)
+
+                # AMP autocast
+                with torch.autocast(device_type="cuda", dtype=torch.float16):
+                    out  = model(cc_imgs, mlo_imgs)
+                    loss = criterion(out["logits"], labels)
+
+                optimizer.zero_grad()
+                scaler.scale(loss).backward()
+                scaler.unscale_(optimizer)
+                nn.utils.clip_grad_norm_(model.parameters(), 1.0)
+                scaler.step(optimizer)
+                scaler.update()
+                scheduler.step()
+
+                preds       = out["logits"].argmax(1)
+                total      += labels.size(0)
+                total_loss += loss.item() * labels.size(0)
+                mask        = (labels == 1)
+                tp         += (preds[mask] == 1).sum().item()
+                pos        += mask.sum().item()
+
+        return total_loss / max(total, 1), tp / max(pos, 1)
+
+    def run_eval_epoch(model, loader, is_multiview=True):
+        """Eval on multi-view or single-view loader."""
+        model.eval()
+        all_probs, all_labels = [], []
+        with torch.inference_mode():
+            for batch in loader:
+                if is_multiview:
+                    cc_imgs, mlo_imgs, labels = batch
+                    cc_imgs  = cc_imgs.to(device)
+                    mlo_imgs = mlo_imgs.to(device)
+                    out = model(cc_imgs, mlo_imgs)
+                else:
+                    imgs, labels = batch
+                    imgs = imgs.to(device)
+                    out  = model.forward_single(imgs)
+                probs = out["probs"][:, 1].cpu().numpy()
+                all_probs.extend(probs.tolist())
+                all_labels.extend(labels.numpy().tolist())
+        return all_labels, all_probs
+
+    def save_checkpoint(model, optimizer, epoch, metrics, path):
+        torch.save({
+            "epoch":      epoch,
+            "state_dict": model.state_dict(),
+            "optimizer":  optimizer.state_dict(),
+            "metrics":    metrics,
+        }, path)
+
+    # ── Phase 1: Frozen backbone, 256×256 ─────────────────────────────────────
+    if not skip_phase1:
+        logger.info("\n" + "─" * 70)
+        logger.info("  PHASE 1 — Head only, 256×256 (%d epochs)", phase1_epochs)
+        logger.info("─" * 70)
+
+        model = MultiViewMammogramClassifier(
+            pretrained=True, freeze_backbone=True
+        ).to(device)
+        criterion = make_criterion()
+        optimizer = AdamW(
+            [p for p in model.parameters() if p.requires_grad],
+            lr=phase1_lr, weight_decay=1e-4,
+        )
+        scaler = torch.cuda.amp.GradScaler()
+
+        train_ds = MultiViewDataset(train_cases, rsna_dir, make_train_tf(256), 256)
+        val_ds   = MultiViewDataset(val_cases,   rsna_dir, val_tf_512, 512)
+        train_loader = DataLoader(train_ds, batch_size, True,  num_workers=num_workers, pin_memory=True)
+        val_loader   = DataLoader(val_ds,   batch_size, False, num_workers=num_workers, pin_memory=True)
+
+        scheduler = OneCycleLR(
+            optimizer, max_lr=phase1_lr * 3,
+            steps_per_epoch=len(train_loader), epochs=phase1_epochs, pct_start=0.3,
+        )
+
+        best_auc = 0.0
+        for epoch in range(1, phase1_epochs + 1):
+            t0 = time.time()
+            tr_loss, tr_sens = run_train_epoch(
+                model, train_loader, criterion, optimizer, scheduler, scaler
+            )
+            vl_labels, vl_probs = run_eval_epoch(model, val_loader)
+            vl_m = compute_metrics(vl_labels, vl_probs)
+            logger.info(
+                "P1 E%02d | 256px | loss=%.4f tr_sens=%.3f | RSNA AUC=%.4f sens=%.3f | %.0fs",
+                epoch, tr_loss, tr_sens,
+                vl_m["auc"], vl_m["sensitivity"], time.time() - t0,
+            )
+            if vl_m["auc"] > best_auc:
+                best_auc = vl_m["auc"]
+                save_checkpoint(model, optimizer, epoch, vl_m,
+                                f"{OUT_DIR}/mammogram_phase1.pth")
+                logger.info("  ✓ Phase 1 checkpoint (AUC=%.4f)", best_auc)
+        out_vol.commit()
+        logger.info("Phase 1 complete. Best AUC: %.4f", best_auc)
+
+    # ── Phase 2: Full fine-tuning, progressive resizing ───────────────────────
+    logger.info("\n" + "─" * 70)
+    logger.info("  PHASE 2 — Full fine-tuning, progressive resizing (%d epochs)",
+                phase2_epochs)
+    logger.info("  Epochs 1–%-2d : 256×256", phase2_epochs // 3)
+    logger.info("  Epochs %-2d–%-2d : 384×384",
+                phase2_epochs // 3 + 1, phase2_epochs * 2 // 3)
+    logger.info("  Epochs %-2d–%-2d : 512×512",
+                phase2_epochs * 2 // 3 + 1, phase2_epochs)
+    logger.info("─" * 70)
+
+    model = MultiViewMammogramClassifier(pretrained=False, freeze_backbone=False).to(device)
+    phase1_ckpt = f"{OUT_DIR}/mammogram_phase1.pth"
+    if Path(phase1_ckpt).exists():
+        ckpt = torch.load(phase1_ckpt, map_location=device)
+        model.load_state_dict(ckpt["state_dict"])
+        logger.info("Loaded Phase 1 checkpoint (AUC=%.4f)",
+                    ckpt["metrics"].get("auc", 0))
+
+    criterion = make_criterion()
+    optimizer = AdamW(model.parameters(), lr=phase2_lr, weight_decay=1e-4)
+    scaler    = torch.cuda.amp.GradScaler()
+
+    # Build full train/val loaders at 512 (size updated per epoch below)
+    val_ds_512   = MultiViewDataset(val_cases, rsna_dir, val_tf_512, 512)
+    vindr_ds     = VinDrDataset(vindr_ext, vindr_dir, make_val_tf(512))
+    val_loader   = DataLoader(val_ds_512, batch_size, False, num_workers=num_workers, pin_memory=True)
+    vindr_loader = DataLoader(vindr_ds,   batch_size, False, num_workers=num_workers, pin_memory=True)
+
+    # Scheduler needs total steps — compute with 512 loader
+    train_ds_512    = MultiViewDataset(train_cases, rsna_dir, make_train_tf(512), 512)
+    tmp_loader      = DataLoader(train_ds_512, batch_size, True, num_workers=num_workers)
+    steps_per_epoch = len(tmp_loader)
+    del tmp_loader, train_ds_512
+
+    scheduler = OneCycleLR(
+        optimizer, max_lr=max_lr,
+        steps_per_epoch=steps_per_epoch,
+        epochs=phase2_epochs, pct_start=0.3,
+    )
+
+    best_auc   = 0.0
+    best_epoch = 0
+    best_thr   = 0.5
+    log_rows   = []
+
+    # Milestone epochs for progressive resizing
+    size_milestones = {
+        1:                          256,
+        phase2_epochs // 3 + 1:    384,
+        phase2_epochs * 2 // 3 + 1: 512,
+    }
+    current_size  = 256
+    train_loader  = DataLoader(
+        MultiViewDataset(train_cases, rsna_dir, make_train_tf(256), 256),
+        batch_size, True, num_workers=num_workers, pin_memory=True,
+    )
+
+    for epoch in range(1, phase2_epochs + 1):
+        t0 = time.time()
+
+        # Innovation 5: Progressive resizing — rebuild loader when size changes
+        if epoch in size_milestones:
+            new_size = size_milestones[epoch]
+            if new_size != current_size:
+                current_size = new_size
+                logger.info("  → Resizing to %d×%d (epoch %d)",
+                            current_size, current_size, epoch)
+                train_loader = DataLoader(
+                    MultiViewDataset(
+                        train_cases, rsna_dir,
+                        make_train_tf(current_size), current_size
+                    ),
+                    batch_size, True,
+                    num_workers=num_workers, pin_memory=True,
+                )
+
+        tr_loss, tr_sens = run_train_epoch(
+            model, train_loader, criterion, optimizer, scheduler, scaler
+        )
+
+        # RSNA internal validation
+        rsna_labels, rsna_probs = run_eval_epoch(model, val_loader)
+        thr = youden_threshold(rsna_labels, rsna_probs)
+        rsna_m = compute_metrics(rsna_labels, rsna_probs, threshold=thr)
+
+        # VinDr external validation
+        vindr_labels, vindr_probs = run_eval_epoch(
+            model, vindr_loader, is_multiview=False
+        )
+        vindr_m = compute_metrics(vindr_labels, vindr_probs, threshold=thr)
+
+        elapsed = time.time() - t0
+
+        logger.info(
+            "E%02d/%d [%3dpx] │ loss=%.4f sens=%.3f │ "
+            "RSNA AUC=%.4f sens=%.3f spec=%.3f │ "
+            "VinDr AUC=%.4f sens=%.3f spec=%.3f │ %.0fs",
+            epoch, phase2_epochs, current_size, tr_loss, tr_sens,
+            rsna_m["auc"],  rsna_m["sensitivity"],  rsna_m["specificity"],
+            vindr_m["auc"], vindr_m["sensitivity"], vindr_m["specificity"],
+            elapsed,
+        )
+
+        log_rows.append({
+            "epoch": epoch, "size": current_size,
+            "train_loss": tr_loss, "train_sens": tr_sens,
+            "rsna_auc": rsna_m["auc"],   "rsna_sens": rsna_m["sensitivity"],
+            "rsna_spec": rsna_m["specificity"], "rsna_ppv": rsna_m["ppv"],
+            "rsna_npv": rsna_m["npv"],   "rsna_acc": rsna_m["accuracy"],
+            "vindr_auc": vindr_m["auc"], "vindr_sens": vindr_m["sensitivity"],
+            "vindr_spec": vindr_m["specificity"], "vindr_ppv": vindr_m["ppv"],
+            "vindr_npv": vindr_m["npv"], "vindr_acc": vindr_m["accuracy"],
+            "threshold": thr,
+        })
+
+        if rsna_m["auc"] > best_auc:
+            best_auc   = rsna_m["auc"]
+            best_epoch = epoch
+            best_thr   = thr
+            save_checkpoint(
+                model, optimizer, epoch,
+                {"rsna": rsna_m, "vindr": vindr_m, "threshold": thr},
+                f"{OUT_DIR}/mammogram_weights.pth",
+            )
+            logger.info(
+                "  ✓ Best checkpoint — RSNA AUC=%.4f  VinDr AUC=%.4f  [%dpx]",
+                rsna_m["auc"], vindr_m["auc"], current_size,
+            )
+        out_vol.commit()
+
+    # ── Final evaluation with bootstrap CI ────────────────────────────────────
+    logger.info("\n" + "=" * 70)
+    logger.info("  FINAL EVALUATION (epoch %d checkpoint)", best_epoch)
+    logger.info("=" * 70)
+
+    ckpt = torch.load(f"{OUT_DIR}/mammogram_weights.pth", map_location=device)
+    model.load_state_dict(ckpt["state_dict"])
+    model.eval()
+
+    rsna_l,  rsna_p  = run_eval_epoch(model, val_loader)
+    vindr_l, vindr_p = run_eval_epoch(model, vindr_loader, is_multiview=False)
+
+    rsna_f  = compute_metrics(rsna_l,  rsna_p,  best_thr)
+    vindr_f = compute_metrics(vindr_l, vindr_p, best_thr)
+    rsna_ci  = bootstrap_auc_ci(rsna_l,  rsna_p)
+    vindr_ci = bootstrap_auc_ci(vindr_l, vindr_p)
+
+    gap = rsna_f["auc"] - vindr_f["auc"]
+
+    logger.info("\n  RSNA 2022 (Internal validation — USA)")
+    logger.info("  AUC:         %.4f  (95%% CI: %.4f–%.4f)", rsna_f["auc"], *rsna_ci)
+    logger.info("  Sensitivity: %.1f%%", rsna_f["sensitivity"] * 100)
+    logger.info("  Specificity: %.1f%%", rsna_f["specificity"] * 100)
+    logger.info("  PPV: %.4f  NPV: %.4f", rsna_f["ppv"], rsna_f["npv"])
+
+    logger.info("\n  VinDr-Mammo (External validation — Vietnam) ← key publication metric")
+    logger.info("  AUC:         %.4f  (95%% CI: %.4f–%.4f)", vindr_f["auc"], *vindr_ci)
+    logger.info("  Sensitivity: %.1f%%", vindr_f["sensitivity"] * 100)
+    logger.info("  Specificity: %.1f%%", vindr_f["specificity"] * 100)
+    logger.info("  PPV: %.4f  NPV: %.4f", vindr_f["ppv"], vindr_f["npv"])
+
+    logger.info("\n  Generalisation gap: %.4f  (%s)",
+                gap,
+                "✓ Excellent (<0.05)" if gap < 0.05 else
+                "⚠ Moderate (0.05–0.10)" if gap < 0.10 else
+                "✗ Large — consider domain adaptation")
+
+    results = {
+        "best_epoch":    best_epoch,
+        "threshold":     best_thr,
+        "innovations":   [
+            "Multi-view patient fusion (Siamese EfficientNet-B4 + ViewAttentionFusion)",
+            f"Focal Loss (α={focal_alpha}, γ={focal_gamma})",
+            "Mixed Precision Training (AMP GradScaler)",
+            "Test-Time Augmentation (8 augments, in mammogram_inference.py)",
+            "Progressive Resizing (256→384→512)",
+        ],
+        "rsna_internal": {
+            **rsna_f, "auc_ci": rsna_ci,
+        },
+        "vindr_external": {
+            **vindr_f, "auc_ci": vindr_ci,
+        },
+        "generalisation_gap": round(gap, 4),
+    }
+
+    with open(f"{OUT_DIR}/mammogram_training_log.csv", "w", newline="") as f:
+        w = csv.DictWriter(f, fieldnames=log_rows[0].keys())
+        w.writeheader(); w.writerows(log_rows)
+
+    with open(f"{OUT_DIR}/mammogram_results.json", "w") as f:
+        json.dump(results, f, indent=2)
+
+    out_vol.commit()
+    logger.info("\n  Saved: mammogram_weights.pth, training_log.csv, results.json")
+    logger.info("=" * 70)
+    return results
+
+
+# ── Local entrypoint ───────────────────────────────────────────────────────────
+@app.local_entrypoint()
+def main(
+    phase1_epochs: int   = 5,
+    phase2_epochs: int   = 15,
+    batch_size:    int   = 8,
+    phase2_lr:     float = 5e-5,
+    max_lr:        float = 1e-3,
+    focal_alpha:   float = 0.25,
+    focal_gamma:   float = 2.0,
+    skip_phase1:   bool  = False,
+    debug:         bool  = False,
+):
+    print("=" * 70)
+    print("  MedAI — Research-Grade Mammogram Training")
+    print("  5 Innovations:")
+    print("    1. Multi-view patient fusion (Siamese + Attention)")
+    print(f"   2. Focal Loss (α={focal_alpha}, γ={focal_gamma})")
+    print("    3. Mixed Precision AMP")
+    print("    4. Test-Time Augmentation (at inference)")
+    print("    5. Progressive Resizing (256→384→512)")
+    print(f"  Train:  RSNA 2022  |  External val: VinDr-Mammo")
+    print(f"  Debug:  {debug}")
+    print("=" * 70)
+
+    results = train.remote(
+        phase1_epochs=phase1_epochs, phase2_epochs=phase2_epochs,
+        batch_size=batch_size, phase2_lr=phase2_lr, max_lr=max_lr,
+        focal_alpha=focal_alpha, focal_gamma=focal_gamma,
+        skip_phase1=skip_phase1, debug=debug,
+    )
+
+    print("=" * 70)
+    print("  Job running independently on Modal GPU.")
+    print("  Your terminal and Mac can now be closed.")
+    print()
+    print("  Check progress:")
+    print("  modal app logs " + str(call.object_id) if hasattr(call, "object_id") else "  modal.com/apps/relixsx/main")
+    print()
+    print("  When done, download weights:")
+    print("  modal volume get mammogram-outputs mammogram_weights.pth model/mammogram_weights.pth")
+    print("  modal volume get mammogram-outputs mammogram_results.json mammogram_results.json")
+    print("=" * 70)

model/__init__.py

@@ -0,0 +1,4 @@
+from .inference import BreastCancerInferencePipeline
+from .model import BreastCancerClassifier
+
+__all__ = ["BreastCancerInferencePipeline", "BreastCancerClassifier"]

model/inference.py

@@ -0,0 +1,197 @@
+"""
+model/inference.py
+──────────────────
+End-to-end inference pipeline.
+
+Usage
+─────
+    from model import BreastCancerInferencePipeline
+
+    pipeline = BreastCancerInferencePipeline(weights_path="model/weights.pth")
+    result   = pipeline.predict("slide_001.png")
+
+    # result → {
+    #   "prediction" : "malignant",
+    #   "confidence" : 0.9341,
+    #   "logits"     : tensor([[-2.14, 3.87]])
+    # }
+
+Output contract (per spec)
+──────────────────────────
+    {
+        "prediction" : str           — "benign" | "malignant"
+        "confidence" : float         — probability of the predicted class [0, 1]
+        "logits"     : torch.Tensor  — raw model outputs (1, 2), pre-softmax
+    }
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Optional, Union
+
+import numpy as np
+import torch
+from PIL import Image
+
+from .model import BreastCancerClassifier
+from utils.preprocessing import ImagePreprocessor   # utils/ is a sibling package
+
+logger = logging.getLogger(__name__)
+
+# Class index → label mapping
+LABEL_MAP: dict[int, str] = {0: "benign", 1: "malignant"}
+
+
+class BreastCancerInferencePipeline:
+    """
+    Self-contained inference pipeline for breast cancer classification.
+
+    Parameters
+    ----------
+    weights_path : str | Path | None
+        Path to a saved state_dict (.pt / .pth). Conventionally stored at
+        model/weights.pth. If None, runs with ImageNet-pretrained backbone
+        weights only (useful for integration testing before fine-tuning).
+    device : str | None
+        "cuda", "mps", or "cpu". Auto-detected when None.
+    confidence_threshold : float
+        Minimum confidence to return the predicted label; below this,
+        the output still returns the argmax class but logs a low-confidence
+        warning. Default: 0.5.
+    """
+
+    def __init__(
+        self,
+        weights_path: Optional[Union[str, Path]] = None,
+        device: Optional[str] = None,
+        confidence_threshold: float = 0.5,
+    ) -> None:
+        self.device = self._resolve_device(device)
+        self.confidence_threshold = confidence_threshold
+        self.preprocessor = ImagePreprocessor()
+
+        # ── Build and load model ─────────────────────────────────────────────
+        self.model = BreastCancerClassifier(pretrained=(weights_path is None))
+        if weights_path is not None:
+            self._load_weights(weights_path)
+
+        self.model.eval()
+        self.model.to(self.device)
+        logger.info("Pipeline ready on device: %s", self.device)
+
+    # ────────────────────────────────────────────────────────────────────────
+    def predict(
+        self,
+        image: Union[str, Path, "Image.Image", np.ndarray, torch.Tensor],
+    ) -> dict:
+        """
+        Run end-to-end inference on a single histopathology image.
+
+        Parameters
+        ----------
+        image : str | Path | PIL.Image | np.ndarray | torch.Tensor
+            Raw image in any supported format (see utils/preprocessing.py).
+
+        Returns
+        -------
+        dict
+            {
+                "prediction" : str          — "benign" or "malignant"
+                "confidence" : float        — predicted-class probability [0, 1]
+                "logits"     : Tensor[1,2]  — raw pre-softmax scores
+            }
+        """
+        tensor = self._preprocess(image)
+
+        with torch.inference_mode():
+            output = self.model(tensor)
+
+        return self._format_output(output["logits"], output["probs"])
+
+    # ────────────────────────────────────────────────────────────────────────
+    def predict_batch(self, images: list) -> list[dict]:
+        """
+        Run inference on a batch of images.
+
+        Parameters
+        ----------
+        images : list of any supported image type
+
+        Returns
+        -------
+        list of prediction dicts (same schema as predict())
+        """
+        tensors = torch.cat([self._preprocess(img) for img in images], dim=0)
+        tensors = tensors.to(self.device)
+
+        with torch.inference_mode():
+            output = self.model(tensors)
+
+        results = []
+        for i in range(tensors.size(0)):
+            logit_i = output["logits"][i].unsqueeze(0)   # (1, 2)
+            prob_i  = output["probs"][i].unsqueeze(0)    # (1, 2)
+            results.append(self._format_output(logit_i, prob_i))
+        return results
+
+    # ── Internal helpers ─────────────────────────────────────────────────────
+    def _preprocess(self, image) -> torch.Tensor:
+        """Preprocess to (1, 3, 224, 224) on the correct device."""
+        tensor = self.preprocessor(image)   # (1, 3, 224, 224) CPU
+        return tensor.to(self.device)
+
+    def _format_output(
+        self,
+        logits: torch.Tensor,
+        probs: torch.Tensor,
+    ) -> dict:
+        """
+        Convert raw model tensors into the specced output dictionary.
+
+        Output contract
+        ───────────────
+            "prediction" : str   — "benign" | "malignant"
+            "confidence" : float — probability of the predicted class
+            "logits"     : Tensor[1, 2]
+        """
+        predicted_idx = int(torch.argmax(probs, dim=1).item())
+        confidence    = float(probs[0, predicted_idx].item())
+        prediction    = LABEL_MAP[predicted_idx]
+
+        if confidence < self.confidence_threshold:
+            logger.warning(
+                "Low-confidence prediction: %s (%.3f). "
+                "Treat result with caution.",
+                prediction, confidence,
+            )
+
+        return {
+            "prediction": prediction,
+            "confidence": round(confidence, 6),
+            "logits":     logits.detach().cpu(),    # (1, 2), kept for Grad-CAM
+        }
+
+    def _load_weights(self, path: Union[str, Path]) -> None:
+        """Load fine-tuned weights from a state_dict checkpoint."""
+        path = Path(path)
+        if not path.exists():
+            raise FileNotFoundError(f"Weights file not found: {path}")
+
+        checkpoint = torch.load(path, map_location=self.device)
+
+        # Support both raw state_dict and {'state_dict': ...} wrappers
+        state_dict = checkpoint.get("state_dict", checkpoint)
+        self.model.load_state_dict(state_dict, strict=True)
+        logger.info("Loaded weights from: %s", path)
+
+    @staticmethod
+    def _resolve_device(device: Optional[str]) -> torch.device:
+        if device is not None:
+            return torch.device(device)
+        if torch.cuda.is_available():
+            return torch.device("cuda")
+        if torch.backends.mps.is_available():
+            return torch.device("mps")
+        return torch.device("cpu")

model/mammogram_ensemble.py

@@ -0,0 +1,234 @@
+"""
+model/mammogram_ensemble.py
+────────────────────────────
+Ensemble inference for the 3 EfficientNet-B4 mammogram models trained
+on vast.ai (seeds 42, 123, 999).
+
+IMPORTANT — architecture match
+───────────────────────────────
+These weights were trained with the SIMPLE single-view architecture
+(feat / pool / head), NOT the multi-view fusion model. This file
+defines the exact matching architecture so the checkpoints load with
+strict=True. Do not use MultiViewMammogramClassifier with these weights.
+
+Ensemble result (RSNA internal validation):
+  Model seed=42:   AUC 0.7989
+  Model seed=123:  AUC 0.8254
+  Model seed=999:  AUC 0.8083
+  ──────────────────────────────
+  Ensemble image AUC:    0.8436
+  Ensemble patient AUC:  0.8443   ← headline number
+  Sensitivity: 70.1%   Specificity: 82.4%
+
+Usage
+─────
+  from model.mammogram_ensemble import MammogramEnsemble
+  from PIL import Image
+
+  ens = MammogramEnsemble(
+      weight_paths=[
+          "model/model_s42.pth",
+          "model/model_s123.pth",
+          "model/model_s999.pth",
+      ],
+  )
+
+  img    = Image.open("mammogram.png")
+  result = ens.predict(img)            # averaged across 3 models
+  result = ens.predict_tta(img)        # + test-time augmentation
+
+  print(result)
+  # { prediction, confidence, per_model, birads, modality }
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import List, Optional, Union
+
+import torch
+import torch.nn as nn
+from PIL import Image
+from torchvision import models, transforms
+from torchvision.models import EfficientNet_B4_Weights
+
+logger = logging.getLogger(__name__)
+
+MEAN = [0.485, 0.456, 0.406]
+STD  = [0.229, 0.224, 0.225]
+TRAIN_SIZE = 384   # the models were trained at 384×384
+
+
+# ── Architecture (must exactly match the vast.ai training script) ──────────────
+class _Model(nn.Module):
+    """EfficientNet-B4 single-view classifier — matches trained checkpoints."""
+
+    def __init__(self, pretrained: bool = False) -> None:
+        super().__init__()
+        w = EfficientNet_B4_Weights.IMAGENET1K_V1 if pretrained else None
+        bb = models.efficientnet_b4(weights=w)
+        self.feat = bb.features
+        self.pool = bb.avgpool
+        self.head = nn.Sequential(
+            nn.BatchNorm1d(1792), nn.Dropout(0.4),
+            nn.Linear(1792, 512), nn.ReLU(),
+            nn.BatchNorm1d(512), nn.Dropout(0.3),
+            nn.Linear(512, 2),
+        )
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return self.head(torch.flatten(self.pool(self.feat(x)), 1))
+
+
+def _build_val_transform(size: int = TRAIN_SIZE):
+    return transforms.Compose([
+        transforms.Resize((size, size)),
+        transforms.ToTensor(),
+        transforms.Normalize(MEAN, STD),
+    ])
+
+
+def _build_tta_transforms(size: int = TRAIN_SIZE) -> List[transforms.Compose]:
+    base = [transforms.Resize((size, size)),
+            transforms.ToTensor(),
+            transforms.Normalize(MEAN, STD)]
+    return [
+        transforms.Compose(base),
+        transforms.Compose([transforms.RandomHorizontalFlip(p=1.0)] + base),
+        transforms.Compose([transforms.RandomVerticalFlip(p=1.0)]   + base),
+        transforms.Compose([transforms.RandomRotation((10, 10))]    + base),
+    ]
+
+
+class MammogramEnsemble:
+    """
+    Averaging ensemble of the 3 trained EfficientNet-B4 mammogram models.
+
+    Parameters
+    ----------
+    weight_paths : list of paths to the 3 .pth checkpoints.
+    device       : "cuda" | "mps" | "cpu". Auto-detected if None.
+    threshold    : decision threshold for malignant. Default 0.5
+                   (override with the ensemble threshold from results.json).
+    """
+
+    BIRADS_MAP = [
+        (0.90, "BI-RADS 5 — Highly suggestive of malignancy"),
+        (0.75, "BI-RADS 4C — High suspicion"),
+        (0.55, "BI-RADS 4B — Moderate suspicion"),
+        (0.40, "BI-RADS 4A — Low suspicion"),
+    ]
+
+    def __init__(
+        self,
+        weight_paths: List[Union[str, Path]],
+        device:       Optional[str] = None,
+        threshold:    float         = 0.5,
+    ) -> None:
+        self.device         = self._resolve_device(device)
+        self.threshold      = threshold
+        self.transform      = _build_val_transform()
+        self.tta_transforms = _build_tta_transforms()
+        self.models: List[_Model] = []
+        self.member_aucs: List[float] = []
+
+        for path in weight_paths:
+            path = Path(path)
+            if not path.exists():
+                logger.warning("Ensemble member not found: %s — skipping", path)
+                continue
+            m = _Model(pretrained=False).to(self.device)
+            ckpt  = torch.load(path, map_location=self.device, weights_only=False)
+            state = ckpt.get("state_dict", ckpt)
+            m.load_state_dict(state, strict=True)
+            m.eval()
+            self.models.append(m)
+            auc = ckpt.get("metrics", {}).get("auc", 0.0)
+            self.member_aucs.append(float(auc) if isinstance(auc, (int, float)) else 0.0)
+            logger.info("Loaded %s (AUC=%s)", path.name, auc)
+
+        if not self.models:
+            raise RuntimeError("No ensemble members loaded — check weight paths.")
+
+        # Best-performing member, used for single-model tasks like Grad-CAM
+        # (saliency maps are inherently per-model; the strongest member is
+        # the most representative choice).
+        best_idx       = int(max(range(len(self.models)),
+                                 key=lambda i: self.member_aucs[i]))
+        self.cam_model = self.models[best_idx]
+
+        logger.info("Ensemble ready: %d models on %s (CAM model: member %d)",
+                    len(self.models), self.device, best_idx)
+
+    # ── Public API ────────────────────────────────────────────────────────────
+    def predict(self, image: Image.Image) -> dict:
+        """Average P(cancer) across all models for a single image."""
+        tensor    = self.transform(image).unsqueeze(0).to(self.device)
+        per_model = []
+        with torch.inference_mode():
+            for m in self.models:
+                p = torch.softmax(m(tensor), dim=1)[0, 1].item()
+                per_model.append(round(p, 6))
+        return self._build_result(per_model)
+
+    def predict_tta(self, image: Image.Image) -> dict:
+        """Average across all models AND all TTA augmentations."""
+        per_model = []
+        with torch.inference_mode():
+            for m in self.models:
+                probs = []
+                for tf in self.tta_transforms:
+                    t = tf(image).unsqueeze(0).to(self.device)
+                    probs.append(torch.softmax(m(t), dim=1)[0, 1].item())
+                per_model.append(round(sum(probs) / len(probs), 6))
+        out = self._build_result(per_model)
+        out["modality"] = "mammogram_ensemble_tta"
+        return out
+
+    # ── Helpers ─────────────────────────────────────────────────────────────
+    def _build_result(self, per_model: List[float]) -> dict:
+        mal_conf   = sum(per_model) / len(per_model)
+        prediction = "malignant" if mal_conf >= self.threshold else "benign"
+        confidence = mal_conf if prediction == "malignant" else (1 - mal_conf)
+        return {
+            "prediction": prediction,
+            "confidence": round(confidence, 6),
+            "malignant_probability": round(mal_conf, 6),
+            "per_model": per_model,
+            "birads":    self._get_birads(prediction, mal_conf),
+            "modality":  "mammogram_ensemble",
+            "n_models":  len(per_model),
+        }
+
+    def _get_birads(self, prediction: str, mal_prob: float) -> str:
+        if prediction == "benign":
+            return ("BI-RADS 3 — Probably benign — short-interval follow-up"
+                    if mal_prob >= 0.30 else "BI-RADS 2 — Benign finding")
+        for thr, label in self.BIRADS_MAP:
+            if mal_prob >= thr:
+                return label
+        return "BI-RADS 4A — Low suspicion"
+
+    @staticmethod
+    def _resolve_device(device: Optional[str]) -> torch.device:
+        if device is not None:
+            return torch.device(device)
+        if torch.cuda.is_available():
+            return torch.device("cuda")
+        if torch.backends.mps.is_available():
+            return torch.device("mps")
+        return torch.device("cpu")
+
+
+# ── Quick self-test ────────────────────────────────────────────────────────────
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.INFO)
+    ens = MammogramEnsemble([
+        "model/model_s42.pth",
+        "model/model_s123.pth",
+        "model/model_s999.pth",
+    ])
+    # Random tensor sanity check — confirms all 3 load and run
+    dummy = Image.new("RGB", (512, 512), 128)
+    print(ens.predict(dummy))

model/mammogram_inference.py

@@ -0,0 +1,315 @@
+"""
+model/mammogram_inference.py
+─────────────────────────────
+Inference pipeline for the multi-view EfficientNet-B4 mammogram classifier.
+
+Innovation 4 — Test-Time Augmentation (TTA)
+─────────────────────────────────────────────
+At inference time, each image is passed through the model 8 times with
+different augmentations (flips and 90° rotations). The predicted
+probabilities are averaged across all 8 runs.
+
+Why TTA works:
+  The model never sees perfectly symmetrical versions of the same image
+  during training due to stochastic augmentation. At test time, presenting
+  multiple augmented versions and averaging "fills in" these unseen views,
+  effectively acting as a free ensemble of 8 models.
+
+  Expected improvement: +0.5–2% AUC with zero training cost.
+
+Usage
+─────
+  from model.mammogram_inference import MammogramInferencePipeline
+  from PIL import Image
+
+  pipeline = MammogramInferencePipeline("model/mammogram_weights.pth")
+
+  # Standard prediction
+  img    = Image.open("mammogram.png")
+  result = pipeline.predict(img)
+
+  # TTA prediction (slower but more accurate)
+  result = pipeline.predict_tta(img, n_augments=8)
+
+  # Multi-view prediction (CC + MLO)
+  cc_img  = Image.open("cc.dcm")
+  mlo_img = Image.open("mlo.dcm")
+  result  = pipeline.predict_multiview(cc_img, mlo_img)
+
+  print(result)
+  # { prediction, confidence, logits, birads, modality }
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import List, Optional, Union
+
+import torch
+import torch.nn.functional as F
+from PIL import Image
+from torchvision import transforms
+
+from model.mammogram_model import MultiViewMammogramClassifier
+from utils.mammogram_preprocessing import (
+    build_mammogram_inference_transform,
+    load_mammogram,
+)
+
+logger = logging.getLogger(__name__)
+
+# ── TTA augmentation set ──────────────────────────────────────────────────────
+# 8 geometric transforms covering all flip/rotation combinations.
+# No colour jitter — we want consistent intensity across augmentations.
+def _build_tta_transforms(size: int = 512) -> List[transforms.Compose]:
+    """Return list of 8 TTA transforms (identity + 7 augmentations)."""
+    base = [
+        transforms.Resize((size, size)),
+        transforms.ToTensor(),
+        transforms.Normalize([0.485, 0.456, 0.406], [0.229, 0.224, 0.225]),
+    ]
+    return [
+        transforms.Compose(base),                                           # 1 original
+        transforms.Compose([transforms.RandomHorizontalFlip(p=1.0)] + base),  # 2 hflip
+        transforms.Compose([transforms.RandomVerticalFlip(p=1.0)]   + base),  # 3 vflip
+        transforms.Compose([transforms.RandomRotation((90, 90))]    + base),  # 4 rot90
+        transforms.Compose([transforms.RandomRotation((180, 180))]  + base),  # 5 rot180
+        transforms.Compose([transforms.RandomRotation((270, 270))]  + base),  # 6 rot270
+        transforms.Compose([                                                    # 7 hflip+rot90
+            transforms.RandomHorizontalFlip(p=1.0),
+            transforms.RandomRotation((90, 90)),
+        ] + base),
+        transforms.Compose([                                                    # 8 vflip+rot90
+            transforms.RandomVerticalFlip(p=1.0),
+            transforms.RandomRotation((90, 90)),
+        ] + base),
+    ]
+
+
+class MammogramInferencePipeline:
+    """
+    Multi-view EfficientNet-B4 inference pipeline with TTA support.
+
+    Parameters
+    ----------
+    weights_path : str | Path | None
+        Path to trained weights (.pth).
+    device : str | None
+        "cuda", "mps", or "cpu". Auto-detected if None.
+    confidence_threshold : float
+        Minimum probability to classify as malignant. Default 0.5.
+    use_tta : bool
+        Enable Test-Time Augmentation by default. Default False
+        (use predict_tta() explicitly for TTA).
+    """
+
+    BIRADS_MAP = [
+        (0.95, "BI-RADS 5 — Highly suggestive of malignancy"),
+        (0.85, "BI-RADS 4C — High suspicion"),
+        (0.75, "BI-RADS 4B — Moderate suspicion"),
+        (0.60, "BI-RADS 4A — Low suspicion"),
+        (0.50, "BI-RADS 3 — Probably benign — short follow-up"),
+        (0.00, "BI-RADS 2 — Benign finding"),
+    ]
+
+    def __init__(
+        self,
+        weights_path:         Optional[Union[str, Path]] = None,
+        device:               Optional[str]              = None,
+        confidence_threshold: float                      = 0.5,
+    ) -> None:
+        self.device    = self._resolve_device(device)
+        self.threshold = confidence_threshold
+        self.transform = build_mammogram_inference_transform()
+        self.tta_transforms = _build_tta_transforms()
+
+        # Build multi-view model
+        self.model = MultiViewMammogramClassifier(
+            pretrained = weights_path is None,
+        ).to(self.device)
+
+        if weights_path is not None:
+            weights_path = Path(weights_path)
+            if not weights_path.exists():
+                logger.warning(
+                    "Mammogram weights not found at '%s'. "
+                    "Using ImageNet init — predictions not clinically valid.",
+                    weights_path,
+                )
+            else:
+                checkpoint = torch.load(
+                    weights_path,
+                    map_location = self.device,
+                    weights_only = True,
+                )
+                state = checkpoint.get("state_dict", checkpoint)
+                self.model.load_state_dict(state, strict=True)
+                logger.info(
+                    "Mammogram pipeline ready on %s (weights: %s)",
+                    self.device, weights_path.name,
+                )
+        else:
+            logger.info(
+                "Mammogram pipeline ready on %s (ImageNet init)",
+                self.device,
+            )
+
+        self.model.eval()
+
+    # ── Public API ────────────────────────────────────────────────────────────
+
+    def predict(self, image: Image.Image) -> dict:
+        """
+        Standard single-image prediction (no TTA).
+
+        The image is used for both CC and MLO inputs — the model
+        makes the best prediction it can from a single view.
+        """
+        tensor = self.transform(image).unsqueeze(0).to(self.device)
+        with torch.inference_mode():
+            out = self.model.forward_single(tensor)
+        return self._build_result(out)
+
+    def predict_tta(
+        self,
+        image:       Image.Image,
+        n_augments:  int = 8,
+    ) -> dict:
+        """
+        Innovation 4 — Test-Time Augmentation prediction.
+
+        Runs the image through n_augments different augmentations,
+        averages the softmax probabilities, and returns the ensemble result.
+
+        Parameters
+        ----------
+        image      : PIL image
+        n_augments : number of TTA augmentations (max 8). Default 8.
+
+        Returns
+        -------
+        Same dict schema as predict(), with modality="mammogram_tta".
+        """
+        n_augments = min(n_augments, len(self.tta_transforms))
+        all_probs  = []
+
+        with torch.inference_mode():
+            for tf in self.tta_transforms[:n_augments]:
+                tensor = tf(image).unsqueeze(0).to(self.device)
+                out    = self.model.forward_single(tensor)
+                all_probs.append(out["probs"])
+
+        # Average probabilities across all augmentations
+        avg_probs  = torch.stack(all_probs).mean(0)
+        mal_conf   = float(avg_probs[0, 1])
+        prediction = "malignant" if mal_conf >= self.threshold else "benign"
+        confidence = mal_conf if prediction == "malignant" else float(avg_probs[0, 0])
+
+        # Reconstruct result dict
+        fake_logits = torch.log(avg_probs + 1e-8)
+        return {
+            "prediction": prediction,
+            "confidence": round(confidence, 6),
+            "logits":     fake_logits,
+            "birads":     self._get_birads(prediction, mal_conf),
+            "modality":   "mammogram_tta",
+            "n_augments": n_augments,
+        }
+
+    def predict_multiview(
+        self,
+        cc_image:  Image.Image,
+        mlo_image: Image.Image,
+    ) -> dict:
+        """
+        Full multi-view prediction using CC and MLO views.
+
+        Parameters
+        ----------
+        cc_image  : craniocaudal view PIL image
+        mlo_image : mediolateral oblique view PIL image
+        """
+        cc_tensor  = self.transform(cc_image).unsqueeze(0).to(self.device)
+        mlo_tensor = self.transform(mlo_image).unsqueeze(0).to(self.device)
+
+        with torch.inference_mode():
+            out = self.model(cc_tensor, mlo_tensor)
+
+        result = self._build_result(out)
+        result["modality"] = "mammogram_multiview"
+        return result
+
+    def predict_multiview_tta(
+        self,
+        cc_image:  Image.Image,
+        mlo_image: Image.Image,
+        n_augments: int = 8,
+    ) -> dict:
+        """Multi-view prediction with TTA — highest accuracy, slowest."""
+        n_augments = min(n_augments, len(self.tta_transforms))
+        all_probs  = []
+
+        with torch.inference_mode():
+            for tf in self.tta_transforms[:n_augments]:
+                cc_t  = tf(cc_image).unsqueeze(0).to(self.device)
+                mlo_t = tf(mlo_image).unsqueeze(0).to(self.device)
+                out   = self.model(cc_t, mlo_t)
+                all_probs.append(out["probs"])
+
+        avg_probs  = torch.stack(all_probs).mean(0)
+        mal_conf   = float(avg_probs[0, 1])
+        prediction = "malignant" if mal_conf >= self.threshold else "benign"
+        confidence = mal_conf if prediction == "malignant" else float(avg_probs[0, 0])
+        fake_logits = torch.log(avg_probs + 1e-8)
+
+        return {
+            "prediction": prediction,
+            "confidence": round(confidence, 6),
+            "logits":     fake_logits,
+            "birads":     self._get_birads(prediction, mal_conf),
+            "modality":   "mammogram_multiview_tta",
+            "n_augments": n_augments,
+        }
+
+    def predict_dicom(self, path: Union[str, Path]) -> dict:
+        """Load a DICOM file and run standard prediction."""
+        image = load_mammogram(path)
+        return self.predict(image)
+
+    def predict_dicom_tta(self, path: Union[str, Path]) -> dict:
+        """Load a DICOM file and run TTA prediction."""
+        image = load_mammogram(path)
+        return self.predict_tta(image)
+
+    def _get_birads(self, prediction: str, mal_prob: float) -> str:
+        if prediction == "benign":
+            return ("BI-RADS 3 — Probably benign — short-interval follow-up"
+                    if mal_prob >= 0.35 else "BI-RADS 2 — Benign finding")
+        for threshold, label in self.BIRADS_MAP:
+            if mal_prob >= threshold:
+                return label
+        return "BI-RADS 2 — Benign finding"
+
+    def _build_result(self, out: dict) -> dict:
+        probs      = out["probs"].squeeze()
+        mal_conf   = float(probs[1])
+        prediction = "malignant" if mal_conf >= self.threshold else "benign"
+        confidence = mal_conf if prediction == "malignant" else float(probs[0])
+        return {
+            "prediction": prediction,
+            "confidence": round(confidence, 6),
+            "logits":     out["logits"],
+            "birads":     self._get_birads(prediction, mal_conf),
+            "modality":   "mammogram",
+        }
+
+    @staticmethod
+    def _resolve_device(device: Optional[str]) -> torch.device:
+        if device is not None:
+            return torch.device(device)
+        if torch.cuda.is_available():
+            return torch.device("cuda")
+        if torch.backends.mps.is_available():
+            return torch.device("mps")
+        return torch.device("cpu")

model/mammogram_model.py

@@ -0,0 +1,293 @@
+"""
+model/mammogram_model.py
+─────────────────────────
+EfficientNet-B4 mammogram classifier with five training innovations:
+
+1. Multi-View Patient Fusion
+   ── Siamese EfficientNet-B4 processes CC and MLO views with shared weights.
+   ── ViewAttentionFusion layer learns which view to trust more per case.
+   ── Patient-level prediction combines both breast views.
+   ── Clinical motivation: radiologists always read CC+MLO together.
+
+2. Focal Loss
+   ── Addresses severe class imbalance (1.5% cancer rate in RSNA).
+   ── FL(pt) = -α(1-pt)^γ · log(pt) — focuses on hard examples.
+   ── Prevents the model from collapsing to "predict everything benign".
+
+3. Mixed Precision Training (AMP)
+   ── torch.cuda.amp.autocast — 2× faster, 40% less VRAM.
+   ── Enables larger batch sizes on A10G.
+   ── Used in training loop in modal_mammogram.py.
+
+4. Test-Time Augmentation (TTA)
+   ── Implemented in mammogram_inference.py.
+   ── 8 augmented predictions averaged at inference.
+
+5. Progressive Resizing
+   ── Implemented in modal_mammogram.py.
+   ── 256→384→512 curriculum during Phase 2 training.
+"""
+
+from __future__ import annotations
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from torchvision import models
+from torchvision.models import EfficientNet_B4_Weights
+
+
+# ╔══════════════════════════════════════════════════════════════════════════════╗
+# ║  INNOVATION 1 — VIEW ATTENTION FUSION                                       ║
+# ╚══════════════════════════════════════════════════════════════════════════════╝
+
+class ViewAttentionFusion(nn.Module):
+    """
+    Soft-attention fusion of CC and MLO mammogram view features.
+
+    Rather than naively averaging CC and MLO predictions, this module
+    learns a per-sample attention weight — how much to trust each view.
+
+    In benign cases the CC view often dominates.
+    In malignant cases the view with the visible lesion drives the prediction.
+    The attention mechanism learns this distinction from data.
+
+    Architecture
+    ────────────
+      Input:  cc_feat  (B, D)  — EfficientNet features from CC view
+              mlo_feat (B, D)  — EfficientNet features from MLO view
+
+      Gate:   [cc_feat | mlo_feat] → Linear(2D, 2) → Softmax → (α_cc, α_mlo)
+
+      Fusion: fused = α_cc · cc_feat + α_mlo · mlo_feat
+
+      Residual gating adds a skip connection so the fusion can fall back
+      to simple averaging if attention provides no benefit.
+
+    Parameters
+    ----------
+    dim : int
+        Feature dimension (1792 for EfficientNet-B4).
+    dropout : float
+        Dropout on the gate network. Default 0.2.
+    """
+
+    def __init__(self, dim: int = 1792, dropout: float = 0.2) -> None:
+        super().__init__()
+        self.gate = nn.Sequential(
+            nn.Linear(dim * 2, dim // 4),
+            nn.ReLU(inplace=True),
+            nn.Dropout(dropout),
+            nn.Linear(dim // 4, 2),
+        )
+        # Learnable residual blend — starts at 0.5/0.5
+        self.residual_w = nn.Parameter(torch.tensor(0.5))
+
+    def forward(
+        self,
+        cc_feat:  torch.Tensor,   # (B, D)
+        mlo_feat: torch.Tensor,   # (B, D)
+    ) -> torch.Tensor:            # (B, D)
+        concat  = torch.cat([cc_feat, mlo_feat], dim=-1)     # (B, 2D)
+        weights = torch.softmax(self.gate(concat), dim=-1)   # (B, 2)
+        α_cc    = weights[:, 0:1]   # (B, 1)
+        α_mlo   = weights[:, 1:2]   # (B, 1)
+
+        # Attention-weighted fusion + residual simple-average
+        attended = α_cc * cc_feat + α_mlo * mlo_feat
+        simple   = 0.5 * cc_feat + 0.5 * mlo_feat
+        w        = torch.sigmoid(self.residual_w)
+        return w * attended + (1 - w) * simple
+
+
+# ╔══════════════════════════════════════════════════════════════════════════════╗
+# ║  INNOVATION 2 — FOCAL LOSS                                                  ║
+# ╚══════════════════════════════════════════════════════════════════════════════╝
+
+class FocalLoss(nn.Module):
+    """
+    Focal Loss for extreme class imbalance (Lin et al., 2017).
+
+    RSNA 2022 has ~1.5% cancer rate. Standard cross-entropy loss with
+    pos_weight is a blunt instrument — it upweights all positive samples
+    equally. Focal Loss instead downweights easy negative examples,
+    forcing the model to focus on hard-to-classify borderline cases.
+
+    FL(pt) = -α · (1 - pt)^γ · log(pt)
+
+    Parameters
+    ----------
+    alpha : float
+        Balance parameter. 0.25 focuses on positives. Default 0.25.
+    gamma : float
+        Focusing parameter. 0 = standard CE, 2 = standard focal. Default 2.
+    pos_weight : torch.Tensor | None
+        Class weight for the positive (cancer) class. Multiplies alpha.
+    label_smoothing : float
+        Prevents overconfident predictions. Default 0.1.
+    """
+
+    def __init__(
+        self,
+        alpha:           float               = 0.25,
+        gamma:           float               = 2.0,
+        pos_weight:      torch.Tensor | None = None,
+        label_smoothing: float               = 0.1,
+    ) -> None:
+        super().__init__()
+        self.alpha           = alpha
+        self.gamma           = gamma
+        self.pos_weight      = pos_weight
+        self.label_smoothing = label_smoothing
+
+    def forward(
+        self,
+        logits:  torch.Tensor,   # (B, C)
+        targets: torch.Tensor,   # (B,) long
+    ) -> torch.Tensor:
+        # Standard CE with label smoothing and class weights
+        ce = F.cross_entropy(
+            logits, targets,
+            weight          = self.pos_weight,
+            label_smoothing = self.label_smoothing,
+            reduction       = "none",
+        )
+        # Focal modulation — downweight easy examples
+        pt          = torch.exp(-ce)
+        focal_loss  = self.alpha * (1 - pt) ** self.gamma * ce
+        return focal_loss.mean()
+
+
+# ╔══════════════════════════════════════════════════════════════════════════════╗
+# ║  MULTI-VIEW MAMMOGRAM CLASSIFIER                                            ║
+# ╚══════════════════════════════════════════════════════════════════════════════╝
+
+class MultiViewMammogramClassifier(nn.Module):
+    """
+    Siamese EfficientNet-B4 with attention-based CC+MLO view fusion.
+
+    Both views are processed by the same EfficientNet-B4 backbone
+    (weight sharing). The ViewAttentionFusion layer then combines
+    the two feature vectors with a learned attention gate.
+
+    Parameters
+    ----------
+    pretrained : bool
+        Load ImageNet weights. Default True.
+    freeze_backbone : bool
+        Freeze backbone during Phase 1 training. Default False.
+    dropout_rate : float
+        Dropout in the classifier head. Default 0.4.
+    """
+
+    FEATURE_DIM = 1792   # EfficientNet-B4 output channels
+
+    def __init__(
+        self,
+        pretrained:      bool  = True,
+        freeze_backbone: bool  = False,
+        dropout_rate:    float = 0.4,
+    ) -> None:
+        super().__init__()
+
+        # Shared backbone — same weights for both views (Siamese)
+        weights          = EfficientNet_B4_Weights.IMAGENET1K_V1 if pretrained else None
+        backbone         = models.efficientnet_b4(weights=weights)
+        self.features    = backbone.features
+        self.avgpool     = backbone.avgpool
+
+        # Freeze for Phase 1
+        if freeze_backbone:
+            for p in self.features.parameters():
+                p.requires_grad = False
+
+        # View attention fusion
+        self.fusion = ViewAttentionFusion(dim=self.FEATURE_DIM)
+
+        # Classifier head
+        D = self.FEATURE_DIM
+        self.classifier = nn.Sequential(
+            nn.BatchNorm1d(D),
+            nn.Dropout(p=dropout_rate),
+            nn.Linear(D, 512),
+            nn.ReLU(inplace=True),
+            nn.BatchNorm1d(512),
+            nn.Dropout(p=dropout_rate * 0.75),
+            nn.Linear(512, 2),
+        )
+
+    def encode(self, x: torch.Tensor) -> torch.Tensor:
+        """Encode a single view to a feature vector (B, D)."""
+        feat   = self.features(x)                # (B, D, H, W)
+        pooled = self.avgpool(feat)              # (B, D, 1, 1)
+        return torch.flatten(pooled, 1)          # (B, D)
+
+    def forward(
+        self,
+        cc_view:  torch.Tensor,   # (B, 3, H, W) — craniocaudal view
+        mlo_view: torch.Tensor,   # (B, 3, H, W) — mediolateral oblique view
+    ) -> dict[str, torch.Tensor]:
+        """
+        Forward pass with both views.
+
+        Returns dict with "logits" (B,2) and "probs" (B,2).
+        """
+        cc_feat  = self.encode(cc_view)          # (B, D)
+        mlo_feat = self.encode(mlo_view)         # (B, D)
+        fused    = self.fusion(cc_feat, mlo_feat)# (B, D)
+        logits   = self.classifier(fused)        # (B, 2)
+        probs    = torch.softmax(logits, dim=1)
+        return {"logits": logits, "probs": probs}
+
+    def forward_single(self, x: torch.Tensor) -> dict[str, torch.Tensor]:
+        """
+        Single-view forward pass — duplicates input for both CC and MLO.
+        Used at inference when only one image is available.
+        """
+        return self.forward(x, x)
+
+
+# ╔══════════════════════════════════════════════════════════════════════════════╗
+# ║  SINGLE-VIEW CLASSIFIER (kept for backward compatibility)                   ║
+# ╚══════════════════════════════════════════════════════════════════════════════╝
+
+class MammogramClassifier(nn.Module):
+    """
+    Single-view EfficientNet-B4 (original architecture).
+    Kept for backward compatibility with existing inference code.
+    """
+
+    def __init__(
+        self,
+        pretrained:      bool  = True,
+        freeze_backbone: bool  = False,
+        dropout_rate:    float = 0.4,
+        num_classes:     int   = 2,
+    ) -> None:
+        super().__init__()
+        weights       = EfficientNet_B4_Weights.IMAGENET1K_V1 if pretrained else None
+        backbone      = models.efficientnet_b4(weights=weights)
+        self.features = backbone.features
+        self.avgpool  = backbone.avgpool
+
+        if freeze_backbone:
+            for p in self.features.parameters():
+                p.requires_grad = False
+
+        D = 1792
+        self.classifier = nn.Sequential(
+            nn.BatchNorm1d(D),
+            nn.Dropout(p=dropout_rate),
+            nn.Linear(D, 512),
+            nn.ReLU(inplace=True),
+            nn.BatchNorm1d(512),
+            nn.Dropout(p=dropout_rate * 0.75),
+            nn.Linear(512, num_classes),
+        )
+
+    def forward(self, x: torch.Tensor) -> dict[str, torch.Tensor]:
+        feat   = self.features(x)
+        pooled = self.avgpool(feat)
+        flat   = torch.flatten(pooled, 1)
+        logits = self.classifier(flat)
+        return {"logits": logits, "probs": torch.softmax(logits, dim=1)}

model/model.py

@@ -0,0 +1,127 @@
+"""
+model/model.py
+──────────────
+DenseNet-121 backbone fine-tuned for binary classification of
+breast cancer histopathology images (benign vs. malignant).
+
+Architecture
+────────────
+  DenseNet-121 (pretrained on ImageNet)
+    └─ Adaptive Average Pool → flatten
+    └─ Classifier head
+         ├─ BatchNorm1d(1024)
+         ├─ Dropout(p=0.4)
+         ├─ Linear(1024 → 256)  + ReLU
+         ├─ BatchNorm1d(256)
+         ├─ Dropout(p=0.3)
+         └─ Linear(256 → 2)   ← raw logits  [benign, malignant]
+
+Outputs
+────────
+  logits  : Tensor[1, 2]   — raw scores (pre-softmax)
+  probs   : Tensor[1, 2]   — calibrated probabilities via softmax
+"""
+
+import torch
+import torch.nn as nn
+from torchvision import models
+
+
+class BreastCancerClassifier(nn.Module):
+    """
+    DenseNet-121 backbone with a custom two-class head.
+
+    Parameters
+    ----------
+    pretrained : bool
+        Load ImageNet weights into the DenseNet-121 backbone (default True).
+    freeze_backbone : bool
+        Freeze all DenseNet layers except the classifier head (default False).
+        Set True for pure feature-extraction / fast fine-tuning scenarios.
+    dropout_rate : float
+        Dropout probability applied in the classifier head (default 0.4).
+    """
+
+    def __init__(
+        self,
+        pretrained: bool = True,
+        freeze_backbone: bool = False,
+        dropout_rate: float = 0.4,
+    ) -> None:
+        super().__init__()
+
+        # ── Backbone ────────────────────────────────────────────────────────
+        weights = models.DenseNet121_Weights.IMAGENET1K_V1 if pretrained else None
+        densenet = models.densenet121(weights=weights)
+
+        # Keep every layer except the original FC classifier
+        self.features = densenet.features          # Conv + DenseBlocks + Transitions
+        self.pool     = nn.AdaptiveAvgPool2d((1, 1))
+
+        in_features = densenet.classifier.in_features   # 1024 for DenseNet-121
+
+        # ── Classifier head ─────────────────────────────────────────────────
+        self.classifier = nn.Sequential(
+            nn.BatchNorm1d(in_features),
+            nn.Dropout(p=dropout_rate),
+            nn.Linear(in_features, 256),
+            nn.ReLU(inplace=True),
+            nn.BatchNorm1d(256),
+            nn.Dropout(p=dropout_rate * 0.75),
+            nn.Linear(256, 2),          # 2 logits: [benign, malignant]
+        )
+
+        # ── Optional backbone freeze ─────────────────────────────────────────
+        if freeze_backbone:
+            for param in self.features.parameters():
+                param.requires_grad = False
+
+        self._init_classifier_weights()
+
+    # ────────────────────────────────────────────────────────────────────────
+    def _init_classifier_weights(self) -> None:
+        """Kaiming / Xavier initialisation for the custom head."""
+        for module in self.classifier.modules():
+            if isinstance(module, nn.Linear):
+                nn.init.kaiming_normal_(module.weight, nonlinearity="relu")
+                if module.bias is not None:
+                    nn.init.zeros_(module.bias)
+            elif isinstance(module, nn.BatchNorm1d):
+                nn.init.ones_(module.weight)
+                nn.init.zeros_(module.bias)
+
+    # ────────────────────────────────────────────────────────────────────────
+    def forward(self, x: torch.Tensor) -> dict:
+        """
+        Forward pass.
+
+        Parameters
+        ----------
+        x : torch.Tensor
+            Normalised image tensor of shape (B, 3, 224, 224).
+
+        Returns
+        -------
+        dict with keys
+            "logits" : Tensor[B, 2]  — raw model outputs
+            "probs"  : Tensor[B, 2]  — softmax probabilities
+        """
+        features = self.features(x)             # (B, 1024, 7, 7)
+        pooled   = self.pool(features)           # (B, 1024, 1, 1)
+        flat     = torch.flatten(pooled, 1)      # (B, 1024)
+        logits   = self.classifier(flat)         # (B, 2)
+        probs    = torch.softmax(logits, dim=1)  # (B, 2)
+
+        return {"logits": logits, "probs": probs}
+
+    # ────────────────────────────────────────────────────────────────────────
+    def get_feature_maps(self, x: torch.Tensor) -> torch.Tensor:
+        """
+        Return the final DenseNet feature maps before pooling.
+        Used by Grad-CAM and other spatial explainability modules.
+
+        Returns
+        -------
+        Tensor[B, 1024, 7, 7]
+        """
+        return self.features(x)

model/model_s123.pth

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

model/model_s42.pth

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

model/model_s999.pth

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

model/weights.pth

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

requirements-deploy.txt

@@ -0,0 +1,24 @@
+# MedAI backend — SERVING dependencies only (Hugging Face Space).
+# Torch CPU wheels are installed separately in the Dockerfile (smaller than CUDA).
+# Excludes training/FLAN-T5 deps (transformers, datasets, accelerate, sentencepiece)
+# because the API defaults to the deterministic template explainer (USE_LLM_MODEL=false).
+
+Pillow>=10.0.0
+numpy>=1.24.0,<2.0
+scipy>=1.11.0
+
+# Mammogram DICOM support
+pydicom>=2.4.0
+pylibjpeg>=2.0.0
+python-gdcm>=3.0.0
+opencv-python-headless>=4.8.0
+
+# API
+fastapi>=0.110.0
+uvicorn[standard]>=0.29.0
+python-multipart>=0.0.9
+python-dotenv>=1.0.0
+
+# Chat (Groq via the OpenAI-compatible SDK)
+openai>=1.30.0
+requests>=2.31.0

requirements.txt

@@ -0,0 +1,33 @@
+# Core ML
+torch>=2.1.0
+torchvision>=0.16.0
+Pillow>=10.0.0
+numpy>=1.24.0,<2.0
+
+# Histopathology dataset
+datasets>=2.18.0
+
+# LLM Explainer
+transformers>=4.38.0
+sentencepiece>=0.1.99
+accelerate>=0.27.0
+
+# Mammogram DICOM support
+pydicom>=2.4.0
+pylibjpeg>=2.0.0
+python-gdcm>=3.0.0
+scipy>=1.11.0
+opencv-python-headless>=4.8.0
+
+# API
+fastapi>=0.110.0
+uvicorn[standard]>=0.29.0
+python-multipart>=0.0.9
+python-dotenv>=1.0.0
+
+# Chat pipeline
+groq>=0.9.0
+requests>=2.31.0
+
+# Testing
+pytest>=8.0.0

tests/test_classifier.py

@@ -0,0 +1,183 @@
+"""
+tests/test_classifier.py
+────────────────────────
+Unit and integration tests for the medical-ai module.
+
+Run from the repo root:
+    pytest tests/ -v
+
+Import paths assume the project root (medical-ai/) is the working directory.
+"""
+
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+import numpy as np
+import pytest
+import torch
+from PIL import Image
+
+from model import BreastCancerClassifier, BreastCancerInferencePipeline
+from utils import ImagePreprocessor
+
+
+# ── Fixtures ──────────────────────────────────────────────────────────────────
+
+@pytest.fixture(scope="module")
+def dummy_pil():
+    """224×224 RGB PIL image filled with mid-grey."""
+    return Image.fromarray(
+        np.full((224, 224, 3), 128, dtype=np.uint8), mode="RGB"
+    )
+
+@pytest.fixture(scope="module")
+def dummy_np():
+    """224×224×3 uint8 numpy array."""
+    return np.random.randint(0, 255, (224, 224, 3), dtype=np.uint8)
+
+@pytest.fixture(scope="module")
+def dummy_tensor():
+    """Properly-shaped (1, 3, 224, 224) float32 tensor."""
+    return torch.rand(1, 3, 224, 224)
+
+@pytest.fixture(scope="module")
+def model():
+    return BreastCancerClassifier(pretrained=False)
+
+@pytest.fixture(scope="module")
+def pipeline():
+    return BreastCancerInferencePipeline(weights_path=None, device="cpu")
+
+
+# ── model/model.py ────────────────────────────────────────────────────────────
+
+class TestBreastCancerClassifier:
+
+    def test_output_keys(self, model):
+        x = torch.rand(1, 3, 224, 224)
+        out = model(x)
+        assert "logits" in out and "probs" in out
+
+    def test_logits_shape(self, model):
+        x = torch.rand(2, 3, 224, 224)
+        out = model(x)
+        assert out["logits"].shape == (2, 2), "Logits must be (B, 2)"
+
+    def test_probs_sum_to_one(self, model):
+        x = torch.rand(4, 3, 224, 224)
+        out = model(x)
+        sums = out["probs"].sum(dim=1)
+        assert torch.allclose(sums, torch.ones(4), atol=1e-5)
+
+    def test_probs_in_range(self, model):
+        x = torch.rand(1, 3, 224, 224)
+        out = model(x)
+        assert out["probs"].min() >= 0.0
+        assert out["probs"].max() <= 1.0
+
+    def test_feature_maps_shape(self, model):
+        """Validates Grad-CAM hook compatibility."""
+        x = torch.rand(1, 3, 224, 224)
+        fm = model.get_feature_maps(x)
+        assert fm.shape == (1, 1024, 7, 7)
+
+    def test_deterministic_output(self, model):
+        """Identical inputs must produce identical outputs at eval time."""
+        model.eval()
+        x = torch.rand(1, 3, 224, 224)
+        with torch.no_grad():
+            out_a = model(x)
+            out_b = model(x)
+        assert torch.allclose(out_a["logits"], out_b["logits"])
+
+    def test_batch_inference(self, model):
+        x = torch.rand(8, 3, 224, 224)
+        out = model(x)
+        assert out["logits"].shape == (8, 2)
+
+    def test_freeze_backbone(self):
+        m = BreastCancerClassifier(pretrained=False, freeze_backbone=True)
+        for param in m.features.parameters():
+            assert not param.requires_grad, "Backbone params should be frozen"
+
+
+# ── utils/preprocessing.py ───────────────────────────────────────────────────
+
+class TestImagePreprocessor:
+
+    def test_pil_input(self, dummy_pil):
+        t = ImagePreprocessor()(dummy_pil)
+        assert t.shape == (1, 3, 224, 224)
+        assert t.dtype == torch.float32
+
+    def test_numpy_input(self, dummy_np):
+        t = ImagePreprocessor()(dummy_np)
+        assert t.shape == (1, 3, 224, 224)
+
+    def test_tensor_input(self, dummy_tensor):
+        t = ImagePreprocessor()(dummy_tensor)
+        assert t.shape == (1, 3, 224, 224)
+
+    def test_normalization_shifts_range(self, dummy_pil):
+        """ImageNet normalization should shift values outside raw [0,1]."""
+        t = ImagePreprocessor()(dummy_pil)
+        assert not (t.min() >= 0 and t.max() <= 1)
+
+    def test_invalid_type_raises(self):
+        with pytest.raises(TypeError):
+            ImagePreprocessor()({"not": "an image"})
+
+    def test_grayscale_numpy_converted_to_rgb(self):
+        grey = np.full((224, 224), 128, dtype=np.uint8)
+        t = ImagePreprocessor()(grey)
+        assert t.shape == (1, 3, 224, 224)
+
+
+# ── model/inference.py ────────────────────────────────────────────────────────
+
+class TestInferencePipeline:
+
+    def test_output_schema(self, pipeline, dummy_pil):
+        result = pipeline.predict(dummy_pil)
+        assert "prediction" in result
+        assert "confidence" in result
+        assert "logits"     in result
+
+    def test_prediction_is_valid_label(self, pipeline, dummy_pil):
+        result = pipeline.predict(dummy_pil)
+        assert result["prediction"] in ("benign", "malignant")
+
+    def test_confidence_range(self, pipeline, dummy_pil):
+        result = pipeline.predict(dummy_pil)
+        assert 0.0 <= result["confidence"] <= 1.0
+
+    def test_logits_shape(self, pipeline, dummy_pil):
+        result = pipeline.predict(dummy_pil)
+        assert result["logits"].shape == (1, 2)
+
+    def test_batch_predict_length(self, pipeline, dummy_pil, dummy_np):
+        results = pipeline.predict_batch([dummy_pil, dummy_np])
+        assert len(results) == 2
+
+    def test_deterministic_inference(self, pipeline, dummy_pil):
+        r1 = pipeline.predict(dummy_pil)
+        r2 = pipeline.predict(dummy_pil)
+        assert r1["prediction"] == r2["prediction"]
+        assert r1["confidence"] == r2["confidence"]
+        assert torch.allclose(r1["logits"], r2["logits"])
+
+    def test_numpy_input_accepted(self, pipeline, dummy_np):
+        result = pipeline.predict(dummy_np)
+        assert result["prediction"] in ("benign", "malignant")
+
+    def test_logits_detached_from_graph(self, pipeline, dummy_pil):
+        result = pipeline.predict(dummy_pil)
+        assert not result["logits"].requires_grad
+
+    def test_missing_weights_raises(self):
+        with pytest.raises(FileNotFoundError):
+            BreastCancerInferencePipeline(
+                weights_path="model/nonexistent_weights.pth",
+                device="cpu",
+            )

train.py

@@ -0,0 +1,692 @@
+"""
+train.py
+────────
+Training script for the BreastCancerClassifier (DenseNet-121).
+
+What this file does
+───────────────────
+  1. Loads the BreastMNIST dataset (auto-downloaded via MedMNIST)
+  2. Applies training augmentations from utils/preprocessing.py
+  3. Fine-tunes the DenseNet-121 backbone + custom classifier head
+  4. Validates after every epoch and tracks the best model
+  5. Saves the best weights to model/weights.pth
+
+Usage
+─────
+  # Basic — runs with all defaults
+  python train.py
+
+  # Custom — override any hyperparameter
+  python train.py --epochs 30 --lr 1e-4 --batch-size 64 --freeze-backbone
+
+Output
+──────
+  model/weights.pth     ← best checkpoint (loaded by inference.py)
+  training_log.csv      ← per-epoch metrics for plotting
+
+Dataset
+───────
+  PatchCamelyon / PCam  (HuggingFace — 1aurent/PatchCamelyon)
+  - 327,680 training patches   (roughly balanced ~50/50)
+  - 32,768  validation patches
+  - 32,768  test patches
+  - Binary labels: 0 = no tumour tissue,  1 = tumour tissue present
+  - 96×96 px RGB H&E-stained histopathology patches
+  - Sourced from Camelyon16 whole-slide images (lymph node sections)
+
+Install dependencies
+────────────────────
+  pip install -r requirements.txt
+  pip install datasets Pillow
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import logging
+import sys
+import time
+from pathlib import Path
+
+import torch
+import torch.nn as nn
+from torch.optim import Adam
+from torch.optim.lr_scheduler import OneCycleLR
+from torch.utils.data import DataLoader
+
+# ── Project imports ──────────────────────────────────────────────────────────
+# Insert project root so `model` and `utils` are importable regardless of
+# where you invoke the script from.
+ROOT = Path(__file__).resolve().parent
+sys.path.insert(0, str(ROOT))
+
+from model.model import BreastCancerClassifier
+from utils.preprocessing import build_training_transform, build_inference_transform
+
+# ── Logging ───────────────────────────────────────────────────────────────────
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s  %(levelname)-8s  %(message)s",
+    datefmt="%H:%M:%S",
+)
+logger = logging.getLogger(__name__)
+
+
+# ╔══════════════════════════════════════════════════════════════════════════════╗
+# ║                         CONFIGURATION                                       ║
+# ╚══════════════════════════════════════════════════════════════════════════════╝
+
+def parse_args() -> argparse.Namespace:
+    """All hyperparameters are CLI-overridable — nothing is hardcoded."""
+    p = argparse.ArgumentParser(
+        description="Train BreastCancerClassifier on BreastMNIST",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+
+    # ── Data ─────────────────────────────────────────────────────────────────
+    p.add_argument("--data-dir",        type=str,   default="data",
+                   help="Directory to download / cache PatchCamelyon")
+
+    # ── Training ─────────────────────────────────────────────────────────────
+    p.add_argument("--epochs",          type=int,   default=20,
+                   help="Total training epochs")
+    p.add_argument("--batch-size",      type=int,   default=32,
+                   help="Samples per mini-batch")
+    p.add_argument("--lr",              type=float, default=3e-4,
+                   help="Initial learning rate for Adam optimizer")
+    p.add_argument("--weight-decay",    type=float, default=1e-4,
+                   help="L2 regularization strength")
+
+    # ── Model ────────────────────────────────────────────────────────────────
+    p.add_argument("--freeze-backbone", action="store_true",
+                   help="Freeze DenseNet feature layers — train head only")
+    p.add_argument("--dropout",         type=float, default=0.4,
+                   help="Dropout rate in classifier head")
+
+    # ── LR Scheduler ─────────���───────────────────────────────────────────────
+    p.add_argument("--lr-patience",     type=int,   default=4,
+                   help="Epochs with no val-loss improvement before LR reduction")
+    p.add_argument("--lr-factor",       type=float, default=0.5,
+                   help="Multiply LR by this factor on plateau")
+
+    # ── Output ───────────────────────────────────────────────────────────────
+    p.add_argument("--weights-out",     type=str,   default="model/weights.pth",
+                   help="Path to save the best model checkpoint")
+    p.add_argument("--log-out",         type=str,   default="training_log.csv",
+                   help="Path to save per-epoch metrics CSV")
+
+    # ── Misc ─────────────────────────────────────────────────────────────────
+    p.add_argument("--num-workers",     type=int,   default=4,
+                   help="DataLoader worker threads")
+    p.add_argument("--seed",            type=int,   default=42,
+                   help="Random seed for reproducibility")
+    p.add_argument("--early-stop",      type=int,   default=7,
+                   help="Stop if val loss doesn't improve for N epochs (0 = off)")
+
+    # ── Regularization fixes ──────────────────────────────────────────────────
+    p.add_argument("--mixup-alpha",    type=float, default=0.4,
+                   help="Beta distribution alpha for Mixup (0 = disabled)")
+    p.add_argument("--label-smoothing", type=float, default=0.1,
+                   help="Label smoothing for CrossEntropyLoss (0 = disabled)")
+
+    # ── OneCycleLR ────────────────────────────────────────────────────────────
+    p.add_argument("--max-lr",         type=float, default=3e-3,
+                   help="Peak LR for OneCycleLR (typically 10x base lr)")
+
+    # ── Deduplication ─────────────────────────────────────────────────────────
+    p.add_argument("--deduplicate",    action="store_true",
+                   help="Remove duplicate images from training set via MD5 hashing")
+
+    return p.parse_args()
+
+
+# ╔══════════════════════════════════════════════════════════════════════════════╗
+# ║                         DATASET                                             ║
+# ╚══════════════════════════════════════════════════════════════════════════════╝
+
+def get_dataloaders(
+    args: argparse.Namespace,
+) -> tuple[DataLoader, DataLoader, DataLoader, torch.Tensor]:
+    """
+    Stream PatchCamelyon from HuggingFace and return
+    (train_loader, val_loader, test_loader, pos_weight).
+
+    PatchCamelyon (PCam)
+    ────────────────────
+    327,680 train / 32,768 val / 32,768 test
+    96×96 px RGB H&E-stained histopathology patches from lymph node sections.
+    Label 0 = no tumour tissue in centre region.
+    Label 1 = tumour tissue present in centre region.
+    Dataset is roughly balanced (~50/50) so pos_weight will be close to 1.0.
+
+    HuggingFace streaming
+    ─────────────────────
+    PCam is ~7 GB total. cache_dir stores the downloaded files locally so
+    subsequent runs don't re-download. On first run this may take a few minutes
+    depending on your connection speed.
+    """
+    try:
+        from datasets import load_dataset
+    except ImportError:
+        logger.error("datasets not installed. Run:  pip install datasets")
+        sys.exit(1)
+
+    data_dir = Path(args.data_dir)
+    data_dir.mkdir(parents=True, exist_ok=True)
+
+    logger.info("Loading PatchCamelyon from HuggingFace (cache: %s) ...", data_dir)
+    logger.info("First run will download ~7 GB — subsequent runs use cache.")
+
+    # ── Download / load all three splits ─────────────────────────────────────
+    # cache_dir stores the Arrow files locally after first download.
+    hf_train = load_dataset("1aurent/PatchCamelyon", split="train",
+                            cache_dir=str(data_dir))
+    hf_val   = load_dataset("1aurent/PatchCamelyon", split="valid",
+                            cache_dir=str(data_dir))
+    hf_test  = load_dataset("1aurent/PatchCamelyon", split="test",
+                            cache_dir=str(data_dir))
+
+    logger.info("Dataset splits  train=%d  val=%d  test=%d",
+                len(hf_train), len(hf_val), len(hf_test))
+
+    # ── Optional deduplication ────────────────────────────────────────────────
+    if getattr(args, "deduplicate", False):
+        hf_train = deduplicate_dataset(hf_train, split_name="train")
+
+    # ── Compute pos_weight from training labels ───────────────────────────────
+    # PCam is ~50/50 so pos_weight ≈ 1.0, but we still compute it correctly
+    # in case the cached split has slight imbalance.
+    all_labels  = hf_train["label"]                      # list of ints, fast column access
+    n_benign    = all_labels.count(0)
+    n_malignant = all_labels.count(1)
+    pos_weight  = torch.tensor([n_benign / max(n_malignant, 1)], dtype=torch.float32)
+
+    logger.info("Class balance  benign=%d  malignant=%d  → pos_weight=%.3f",
+                n_benign, n_malignant, pos_weight.item())
+
+    # ── Wrap HuggingFace datasets in PyTorch Dataset objects ──────────────────
+    train_transform = build_training_transform()
+    eval_transform  = build_inference_transform()
+
+    train_ds = PCamDataset(hf_train, transform=train_transform)
+    val_ds   = PCamDataset(hf_val,   transform=eval_transform)
+    test_ds  = PCamDataset(hf_test,  transform=eval_transform)
+
+    # ── DataLoaders ───────────────────────────────────────────────────────────
+    train_loader = DataLoader(
+        train_ds,
+        batch_size=args.batch_size,
+        shuffle=True,
+        num_workers=args.num_workers,
+        pin_memory=True,
+        drop_last=True,
+    )
+    val_loader = DataLoader(
+        val_ds,
+        batch_size=args.batch_size * 2,
+        shuffle=False,
+        num_workers=args.num_workers,
+        pin_memory=True,
+    )
+    test_loader = DataLoader(
+        test_ds,
+        batch_size=args.batch_size * 2,
+        shuffle=False,
+        num_workers=args.num_workers,
+        pin_memory=True,
+    )
+
+    return train_loader, val_loader, test_loader, pos_weight
+
+
+# ╔══════════════════════════════════════════════════════════════════════════════╗
+# ║                         PCAM PYTORCH DATASET WRAPPER                        ║
+# ╚══════════════════════════════════════════════════════════════════════════════╝
+
+class PCamDataset(torch.utils.data.Dataset):
+    """
+    Wraps a HuggingFace PCam split into a standard PyTorch Dataset.
+
+    HuggingFace datasets return dicts like {"image": PIL.Image, "label": int}.
+    PyTorch DataLoader expects __len__ and __getitem__ returning (tensor, int).
+    This class bridges that gap — it is the only PCam-specific code in the
+    entire project. Everything else (model, inference, API) stays identical.
+
+    Parameters
+    ----------
+    hf_dataset : HuggingFace Dataset split
+    transform  : torchvision transform pipeline to apply to each image
+    """
+
+    def __init__(self, hf_dataset, transform) -> None:
+        self.dataset   = hf_dataset
+        self.transform = transform
+
+    def __len__(self) -> int:
+        return len(self.dataset)
+
+    def __getitem__(self, idx: int) -> tuple[torch.Tensor, int]:
+        sample = self.dataset[idx]
+
+        # HuggingFace already gives us a PIL Image — convert to RGB in case
+        # any patches are stored as RGBA or have an unexpected mode
+        image = sample["image"].convert("RGB")
+        label = int(sample["label"])
+
+        # Apply the transform pipeline (resize → crop → normalize)
+        # This is the same pipeline used by inference.py via ImagePreprocessor
+        tensor = self.transform(image)   # → (3, 224, 224)
+
+        return tensor, label
+
+
+# ╔══════════════════════════════════════════════════════════════════════════════╗
+# ║                         DEDUPLICATION                                       ║
+# ╚══════════════════════════════════════════════════════════════════════════════╝
+
+def deduplicate_dataset(hf_dataset, split_name: str = "train"):
+    """
+    Remove duplicate images from a HuggingFace PCam split using MD5 hashing.
+
+    The standard PCam dataset contains duplicate images across training samples.
+    Duplicates cause the model to memorise specific patches rather than learning
+    generalizable tissue patterns — directly causing the overfitting seen in
+    earlier training runs. This function removes them.
+
+    The Kaggle PCam competition version has duplicates removed (giving ~220K
+    training samples vs the original 262K). This function replicates that
+    cleaning step without requiring a Kaggle account.
+
+    Parameters
+    ----------
+    hf_dataset  : HuggingFace Dataset split
+    split_name  : for logging only
+
+    Returns
+    -------
+    HuggingFace Dataset with duplicate images removed
+    """
+    import hashlib
+
+    logger.info("Deduplicating %s split (%d samples) — this runs once...",
+                split_name, len(hf_dataset))
+
+    seen_hashes = set()
+    keep_indices = []
+    batch_size = 500   # process in batches for speed
+
+    for start in range(0, len(hf_dataset), batch_size):
+        end   = min(start + batch_size, len(hf_dataset))
+        batch = hf_dataset[start:end]   # dict of lists — fast Arrow column access
+        images = batch["image"]          # list of PIL Images
+
+        for i, img in enumerate(images):
+            # Hash the raw pixel bytes — identical images hash identically
+            img_hash = hashlib.md5(img.tobytes()).hexdigest()
+            if img_hash not in seen_hashes:
+                seen_hashes.add(img_hash)
+                keep_indices.append(start + i)
+
+        if (start // batch_size) % 50 == 0:
+            logger.info("  Hashed %d / %d samples...", end, len(hf_dataset))
+
+    deduped  = hf_dataset.select(keep_indices)
+    removed  = len(hf_dataset) - len(deduped)
+    logger.info("Deduplication complete: removed %d duplicates, kept %d samples (%.1f%%)",
+                removed, len(deduped), 100 * len(deduped) / len(hf_dataset))
+    return deduped
+
+
+# ╔══════════════════════════════════════════════════════════════════════════════╗
+# ║                         ONE EPOCH                                           ║
+# ╚══════════════════════════════════════════════════════════════════════════════╝
+
+def run_epoch(
+    model:       nn.Module,
+    loader:      DataLoader,
+    criterion:   nn.Module,
+    optimizer:   torch.optim.Optimizer | None,
+    device:      torch.device,
+    phase:       str,
+    mixup_alpha: float = 0.0,
+    scheduler    = None,                   # OneCycleLR — stepped per batch
+) -> tuple[float, float, float]:
+    """
+    Run one complete pass over a DataLoader.
+
+    Fix 2 — Mixup augmentation
+    ──────────────────────────
+    When mixup_alpha > 0 and phase == "train", each batch is blended with a
+    randomly shuffled version of itself using a Beta(alpha, alpha) weight.
+    This forces the model to learn smooth interpolations between patches,
+    preventing it from memorising hard boundaries around training examples.
+
+    Returns (avg_loss, accuracy, sensitivity).
+    """
+    import numpy as np
+
+    is_train   = (phase == "train")
+    use_mixup  = is_train and mixup_alpha > 0.0
+    model.train() if is_train else model.eval()
+
+    total_loss = 0.0
+    correct    = 0
+    total      = 0
+    true_pos   = 0
+    actual_pos = 0
+
+    context = torch.enable_grad() if is_train else torch.inference_mode()
+
+    with context:
+        for images, labels in loader:
+
+            images = images.to(device, non_blocking=True)
+            labels = labels.long().to(device, non_blocking=True)
+
+            # ── Fix 2: Mixup ──────────────────────────────────────────────────
+            if use_mixup:
+                # Sample mixing weight from Beta distribution
+                lam = float(np.random.beta(mixup_alpha, mixup_alpha))
+                # Randomly shuffle the batch to get mixing partners
+                idx          = torch.randperm(images.size(0), device=device)
+                mixed_images = lam * images + (1.0 - lam) * images[idx]
+                labels_b     = labels[idx]
+
+                output = model(mixed_images)
+                # Mixed loss: weighted combination of both label sets
+                loss = (lam       * criterion(output["logits"], labels) +
+                        (1 - lam) * criterion(output["logits"], labels_b))
+            else:
+                output = model(images)
+                loss   = criterion(output["logits"], labels)
+
+            # ���─ Backward pass (training only) ─────────────────────────────────
+            if is_train:
+                optimizer.zero_grad()
+                loss.backward()
+                nn.utils.clip_grad_norm_(model.parameters(), max_norm=1.0)
+                optimizer.step()
+                if scheduler is not None:
+                    scheduler.step()       # OneCycleLR steps every batch
+
+            # ── Accumulate metrics (always on original labels) ────────────────
+            preds       = output["logits"].argmax(dim=1)
+            correct    += (preds == labels).sum().item()
+            total      += labels.size(0)
+            total_loss += loss.item() * labels.size(0)
+
+            malignant_mask = (labels == 1)
+            true_pos      += (preds[malignant_mask] == 1).sum().item()
+            actual_pos    += malignant_mask.sum().item()
+
+    avg_loss    = total_loss / max(total, 1)
+    accuracy    = correct    / max(total, 1)
+    sensitivity = true_pos   / max(actual_pos, 1)
+
+    return avg_loss, accuracy, sensitivity
+
+
+# ╔══════════════════════════════════════════════════════════════════════════════╗
+# ║                         CHECKPOINT SAVE                                     ║
+# ╚══════════════════════════════════════════════════════════════════════════════╝
+
+def save_checkpoint(
+    model:     nn.Module,
+    optimizer: torch.optim.Optimizer,
+    epoch:     int,
+    val_loss:  float,
+    val_acc:   float,
+    path:      str | Path,
+) -> None:
+    """
+    Save model weights + training metadata to disk.
+
+    The saved dict uses the key "state_dict" — exactly what
+    inference.py's _load_weights() looks for when loading weights.
+    The extra keys (optimizer, epoch, val_loss, val_acc) are ignored
+    by inference.py but useful if you want to resume training later.
+    """
+    Path(path).parent.mkdir(parents=True, exist_ok=True)
+    torch.save(
+        {
+            "state_dict": model.state_dict(),    # ← inference.py reads this
+            "optimizer":  optimizer.state_dict(),
+            "epoch":      epoch,
+            "val_loss":   val_loss,
+            "val_acc":    val_acc,
+        },
+        path,
+    )
+    logger.info("  ✓ Best checkpoint saved → %s", path)
+
+
+# ╔══════════════════════════════════════════════════════════════════════════════╗
+# ║                         CSV LOGGER                                          ║
+# ╚══════════════════════════════════════════════════════════════════════════════╝
+
+class CSVLogger:
+    """Writes one row per epoch to a CSV file so you can plot training curves."""
+
+    FIELDS = [
+        "epoch", "train_loss", "train_acc", "train_sens",
+        "val_loss", "val_acc", "val_sens", "lr", "epoch_time_s",
+    ]
+
+    def __init__(self, path: str | Path) -> None:
+        self.path = Path(path)
+        # Write header on creation — overwrites any previous log file
+        with open(self.path, "w", newline="") as f:
+            csv.DictWriter(f, fieldnames=self.FIELDS).writeheader()
+
+    def log(self, row: dict) -> None:
+        with open(self.path, "a", newline="") as f:
+            writer = csv.DictWriter(f, fieldnames=self.FIELDS)
+            writer.writerow(
+                {k: round(v, 6) if isinstance(v, float) else v
+                 for k, v in row.items()}
+            )
+
+
+# ╔══════════════════════════════════════════════════════════════════════════════╗
+# ║                         DEVICE RESOLUTION                                   ║
+# ╚══════════════════════════════════════════════════════════════════════════════╝
+
+def resolve_device() -> torch.device:
+    """Auto-detect best available device: CUDA → Apple MPS → CPU."""
+    if torch.cuda.is_available():
+        return torch.device("cuda")
+    if torch.backends.mps.is_available():
+        return torch.device("mps")
+    return torch.device("cpu")
+
+
+# ╔════════════════════════════════════���═════════════════════════════════════════╗
+# ║                         MAIN                                                ║
+# ╚══════════════════════════════════════════════════════════════════════════════╝
+
+def main() -> None:
+    args   = parse_args()
+    device = resolve_device()
+
+    # ── Reproducibility ───────────────────────────────────────────────────────
+    # Setting the seed ensures you get the same weight initializations,
+    # data shuffling order, and dropout masks every run. Makes results comparable.
+    torch.manual_seed(args.seed)
+    if device.type == "cuda":
+        torch.cuda.manual_seed_all(args.seed)
+
+    logger.info("═" * 58)
+    logger.info("  Breast Cancer Classifier — Training Run (PCam)")
+    logger.info("  Device      : %s", device)
+    logger.info("  Epochs      : %d", args.epochs)
+    logger.info("  Batch size  : %d", args.batch_size)
+    logger.info("  LR          : %g", args.lr)
+    logger.info("  Freeze      : %s", args.freeze_backbone)
+    logger.info("  Mixup alpha : %.2f", args.mixup_alpha)
+    logger.info("  Lbl smooth  : %.2f", args.label_smoothing)
+    logger.info("  Max LR      : %g",   args.max_lr)
+    logger.info("  Deduplicate : %s",   args.deduplicate)
+    logger.info("  Output      : %s",   args.weights_out)
+    logger.info("═" * 58)
+
+    # ── Step 1 — Load data ────────────────────────────────────────────────────
+    train_loader, val_loader, test_loader, pos_weight = get_dataloaders(args)
+
+    # ── Step 2 — Build model ──────────────────────────────────────────────────
+    # Uses BreastCancerClassifier from model/model.py — the same class
+    # that inference.py uses at prediction time.
+    model = BreastCancerClassifier(
+        pretrained=True,                        # start from ImageNet weights
+        freeze_backbone=args.freeze_backbone,
+        dropout_rate=args.dropout,
+    ).to(device)
+
+    trainable = sum(p.numel() for p in model.parameters() if p.requires_grad)
+    total     = sum(p.numel() for p in model.parameters())
+    logger.info("Parameters  trainable=%s / total=%s",
+                f"{trainable:,}", f"{total:,}")
+
+    # ── Step 3 — Loss function ────────────────────────────────────────────────
+    # CrossEntropyLoss with class weights.
+    # [1.0, pos_weight] = [benign weight, malignant weight]
+    # The malignant class gets upweighted because:
+    #   (a) it's the minority class
+    #   (b) missing a malignant case is clinically much worse than a false alarm
+    criterion = nn.CrossEntropyLoss(
+        weight          = torch.tensor([1.0, pos_weight.item()], device=device),
+        label_smoothing = args.label_smoothing,   # Fix 3: label smoothing
+    )
+
+    # ── Step 4 — Optimizer ────────────────────────────────────────────────────
+    # Adam is used because it adapts the learning rate per parameter —
+    # well suited for fine-tuning pretrained networks.
+    # filter(...) skips frozen backbone parameters so they receive no updates.
+    optimizer = Adam(
+        filter(lambda p: p.requires_grad, model.parameters()),
+        lr=args.lr,
+        weight_decay=args.weight_decay,
+    )
+
+    # ── Step 5 — LR Scheduler ─────────────────────────────────────────────────
+    # OneCycleLR ramps the LR up to max_lr then back down over all epochs.
+    # This breaks out of bad local minima early (ramp up) then converges
+    # precisely (ramp down). Proven to reach 97%+ on PCam in published work.
+    # Must be stepped every BATCH — see run_epoch() for the scheduler.step() call.
+    scheduler = OneCycleLR(
+        optimizer,
+        max_lr          = args.max_lr,
+        steps_per_epoch = len(train_loader),   # batches per epoch
+        epochs          = args.epochs,
+        pct_start       = 0.3,                 # 30% of training ramps up
+        anneal_strategy = "cos",
+    )
+
+    # ── Training state ────────────────────────────────────────────────────────
+    csv_logger        = CSVLogger(args.log_out)
+    best_val_sens     = 0.0       # track sensitivity, not loss
+    epochs_no_improve = 0
+
+    # ═══════════════════════════════════════════════════════════════════════════
+    #  EPOCH LOOP
+    # ═══════════════════════════════════════════════════════════════════════════
+    for epoch in range(1, args.epochs + 1):
+        t0 = time.time()
+
+        # ── Train for one full epoch ───────────────────────────────────────────
+        train_loss, train_acc, train_sens = run_epoch(
+            model, train_loader, criterion, optimizer, device,
+            phase="train", mixup_alpha=args.mixup_alpha,
+            scheduler=scheduler,
+        )
+
+        # ── Validate (no weight updates) ──────────────────────────────────────
+        val_loss, val_acc, val_sens = run_epoch(
+            model, val_loader, criterion, None, device, phase="val"
+        )
+
+        elapsed    = time.time() - t0
+        current_lr = optimizer.param_groups[0]["lr"]
+
+        # ── Print epoch summary ───────────────────────────────────────────────
+        logger.info(
+            "Epoch %2d/%d │ "
+            "train  loss=%.4f  acc=%.3f  sens=%.3f │ "
+            "val  loss=%.4f  acc=%.3f  sens=%.3f │ "
+            "lr=%.1e  time=%.1fs",
+            epoch, args.epochs,
+            train_loss, train_acc, train_sens,
+            val_loss,   val_acc,   val_sens,
+            current_lr, elapsed,
+        )
+
+        # ── Log to CSV ────────────────────────────────────────────────────────
+        csv_logger.log({
+            "epoch":        epoch,
+            "train_loss":   train_loss,
+            "train_acc":    train_acc,
+            "train_sens":   train_sens,
+            "val_loss":     val_loss,
+            "val_acc":      val_acc,
+            "val_sens":     val_sens,
+            "lr":           current_lr,
+            "epoch_time_s": elapsed,
+        })
+
+        # ── Save if this is the best model so far ─────────────────────────────
+        if val_sens > best_val_sens:
+            best_val_sens     = val_sens
+            epochs_no_improve = 0
+            save_checkpoint(
+                model, optimizer, epoch,
+                val_loss, val_acc,
+                path=args.weights_out,
+            )
+            logger.info("  ★ New best sensitivity: %.3f", best_val_sens)
+        else:
+            epochs_no_improve += 1
+            logger.info("  No improvement (%d/%d before early stop)",
+                        epochs_no_improve, args.early_stop or args.epochs)
+
+        # ── Early stopping ────────────────────────────────────────────────────
+        if args.early_stop > 0 and epochs_no_improve >= args.early_stop:
+            logger.info(
+                "Early stopping: no improvement for %d consecutive epochs.",
+                args.early_stop,
+            )
+            break
+
+    # ═══════════════════════════════════════════════════════════════════════════
+    #  FINAL TEST EVALUATION
+    #  Always uses the BEST checkpoint, not the final epoch's weights
+    # ═══════════════════════════════════════════════════════════════════════════
+    logger.info("─" * 58)
+    logger.info("Reloading best checkpoint for final test evaluation...")
+
+    best_ckpt = torch.load(args.weights_out, map_location=device)
+    model.load_state_dict(best_ckpt["state_dict"])
+
+    test_loss, test_acc, test_sens = run_epoch(
+        model, test_loader, criterion, None, device, phase="test"
+    )
+
+    logger.info("═" * 58)
+    logger.info("  FINAL TEST RESULTS  (from epoch %d checkpoint)",
+                best_ckpt["epoch"])
+    logger.info("  Loss        : %.4f",       test_loss)
+    logger.info("  Accuracy    : %.1f%%",     test_acc  * 100)
+    logger.info("  Sensitivity : %.1f%%",     test_sens * 100)
+    logger.info("─" * 58)
+    logger.info("  Weights saved : %s",       args.weights_out)
+    logger.info("  Training log  : %s",       args.log_out)
+    logger.info("═" * 58)
+    logger.info("  Run inference:")
+    logger.info("    from model import BreastCancerInferencePipeline")
+    logger.info("    p = BreastCancerInferencePipeline('%s')", args.weights_out)
+    logger.info("    p.predict('slide.png')")
+    logger.info("═" * 58)
+
+
+# ── Entry point ───────────────────────────────────────────────────────────────
+if __name__ == "__main__":
+    main()

train_mammogram.py

@@ -0,0 +1,838 @@
+"""
+train_mammogram.py
+───────────────────
+Standalone EfficientNet-B4 mammogram training script.
+Runs on any Linux machine with a GPU — no Modal, no cloud API needed.
+
+Designed for vast.ai RTX 3090 (24GB) or any GPU with 16GB+ VRAM.
+
+Usage
+─────
+  # Full training
+  python train_mammogram.py
+
+  # Debug mode (5% data, 2 epochs)
+  python train_mammogram.py --debug
+
+  # Resume Phase 2 from Phase 1 checkpoint
+  python train_mammogram.py --skip-phase1
+
+  # Custom paths
+  python train_mammogram.py --rsna-dir /data/rsna --vindr-dir /data/vindr
+
+Setup on vast.ai
+─────────────────
+  # 1. Rent instance
+  #    GPU: RTX 3090 (24GB)  ~$0.30/hr
+  #    Disk: 500GB
+  #    Image: pytorch/pytorch:2.2.0-cuda12.1-cudnn8-runtime
+
+  # 2. SSH in and install dependencies
+  pip install pydicom pylibjpeg python-gdcm kaggle scikit-learn tqdm pandas
+
+  # 3. Set Kaggle credentials
+  mkdir -p ~/.kaggle
+  echo '{"username":"relixsx","key":"your_key"}' > ~/.kaggle/kaggle.json
+  chmod 600 ~/.kaggle/kaggle.json
+
+  # 4. Run in tmux (survives disconnection)
+  tmux new -s training
+  python train_mammogram.py
+  # Ctrl+B then D to detach — training keeps running
+  # tmux attach -t training to reconnect
+
+  # 5. When done, download weights
+  scp -P PORT root@IP:/workspace/outputs/mammogram_weights.pth ./model/
+  scp -P PORT root@IP:/workspace/outputs/mammogram_results.json ./
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import logging
+import os
+import subprocess
+import sys
+import time
+import warnings
+from pathlib import Path
+
+# Suppress pydicom deprecation warnings
+warnings.filterwarnings("ignore", category=DeprecationWarning)
+os.environ.setdefault("PYTORCH_CUDA_ALLOC_CONF", "expandable_segments:True")
+
+import numpy as np
+import pandas as pd
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from PIL import Image
+from sklearn.metrics import f1_score, roc_auc_score, confusion_matrix, roc_curve
+from sklearn.model_selection import train_test_split
+from torch.optim import AdamW
+from torch.optim.lr_scheduler import OneCycleLR
+from torch.utils.data import Dataset, DataLoader
+from torchvision import models, transforms
+from torchvision.models import EfficientNet_B4_Weights
+
+# ── Logging ────────────────────────────────────────────────────────────────────
+logging.basicConfig(
+    level   = logging.INFO,
+    format  = "%(asctime)s  %(levelname)-8s %(message)s",
+    datefmt = "%H:%M:%S",
+    handlers=[
+        logging.StreamHandler(sys.stdout),
+        logging.FileHandler("training.log"),
+    ],
+)
+logger = logging.getLogger(__name__)
+
+
+# ╔══════════════════════════════════════════════════════════════════════════════╗
+# ║  MODEL DEFINITIONS                                                          ║
+# ╚══════════════════════════════════════════════════════════════════════════════╝
+
+class FocalLoss(nn.Module):
+    def __init__(self, alpha=0.25, gamma=2.0, pos_weight=None, label_smoothing=0.1):
+        super().__init__()
+        self.alpha           = alpha
+        self.gamma           = gamma
+        self.pos_weight      = pos_weight
+        self.label_smoothing = label_smoothing
+
+    def forward(self, logits, targets):
+        ce   = F.cross_entropy(
+            logits, targets,
+            weight          = self.pos_weight,
+            label_smoothing = self.label_smoothing,
+            reduction       = "none",
+        )
+        pt   = torch.exp(-ce)
+        return (self.alpha * (1 - pt) ** self.gamma * ce).mean()
+
+
+class ViewAttentionFusion(nn.Module):
+    """Soft-attention fusion of CC and MLO view features."""
+
+    def __init__(self, dim=1792, dropout=0.2):
+        super().__init__()
+        self.gate = nn.Sequential(
+            nn.Linear(dim * 2, dim // 4),
+            nn.ReLU(inplace=True),
+            nn.Dropout(dropout),
+            nn.Linear(dim // 4, 2),
+        )
+        self.residual_w = nn.Parameter(torch.tensor(0.5))
+
+    def forward(self, cc_feat, mlo_feat):
+        weights  = torch.softmax(
+            self.gate(torch.cat([cc_feat, mlo_feat], dim=-1)), dim=-1
+        )
+        attended = weights[:, 0:1] * cc_feat + weights[:, 1:2] * mlo_feat
+        simple   = 0.5 * cc_feat + 0.5 * mlo_feat
+        w        = torch.sigmoid(self.residual_w)
+        return w * attended + (1 - w) * simple
+
+
+class MultiViewMammogramClassifier(nn.Module):
+    """Siamese EfficientNet-B4 with attention-based CC+MLO view fusion."""
+
+    def __init__(self, pretrained=True, freeze_backbone=False, dropout_rate=0.4):
+        super().__init__()
+        weights       = EfficientNet_B4_Weights.IMAGENET1K_V1 if pretrained else None
+        bb            = models.efficientnet_b4(weights=weights)
+        self.features = bb.features
+        self.avgpool  = bb.avgpool
+
+        if freeze_backbone:
+            for p in self.features.parameters():
+                p.requires_grad = False
+
+        self.fusion     = ViewAttentionFusion(dim=1792)
+        self.classifier = nn.Sequential(
+            nn.BatchNorm1d(1792),
+            nn.Dropout(dropout_rate),
+            nn.Linear(1792, 512),
+            nn.ReLU(inplace=True),
+            nn.BatchNorm1d(512),
+            nn.Dropout(dropout_rate * 0.75),
+            nn.Linear(512, 2),
+        )
+
+    def encode(self, x):
+        return torch.flatten(self.avgpool(self.features(x)), 1)
+
+    def forward(self, cc, mlo):
+        logits = self.classifier(self.fusion(self.encode(cc), self.encode(mlo)))
+        return {"logits": logits, "probs": torch.softmax(logits, 1)}
+
+    def forward_single(self, x):
+        return self.forward(x, x)
+
+
+# ╔══════════════════════════════════════════════════════════════════════════════╗
+# ║  DICOM LOADER                                                               ║
+# ╚══════════════════════════════════════════════════════════════════════════════╝
+
+def dicom_to_rgb(path: str) -> Image.Image:
+    import pydicom
+    from pydicom.pixels import apply_voi_lut
+
+    dcm = pydicom.dcmread(path)
+    try:
+        arr = apply_voi_lut(dcm.pixel_array, dcm)
+    except Exception:
+        arr = dcm.pixel_array.astype(np.float32)
+
+    arr = arr.astype(np.float32)
+    mn, mx = arr.min(), arr.max()
+    if mx > mn:
+        arr = (arr - mn) / (mx - mn) * 255.0
+    arr = arr.astype(np.uint8)
+
+    if getattr(dcm, "PhotometricInterpretation", "") == "MONOCHROME1":
+        arr = 255 - arr
+    if arr.ndim == 2:
+        arr = np.stack([arr, arr, arr], axis=-1)
+    return Image.fromarray(arr, mode="RGB")
+
+
+# ╔══════════════════════════════════════════════════════════════════════════════╗
+# ║  METRICS                                                                    ║
+# ╚══════════════════════════════════════════════════════════════════════════════╝
+
+def compute_metrics(y_true, y_prob, threshold=0.5):
+    y_true = np.array(y_true)
+    y_prob = np.array(y_prob)
+    y_pred = (y_prob >= threshold).astype(int)
+    auc    = roc_auc_score(y_true, y_prob) if len(set(y_true)) > 1 else 0.0
+    cm     = confusion_matrix(y_true, y_pred)
+    tn, fp, fn, tp = cm.ravel() if cm.size == 4 else (0, 0, 0, 0)
+    return {
+        "auc":         round(float(auc), 4),
+        "sensitivity": round(tp / max(tp + fn, 1), 4),
+        "specificity": round(tn / max(tn + fp, 1), 4),
+        "ppv":         round(tp / max(tp + fp, 1), 4),
+        "npv":         round(tn / max(tn + fn, 1), 4),
+        "accuracy":    round((tp + tn) / max(len(y_true), 1), 4),
+        "f1":          round(float(f1_score(y_true, y_pred, zero_division=0)), 4),
+        "n_pos":       int(y_true.sum()),
+        "n_neg":       int((1 - y_true).sum()),
+    }
+
+
+def youden_threshold(y_true, y_prob):
+    fpr, tpr, thr = roc_curve(y_true, y_prob)
+    return float(thr[np.argmax(tpr - fpr)])
+
+
+def bootstrap_auc_ci(y_true, y_prob, n=1000):
+    rng  = np.random.default_rng(42)
+    aucs = []
+    y_true, y_prob = np.array(y_true), np.array(y_prob)
+    for _ in range(n):
+        idx = rng.integers(0, len(y_true), len(y_true))
+        yt, yp = y_true[idx], y_prob[idx]
+        if len(set(yt)) > 1:
+            aucs.append(roc_auc_score(yt, yp))
+    return (
+        round(float(np.percentile(aucs, 2.5)), 4),
+        round(float(np.percentile(aucs, 97.5)), 4),
+    )
+
+
+# ╔══════════════════════════════════════════════════════════════════════════════╗
+# ║  DATA DOWNLOAD                                                              ║
+# ╚══════════════════════════════════════════════════════════════════════════════╝
+
+def download_rsna(rsna_dir: Path):
+    if (rsna_dir / "train.csv").exists():
+        logger.info("RSNA 2022 found in cache.")
+        return
+
+    logger.info("Downloading RSNA 2022 (~300 GB) to /tmp then unzipping...")
+    os.makedirs(str(rsna_dir), exist_ok=True)
+
+    subprocess.run([
+        "kaggle", "competitions", "download",
+        "-c", "rsna-breast-cancer-detection",
+        "-p", "/tmp",
+    ], check=True)
+
+    import glob
+    zips    = glob.glob("/tmp/*.zip")
+    tmp_zip = zips[0] if zips else "/tmp/rsna-breast-cancer-detection.zip"
+
+    logger.info("Unzipping RSNA to %s ...", rsna_dir)
+    subprocess.run(["unzip", "-q", tmp_zip, "-d", str(rsna_dir)], check=True)
+    os.remove(tmp_zip)
+    logger.info("RSNA ready.")
+
+
+def download_vindr(vindr_dir: Path, physionet_user: str, physionet_pass: str):
+    if (vindr_dir / "breast-level_annotations.csv").exists():
+        logger.info("VinDr-Mammo found in cache.")
+        return
+
+    logger.info("Downloading VinDr-Mammo from PhysioNet (~70 GB)...")
+    os.makedirs(str(vindr_dir), exist_ok=True)
+
+    # Download CSV annotations first (fast)
+    for csv_file in ["breast-level_annotations.csv", "finding_annotations.csv"]:
+        subprocess.run([
+            "wget", "-N", "-c", "-q",
+            f"--user={physionet_user}",
+            f"--password={physionet_pass}",
+            "-P", str(vindr_dir),
+            f"https://physionet.org/files/vindr-mammo/1.0.0/{csv_file}",
+        ], check=True)
+
+    # Download DICOM images — skip HTML crawling
+    subprocess.run([
+        "wget", "-r", "-N", "-c", "-np", "-q",
+        "--accept=*.dicom,*.dcm",
+        "--reject=*.html,*.php,index*,robots*",
+        f"--user={physionet_user}",
+        f"--password={physionet_pass}",
+        "-P", str(vindr_dir),
+        "https://physionet.org/files/vindr-mammo/1.0.0/images/",
+    ], check=True)
+
+    # Move from nested wget path
+    import shutil
+    nested = vindr_dir / "physionet.org" / "files" / "vindr-mammo" / "1.0.0"
+    if nested.exists():
+        for item in nested.iterdir():
+            shutil.move(str(item), str(vindr_dir / item.name))
+        shutil.rmtree(str(vindr_dir / "physionet.org"))
+
+    logger.info("VinDr-Mammo ready.")
+
+
+# ╔══════════════════════════════════════════════════════════════════════════════╗
+# ║  DATASETS                                                                   ║
+# ╚══════════════════════════════════════════════════════════════════════════════╝
+
+class MultiViewDataset(Dataset):
+    def __init__(self, cases_df, img_dir, transform, size):
+        self.cases     = cases_df.reset_index(drop=True)
+        self.img_dir   = Path(img_dir)
+        self.transform = transform
+        self.size      = size
+
+    def _load(self, patient_id, image_id):
+        path = self.img_dir / "train_images" / str(patient_id) / f"{image_id}.dcm"
+        try:
+            return dicom_to_rgb(str(path))
+        except Exception as e:
+            logger.warning("Load error %s: %s", path.name, e)
+            return Image.new("RGB", (self.size, self.size), 0)
+
+    def __len__(self):
+        return len(self.cases)
+
+    def __getitem__(self, idx):
+        row = self.cases.iloc[idx]
+        return (
+            self.transform(self._load(row["patient_id"], row["cc_img"])),
+            self.transform(self._load(row["patient_id"], row["mlo_img"])),
+            int(row["label"]),
+        )
+
+
+class VinDrDataset(Dataset):
+    def __init__(self, df, img_dir, transform):
+        self.df        = df.reset_index(drop=True)
+        self.img_dir   = Path(img_dir)
+        self.transform = transform
+
+    def __len__(self):
+        return len(self.df)
+
+    def __getitem__(self, idx):
+        row    = self.df.iloc[idx]
+        study  = str(row.get("study_id", ""))
+        img_id = str(row.get("image_id", ""))
+        label  = int(row["label"])
+        path   = None
+        for ext in [".dicom", ".dcm"]:
+            p = self.img_dir / "images" / study / f"{img_id}{ext}"
+            if p.exists():
+                path = p
+                break
+        try:
+            img = dicom_to_rgb(str(path)) if path else Image.new("RGB", (512, 512), 0)
+        except Exception:
+            img = Image.new("RGB", (512, 512), 0)
+        return self.transform(img), label
+
+
+# ╔══════════════════════════════════════════════════════════════════════════════╗
+# ║  TRANSFORMS                                                                 ║
+# ╚═════════════════════════════════════��════════════════════════════════════════╝
+
+IMGNET_MEAN = [0.485, 0.456, 0.406]
+IMGNET_STD  = [0.229, 0.224, 0.225]
+
+
+def make_train_tf(size):
+    return transforms.Compose([
+        transforms.Resize((size, size)),
+        transforms.RandomHorizontalFlip(),
+        transforms.RandomVerticalFlip(p=0.2),
+        transforms.RandomRotation(10),
+        transforms.ColorJitter(brightness=0.15, contrast=0.15),
+        transforms.RandomAffine(0, translate=(0.05, 0.05), scale=(0.95, 1.05)),
+        transforms.ToTensor(),
+        transforms.Normalize(IMGNET_MEAN, IMGNET_STD),
+    ])
+
+
+def make_val_tf(size=256):
+    return transforms.Compose([
+        transforms.Resize((size, size)),
+        transforms.ToTensor(),
+        transforms.Normalize(IMGNET_MEAN, IMGNET_STD),
+    ])
+
+
+# ╔══════════════════════════════════════════════════════════════════════════════╗
+# ║  TRAINING                                                                   ║
+# ╚══════════════════════════════════════════════════════════════════════════════╝
+
+def run_train_epoch(model, loader, criterion, optimizer, scheduler, scaler, device):
+    model.train()
+    total_loss = tp = total = pos = 0
+
+    for cc_imgs, mlo_imgs, labels in loader:
+        cc_imgs  = cc_imgs.to(device, non_blocking=True)
+        mlo_imgs = mlo_imgs.to(device, non_blocking=True)
+        labels   = labels.long().to(device, non_blocking=True)
+
+        with torch.autocast(device_type="cuda", dtype=torch.float16):
+            out  = model(cc_imgs, mlo_imgs)
+            loss = criterion(out["logits"], labels)
+
+        optimizer.zero_grad()
+        scaler.scale(loss).backward()
+        scaler.unscale_(optimizer)
+        nn.utils.clip_grad_norm_(model.parameters(), 1.0)
+        scaler.step(optimizer)
+        scaler.update()
+        scheduler.step()
+
+        preds       = out["logits"].argmax(1)
+        total      += labels.size(0)
+        total_loss += loss.item() * labels.size(0)
+        mask        = (labels == 1)
+        tp         += (preds[mask] == 1).sum().item()
+        pos        += mask.sum().item()
+
+    return total_loss / max(total, 1), tp / max(pos, 1)
+
+
+def run_eval_epoch(model, loader, device, is_multiview=True):
+    model.eval()
+    all_probs, all_labels = [], []
+
+    with torch.inference_mode():
+        for batch in loader:
+            if is_multiview:
+                cc_imgs, mlo_imgs, labels = batch
+                out = model(cc_imgs.to(device), mlo_imgs.to(device))
+            else:
+                imgs, labels = batch
+                out = model.forward_single(imgs.to(device))
+            all_probs.extend(out["probs"][:, 1].cpu().numpy().tolist())
+            all_labels.extend(labels.numpy().tolist())
+
+    return all_labels, all_probs
+
+
+def save_checkpoint(model, optimizer, epoch, metrics, path):
+    torch.save({
+        "epoch":      epoch,
+        "state_dict": model.state_dict(),
+        "optimizer":  optimizer.state_dict(),
+        "metrics":    metrics,
+    }, path)
+    logger.info("Checkpoint saved → %s", path)
+
+
+# ╔══════════════════════════════════════════════════════════════════════════════╗
+# ║  MAIN                                                                       ║
+# ╚══════════════════════════════════════════════════════════════════════════════╝
+
+def main():
+    parser = argparse.ArgumentParser(description="MedAI Mammogram Training")
+    parser.add_argument("--rsna-dir",        default="/workspace/data/rsna")
+    parser.add_argument("--vindr-dir",       default="/workspace/data/vindr")
+    parser.add_argument("--output-dir",      default="/workspace/outputs")
+    parser.add_argument("--physionet-user",  default=os.getenv("PHYSIONET_USERNAME", ""))
+    parser.add_argument("--physionet-pass",  default=os.getenv("PHYSIONET_PASSWORD", ""))
+    parser.add_argument("--phase1-epochs",   type=int,   default=5)
+    parser.add_argument("--phase2-epochs",   type=int,   default=15)
+    parser.add_argument("--batch-size",      type=int,   default=16)
+    parser.add_argument("--phase1-lr",       type=float, default=3e-4)
+    parser.add_argument("--phase2-lr",       type=float, default=5e-5)
+    parser.add_argument("--max-lr",          type=float, default=1e-3)
+    parser.add_argument("--focal-alpha",     type=float, default=0.25)
+    parser.add_argument("--focal-gamma",     type=float, default=2.0)
+    parser.add_argument("--num-workers",     type=int,   default=4)
+    parser.add_argument("--seed",            type=int,   default=42)
+    parser.add_argument("--skip-phase1",     action="store_true")
+    parser.add_argument("--debug",           action="store_true",
+                        help="Use 5% of data and 2 epochs for testing")
+    args = parser.parse_args()
+
+    # ── Setup ─────────────────────────────────────────────────────────────────
+    import random
+    random.seed(args.seed)
+    np.random.seed(args.seed)
+    torch.manual_seed(args.seed)
+
+    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    logger.info("Device: %s", device)
+    if torch.cuda.is_available():
+        torch.cuda.manual_seed_all(args.seed)
+        logger.info("GPU : %s", torch.cuda.get_device_name(0))
+        logger.info("VRAM: %.1f GB",
+                    torch.cuda.get_device_properties(0).total_memory / 1e9)
+
+    rsna_dir   = Path(args.rsna_dir)
+    vindr_dir  = Path(args.vindr_dir)
+    output_dir = Path(args.output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    logger.info("=" * 70)
+    logger.info("  EfficientNet-B4 Mammogram Training — 5 Innovations")
+    logger.info("  Train:  RSNA 2022 | External val: VinDr-Mammo")
+    logger.info("  Debug:  %s", args.debug)
+    logger.info("=" * 70)
+
+    # ── Download data ─────────────────────────────────────────────────────────
+    download_rsna(rsna_dir)
+    if args.physionet_user:
+        download_vindr(vindr_dir, args.physionet_user, args.physionet_pass)
+    else:
+        logger.warning("PHYSIONET_USERNAME not set — skipping VinDr download.")
+
+    # ── Load RSNA labels ──────────────────────────────────────────────────────
+    rsna_df = pd.read_csv(rsna_dir / "train.csv")
+    logger.info("RSNA: %d images | cancer: %.1f%%",
+                len(rsna_df), 100 * rsna_df["cancer"].mean())
+
+    if args.debug:
+        rsna_df         = rsna_df.sample(frac=0.05, random_state=args.seed).reset_index(drop=True)
+        args.phase1_epochs = min(2, args.phase1_epochs)
+        args.phase2_epochs = min(2, args.phase2_epochs)
+        logger.info("DEBUG: %d samples", len(rsna_df))
+
+    # ── Build multi-view pairs ────────────────────────────────────────────────
+    logger.info("Building multi-view pairs...")
+    cases = []
+    if "view" in rsna_df.columns and "laterality" in rsna_df.columns:
+        for (pid, lat), grp in rsna_df.groupby(["patient_id", "laterality"]):
+            cc  = grp[grp["view"] == "CC"]
+            mlo = grp[grp["view"] == "MLO"]
+            lbl = int(grp["cancer"].max())
+            if len(cc) > 0 and len(mlo) > 0:
+                cases.append({"patient_id": pid, "laterality": lat,
+                               "cc_img": cc.iloc[0]["image_id"],
+                               "mlo_img": mlo.iloc[0]["image_id"],
+                               "label": lbl})
+            else:
+                row = grp.iloc[0]
+                cases.append({"patient_id": pid, "laterality": lat,
+                               "cc_img": row["image_id"],
+                               "mlo_img": row["image_id"],
+                               "label": lbl})
+    else:
+        for _, row in rsna_df.iterrows():
+            cases.append({"patient_id": row["patient_id"],
+                          "laterality": row.get("laterality", "L"),
+                          "cc_img": row["image_id"],
+                          "mlo_img": row["image_id"],
+                          "label": int(row["cancer"])})
+
+    cases_df = pd.DataFrame(cases)
+    train_df, val_df = train_test_split(
+        cases_df, test_size=0.15, stratify=cases_df["label"], random_state=args.seed
+    )
+    logger.info("Train: %d | Val: %d", len(train_df), len(val_df))
+
+    # ── Load VinDr labels ─────────────────────────────────────────────────────
+    vindr_ext   = pd.DataFrame()
+    vindr_csv   = vindr_dir / "breast-level_annotations.csv"
+    if vindr_csv.exists():
+        vindr_df  = pd.read_csv(vindr_csv)
+        bc        = "breast_birads" if "breast_birads" in vindr_df.columns else "birads"
+        vindr_df["label"] = vindr_df[bc].map(
+            {"BI-RADS 1": 0, "BI-RADS 2": 0, "BI-RADS 4": 1, "BI-RADS 5": 1,
+             1: 0, 2: 0, 4: 1, 5: 1}
+        )
+        vindr_df  = vindr_df.dropna(subset=["label"])
+        split_col = "split" if "split" in vindr_df.columns else None
+        if split_col:
+            vindr_ext = vindr_df[vindr_df[split_col] == "test"].reset_index(drop=True)
+        else:
+            _, vindr_ext = train_test_split(
+                vindr_df, test_size=0.2, stratify=vindr_df["label"],
+                random_state=args.seed
+            )
+        logger.info("VinDr: %d images | cancer: %.1f%%",
+                    len(vindr_ext), 100 * vindr_ext["label"].mean())
+    else:
+        logger.warning("VinDr CSV not found — external validation skipped.")
+
+    # ── Class weight ──────────────────────────────────────────────────────────
+    n_pos      = int(train_df["label"].sum())
+    n_neg      = len(train_df) - n_pos
+    pos_weight = torch.tensor([n_neg / max(n_pos, 1)], device=device)
+    logger.info("Class weight: %.1f (cancer: %.1f%%)",
+                pos_weight.item(), 100 * n_pos / len(train_df))
+
+    # ── Progressive resizing schedule ─────────────────────────────────────────
+    # Phase 1: 256×256
+    # Phase 2 first third: 256×256
+    # Phase 2 second third: 384×384
+    # Phase 2 final third: 512×512 (if GPU memory allows) else 384×384
+    def get_size(epoch, phase2_epochs, is_phase2):
+        if not is_phase2:
+            return 256
+        third = phase2_epochs // 3
+        if epoch <= third:
+            return 256
+        elif epoch <= 2 * third:
+            return 384
+        return 512
+
+    val_tf_256 = make_val_tf(256)
+    val_tf_512 = make_val_tf(512)
+
+    def make_criterion():
+        return FocalLoss(
+            alpha           = args.focal_alpha,
+            gamma           = args.focal_gamma,
+            pos_weight      = torch.tensor([1.0, pos_weight.item()], device=device),
+            label_smoothing = 0.1,
+        )
+
+    # ── PHASE 1 ───────────────────────────────────────────────────────────────
+    if not args.skip_phase1:
+        logger.info("\n" + "─" * 70)
+        logger.info("  PHASE 1 — Head only, 256×256 (%d epochs)", args.phase1_epochs)
+        logger.info("─" * 70)
+
+        model     = MultiViewMammogramClassifier(pretrained=True, freeze_backbone=True).to(device)
+        criterion = make_criterion()
+        optimizer = AdamW(
+            [p for p in model.parameters() if p.requires_grad],
+            lr=args.phase1_lr, weight_decay=1e-4
+        )
+        scaler    = torch.cuda.amp.GradScaler()
+
+        train_ds     = MultiViewDataset(train_df, rsna_dir, make_train_tf(256), 256)
+        val_ds       = MultiViewDataset(val_df,   rsna_dir, val_tf_256, 256)
+        train_loader = DataLoader(train_ds, args.batch_size, True,
+                                  num_workers=args.num_workers, pin_memory=True)
+        val_loader   = DataLoader(val_ds,   args.batch_size, False,
+                                  num_workers=args.num_workers, pin_memory=True)
+
+        scheduler = OneCycleLR(
+            optimizer, max_lr=args.phase1_lr * 3,
+            steps_per_epoch=len(train_loader),
+            epochs=args.phase1_epochs, pct_start=0.3,
+        )
+
+        best_auc = 0.0
+        for epoch in range(1, args.phase1_epochs + 1):
+            t0 = time.time()
+            tr_loss, tr_sens = run_train_epoch(
+                model, train_loader, criterion, optimizer, scheduler, scaler, device
+            )
+            vl_labels, vl_probs = run_eval_epoch(model, val_loader, device)
+            vl_m = compute_metrics(vl_labels, vl_probs)
+            logger.info(
+                "P1 E%02d/%d | loss=%.4f sens=%.3f | AUC=%.4f sens=%.3f | %.0fs",
+                epoch, args.phase1_epochs, tr_loss, tr_sens,
+                vl_m["auc"], vl_m["sensitivity"], time.time() - t0,
+            )
+            if vl_m["auc"] > best_auc:
+                best_auc = vl_m["auc"]
+                save_checkpoint(model, optimizer, epoch, vl_m,
+                                output_dir / "mammogram_phase1.pth")
+
+        logger.info("Phase 1 complete. Best AUC: %.4f", best_auc)
+
+    # ── PHASE 2 ───────────────────────────────────────────────────────────────
+    logger.info("\n" + "─" * 70)
+    logger.info("  PHASE 2 — Full fine-tuning, progressive resizing (%d epochs)",
+                args.phase2_epochs)
+    logger.info("─" * 70)
+
+    model     = MultiViewMammogramClassifier(pretrained=False, freeze_backbone=False).to(device)
+    phase1_ckpt = output_dir / "mammogram_phase1.pth"
+    if phase1_ckpt.exists():
+        ckpt = torch.load(phase1_ckpt, map_location=device)
+        model.load_state_dict(ckpt["state_dict"])
+        logger.info("Loaded Phase 1 (AUC=%.4f)", ckpt["metrics"].get("auc", 0))
+
+    criterion = make_criterion()
+    optimizer = AdamW(model.parameters(), lr=args.phase2_lr, weight_decay=1e-4)
+    scaler    = torch.cuda.amp.GradScaler()
+
+    # Build val loaders
+    val_ds_256   = MultiViewDataset(val_df, rsna_dir, val_tf_256, 256)
+    val_loader   = DataLoader(val_ds_256, args.batch_size, False,
+                              num_workers=args.num_workers, pin_memory=True)
+
+    vindr_loader = None
+    if len(vindr_ext) > 0:
+        vindr_ds     = VinDrDataset(vindr_ext, vindr_dir, val_tf_256)
+        vindr_loader = DataLoader(vindr_ds, args.batch_size, False,
+                                  num_workers=args.num_workers, pin_memory=True)
+
+    # Compute total steps for scheduler
+    train_ds_tmp    = MultiViewDataset(train_df, rsna_dir, make_train_tf(256), 256)
+    tmp_loader      = DataLoader(train_ds_tmp, args.batch_size, True, num_workers=0)
+    steps_per_epoch = len(tmp_loader)
+    del tmp_loader, train_ds_tmp
+
+    scheduler = OneCycleLR(
+        optimizer, max_lr=args.max_lr,
+        steps_per_epoch=steps_per_epoch,
+        epochs=args.phase2_epochs, pct_start=0.3,
+    )
+
+    best_auc    = 0.0
+    best_epoch  = 0
+    best_thr    = 0.5
+    log_rows    = []
+    current_size = 256
+    train_loader = DataLoader(
+        MultiViewDataset(train_df, rsna_dir, make_train_tf(256), 256),
+        args.batch_size, True, num_workers=args.num_workers, pin_memory=True,
+    )
+
+    size_milestones = {
+        1:                              256,
+        args.phase2_epochs // 3 + 1:   384,
+        args.phase2_epochs * 2 // 3 + 1: 512,
+    }
+
+    for epoch in range(1, args.phase2_epochs + 1):
+        t0 = time.time()
+
+        # Progressive resizing
+        if epoch in size_milestones:
+            new_size = size_milestones[epoch]
+            if new_size != current_size:
+                current_size = new_size
+                logger.info("  → Resizing to %d×%d", current_size, current_size)
+                train_loader = DataLoader(
+                    MultiViewDataset(train_df, rsna_dir,
+                                     make_train_tf(current_size), current_size),
+                    args.batch_size, True,
+                    num_workers=args.num_workers, pin_memory=True,
+                )
+
+        tr_loss, tr_sens = run_train_epoch(
+            model, train_loader, criterion, optimizer, scheduler, scaler, device
+        )
+
+        rsna_labels, rsna_probs = run_eval_epoch(model, val_loader, device)
+        thr    = youden_threshold(rsna_labels, rsna_probs)
+        rsna_m = compute_metrics(rsna_labels, rsna_probs, thr)
+
+        vindr_str = ""
+        vindr_m   = {}
+        if vindr_loader:
+            vl, vp  = run_eval_epoch(model, vindr_loader, device, is_multiview=False)
+            vindr_m = compute_metrics(vl, vp, thr)
+            vindr_str = f" | VinDr AUC={vindr_m['auc']:.4f} sens={vindr_m['sensitivity']:.3f}"
+
+        logger.info(
+            "E%02d/%d [%3dpx] | loss=%.4f sens=%.3f | RSNA AUC=%.4f sens=%.3f%s | %.0fs",
+            epoch, args.phase2_epochs, current_size, tr_loss, tr_sens,
+            rsna_m["auc"], rsna_m["sensitivity"], vindr_str, time.time() - t0,
+        )
+
+        log_rows.append({
+            "epoch": epoch, "size": current_size,
+            "train_loss": tr_loss, "train_sens": tr_sens,
+            "rsna_auc": rsna_m["auc"], "rsna_sens": rsna_m["sensitivity"],
+            "rsna_spec": rsna_m["specificity"],
+            "vindr_auc": vindr_m.get("auc", 0),
+            "vindr_sens": vindr_m.get("sensitivity", 0),
+            "threshold": thr,
+        })
+
+        if rsna_m["auc"] > best_auc:
+            best_auc   = rsna_m["auc"]
+            best_epoch = epoch
+            best_thr   = thr
+            save_checkpoint(
+                model, optimizer, epoch,
+                {"rsna": rsna_m, "vindr": vindr_m, "threshold": thr},
+                output_dir / "mammogram_weights.pth",
+            )
+            logger.info("  ✓ Best checkpoint (AUC=%.4f)", best_auc)
+
+    # ── Final evaluation ──────────────────────────────────────────────────────
+    logger.info("\n" + "=" * 70)
+    logger.info("  FINAL EVALUATION (epoch %d)", best_epoch)
+    logger.info("=" * 70)
+
+    ckpt = torch.load(output_dir / "mammogram_weights.pth", map_location=device)
+    model.load_state_dict(ckpt["state_dict"])
+
+    rsna_l, rsna_p = run_eval_epoch(model, val_loader, device)
+    rsna_f         = compute_metrics(rsna_l, rsna_p, best_thr)
+    rsna_ci        = bootstrap_auc_ci(rsna_l, rsna_p)
+
+    logger.info("RSNA (internal): AUC=%.4f (95%% CI: %.4f–%.4f) sens=%.1f%% spec=%.1f%%",
+                rsna_f["auc"], *rsna_ci,
+                rsna_f["sensitivity"] * 100, rsna_f["specificity"] * 100)
+
+    vindr_f  = {}
+    vindr_ci = (0, 0)
+    if vindr_loader:
+        vl, vp  = run_eval_epoch(model, vindr_loader, device, is_multiview=False)
+        vindr_f = compute_metrics(vl, vp, best_thr)
+        vindr_ci = bootstrap_auc_ci(vl, vp)
+        gap      = rsna_f["auc"] - vindr_f["auc"]
+        logger.info("VinDr (external): AUC=%.4f (95%% CI: %.4f–%.4f) sens=%.1f%% spec=%.1f%%",
+                    vindr_f["auc"], *vindr_ci,
+                    vindr_f["sensitivity"] * 100, vindr_f["specificity"] * 100)
+        logger.info("Generalisation gap: %.4f  (%s)",
+                    gap,
+                    "✓ Excellent" if gap < 0.05 else "⚠ Moderate" if gap < 0.10 else "✗ Large")
+
+    # ── Save results ──────────────────────────────────────────────────────────
+    with open(output_dir / "mammogram_training_log.csv", "w", newline="") as f:
+        w = csv.DictWriter(f, fieldnames=log_rows[0].keys())
+        w.writeheader()
+        w.writerows(log_rows)
+
+    results = {
+        "best_epoch": best_epoch,
+        "threshold":  best_thr,
+        "rsna_internal":  {**rsna_f, "auc_ci": rsna_ci},
+        "vindr_external": {**vindr_f, "auc_ci": vindr_ci} if vindr_f else {},
+        "generalisation_gap": round(rsna_f["auc"] - vindr_f.get("auc", rsna_f["auc"]), 4),
+    }
+    with open(output_dir / "mammogram_results.json", "w") as f:
+        json.dump(results, f, indent=2)
+
+    logger.info("\nSaved to %s:", output_dir)
+    logger.info("  mammogram_weights.pth")
+    logger.info("  mammogram_training_log.csv")
+    logger.info("  mammogram_results.json")
+    logger.info("=" * 70)
+
+
+if __name__ == "__main__":
+    main()

utils/mammogram_preprocessing.py

@@ -0,0 +1,280 @@
+"""
+utils/mammogram_preprocessing.py
+──────────────────────────────────
+Preprocessing pipeline for full-field digital mammography (FFDM).
+
+Handles both DICOM files and standard image formats (PNG, JPG).
+Applies mammogram-specific preprocessing:
+  - VOI LUT windowing for DICOM files
+  - Breast region normalisation
+  - Grayscale to 3-channel RGB conversion
+  - Mammogram-appropriate augmentations (no stain jitter)
+
+Install
+───────
+  pip install pydicom pylibjpeg python-gdcm
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional, Union
+
+import numpy as np
+from PIL import Image
+from torchvision import transforms
+
+# DICOM support — optional import so the rest of the codebase doesn't break
+# if pydicom is not installed
+try:
+    import pydicom
+    from pydicom.pixel_data_handlers.util import apply_voi_lut
+    PYDICOM_AVAILABLE = True
+except ImportError:
+    PYDICOM_AVAILABLE = False
+
+# ── Constants ──────────────────────────────────────────────────────────────────
+MAMMOGRAM_SIZE    = 512            # EfficientNet-B4 input resolution
+IMAGENET_MEAN     = [0.485, 0.456, 0.406]
+IMAGENET_STD      = [0.229, 0.224, 0.225]
+
+
+# ── DICOM loader ───────────────────────────────────────────────────────────────
+
+def load_dicom(path: Union[str, Path]) -> Image.Image:
+    """
+    Load a DICOM mammogram file and convert to an 8-bit RGB PIL Image.
+
+    Applies VOI LUT windowing if available in the DICOM metadata,
+    otherwise falls back to min-max normalisation.
+
+    MONOCHROME1 images (where high pixel = dark) are inverted so
+    the tissue appears bright on a dark background, matching the
+    visual convention used during model training.
+
+    Parameters
+    ----------
+    path : str | Path
+        Path to a .dcm DICOM file.
+
+    Returns
+    -------
+    PIL.Image.Image  — RGB image ready for preprocessing.
+
+    Raises
+    ------
+    ImportError  — if pydicom is not installed.
+    FileNotFoundError — if the file does not exist.
+    """
+    if not PYDICOM_AVAILABLE:
+        raise ImportError(
+            "pydicom not installed. Run: pip install pydicom pylibjpeg python-gdcm"
+        )
+
+    path = Path(path)
+    if not path.exists():
+        raise FileNotFoundError(f"DICOM file not found: {path}")
+
+    dcm = pydicom.dcmread(str(path))
+
+    # Apply VOI LUT windowing (converts to display-ready values)
+    try:
+        pixel_array = apply_voi_lut(dcm.pixel_array, dcm)
+    except Exception:
+        pixel_array = dcm.pixel_array.astype(np.float32)
+
+    pixel_array = pixel_array.astype(np.float32)
+
+    # Normalise to [0, 255]
+    p_min, p_max = pixel_array.min(), pixel_array.max()
+    if p_max > p_min:
+        pixel_array = (pixel_array - p_min) / (p_max - p_min) * 255.0
+    else:
+        pixel_array = np.zeros_like(pixel_array)
+
+    pixel_array = pixel_array.astype(np.uint8)
+
+    # MONOCHROME1: invert so tissue is bright
+    if hasattr(dcm, "PhotometricInterpretation"):
+        if dcm.PhotometricInterpretation == "MONOCHROME1":
+            pixel_array = 255 - pixel_array
+
+    # Convert grayscale → RGB (EfficientNet expects 3 channels)
+    if pixel_array.ndim == 2:
+        rgb = np.stack([pixel_array, pixel_array, pixel_array], axis=-1)
+    else:
+        rgb = pixel_array
+
+    return Image.fromarray(rgb, mode="RGB")
+
+
+def load_mammogram(path: Union[str, Path]) -> Image.Image:
+    """
+    Load a mammogram from either DICOM or standard image format.
+
+    Automatically detects format by file extension.
+
+    Parameters
+    ----------
+    path : str | Path
+        Path to DICOM (.dcm) or image file (.png, .jpg, .tiff).
+
+    Returns
+    -------
+    PIL.Image.Image — RGB image.
+    """
+    path = Path(path)
+    if path.suffix.lower() in {".dcm", ".dicom"}:
+        return load_dicom(path)
+
+    # Standard image format
+    img = Image.open(path).convert("RGB")
+
+    # If grayscale was saved as single-channel PNG, already converted above.
+    # But if it's a true grayscale mammogram saved as PNG:
+    if img.mode == "L":
+        arr = np.array(img)
+        rgb = np.stack([arr, arr, arr], axis=-1)
+        return Image.fromarray(rgb, mode="RGB")
+
+    return img
+
+
+# ── Mammogram-specific augmentation transforms ──────────────────────────────────
+
+class BreastRegionEnhancer:
+    """
+    Enhances breast tissue contrast using adaptive histogram equalisation.
+
+    Applied per-channel to improve visibility of masses and calcifications
+    without affecting the overall image structure.
+
+    Parameters
+    ----------
+    clip_limit : float
+        CLAHE clip limit. Higher = more aggressive enhancement.
+    p : float
+        Probability of applying this transform.
+    """
+
+    def __init__(self, clip_limit: float = 2.0, p: float = 0.5) -> None:
+        self.clip_limit = clip_limit
+        self.p          = p
+
+    def __call__(self, img: Image.Image) -> Image.Image:
+        if np.random.random() > self.p:
+            return img
+
+        try:
+            import cv2
+            arr = np.array(img)
+            clahe = cv2.createCLAHE(
+                clipLimit    = self.clip_limit,
+                tileGridSize = (8, 8),
+            )
+            # Apply CLAHE to each channel
+            enhanced = np.stack(
+                [clahe.apply(arr[:, :, c]) for c in range(arr.shape[2])],
+                axis=-1,
+            )
+            return Image.fromarray(enhanced.astype(np.uint8), mode="RGB")
+        except ImportError:
+            return img   # OpenCV not available — skip silently
+
+
+class RandomElasticDeformation:
+    """
+    Random elastic deformation — simulates tissue compression variation
+    from different mammography unit pressures.
+
+    Parameters
+    ----------
+    alpha : float
+        Strength of deformation.
+    sigma : float
+        Smoothness of deformation field.
+    p : float
+        Probability of applying.
+    """
+
+    def __init__(
+        self,
+        alpha: float = 34.0,
+        sigma: float = 4.0,
+        p:     float = 0.3,
+    ) -> None:
+        self.alpha = alpha
+        self.sigma = sigma
+        self.p     = p
+
+    def __call__(self, img: Image.Image) -> Image.Image:
+        if np.random.random() > self.p:
+            return img
+
+        try:
+            from scipy.ndimage import gaussian_filter, map_coordinates
+
+            arr    = np.array(img, dtype=np.float32)
+            h, w   = arr.shape[:2]
+            dx     = gaussian_filter(
+                (np.random.rand(h, w) * 2 - 1) * self.alpha, self.sigma
+            )
+            dy     = gaussian_filter(
+                (np.random.rand(h, w) * 2 - 1) * self.alpha, self.sigma
+            )
+            x, y   = np.meshgrid(np.arange(w), np.arange(h))
+            coords = [
+                np.clip(y + dy, 0, h - 1).ravel(),
+                np.clip(x + dx, 0, w - 1).ravel(),
+            ]
+
+            result = np.stack([
+                map_coordinates(arr[:, :, c], coords, order=1).reshape(h, w)
+                for c in range(arr.shape[2])
+            ], axis=-1)
+
+            return Image.fromarray(result.clip(0, 255).astype(np.uint8), mode="RGB")
+        except ImportError:
+            return img   # scipy not available — skip
+
+
+def build_mammogram_train_transform() -> transforms.Compose:
+    """
+    Training augmentation pipeline for mammograms.
+
+    Mammogram-appropriate augmentations — NO stain jitter (mammograms
+    are X-ray images, not H&E-stained tissue). Augmentations simulate:
+    - Different patient positioning (flips, rotation)
+    - Tissue compression variation (elastic deformation)
+    - Scanner variation (brightness/contrast)
+    - Tissue contrast differences (CLAHE)
+    """
+    return transforms.Compose([
+        BreastRegionEnhancer(clip_limit=2.0, p=0.4),
+        RandomElasticDeformation(alpha=34.0, sigma=4.0, p=0.3),
+        transforms.Resize((MAMMOGRAM_SIZE, MAMMOGRAM_SIZE)),
+        transforms.RandomHorizontalFlip(p=0.5),
+        transforms.RandomVerticalFlip(p=0.2),
+        transforms.RandomRotation(degrees=10),
+        transforms.ColorJitter(
+            brightness = 0.15,
+            contrast   = 0.15,
+        ),
+        transforms.RandomAffine(
+            degrees    = 0,
+            translate  = (0.05, 0.05),
+            scale      = (0.95, 1.05),
+        ),
+        transforms.ToTensor(),
+        transforms.Normalize(IMAGENET_MEAN, IMAGENET_STD),
+    ])
+
+
+def build_mammogram_inference_transform() -> transforms.Compose:
+    """
+    Inference transform — resize and normalise only. No augmentation."""
+    return transforms.Compose([
+        transforms.Resize((MAMMOGRAM_SIZE, MAMMOGRAM_SIZE)),
+        transforms.ToTensor(),
+        transforms.Normalize(IMAGENET_MEAN, IMAGENET_STD),
+    ])

utils/preprocessing.py

@@ -0,0 +1,211 @@
+"""
+utils/preprocessing.py
+───────────────────────
+Image preprocessing pipeline that converts a raw histopathology image
+(file path, PIL Image, or numpy array) into a normalised tensor of
+shape (1, 3, 224, 224) ready for model inference.
+
+Normalization follows ImageNet standards as required by the spec:
+    Mean : [0.485, 0.456, 0.406]
+    Std  : [0.229, 0.224, 0.225]
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Union
+
+import numpy as np
+import torch
+from PIL import Image
+from torchvision import transforms
+
+# ── ImageNet normalization constants ────────────────────────────────────────
+IMAGENET_MEAN = [0.485, 0.456, 0.406]
+IMAGENET_STD  = [0.229, 0.224, 0.225]
+
+# ── Target tensor shape ─────────────────────────────────────────────────────
+TARGET_SIZE = (224, 224)
+
+
+# ── Transform pipeline ───────────────────────────────────────────────────────
+def build_inference_transform() -> transforms.Compose:
+    """
+    Returns the deterministic inference transform pipeline.
+
+    Steps
+    ─────
+    1. Resize shortest edge to 256 px (preserves aspect ratio).
+    2. Centre-crop to 224 × 224.
+    3. Convert PIL image to float32 tensor in [0, 1].
+    4. Normalize with ImageNet mean / std.
+    """
+    return transforms.Compose([
+        transforms.Resize(256, interpolation=transforms.InterpolationMode.BICUBIC),
+        transforms.CenterCrop(TARGET_SIZE),
+        transforms.ToTensor(),                          # → [0, 1]
+        transforms.Normalize(IMAGENET_MEAN, IMAGENET_STD),
+    ])
+
+
+
+
+# ── StainJitter — Fix 1 ──────────────────────────────────────────────────────
+class StainJitter:
+    """
+    Randomly perturb H&E stain concentrations in HED colour space.
+
+    Why this works
+    ──────────────
+    H&E-stained slides vary in colour between labs due to differences in
+    staining batches, fixation protocols, and scanner calibrations.
+    Standard RGB colour jitter doesn't model this — it shifts all three
+    channels independently. StainJitter works in HED space (Haematoxylin,
+    Eosin, DAB), which directly corresponds to the actual stains in the tissue.
+    Perturbing HED channels simulates real-world staining variation without
+    needing a reference image or external library.
+
+    Implementation
+    ──────────────
+    Uses the Ruifrok & Johnston HED deconvolution matrix to decompose
+    RGB into stain concentrations, perturbs each channel with a random
+    scale (alpha) and shift (beta), then reconstructs the RGB image.
+    Pure NumPy — no external dependencies beyond what is already installed.
+
+    Parameters
+    ----------
+    strength : float
+        Controls the magnitude of perturbation.
+        0.05 = ±5% scale variation + ±5% shift variation per channel.
+        Typical values: 0.03 (subtle) to 0.10 (aggressive).
+    p : float
+        Probability of applying the transform. Default 0.5.
+    """
+
+    # Ruifrok & Johnston HED deconvolution matrix
+    # Rows = [Haematoxylin, Eosin, DAB] stain absorption vectors
+    HED = np.array([
+        [0.6500286,  0.7044536,  0.2860126],
+        [0.7044522,  0.4956977,  0.5079795],
+        [0.2860126,  0.5079795,  0.8128560],
+    ], dtype=np.float64)
+
+    # Pre-compute inverse once at class level
+    HED_INV = np.linalg.inv(HED)
+
+    def __init__(self, strength: float = 0.05, p: float = 0.5) -> None:
+        self.strength = strength
+        self.p        = p
+
+    def __call__(self, img: "Image.Image") -> "Image.Image":
+        if np.random.random() > self.p:
+            return img
+
+        # PIL → float64 numpy in [0, 1]
+        rgb = np.array(img, dtype=np.float64) / 255.0
+
+        # Convert to optical density — Beer-Lambert law
+        # Clamp to avoid log(0)
+        od = -np.log(np.clip(rgb, 1e-6, 1.0))
+
+        # Decompose into HED stain concentrations
+        # od = concentrations @ HED  →  concentrations = od @ HED_INV
+        hed = od @ self.HED_INV                      # (H, W, 3) HED concentrations
+
+        # Perturb each stain channel independently
+        alpha = np.random.uniform(
+            1.0 - self.strength,
+            1.0 + self.strength,
+            size=(1, 1, 3),
+        )
+        beta = np.random.uniform(
+            -self.strength,
+            +self.strength,
+            size=(1, 1, 3),
+        )
+        hed_perturbed = hed * alpha + beta
+
+        # Reconstruct optical density then RGB
+        od_reconstructed = hed_perturbed @ self.HED
+        rgb_out = np.exp(-od_reconstructed)
+        rgb_out = np.clip(rgb_out, 0.0, 1.0)
+
+        return Image.fromarray((rgb_out * 255).astype(np.uint8), mode="RGB")
+
+def build_training_transform() -> transforms.Compose:
+    """
+    Augmentation pipeline for fine-tuning.
+    Included for completeness; inference always uses build_inference_transform().
+    """
+    return transforms.Compose([
+        StainJitter(strength=0.05, p=0.5),           # Fix 1: H&E stain augmentation
+        transforms.RandomResizedCrop(TARGET_SIZE, scale=(0.8, 1.0)),
+        transforms.RandomHorizontalFlip(),
+        transforms.RandomVerticalFlip(),
+        transforms.ColorJitter(brightness=0.2, contrast=0.2,
+                               saturation=0.1),
+        transforms.RandomRotation(degrees=15),
+        transforms.ToTensor(),
+        transforms.Normalize(IMAGENET_MEAN, IMAGENET_STD),
+    ])
+
+
+# ── Preprocessing entry point ────────────────────────────────────────────────
+class ImagePreprocessor:
+    """
+    Accepts multiple input types and returns a (1, 3, 224, 224) tensor.
+
+    Supported inputs
+    ────────────────
+    - str / pathlib.Path  : local file path to PNG / JPG / TIFF
+    - PIL.Image.Image     : already-loaded PIL image
+    - np.ndarray          : HxWx3 uint8 or float32 array
+    - torch.Tensor        : CxHxW or 1xCxHxW (skips PIL stage)
+    """
+
+    def __init__(self) -> None:
+        self._transform = build_inference_transform()
+
+    def __call__(
+        self,
+        image: Union[str, Path, "Image.Image", np.ndarray, torch.Tensor],
+    ) -> torch.Tensor:
+        """
+        Parameters
+        ----------
+        image : see supported inputs above
+
+        Returns
+        -------
+        torch.Tensor
+            Shape (1, 3, 224, 224), dtype float32, ImageNet-normalised.
+        """
+        pil_image = self._to_pil(image)
+        tensor    = self._transform(pil_image)   # (3, 224, 224)
+        return tensor.unsqueeze(0)               # (1, 3, 224, 224)
+
+    # ── Type dispatch helpers ────────────────────────────────────────────────
+    @staticmethod
+    def _to_pil(image) -> "Image.Image":
+        if isinstance(image, (str, Path)):
+            return Image.open(image).convert("RGB")
+
+        if isinstance(image, Image.Image):
+            return image.convert("RGB")
+
+        if isinstance(image, np.ndarray):
+            if image.dtype != np.uint8:
+                image = (np.clip(image, 0, 1) * 255).astype(np.uint8)
+            if image.ndim == 2:
+                image = np.stack([image] * 3, axis=-1)  # grayscale → RGB
+            return Image.fromarray(image, mode="RGB")
+
+        if isinstance(image, torch.Tensor):
+            t   = image.squeeze(0) if image.ndim == 4 else image
+            arr = (t.permute(1, 2, 0).cpu().numpy() * 255).astype(np.uint8)
+            return Image.fromarray(arr, mode="RGB")
+
+        raise TypeError(
+            f"Unsupported image type: {type(image)}. "
+            "Expected str, Path, PIL.Image, np.ndarray, or torch.Tensor."
+        )