Upload folder using huggingface_hub

.devcontainer/devcontainer.json

@@ -0,0 +1,33 @@
+{
+  "name": "Python 3",
+  // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
+  "image": "mcr.microsoft.com/devcontainers/python:1-3.11-bullseye",
+  "customizations": {
+    "codespaces": {
+      "openFiles": [
+        "README.md",
+        "app/streamlit_app.py"
+      ]
+    },
+    "vscode": {
+      "settings": {},
+      "extensions": [
+        "ms-python.python",
+        "ms-python.vscode-pylance"
+      ]
+    }
+  },
+  "updateContentCommand": "[ -f packages.txt ] && sudo apt update && sudo apt upgrade -y && sudo xargs apt install -y <packages.txt; [ -f requirements.txt ] && pip3 install --user -r requirements.txt; pip3 install --user streamlit; echo '✅ Packages installed and Requirements met'",
+  "postAttachCommand": {
+    "server": "streamlit run app/streamlit_app.py --server.enableCORS false --server.enableXsrfProtection false"
+  },
+  "portsAttributes": {
+    "8501": {
+      "label": "Application",
+      "onAutoForward": "openPreview"
+    }
+  },
+  "forwardPorts": [
+    8501
+  ]
+}

.flake8

@@ -0,0 +1,3 @@
+[flake8]
+max-line-length = 88
+extend-ignore = E203, W503

.github/workflows/update_space.yml

@@ -0,0 +1,28 @@
+name: Run Python script
+
+on:
+  push:
+    branches:
+      - https://github.com/Stefanoo01/ExplainableCNN
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v2
+
+    - name: Set up Python
+      uses: actions/setup-python@v2
+      with:
+        python-version: '3.9'
+
+    - name: Install Gradio
+      run: python -m pip install gradio
+
+    - name: Log in to Hugging Face
+      run: python -c 'import huggingface_hub; huggingface_hub.login(token="${{ secrets.hf_token }}")'
+
+    - name: Deploy to Spaces
+      run: gradio deploy

.gitignore

@@ -0,0 +1,44 @@
+# bytecode & caches
+__pycache__/
+*.py[cod]
+*.pyo
+
+# envs
+.env
+.venv
+venv/
+ENV/
+.conda/
+.ipynb_checkpoints/
+
+# OS/editor
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/
+
+# build/dist
+build/
+dist/
+*.egg-info/
+
+# data & artifacts
+data/
+checkpoints/
+reports/figures/
+reports/cams/
+logs/
+runs/
+wandb/
+input/
+notebooks/reports
+reports
+
+# notebooks temp
+*.checkpoint.ipynb
+
+# configs with secrets (if any)
+*.secret.*
+
+# Model checkpoints
+saved_checkpoints/*.ckpt

.gradio/certificate.pem

@@ -0,0 +1,31 @@
+-----BEGIN CERTIFICATE-----
+MIIFazCCA1OgAwIBAgIRAIIQz7DSQONZRGPgu2OCiwAwDQYJKoZIhvcNAQELBQAw
+TzELMAkGA1UEBhMCVVMxKTAnBgNVBAoTIEludGVybmV0IFNlY3VyaXR5IFJlc2Vh
+cmNoIEdyb3VwMRUwEwYDVQQDEwxJU1JHIFJvb3QgWDEwHhcNMTUwNjA0MTEwNDM4
+WhcNMzUwNjA0MTEwNDM4WjBPMQswCQYDVQQGEwJVUzEpMCcGA1UEChMgSW50ZXJu
+ZXQgU2VjdXJpdHkgUmVzZWFyY2ggR3JvdXAxFTATBgNVBAMTDElTUkcgUm9vdCBY
+MTCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBAK3oJHP0FDfzm54rVygc
+h77ct984kIxuPOZXoHj3dcKi/vVqbvYATyjb3miGbESTtrFj/RQSa78f0uoxmyF+
+0TM8ukj13Xnfs7j/EvEhmkvBioZxaUpmZmyPfjxwv60pIgbz5MDmgK7iS4+3mX6U
+A5/TR5d8mUgjU+g4rk8Kb4Mu0UlXjIB0ttov0DiNewNwIRt18jA8+o+u3dpjq+sW
+T8KOEUt+zwvo/7V3LvSye0rgTBIlDHCNAymg4VMk7BPZ7hm/ELNKjD+Jo2FR3qyH
+B5T0Y3HsLuJvW5iB4YlcNHlsdu87kGJ55tukmi8mxdAQ4Q7e2RCOFvu396j3x+UC
+B5iPNgiV5+I3lg02dZ77DnKxHZu8A/lJBdiB3QW0KtZB6awBdpUKD9jf1b0SHzUv
+KBds0pjBqAlkd25HN7rOrFleaJ1/ctaJxQZBKT5ZPt0m9STJEadao0xAH0ahmbWn
+OlFuhjuefXKnEgV4We0+UXgVCwOPjdAvBbI+e0ocS3MFEvzG6uBQE3xDk3SzynTn
+jh8BCNAw1FtxNrQHusEwMFxIt4I7mKZ9YIqioymCzLq9gwQbooMDQaHWBfEbwrbw
+qHyGO0aoSCqI3Haadr8faqU9GY/rOPNk3sgrDQoo//fb4hVC1CLQJ13hef4Y53CI
+rU7m2Ys6xt0nUW7/vGT1M0NPAgMBAAGjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNV
+HRMBAf8EBTADAQH/MB0GA1UdDgQWBBR5tFnme7bl5AFzgAiIyBpY9umbbjANBgkq
+hkiG9w0BAQsFAAOCAgEAVR9YqbyyqFDQDLHYGmkgJykIrGF1XIpu+ILlaS/V9lZL
+ubhzEFnTIZd+50xx+7LSYK05qAvqFyFWhfFQDlnrzuBZ6brJFe+GnY+EgPbk6ZGQ
+3BebYhtF8GaV0nxvwuo77x/Py9auJ/GpsMiu/X1+mvoiBOv/2X/qkSsisRcOj/KK
+NFtY2PwByVS5uCbMiogziUwthDyC3+6WVwW6LLv3xLfHTjuCvjHIInNzktHCgKQ5
+ORAzI4JMPJ+GslWYHb4phowim57iaztXOoJwTdwJx4nLCgdNbOhdjsnvzqvHu7Ur
+TkXWStAmzOVyyghqpZXjFaH3pO3JLF+l+/+sKAIuvtd7u+Nxe5AW0wdeRlN8NwdC
+jNPElpzVmbUq4JUagEiuTDkHzsxHpFKVK7q4+63SM1N95R1NbdWhscdCb+ZAJzVc
+oyi3B43njTOQ5yOf+1CceWxG1bQVs5ZufpsMljq4Ui0/1lvh+wjChP4kqKOJ2qxq
+4RgqsahDYVvTH9w7jXbyLeiNdd8XM2w9U/t7y0Ff/9yi0GE44Za4rF2LN9d11TPA
+mRGunUHBcnWEvgJBQl9nJEiU0Zsnvgc/ubhPgXRR4Xq37Z0j4r7g1SgEEzwxA57d
+emyPxgcYxn/eR44/KJ4EBs+lVDR3veyJm+kXQ99b21/+jh5Xos1AnX5iItreGCc=
+-----END CERTIFICATE-----

.pre-commit-config.yaml

@@ -0,0 +1,27 @@
+repos:
+  - repo: https://github.com/psf/black
+    rev: 24.8.0
+    hooks:
+      - id: black
+        args: [--line-length=88]
+
+  - repo: https://github.com/pycqa/isort
+    rev: 5.13.2
+    hooks:
+      - id: isort
+        args: [--profile=black]
+
+  - repo: https://github.com/pycqa/flake8
+    rev: 7.1.1
+    hooks:
+      - id: flake8
+        args: [--max-line-length=88, --extend-ignore=E203,W503]
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-yaml
+      - id: check-json
+      - id: check-merge-conflict

.streamlit/presets.json

@@ -0,0 +1,7 @@
+{
+    "release_checkpoints": {
+        "resnet18_cifar10": "https://github.com/Stefanoo01/ExplainableCNN/releases/download/v1.0.0/resnet18_cifar10.ckpt",
+        "smallcnn_fmnist": "https://github.com/Stefanoo01/ExplainableCNN/releases/download/v1.0.0/smallcnn_fmnist.ckpt",
+        "smallcnn_aug_fmnist": "https://github.com/Stefanoo01/ExplainableCNN/releases/download/v1.0.0/smallcnn_aug_fmnist.ckpt"
+    }
+  }

README.MD

@@ -0,0 +1,188 @@
+---
+title: ExplainableCNN
+app_file: app/gradio_app.py
+sdk: gradio
+sdk_version: 5.47.0
+---
+# ExplainableCNN
+
+End‑to‑end image classification with explainability. Train CNNs on common vision datasets, save checkpoints and metrics, and visualize Grad‑CAM/Grad‑CAM++ heatmaps in a Streamlit app.
+
+>**Online App**: You can try the app online at `https://explainable-cnn.streamlit.app`
+
+Contents
+- Quick start
+- Installation
+- Datasets
+- Training
+- Configuration reference
+- Streamlit Grad‑CAM demo
+- Checkpoints and outputs
+- Project layout
+- FAQ / Tips
+
+## Quick start
+
+1) Install dependencies (CPU‑only by default):
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+2) Train with defaults (Fashion‑MNIST, small CNN):
+```bash
+python -m src.train --config configs/baseline.yaml
+```
+
+3) Launch the Grad‑CAM demo and visualize predictions:
+```bash
+streamlit run app/streamlit_app.py
+```
+
+## Installation
+
+This repo ships with CPU‑only PyTorch wheels via the official extra index in `requirements.txt`. If you have CUDA, you can install the matching GPU wheels from PyTorch and keep the rest of the requirements.
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+### GPU installation (recommended for training)
+
+1) Install CUDA‑enabled PyTorch that matches your driver and CUDA version (see `https://pytorch.org/get-started/locally/`). Examples:
+
+```bash
+# CUDA 12.1
+pip install --index-url https://download.pytorch.org/whl/cu121 torch torchvision torchaudio
+
+# CUDA 11.8
+# pip install --index-url https://download.pytorch.org/whl/cu118 torch torchvision torchaudio
+```
+
+2) Install the rest of the project dependencies (excluding torch*):
+
+```bash
+pip install -r requirements-gpu.txt
+```
+
+Notes
+- If you want GPU builds: follow the selector at `https://pytorch.org/get-started/locally/` and install the torch/torchvision/torchaudio triplet before installing the rest of the requirements.
+- This project uses: torch/torchvision, torchmetrics, captum/torchcam, lightning (as the newer package name), albumentations, TensorBoard, Streamlit, PyYAML, etc.
+
+## Datasets
+
+Built‑in dataset options for training:
+- `fashion-mnist` (default)
+- `mnist`
+- `cifar10`
+
+Where data lives
+- By default datasets are downloaded under `data/`.
+
+## Training
+
+Run with a YAML config
+```bash
+python -m src.train --config configs/baseline.yaml
+```
+
+Override config values from the CLI
+```bash
+python -m src.train --config configs/baseline.yaml --epochs 12 --lr 5e-4
+```
+
+Switch dataset from the CLI
+```bash
+python -m src.train --config configs/baseline.yaml --dataset mnist
+```
+
+Use a ResNet‑18 backbone for CIFAR‑10 (adapted conv1/no maxpool)
+```bash
+python -m src.train --config configs/cifar10_resnet18.yaml
+```
+
+
+Training flow (high level)
+- Loads YAML config and merges CLI overrides
+- Builds dataloaders with dataset‑specific transforms and normalization
+- Builds model: `smallcnn`, `resnet18_cifar`, or `resnet18_imagenet`
+- Optimizer: Adam (default) or SGD with momentum
+- Trains with early stopping and ReduceLROnPlateau on val loss
+- Writes TensorBoard logs, metrics JSONs, and image reports (confusion matrix)
+- Saves `last.ckpt` and `best.ckpt` with model weights and metadata
+
+Outputs per run (under roots from config)
+- `runs/<run_id>/` TensorBoard logs
+- `checkpoints/<run_id>/last.ckpt` and `best.ckpt`
+- `reports/<run_id>/config_effective.yaml`, `metrics.json`, and `figures/confusion_matrix.png`
+
+## Configuration reference
+
+See examples in `configs/`:
+- `baseline.yaml` (Fashion‑MNIST + `smallcnn`)
+- `cifar10_resnet18.yaml` (CIFAR‑10 + adapted ResNet‑18)
+
+Common keys
+- `dataset`: one of `fashion-mnist`, `mnist`, `cifar10`
+- `model_name`: `smallcnn` | `resnet18_cifar` | `resnet18_imagenet`
+- `data_dir`: root folder for data (default `./data`)
+- `batch_size`, `epochs`, `lr`, `weight_decay`, `num_workers`, `seed`, `device`
+- `img_size`, `mean`, `std`: image shape and normalization stats
+- `optimizer`: `adam` (default) or `sgd`; `momentum` used for SGD
+- `log_root`, `ckpt_root`, `reports_root`: base folders for artifacts
+- `early_stop`: `{ monitor: val_loss|val_acc, mode: min|max, patience, min_delta }`
+
+CLI flags can override the YAML. For example `--dataset`, `--epochs`, `--lr`, `--model-name`.
+
+## Streamlit Grad‑CAM demo
+
+Start the app (or try it online at `https://explainable-cnn.streamlit.app`)
+```bash
+streamlit run app/streamlit_app.py
+```
+
+What it does
+- Load a trained checkpoint (`.ckpt`)
+- Upload an image or sample one from the corresponding dataset
+- Run inference and display top‑k predictions
+- Visualize Grad‑CAM or Grad‑CAM++ overlays with adjustable alpha
+
+Supplying checkpoints
+- Local discovery: put `.ckpt` files under `saved_checkpoints/` or use the file uploader
+- Download from a URL: paste a direct link to a `.ckpt` asset and click “Download checkpoint”
+- Presets: provide a map of names → URLs via one of:
+  - Streamlit secrets: `st.secrets["release_checkpoints"] = { "Name": "https://...best.ckpt" }`
+  - `.streamlit/presets.json` or `presets.json` in repo root, either:
+    ```json
+    { "release_checkpoints": { "FMNIST SmallCNN": "https://.../best.ckpt" } }
+    ```
+    or a flat mapping `{ "FMNIST SmallCNN": "https://..." }`
+  - Environment variable `RELEASE_CKPTS_JSON` with a JSON mapping string
+
+Devices and CAM methods
+- Device: `auto` (default), `cuda`, or `cpu`
+- CAM: `Grad-CAM` or `Grad-CAM++` via `torchcam`
+
+Checkpoint metadata expected
+- `meta`: `{ dataset, model_name, img_size, mean, std, default_target_layer }`
+- `classes`: list of class names (used to label predictions)
+
+## Checkpoints and outputs
+
+Each run writes:
+- Checkpoints: `<ckpt_root>/<run_id>/{last.ckpt,best.ckpt}`
+- Logs: `<log_root>/<run_id>/` (TensorBoard)
+- Reports: `<reports_root>/<run_id>/metrics.json`, `figures/confusion_matrix.png`
+
+Best checkpoint selection respects early‑stopping monitor (`val_loss` or `val_acc`).
+
+## License and acknowledgements
+
+- Uses `torchcam` for CAM extraction and `captum` as a general explainability dependency
+- TorchVision models and datasets are used for baselines and data handling
+
+___
+
+If you run into issues, please open an issue with your command, config file, and environment details.

app/gradio_app.py

@@ -0,0 +1,668 @@
+import datetime as dt
+import random
+from pathlib import Path
+import os
+import hashlib
+import requests
+import json
+import tempfile
+
+import numpy as np
+import gradio as gr
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+import torchvision.models as tvm
+import torchvision.transforms as T
+from PIL import Image
+from torchcam.methods import GradCAM, GradCAMpp
+from torchcam.utils import overlay_mask
+from torchvision.datasets import CIFAR10, MNIST, FashionMNIST
+
+# Global state for model and configuration
+app_state = {
+    "model": None,
+    "classes": None,
+    "meta": None,
+    "transform": None,
+    "target_layer": None,
+    "dataset": None,
+    "dataset_classes": None
+}
+
+custom_theme = gr.themes.Soft(
+    primary_hue="green",     # main brand color
+    secondary_hue="purple",  # accent color
+    neutral_hue="slate"       # backgrounds/borders/text neutrals
+)
+
+def download_release_asset(url: str, dest_dir: str = "saved_checkpoints") -> str:
+    """Download a remote checkpoint to dest_dir and return its local path."""
+    Path(dest_dir).mkdir(parents=True, exist_ok=True)
+    url_hash = hashlib.sha256(url.encode("utf-8")).hexdigest()[:16]
+    fname = Path(url).name or f"asset_{url_hash}.ckpt"
+    if not fname.endswith(".ckpt"):
+        fname = f"{fname}.ckpt"
+    local_path = Path(dest_dir) / f"{url_hash}_{fname}"
+    
+    if local_path.exists() and local_path.stat().st_size > 0:
+        return str(local_path)
+    
+    with requests.get(url, stream=True, timeout=120) as r:
+        r.raise_for_status()
+        with open(local_path, "wb") as f:
+            for chunk in r.iter_content(chunk_size=1024 * 1024):
+                if chunk:
+                    f.write(chunk)
+    return str(local_path)
+
+
+def load_release_presets() -> dict:
+    """Load release preset URLs from multiple sources."""
+    # Try environment variable containing JSON mapping
+    env_json = os.environ.get("RELEASE_CKPTS_JSON", "").strip()
+    if env_json:
+        try:
+            data = json.loads(env_json)
+            if isinstance(data, dict):
+                return dict(data)
+        except Exception:
+            pass
+    
+    # Try local JSON files for dev
+    for rel in (".streamlit/presets.json", "presets.json"):
+        p = Path(rel)
+        if p.exists():
+            try:
+                with open(p, "r", encoding="utf-8") as f:
+                    data = json.load(f)
+                if isinstance(data, dict) and data:
+                    if "release_checkpoints" in data and isinstance(data["release_checkpoints"], dict):
+                        return dict(data["release_checkpoints"])
+                    return dict(data)
+            except Exception:
+                pass
+    
+    return {}
+
+
+def get_device(choice="auto"):
+    if choice == "cpu":
+        return "cpu"
+    if choice == "cuda":
+        return "cuda"
+    return "cuda" if torch.cuda.is_available() else "cpu"
+
+
+def denorm_to_pil(x, mean, std):
+    """Convert normalized tensor to PIL Image."""
+    x = x.detach().cpu().clone()
+    if len(mean) == 1:
+        # grayscale
+        m, s = float(mean[0]), float(std[0])
+        x = x * s + m
+        x = x.clamp(0, 1)
+        pil = T.ToPILImage()(x)
+        pil = pil.convert("RGB")
+        return pil
+    else:
+        mean = torch.tensor(mean)[:, None, None]
+        std = torch.tensor(std)[:, None, None]
+        x = x * std + mean
+        x = x.clamp(0, 1)
+        return T.ToPILImage()(x)
+
+
+DATASET_CLASSES = {
+    "fashion-mnist": [
+        "T-shirt/top", "Trouser", "Pullover", "Dress", "Coat",
+        "Sandal", "Shirt", "Sneaker", "Bag", "Ankle boot",
+    ],
+    "mnist": [str(i) for i in range(10)],
+    "cifar10": [
+        "airplane", "automobile", "bird", "cat", "deer",
+        "dog", "frog", "horse", "ship", "truck",
+    ],
+}
+
+
+def load_raw_dataset(name: str, root="data"):
+    """Load the test split with ToTensor() only (for preview)."""
+    tt = T.ToTensor()
+    if name == "fashion-mnist":
+        ds = FashionMNIST(root=root, train=False, download=True, transform=tt)
+    elif name == "mnist":
+        ds = MNIST(root=root, train=False, download=True, transform=tt)
+    elif name == "cifar10":
+        ds = CIFAR10(root=root, train=False, download=True, transform=tt)
+    else:
+        raise ValueError(f"Unknown dataset: {name}")
+    classes = getattr(ds, "classes", None) or [str(i) for i in range(10)]
+    return ds, classes
+
+
+def pil_from_tensor(img_tensor, grayscale_to_rgb=True):
+    pil = T.ToPILImage()(img_tensor)
+    if grayscale_to_rgb and img_tensor.ndim == 3 and img_tensor.shape[0] == 1:
+        pil = pil.convert("RGB")
+    return pil
+
+
+class SmallCNN(nn.Module):
+    def __init__(self, num_classes=10):
+        super().__init__()
+        self.conv1 = nn.Conv2d(1, 32, 3, padding=1)
+        self.pool1 = nn.MaxPool2d(2, 2)
+        self.conv2 = nn.Conv2d(32, 64, 3, padding=1)
+        self.pool2 = nn.MaxPool2d(2, 2)
+        self.fc = nn.Linear(64 * 7 * 7, num_classes)
+
+    def forward(self, x):
+        x = F.relu(self.conv1(x))
+        x = self.pool1(x)
+        x = F.relu(self.conv2(x))
+        x = self.pool2(x)
+        x = torch.flatten(x, 1)
+        return self.fc(x)
+
+
+def load_model_from_ckpt(ckpt_path: Path, device: str):
+    ckpt = torch.load(str(ckpt_path), map_location=device)
+    classes = ckpt.get("classes", None)
+    meta = ckpt.get("meta", {})
+    num_classes = len(classes) if classes else 10
+    model_name = meta.get("model_name", "smallcnn")
+
+    if model_name == "smallcnn":
+        model = SmallCNN(num_classes=num_classes).to(device)
+        default_target_layer = "conv2"
+    elif model_name == "resnet18_cifar":
+        m = tvm.resnet18(weights=None)
+        m.conv1 = nn.Conv2d(3, 64, kernel_size=3, stride=1, padding=1, bias=False)
+        m.maxpool = nn.Identity()
+        m.fc = nn.Linear(m.fc.in_features, num_classes)
+        model = m.to(device)
+        default_target_layer = "layer4"
+    elif model_name == "resnet18_imagenet":
+        try:
+            w = tvm.ResNet18_Weights.IMAGENET1K_V1
+        except Exception:
+            w = None
+        m = tvm.resnet18(weights=w)
+        m.fc = nn.Linear(m.fc.in_features, num_classes)
+        model = m.to(device)
+        default_target_layer = "layer4"
+    else:
+        raise ValueError(f"Unknown model_name in ckpt: {model_name}")
+
+    model.load_state_dict(ckpt["model_state"])
+    model.eval()
+    meta.setdefault("default_target_layer", default_target_layer)
+    return model, classes, meta
+
+
+def build_transform_from_meta(meta):
+    img_size = int(meta.get("img_size", 28))
+    mean = meta.get("mean", [0.2860])
+    std = meta.get("std", [0.3530])
+    if len(mean) == 1:
+        return T.Compose([
+            T.Grayscale(num_output_channels=1),
+            T.Resize((img_size, img_size)),
+            T.ToTensor(),
+            T.Normalize(mean, std),
+        ])
+    else:
+        return T.Compose([
+            T.Resize((img_size, img_size)),
+            T.ToTensor(),
+            T.Normalize(mean, std),
+        ])
+
+
+def predict_and_cam(model, x, device, target_layer, topk=3, method="Grad-CAM"):
+    """Predict and generate CAM for top-k classes."""
+    cam_cls = GradCAM if method == "Grad-CAM" else GradCAMpp
+    cam_extractor = cam_cls(model, target_layer=target_layer)
+
+    logits = model(x.to(device))
+    probs = torch.softmax(logits, dim=1)[0].detach().cpu()
+    top_vals, top_idxs = probs.topk(topk)
+
+    results = []
+    for rank, (p, idx) in enumerate(zip(top_vals.tolist(), top_idxs.tolist())):
+        retain = rank < topk - 1
+        cams = cam_extractor(idx, logits, retain_graph=retain)
+        cam = cams[0].detach().cpu()
+        results.append({
+            "rank": rank + 1,
+            "class_index": int(idx),
+            "prob": float(p),
+            "cam": cam
+        })
+    return results, probs
+
+
+def overlay_pil(base_pil_rgb: Image.Image, cam_tensor, alpha=0.5):
+    """Create overlay of CAM on base image."""
+    cam = cam_tensor.clone()
+    cam -= cam.min()
+    cam = cam / (cam.max() + 1e-8)
+    heat = T.ToPILImage()(cam)
+    return overlay_mask(base_pil_rgb, heat, alpha=alpha)
+
+
+# Gradio interface functions
+def load_checkpoint_from_url(url, preset_name):
+    """Load checkpoint from URL or preset."""
+    presets = load_release_presets()
+    
+    if preset_name and preset_name != "None":
+        url = presets.get(preset_name, "")
+    
+    if not url:
+        return "❌ No URL provided", "", ""
+    
+    try:
+        ckpt_path = download_release_asset(url)
+        device = get_device("cpu")
+        model, classes, meta = load_model_from_ckpt(Path(ckpt_path), device)
+        
+        # Update global state
+        app_state["model"] = model
+        app_state["classes"] = classes
+        app_state["meta"] = meta
+        app_state["transform"] = build_transform_from_meta(meta)
+        app_state["target_layer"] = meta.get("default_target_layer", "conv2")
+        
+        # Load dataset for samples
+        ds_name = meta.get("dataset", "fashion-mnist")
+        try:
+            dataset, dataset_classes = load_raw_dataset(ds_name)
+            app_state["dataset"] = dataset
+            app_state["dataset_classes"] = dataset_classes
+        except:
+            app_state["dataset"] = None
+            app_state["dataset_classes"] = None
+        
+        meta_info = {
+            "dataset": meta.get("dataset"),
+            "model_name": meta.get("model_name"),
+            "img_size": meta.get("img_size"),
+            "target_layer": app_state["target_layer"],
+            "mean": meta.get("mean"),
+            "std": meta.get("std"),
+            "classes": len(classes) if classes else "N/A"
+        }
+        
+        # Create class choices for filter
+        class_choices = ["(any)"] + (dataset_classes if app_state["dataset"] else [])
+        max_samples = len(dataset) - 1 if app_state["dataset"] else 0
+        
+        return (f"✅ Loaded: {ckpt_path}", json.dumps(meta_info, indent=2), 
+                gr.update(visible=True), gr.update(choices=class_choices, value="(any)"),
+                gr.update(visible=True, maximum=max_samples, value=0))
+    
+    except Exception as e:
+        return f"❌ Failed: {str(e)}", "", gr.update(visible=False), gr.update(choices=["(any)"], value="(any)"), gr.update(visible=False), gr.update(choices=["(any)"], value="(any)"), gr.update(visible=False)
+
+
+def load_checkpoint_from_file(file):
+    """Load checkpoint from uploaded file."""
+    if file is None:
+        return "❌ No file uploaded", "", ""
+    
+    try:
+        # Save uploaded file temporarily
+        Path("saved_checkpoints").mkdir(parents=True, exist_ok=True)
+        with open(file.name, "rb") as f:
+            content = f.read()
+        
+        content_hash = hashlib.sha256(content).hexdigest()[:16]
+        base_name = Path(file.name).name
+        if not base_name.endswith(".ckpt"):
+            base_name = f"{base_name}.ckpt"
+        local_path = Path("saved_checkpoints") / f"{content_hash}_{base_name}"
+        
+        with open(local_path, "wb") as f:
+            f.write(content)
+        
+        device = get_device("cpu")
+        model, classes, meta = load_model_from_ckpt(local_path, device)
+        
+        # Update global state
+        app_state["model"] = model
+        app_state["classes"] = classes
+        app_state["meta"] = meta
+        app_state["transform"] = build_transform_from_meta(meta)
+        app_state["target_layer"] = meta.get("default_target_layer", "conv2")
+        
+        # Load dataset for samples
+        ds_name = meta.get("dataset", "fashion-mnist")
+        try:
+            dataset, dataset_classes = load_raw_dataset(ds_name)
+            app_state["dataset"] = dataset
+            app_state["dataset_classes"] = dataset_classes
+        except:
+            app_state["dataset"] = None
+            app_state["dataset_classes"] = None
+        
+        meta_info = {
+            "dataset": meta.get("dataset"),
+            "model_name": meta.get("model_name"),
+            "img_size": meta.get("img_size"),
+            "target_layer": app_state["target_layer"],
+            "mean": meta.get("mean"),
+            "std": meta.get("std"),
+            "classes": len(classes) if classes else "N/A"
+        }
+        
+        # Create class choices for filter
+        class_choices = ["(any)"] + (dataset_classes if app_state["dataset"] else [])
+        max_samples = len(dataset) - 1 if app_state["dataset"] else 0
+        
+        return (f"✅ Loaded: {local_path}", json.dumps(meta_info, indent=2), 
+                gr.update(visible=True), gr.update(choices=class_choices, value="(any)"),
+                gr.update(visible=True, maximum=max_samples, value=0))
+    
+    except Exception as e:
+        return f"❌ Failed: {str(e)}", "", gr.update(visible=False)
+
+
+def get_random_sample():
+    """Get a random sample from the loaded dataset."""
+    if app_state["dataset"] is None:
+        return None, "No dataset loaded", gr.update(visible=False)
+    
+    dataset = app_state["dataset"]
+    idx = random.randint(0, len(dataset) - 1)
+    img_tensor, label = dataset[idx]
+    sample_img = pil_from_tensor(img_tensor, grayscale_to_rgb=True)
+    
+    class_name = app_state["dataset_classes"][label] if app_state["dataset_classes"] else str(label)
+    caption = f"Sample from {app_state['meta'].get('dataset', 'dataset')} • class: {class_name} • idx: {idx}"
+    
+    # Update slider maximum and current value
+    max_idx = len(dataset) - 1
+    return sample_img, caption, gr.update(visible=True, maximum=max_idx, value=idx)
+
+
+def get_sample_by_index(idx, class_filter):
+    """Get a specific sample by index with optional class filtering."""
+    if app_state["dataset"] is None:
+        return None, "No dataset loaded"
+    
+    dataset = app_state["dataset"]
+    dataset_classes = app_state["dataset_classes"]
+    
+    # Apply class filter
+    if class_filter != "(any)":
+        targets = np.array([dataset[i][1] for i in range(len(dataset))])
+        class_id = dataset_classes.index(class_filter)
+        filtered_indices = np.where(targets == class_id)[0]
+        
+        if len(filtered_indices) == 0:
+            return None, f"No samples found for class: {class_filter}"
+        
+        # Clamp index to filtered range
+        idx = max(0, min(idx, len(filtered_indices) - 1))
+        actual_idx = filtered_indices[idx]
+    else:
+        # Clamp index to dataset range
+        idx = max(0, min(idx, len(dataset) - 1))
+        actual_idx = idx
+    
+    img_tensor, label = dataset[actual_idx]
+    sample_img = pil_from_tensor(img_tensor, grayscale_to_rgb=True)
+    
+    class_name = dataset_classes[label] if dataset_classes else str(label)
+    caption = f"Sample {actual_idx} from {app_state['meta'].get('dataset', 'dataset')} • class: {class_name}"
+    
+    return sample_img, caption
+
+
+def update_class_filter(class_filter):
+    """Update the slider range when class filter changes."""
+    if app_state["dataset"] is None:
+        return gr.update(visible=False, maximum=0, value=0)
+    
+    dataset = app_state["dataset"]
+    dataset_classes = app_state["dataset_classes"]
+    
+    if class_filter == "(any)":
+        max_idx = len(dataset) - 1
+    else:
+        targets = np.array([dataset[i][1] for i in range(len(dataset))])
+        class_id = dataset_classes.index(class_filter)
+        filtered_indices = np.where(targets == class_id)[0]
+        max_idx = len(filtered_indices) - 1 if len(filtered_indices) > 0 else 0
+    
+    return gr.update(visible=True, maximum=max_idx, value=0)
+
+
+def process_image(image, method, topk, alpha):
+    """Process image and generate Grad-CAM visualizations."""
+    if app_state["model"] is None:
+        return "❌ No model loaded", [], []
+    
+    if image is None:
+        return "❌ No image provided", [], []
+    
+    try:
+        # Convert to PIL if needed
+        if isinstance(image, np.ndarray):
+            image = Image.fromarray(image)
+        
+        # Prepare image
+        pil = image.convert("RGB")
+        x = app_state["transform"](pil)
+        x_batched = x.unsqueeze(0)
+        
+        # Generate base image for overlay
+        base_pil = denorm_to_pil(
+            x, 
+            app_state["meta"].get("mean", [0.2860]), 
+            app_state["meta"].get("std", [0.3530])
+        )
+        
+        # Run prediction and CAM
+        device = get_device("cpu")
+        cam_results, probs = predict_and_cam(
+            app_state["model"], x_batched, device, 
+            app_state["target_layer"], topk=topk, method=method
+        )
+        
+        # Create predictions table
+        predictions = []
+        for r in cam_results:
+            class_name = app_state["classes"][r["class_index"]] if app_state["classes"] else str(r["class_index"])
+            predictions.append([
+                r["rank"],
+                class_name,
+                r["class_index"],
+                f"{r['prob']:.4f}"
+            ])
+        
+        # Create overlay images
+        overlays = []
+        for r in cam_results:
+            class_name = app_state["classes"][r["class_index"]] if app_state["classes"] else str(r["class_index"])
+            overlay_img = overlay_pil(base_pil, r["cam"], alpha=alpha)
+            overlays.append((overlay_img, f"Top{r['rank']}: {class_name} ({r['prob']:.3f})"))
+        
+        return "✅ Processing complete", predictions, overlays
+    
+    except Exception as e:
+        return f"❌ Processing failed: {str(e)}", [], []
+
+
+# Create Gradio interface
+def create_interface():
+    presets = load_release_presets()
+    preset_choices = ["None"] + list(presets.keys()) if presets else ["None"]
+    
+    with gr.Blocks(title="🔍 Grad-CAM Demo", theme=custom_theme) as demo:
+        gr.Markdown("# 🔍 Grad-CAM Demo — Upload an image, get top-k predictions + heatmaps")
+        
+        with gr.Row():
+            with gr.Column(scale=1):
+                gr.Markdown("## Settings")
+                
+                # Checkpoint loading
+                gr.Markdown("### Load Checkpoint")
+                with gr.Group():
+                    preset_dropdown = gr.Dropdown(
+                        choices=preset_choices, 
+                        value="None",
+                        label="Preset (GitHub Releases)"
+                    )
+                    url_input = gr.Textbox(
+                        label="Or paste asset URL",
+                        placeholder="https://github.com/user/repo/releases/download/..."
+                    )
+                    url_button = gr.Button("Download from URL", variant="primary")
+                
+                with gr.Group():
+                    file_input = gr.File(
+                        label="Upload checkpoint (.ckpt)",
+                        file_types=[".ckpt"]
+                    )
+                    file_button = gr.Button("Load uploaded file", variant="primary")
+                
+                status_text = gr.Textbox(
+                    label="Status",
+                    interactive=False,
+                    value="No checkpoint loaded"
+                )
+                
+                meta_display = gr.Code(
+                    label="Model Metadata",
+                    language="json",
+                    interactive=False
+                )
+                
+                # Processing options
+                gr.Markdown("### Processing Options")
+                method_radio = gr.Radio(
+                    choices=["Grad-CAM", "Grad-CAM++"],
+                    value="Grad-CAM",
+                    label="CAM Method"
+                )
+                topk_slider = gr.Slider(
+                    minimum=1, maximum=10, value=3, step=1,
+                    label="Top-k classes"
+                )
+                alpha_slider = gr.Slider(
+                    minimum=0.1, maximum=0.9, value=0.5, step=0.05,
+                    label="Overlay alpha"
+                )
+            
+            with gr.Column(scale=2):
+                gr.Markdown("## Image Input")
+                
+                with gr.Group():
+                    image_input = gr.Image(
+                        label="Upload Image",
+                        type="pil"
+                    )
+                    
+                    with gr.Row():
+                        sample_button = gr.Button("Random Sample", visible=False)
+                        
+                    with gr.Group():
+                        gr.Markdown("**Dataset Sample Browser**")
+                        class_filter = gr.Dropdown(
+                            label="Filter by class",
+                            choices=["(any)"],
+                            value="(any)",
+                            visible=False
+                        )
+                        sample_slider = gr.Slider(
+                            label="Sample index",
+                            minimum=0,
+                            maximum=0,
+                            value=0,
+                            step=1,
+                            visible=False,
+                            interactive=True
+                        )
+                        sample_info = gr.Textbox(
+                            label="Sample Info",
+                            interactive=False,
+                            visible=False
+                        )
+                
+                process_button = gr.Button("🔍 Process Image", variant="primary", size="lg")
+                process_status = gr.Textbox(
+                    label="Processing Status",
+                    interactive=False
+                )
+                
+                gr.Markdown("## Results")
+                
+                with gr.Group():
+                    gr.Markdown("### Top-k Predictions")
+                    predictions_table = gr.Dataframe(
+                        headers=["Rank", "Class", "Index", "Probability"],
+                        datatype=["number", "str", "number", "str"],
+                        interactive=False
+                    )
+                
+                with gr.Group():
+                    gr.Markdown("### Grad-CAM Overlays")
+                    overlay_gallery = gr.Gallery(
+                        label="CAM Overlays",
+                        show_label=False,
+                        elem_id="gallery",
+                        columns=3,
+                        rows=2,
+                        object_fit="contain",
+                        height="auto"
+                    )
+        
+        # Event handlers
+        url_button.click(
+            fn=load_checkpoint_from_url,
+            inputs=[url_input, preset_dropdown],
+            outputs=[status_text, meta_display, sample_button, class_filter, sample_slider]
+        )
+        
+        file_button.click(
+            fn=load_checkpoint_from_file,
+            inputs=[file_input],
+            outputs=[status_text, meta_display, sample_button, class_filter, sample_slider]
+        )
+        
+        sample_button.click(
+            fn=get_random_sample,
+            outputs=[image_input, sample_info, sample_slider]
+        )
+        
+        class_filter.change(
+            fn=update_class_filter,
+            inputs=[class_filter],
+            outputs=[sample_slider]
+        )
+        
+        sample_slider.change(
+            fn=get_sample_by_index,
+            inputs=[sample_slider, class_filter],
+            outputs=[image_input, sample_info]
+        )
+        
+        process_button.click(
+            fn=process_image,
+            inputs=[image_input, method_radio, topk_slider, alpha_slider],
+            outputs=[process_status, predictions_table, overlay_gallery]
+        )
+    
+    return demo
+
+
+if __name__ == "__main__":
+    demo = create_interface()
+    demo.launch(
+        share=True,
+        server_name="0.0.0.0",
+        server_port=7860
+    )

app/streamlit_app.py

@@ -0,0 +1,557 @@
+import datetime as dt
+import random
+from pathlib import Path
+import os
+import hashlib
+import requests
+import json
+
+import numpy as np
+import streamlit as st
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+import torchvision.models as tvm
+import torchvision.transforms as T
+from PIL import Image
+from torchcam.methods import GradCAM, GradCAMpp
+from torchcam.utils import overlay_mask
+from torchvision.datasets import CIFAR10, MNIST, FashionMNIST
+
+# Persist selected checkpoint across reruns
+if "ckpt_path" not in st.session_state:
+    st.session_state["ckpt_path"] = None
+
+
+@st.cache_data(show_spinner=True)
+def download_release_asset(url: str, dest_dir: str = "saved_checkpoints") -> str:
+    """Download a remote checkpoint to dest_dir and return its local path.
+    Cached so subsequent reruns won't redownload.
+    """
+    Path(dest_dir).mkdir(parents=True, exist_ok=True)
+    url_hash = hashlib.sha256(url.encode("utf-8")).hexdigest()[:16]
+    fname = Path(url).name or f"asset_{url_hash}.ckpt"
+    if not fname.endswith(".ckpt"):
+        fname = f"{fname}.ckpt"
+    local_path = Path(dest_dir) / f"{url_hash}_{fname}"
+    if local_path.exists() and local_path.stat().st_size > 0:
+        return str(local_path)
+    with requests.get(url, stream=True, timeout=120) as r:
+        r.raise_for_status()
+        with open(local_path, "wb") as f:
+            for chunk in r.iter_content(chunk_size=1024 * 1024):
+                if chunk:
+                    f.write(chunk)
+    return str(local_path)
+
+
+def load_release_presets() -> dict:
+    """Load release preset URLs from multiple sources.
+    Order: Streamlit secrets → .streamlit/presets.json → presets.json → env var RELEASE_CKPTS_JSON.
+    Returns a dict name -> url. Safe if nothing is configured.
+    """
+    # 1) Streamlit secrets
+    try:
+        if hasattr(st, "secrets") and "release_checkpoints" in st.secrets:
+            # Convert to plain dict in case it's a Secrets object
+            return dict(st.secrets["release_checkpoints"])  # type: ignore[index]
+    except Exception:
+        pass
+
+    # 2) Local JSON files for dev
+    for rel in (".streamlit/presets.json", "presets.json"):
+        p = Path(rel)
+        if p.exists():
+            try:
+                with open(p, "r", encoding="utf-8") as f:
+                    data = json.load(f)
+                # Either the file is a mapping directly, or has a top-level key
+                if isinstance(data, dict) and data:
+                    if "release_checkpoints" in data and isinstance(data["release_checkpoints"], dict):
+                        return dict(data["release_checkpoints"])  # nested
+                    return dict(data)  # flat mapping
+            except Exception:
+                pass
+
+    # 3) Environment variable containing JSON mapping
+    env_json = os.environ.get("RELEASE_CKPTS_JSON", "").strip()
+    if env_json:
+        try:
+            data = json.loads(env_json)
+            if isinstance(data, dict):
+                return dict(data)
+        except Exception:
+            pass
+
+    return {}
+
+
+# ---------- Small utilities ----------
+def get_device(choice="auto"):
+    if choice == "cpu":
+        return "cpu"
+    if choice == "cuda":
+        return "cuda"
+    return "cuda" if torch.cuda.is_available() else "cpu"
+
+
+def find_latest_best_ckpt():
+    ckpts = sorted(
+        Path("checkpoints").rglob("best.ckpt"), key=lambda p: p.stat().st_mtime
+    )
+    return ckpts[-1] if ckpts else None
+
+
+def denorm_to_pil(x, mean, std):
+    """
+    x: torch.Tensor CxHxW (normalized), mean/std lists
+    returns PIL.Image (RGB)
+    """
+    x = x.detach().cpu().clone()
+    if len(mean) == 1:
+        # grayscale
+        m, s = float(mean[0]), float(std[0])
+        x = x * s + m  # de-normalize
+        x = x.clamp(0, 1)
+        # convert to RGB for overlay convenience
+        pil = T.ToPILImage()(x)
+        pil = pil.convert("RGB")
+        return pil
+    else:
+        mean = torch.tensor(mean)[:, None, None]
+        std = torch.tensor(std)[:, None, None]
+        x = x * std + mean
+        x = x.clamp(0, 1)
+        return T.ToPILImage()(x)
+
+
+DATASET_CLASSES = {
+    "fashion-mnist": [
+        "T-shirt/top",
+        "Trouser",
+        "Pullover",
+        "Dress",
+        "Coat",
+        "Sandal",
+        "Shirt",
+        "Sneaker",
+        "Bag",
+        "Ankle boot",
+    ],
+    "mnist": [str(i) for i in range(10)],
+    "cifar10": [
+        "airplane",
+        "automobile",
+        "bird",
+        "cat",
+        "deer",
+        "dog",
+        "frog",
+        "horse",
+        "ship",
+        "truck",
+    ],
+}
+
+
+@st.cache_resource
+def load_raw_dataset(name: str, root="data"):
+    """Load the test split with ToTensor() only (for preview)."""
+    tt = T.ToTensor()
+    if name == "fashion-mnist":
+        ds = FashionMNIST(root=root, train=False, download=True, transform=tt)
+    elif name == "mnist":
+        ds = MNIST(root=root, train=False, download=True, transform=tt)
+    elif name == "cifar10":
+        ds = CIFAR10(root=root, train=False, download=True, transform=tt)
+    else:
+        raise ValueError(f"Unknown dataset: {name}")
+    classes = getattr(ds, "classes", None) or [str(i) for i in range(10)]
+    return ds, classes
+
+
+def pil_from_tensor(img_tensor, grayscale_to_rgb=True):
+    pil = T.ToPILImage()(img_tensor)
+    if grayscale_to_rgb and img_tensor.ndim == 3 and img_tensor.shape[0] == 1:
+        pil = pil.convert("RGB")
+    return pil
+
+
+@st.cache_data(ttl=5, show_spinner=False)
+def list_ckpts(root_dir: str, recursive: bool = True, filter: str = ""):
+    """Return (labels, paths) sorted by mtime desc."""
+    root = Path(root_dir)
+    if not root.exists():
+        return [], []
+    files = sorted(
+        (root.rglob("*.ckpt") if recursive else root.glob("*.ckpt")),
+        key=lambda p: p.stat().st_mtime,
+        reverse=True,
+    )
+    files = [p for p in files if filter in str(p)]
+    labels = []
+    for p in files:
+        rel = p.relative_to(root)
+        mtime = dt.datetime.fromtimestamp(p.stat().st_mtime).strftime("%Y-%m-%d %H:%M")
+        labels.append(f"{rel}  •  {mtime}")
+    return labels, [str(p) for p in files]
+
+
+# ---------- Your SmallCNN (for FMNIST) ----------
+class SmallCNN(nn.Module):
+    def __init__(self, num_classes=10):
+        super().__init__()
+        self.conv1 = nn.Conv2d(1, 32, 3, padding=1)
+        self.pool1 = nn.MaxPool2d(2, 2)
+        self.conv2 = nn.Conv2d(32, 64, 3, padding=1)
+        self.pool2 = nn.MaxPool2d(2, 2)
+        self.fc = nn.Linear(64 * 7 * 7, num_classes)
+
+    def forward(self, x):
+        x = F.relu(self.conv1(x))
+        x = self.pool1(x)
+        x = F.relu(self.conv2(x))
+        x = self.pool2(x)
+        x = torch.flatten(x, 1)
+        return self.fc(x)
+
+
+# ---------- Load model + meta from checkpoint ----------
+def load_model_from_ckpt(ckpt_path: Path, device: str):
+    ckpt = torch.load(str(ckpt_path), map_location=device)
+    classes = ckpt.get("classes", None)
+    meta = ckpt.get("meta", {})
+    num_classes = len(classes) if classes else 10
+    model_name = meta.get("model_name", "smallcnn")
+
+    if model_name == "smallcnn":
+        model = SmallCNN(num_classes=num_classes).to(device)
+        default_target_layer = "conv2"
+    elif model_name == "resnet18_cifar":
+        m = tvm.resnet18(weights=None)
+        m.conv1 = nn.Conv2d(3, 64, kernel_size=3, stride=1, padding=1, bias=False)
+        m.maxpool = nn.Identity()
+        m.fc = nn.Linear(m.fc.in_features, num_classes)
+        model = m.to(device)
+        default_target_layer = "layer4"
+    elif model_name == "resnet18_imagenet":
+        try:
+            w = tvm.ResNet18_Weights.IMAGENET1K_V1
+        except Exception:
+            w = None
+        m = tvm.resnet18(weights=w)
+        m.fc = nn.Linear(m.fc.in_features, num_classes)
+        model = m.to(device)
+        default_target_layer = "layer4"
+    else:
+        raise ValueError(f"Unknown model_name in ckpt: {model_name}")
+
+    model.load_state_dict(ckpt["model_state"])
+    model.eval()
+    # ensure meta has defaults
+    meta.setdefault("default_target_layer", default_target_layer)
+    return model, classes, meta
+
+
+def build_transform_from_meta(meta):
+    img_size = int(meta.get("img_size", 28))
+    mean = meta.get("mean", [0.2860])  # FMNIST fallback
+    std = meta.get("std", [0.3530])
+    if len(mean) == 1:
+        return T.Compose(
+            [
+                T.Grayscale(num_output_channels=1),
+                T.Resize((img_size, img_size)),
+                T.ToTensor(),
+                T.Normalize(mean, std),
+            ]
+        )
+    else:
+        return T.Compose(
+            [
+                T.Resize((img_size, img_size)),
+                T.ToTensor(),
+                T.Normalize(mean, std),
+            ]
+        )
+
+
+def predict_and_cam(model, x, device, target_layer, topk=3, method="Grad-CAM"):
+    """
+    x: Tensor [1,C,H,W] normalized
+    returns: list of dicts: {rank, class_index, prob, cam_tensor(H,W)}
+    """
+    cam_cls = GradCAM if method == "Grad-CAM" else GradCAMpp
+    cam_extractor = cam_cls(model, target_layer=target_layer)
+
+    logits = model(x.to(device))
+    probs = torch.softmax(logits, dim=1)[0].detach().cpu()
+    top_vals, top_idxs = probs.topk(topk)
+
+    results = []
+    for rank, (p, idx) in enumerate(zip(top_vals.tolist(), top_idxs.tolist())):
+        retain = rank < topk - 1
+        cams = cam_extractor(idx, logits, retain_graph=retain)  # list
+        cam = cams[0].detach().cpu()  # [H,W] at feature-map resolution
+        results.append(
+            {"rank": rank + 1, "class_index": int(idx), "prob": float(p), "cam": cam}
+        )
+    return results, probs
+
+
+def overlay_pil(base_pil_rgb: Image.Image, cam_tensor, alpha=0.5):
+    # cam_tensor: torch.Tensor HxW in [0,1] (we'll min-max it)
+    cam = cam_tensor.clone()
+    cam -= cam.min()
+    cam = cam / (cam.max() + 1e-8)
+    heat = T.ToPILImage()(cam)  # single-channel PIL
+    return overlay_mask(base_pil_rgb, heat, alpha=alpha)
+
+
+# ---------- UI ----------
+st.set_page_config(page_title="Grad-CAM Demo", page_icon="🔍", layout="wide")
+st.title("🔍 Grad-CAM Demo — upload an image, get top-k + heatmaps")
+
+# Sidebar: checkpoint + options
+with st.sidebar:
+    st.header("Settings")
+
+    ckpt_path = st.session_state.get("ckpt_path")
+
+    st.subheader("Checkpoints")
+    # Remote download (presets or URL), saved automatically to saved_checkpoints/
+    presets = load_release_presets()
+    preset_names = list(presets.keys())
+    preset_sel = st.selectbox("Preset (GitHub Releases)", options=["(none)"] + preset_names, index=0) if preset_names else "(none)"
+    url_input = st.text_input("Or paste asset URL", value="")
+    if st.button("Download checkpoint", use_container_width=True):
+        url = presets.get(preset_sel, "") if preset_sel != "(none)" else url_input.strip()
+        if not url:
+            st.warning("Provide a preset or paste a URL")
+        else:
+            try:
+                path_dl = download_release_asset(url, dest_dir="saved_checkpoints")
+                st.success(f"Downloaded to: {path_dl}")
+                ckpt_path = path_dl
+                st.session_state["ckpt_path"] = ckpt_path
+                st.cache_data.clear()
+            except Exception as e:
+                st.error(f"Download failed: {e}")
+
+    # Upload a user-provided .ckpt directly in the online app
+    uploaded_ckpt = st.file_uploader("Upload checkpoint (.ckpt)", type=["ckpt"], accept_multiple_files=False)
+    if uploaded_ckpt is not None and st.button("Use uploaded checkpoint", use_container_width=True):
+        try:
+            Path("saved_checkpoints").mkdir(parents=True, exist_ok=True)
+            raw = uploaded_ckpt.read()
+            content_hash = hashlib.sha256(raw).hexdigest()[:16]
+            base_name = Path(uploaded_ckpt.name).name
+            if not base_name.endswith(".ckpt"):
+                base_name = f"{base_name}.ckpt"
+            local_path = Path("saved_checkpoints") / f"{content_hash}_{base_name}"
+            with open(local_path, "wb") as f:
+                f.write(raw)
+            ckpt_path = str(local_path)
+            st.session_state["ckpt_path"] = ckpt_path
+            st.success(f"Uploaded to: {ckpt_path}")
+            st.cache_data.clear()
+        except Exception as e:
+            st.error(f"Upload failed: {e}")
+
+    st.caption(f"Selected: {ckpt_path}")
+
+    with st.expander("Checkpoint meta preview", expanded=False):
+        try:
+            if ckpt_path:
+                m, c, meta_preview = load_model_from_ckpt(Path(ckpt_path), device="cpu")
+                st.json(
+                    {
+                        "dataset": meta_preview.get("dataset"),
+                        "model_name": meta_preview.get("model_name"),
+                        "img_size": meta_preview.get("img_size"),
+                        "target_layer": meta_preview.get("default_target_layer"),
+                    }
+                )
+            else:
+                st.info("No checkpoint selected yet.")
+        except Exception as e:
+            st.info(f"Could not read meta: {e}")
+
+    method = st.selectbox("CAM method", ["Grad-CAM", "Grad-CAM++"], index=0)
+    topk = st.slider("Top-k classes", min_value=1, max_value=10, value=3, step=1)
+    alpha = st.slider(
+        "Overlay alpha", min_value=0.1, max_value=0.9, value=0.5, step=0.05
+    )
+
+# Load model/meta
+if not ckpt_path or not Path(ckpt_path).exists():
+    st.info(
+        "First choose a checkpoint:\n"
+        "- Preset: pick from the list and click 'Download checkpoint'\n"
+        "- URL: paste a direct .ckpt URL and click 'Download checkpoint'\n"
+        "- Upload: select a .ckpt and click 'Use uploaded checkpoint'\n\n"
+        "After a checkpoint is selected, upload an image or use the sample picker to see predictions and Grad-CAM overlays."
+    )
+    st.stop()
+
+device = "cpu"
+model, classes, meta = load_model_from_ckpt(Path(ckpt_path), device)
+tf = build_transform_from_meta(meta)
+target_layer = meta.get("default_target_layer", "conv2")
+
+# Main: uploader
+# Main: uploader OR dataset sample
+st.subheader("1) Provide an image")
+uploaded = st.file_uploader(
+    "Upload PNG/JPG (or pick a sample below)", type=["png", "jpg", "jpeg"]
+)
+
+with st.expander("…or pick a sample from this model's dataset", expanded=False):
+    ds_default = meta.get("dataset", "fashion-mnist")
+    ds, ds_classes = load_raw_dataset(ds_default, root="data")
+    targets = np.array(getattr(ds, "targets", [ds[i][1] for i in range(len(ds))]))
+
+    # --- class filter (persisted) ---
+    class_opts = ["(any)"] + list(ds_classes)
+    class_sel = st.selectbox("Class filter", options=class_opts, index=0, key="class_sel")
+
+    if class_sel == "(any)":
+        filtered_idx = np.arange(len(ds))
+    else:
+        class_id = ds_classes.index(class_sel)
+        filtered_idx = np.nonzero(targets == class_id)[0]
+
+    # --- ensure we have a session index and keep it valid ---
+    if "sample_idx" not in st.session_state:
+        st.session_state["sample_idx"] = 0
+
+    # clamp when filter changes or dataset length is small
+    if len(filtered_idx) > 0:
+        st.session_state["sample_idx"] = int(
+            np.clip(st.session_state["sample_idx"], 0, len(filtered_idx) - 1)
+        )
+
+    if len(filtered_idx) == 0:
+        st.info("No samples found for this class.")
+        sample_img = None
+    else:
+        col_l, col_r = st.columns([2, 1])
+
+        with col_r:
+            picked = st.button("Pick random", use_container_width=True, key="btn_pick_random")
+            if picked:
+                # IMPORTANT: update session_state BEFORE creating the slider
+                cur = st.session_state["sample_idx"]
+                if len(filtered_idx) > 1:
+                    new_idx = random.randrange(len(filtered_idx) - 1)
+                    if new_idx >= cur:
+                        new_idx += 1
+                else:
+                    new_idx = 0
+                st.session_state["sample_idx"] = new_idx
+                # no st.rerun() needed; the app will rerun after the button
+
+        with col_l:
+            # Now instantiate the slider (AFTER any state changes above)
+            st.slider(
+                "Pick index (within filtered samples)",
+                0, max(0, len(filtered_idx) - 1),
+                key="sample_idx",  # same key as the state we set above
+            )
+
+        raw_idx = int(filtered_idx[st.session_state["sample_idx"]])
+        img_tensor, label = ds[raw_idx]
+        sample_img = pil_from_tensor(img_tensor, grayscale_to_rgb=True)
+
+        st.image(
+            sample_img,
+            caption=f"Sample • {ds_default} • class={ds_classes[label]} • idx={raw_idx}",
+            width=160,
+            use_container_width=False,
+        )
+
+# Decide the input image used downstream
+if uploaded is not None:
+    pil = Image.open(uploaded).convert("RGB")
+elif "sample_img" in locals() and sample_img is not None:
+    pil = sample_img
+else:
+    st.info("Upload an image or open the sample picker above.")
+    st.stop()
+
+col_in, col_cfg = st.columns([2, 1])
+
+with col_in:
+    if uploaded:
+        pil = Image.open(uploaded).convert("RGB")
+    elif sample_img is not None:
+        pil = sample_img
+    else:
+        st.info("Upload an image or check 'Use a sample image'.")
+        st.stop()
+
+    st.image(pil, caption="Input", use_container_width=True)
+
+with col_cfg:
+    st.markdown("**Model meta**")
+    st.json(
+        {
+            "dataset": meta.get("dataset"),
+            "model_name": meta.get("model_name"),
+            "img_size": meta.get("img_size"),
+            "target_layer": target_layer,
+            "mean": meta.get("mean"),
+            "std": meta.get("std"),
+            "classes": (
+                classes
+                if classes and len(classes) <= 10
+                else f"{len(classes) if classes else 'N/A'} classes"
+            ),
+        }
+    )
+
+# Prepare tensor + denormalized PIL base for overlay
+x = tf(pil)  # CxHxW normalized
+x_batched = x.unsqueeze(0)  # 1xCxHxW
+base_pil = denorm_to_pil(x, meta.get("mean", [0.2860]), meta.get("std", [0.3530]))
+
+# Predict + CAM
+with st.spinner("Running inference + Grad-CAM..."):
+    try:
+        cam_results, probs = predict_and_cam(
+            model, x_batched, device, target_layer, topk=topk, method=method
+        )
+    except Exception as e:
+        st.error(
+            f"Grad-CAM failed. Target layer likely incorrect."
+            f"\nLayer: {target_layer}\nError: {e}"
+        )
+        st.stop()
+
+# Top-k table
+st.subheader("2) Top-k predictions")
+rows = []
+for r in cam_results:
+    name = classes[r["class_index"]] if classes else str(r["class_index"])
+    rows.append(
+        {
+            "rank": r["rank"],
+            "class": name,
+            "index": r["class_index"],
+            "prob": round(r["prob"], 4),
+        }
+    )
+st.dataframe(rows, use_container_width=True)
+
+# Overlays
+st.subheader("3) Grad-CAM overlays")
+cols = st.columns(len(cam_results))
+for c, r in zip(cols, cam_results):
+    name = classes[r["class_index"]] if classes else str(r["class_index"])
+    ov = overlay_pil(base_pil, r["cam"], alpha=alpha)
+    with c:
+        st.image(
+            ov,
+            caption=f"Top{r['rank']}: {name} ({r['prob']:.3f})",
+            use_container_width=True,
+        )

configs/baseline.yaml

@@ -0,0 +1,20 @@
+dataset: fashion-mnist
+data_dir: ./data
+
+batch_size: 128
+epochs: 8
+lr: 0.001
+weight_decay: 0.0001
+num_workers: 2
+seed: 41
+device: auto
+
+log_root: runs
+ckpt_root: checkpoints
+reports_root: reports
+
+early_stop:
+  monitor: val_loss    # val_loss or val_acc
+  mode: min            # min for loss, max for acc
+  patience: 3
+  min_delta: 0.0

configs/cifar10_resnet18.yaml

@@ -0,0 +1,28 @@
+dataset: cifar10
+model_name: resnet18_cifar      # CIFAR variant (3×3 conv1, no maxpool)
+data_dir: ./data
+
+# training
+batch_size: 128
+epochs: 40
+lr: 0.001
+weight_decay: 0.0005
+num_workers: 2
+seed: 41
+device: auto
+
+# image + normalization (CIFAR-10 stats)
+img_size: 32
+mean: [0.4914, 0.4822, 0.4465]
+std:  [0.2470, 0.2435, 0.2616]
+
+# logging+artifacts
+log_root: runs
+ckpt_root: checkpoints
+reports_root: reports
+
+early_stop:
+  monitor: val_loss
+  mode: min
+  patience: 5
+  min_delta: 0.0

configs/cifar10_resnet18_adam.yaml

@@ -0,0 +1,27 @@
+dataset: cifar10
+model_name: resnet18_cifar
+data_dir: ./data
+
+batch_size: 128
+epochs: 40
+lr: 0.001          # Adam baseline
+weight_decay: 0.0005
+optimizer: adam        # or sgd
+momentum: 0.9
+num_workers: 2
+seed: 41
+device: auto
+
+img_size: 32
+mean: [0.4914, 0.4822, 0.4465]
+std:  [0.2470, 0.2435, 0.2616]
+
+log_root: runs
+ckpt_root: checkpoints
+reports_root: reports
+
+early_stop:
+  monitor: val_loss
+  mode: min
+  patience: 5
+  min_delta: 0.0

configs/cifar10_resnet18_imagenet.yaml

@@ -0,0 +1,26 @@
+dataset: cifar10
+model_name: resnet18_imagenet   # ImageNet-pretrained; resize to 224
+data_dir: ./data
+
+batch_size: 128
+epochs: 20
+lr: 0.0005
+weight_decay: 0.0005
+num_workers: 2
+seed: 41
+device: auto
+
+# image + normalization (ImageNet stats)
+img_size: 224
+mean: [0.485, 0.456, 0.406]
+std:  [0.229, 0.224, 0.225]
+
+log_root: runs
+ckpt_root: checkpoints
+reports_root: reports
+
+early_stop:
+  monitor: val_loss
+  mode: min
+  patience: 5
+  min_delta: 0.0

configs/cifar10_resnet18_sgd.yaml

@@ -0,0 +1,27 @@
+dataset: cifar10
+model_name: resnet18_cifar
+data_dir: ./data
+
+batch_size: 128
+epochs: 60
+lr: 0.1            # classic SGD start
+weight_decay: 0.0005
+optimizer: adam        # or sgd
+momentum: 0.9
+num_workers: 2
+seed: 41
+device: auto
+
+img_size: 32
+mean: [0.4914, 0.4822, 0.4465]
+std:  [0.2470, 0.2435, 0.2616]
+
+log_root: runs
+ckpt_root: checkpoints
+reports_root: reports
+
+early_stop:
+  monitor: val_loss
+  mode: min
+  patience: 8
+  min_delta: 0.0

configs/fmnist_smallcnn.yaml

@@ -0,0 +1,25 @@
+dataset: fashion-mnist
+model_name: smallcnn
+data_dir: ./data
+
+batch_size: 128
+epochs: 8
+lr: 0.001
+weight_decay: 0.0001
+num_workers: 2
+seed: 41
+device: auto
+
+img_size: 28
+mean: [0.2860]
+std:  [0.3530]
+
+log_root: runs
+ckpt_root: checkpoints
+reports_root: reports
+
+early_stop:
+  monitor: val_loss
+  mode: min
+  patience: 3
+  min_delta: 0.0

configs/fmnist_smallcnn_aug.yaml

@@ -0,0 +1,25 @@
+dataset: fashion-mnist
+model_name: smallcnn
+data_dir: ./data
+
+batch_size: 128
+epochs: 12
+lr: 0.001
+weight_decay: 0.0001
+num_workers: 2
+seed: 41
+device: auto
+
+img_size: 28
+mean: [0.2860]
+std:  [0.3530]
+
+log_root: runs
+ckpt_root: checkpoints
+reports_root: reports
+
+early_stop:
+  monitor: val_loss
+  mode: min
+  patience: 3
+  min_delta: 0.0

requirements-gpu.txt

@@ -0,0 +1,19 @@
+# GPU build (install torch/torchvision/torchaudio separately per https://pytorch.org/get-started/locally/)
+# Example (CUDA 12.1):
+#   pip install --index-url https://download.pytorch.org/whl/cu121 torch torchvision torchaudio
+
+# Core libs (do NOT pin torch* here; users install matching CUDA builds first)
+torchmetrics
+torchcam
+captum
+lightning
+albumentations
+opencv-python-headless
+matplotlib
+seaborn
+tensorboard
+rich
+PyYAML
+streamlit
+requests
+gradio

requirements.txt

@@ -0,0 +1,21 @@
+# Use CPU-only PyTorch wheels from the official index
+--extra-index-url https://download.pytorch.org/whl/cpu
+torch==2.2.2+cpu
+torchvision==0.17.2+cpu
+torchaudio==2.2.2+cpu
+torchmetrics
+torchcam
+captum
+# Lightning (pytorch-lightning older alias still works but this is preferred)
+lightning
+albumentations
+# Headless OpenCV for servers without GUI
+opencv-python-headless
+matplotlib
+seaborn
+tensorboard
+rich
+PyYAML
+streamlit
+requests
+gradio

runtime.txt

@@ -0,0 +1,2 @@
+python-3.11
+

src/explain.py

@@ -0,0 +1,236 @@
+import argparse
+import json
+from pathlib import Path
+
+import torch
+import torch.nn as nn
+import torchvision.transforms.functional as TF
+from PIL import Image
+from torchcam.methods import GradCAM
+from torchcam.utils import overlay_mask
+from torchvision import models as tvm
+from torchvision import transforms
+
+from src.train import SmallCNN, get_device
+
+
+def build_argparser():
+    p = argparse.ArgumentParser(description="Grad-CAM explanations")
+    p.add_argument("--ckpt", type=str, required=True, help="Path to best.ckpt")
+    p.add_argument("--image", type=str, required=True, help="Path to an input image")
+    p.add_argument(
+        "--dataset",
+        choices=["fashion-mnist", "mnist", "cifar10"],
+        default="fashion-mnist",
+        help="Used to apply the right normalization and class names",
+    )
+    p.add_argument(
+        "--target-layer",
+        type=str,
+        default="conv2",
+        help="Layer to attach CAMs (e.g., 'conv2' for SmallCNN, 'layer4' for ResNet)",
+    )
+    p.add_argument(
+        "--outdir",
+        type=str,
+        default=None,
+        help="Where to store results; defaults near the checkpoint",
+    )
+    p.add_argument("--device", choices=["auto", "cpu", "cuda"], default="auto")
+    p.add_argument("--topk", type=int, default=3, help="How many top classes to render")
+    return p
+
+
+def get_transforms_from_meta(meta):
+    img_size = int(meta.get("img_size", 28))
+    mean = meta.get("mean", [0.2860])  # fallback FMNIST
+    std = meta.get("std", [0.3530])
+
+    # channels: grayscale if mean/std length==1, else RGB
+    if len(mean) == 1:
+        tf = transforms.Compose(
+            [
+                transforms.Grayscale(num_output_channels=1),
+                transforms.Resize((img_size, img_size)),
+                transforms.ToTensor(),
+                transforms.Normalize(mean, std),
+            ]
+        )
+    else:
+        tf = transforms.Compose(
+            [
+                transforms.Resize((img_size, img_size)),
+                transforms.ToTensor(),
+                transforms.Normalize(mean, std),
+            ]
+        )
+    return tf
+
+
+def denorm_to_pil(x: torch.Tensor, mean, std) -> Image.Image:
+    """
+    x: normalized tensor CxHxW
+    mean/std: list(s) from meta
+    returns: PIL RGB image for overlay
+    """
+    x = x.detach().cpu().clone()
+    if len(mean) == 1:  # grayscale
+        m, s = float(mean[0]), float(std[0])
+        x = x * s + m
+        x = x.clamp(0, 1)
+        pil = transforms.ToPILImage()(x)  # grayscale PIL
+        return pil.convert("RGB")
+    else:  # RGB
+        mean_t = torch.tensor(mean)[:, None, None]
+        std_t = torch.tensor(std)[:, None, None]
+        x = x * std_t + mean_t
+        x = x.clamp(0, 1)
+        return transforms.ToPILImage()(x)
+
+
+def load_model(ckpt_path, device):
+    ckpt = torch.load(ckpt_path, map_location=device)
+    classes = ckpt.get("classes", None)
+    meta = ckpt.get("meta", {})
+    num_classes = len(classes) if classes else 10
+    model_name = meta.get("model_name", "smallcnn")
+
+    if model_name == "smallcnn":
+        model = SmallCNN(num_classes=num_classes).to(device)
+    elif model_name == "resnet18_cifar":
+        m = tvm.resnet18(weights=None)
+        m.conv1 = nn.Conv2d(3, 64, kernel_size=3, stride=1, padding=1, bias=False)
+        m.maxpool = nn.Identity()
+        m.fc = nn.Linear(m.fc.in_features, num_classes)
+        model = m.to(device)
+    elif model_name == "resnet18_imagenet":
+        try:
+            w = tvm.ResNet18_Weights.IMAGENET1K_V1
+        except Exception:
+            w = None
+        m = tvm.resnet18(weights=w)
+        m.fc = nn.Linear(m.fc.in_features, num_classes)
+        model = m.to(device)
+    else:
+        raise ValueError(f"Unknown model in ckpt: {model_name}")
+
+    model.load_state_dict(ckpt["model_state"])
+    model.eval()
+    return model, classes, meta
+
+
+def run_gradcam(
+    model,
+    target_layer,
+    img_tensor,
+    device,
+    classes,
+    outdir: Path,
+    topk=3,
+    base_pil_rgb: Image.Image = None,
+):
+    """
+    img_tensor: CxHxW normalized (not batched)
+    base_pil_rgb: PIL image already denormalized & RGB for overlay (optional).
+                  If None, will min-max scale from img_tensor (last-resort).
+    """
+    model.eval()
+    x = img_tensor.to(device).unsqueeze(0)  # [1,C,H,W]
+    H, W = img_tensor.shape[-2:]
+    cam_extractor = GradCAM(model, target_layer=target_layer)
+
+    # forward once to get top-k
+    logits = model(x)
+    probs = torch.softmax(logits, dim=1)[0].detach().cpu()
+    top_vals, top_idxs = probs.topk(topk)
+
+    if base_pil_rgb is None:
+        # Fallback: simple min-max scaling (works but less faithful than denorm)
+        xx = img_tensor.detach().cpu()
+        xx = (xx - xx.min()) / (xx.max() - xx.min() + 1e-8)
+        base_pil_rgb = transforms.ToPILImage()(xx)
+        if xx.shape[0] == 1:
+            base_pil_rgb = base_pil_rgb.convert("RGB")
+
+    results = []
+    for rank, (score, cls_idx) in enumerate(zip(top_vals.tolist(), top_idxs.tolist())):
+        retain = rank < topk - 1
+        cams = cam_extractor(int(cls_idx), logits, retain_graph=retain)
+        cam = cams[0].detach().cpu()  # [h,w]
+        cam_up = TF.resize(cam.unsqueeze(0), size=[H, W])[0]  # upsample to input size
+
+        heat = transforms.ToPILImage()(cam_up)
+        overlay = overlay_mask(base_pil_rgb, heat, alpha=0.6)
+
+        out_png = (
+            outdir / f"gradcam_top{rank+1}_class{cls_idx}_"
+            + f"{classes[cls_idx] if classes else cls_idx}.png"
+        )
+        overlay.save(out_png)
+
+        results.append(
+            {
+                "rank": rank + 1,
+                "class_index": int(cls_idx),
+                "class_name": classes[cls_idx] if classes else str(cls_idx),
+                "prob": float(score),
+                "file": str(out_png),
+            }
+        )
+
+    with open(outdir / "summary.json", "w") as f:
+        json.dump({"topk": results}, f, indent=2)
+
+    print("Saved:", outdir)
+    return results
+
+
+def main():
+    args = build_argparser().parse_args()
+    device = get_device(args.device)
+
+    ckpt_path = Path(args.ckpt)
+
+    # outdir default
+    if args.outdir is None:
+        run_id = ckpt_path.parent.name
+        outdir = ckpt_path.parent.parent.parent / "reports" / run_id / "explain"
+    else:
+        outdir = Path(args.outdir)
+    outdir.mkdir(parents=True, exist_ok=True)
+
+    # 1) load model+meta first
+    model, classes, meta = load_model(str(ckpt_path), device)
+
+    # 2) build tf from meta
+    tf = get_transforms_from_meta(meta)
+
+    # 3) load and transform image
+    pil = Image.open(args.image).convert("RGB")
+    x = tf(pil)  # CxHxW normalized
+
+    # 4) make a denormalized RGB base image for overlay
+    base_pil = denorm_to_pil(x, meta.get("mean", [0.2860]), meta.get("std", [0.3530]))
+
+    # 5) target layer (CLI overrides meta default)
+    target_layer = args.target_layer or meta.get("default_target_layer", "conv2")
+
+    # 6) run Grad-CAM
+    results = run_gradcam(
+        model,
+        target_layer,
+        x,
+        device,
+        classes,
+        outdir,
+        topk=args.topk,
+        base_pil_rgb=base_pil,
+    )
+
+    # 7) print summary
+    for r in results:
+        print(f"Top{r['rank']}: {r['class_name']} ({r['prob']:.3f}) -> {r['file']}")
+
+
+if __name__ == "__main__":
+    main()

src/simCLR.py

@@ -0,0 +1,134 @@
+import os
+from pathlib import Path
+
+import torch
+from torch import nn
+from torch.utils.data import DataLoader
+from torchvision import models as tvm
+from torchvision.datasets import ImageFolder
+
+from lightly.loss import NTXentLoss
+from lightly.models.modules import SimCLRProjectionHead
+from lightly.transforms.simclr_transform import SimCLRTransform
+from torch.optim.lr_scheduler import LambdaLR
+
+# ----------------------------
+# Config
+# ----------------------------
+DATA_ROOT = "data/eurosat_custom/train"   # prepared split (train only, unlabeled)
+BATCH_SIZE = 256
+EPOCHS = 150
+LR = 0.06
+NUM_WORKERS = 8
+IMG_SIZE = 224             # resize inside transform
+OUT_DIR = Path("checkpoints_ssl")
+OUT_DIR.mkdir(parents=True, exist_ok=True)
+warmup_epochs = 10
+total_epochs = EPOCHS
+
+def lr_lambda(epoch):
+    if epoch < warmup_epochs:
+        return float(epoch + 1) / warmup_epochs
+    progress = (epoch - warmup_epochs) / float(total_epochs - warmup_epochs)
+    return 0.5 * (1.0 + torch.cos(torch.pi * progress))
+
+scheduler = LambdaLR(optimizer, lr_lambda=lr_lambda)
+
+device = "cuda" if torch.cuda.is_available() else "cpu"
+use_amp = torch.cuda.is_available()  # mixed precision if GPU
+
+
+# ----------------------------
+# Model: ResNet18 encoder + SimCLR projection head
+# ----------------------------
+class SimCLR(nn.Module):
+    def __init__(self, backbone, in_dim=512, proj_hidden=512, proj_out=128):
+        super().__init__()
+        self.backbone = backbone
+        self.projection_head = SimCLRProjectionHead(in_dim, proj_hidden, proj_out)
+
+    def forward(self, x):
+        # backbone assumed to output [N, C, 1, 1] after global pooling
+        x = self.backbone(x).flatten(start_dim=1)
+        z = self.projection_head(x)
+        return z
+
+# Build a torchvision resnet18 backbone without the FC layer
+resnet = tvm.resnet18(weights=None)
+# replace avgpool+fc stack with Identity + keep global avgpool:
+# torchvision resnet18 returns features after avgpool as 512-d before fc.
+backbone = nn.Sequential(*list(resnet.children())[:-1])  # until avgpool, outputs [N,512,1,1]
+model = SimCLR(backbone, in_dim=512, proj_hidden=512, proj_out=128).to(device)
+
+
+# ----------------------------
+# Data: EuroSAT train images as unlabeled pairs of views
+# ----------------------------
+# SimCLR default normalization in Lightly is ImageNet stats; perfect for ResNet18 at 224.
+transform = SimCLRTransform(
+    input_size=IMG_SIZE,
+    gaussian_blur=0.1,        # EuroSAT is small; mild blur helps but keep modest
+    cj_strength=0.5,          # color jitter strength
+)
+
+dataset = ImageFolder(DATA_ROOT, transform=transform)
+# ImageFolder returns ( (v1, v2), label ) because transform yields two views.
+# We'll ignore labels during pretraining.
+loader = DataLoader(
+    dataset,
+    batch_size=BATCH_SIZE,
+    shuffle=True,
+    drop_last=True,
+    num_workers=NUM_WORKERS,
+    pin_memory=torch.cuda.is_available(),
+)
+
+
+# ----------------------------
+# Objective & Optimizer
+# ----------------------------
+criterion = NTXentLoss(temperature=0.5)   # standard SimCLR temperature
+optimizer = torch.optim.SGD(model.parameters(), lr=LR, momentum=0.9, weight_decay=1e-4)
+
+scaler = torch.cuda.amp.GradScaler(enabled=use_amp)
+
+
+# ----------------------------
+# Training loop
+# ----------------------------
+print(f"Starting SimCLR pretraining on {device} for {EPOCHS} epochs…")
+model.train()
+for epoch in range(1, EPOCHS + 1):
+    total_loss = 0.0
+    for (v1, v2), _ in loader:      # labels are unused
+        v1 = v1.to(device, non_blocking=True)
+        v2 = v2.to(device, non_blocking=True)
+
+        optimizer.zero_grad(set_to_none=True)
+
+        with torch.cuda.amp.autocast(enabled=use_amp):
+            z1 = model(v1)
+            z2 = model(v2)
+            loss = criterion(z1, z2)
+
+        scaler.scale(loss).backward()
+        scaler.step(optimizer)
+        scaler.update()
+
+        total_loss += loss.detach().item()
+
+    avg_loss = total_loss / len(loader)
+    current_lr = scheduler.get_last_lr()[0]
+    print(f"epoch {epoch:03d} | loss {avg_loss:.5f} | lr {current_lr:.5f}")
+
+    scheduler.step()
+
+    # (optional) save checkpoints every N epochs
+    if epoch % 25 == 0 or epoch == EPOCHS:
+        # save only the encoder (backbone) weights for fine-tuning
+        enc_state = {k.replace("backbone.", "", 1): v
+                     for k, v in model.state_dict().items()
+                     if k.startswith("backbone.")}
+        torch.save(enc_state, OUT_DIR / f"simclr_resnet18_eurosat_epoch{epoch}.pt")
+
+print("Done.")

src/train.py

@@ -0,0 +1,583 @@
+import argparse
+import json
+import time
+from copy import deepcopy
+from pathlib import Path
+
+import matplotlib.pyplot as plt
+import numpy as np
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+import torch.optim as optim
+import torchvision as tv
+import torchvision.models as models
+import yaml
+from torch.utils.data import DataLoader
+from torch.utils.tensorboard import SummaryWriter
+from torchmetrics.classification import MulticlassConfusionMatrix
+from torchvision import transforms
+from torchvision.datasets import ImageFolder
+
+
+# ----------------- argparse -----------------
+def build_argparser():
+    p = argparse.ArgumentParser(description="Train a small CNN on MNIST/Fashion-MNIST")
+    p.add_argument(
+        "--dataset", choices=["fashion-mnist", "mnist", "cifar10"], default="fashion-mnist"
+    )
+    p.add_argument("--data-dir", type=str, default="./data")
+    p.add_argument("--batch-size", type=int, default=128)
+    p.add_argument("--epochs", type=int, default=8)
+    p.add_argument("--lr", type=float, default=1e-3)
+    p.add_argument("--weight-decay", type=float, default=1e-4)
+    p.add_argument("--num-workers", type=int, default=2)
+    p.add_argument("--seed", type=int, default=41)
+    p.add_argument("--device", choices=["auto", "cpu", "cuda"], default="auto")
+    # legacy path args (we’ll map them into roots if provided)
+    p.add_argument("--logdir", type=str, default=None)
+    p.add_argument("--ckpt", type=str, default=None)
+    p.add_argument("--metrics", type=str, default=None)
+    p.add_argument("--reports-dir", type=str, default=None)
+    # config
+    p.add_argument(
+        "--config",
+        type=str,
+        default="configs/baseline.yaml",
+        help="Path to YAML config with defaults",
+    )
+    p.add_argument(
+        "--model-name",
+        type=str,
+        default=None,
+        choices=["smallcnn", "resnet18_cifar", "resnet18_imagenet"],
+        help="Choose model architecture",
+    )
+    return p
+
+
+# ----------------- small utils -----------------
+def get_device(choice: str) -> str:
+    if choice == "cpu":
+        return "cpu"
+    if choice == "cuda":
+        return "cuda"
+    return "cuda" if torch.cuda.is_available() else "cpu"
+
+
+def seed_all(seed: int):
+    import random
+
+    import numpy as np
+
+    random.seed(seed)
+    np.random.seed(seed)
+    torch.manual_seed(seed)
+    torch.cuda.manual_seed_all(seed)
+    torch.backends.cudnn.deterministic = True
+    torch.backends.cudnn.benchmark = False
+
+
+def accuracy(logits, targets):
+    preds = logits.argmax(dim=1)
+    return (preds == targets).float().mean().item()
+
+
+def load_yaml(path: str) -> dict:
+    with open(path, "r") as f:
+        return yaml.safe_load(f)
+
+
+def merge_cli_over_config_with_defaults(cfg, args, parser):
+    cfg = deepcopy(cfg)
+    defaults = parser.parse_args([])  # argparse defaults only
+    for arg_name, cfg_key in [
+        ("dataset", "dataset"),
+        ("data_dir", "data_dir"),
+        ("batch_size", "batch_size"),
+        ("epochs", "epochs"),
+        ("lr", "lr"),
+        ("weight_decay", "weight_decay"),
+        ("num_workers", "num_workers"),
+        ("seed", "seed"),
+        ("device", "device"),
+        ("logdir", "log_root"),
+        ("ckpt", "ckpt_root"),
+        ("metrics", "reports_root"),
+        ("reports_dir", "reports_root"),
+        ("model_name", "model_name"),
+    ]:
+        val = getattr(args, arg_name)
+        defval = getattr(defaults, arg_name)
+        if val is not None and val != defval:
+            if arg_name == "ckpt":
+                cfg[cfg_key] = str(Path(val).parent)
+            elif arg_name in ("metrics", "reports_dir"):
+                cfg[cfg_key] = str(Path(val).parent)
+            else:
+                cfg[cfg_key] = val
+    cfg["_config_path"] = args.config
+    return cfg
+
+
+def is_improved(best_value, current, mode: str, min_delta: float) -> bool:
+    if mode == "min":
+        return current < (best_value - min_delta)
+    return current > (best_value + min_delta)
+
+
+def save_checkpoint(payload: dict, path: Path):
+    torch.save(payload, str(path))
+
+
+# ----------------- model -----------------
+class SmallCNN(nn.Module):
+    def __init__(self, num_classes: int = 10):
+        super().__init__()
+        self.conv1 = nn.Conv2d(1, 32, 3, padding=1)
+        self.pool1 = nn.MaxPool2d(2, 2)
+        self.conv2 = nn.Conv2d(32, 64, 3, padding=1)
+        self.pool2 = nn.MaxPool2d(2, 2)
+        self.fc = nn.Linear(64 * 7 * 7, num_classes)
+
+    def forward(self, x):
+        x = F.relu(self.conv1(x))
+        x = self.pool1(x)
+        x = F.relu(self.conv2(x))
+        x = self.pool2(x)
+        x = torch.flatten(x, 1)
+        return self.fc(x)  # logits
+
+
+def build_model(model_name: str, num_classes: int, img_size: int):
+    """
+    Returns (model, default_target_layer)
+    """
+    if model_name == "smallcnn":
+        m = SmallCNN(num_classes=num_classes)
+        return m, "conv2"
+
+    if model_name == "resnet18_cifar":
+        # Start from vanilla resnet18 but adapt for CIFAR (32x32)
+        m = models.resnet18(weights=None)
+        # 3x3 conv, stride=1, padding=1 instead of 7x7/stride=2, and remove maxpool
+        m.conv1 = nn.Conv2d(3, 64, kernel_size=3, stride=1, padding=1, bias=False)
+        m.maxpool = nn.Identity()
+        # replace classifier
+        m.fc = nn.Linear(m.fc.in_features, num_classes)
+        return m, "layer4"
+
+    if model_name == "resnet18_imagenet":
+        # Use ImageNet weights and resize input to 224
+        try:
+            w = models.ResNet18_Weights.IMAGENET1K_V1
+        except Exception:
+            w = None
+        m = models.resnet18(weights=w)
+        m.fc = nn.Linear(m.fc.in_features, num_classes)
+        return m, "layer4"
+
+    raise ValueError(f"Unknown model_name: {model_name}")
+
+
+# ----------------- data -----------------
+def get_transforms_for(dataset_name: str, img_size: int, mean, std, train: bool):
+    tfms = []
+    if dataset_name in {"cifar10"}:
+        if train:
+            # light augments for CIFAR
+            if img_size == 32:
+                tfms += [
+                    transforms.RandomCrop(32, padding=4),
+                    transforms.RandomHorizontalFlip(),
+                ]
+            else:
+                tfms += [
+                    transforms.Resize((img_size, img_size)),
+                    transforms.RandomHorizontalFlip(),
+                ]
+        else:
+            tfms += [transforms.Resize((img_size, img_size))]
+        tfms += [transforms.ToTensor(), transforms.Normalize(mean, std)]
+        return transforms.Compose(tfms)
+    
+    
+
+    # fashion-mnist / mnist (grayscale)
+    # fashion-mnist / mnist (grayscale)
+    m, s = float(mean[0]), float(std[0])
+    tfms = [transforms.ToTensor(), transforms.Normalize((m,), (s,))]
+    return transforms.Compose(tfms)
+
+
+def get_dataloaders(
+    dataset_name: str,
+    data_dir: str,
+    batch_size: int,
+    num_workers: int,
+    seed: int,
+    img_size: int,
+    mean,
+    std,
+):
+    root = Path(data_dir)
+    g = torch.Generator().manual_seed(seed)
+
+    if dataset_name == "fashion-mnist":
+        train_tf = get_transforms_for("fashion-mnist", img_size, mean, std, train=True)
+        eval_tf  = get_transforms_for("fashion-mnist", img_size, mean, std, train=False)
+        train_ds = tv.datasets.FashionMNIST(root=root, train=True,  download=True, transform=train_tf)
+        test_ds  = tv.datasets.FashionMNIST(root=root, train=False, download=True, transform=eval_tf)
+
+        train_loader = DataLoader(train_ds, batch_size=batch_size, shuffle=True,  num_workers=num_workers, generator=g)
+        val_loader   = DataLoader(test_ds,  batch_size=batch_size, shuffle=False, num_workers=num_workers)
+        test_loader  = DataLoader(test_ds,  batch_size=batch_size, shuffle=False, num_workers=num_workers)
+        classes = train_ds.classes
+        return train_loader, val_loader, test_loader, classes
+
+    elif dataset_name == "mnist":
+        train_tf = get_transforms_for("mnist", img_size, mean, std, train=True)
+        eval_tf  = get_transforms_for("mnist", img_size, mean, std, train=False)
+        train_ds = tv.datasets.MNIST(root=root, train=True,  download=True, transform=train_tf)
+        test_ds  = tv.datasets.MNIST(root=root, train=False, download=True, transform=eval_tf)
+
+        train_loader = DataLoader(train_ds, batch_size=batch_size, shuffle=True,  num_workers=num_workers, generator=g)
+        val_loader   = DataLoader(test_ds,  batch_size=batch_size, shuffle=False, num_workers=num_workers)
+        test_loader  = DataLoader(test_ds,  batch_size=batch_size, shuffle=False, num_workers=num_workers)
+        classes = train_ds.classes
+        return train_loader, val_loader, test_loader, classes
+
+    elif dataset_name == "cifar10":
+        train_tf = get_transforms_for("cifar10", img_size, mean, std, train=True)
+        eval_tf  = get_transforms_for("cifar10", img_size, mean, std, train=False)
+        train_ds = tv.datasets.CIFAR10(root=root, train=True,  download=True, transform=train_tf)
+        test_ds  = tv.datasets.CIFAR10(root=root, train=False, download=True, transform=eval_tf)
+
+        train_loader = DataLoader(train_ds, batch_size=batch_size, shuffle=True,  num_workers=num_workers, generator=g)
+        val_loader   = DataLoader(test_ds,  batch_size=batch_size, shuffle=False, num_workers=num_workers)
+        test_loader  = DataLoader(test_ds,  batch_size=batch_size, shuffle=False, num_workers=num_workers)
+        classes = train_ds.classes
+        return train_loader, val_loader, test_loader, classes
+
+    
+
+    else:
+        raise ValueError(f"Unsupported dataset: {dataset_name}")
+
+
+# ----------------- train/eval -----------------
+def train_one_epoch(model, loader, device, optimizer, loss_fn):
+    model.train()
+    loss_sum = 0.0
+    acc_sum = 0.0
+    n = 0
+    for xb, yb in loader:
+        xb, yb = xb.to(device), yb.to(device)
+        optimizer.zero_grad()
+        logits = model(xb)
+        loss = loss_fn(logits, yb)
+        loss.backward()
+        optimizer.step()
+        b = yb.size(0)
+        loss_sum += loss.item() * b
+        acc_sum += accuracy(logits, yb) * b
+        n += b
+    return loss_sum / n, acc_sum / n
+
+
+@torch.no_grad()
+def eval_one_epoch(model, loader, device, loss_fn):
+    model.eval()
+    loss_sum = 0.0
+    acc_sum = 0.0
+    n = 0
+    for xb, yb in loader:
+        xb, yb = xb.to(device), yb.to(device)
+        logits = model(xb)
+        loss = loss_fn(logits, yb)
+        b = yb.size(0)
+        loss_sum += loss.item() * b
+        acc_sum += accuracy(logits, yb) * b
+        n += b
+    return loss_sum / n, acc_sum / n
+
+
+@torch.no_grad()
+def confusion_matrix_report(
+    model,
+    test_loader,
+    device,
+    classes,
+    reports_dir: Path,
+    metrics_path: Path,
+    title_prefix: str,
+):
+    model.eval()
+    all_preds, all_targets = [], []
+    for xb, yb in test_loader:
+        xb = xb.to(device)
+        logits = model(xb)
+        preds = logits.argmax(dim=1).cpu()
+        all_preds.append(preds)
+        all_targets.append(yb)
+    all_preds = torch.cat(all_preds)
+    all_targets = torch.cat(all_targets)
+
+    num_classes = len(classes)
+    cm_metric = MulticlassConfusionMatrix(num_classes=num_classes)
+    cm = cm_metric(all_preds, all_targets).numpy()
+    cm_norm = cm / cm.sum(axis=1, keepdims=True)
+
+    reports_dir.mkdir(parents=True, exist_ok=True)
+    fig, ax = plt.subplots(figsize=(7, 6))
+    im = ax.imshow(cm_norm, interpolation="nearest")
+    ax.figure.colorbar(im, ax=ax)
+    ax.set(
+        xticks=np.arange(num_classes),
+        yticks=np.arange(num_classes),
+        xticklabels=classes,
+        yticklabels=classes,
+        ylabel="True label",
+        xlabel="Predicted label",
+        title=f"{title_prefix} Confusion Matrix (row-normalized)",
+    )
+    plt.setp(ax.get_xticklabels(), rotation=45, ha="right", rotation_mode="anchor")
+    for i in range(num_classes):
+        for j in range(num_classes):
+            ax.text(
+                j, i, f"{cm_norm[i, j]*100:.1f}%", ha="center", va="center", fontsize=8
+            )
+    fig.tight_layout()
+    fig_path = reports_dir / "confusion_matrix.png"
+    plt.savefig(fig_path, dpi=200)
+    plt.close(fig)
+    print("Saved figure to:", fig_path)
+
+    np.save(reports_dir / "confusion_matrix_counts.npy", cm)
+    np.save(reports_dir / "confusion_matrix_norm.npy", cm_norm)
+
+    try:
+        with open(metrics_path) as f:
+            metrics = json.load(f)
+    except FileNotFoundError:
+        metrics = {}
+    metrics.update(
+        {
+            "confusion_matrix_counts_path": str(
+                reports_dir / "confusion_matrix_counts.npy"
+            ),
+            "confusion_matrix_norm_path": str(
+                reports_dir / "confusion_matrix_norm.npy"
+            ),
+            "confusion_matrix_figure": str(fig_path),
+        }
+    )
+    with open(metrics_path, "w") as f:
+        json.dump(metrics, f, indent=2)
+
+
+# ----------------- main -----------------
+def main():
+    parser = build_argparser()
+    args = parser.parse_args()
+    seed_all(args.seed)
+
+    base_cfg = load_yaml(args.config)
+    cfg = merge_cli_over_config_with_defaults(base_cfg, args, parser)
+
+    dataset = cfg["dataset"]
+    model_name = cfg.get("model_name", "smallcnn")
+
+    img_size = int(
+        cfg.get("img_size", 28 if dataset in ["fashion-mnist", "mnist"] else 32)
+    )
+    mean = cfg.get("mean", None)
+    std = cfg.get("std", None)
+
+    # defaults for grayscale datasets
+    if dataset in ["fashion-mnist", "mnist"]:
+        if mean is None or std is None:
+            if dataset == "fashion-mnist":
+                mean, std = [0.2860], [0.3530]
+            else:
+                mean, std = [0.1307], [0.3081]
+    # defaults for cifar10
+    if dataset == "cifar10" and (mean is None or std is None):
+        mean, std = [0.4914, 0.4822, 0.4465], [0.2470, 0.2435, 0.2616]
+
+    
+
+    device = get_device(cfg["device"])
+    print("device:", device)
+
+    run_id = f'{cfg["dataset"]}_{int(time.time())}'
+    LOG_DIR = Path(cfg["log_root"]) / run_id
+    CKPTS_DIR = Path(cfg["ckpt_root"]) / run_id
+    REPORTS_DIR = Path(cfg["reports_root"]) / run_id
+    for d in (LOG_DIR, CKPTS_DIR, REPORTS_DIR):
+        d.mkdir(parents=True, exist_ok=True)
+
+    effective_cfg = deepcopy(cfg)
+    effective_cfg["run_id"] = run_id
+    with open(REPORTS_DIR / "config_effective.yaml", "w") as f:
+        yaml.safe_dump(effective_cfg, f)
+
+    train_loader, val_loader, test_loader, classes = get_dataloaders(
+        dataset,
+        cfg["data_dir"],
+        cfg["batch_size"],
+        cfg["num_workers"],
+        cfg["seed"],
+        img_size,
+        mean,
+        std,
+        )
+
+    loss_fn = nn.CrossEntropyLoss()
+
+    model, default_target_layer = build_model(
+        model_name, num_classes=len(classes), img_size=img_size
+    )
+    model = model.to(device)
+
+    opt_name = str(cfg.get("optimizer", "adam")).lower()
+    if opt_name == "sgd":
+        optimizer = optim.SGD(
+            model.parameters(),
+            lr=cfg["lr"],
+            momentum=float(cfg.get("momentum", 0.9)),
+            weight_decay=cfg["weight_decay"],
+            nesterov=True,
+        )
+    else:
+        optimizer = optim.Adam(
+            model.parameters(), lr=cfg["lr"], weight_decay=cfg["weight_decay"]
+        )
+    scheduler = optim.lr_scheduler.ReduceLROnPlateau(
+        optimizer, mode="min", factor=0.5, patience=2
+    )
+
+    writer = SummaryWriter(log_dir=str(LOG_DIR))
+
+    monitor = cfg["early_stop"]["monitor"]
+    mode = cfg["early_stop"]["mode"]
+    patience = int(cfg["early_stop"]["patience"])
+    min_delta = float(cfg["early_stop"]["min_delta"])
+
+    best_val = float("inf") if mode == "min" else -float("inf")
+    epochs_no_improve = 0
+
+    ckpt_last = CKPTS_DIR / "last.ckpt"
+    ckpt_best = CKPTS_DIR / "best.ckpt"
+
+    for epoch in range(1, cfg["epochs"] + 1):
+        tr_loss, tr_acc = train_one_epoch(
+            model, train_loader, device, optimizer, loss_fn
+        )
+        va_loss, va_acc = eval_one_epoch(model, val_loader, device, loss_fn)
+        scheduler.step(va_loss)
+
+        writer.add_scalar("Loss/train", tr_loss, epoch)
+        writer.add_scalar("Loss/val", va_loss, epoch)
+        writer.add_scalar("Acc/train", tr_acc, epoch)
+        writer.add_scalar("Acc/val", va_acc, epoch)
+        writer.add_scalar("LR", optimizer.param_groups[0]["lr"], epoch)
+
+        print(
+            f"Epoch {epoch:02d} | train_loss={tr_loss:.4f} acc={tr_acc:.4f}"
+            + f" | val_loss={va_loss:.4f} acc={va_acc:.4f}"
+        )
+
+        mon_value = va_loss if monitor == "val_loss" else va_acc
+
+        payload = {
+            "epoch": epoch,
+            "model_state": model.state_dict(),
+            "optimizer_state": optimizer.state_dict(),
+            "val_acc": va_acc,
+            "val_loss": va_loss,
+            "dataset": cfg["dataset"],
+            "classes": classes,
+            "config_path": cfg.get("_config_path"),
+            "meta": {
+                "dataset": dataset,
+                "model_name": model_name,
+                "img_size": img_size,
+                "mean": mean,
+                "std": std,
+                "default_target_layer": default_target_layer,
+            },
+        }
+        save_checkpoint(payload, ckpt_last)
+
+        if is_improved(best_val, mon_value, mode, min_delta):
+            best_val = mon_value
+            epochs_no_improve = 0
+            save_checkpoint(payload, ckpt_best)
+            best_json = {
+                "epoch": epoch,
+                "monitor": monitor,
+                "mode": mode,
+                "best_value": float(best_val),
+                "val_acc": float(va_acc),
+                "val_loss": float(va_loss),
+                "ckpt_path": str(ckpt_best),
+                "meta": {
+                    "dataset": dataset,
+                    "model_name": model_name,
+                    "img_size": img_size,
+                    "mean": mean,
+                    "std": std,
+                    "default_target_layer": default_target_layer,
+                },
+            }
+            with open(REPORTS_DIR / "best.json", "w") as f:
+                json.dump(best_json, f, indent=2)
+        else:
+            epochs_no_improve += 1
+
+        if epochs_no_improve >= patience:
+            print(f"Early stopping: no improvement in {patience} epochs.")
+            break
+
+    writer.close()
+    print(f"Best {monitor}: {best_val:.4f}")
+
+    # Use best checkpoint for reports
+    best_ckpt = torch.load(str(ckpt_best), map_location=device)
+    model.load_state_dict(best_ckpt["model_state"])
+    model.eval()
+
+    metrics_path = REPORTS_DIR / "metrics.json"
+    confusion_matrix_report(
+        model,
+        test_loader,
+        device,
+        classes,
+        reports_dir=REPORTS_DIR / "figures",
+        metrics_path=metrics_path,
+        title_prefix=cfg["dataset"].replace("-", " ").title(),
+    )
+
+    metrics = {
+        "dataset": cfg["dataset"],
+        "epochs_ran": epoch,
+        "batch_size": cfg["batch_size"],
+        "lr": cfg["lr"],
+        "weight_decay": cfg["weight_decay"],
+        "best_monitor": monitor,
+        "best_mode": mode,
+        "best_value": float(best_val),
+        "logs_dir": str(LOG_DIR),
+        "ckpts_dir": str(CKPTS_DIR),
+        "reports_dir": str(REPORTS_DIR),
+    }
+    with open(metrics_path, "w") as f:
+        json.dump(metrics, f, indent=2)
+
+    print("Saved metrics to:", metrics_path)
+    print("Best checkpoint:", ckpt_best)
+
+
+if __name__ == "__main__":
+    main()