Upload folder using huggingface_hub

.gitattributes

@@ -1,35 +1,4 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
 *.pt filter=lfs diff=lfs merge=lfs -text
 *.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
 *.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+.venv/
+.env
+.DS_Store
+.ipynb_checkpoints/

DEPLOYMENT_INSTRUCTIONS.md

@@ -0,0 +1,216 @@
+# Deployment instructions: Hugging Face Space MRI ensemble
+
+This is a fresh Hugging Face Space bundle. It is not a patch of the earlier bundle.
+
+The app expects all model checkpoints to live in exactly one folder:
+
+```text
+models/
+```
+
+## 1. Required checkpoint files
+
+Place these three files in the `models/` folder:
+
+```text
+models/best_efficientnet_b0_seed123.pt
+models/best_efficientnet_b0_seed2026.pt
+models/best_mobilenet_v3_small_seed42.pt
+```
+
+These correspond to the non-zero-weight members of the selected ensemble:
+
+| Member | Ensemble weight |
+|---|---:|
+| EfficientNet-B0 seed 123 | `0.49513684` |
+| EfficientNet-B0 seed 2026 | `0.35077890` |
+| MobileNetV3-Small seed 42 | `0.15408426` |
+
+Do not add the zero-weight selected members unless you modify the app. They do not affect inference.
+
+## 2. Folder structure to upload
+
+Your final Space repo should look like this:
+
+```text
+.
+├── app.py
+├── README.md
+├── requirements.txt
+├── DEPLOYMENT_INSTRUCTIONS.md
+├── validate_bundle.py
+├── .gitattributes
+├── src/
+│   ├── __init__.py
+│   ├── config.py
+│   └── modeling.py
+├── results/
+│   ├── selected_ensemble.json
+│   ├── deployed_members.csv
+│   ├── selected_metrics.csv
+│   ├── cm_ensemble_lightweight_effnet_mobilenet_optimized_val_ce_weighted_soft.csv
+│   ├── classification_report_ensemble_lightweight_effnet_mobilenet_optimized_val_ce_weighted_soft.json
+│   ├── ensemble_fusion_ablation_results.csv
+│   └── single_checkpoint_results.csv
+└── models/
+    ├── README.md
+    ├── best_efficientnet_b0_seed123.pt
+    ├── best_efficientnet_b0_seed2026.pt
+    └── best_mobilenet_v3_small_seed42.pt
+```
+
+## 3. Local test before upload
+
+From the bundle folder:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install --upgrade pip
+pip install -r requirements.txt
+python validate_bundle.py
+python app.py
+```
+
+Open the local Gradio URL shown in the terminal. Go to **Model status** and click **Test-load ensemble**.
+
+If checkpoint files are not present yet, `validate_bundle.py` will warn you but still validate the source files. The Space will not run real inference until the checkpoints are present.
+
+## 4. Create the Hugging Face Space
+
+1. Go to Hugging Face.
+2. Create a new Space.
+3. Select **Gradio** as the SDK.
+4. Use the files in this bundle as the root of the Space repo.
+5. Keep `README.md` at the repo root because the Space config is in the YAML block at the top of that file.
+
+## 5. Upload using Git
+
+Install Git LFS once:
+
+```bash
+git lfs install
+```
+
+Clone your Space:
+
+```bash
+git clone https://huggingface.co/spaces/<your-username>/<your-space-name>
+cd <your-space-name>
+```
+
+Copy the bundle into the repo. Then copy the three checkpoint files into `models/`.
+
+Track large checkpoints with LFS:
+
+```bash
+git lfs track "*.pt"
+git lfs track "*.pth"
+git lfs track "*.ckpt"
+git lfs track "*.safetensors"
+```
+
+Commit and push:
+
+```bash
+git add .gitattributes .
+git commit -m "Deploy MRI ensemble Space"
+git push
+```
+
+## 6. Upload using the web interface
+
+If you prefer the browser UI:
+
+1. Upload all code files and folders from this bundle.
+2. Create or open the `models/` folder.
+3. Upload the three `.pt` files into `models/`.
+4. Confirm the filenames match exactly.
+5. Wait for the Space to rebuild.
+6. Open the **Model status** tab and click **Test-load ensemble**.
+
+For large files, Git + Git LFS is usually more reliable than the browser uploader.
+
+## 7. After deployment: checks to run
+
+Open the Space and run these checks:
+
+1. **Model status** tab shows all three checkpoints as found.
+2. **Test-load ensemble** returns a success message.
+3. Upload a sample MRI image.
+4. Run prediction with heatmap **off** first.
+5. Then try heatmap **on**. Heatmap generation can be slow on CPU.
+
+## 8. Common errors
+
+### Error: missing checkpoint
+
+Make sure the files are in `models/`, not the repo root or another folder.
+
+Correct:
+
+```text
+models/best_efficientnet_b0_seed123.pt
+```
+
+Incorrect:
+
+```text
+best_efficientnet_b0_seed123.pt
+checkpoints/best_efficientnet_b0_seed123.pt
+model/best_efficientnet_b0_seed123.pt
+```
+
+### Error: filename mismatch
+
+The app expects exact filenames. Rename your files if necessary.
+
+### Error: size mismatch during model loading
+
+This usually means the checkpoint does not match the deployed architecture or class count. The app expects:
+
+```text
+EfficientNet-B0 with 4 output classes
+EfficientNet-B0 with 4 output classes
+MobileNetV3-Small with 4 output classes
+```
+
+Class order:
+
+```text
+glioma, meningioma, notumor, pituitary
+```
+
+### Error: Space runs out of memory
+
+Use CPU Upgrade or a small GPU hardware tier. The app loads two EfficientNet-B0 models and one MobileNetV3-Small model. CPU Basic may work, but startup and heatmaps can be slow.
+
+### Error: heatmap fails but prediction works
+
+The heatmap is optional interpretability support. Leave the heatmap checkbox off if CPU performance is poor. Prediction does not depend on heatmap generation.
+
+## 9. Customization
+
+### Change checkpoint names
+
+Edit `src/config.py`:
+
+```python
+ENSEMBLE_MEMBERS = [...]
+```
+
+Update `checkpoint_file` values only if your filenames are different.
+
+### Disable strict checkpoint loading
+
+By default, checkpoint loading is strict. To loosen loading, set this Space environment variable:
+
+```text
+STRICT_CHECKPOINT_LOADING=false
+```
+
+Use this only for debugging. For research reproducibility, strict loading is better.
+
+## 10. Important research caution
+
+The reported metrics come from the provided experiment outputs. They do not prove clinical readiness. External validation, calibration review, scanner/protocol shift testing, patient-level leakage checks, bias checks, and clinical governance are still required before any medical use.

README.md

@@ -1,13 +1,67 @@
 ---
-title: LCVC DeepFuse
-emoji: 🦀
-colorFrom: purple
-colorTo: purple
+title: Brain MRI Ensemble Classifier
+emoji: 🧠
+colorFrom: indigo
+colorTo: blue
 sdk: gradio
-sdk_version: 6.14.0
-python_version: '3.13'
+sdk_version: 5.49.1
+python_version: 3.10
 app_file: app.py
 pinned: false
+short_description: Weighted-soft EfficientNet/MobileNet MRI ensemble demo
+suggested_hardware: cpu-upgrade
+tags:
+  - medical-imaging
+  - mri
+  - image-classification
+  - gradio
+  - pytorch
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Brain MRI Ensemble Classifier
+
+This Hugging Face Space deploys the selected ensemble from the MRI backbone/ensemble research notebooks.
+
+## Selected deployment ensemble
+
+**Pool:** `lightweight_effnet_mobilenet`  
+**Fusion:** `optimized_val_ce_weighted_soft`  
+**Classes:** `glioma`, `meningioma`, `notumor`, `pituitary`
+
+Only non-zero-weight members are deployed:
+
+| Member | Weight | Checkpoint required in `models/` |
+|---|---:|---|
+| EfficientNet-B0 seed 123 | `0.49513684` | `best_efficientnet_b0_seed123.pt` |
+| EfficientNet-B0 seed 2026 | `0.35077890` | `best_efficientnet_b0_seed2026.pt` |
+| MobileNetV3-Small seed 42 | `0.15408426` | `best_mobilenet_v3_small_seed42.pt` |
+
+Zero-weight members from the optimization result are intentionally omitted because they do not change weighted-soft inference.
+
+## Reported research metrics
+
+| Metric | Value |
+|---|---:|
+| Validation Macro-F1 | `0.994487` |
+| Test accuracy | `0.990637` |
+| Test Macro-F1 | `0.990633` |
+| Test balanced accuracy | `0.990640` |
+| Test macro AUC OVR | `0.999339` |
+| Test ECE | `0.008194` |
+
+## Checkpoint placement
+
+Put all required checkpoint files in:
+
+```text
+models/
+├── best_efficientnet_b0_seed123.pt
+├── best_efficientnet_b0_seed2026.pt
+└── best_mobilenet_v3_small_seed42.pt
+```
+
+The app intentionally looks in `models/` only, so deployment remains simple and reproducible.
+
+## Medical disclaimer
+
+This Space is a research prototype and is not a medical device. It must not be used for diagnosis, treatment, or patient triage.

app.py

@@ -0,0 +1,337 @@
+from __future__ import annotations
+
+import traceback
+
+import gradio as gr
+import matplotlib.pyplot as plt
+import pandas as pd
+from PIL import Image
+
+from src.config import CLASS_DISPLAY_NAMES, CLASS_NAMES, ENSEMBLE_MEMBERS
+from src.modeling import diagnose_checkpoints, load_ensemble, predict, weighted_ensemble_cam
+
+
+DISCLAIMER = """
+<div class="notice">
+  <b>Research prototype only.</b> This Space is for demonstrating a trained MRI image classifier from the submitted research workflow. It is not a medical device and must not be used for diagnosis, treatment, or patient triage.
+</div>
+"""
+
+
+CUSTOM_CSS = """
+:root {
+  --radius-xl: 26px;
+  --radius-lg: 18px;
+  --glass: rgba(255,255,255,0.80);
+  --stroke: rgba(148,163,184,0.28);
+  --shadow: 0 18px 60px rgba(15, 23, 42, .16);
+}
+.gradio-container {
+  max-width: 1220px !important;
+  margin: auto !important;
+  background:
+    radial-gradient(circle at 10% 8%, rgba(99,102,241,.18), transparent 30%),
+    radial-gradient(circle at 90% 0%, rgba(14,165,233,.17), transparent 28%),
+    linear-gradient(180deg, #f8fafc 0%, #eef2ff 52%, #f8fafc 100%) !important;
+  font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif !important;
+}
+.hero {
+  padding: 34px 36px;
+  border-radius: var(--radius-xl);
+  background: linear-gradient(135deg, rgba(15,23,42,.96), rgba(30,64,175,.88) 52%, rgba(2,132,199,.84));
+  color: white;
+  box-shadow: var(--shadow);
+  border: 1px solid rgba(255,255,255,.16);
+  margin-bottom: 20px;
+}
+.hero h1 {
+  margin: 0 0 10px 0 !important;
+  font-size: clamp(2rem, 5vw, 3.8rem) !important;
+  line-height: 1.02 !important;
+  letter-spacing: -0.05em !important;
+}
+.hero p {
+  font-size: 1.02rem;
+  color: rgba(255,255,255,.86);
+  max-width: 880px;
+  margin: 0;
+}
+.badges {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 10px;
+  margin-top: 20px;
+}
+.badge {
+  border: 1px solid rgba(255,255,255,.22);
+  background: rgba(255,255,255,.12);
+  color: #fff;
+  padding: 8px 12px;
+  border-radius: 999px;
+  font-weight: 650;
+  font-size: .88rem;
+}
+.notice {
+  padding: 14px 16px;
+  border-radius: 16px;
+  background: rgba(254, 243, 199, .82);
+  border: 1px solid rgba(245, 158, 11, .34);
+  color: #78350f;
+  margin: 10px 0 18px 0;
+}
+.result-card {
+  padding: 22px;
+  border-radius: var(--radius-xl);
+  background: var(--glass);
+  border: 1px solid var(--stroke);
+  box-shadow: 0 14px 44px rgba(15,23,42,.11);
+  backdrop-filter: blur(12px);
+}
+.pred-title {
+  font-size: 1.05rem;
+  text-transform: uppercase;
+  letter-spacing: .08em;
+  color: #475569;
+  font-weight: 800;
+  margin-bottom: 4px;
+}
+.pred-label {
+  font-size: clamp(2rem, 4vw, 3.4rem);
+  line-height: 1;
+  font-weight: 900;
+  letter-spacing: -0.045em;
+  color: #0f172a;
+}
+.pred-sub {
+  margin-top: 12px;
+  color: #475569;
+  font-size: 1rem;
+}
+.metric-grid {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 12px;
+  margin-top: 18px;
+}
+.metric {
+  padding: 14px;
+  border-radius: 16px;
+  background: rgba(255,255,255,.76);
+  border: 1px solid rgba(148,163,184,.28);
+}
+.metric .k { color: #64748b; font-size: .8rem; font-weight: 800; text-transform: uppercase; letter-spacing: .07em; }
+.metric .v { color: #0f172a; font-size: 1.35rem; font-weight: 900; margin-top: 4px; }
+.status-good { color: #166534; font-weight: 800; }
+.status-bad { color: #991b1b; font-weight: 800; }
+.footer-note { color: #64748b; font-size: .92rem; }
+button.primary, .primary button {
+  border-radius: 16px !important;
+  font-weight: 850 !important;
+}
+.block, .form, .panel, .tabitem, .gr-box {
+  border-radius: 18px !important;
+}
+@media (max-width: 800px) {
+  .hero { padding: 24px 20px; }
+  .metric-grid { grid-template-columns: 1fr; }
+}
+"""
+
+
+HERO_HTML = """
+<div class="hero">
+  <h1>Brain MRI Ensemble Classifier</h1>
+  <p>Upload a brain MRI image and run the selected lightweight weighted-soft ensemble from the research notebook: EfficientNet-B0 + MobileNetV3-Small.</p>
+  <div class="badges">
+    <span class="badge">4 classes</span>
+    <span class="badge">Weighted soft voting</span>
+    <span class="badge">EfficientNet-B0</span>
+    <span class="badge">MobileNetV3-Small</span>
+    <span class="badge">Optional heatmap</span>
+  </div>
+</div>
+"""
+
+
+def _status_markdown() -> str:
+    ok, _df, message = diagnose_checkpoints()
+    cls = "status-good" if ok else "status-bad"
+    return f"<div class='{cls}'>{message}</div>"
+
+
+def _model_table() -> pd.DataFrame:
+    _ok, df, _message = diagnose_checkpoints()
+    return df
+
+
+def _research_metrics_table() -> pd.DataFrame:
+    return pd.DataFrame(
+        [
+            {"metric": "Validation Macro-F1", "value": "0.994487"},
+            {"metric": "Test Accuracy", "value": "0.990637"},
+            {"metric": "Test Macro-F1", "value": "0.990633"},
+            {"metric": "Test Balanced Accuracy", "value": "0.990640"},
+            {"metric": "Test Macro AUC OVR", "value": "0.999339"},
+            {"metric": "Test ECE", "value": "0.008194"},
+        ]
+    )
+
+
+def _deployed_members_table() -> pd.DataFrame:
+    rows = []
+    for m in ENSEMBLE_MEMBERS:
+        rows.append(
+            {
+                "member": m["display_name"],
+                "weight": f"{m['weight']:.8f}",
+                "checkpoint": f"models/{m['checkpoint_file']}",
+            }
+        )
+    return pd.DataFrame(rows)
+
+
+def _probability_plot(prob_df: pd.DataFrame):
+    fig, ax = plt.subplots(figsize=(7.5, 4.2))
+    labels = prob_df["class"].tolist()[::-1]
+    values = prob_df["probability"].tolist()[::-1]
+    ax.barh(labels, values)
+    ax.set_xlim(0, 1)
+    ax.set_xlabel("Probability")
+    ax.set_title("Ensemble class probabilities")
+    ax.grid(axis="x", alpha=0.28)
+    for idx, value in enumerate(values):
+        ax.text(min(value + 0.015, 0.98), idx, f"{value*100:.1f}%", va="center", fontweight="bold")
+    fig.tight_layout()
+    return fig
+
+
+def _prediction_card(label: str, confidence: float, image: Image.Image, heatmap_enabled: bool) -> str:
+    width, height = image.size if image is not None else (0, 0)
+    heatmap_text = "Generated" if heatmap_enabled else "Off"
+    return f"""
+    <div class="result-card">
+      <div class="pred-title">Top prediction</div>
+      <div class="pred-label">{label}</div>
+      <div class="pred-sub">Weighted-soft ensemble confidence: <b>{confidence*100:.2f}%</b></div>
+      <div class="metric-grid">
+        <div class="metric"><div class="k">Input size</div><div class="v">{width}×{height}</div></div>
+        <div class="metric"><div class="k">Model votes</div><div class="v">3</div></div>
+        <div class="metric"><div class="k">Heatmap</div><div class="v">{heatmap_text}</div></div>
+      </div>
+    </div>
+    """
+
+
+def run_prediction(image: Image.Image, make_heatmap: bool):
+    if image is None:
+        raise gr.Error("Upload an MRI image first.")
+
+    try:
+        result = predict(image)
+        prob_df = result.probability_df.copy()
+        prob_df["probability"] = prob_df["probability"].map(lambda x: round(float(x), 6))
+        plot = _probability_plot(result.probability_df)
+        heatmap = None
+        if make_heatmap:
+            heatmap = weighted_ensemble_cam(image, result.predicted_class)
+        card = _prediction_card(result.predicted_display, result.confidence, image, make_heatmap and heatmap is not None)
+        return card, prob_df, result.member_df, plot, heatmap
+    except FileNotFoundError as exc:
+        raise gr.Error(str(exc)) from exc
+    except Exception as exc:
+        detail = traceback.format_exc(limit=3)
+        raise gr.Error(f"Prediction failed: {exc}\n\n{detail}") from exc
+
+
+def warmup_status() -> str:
+    ok, _df, message = diagnose_checkpoints()
+    if not ok:
+        return message
+    try:
+        # Load once so the first user prediction is faster.
+        load_ensemble()
+        return "✅ Checkpoints found and ensemble loaded successfully."
+    except Exception as exc:
+        return f"❌ Checkpoints were found, but model loading failed: {exc}"
+
+
+with gr.Blocks(css=CUSTOM_CSS, theme=gr.themes.Soft(primary_hue="indigo", secondary_hue="sky"), title="MRI Ensemble Classifier") as demo:
+    gr.HTML(HERO_HTML)
+    gr.HTML(DISCLAIMER)
+
+    with gr.Tabs():
+        with gr.Tab("Predict"):
+            with gr.Row(equal_height=False):
+                with gr.Column(scale=5):
+                    image_input = gr.Image(
+                        label="Upload MRI image",
+                        type="pil",
+                        height=390,
+                        sources=["upload", "clipboard"],
+                    )
+                    with gr.Row():
+                        heatmap_toggle = gr.Checkbox(
+                            value=False,
+                            label="Generate ensemble heatmap",
+                            info="Slower on CPU. Use after the basic prediction works.",
+                        )
+                        run_button = gr.Button("Run ensemble prediction", variant="primary", elem_classes="primary")
+                with gr.Column(scale=7):
+                    prediction_html = gr.HTML(
+                        "<div class='result-card'><div class='pred-title'>Waiting for image</div><div class='pred-label'>—</div><div class='pred-sub'>Upload an MRI image and run the selected ensemble.</div></div>",
+                        label="Prediction",
+                    )
+                    probabilities_output = gr.Dataframe(
+                        label="Class probabilities",
+                        headers=["class", "probability", "percent"],
+                        interactive=False,
+                    )
+            with gr.Row():
+                probability_plot = gr.Plot(label="Probability chart")
+                heatmap_output = gr.Image(label="Optional ensemble heatmap", type="pil")
+            member_output = gr.Dataframe(label="Per-member predictions", interactive=False)
+
+            run_button.click(
+                fn=run_prediction,
+                inputs=[image_input, heatmap_toggle],
+                outputs=[prediction_html, probabilities_output, member_output, probability_plot, heatmap_output],
+            )
+
+        with gr.Tab("Model status"):
+            gr.Markdown("### Checkpoint status")
+            status_md = gr.Markdown(_status_markdown())
+            status_table = gr.Dataframe(value=_model_table(), interactive=False, label="Required files")
+            refresh_btn = gr.Button("Refresh status")
+            load_btn = gr.Button("Test-load ensemble", variant="secondary")
+            load_status = gr.Textbox(label="Load result", interactive=False)
+            refresh_btn.click(fn=_status_markdown, inputs=None, outputs=status_md)
+            refresh_btn.click(fn=_model_table, inputs=None, outputs=status_table)
+            load_btn.click(fn=warmup_status, inputs=None, outputs=load_status)
+
+        with gr.Tab("Research summary"):
+            gr.Markdown(
+                """
+### Selected ensemble
+
+The deployed model is the selected **`lightweight_effnet_mobilenet | optimized_val_ce_weighted_soft`** ensemble. It uses only the non-zero-weight members from the ablation result. The zero-weight EfficientNet/MobileNet members are not loaded because they do not affect weighted-soft inference.
+
+Class order used at inference: **glioma, meningioma, notumor, pituitary**.
+                """
+            )
+            gr.Dataframe(value=_deployed_members_table(), label="Deployed members", interactive=False)
+            gr.Dataframe(value=_research_metrics_table(), label="Reported evaluation metrics", interactive=False)
+            gr.Markdown(
+                """
+### Practical interpretation
+
+High validation/test scores from the research split do not make this a clinical diagnostic tool. Before any real-world medical use, the model would need independent external validation, bias checks, clinical review, calibration review, privacy/security review, and regulatory evaluation.
+                """
+            )
+
+    gr.Markdown(
+        "<div class='footer-note'>Built for Hugging Face Spaces with Gradio. Put all required checkpoint files inside the repository's <code>models/</code> folder.</div>"
+    )
+
+
+if __name__ == "__main__":
+    demo.queue(max_size=16).launch()

models/README.md

@@ -0,0 +1,17 @@
+# Model checkpoint folder
+
+Place the three required checkpoint files in this folder before running the Space:
+
+```text
+models/best_efficientnet_b0_seed123.pt
+models/best_efficientnet_b0_seed2026.pt
+models/best_mobilenet_v3_small_seed42.pt
+```
+
+These are the non-zero-weight members of the selected ensemble:
+
+```text
+lightweight_effnet_mobilenet | optimized_val_ce_weighted_soft
+```
+
+The app does not search other folders by design. This prevents accidentally loading the wrong checkpoint when multiple experiments are present.

models/best_efficientnet_b0_seed123.pt

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

models/best_efficientnet_b0_seed2026.pt

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

models/best_mobilenet_v3_small_seed42.pt

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

requirements.txt

@@ -0,0 +1,7 @@
+gradio>=5.0,<6
+torch==2.5.1
+torchvision==0.20.1
+numpy
+pandas
+pillow
+matplotlib

results/classification_report_ensemble_lightweight_effnet_mobilenet_optimized_val_ce_weighted_soft.json

@@ -0,0 +1,39 @@
+{
+  "glioma": {
+    "precision": 0.9962121212121212,
+    "recall": 0.9813432835820896,
+    "f1-score": 0.9887218045112782,
+    "support": 268.0
+  },
+  "meningioma": {
+    "precision": 0.9739776951672863,
+    "recall": 0.9886792452830189,
+    "f1-score": 0.9812734082397003,
+    "support": 265.0
+  },
+  "notumor": {
+    "precision": 1.0,
+    "recall": 1.0,
+    "f1-score": 1.0,
+    "support": 267.0
+  },
+  "pituitary": {
+    "precision": 0.9925373134328358,
+    "recall": 0.9925373134328358,
+    "f1-score": 0.9925373134328358,
+    "support": 268.0
+  },
+  "accuracy": 0.9906367041198502,
+  "macro avg": {
+    "precision": 0.9906817824530608,
+    "recall": 0.990639960574486,
+    "f1-score": 0.9906331315459536,
+    "support": 1068.0
+  },
+  "weighted avg": {
+    "precision": 0.9907199791237635,
+    "recall": 0.9906367041198502,
+    "f1-score": 0.9906506524274749,
+    "support": 1068.0
+  }
+}

results/cm_ensemble_lightweight_effnet_mobilenet_optimized_val_ce_weighted_soft.csv

@@ -0,0 +1,5 @@
+,glioma,meningioma,notumor,pituitary
+glioma,263,5,0,0
+meningioma,1,262,0,2
+notumor,0,0,267,0
+pituitary,0,2,0,266

results/deployed_members.csv

@@ -0,0 +1,4 @@
+member,model_name,seed,weight,checkpoint_file
+efficientnet_b0__seed123,efficientnet_b0,123,0.49513684,best_efficientnet_b0_seed123.pt
+efficientnet_b0__seed2026,efficientnet_b0,2026,0.3507789,best_efficientnet_b0_seed2026.pt
+mobilenet_v3_small__seed42,mobilenet_v3_small,42,0.15408426,best_mobilenet_v3_small_seed42.pt

results/selected_ensemble.json

@@ -0,0 +1,89 @@
+{
+  "ensemble_name": "lightweight_effnet_mobilenet__optimized_val_ce_weighted_soft",
+  "pool": "lightweight_effnet_mobilenet",
+  "fusion_method": "optimized_val_ce_weighted_soft",
+  "classes": [
+    "glioma",
+    "meningioma",
+    "notumor",
+    "pituitary"
+  ],
+  "image_size": 224,
+  "normalization": {
+    "mean": [
+      0.485,
+      0.456,
+      0.406
+    ],
+    "std": [
+      0.229,
+      0.224,
+      0.225
+    ]
+  },
+  "members_all_from_result": [
+    {
+      "member": "efficientnet_b0__seed123",
+      "weight": 0.49513684
+    },
+    {
+      "member": "efficientnet_b0__seed2026",
+      "weight": 0.3507789
+    },
+    {
+      "member": "efficientnet_b0__seed42",
+      "weight": 0.0
+    },
+    {
+      "member": "mobilenet_v3_small__seed42",
+      "weight": 0.15408426
+    },
+    {
+      "member": "mobilenet_v3_small__seed123",
+      "weight": 0.0
+    },
+    {
+      "member": "mobilenet_v3_small__seed2026",
+      "weight": 0.0
+    }
+  ],
+  "members_deployed_nonzero": [
+    {
+      "member": "efficientnet_b0__seed123",
+      "model_name": "efficientnet_b0",
+      "seed": 123,
+      "weight": 0.49513684,
+      "checkpoint_file": "best_efficientnet_b0_seed123.pt"
+    },
+    {
+      "member": "efficientnet_b0__seed2026",
+      "model_name": "efficientnet_b0",
+      "seed": 2026,
+      "weight": 0.3507789,
+      "checkpoint_file": "best_efficientnet_b0_seed2026.pt"
+    },
+    {
+      "member": "mobilenet_v3_small__seed42",
+      "model_name": "mobilenet_v3_small",
+      "seed": 42,
+      "weight": 0.15408426,
+      "checkpoint_file": "best_mobilenet_v3_small_seed42.pt"
+    }
+  ],
+  "metrics": {
+    "val_loss": 0.0351625656474978,
+    "val_accuracy": 0.994413407821229,
+    "val_macro_f1": 0.9944868552693548,
+    "val_weighted_f1": 0.9944201163864824,
+    "val_balanced_accuracy": 0.9944473211762224,
+    "val_macro_auc_ovr": 0.9997045067264196,
+    "test_loss": 0.0411555544777738,
+    "test_accuracy": 0.9906367041198502,
+    "test_macro_f1": 0.9906331315459536,
+    "test_weighted_f1": 0.9906506524274749,
+    "test_balanced_accuracy": 0.990639960574486,
+    "test_macro_auc_ovr": 0.9993387485257516,
+    "test_ece": 0.0081940678915398
+  },
+  "notes": "Zero-weight selected ensemble members are intentionally omitted from deployment; they do not affect weighted-soft inference."
+}

results/selected_metrics.csv

@@ -0,0 +1,2 @@
+val_loss,val_accuracy,val_macro_f1,val_weighted_f1,val_balanced_accuracy,val_macro_auc_ovr,test_loss,test_accuracy,test_macro_f1,test_weighted_f1,test_balanced_accuracy,test_macro_auc_ovr,test_ece
+0.0351625656474978,0.994413407821229,0.9944868552693548,0.9944201163864824,0.9944473211762224,0.9997045067264196,0.0411555544777738,0.9906367041198502,0.9906331315459536,0.9906506524274749,0.990639960574486,0.9993387485257516,0.0081940678915398

results/single_checkpoint_results.csv

@@ -0,0 +1,16 @@
+run_key,model,display_name,seed,params,val_loss,val_accuracy,val_macro_f1,val_weighted_f1,val_balanced_accuracy,val_macro_auc_ovr,test_loss,test_accuracy,test_macro_f1,test_weighted_f1,test_balanced_accuracy,test_macro_auc_ovr,test_ece,cm_path,cm_csv_path,report_path,reliability_path,checkpoint_path
+convnext_tiny__seed123,convnext_tiny,ConvNeXt-Tiny,123,27823204,0.05633521461468096,0.9869646182495344,0.9870486143666763,0.9869666913812417,0.9869601256474765,0.9995339866054144,0.08842497824530703,0.9747191011235955,0.9747367912288595,0.9747705564029551,0.9747363326467092,0.9987674614827884,0.013772038010398967,/kaggle/working/mri_ensemble_fusion_outputs/confusion_matrices/cm_single_convnext_tiny_seed123.png,/kaggle/working/mri_ensemble_fusion_outputs/confusion_matrices/cm_single_convnext_tiny_seed123.csv,/kaggle/working/mri_ensemble_fusion_outputs/classification_reports/classification_report_single_convnext_tiny_seed123.json,/kaggle/working/mri_ensemble_fusion_outputs/plots/reliability_single_convnext_tiny_seed123.png,/kaggle/input/datasets/sayemahmedshayeed/baseline-cnn-result/mri_backbone_baselines_outputs/best_convnext_tiny_seed123.pt
+efficientnet_b0__seed123,efficientnet_b0,EfficientNet-B0,123,4012672,0.05216454092915397,0.984171322160149,0.9842404596100689,0.9841449541023992,0.9843385749686048,0.9994274057336936,0.050461610398573026,0.9840823970037453,0.984111907683999,0.9841518869848078,0.9840750139487004,0.9993316443503547,0.007627396994315781,/kaggle/working/mri_ensemble_fusion_outputs/confusion_matrices/cm_single_efficientnet_b0_seed123.png,/kaggle/working/mri_ensemble_fusion_outputs/confusion_matrices/cm_single_efficientnet_b0_seed123.csv,/kaggle/working/mri_ensemble_fusion_outputs/classification_reports/classification_report_single_efficientnet_b0_seed123.json,/kaggle/working/mri_ensemble_fusion_outputs/plots/reliability_single_efficientnet_b0_seed123.png,/kaggle/input/datasets/sayemahmedshayeed/baseline-cnn-result/mri_backbone_baselines_outputs/best_efficientnet_b0_seed123.pt
+efficientnet_b0__seed2026,efficientnet_b0,EfficientNet-B0,2026,4012672,0.05301791995071825,0.984171322160149,0.9842174297345075,0.984133994553996,0.9842908942132239,0.999159752653795,0.05500029845628876,0.9803370786516854,0.9802870622455948,0.9803219434421269,0.9803224707499181,0.999261557309636,0.009121747889768784,/kaggle/working/mri_ensemble_fusion_outputs/confusion_matrices/cm_single_efficientnet_b0_seed2026.png,/kaggle/working/mri_ensemble_fusion_outputs/confusion_matrices/cm_single_efficientnet_b0_seed2026.csv,/kaggle/working/mri_ensemble_fusion_outputs/classification_reports/classification_report_single_efficientnet_b0_seed2026.json,/kaggle/working/mri_ensemble_fusion_outputs/plots/reliability_single_efficientnet_b0_seed2026.png,/kaggle/input/datasets/sayemahmedshayeed/baseline-cnn-result/mri_backbone_baselines_outputs/best_efficientnet_b0_seed2026.pt
+efficientnet_b0__seed42,efficientnet_b0,EfficientNet-B0,42,4012672,0.0588622792676823,0.9832402234636871,0.9835034785528445,0.9832479292355641,0.9835550767396486,0.9991128183741339,0.05389325926188666,0.9859550561797753,0.9859513817770005,0.9859744427022225,0.9859406064863303,0.9993916755816631,0.006639772698227371,/kaggle/working/mri_ensemble_fusion_outputs/confusion_matrices/cm_single_efficientnet_b0_seed42.png,/kaggle/working/mri_ensemble_fusion_outputs/confusion_matrices/cm_single_efficientnet_b0_seed42.csv,/kaggle/working/mri_ensemble_fusion_outputs/classification_reports/classification_report_single_efficientnet_b0_seed42.json,/kaggle/working/mri_ensemble_fusion_outputs/plots/reliability_single_efficientnet_b0_seed42.png,/kaggle/input/datasets/sayemahmedshayeed/baseline-cnn-result/mri_backbone_baselines_outputs/best_efficientnet_b0_seed42.pt
+convnext_tiny__seed42,convnext_tiny,ConvNeXt-Tiny,42,27823204,0.06510456716608627,0.9823091247672253,0.9824939017733962,0.9822945948953601,0.9826165494285591,0.9992531872698879,0.0726724916066551,0.9831460674157303,0.9831484695235262,0.983153026842635,0.9831104969112461,0.9983606331386008,0.008378916688626179,/kaggle/working/mri_ensemble_fusion_outputs/confusion_matrices/cm_single_convnext_tiny_seed42.png,/kaggle/working/mri_ensemble_fusion_outputs/confusion_matrices/cm_single_convnext_tiny_seed42.csv,/kaggle/working/mri_ensemble_fusion_outputs/classification_reports/classification_report_single_convnext_tiny_seed42.json,/kaggle/working/mri_ensemble_fusion_outputs/plots/reliability_single_convnext_tiny_seed42.png,/kaggle/input/datasets/sayemahmedshayeed/baseline-cnn-result/mri_backbone_baselines_outputs/best_convnext_tiny_seed42.pt
+densenet121__seed42,densenet121,DenseNet-121,42,6957956,0.04785946883591831,0.9823091247672253,0.9823141380049392,0.9822805558528293,0.9824195310812389,0.9994077142903257,0.047856924889672484,0.9878277153558053,0.9878113582281064,0.9878187496215687,0.9878133447665214,0.9992095550961899,0.005454951569382119,/kaggle/working/mri_ensemble_fusion_outputs/confusion_matrices/cm_single_densenet121_seed42.png,/kaggle/working/mri_ensemble_fusion_outputs/confusion_matrices/cm_single_densenet121_seed42.csv,/kaggle/working/mri_ensemble_fusion_outputs/classification_reports/classification_report_single_densenet121_seed42.json,/kaggle/working/mri_ensemble_fusion_outputs/plots/reliability_single_densenet121_seed42.png,/kaggle/input/datasets/sayemahmedshayeed/baseline-cnn-result/mri_backbone_baselines_outputs/best_densenet121_seed42.pt
+mobilenet_v3_small__seed42,mobilenet_v3_small,MobileNetV3-Small,42,1521956,0.06709872207855672,0.9813780260707635,0.9815436769897888,0.981328149769024,0.9816721892794491,0.9989308126793339,0.07185961680883995,0.9850187265917603,0.9849757853063128,0.9849918327374848,0.9850077706654348,0.9986725683477449,0.007273516683989229,/kaggle/working/mri_ensemble_fusion_outputs/confusion_matrices/cm_single_mobilenet_v3_small_seed42.png,/kaggle/working/mri_ensemble_fusion_outputs/confusion_matrices/cm_single_mobilenet_v3_small_seed42.csv,/kaggle/working/mri_ensemble_fusion_outputs/classification_reports/classification_report_single_mobilenet_v3_small_seed42.json,/kaggle/working/mri_ensemble_fusion_outputs/plots/reliability_single_mobilenet_v3_small_seed42.png,/kaggle/input/datasets/sayemahmedshayeed/baseline-cnn-result/mri_backbone_baselines_outputs/best_mobilenet_v3_small_seed42.pt
+vgg16_bn__seed123,vgg16_bn,VGG16-BN,123,134285380,0.0873618445690808,0.9776536312849162,0.9779303695977464,0.9776897022973287,0.9778162818507063,0.9980755053946028,0.11785322495562217,0.9644194756554307,0.9645044856653757,0.964527977005436,0.9643694554575015,0.9975909112925884,0.013353234429037995,/kaggle/working/mri_ensemble_fusion_outputs/confusion_matrices/cm_single_vgg16_bn_seed123.png,/kaggle/working/mri_ensemble_fusion_outputs/confusion_matrices/cm_single_vgg16_bn_seed123.csv,/kaggle/working/mri_ensemble_fusion_outputs/classification_reports/classification_report_single_vgg16_bn_seed123.json,/kaggle/working/mri_ensemble_fusion_outputs/plots/reliability_single_vgg16_bn_seed123.png,/kaggle/input/datasets/sayemahmedshayeed/baseline-cnn-result/mri_backbone_baselines_outputs/best_vgg16_bn_seed123.pt
+mobilenet_v3_small__seed123,mobilenet_v3_small,MobileNetV3-Small,123,1521956,0.07689923900253745,0.9776536312849162,0.9778842773264018,0.9776990699982956,0.9777087921761276,0.9990071749048224,0.07556553708152419,0.9803370786516854,0.9803202327111422,0.9803418056756279,0.9803120685527208,0.9986498759354855,0.010024301038029503,/kaggle/working/mri_ensemble_fusion_outputs/confusion_matrices/cm_single_mobilenet_v3_small_seed123.png,/kaggle/working/mri_ensemble_fusion_outputs/confusion_matrices/cm_single_mobilenet_v3_small_seed123.csv,/kaggle/working/mri_ensemble_fusion_outputs/classification_reports/classification_report_single_mobilenet_v3_small_seed123.json,/kaggle/working/mri_ensemble_fusion_outputs/plots/reliability_single_mobilenet_v3_small_seed123.png,/kaggle/input/datasets/sayemahmedshayeed/baseline-cnn-result/mri_backbone_baselines_outputs/best_mobilenet_v3_small_seed123.pt
+convnext_tiny__seed2026,convnext_tiny,ConvNeXt-Tiny,2026,27823204,0.07302775405488651,0.9776536312849162,0.977484034968861,0.9775049475166269,0.977749161577879,0.9993729225664927,0.07790437014985867,0.9822097378277154,0.9821713003235568,0.9821711563628671,0.9822304631179485,0.9988261503310832,0.013854810695969623,/kaggle/working/mri_ensemble_fusion_outputs/confusion_matrices/cm_single_convnext_tiny_seed2026.png,/kaggle/working/mri_ensemble_fusion_outputs/confusion_matrices/cm_single_convnext_tiny_seed2026.csv,/kaggle/working/mri_ensemble_fusion_outputs/classification_reports/classification_report_single_convnext_tiny_seed2026.json,/kaggle/working/mri_ensemble_fusion_outputs/plots/reliability_single_convnext_tiny_seed2026.png,/kaggle/input/datasets/sayemahmedshayeed/baseline-cnn-result/mri_backbone_baselines_outputs/best_convnext_tiny_seed2026.pt
+densenet121__seed2026,densenet121,DenseNet-121,2026,6957956,0.09570076874671694,0.9757914338919925,0.9759267930906603,0.9757787884069115,0.9759707949097911,0.9977856943941891,0.08383405938199204,0.9644194756554307,0.9643978889368212,0.9644189685879881,0.9644186055096575,0.9988792690733579,0.019289190598418174,/kaggle/working/mri_ensemble_fusion_outputs/confusion_matrices/cm_single_densenet121_seed2026.png,/kaggle/working/mri_ensemble_fusion_outputs/confusion_matrices/cm_single_densenet121_seed2026.csv,/kaggle/working/mri_ensemble_fusion_outputs/classification_reports/classification_report_single_densenet121_seed2026.json,/kaggle/working/mri_ensemble_fusion_outputs/plots/reliability_single_densenet121_seed2026.png,/kaggle/input/datasets/sayemahmedshayeed/baseline-cnn-result/mri_backbone_baselines_outputs/best_densenet121_seed2026.pt
+densenet121__seed123,densenet121,DenseNet-121,123,6957956,0.09968911743004086,0.9739292364990689,0.9739673854664407,0.9739159889765808,0.9735980467564134,0.9976868268064609,0.07860011383005662,0.9747191011235955,0.9747641445122848,0.9748104625930375,0.9747115598602282,0.9988868932999658,0.01756444989183869,/kaggle/working/mri_ensemble_fusion_outputs/confusion_matrices/cm_single_densenet121_seed123.png,/kaggle/working/mri_ensemble_fusion_outputs/confusion_matrices/cm_single_densenet121_seed123.csv,/kaggle/working/mri_ensemble_fusion_outputs/classification_reports/classification_report_single_densenet121_seed123.json,/kaggle/working/mri_ensemble_fusion_outputs/plots/reliability_single_densenet121_seed123.png,/kaggle/input/datasets/sayemahmedshayeed/baseline-cnn-result/mri_backbone_baselines_outputs/best_densenet121_seed123.pt
+vgg16_bn__seed2026,vgg16_bn,VGG16-BN,2026,134285380,0.10408583767801201,0.9720670391061452,0.9722151046438083,0.9720761879541201,0.972068450817785,0.9984540600625993,0.08444612967529652,0.9765917602996255,0.9765918352506224,0.9766090798263743,0.9765983523130584,0.9990747676874356,0.013427661097005068,/kaggle/working/mri_ensemble_fusion_outputs/confusion_matrices/cm_single_vgg16_bn_seed2026.png,/kaggle/working/mri_ensemble_fusion_outputs/confusion_matrices/cm_single_vgg16_bn_seed2026.csv,/kaggle/working/mri_ensemble_fusion_outputs/classification_reports/classification_report_single_vgg16_bn_seed2026.json,/kaggle/working/mri_ensemble_fusion_outputs/plots/reliability_single_vgg16_bn_seed2026.png,/kaggle/input/datasets/sayemahmedshayeed/baseline-cnn-result/mri_backbone_baselines_outputs/best_vgg16_bn_seed2026.pt
+mobilenet_v3_small__seed2026,mobilenet_v3_small,MobileNetV3-Small,2026,1521956,0.10379444774017793,0.9720670391061452,0.972096982838462,0.9719829130460705,0.9722590142810259,0.9984988748854673,0.07063478876050787,0.9803370786516854,0.9803169820469883,0.9803391301476101,0.9803577248377573,0.9991091203815945,0.010550924901212212,/kaggle/working/mri_ensemble_fusion_outputs/confusion_matrices/cm_single_mobilenet_v3_small_seed2026.png,/kaggle/working/mri_ensemble_fusion_outputs/confusion_matrices/cm_single_mobilenet_v3_small_seed2026.csv,/kaggle/working/mri_ensemble_fusion_outputs/classification_reports/classification_report_single_mobilenet_v3_small_seed2026.json,/kaggle/working/mri_ensemble_fusion_outputs/plots/reliability_single_mobilenet_v3_small_seed2026.png,/kaggle/input/datasets/sayemahmedshayeed/baseline-cnn-result/mri_backbone_baselines_outputs/best_mobilenet_v3_small_seed2026.pt
+vgg16_bn__seed42,vgg16_bn,VGG16-BN,42,134285380,0.10840335874189626,0.9683426443202979,0.9685667625901326,0.9683206603405599,0.9686558442815867,0.997278133381573,0.09195423337944612,0.9700374531835206,0.9701289544321485,0.9701563944371983,0.9700085537966306,0.9978532311113247,0.008399970717867699,/kaggle/working/mri_ensemble_fusion_outputs/confusion_matrices/cm_single_vgg16_bn_seed42.png,/kaggle/working/mri_ensemble_fusion_outputs/confusion_matrices/cm_single_vgg16_bn_seed42.csv,/kaggle/working/mri_ensemble_fusion_outputs/classification_reports/classification_report_single_vgg16_bn_seed42.json,/kaggle/working/mri_ensemble_fusion_outputs/plots/reliability_single_vgg16_bn_seed42.png,/kaggle/input/datasets/sayemahmedshayeed/baseline-cnn-result/mri_backbone_baselines_outputs/best_vgg16_bn_seed42.pt

src/__init__.py

@@ -0,0 +1 @@
+"""MRI ensemble Hugging Face Space package."""

src/config.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+APP_ROOT = Path(__file__).resolve().parents[1]
+MODELS_DIR = APP_ROOT / "models"
+RESULTS_DIR = APP_ROOT / "results"
+SELECTED_ENSEMBLE_PATH = RESULTS_DIR / "selected_ensemble.json"
+
+CLASS_NAMES = ["glioma", "meningioma", "notumor", "pituitary"]
+CLASS_DISPLAY_NAMES = {
+    "glioma": "Glioma",
+    "meningioma": "Meningioma",
+    "notumor": "No tumor",
+    "pituitary": "Pituitary",
+}
+
+IMAGE_SIZE = 224
+NORMALIZE_MEAN = [0.485, 0.456, 0.406]
+NORMALIZE_STD = [0.229, 0.224, 0.225]
+
+# The selected deployment ensemble from the ablation notebook.
+# Zero-weight members are intentionally omitted.
+ENSEMBLE_MEMBERS = [
+    {
+        "member": "efficientnet_b0__seed123",
+        "model_name": "efficientnet_b0",
+        "seed": 123,
+        "weight": 0.49513684,
+        "checkpoint_file": "best_efficientnet_b0_seed123.pt",
+        "display_name": "EfficientNet-B0 · seed 123",
+    },
+    {
+        "member": "efficientnet_b0__seed2026",
+        "model_name": "efficientnet_b0",
+        "seed": 2026,
+        "weight": 0.35077890,
+        "checkpoint_file": "best_efficientnet_b0_seed2026.pt",
+        "display_name": "EfficientNet-B0 · seed 2026",
+    },
+    {
+        "member": "mobilenet_v3_small__seed42",
+        "model_name": "mobilenet_v3_small",
+        "seed": 42,
+        "weight": 0.15408426,
+        "checkpoint_file": "best_mobilenet_v3_small_seed42.pt",
+        "display_name": "MobileNetV3-Small · seed 42",
+    },
+]

src/modeling.py

@@ -0,0 +1,344 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+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 torchvision import models, transforms
+
+from .config import (
+    CLASS_DISPLAY_NAMES,
+    CLASS_NAMES,
+    ENSEMBLE_MEMBERS,
+    IMAGE_SIZE,
+    MODELS_DIR,
+    NORMALIZE_MEAN,
+    NORMALIZE_STD,
+    SELECTED_ENSEMBLE_PATH,
+)
+
+
+def _env_flag(name: str, default: bool = True) -> bool:
+    raw = os.getenv(name)
+    if raw is None:
+        return default
+    return raw.strip().lower() not in {"0", "false", "no", "off"}
+
+
+STRICT_CHECKPOINT_LOADING = _env_flag("STRICT_CHECKPOINT_LOADING", True)
+
+
+@dataclass
+class LoadedMember:
+    member: str
+    display_name: str
+    model_name: str
+    seed: int
+    weight: float
+    checkpoint_file: str
+    checkpoint_path: Path
+    model: nn.Module
+
+
+@dataclass
+class PredictionResult:
+    predicted_class: str
+    predicted_display: str
+    confidence: float
+    probabilities: dict[str, float]
+    probability_df: pd.DataFrame
+    member_df: pd.DataFrame
+    ensemble_logits: torch.Tensor
+    input_tensor: torch.Tensor
+
+
+_preprocess = transforms.Compose(
+    [
+        transforms.Resize((IMAGE_SIZE, IMAGE_SIZE)),
+        transforms.ToTensor(),
+        transforms.Normalize(mean=NORMALIZE_MEAN, std=NORMALIZE_STD),
+    ]
+)
+
+
+def preprocess_image(image: Image.Image) -> torch.Tensor:
+    if image is None:
+        raise ValueError("Please upload an MRI image first.")
+    return _preprocess(image.convert("RGB")).unsqueeze(0)
+
+
+def build_model(model_name: str, num_classes: int = len(CLASS_NAMES)) -> nn.Module:
+    constructors = {
+        "efficientnet_b0": models.efficientnet_b0,
+        "mobilenet_v3_small": models.mobilenet_v3_small,
+    }
+    if model_name not in constructors:
+        raise ValueError(f"Unsupported deployment backbone: {model_name}")
+
+    # Do not request torchvision pretrained weights at Space startup. The fine-tuned
+    # checkpoint is expected to contain the trained weights.
+    model = constructors[model_name](weights=None)
+
+    if model_name in {"efficientnet_b0", "mobilenet_v3_small"}:
+        in_features = model.classifier[-1].in_features
+        model.classifier[-1] = nn.Linear(in_features, num_classes)
+    else:  # Defensive; guarded above.
+        raise ValueError(f"No classifier replacement rule for {model_name}")
+    return model
+
+
+def _torch_load(path: Path) -> Any:
+    """Load a PyTorch checkpoint across torch versions.
+
+    Newer PyTorch versions may support weights_only. We first try the safer path,
+    then fall back for older checkpoints that store a richer dictionary.
+    """
+    try:
+        return torch.load(path, map_location="cpu", weights_only=True)
+    except TypeError:
+        return torch.load(path, map_location="cpu")
+    except Exception:
+        # Only use this fallback for your own trusted checkpoints.
+        return torch.load(path, map_location="cpu", weights_only=False)
+
+
+def clean_state_dict(checkpoint: Any) -> dict[str, torch.Tensor]:
+    if isinstance(checkpoint, nn.Module):
+        checkpoint = checkpoint.state_dict()
+
+    if isinstance(checkpoint, dict):
+        for key in ("model_state_dict", "state_dict", "model", "net", "weights"):
+            value = checkpoint.get(key)
+            if isinstance(value, dict):
+                checkpoint = value
+                break
+
+    if not isinstance(checkpoint, dict):
+        raise TypeError("Checkpoint does not contain a PyTorch state_dict-like object.")
+
+    cleaned: dict[str, torch.Tensor] = {}
+    for key, value in checkpoint.items():
+        if not torch.is_tensor(value):
+            continue
+        new_key = str(key)
+        for prefix in ("module.", "model."):
+            if new_key.startswith(prefix):
+                new_key = new_key[len(prefix) :]
+        cleaned[new_key] = value
+
+    if not cleaned:
+        raise ValueError("No tensor weights were found in the checkpoint.")
+    return cleaned
+
+
+def expected_checkpoint_paths() -> dict[str, Path]:
+    return {m["checkpoint_file"]: MODELS_DIR / m["checkpoint_file"] for m in ENSEMBLE_MEMBERS}
+
+
+def diagnose_checkpoints() -> tuple[bool, pd.DataFrame, str]:
+    rows = []
+    all_present = True
+    for m in ENSEMBLE_MEMBERS:
+        path = MODELS_DIR / m["checkpoint_file"]
+        exists = path.exists()
+        all_present = all_present and exists
+        rows.append(
+            {
+                "member": m["display_name"],
+                "weight": round(float(m["weight"]), 8),
+                "expected file": f"models/{m['checkpoint_file']}",
+                "status": "✅ found" if exists else "❌ missing",
+            }
+        )
+    df = pd.DataFrame(rows)
+    if all_present:
+        message = "✅ All required checkpoint files were found in `models/`."
+    else:
+        missing = [r["expected file"] for r in rows if r["status"].startswith("❌")]
+        message = "❌ Missing checkpoint file(s):\n" + "\n".join(f"- `{m}`" for m in missing)
+    return all_present, df, message
+
+
+def _load_selected_metadata() -> dict[str, Any]:
+    if SELECTED_ENSEMBLE_PATH.exists():
+        return json.loads(SELECTED_ENSEMBLE_PATH.read_text(encoding="utf-8"))
+    return {}
+
+
+@lru_cache(maxsize=1)
+def load_ensemble() -> tuple[list[LoadedMember], torch.device, dict[str, Any]]:
+    all_present, _df, message = diagnose_checkpoints()
+    if not all_present:
+        raise FileNotFoundError(message)
+
+    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    loaded: list[LoadedMember] = []
+    for m in ENSEMBLE_MEMBERS:
+        checkpoint_path = MODELS_DIR / m["checkpoint_file"]
+        model = build_model(m["model_name"], len(CLASS_NAMES))
+        state_dict = clean_state_dict(_torch_load(checkpoint_path))
+        model.load_state_dict(state_dict, strict=STRICT_CHECKPOINT_LOADING)
+        model.eval().to(device)
+        loaded.append(
+            LoadedMember(
+                member=m["member"],
+                display_name=m["display_name"],
+                model_name=m["model_name"],
+                seed=int(m["seed"]),
+                weight=float(m["weight"]),
+                checkpoint_file=m["checkpoint_file"],
+                checkpoint_path=checkpoint_path,
+                model=model,
+            )
+        )
+    return loaded, device, _load_selected_metadata()
+
+
+def predict(image: Image.Image) -> PredictionResult:
+    members, device, _metadata = load_ensemble()
+    x_cpu = preprocess_image(image)
+    x = x_cpu.to(device)
+
+    ensemble_probs = None
+    rows = []
+    with torch.inference_mode():
+        for m in members:
+            logits = m.model(x)
+            probs = F.softmax(logits, dim=1)
+            weighted_probs = probs * m.weight
+            ensemble_probs = weighted_probs if ensemble_probs is None else ensemble_probs + weighted_probs
+
+            probs_np = probs.squeeze(0).detach().cpu().numpy()
+            idx = int(np.argmax(probs_np))
+            rows.append(
+                {
+                    "member": m.display_name,
+                    "weight": round(m.weight, 8),
+                    "member prediction": CLASS_DISPLAY_NAMES[CLASS_NAMES[idx]],
+                    "member confidence": round(float(probs_np[idx]), 6),
+                }
+            )
+
+    if ensemble_probs is None:
+        raise RuntimeError("No ensemble members were loaded.")
+
+    probs_np = ensemble_probs.squeeze(0).detach().cpu().numpy()
+    # The weights are normalized from the optimization result, but normalize defensively.
+    probs_np = probs_np / max(float(probs_np.sum()), 1e-12)
+    top_idx = int(np.argmax(probs_np))
+    predicted_class = CLASS_NAMES[top_idx]
+
+    prob_rows = []
+    for label, probability in zip(CLASS_NAMES, probs_np):
+        prob_rows.append(
+            {
+                "class": CLASS_DISPLAY_NAMES[label],
+                "probability": float(probability),
+                "percent": f"{100.0 * float(probability):.2f}%",
+            }
+        )
+    prob_df = pd.DataFrame(prob_rows).sort_values("probability", ascending=False).reset_index(drop=True)
+
+    return PredictionResult(
+        predicted_class=predicted_class,
+        predicted_display=CLASS_DISPLAY_NAMES[predicted_class],
+        confidence=float(probs_np[top_idx]),
+        probabilities={label: float(prob) for label, prob in zip(CLASS_NAMES, probs_np)},
+        probability_df=prob_df,
+        member_df=pd.DataFrame(rows),
+        ensemble_logits=torch.from_numpy(np.log(np.maximum(probs_np, 1e-12))).unsqueeze(0),
+        input_tensor=x_cpu,
+    )
+
+
+def get_target_layer(model: nn.Module, model_name: str) -> nn.Module:
+    # Last convolutional feature block for each deployed torchvision architecture.
+    if model_name == "efficientnet_b0":
+        return model.features[-1]
+    if model_name == "mobilenet_v3_small":
+        return model.features[-1]
+    raise ValueError(f"No Grad-CAM layer configured for {model_name}")
+
+
+def gradcam_for_member(member: LoadedMember, x_cpu: torch.Tensor, target_index: int, output_size: tuple[int, int]) -> np.ndarray:
+    device = next(member.model.parameters()).device
+    x = x_cpu.to(device)
+    activations: list[torch.Tensor] = []
+    gradients: list[torch.Tensor] = []
+
+    target_layer = get_target_layer(member.model, member.model_name)
+
+    def forward_hook(_module, _inputs, output):
+        activations.append(output.detach())
+
+    def backward_hook(_module, _grad_input, grad_output):
+        gradients.append(grad_output[0].detach())
+
+    handle_fwd = target_layer.register_forward_hook(forward_hook)
+    handle_bwd = target_layer.register_full_backward_hook(backward_hook)
+    try:
+        member.model.zero_grad(set_to_none=True)
+        logits = member.model(x)
+        score = logits[0, target_index]
+        score.backward()
+    finally:
+        handle_fwd.remove()
+        handle_bwd.remove()
+
+    if not activations or not gradients:
+        raise RuntimeError(f"Could not collect gradients for {member.display_name}.")
+
+    acts = activations[-1]
+    grads = gradients[-1]
+    weights = grads.mean(dim=(2, 3), keepdim=True)
+    cam = torch.relu((weights * acts).sum(dim=1, keepdim=True))
+    cam = F.interpolate(cam, size=output_size, mode="bilinear", align_corners=False)
+    cam_np = cam.squeeze().detach().cpu().numpy()
+    cam_np = cam_np - cam_np.min()
+    denom = cam_np.max()
+    if denom > 1e-8:
+        cam_np = cam_np / denom
+    return cam_np.astype(np.float32)
+
+
+def weighted_ensemble_cam(image: Image.Image, target_class: str) -> Image.Image:
+    members, _device, _metadata = load_ensemble()
+    rgb = image.convert("RGB")
+    x_cpu = preprocess_image(rgb)
+    target_index = CLASS_NAMES.index(target_class)
+    width, height = rgb.size
+
+    combined = np.zeros((height, width), dtype=np.float32)
+    total_weight = 0.0
+    for member in members:
+        try:
+            cam = gradcam_for_member(member, x_cpu, target_index, output_size=(height, width))
+            combined += cam * float(member.weight)
+            total_weight += float(member.weight)
+        except Exception:
+            # Heatmap is interpretability assistance, not the core prediction. Keep
+            # going if one hook fails; deployment prediction remains unaffected.
+            continue
+
+    if total_weight <= 0:
+        raise RuntimeError("Could not generate Grad-CAM for any ensemble member.")
+    combined = combined / total_weight
+    combined = combined - combined.min()
+    if combined.max() > 1e-8:
+        combined = combined / combined.max()
+
+    import matplotlib.cm as cm
+
+    base = np.asarray(rgb).astype(np.float32) / 255.0
+    heat = cm.get_cmap("magma")(combined)[..., :3].astype(np.float32)
+    overlay = np.clip(0.58 * base + 0.42 * heat, 0, 1)
+    return Image.fromarray((overlay * 255).astype(np.uint8))

validate_bundle.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent
+REQUIRED_FILES = [
+    "app.py",
+    "README.md",
+    "requirements.txt",
+    "src/__init__.py",
+    "src/config.py",
+    "src/modeling.py",
+    "results/selected_ensemble.json",
+    "models/README.md",
+]
+REQUIRED_CHECKPOINTS = [
+    "models/best_efficientnet_b0_seed123.pt",
+    "models/best_efficientnet_b0_seed2026.pt",
+    "models/best_mobilenet_v3_small_seed42.pt",
+]
+PY_FILES = ["app.py", "src/config.py", "src/modeling.py", "validate_bundle.py"]
+
+
+def check_exists() -> bool:
+    ok = True
+    for rel in REQUIRED_FILES:
+        path = ROOT / rel
+        if not path.exists():
+            print(f"ERROR missing required file: {rel}")
+            ok = False
+    return ok
+
+
+def check_syntax() -> bool:
+    ok = True
+    for rel in PY_FILES:
+        path = ROOT / rel
+        if not path.exists():
+            continue
+        try:
+            ast.parse(path.read_text(encoding="utf-8"), filename=rel)
+            print(f"OK syntax: {rel}")
+        except SyntaxError as exc:
+            print(f"ERROR syntax in {rel}: {exc}")
+            ok = False
+    return ok
+
+
+def check_checkpoints() -> bool:
+    ok = True
+    print("\nCheckpoint check:")
+    for rel in REQUIRED_CHECKPOINTS:
+        path = ROOT / rel
+        if path.exists():
+            print(f"OK found: {rel}")
+        else:
+            print(f"WARNING missing: {rel}")
+            ok = False
+    return ok
+
+
+if __name__ == "__main__":
+    files_ok = check_exists()
+    syntax_ok = check_syntax()
+    ckpt_ok = check_checkpoints()
+    print("\nSummary:")
+    print(f"Required files: {'OK' if files_ok else 'ERROR'}")
+    print(f"Python syntax: {'OK' if syntax_ok else 'ERROR'}")
+    print(f"Checkpoints: {'OK' if ckpt_ok else 'MISSING - add them before live inference'}")
+    raise SystemExit(0 if files_ok and syntax_ok else 1)