Clean push

.dockerignore

@@ -0,0 +1,11 @@
+# Local env
+.venv/
+__pycache__/
+*.pyc
+
+# Local data (do not ship)
+data/
+
+# OS / IDE
+.vscode/
+.DS_Store

.gitattributes

@@ -0,0 +1,4 @@
+# Git LFS
+artifacts/model.pt filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,29 @@
+# Python virtual env
+.venv/
+venv/
+
+# Python cache
+__pycache__/
+*.pyc
+
+# Local datasets / splits
+data/
+
+# OS / IDE
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/
+
+# Dataset artifacts / HF datasets shards
+data/splits/**/*.arrow
+data/splits/**/dataset_info.json
+data/splits/**/state.json
+data/splits/
+
+# Jupyter / checkpoints
+.ipynb_checkpoints/
+.venv/
+data/splits/.git_old/
+*.arrow
+

Dockerfile

@@ -0,0 +1,24 @@
+FROM python:3.11-slim
+
+# HF Spaces containers run as UID 1000; creating a user avoids permission issues.
+RUN useradd -m -u 1000 user
+USER user
+
+WORKDIR /app
+
+# Copy only requirement file first for better Docker layer caching
+COPY requirements.txt /app/requirements.txt
+RUN pip install --no-cache-dir -r /app/requirements.txt
+
+# Copy the app code + artifacts
+COPY src /app/src
+COPY artifacts /app/artifacts
+COPY README.md /app/README.md
+
+# Spaces expect the app to listen on port 7860
+EXPOSE 7860
+
+# Ensure python can import "src.*"
+ENV PYTHONPATH=/app
+
+CMD ["uvicorn", "src.app.main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,11 @@
+---
+title: Vehicle Damage Classifier
+emoji: 📉
+colorFrom: indigo
+colorTo: blue
+sdk: docker
+pinned: false
+short_description: MIS453 Midterm Project
+---
+
+Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

artifacts/label_names.json

@@ -0,0 +1,8 @@
+[
+  "F_Breakage",
+  "F_Crushed",
+  "F_Normal",
+  "R_Breakage",
+  "R_Crushed",
+  "R_Normal"
+]

artifacts/model.pt

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

src/app/README.md

@@ -0,0 +1,82 @@
+# Vehicle Damage Classification Using Computer Vision
+
+This project is developed as part of the **MIS453 Midterm Project**.  
+The goal is to build an **end-to-end machine learning application** that classifies vehicle damage images into predefined categories and serves predictions via a backend API.
+
+---
+
+## 📌 Problem Definition
+
+Given a single RGB image of a vehicle, the system predicts **one damage class** among the following:
+
+- F_Normal  
+- F_Breakage  
+- F_Crushed  
+- R_Normal  
+- R_Breakage  
+- R_Crushed  
+
+The task is strictly **multi-class image classification**.
+
+---
+
+## 📊 Dataset
+
+- **Source:** DrBimmer / Comprehensive Car Damage (Hugging Face)
+- **Total samples:** 2300 images
+- **Split:** Stratified Train / Validation (80% / 20%)
+- **Classes:** 6 (verified programmatically)
+
+The dataset was visually inspected and class distributions were analyzed before model training.
+
+---
+
+## 🧠 Model & Training
+
+- **Architecture:** ResNet18
+- **Training mode:** Offline (no pretrained weight download)
+- **Loss:** CrossEntropyLoss with class weighting
+- **Input size:** 224 × 224
+- **Device:** CPU
+- **Output:** Trained model artifact saved to disk
+
+Artifacts generated after training:
+- `artifacts/model.pt`
+- `artifacts/label_names.json`
+- `artifacts/confusion_matrix.pt`
+
+---
+
+## 📈 Evaluation
+
+- **Validation Accuracy:** ~0.57
+- **Metrics:** Confusion matrix + class-wise Precision / Recall / F1
+- Strong performance on **Front** classes, lower recall on **Rear** damage types (expected due to visual similarity and class imbalance).
+
+The goal of this project is **not accuracy maximization**, but demonstrating a **correct and reproducible ML pipeline**.
+
+---
+
+## 🚀 Backend API (FastAPI)
+
+A FastAPI backend is implemented to serve predictions using the trained model artifact.
+
+### Available Endpoints
+
+- `GET /health`  
+  Returns API status and class information.
+
+- `POST /predict`  
+  Accepts an image file and returns:
+  - predicted class
+  - confidence score
+  - top-3 predictions
+
+---
+
+## ▶️ Local Setup & Run
+
+### 1. Install dependencies
+```bash
+pip install -r requirements.txt
+

src/app/inference.py

@@ -0,0 +1,109 @@
+# src/app/inference.py
+import json
+from pathlib import Path
+from typing import List, Tuple, Dict, Any
+
+import torch
+import torch.nn as nn
+from torchvision import transforms, models
+from PIL import Image
+
+
+# --- Paths (relative to project root) ---
+ARTIFACTS_DIR = Path("artifacts")
+CKPT_PATH = ARTIFACTS_DIR / "model.pt"
+LABELS_PATH = ARTIFACTS_DIR / "label_names.json"
+
+IMG_SIZE = 224
+
+
+def get_device() -> torch.device:
+    return torch.device("cuda" if torch.cuda.is_available() else "cpu")
+
+
+def load_label_names() -> List[str]:
+    if not LABELS_PATH.exists():
+        raise FileNotFoundError(f"Missing {LABELS_PATH}. Run training first to create artifacts.")
+    return json.loads(LABELS_PATH.read_text(encoding="utf-8"))
+
+
+def build_model(num_classes: int) -> nn.Module:
+    # OFFLINE SAFE: no pretrained downloads
+    model = models.resnet18(weights=None)
+    model.fc = nn.Linear(model.fc.in_features, num_classes)
+    return model
+
+
+def load_model() -> Tuple[nn.Module, List[str], torch.device]:
+    """
+    Loads the trained model artifact and label names once.
+    Returns (model, label_names, device).
+    """
+    if not CKPT_PATH.exists():
+        raise FileNotFoundError(f"Missing {CKPT_PATH}. Train and save model first.")
+
+    label_names = load_label_names()
+    num_classes = len(label_names)
+
+    device = get_device()
+    model = build_model(num_classes)
+
+    ckpt = torch.load(CKPT_PATH, map_location="cpu")
+    model.load_state_dict(ckpt["model_state_dict"])
+
+    model.to(device)
+    model.eval()
+    return model, label_names, device
+
+
+def get_preprocess() -> transforms.Compose:
+    # Must match training/evaluation preprocessing
+    return transforms.Compose([
+        transforms.Resize((IMG_SIZE, IMG_SIZE)),
+        transforms.ToTensor(),
+        transforms.Normalize(mean=[0.485, 0.456, 0.406],
+                             std=[0.229, 0.224, 0.225]),
+    ])
+
+
+@torch.no_grad()
+def predict_image(
+    model: nn.Module,
+    label_names: List[str],
+    device: torch.device,
+    image: Image.Image,
+    top_k: int = 3
+) -> Dict[str, Any]:
+    """
+    Predicts class probabilities for a single PIL image.
+    Returns predicted class, confidence, and top-k list.
+    """
+    tf = get_preprocess()
+    x = tf(image.convert("RGB")).unsqueeze(0).to(device)  # (1,3,H,W)
+
+    logits = model(x)
+    probs = torch.softmax(logits, dim=1).squeeze(0).detach().cpu()
+
+    pred_id = int(torch.argmax(probs).item())
+    pred_label = label_names[pred_id]
+    pred_conf = float(probs[pred_id].item())
+
+    k = min(top_k, len(label_names))
+    top = torch.topk(probs, k=k)
+    topk: List[Dict[str, float]] = []
+    for score, idx in zip(top.values.tolist(), top.indices.tolist()):
+        topk.append({"label": label_names[int(idx)], "confidence": float(score)})
+
+    # all_probs is sometimes useful for debugging/UI charts
+    all_probs = {label_names[i]: float(probs[i].item()) for i in range(len(label_names))}
+
+    return {
+        "predicted_class": pred_label,
+        "confidence": pred_conf,
+        "top_k": topk,
+        "all_probs": all_probs,
+    }
+# --- IGNORE ---
+# This module provides functions to load a trained ResNet18 model,
+# preprocess images, and perform inference to obtain class predictions
+# and confidence scores for the "comprehensive-car-damage" dataset.

src/app/main.py

@@ -0,0 +1,50 @@
+# src/app/main.py
+from io import BytesIO
+from typing import Any, Dict
+
+from fastapi import FastAPI, UploadFile, File, HTTPException
+from PIL import Image
+
+from src.app.inference import load_model, predict_image
+
+app = FastAPI(
+    title="Vehicle Damage Classifier API",
+    version="1.0.0",
+    description="Predicts one of 6 vehicle damage classes from an uploaded image."
+)
+
+# Load once at startup (no retraining, no repeated loading per request)
+MODEL, LABEL_NAMES, DEVICE = load_model()
+
+
+@app.get("/health")
+def health() -> Dict[str, Any]:
+    return {
+        "status": "ok",
+        "device": str(DEVICE),
+        "num_classes": len(LABEL_NAMES),
+        "classes": LABEL_NAMES,
+    }
+
+
+@app.post("/predict")
+async def predict(file: UploadFile = File(...)) -> Dict[str, Any]:
+    # Basic content-type guard (not perfect, but prevents obvious non-images)
+    if file.content_type is None or not file.content_type.startswith("image/"):
+        raise HTTPException(status_code=400, detail="Please upload an image file.")
+
+    try:
+        content = await file.read()
+        img = Image.open(BytesIO(content))
+    except Exception:
+        raise HTTPException(status_code=400, detail="Invalid image file.")
+
+    result = predict_image(MODEL, LABEL_NAMES, DEVICE, img, top_k=3)
+
+    return {
+        "filename": file.filename,
+        **result,
+    }
+# --- IGNORE ---
+# This is the main FastAPI application defining endpoints for health check
+# and image prediction using a pre-loaded vehicle damage classification model.

src/app/requirements.txt

@@ -0,0 +1,7 @@
+fastapi
+uvicorn
+python-multipart
+pillow
+torch
+torchvision
+datasets

src/step10_demo_request.py

@@ -0,0 +1,49 @@
+import sys
+import requests
+import mimetypes
+import os
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python src/step10_demo_request.py path/to/image.jpg")
+        sys.exit(1)
+
+    img_path = sys.argv[1]
+    url = "http://127.0.0.1:8000/predict"
+
+    mime_type, _ = mimetypes.guess_type(img_path)
+    if mime_type is None:
+        mime_type = "application/octet-stream"
+
+    print(f"Sending: {img_path} -> {url} (mime: {mime_type})")
+
+    try:
+        with open(img_path, "rb") as f:
+            files = {"file": (os.path.basename(img_path), f, mime_type)}
+            r = requests.post(url, files=files, timeout=60)
+
+        print("Request sent.")
+        print("Status code:", r.status_code)
+        print("Response headers:", dict(r.headers))
+
+        try:
+            print("JSON response:", r.json())
+        except ValueError:
+            print("Non-JSON response text:", r.text)
+
+        # Optional: raise for non-2xx to get exception trace if desired
+        # r.raise_for_status()
+
+    except requests.exceptions.RequestException as e:
+        print("Request failed:", repr(e))
+    except FileNotFoundError:
+        print("File not found:", img_path)
+    except Exception as e:
+        print("Unexpected error:", repr(e))
+
+if __name__ == "__main__":
+    main()
+# --- IGNORE ---
+# This script demonstrates how to send an image file to the FastAPI
+# prediction endpoint and print the response containing predicted
+# vehicle damage classes and confidence scores.

src/step2_show_sample.py

@@ -0,0 +1,23 @@
+from datasets import load_dataset
+import matplotlib.pyplot as plt
+
+def main():
+    ds = load_dataset("DrBimmer/comprehensive-car-damage")
+    sample = ds["train"][0]
+
+    image = sample["image"]
+    label = sample["label"]
+
+    print("Label ID:", label)
+    print("Label Name:", ds["train"].features["label"].names[label])
+
+    plt.imshow(image)
+    plt.axis("off")
+    plt.title(ds["train"].features["label"].names[label])
+    plt.show()
+
+if __name__ == "__main__":
+    main()
+# This script loads a sample from the "comprehensive-car-damage" dataset,
+# prints its label ID and name, and displays the image using matplotlib.
+

src/step3_show_all_classes.py

@@ -0,0 +1,36 @@
+from datasets import load_dataset
+import matplotlib.pyplot as plt
+
+def main():
+    ds = load_dataset("DrBimmer/comprehensive-car-damage")
+    train_ds = ds["train"]
+    label_names = train_ds.features["label"].names
+
+    shown = set()
+    images = []
+    titles = []
+
+    for sample in train_ds:
+        label = sample["label"]
+        if label not in shown:
+            images.append(sample["image"])
+            titles.append(label_names[label])
+            shown.add(label)
+        if len(shown) == len(label_names):
+            break
+
+    plt.figure(figsize=(12, 8))
+    for i, (img, title) in enumerate(zip(images, titles)):
+        plt.subplot(2, 3, i + 1)
+        plt.imshow(img)
+        plt.title(title)
+        plt.axis("off")
+
+    plt.tight_layout()
+    plt.show()
+
+if __name__ == "__main__":
+    main()
+# This script loads the "comprehensive-car-damage" dataset,
+# iterates through the training set to find and display one image for each damage class
+# using matplotlib in a grid layout.

src/step4_make_splits.py

@@ -0,0 +1,45 @@
+from collections import Counter
+from datasets import load_dataset, DatasetDict
+from pathlib import Path
+
+SEED = 42
+TEST_SIZE = 0.2
+OUT_DIR = Path("data/splits/comprehensive-car-damage_seed42_test0p2")
+
+def dist(ds_split):
+    c = Counter(ds_split["label"])
+    names = ds_split.features["label"].names
+    total = len(ds_split)
+    rows = []
+    for k in range(len(names)):
+        v = c.get(k, 0)
+        rows.append((names[k], v, v/total if total else 0))
+    return rows
+
+def print_dist(title, ds_split):
+    print(f"\n{title} (n={len(ds_split)})")
+    for name, v, p in dist(ds_split):
+        print(f"- {name:<10}: {v:>4} ({p*100:>5.1f}%)")
+
+def main():
+    ds = load_dataset("DrBimmer/comprehensive-car-damage")
+    train = ds["train"]
+
+    split = train.train_test_split(
+        test_size=TEST_SIZE,
+        seed=SEED,
+        stratify_by_column="label"
+    )
+
+    # Rename for clarity: test -> val
+    splits = DatasetDict({"train": split["train"], "val": split["test"]})
+
+    print_dist("TRAIN", splits["train"])
+    print_dist("VAL", splits["val"])
+
+    OUT_DIR.mkdir(parents=True, exist_ok=True)
+    splits.save_to_disk(str(OUT_DIR))
+    print(f"\nSaved splits to: {OUT_DIR}")
+
+if __name__ == "__main__":
+    main()

src/step5_verify_load_splits.py

@@ -0,0 +1,15 @@
+from datasets import load_from_disk
+
+SPLIT_DIR = "data/splits/comprehensive-car-damage_seed42_test0p2"
+
+def main():
+    splits = load_from_disk(SPLIT_DIR)
+    print("Loaded keys:", list(splits.keys()))
+    print("train:", len(splits["train"]), "val:", len(splits["val"]))
+
+    # sanity: label names
+    names = splits["train"].features["label"].names
+    print("Label names:", names)
+
+if __name__ == "__main__":
+    main()

src/step6_dataloaders.py

@@ -0,0 +1,83 @@
+import torch
+from torch.utils.data import DataLoader
+from torchvision import transforms
+from datasets import load_from_disk
+from collections import Counter
+
+SPLIT_DIR = "data/splits/comprehensive-car-damage_seed42_test0p2"
+BATCH_SIZE = 16
+NUM_WORKERS = 0  # For Windows compatibility; set higher for Linux/Mac
+IMG_SIZE = 224
+
+def compute_class_weights(labels, num_classes):
+    c = Counter(labels)
+    total = len(labels)
+    # simple inverse frequency weighting
+    weights = []
+    for k in range(num_classes):
+        freq = c.get(k, 1) / total
+        weights.append(1.0 / freq)
+    w = torch.tensor(weights, dtype=torch.float)
+    # normalize (optional)
+    w = w / w.mean()
+    return w
+
+def main():
+    splits = load_from_disk(SPLIT_DIR)
+    train_ds = splits["train"]
+    val_ds = splits["val"]
+
+    label_names = train_ds.features["label"].names
+    num_classes = len(label_names)
+    print("Classes:", label_names)
+
+    train_tf = transforms.Compose([
+        transforms.Resize((IMG_SIZE, IMG_SIZE)),
+        transforms.RandomHorizontalFlip(p=0.5),
+        transforms.ToTensor(),
+        transforms.Normalize(mean=[0.485, 0.456, 0.406],
+                             std=[0.229, 0.224, 0.225]),
+    ])
+
+    val_tf = transforms.Compose([
+        transforms.Resize((IMG_SIZE, IMG_SIZE)),
+        transforms.ToTensor(),
+        transforms.Normalize(mean=[0.485, 0.456, 0.406],
+                             std=[0.229, 0.224, 0.225]),
+    ])
+
+    def transform_batch(examples, tf):
+        images = [tf(img.convert("RGB")) for img in examples["image"]]
+        labels = torch.tensor(examples["label"], dtype=torch.long)
+        return {"pixel_values": torch.stack(images), "labels": labels}
+
+    def collate_train(batch):
+        # batch: list of dicts from HF dataset rows
+        imgs = [row["image"] for row in batch]
+        labels = [row["label"] for row in batch]
+        return transform_batch({"image": imgs, "label": labels}, train_tf)
+
+    def collate_val(batch):
+        imgs = [row["image"] for row in batch]
+        labels = [row["label"] for row in batch]
+        return transform_batch({"image": imgs, "label": labels}, val_tf)
+
+    train_loader = DataLoader(train_ds, batch_size=BATCH_SIZE, shuffle=True,
+                              num_workers=NUM_WORKERS, collate_fn=collate_train)
+    val_loader = DataLoader(val_ds, batch_size=BATCH_SIZE, shuffle=False,
+                            num_workers=NUM_WORKERS, collate_fn=collate_val)
+
+    # sanity check: one batch
+    batch = next(iter(train_loader))
+    print("Batch keys:", batch.keys())
+    print("pixel_values shape:", batch["pixel_values"].shape)  # (B, C, H, W)
+    print("labels shape:", batch["labels"].shape)
+    print("labels sample:", batch["labels"][:8].tolist())
+    print("labels sample names:", [label_names[i] for i in batch["labels"][:8].tolist()])
+
+    # class weights (train)
+    w = compute_class_weights(train_ds["label"], num_classes)
+    print("Class weights:", {label_names[i]: float(w[i]) for i in range(num_classes)})
+
+if __name__ == "__main__":
+    main()

src/step7_train_resnet18.py

@@ -0,0 +1,194 @@
+import json
+from pathlib import Path
+from collections import Counter
+
+import torch
+import torch.nn as nn
+from torch.utils.data import DataLoader
+from torchvision import transforms, models
+from datasets import load_from_disk
+
+# --- Fixed inputs for reproducibility and consistent artifact paths ---
+SPLIT_DIR = "data/splits/comprehensive-car-damage_seed42_test0p2"
+ART_DIR = Path("artifacts")
+ART_DIR.mkdir(parents=True, exist_ok=True)
+
+IMG_SIZE = 224
+BATCH_SIZE = 16
+NUM_WORKERS = 0  # Windows-safe default (avoid multiprocessing issues)
+EPOCHS = 8
+LR = 3e-4
+SEED = 42
+
+def set_seed(seed: int):
+    # Ensures consistent shuffling and initialization across runs
+    torch.manual_seed(seed)
+    torch.cuda.manual_seed_all(seed)
+
+def compute_class_weights(labels, num_classes):
+    # Inverse-frequency weights to reduce bias toward majority classes
+    c = Counter(labels)
+    total = len(labels)
+    weights = []
+    for k in range(num_classes):
+        freq = c.get(k, 1) / total
+        weights.append(1.0 / freq)
+    w = torch.tensor(weights, dtype=torch.float)
+    # Normalize weights so average weight ≈ 1 (stable loss scale)
+    w = w / w.mean()
+    return w
+
+def accuracy(logits, labels):
+    # Simple top-1 accuracy
+    preds = logits.argmax(dim=1)
+    return (preds == labels).float().mean().item()
+
+def main():
+    set_seed(SEED)
+
+    # --- Device selection (CPU is fine; CUDA if available) ---
+    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    print("Device:", device)
+
+    # --- Load the *saved* stratified splits (do NOT re-split each run) ---
+    splits = load_from_disk(SPLIT_DIR)
+    train_ds = splits["train"]
+    val_ds = splits["val"]
+
+    # --- Label metadata (source of truth for class order) ---
+    label_names = train_ds.features["label"].names
+    num_classes = len(label_names)
+    print("Classes:", label_names)
+
+    # Save label map alongside the model artifact (needed for inference/API)
+    with open(ART_DIR / "label_names.json", "w", encoding="utf-8") as f:
+        json.dump(label_names, f, ensure_ascii=False, indent=2)
+
+    # --- Image preprocessing ---
+    # Train: small augmentation (flip) to improve generalization
+    # Val: deterministic transforms only
+    train_tf = transforms.Compose([
+        transforms.Resize((IMG_SIZE, IMG_SIZE)),
+        transforms.RandomHorizontalFlip(p=0.5),
+        transforms.ToTensor(),
+        transforms.Normalize(mean=[0.485, 0.456, 0.406],
+                             std=[0.229, 0.224, 0.225]),
+    ])
+
+    val_tf = transforms.Compose([
+        transforms.Resize((IMG_SIZE, IMG_SIZE)),
+        transforms.ToTensor(),
+        transforms.Normalize(mean=[0.485, 0.456, 0.406],
+                             std=[0.229, 0.224, 0.225]),
+    ])
+
+    # --- HF Dataset -> PyTorch batch conversion (collate_fn) ---
+    # We apply torchvision transforms inside collate_fn because HF stores PIL Images.
+    def transform_batch(examples, tf):
+        images = [tf(img.convert("RGB")) for img in examples["image"]]
+        labels = torch.tensor(examples["label"], dtype=torch.long)
+        return {"pixel_values": torch.stack(images), "labels": labels}
+
+    def collate_train(batch):
+        imgs = [row["image"] for row in batch]
+        labels = [row["label"] for row in batch]
+        return transform_batch({"image": imgs, "label": labels}, train_tf)
+
+    def collate_val(batch):
+        imgs = [row["image"] for row in batch]
+        labels = [row["label"] for row in batch]
+        return transform_batch({"image": imgs, "label": labels}, val_tf)
+
+    # --- DataLoaders (train shuffled, val not shuffled) ---
+    train_loader = DataLoader(train_ds, batch_size=BATCH_SIZE, shuffle=True,
+                              num_workers=NUM_WORKERS, collate_fn=collate_train)
+    val_loader = DataLoader(val_ds, batch_size=BATCH_SIZE, shuffle=False,
+                            num_workers=NUM_WORKERS, collate_fn=collate_val)
+
+    # --- Transfer Learning model ---
+    # Start from pretrained ImageNet weights, replace final classifier head for 6 classes.
+    USE_PRETRAINED = False
+    weights = models.ResNet18_Weights.DEFAULT if USE_PRETRAINED else None
+    model = models.resnet18(weights=weights)
+    in_features = model.fc.in_features
+    model.fc = nn.Linear(in_features, num_classes)
+    model = model.to(device)
+
+    # --- Loss with class weights (handles mild imbalance) ---
+    class_w = compute_class_weights(train_ds["label"], num_classes).to(device)
+    criterion = nn.CrossEntropyLoss(weight=class_w)
+
+    # --- Optimizer ---
+    optimizer = torch.optim.AdamW(model.parameters(), lr=LR)
+
+    # --- Checkpointing: keep the best model by validation accuracy ---
+    best_val_acc = -1.0
+    best_path = ART_DIR / "model.pt"
+
+    for epoch in range(1, EPOCHS + 1):
+        # ===== TRAIN LOOP =====
+        model.train()
+        train_loss = 0.0
+        train_acc = 0.0
+        n_train = 0
+
+        for batch in train_loader:
+            x = batch["pixel_values"].to(device)
+            y = batch["labels"].to(device)
+
+            optimizer.zero_grad(set_to_none=True)
+            logits = model(x)
+            loss = criterion(logits, y)
+            loss.backward()
+            optimizer.step()
+
+            bs = y.size(0)
+            train_loss += loss.item() * bs
+            train_acc += accuracy(logits.detach(), y) * bs
+            n_train += bs
+
+        train_loss /= n_train
+        train_acc /= n_train
+
+        # ===== VALIDATION LOOP =====
+        model.eval()
+        val_loss = 0.0
+        val_acc = 0.0
+        n_val = 0
+
+        with torch.no_grad():
+            for batch in val_loader:
+                x = batch["pixel_values"].to(device)
+                y = batch["labels"].to(device)
+
+                logits = model(x)
+                loss = criterion(logits, y)
+
+                bs = y.size(0)
+                val_loss += loss.item() * bs
+                val_acc += accuracy(logits, y) * bs
+                n_val += bs
+
+        val_loss /= n_val
+        val_acc /= n_val
+
+        print(f"Epoch {epoch:02d}/{EPOCHS} | "
+              f"train loss {train_loss:.4f} acc {train_acc:.4f} | "
+              f"val loss {val_loss:.4f} acc {val_acc:.4f}")
+
+        # Save best checkpoint
+        if val_acc > best_val_acc:
+            best_val_acc = val_acc
+            torch.save({
+                "model_state_dict": model.state_dict(),
+                "label_names": label_names,
+                "img_size": IMG_SIZE,
+                "arch": "resnet18",
+            }, best_path)
+            print(f"  -> saved best to {best_path} (val_acc={best_val_acc:.4f})")
+
+    print("\nTraining complete.")
+    print("Best val acc:", best_val_acc)
+
+if __name__ == "__main__":
+    main()

src/step8_evaluate.py

@@ -0,0 +1,116 @@
+import json
+from pathlib import Path
+
+import torch
+import torch.nn as nn
+from torch.utils.data import DataLoader
+from torchvision import transforms, models
+from datasets import load_from_disk
+
+SPLIT_DIR = "data/splits/comprehensive-car-damage_seed42_test0p2"
+CKPT_PATH = Path("artifacts/model.pt")
+LABELS_PATH = Path("artifacts/label_names.json")
+
+IMG_SIZE = 224
+BATCH_SIZE = 32
+NUM_WORKERS = 0
+
+def confusion_matrix_torch(y_true, y_pred, num_classes):
+    cm = torch.zeros((num_classes, num_classes), dtype=torch.int64)
+    for t, p in zip(y_true, y_pred):
+        cm[t, p] += 1
+    return cm
+
+def precision_recall_f1(cm):
+    # cm rows: true, cols: pred
+    num_classes = cm.size(0)
+    metrics = []
+    for i in range(num_classes):
+        tp = cm[i, i].item()
+        fp = cm[:, i].sum().item() - tp
+        fn = cm[i, :].sum().item() - tp
+
+        prec = tp / (tp + fp) if (tp + fp) else 0.0
+        rec  = tp / (tp + fn) if (tp + fn) else 0.0
+        f1   = (2 * prec * rec / (prec + rec)) if (prec + rec) else 0.0
+        metrics.append((prec, rec, f1))
+    return metrics
+
+def main():
+    # Load label names (source of truth for readable reporting)
+    label_names = json.loads(LABELS_PATH.read_text(encoding="utf-8"))
+    num_classes = len(label_names)
+
+    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    print("Device:", device)
+    print("Classes:", label_names)
+
+    # Load val split from disk
+    splits = load_from_disk(SPLIT_DIR)
+    val_ds = splits["val"]
+
+    # Deterministic val transforms
+    val_tf = transforms.Compose([
+        transforms.Resize((IMG_SIZE, IMG_SIZE)),
+        transforms.ToTensor(),
+        transforms.Normalize(mean=[0.485, 0.456, 0.406],
+                             std=[0.229, 0.224, 0.225]),
+    ])
+
+    def collate_val(batch):
+        imgs = [val_tf(row["image"].convert("RGB")) for row in batch]
+        labels = torch.tensor([row["label"] for row in batch], dtype=torch.long)
+        return {"pixel_values": torch.stack(imgs), "labels": labels}
+
+    val_loader = DataLoader(val_ds, batch_size=BATCH_SIZE, shuffle=False,
+                            num_workers=NUM_WORKERS, collate_fn=collate_val)
+
+    # Rebuild model architecture and load checkpoint weights
+    model = models.resnet18(weights=None)
+    in_features = model.fc.in_features
+    model.fc = nn.Linear(in_features, num_classes)
+
+    ckpt = torch.load(CKPT_PATH, map_location="cpu")
+    model.load_state_dict(ckpt["model_state_dict"])
+    model = model.to(device)
+    model.eval()
+
+    y_true_all = []
+    y_pred_all = []
+
+    with torch.no_grad():
+        for batch in val_loader:
+            x = batch["pixel_values"].to(device)
+            y = batch["labels"].to(device)
+
+            logits = model(x)
+            preds = logits.argmax(dim=1)
+
+            y_true_all.append(y.cpu())
+            y_pred_all.append(preds.cpu())
+
+    y_true = torch.cat(y_true_all)
+    y_pred = torch.cat(y_pred_all)
+
+    acc = (y_true == y_pred).float().mean().item()
+    print(f"\nVAL Accuracy: {acc:.4f}")
+
+    cm = confusion_matrix_torch(y_true, y_pred, num_classes)
+    print("\nConfusion Matrix (rows=true, cols=pred):")
+    print(cm)
+
+    metrics = precision_recall_f1(cm)
+    print("\nPer-class metrics:")
+    for i, (prec, rec, f1) in enumerate(metrics):
+        print(f"- {label_names[i]:<10} | P {prec:.3f} | R {rec:.3f} | F1 {f1:.3f}")
+
+    # Save CM for later reporting
+    out_path = Path("artifacts/confusion_matrix.pt")
+    torch.save({"confusion_matrix": cm, "label_names": label_names, "val_acc": acc}, out_path)
+    print(f"\nSaved confusion matrix to: {out_path}")
+
+if __name__ == "__main__":
+    main()
+# This script evaluates a trained ResNet18 model on the validation split of the
+# "comprehensive-car-damage" dataset, computes accuracy, confusion matrix,
+# precision, recall, and F1-score for each class, and saves the confusion matrix to disk.

src/step9_infer_from_dataset.py

@@ -0,0 +1,78 @@
+import json
+import random
+from pathlib import Path
+
+import torch
+import torch.nn as nn
+from torchvision import transforms, models
+from datasets import load_from_disk
+
+SPLIT_DIR = "data/splits/comprehensive-car-damage_seed42_test0p2"
+CKPT_PATH = Path("artifacts/model.pt")
+LABELS_PATH = Path("artifacts/label_names.json")
+
+IMG_SIZE = 224
+SEED = 42
+
+def softmax_probs(logits: torch.Tensor) -> torch.Tensor:
+    return torch.softmax(logits, dim=1)
+
+def main():
+    random.seed(SEED)
+    torch.manual_seed(SEED)
+
+    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    label_names = json.loads(LABELS_PATH.read_text(encoding="utf-8"))
+    num_classes = len(label_names)
+
+    # Load saved splits and pick one random sample from VAL (more meaningful than train)
+    splits = load_from_disk(SPLIT_DIR)
+    val_ds = splits["val"]
+    idx = random.randint(0, len(val_ds) - 1)
+    sample = val_ds[idx]
+
+    true_id = sample["label"]
+    true_name = label_names[true_id]
+
+    tf = transforms.Compose([
+        transforms.Resize((IMG_SIZE, IMG_SIZE)),
+        transforms.ToTensor(),
+        transforms.Normalize(mean=[0.485, 0.456, 0.406],
+                             std=[0.229, 0.224, 0.225]),
+    ])
+
+    x = tf(sample["image"].convert("RGB")).unsqueeze(0)  # (1,3,H,W)
+
+    # Rebuild model arch and load weights
+    model = models.resnet18(weights=None)
+    model.fc = nn.Linear(model.fc.in_features, num_classes)
+
+    ckpt = torch.load(CKPT_PATH, map_location="cpu")
+    model.load_state_dict(ckpt["model_state_dict"])
+    model = model.to(device)
+    model.eval()
+
+    with torch.no_grad():
+        logits = model(x.to(device))
+        probs = softmax_probs(logits).cpu().squeeze(0)
+
+    pred_id = int(torch.argmax(probs).item())
+    pred_name = label_names[pred_id]
+    pred_conf = float(probs[pred_id].item())
+
+    # top-3
+    topk = torch.topk(probs, k=3)
+    top3 = [(label_names[int(i)], float(v)) for v, i in zip(topk.values, topk.indices)]
+
+    print(f"Sample index (val): {idx}")
+    print(f"TRUE: {true_name} ({true_id})")
+    print(f"PRED: {pred_name} ({pred_id})  conf={pred_conf:.4f}")
+    print("TOP-3:")
+    for name, p in top3:
+        print(f"- {name:<10} : {p:.4f}")
+
+if __name__ == "__main__":
+    main()
+# This script performs inference on a single random sample from the validation split
+# of the "comprehensive-car-damage" dataset using a trained ResNet18 model,
+# and prints the true label, predicted label, confidence, and top-3 predictions.