initial deployment

.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.env
+data/raw/*.npy
+data/processed/
+data/outputs/
+models/*.pkl
+notebooks/.ipynb_checkpoints/
+.DS_Store
+*.egg-info/

Makefile

@@ -0,0 +1,27 @@
+.PHONY: setup download features train app clean
+
+# Run full pipeline (download → features → train)
+setup:
+	python setup.py
+
+# Individual steps
+download:
+	python scripts/make_dataset.py
+
+features:
+	python scripts/build_features.py
+
+train:
+	python scripts/model.py
+
+# Run the app locally
+app:
+	python app.py
+
+# Remove all generated data and model files
+clean:
+	rm -rf data/raw/*.npy data/processed/*.npy data/outputs/* models/*.pkl models/*.pth
+
+# Install dependencies
+install:
+	pip install -r requirements.txt

README.md

@@ -1,13 +1,129 @@
+# ScribblBot
+
+Real time sketch recognition powered by a lightweight CNN trained on Google's Quick Draw dataset. Draw anything in the browser and ScribblBot identifies it instantly.
+
+**Live app:** [your HuggingFace Spaces URL here]
+
+---
+
+## Results
+
+| Model | Architecture | Test Accuracy |
+|---|---|---|
+| Majority Class Baseline | Always predicts most frequent class | 6.67% |
+| Random Forest | HOG features, 200 trees | 85.10% |
+| ScribblNet | 3-layer CNN | **94.42%** |
+
+ScribblNet was trained on 30,000 samples across 15 classes (2,000 per class) for 15 epochs using Adam with cosine annealing. Training took under 5 minutes on Apple M-series hardware with MPS acceleration. The Random Forest operates on 1,296-dimensional HOG feature vectors extracted from 28×28 grayscale bitmaps.
+
+**Classes:** cat · dog · pizza · bicycle · house · sun · tree · car · fish · butterfly · guitar · hamburger · airplane · banana · star
+
+### Per-class performance (ScribblNet)
+
+| Class | Precision | Recall | F1 |
+|---|---|---|---|
+| cat | 0.88 | 0.83 | 0.85 |
+| dog | 0.81 | 0.82 | 0.82 |
+| pizza | 0.94 | 0.97 | 0.96 |
+| bicycle | 0.96 | 0.98 | 0.97 |
+| house | 0.99 | 0.98 | 0.98 |
+| sun | 0.95 | 0.96 | 0.96 |
+| tree | 0.96 | 0.97 | 0.97 |
+| car | 0.97 | 0.96 | 0.96 |
+| fish | 0.97 | 0.95 | 0.96 |
+| butterfly | 0.97 | 0.97 | 0.97 |
+| guitar | 0.95 | 0.98 | 0.96 |
+| hamburger | 0.99 | 0.97 | 0.98 |
+| airplane | 0.91 | 0.89 | 0.90 |
+| banana | 0.97 | 0.98 | 0.97 |
+| star | 0.94 | 0.94 | 0.94 |
+
+Cat and dog are the hardest classes, which is expected given their visual similarity in quick sketches. Airplane also underperforms, likely due to style variation in how people draw wings and fuselage.
+
+---
+
+## Experiment: Training Size Sensitivity
+
+Both ScribblNet and Random Forest were trained at 10%, 25%, 50%, 75%, and 100% of available training data.
+
+| Fraction | Samples | ScribblNet | Random Forest |
+|---|---|---|---|
+| 10% | 3,000 | 86.12% | 77.92% |
+| 25% | 7,500 | 90.37% | 80.35% |
+| 50% | 15,000 | 92.70% | 81.57% |
+| 75% | 22,500 | 93.00% | 82.88% |
+| 100% | 30,000 | 94.02% | 83.03% |
+
+The CNN scales more steeply with data volume than the Random Forest. At 10% of training data the gap is about 8 points; at 100% it grows to 11 points. The Random Forest plateaus around 83% while ScribblNet continues improving, suggesting the CNN would benefit further from additional data.
+
+---
+
+## Dataset
+
+[Quick Draw](https://quickdraw.withgoogle.com/data) by Google — 50 million drawings across 345 categories, collected from players of the Quick Draw game. Each drawing is a 28×28 grayscale bitmap stored as a flat 784-element uint8 vector. The dataset is publicly available via Google Cloud Storage.
+
 ---
-title: ScribbleBot Huggingface
-emoji: 🚀
-colorFrom: pink
-colorTo: yellow
-sdk: gradio
-sdk_version: 6.13.0
-app_file: app.py
-pinned: false
-short_description: Real-time sketch recognition using CNN
+
+## Setup
+
+```bash
+pip install -r requirements.txt
+python setup.py
+python app.py
+```
+
+`setup.py` runs the full pipeline: downloads the raw `.npy` files, extracts HOG features, trains all three models, and runs the experiment.
+
+Individual steps:
+
+```bash
+python scripts/make_dataset.py
+python scripts/build_features.py
+python scripts/model.py
+```
+
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+## Repository Structure
+
+```
+scribblbot/
+├── README.md
+├── requirements.txt
+├── Makefile
+├── setup.py
+├── app.py
+├── config.py
+├── scripts/
+│   ├── make_dataset.py
+│   ├── build_features.py
+│   └── model.py
+├── models/
+├── data/
+│   ├── raw/
+│   ├── processed/
+│   └── outputs/
+└── notebooks/
+```
+
+| Component | Location |
+|---|---|
+| Naive baseline | `scripts/model.py` — `MajorityClassifier`, saved to `models/naive_model.pkl` |
+| Random Forest | `scripts/model.py` — `train_classical()`, saved to `models/classical_model.pkl` |
+| ScribblNet CNN | `scripts/model.py` — `ScribblNet`, `train_deep()`, saved to `models/deep_model.pth` |
+| Inference app | `app.py` |
+| Config | `config.py` |
+
+---
+
+## Deployment
+
+1. `python setup.py` to train and generate `models/deep_model.pth`
+2. Create a new Space on HuggingFace (SDK: Gradio)
+3. Push the full repo including `models/deep_model.pth`
+
+---
+
+## Git Workflow
+
+Working branches: `develop` for integration, `feature/*` for individual changes. All work branches into `develop` via pull requests. `develop` merges into `main` for releases. No direct commits to `main`.

app.py

@@ -0,0 +1,284 @@
+"""
+app.py - ScribblBot inference application.
+"""
+
+import sys
+from pathlib import Path
+from typing import Optional
+
+import gradio as gr
+import numpy as np
+import torch
+import torch.nn.functional as F
+from PIL import Image
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+from config import CLASSES, CLASS_EMOJIS, MODELS_DIR, NUM_CLASSES
+from scripts.model import ScribblNet
+
+
+def _load_model() -> tuple[ScribblNet, torch.device]:
+    """Load trained ScribblNet weights from disk."""
+    device = torch.device("cpu")
+    model_path = MODELS_DIR / "deep_model.pth"
+    if not model_path.exists():
+        raise FileNotFoundError(f"Weights not found at {model_path}. Run python setup.py first.")
+    model = ScribblNet(num_classes=NUM_CLASSES)
+    model.load_state_dict(torch.load(model_path, map_location=device))
+    model.eval()
+    return model, device
+
+
+MODEL, DEVICE = _load_model()
+
+
+def predict(sketch: Optional[dict], _counter: int) -> tuple[str, int]:
+    """Run inference on an ImageEditor drawing.
+
+    Args:
+        sketch: Dict from gr.ImageEditor with 'composite' key.
+        _counter: Click counter used to bust Gradio output caching.
+
+    Returns:
+        Tuple of (HTML results string, incremented counter).
+    """
+    _counter += 1
+    if sketch is None:
+        return _empty_state_html(), _counter
+
+    img_array = sketch.get("composite") if isinstance(sketch, dict) else sketch
+    if img_array is None:
+        return _empty_state_html(), _counter
+
+    try:
+        img_pil = Image.fromarray(img_array.astype(np.uint8))
+        if img_pil.mode == "RGBA":
+            white = Image.new("RGBA", img_pil.size, (248, 247, 242, 255))
+            img_pil = Image.alpha_composite(white, img_pil).convert("L")
+        else:
+            img_pil = img_pil.convert("L")
+        img_pil = img_pil.resize((28, 28), Image.LANCZOS)
+        arr = np.array(img_pil, dtype=np.float32)
+        arr = (255.0 - arr) / 255.0
+        tensor = torch.from_numpy(arr).unsqueeze(0).unsqueeze(0).to(DEVICE)
+    except Exception as exc:
+        return _error_html(str(exc)), _counter
+
+    with torch.no_grad():
+        probs = F.softmax(MODEL(tensor), dim=1)[0].cpu().numpy()
+
+    top = [(CLASSES[i], float(probs[i])) for i in np.argsort(probs)[::-1][:5]]
+    return _results_html(top), _counter
+
+
+def _results_html(top: list[tuple[str, float]]) -> str:
+    best_cls, best_prob = top[0]
+    conf_pct = best_prob * 100
+    label = "CONFIDENT" if best_prob > 0.7 else "LIKELY" if best_prob > 0.4 else "UNSURE"
+    bars = ""
+    for i, (cls, prob) in enumerate(top):
+        pct = prob * 100
+        bars += f"""
+        <div class="bar-row" style="animation-delay:{i*0.08}s">
+            <span class="bar-emoji">{CLASS_EMOJIS.get(cls,'')}</span>
+            <span class="bar-label">{cls.upper()}</span>
+            <div class="bar-track"><div class="bar-fill" style="width:{pct:.1f}%;animation-delay:{i*0.08+0.1}s"></div></div>
+            <span class="bar-pct">{pct:.1f}%</span>
+        </div>"""
+    return f"""
+    <div class="results-panel fade-in">
+        <div class="result-tag">[ PREDICTION ]</div>
+        <div class="top-result">
+            <span class="top-emoji">{CLASS_EMOJIS.get(best_cls,'?')}</span>
+            <div class="top-text">
+                <div class="top-label">{best_cls.upper()}</div>
+                <div class="top-conf">{conf_pct:.1f}% &nbsp;·&nbsp; {label}</div>
+            </div>
+        </div>
+        <div class="divider"></div>
+        <div class="section-label">TOP 5 PROBABILITIES</div>
+        {bars}
+    </div>"""
+
+
+def _empty_state_html() -> str:
+    return """
+    <div class="results-panel empty-state">
+        <div class="empty-icon">✏️</div>
+        <div class="empty-title">DRAW SOMETHING</div>
+        <div class="empty-sub">then hit ANALYZE</div>
+        <div class="class-pills">
+            <span class="pill">🐱 cat</span><span class="pill">🐶 dog</span>
+            <span class="pill">🍕 pizza</span><span class="pill">🚲 bicycle</span>
+            <span class="pill">🏠 house</span><span class="pill">☀️ sun</span>
+            <span class="pill">🌳 tree</span><span class="pill">🚗 car</span>
+            <span class="pill">🐟 fish</span><span class="pill">🦋 butterfly</span>
+            <span class="pill">🎸 guitar</span><span class="pill">🍔 hamburger</span>
+            <span class="pill">✈️ airplane</span><span class="pill">🍌 banana</span>
+            <span class="pill">⭐ star</span>
+        </div>
+    </div>"""
+
+
+def _error_html(msg: str) -> str:
+    return f'<div class="results-panel error-state"><p class="err-msg">⚠ {msg}</p></div>'
+
+
+CUSTOM_CSS = """
+@import url('https://fonts.googleapis.com/css2?family=VT323&family=IBM+Plex+Mono:wght@400;500&display=swap');
+
+:root {
+    --bg:        #080808;
+    --surface:   #111111;
+    --surface2:  #1a1a1a;
+    --border:    #2a2a2a;
+    --accent:    #b8ff57;
+    --text:      #e8e8e0;
+    --text-muted:#888880;
+    --red:       #ff5f57;
+    --mono:      'IBM Plex Mono', monospace;
+    --display:   'VT323', monospace;
+}
+body, .gradio-container, #root {
+    background: var(--bg) !important;
+    font-family: var(--mono) !important;
+    color: var(--text) !important;
+}
+.gradio-container { max-width: 1100px !important; margin: 0 auto !important; }
+footer { display: none !important; }
+.block, .gr-box { background: transparent !important; border: none !important; box-shadow: none !important; }
+
+.app-header { text-align: center; padding: 36px 20px 20px; border-bottom: 1px solid var(--border); margin-bottom: 28px; }
+.app-title  { font-family: var(--display); font-size: 72px; line-height: 1; color: var(--accent); letter-spacing: 6px; text-shadow: 0 0 30px rgba(184,255,87,0.3); margin: 0; }
+.app-subtitle { font-size: 12px; color: var(--text-muted); letter-spacing: 4px; margin-top: 6px; }
+
+/* ImageEditor styling */
+/* Override Gradio's orange accent with our green */
+.sketch-col { --color-accent: #b8ff57 !important; --color-accent-soft: rgba(184,255,87,0.15) !important; }
+.sketch-col .image-editor { border: 1px solid var(--border) !important; border-radius: 4px !important; background: var(--surface) !important; }
+/* Hide color picker and swatch - we only need pen and eraser */
+.sketch-col [aria-label="Color"],
+.sketch-col [title="Color"],
+.sketch-col .image-editor .toolbar > button:nth-child(3),
+.sketch-col .image-editor .toolbar > button:nth-child(4) { display: none !important; }
+/* Toolbar background */
+.sketch-col .image-editor > div { background: var(--surface2) !important; }
+/* All buttons */
+.sketch-col .image-editor button {
+    background: var(--surface2) !important;
+    border: 1px solid var(--border) !important;
+    border-radius: 3px !important;
+    margin: 2px !important;
+    color: var(--text) !important;
+}
+.sketch-col .image-editor button:hover {
+    background: var(--accent) !important;
+    border-color: var(--accent) !important;
+    color: #000 !important;
+}
+/* Active tool */
+.sketch-col .image-editor button[aria-pressed="true"] {
+    border: 2px solid var(--accent) !important;
+    background: rgba(184,255,87,0.15) !important;
+    color: var(--accent) !important;
+}
+/* Force all SVG icons to white/text color */
+.sketch-col .image-editor svg *  { color: inherit !important; stroke: currentColor !important; }
+.sketch-col [data-testid="layer-wrap"] { display: none !important; }
+.sketch-col .layers-panel { display: none !important; }
+/* White canvas */
+.sketch-col .konvajs-content,
+.sketch-col .konvajs-content canvas,
+.sketch-col canvas { background: #f8f7f2 !important; background-color: #f8f7f2 !important; }
+.sketch-col canvas { cursor: crosshair !important; }
+.sketch-col * { cursor: auto; }
+.sketch-col canvas { cursor: crosshair !important; }
+
+.results-panel { background: var(--surface); border: 1px solid var(--border); border-radius: 4px; padding: 20px; min-height: 420px; font-family: var(--mono); }
+.result-tag { font-size: 11px; color: var(--accent); letter-spacing: 3px; margin-bottom: 16px; }
+.top-result { display: flex; align-items: center; gap: 18px; margin-bottom: 18px; }
+.top-emoji  { font-size: 56px; line-height: 1; }
+.top-label  { font-family: var(--display); font-size: 52px; color: var(--text); line-height: 1; letter-spacing: 3px; }
+.top-conf   { font-size: 13px; color: var(--accent); margin-top: 4px; }
+.divider    { height: 1px; background: var(--border); margin: 16px 0; }
+.section-label { font-size: 10px; color: var(--text-muted); letter-spacing: 3px; margin-bottom: 12px; }
+.bar-row { display: grid; grid-template-columns: 28px 90px 1fr 50px; align-items: center; gap: 8px; margin-bottom: 10px; opacity: 0; animation: slideIn 0.3s ease forwards; }
+.bar-emoji { font-size: 16px; text-align: center; }
+.bar-label { font-size: 11px; color: var(--text-muted); letter-spacing: 1px; }
+.bar-track { height: 6px; background: var(--surface2); border-radius: 3px; overflow: hidden; }
+.bar-fill  { height: 100%; background: var(--accent); border-radius: 3px; width: 0; animation: barGrow 0.4s ease forwards; }
+.bar-pct   { font-size: 11px; color: var(--text); text-align: right; }
+
+.empty-state { display: flex; flex-direction: column; align-items: center; justify-content: center; min-height: 360px; }
+.empty-icon  { font-size: 48px; margin-bottom: 12px; }
+.empty-title { font-family: var(--display); font-size: 36px; color: var(--accent); letter-spacing: 3px; }
+.empty-sub   { font-size: 12px; color: var(--text-muted); margin: 4px 0 24px; letter-spacing: 2px; }
+.class-pills { display: flex; flex-wrap: wrap; gap: 6px; justify-content: center; max-width: 340px; }
+.pill { background: var(--surface2); border: 1px solid var(--border); padding: 3px 10px; border-radius: 20px; font-size: 11px; color: var(--text-muted); }
+.error-state { display: flex; align-items: center; justify-content: center; min-height: 200px; }
+.err-msg { font-size: 13px; color: var(--red); }
+
+.analyze-row { padding: 12px 0 0 !important; }
+.analyze-row button { width: 100% !important; background: rgba(184,255,87,0.06) !important; border: 2px solid var(--accent) !important; color: var(--accent) !important; font-family: var(--mono) !important; font-size: 15px !important; letter-spacing: 4px !important; padding: 14px !important; border-radius: 2px !important; cursor: pointer !important; transition: background 0.15s !important; }
+.analyze-row button:hover { background: var(--accent) !important; color: #000 !important; }
+
+.app-footer { text-align: center; padding: 18px; font-size: 11px; color: var(--text-muted); letter-spacing: 1px; border-top: 1px solid var(--border); margin-top: 16px; }
+
+@keyframes slideIn { from { opacity: 0; transform: translateX(-8px); } to { opacity: 1; transform: translateX(0); } }
+@keyframes barGrow  { from { width: 0; } }
+.fade-in { animation: fadeIn 0.25s ease; }
+@keyframes fadeIn   { from { opacity: 0; } to { opacity: 1; } }
+"""
+
+
+def build_app() -> gr.Blocks:
+    """Construct and return the Gradio Blocks application."""
+    with gr.Blocks(css=CUSTOM_CSS, title="ScribblBot") as app:
+
+        gr.HTML("""
+        <div class="app-header">
+            <h1 class="app-title">SCRIBBLBOT</h1>
+            <p class="app-subtitle">NEURAL SKETCH CLASSIFIER · 15 CATEGORIES · QUICK DRAW DATASET</p>
+        </div>
+        """)
+
+        click_counter = gr.State(0)
+
+        with gr.Row():
+            with gr.Column(elem_classes=["sketch-col"]):
+                sketch_input = gr.ImageEditor(
+                    type="numpy",
+                    image_mode="RGBA",
+                    canvas_size=(480, 480),
+                    layers=False,
+                    sources=[],
+                    brush=gr.Brush(
+                        colors=["#111111"],
+                        default_size=14,
+                        color_mode="fixed",
+                    ),
+                    eraser=gr.Eraser(default_size=20),
+                    show_label=False,
+                )
+
+            with gr.Column():
+                result_html = gr.HTML(_empty_state_html())
+
+        with gr.Row(elem_classes=["analyze-row"]):
+            analyze_btn = gr.Button("ANALYZE")
+
+        gr.HTML('<div class="app-footer">ScribblBot · built with Quick Draw · PyTorch · Gradio</div>')
+
+        analyze_btn.click(
+            fn=predict,
+            inputs=[sketch_input, click_counter],
+            outputs=[result_html, click_counter],
+        )
+
+    return app
+
+
+if __name__ == "__main__":
+    demo = build_app()
+    demo.launch()

config.py

@@ -0,0 +1,60 @@
+"""
+Central configuration for ScribblBot.
+All hyperparameters, paths, and constants live here.
+"""
+
+from pathlib import Path
+
+# Paths
+PROJECT_ROOT = Path(__file__).parent
+DATA_DIR = PROJECT_ROOT / "data"
+RAW_DIR = DATA_DIR / "raw"
+PROCESSED_DIR = DATA_DIR / "processed"
+OUTPUTS_DIR = DATA_DIR / "outputs"
+MODELS_DIR = PROJECT_ROOT / "models"
+
+for _d in [RAW_DIR, PROCESSED_DIR, OUTPUTS_DIR, MODELS_DIR]:
+    _d.mkdir(parents=True, exist_ok=True)
+
+# Classes
+# 15 visually distinct Quick Draw categories
+CLASSES = [
+    "cat", "dog", "pizza", "bicycle", "house",
+    "sun", "tree", "car", "fish", "butterfly",
+    "guitar", "hamburger", "airplane", "banana", "star",
+]
+NUM_CLASSES = len(CLASSES)
+
+CLASS_EMOJIS = {
+    "cat": "🐱", "dog": "🐶", "pizza": "🍕", "bicycle": "🚲",
+    "house": "🏠", "sun": "☀️", "tree": "🌳", "car": "🚗",
+    "fish": "🐟", "butterfly": "🦋", "guitar": "🎸", "hamburger": "🍔",
+    "airplane": "✈️", "banana": "🍌", "star": "⭐",
+}
+
+# Dataset
+TRAIN_SAMPLES_PER_CLASS = 2000   # keeps training fast (~30k total)
+TEST_SAMPLES_PER_CLASS = 400     # solid eval set (~6k total)
+IMG_SIZE = 28                    # Quick Draw native resolution
+
+# Quick Draw public GCS bucket
+QUICKDRAW_URL = (
+    "https://storage.googleapis.com/quickdraw_dataset/full/numpy_bitmap/{cls}.npy"
+)
+
+# Deep Model
+DEEP_BATCH_SIZE = 128
+DEEP_EPOCHS = 15
+DEEP_LR = 1e-3
+DEEP_WEIGHT_DECAY = 1e-4
+
+# Classical Model
+RF_N_ESTIMATORS = 200
+RF_MAX_DEPTH = None
+HOG_ORIENTATIONS = 9
+HOG_PIXELS_PER_CELL = (4, 4)
+HOG_CELLS_PER_BLOCK = (2, 2)
+
+# Experiment: training set size sensitivity
+EXPERIMENT_FRACTIONS = [0.1, 0.25, 0.5, 0.75, 1.0]
+EXPERIMENT_EPOCHS = 10     # shorter runs for the sweep

notebooks/colab_train.ipynb

@@ -0,0 +1,564 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# ScribblBot — Colab Training Notebook\n",
+    "\n",
+    "Run every cell top to bottom. At the end your trained model files will be saved to Google Drive.\n",
+    "\n",
+    "**Before running:** go to Runtime > Change runtime type > T4 GPU"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# 1. Install dependencies\n",
+    "!pip install scikit-image seaborn joblib --quiet"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# 2. Mount Google Drive so models persist after the session ends\n",
+    "from google.colab import drive\n",
+    "drive.mount('/content/drive')\n",
+    "\n",
+    "import os\n",
+    "SAVE_DIR = '/content/drive/MyDrive/scribblbot_models'\n",
+    "os.makedirs(SAVE_DIR, exist_ok=True)\n",
+    "print(f'Models will be saved to: {SAVE_DIR}')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# 3. Config\n",
+    "from pathlib import Path\n",
+    "\n",
+    "CLASSES = [\n",
+    "    'cat', 'dog', 'pizza', 'bicycle', 'house',\n",
+    "    'sun', 'tree', 'car', 'fish', 'butterfly',\n",
+    "    'guitar', 'hamburger', 'airplane', 'banana', 'star',\n",
+    "]\n",
+    "NUM_CLASSES = len(CLASSES)\n",
+    "\n",
+    "TRAIN_SAMPLES_PER_CLASS = 2000\n",
+    "TEST_SAMPLES_PER_CLASS = 400\n",
+    "IMG_SIZE = 28\n",
+    "\n",
+    "DEEP_BATCH_SIZE = 256    # bigger batch since we have GPU\n",
+    "DEEP_EPOCHS = 15\n",
+    "DEEP_LR = 1e-3\n",
+    "DEEP_WEIGHT_DECAY = 1e-4\n",
+    "\n",
+    "RF_N_ESTIMATORS = 200\n",
+    "HOG_ORIENTATIONS = 9\n",
+    "HOG_PIXELS_PER_CELL = (4, 4)\n",
+    "HOG_CELLS_PER_BLOCK = (2, 2)\n",
+    "\n",
+    "EXPERIMENT_FRACTIONS = [0.1, 0.25, 0.5, 0.75, 1.0]\n",
+    "EXPERIMENT_EPOCHS = 10\n",
+    "\n",
+    "RAW_DIR = Path('/content/data/raw')\n",
+    "PROCESSED_DIR = Path('/content/data/processed')\n",
+    "OUTPUTS_DIR = Path('/content/data/outputs')\n",
+    "MODELS_DIR = Path('/content/models')\n",
+    "\n",
+    "for d in [RAW_DIR, PROCESSED_DIR, OUTPUTS_DIR, MODELS_DIR]:\n",
+    "    d.mkdir(parents=True, exist_ok=True)\n",
+    "\n",
+    "QUICKDRAW_URL = 'https://storage.googleapis.com/quickdraw_dataset/full/numpy_bitmap/{cls}.npy'\n",
+    "\n",
+    "print(f'Config ready. {NUM_CLASSES} classes, {TRAIN_SAMPLES_PER_CLASS} train samples each.')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# 4. Download Quick Draw data\n",
+    "import urllib.request\n",
+    "\n",
+    "def download_class(cls):\n",
+    "    url = QUICKDRAW_URL.format(cls=cls.replace(' ', '%20'))\n",
+    "    dest = RAW_DIR / f'{cls}.npy'\n",
+    "    if dest.exists():\n",
+    "        print(f'  already have {cls}.npy')\n",
+    "        return\n",
+    "    urllib.request.urlretrieve(url, dest)\n",
+    "    print(f'  downloaded {cls}.npy')\n",
+    "\n",
+    "print('Downloading dataset...')\n",
+    "for cls in CLASSES:\n",
+    "    download_class(cls)\n",
+    "print('Done.')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# 5. Build train/test splits and HOG features\n",
+    "import numpy as np\n",
+    "from skimage.feature import hog\n",
+    "\n",
+    "def load_class_data(cls, n_train, n_test):\n",
+    "    data = np.load(RAW_DIR / f'{cls}.npy', mmap_mode='r')\n",
+    "    rng = np.random.default_rng(seed=42)\n",
+    "    indices = rng.permutation(len(data))[:n_train + n_test]\n",
+    "    data = data[indices]\n",
+    "    return data[:n_train], data[n_train:n_train + n_test]\n",
+    "\n",
+    "def extract_hog(pixel_matrix):\n",
+    "    features = []\n",
+    "    for row in pixel_matrix:\n",
+    "        img = row.reshape(IMG_SIZE, IMG_SIZE)\n",
+    "        desc = hog(img, orientations=HOG_ORIENTATIONS,\n",
+    "                   pixels_per_cell=HOG_PIXELS_PER_CELL,\n",
+    "                   cells_per_block=HOG_CELLS_PER_BLOCK,\n",
+    "                   visualize=False, channel_axis=None)\n",
+    "        features.append(desc)\n",
+    "    return np.array(features, dtype=np.float32)\n",
+    "\n",
+    "print('Loading raw data...')\n",
+    "train_raws, test_raws, train_labels, test_labels = [], [], [], []\n",
+    "for idx, cls in enumerate(CLASSES):\n",
+    "    tr, te = load_class_data(cls, TRAIN_SAMPLES_PER_CLASS, TEST_SAMPLES_PER_CLASS)\n",
+    "    train_raws.append(tr)\n",
+    "    test_raws.append(te)\n",
+    "    train_labels.append(np.full(len(tr), idx, dtype=np.int64))\n",
+    "    test_labels.append(np.full(len(te), idx, dtype=np.int64))\n",
+    "    print(f'  {cls}')\n",
+    "\n",
+    "X_train_raw = np.concatenate(train_raws)\n",
+    "X_test_raw = np.concatenate(test_raws)\n",
+    "y_train = np.concatenate(train_labels)\n",
+    "y_test = np.concatenate(test_labels)\n",
+    "\n",
+    "rng = np.random.default_rng(seed=0)\n",
+    "perm = rng.permutation(len(X_train_raw))\n",
+    "X_train_raw = X_train_raw[perm]\n",
+    "y_train = y_train[perm]\n",
+    "\n",
+    "print('\\nExtracting HOG features (train)...')\n",
+    "X_train_hog = extract_hog(X_train_raw)\n",
+    "print('Extracting HOG features (test)...')\n",
+    "X_test_hog = extract_hog(X_test_raw)\n",
+    "\n",
+    "np.save(PROCESSED_DIR / 'X_train_raw.npy', X_train_raw)\n",
+    "np.save(PROCESSED_DIR / 'X_test_raw.npy', X_test_raw)\n",
+    "np.save(PROCESSED_DIR / 'y_train.npy', y_train)\n",
+    "np.save(PROCESSED_DIR / 'y_test.npy', y_test)\n",
+    "np.save(PROCESSED_DIR / 'X_train_hog.npy', X_train_hog)\n",
+    "np.save(PROCESSED_DIR / 'X_test_hog.npy', X_test_hog)\n",
+    "\n",
+    "print(f'\\nTrain: {X_train_raw.shape}, Test: {X_test_raw.shape}, HOG features: {X_train_hog.shape[1]}')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# 6. Naive baseline\n",
+    "from sklearn.metrics import accuracy_score\n",
+    "import joblib\n",
+    "\n",
+    "majority_class = int(np.bincount(y_train).argmax())\n",
+    "naive_preds = np.full(len(y_test), majority_class, dtype=np.int64)\n",
+    "naive_acc = accuracy_score(y_test, naive_preds)\n",
+    "\n",
+    "joblib.dump({'majority_class': majority_class, 'accuracy': naive_acc}, MODELS_DIR / 'naive_model.pkl')\n",
+    "print(f'Naive baseline accuracy: {naive_acc:.4f}')\n",
+    "print(f'Majority class: {CLASSES[majority_class]}')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# 7. Classical ML: Random Forest on HOG features\n",
+    "from sklearn.ensemble import RandomForestClassifier\n",
+    "from sklearn.preprocessing import StandardScaler\n",
+    "from sklearn.metrics import classification_report, confusion_matrix\n",
+    "import time\n",
+    "\n",
+    "scaler = StandardScaler()\n",
+    "X_tr_scaled = scaler.fit_transform(X_train_hog)\n",
+    "X_te_scaled = scaler.transform(X_test_hog)\n",
+    "\n",
+    "rf = RandomForestClassifier(n_estimators=RF_N_ESTIMATORS, n_jobs=-1, random_state=42)\n",
+    "t0 = time.time()\n",
+    "rf.fit(X_tr_scaled, y_train)\n",
+    "elapsed = time.time() - t0\n",
+    "\n",
+    "rf_preds = rf.predict(X_te_scaled)\n",
+    "rf_acc = accuracy_score(y_test, rf_preds)\n",
+    "\n",
+    "joblib.dump({'clf': rf, 'scaler': scaler}, MODELS_DIR / 'classical_model.pkl')\n",
+    "\n",
+    "print(f'Random Forest trained in {elapsed:.1f}s')\n",
+    "print(f'Test accuracy: {rf_acc:.4f}')\n",
+    "print()\n",
+    "print(classification_report(y_test, rf_preds, target_names=CLASSES))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# 8. Define ScribblNet\n",
+    "import torch\n",
+    "import torch.nn as nn\n",
+    "import torch.nn.functional as F\n",
+    "from torch.utils.data import DataLoader, TensorDataset\n",
+    "\n",
+    "device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')\n",
+    "print(f'Using device: {device}')\n",
+    "\n",
+    "class ScribblNet(nn.Module):\n",
+    "    def __init__(self, num_classes=NUM_CLASSES):\n",
+    "        super().__init__()\n",
+    "        self.features = nn.Sequential(\n",
+    "            nn.Conv2d(1, 32, kernel_size=3, padding=1),\n",
+    "            nn.BatchNorm2d(32),\n",
+    "            nn.ReLU(inplace=True),\n",
+    "            nn.MaxPool2d(2),\n",
+    "\n",
+    "            nn.Conv2d(32, 64, kernel_size=3, padding=1),\n",
+    "            nn.BatchNorm2d(64),\n",
+    "            nn.ReLU(inplace=True),\n",
+    "            nn.MaxPool2d(2),\n",
+    "\n",
+    "            nn.Conv2d(64, 128, kernel_size=3, padding=1),\n",
+    "            nn.BatchNorm2d(128),\n",
+    "            nn.ReLU(inplace=True),\n",
+    "            nn.MaxPool2d(2),\n",
+    "        )\n",
+    "        self.classifier = nn.Sequential(\n",
+    "            nn.Dropout(0.5),\n",
+    "            nn.Linear(128 * 3 * 3, 256),\n",
+    "            nn.ReLU(inplace=True),\n",
+    "            nn.Dropout(0.3),\n",
+    "            nn.Linear(256, num_classes),\n",
+    "        )\n",
+    "\n",
+    "    def forward(self, x):\n",
+    "        x = self.features(x)\n",
+    "        x = x.view(x.size(0), -1)\n",
+    "        return self.classifier(x)\n",
+    "\n",
+    "print('ScribblNet defined.')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# 9. Train ScribblNet\n",
+    "def make_loaders(X_raw, y, X_test, y_test, batch_size, fraction=1.0):\n",
+    "    if fraction < 1.0:\n",
+    "        n = max(1, int(len(X_raw) * fraction))\n",
+    "        idx = np.random.default_rng(seed=7).permutation(len(X_raw))[:n]\n",
+    "        X_raw = X_raw[idx]\n",
+    "        y = y[idx]\n",
+    "    def to_ds(X, labels):\n",
+    "        imgs = torch.from_numpy(X.astype(np.float32) / 255.0).view(-1, 1, IMG_SIZE, IMG_SIZE)\n",
+    "        return TensorDataset(imgs, torch.from_numpy(labels))\n",
+    "    train_loader = DataLoader(to_ds(X_raw, y), batch_size=batch_size, shuffle=True, num_workers=2)\n",
+    "    test_loader  = DataLoader(to_ds(X_test, y_test), batch_size=batch_size, shuffle=False, num_workers=2)\n",
+    "    return train_loader, test_loader\n",
+    "\n",
+    "def evaluate_model(model, loader):\n",
+    "    model.eval()\n",
+    "    all_preds, all_labels = [], []\n",
+    "    with torch.no_grad():\n",
+    "        for imgs, labels in loader:\n",
+    "            preds = model(imgs.to(device)).argmax(dim=1).cpu().numpy()\n",
+    "            all_preds.append(preds)\n",
+    "            all_labels.append(labels.numpy())\n",
+    "    preds = np.concatenate(all_preds)\n",
+    "    labels = np.concatenate(all_labels)\n",
+    "    return accuracy_score(labels, preds), preds\n",
+    "\n",
+    "train_loader, test_loader = make_loaders(X_train_raw, y_train, X_test_raw, y_test, DEEP_BATCH_SIZE)\n",
+    "\n",
+    "model = ScribblNet().to(device)\n",
+    "optimizer = torch.optim.Adam(model.parameters(), lr=DEEP_LR, weight_decay=DEEP_WEIGHT_DECAY)\n",
+    "scheduler = torch.optim.lr_scheduler.CosineAnnealingLR(optimizer, T_max=DEEP_EPOCHS)\n",
+    "criterion = nn.CrossEntropyLoss()\n",
+    "\n",
+    "best_acc = 0.0\n",
+    "history = {'loss': [], 'val_acc': []}\n",
+    "\n",
+    "print(f'Training for {DEEP_EPOCHS} epochs...')\n",
+    "for epoch in range(1, DEEP_EPOCHS + 1):\n",
+    "    model.train()\n",
+    "    total_loss = 0.0\n",
+    "    for imgs, labels in train_loader:\n",
+    "        imgs, labels = imgs.to(device), labels.to(device)\n",
+    "        optimizer.zero_grad()\n",
+    "        loss = criterion(model(imgs), labels)\n",
+    "        loss.backward()\n",
+    "        optimizer.step()\n",
+    "        total_loss += loss.item()\n",
+    "    avg_loss = total_loss / len(train_loader)\n",
+    "    val_acc, _ = evaluate_model(model, test_loader)\n",
+    "    scheduler.step()\n",
+    "    history['loss'].append(avg_loss)\n",
+    "    history['val_acc'].append(val_acc)\n",
+    "    print(f'  epoch {epoch:02d}/{DEEP_EPOCHS}  loss={avg_loss:.4f}  val_acc={val_acc:.4f}')\n",
+    "    if val_acc > best_acc:\n",
+    "        best_acc = val_acc\n",
+    "        torch.save(model.state_dict(), MODELS_DIR / 'deep_model.pth')\n",
+    "\n",
+    "print(f'\\nBest test accuracy: {best_acc:.4f}')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# 10. Training curves\n",
+    "import matplotlib.pyplot as plt\n",
+    "\n",
+    "fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(11, 4))\n",
+    "\n",
+    "ax1.plot(range(1, len(history['loss']) + 1), history['loss'],\n",
+    "         color='steelblue', marker='o', linestyle='solid', markersize=5)\n",
+    "ax1.set_xlabel('Epoch')\n",
+    "ax1.set_ylabel('Training Loss')\n",
+    "ax1.set_title('ScribblNet Training Loss')\n",
+    "ax1.grid(True, alpha=0.3)\n",
+    "\n",
+    "ax2.plot(range(1, len(history['val_acc']) + 1), history['val_acc'],\n",
+    "         color='seagreen', marker='o', linestyle='solid', markersize=5)\n",
+    "ax2.set_xlabel('Epoch')\n",
+    "ax2.set_ylabel('Validation Accuracy')\n",
+    "ax2.set_title('ScribblNet Validation Accuracy')\n",
+    "ax2.grid(True, alpha=0.3)\n",
+    "\n",
+    "plt.tight_layout()\n",
+    "plt.savefig(OUTPUTS_DIR / 'deep_training_curves.png', dpi=150)\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# 11. Confusion matrices\n",
+    "import seaborn as sns\n",
+    "\n",
+    "model.load_state_dict(torch.load(MODELS_DIR / 'deep_model.pth', map_location=device))\n",
+    "_, deep_preds = evaluate_model(model, test_loader)\n",
+    "\n",
+    "def plot_cm(y_true, y_pred, title, filename):\n",
+    "    cm = confusion_matrix(y_true, y_pred, normalize='true')\n",
+    "    fig, ax = plt.subplots(figsize=(10, 8))\n",
+    "    sns.heatmap(cm, annot=True, fmt='.2f', xticklabels=CLASSES,\n",
+    "                yticklabels=CLASSES, cmap='Blues', ax=ax, linewidths=0.5)\n",
+    "    ax.set_xlabel('Predicted')\n",
+    "    ax.set_ylabel('True')\n",
+    "    ax.set_title(title)\n",
+    "    plt.xticks(rotation=45, ha='right')\n",
+    "    plt.tight_layout()\n",
+    "    plt.savefig(OUTPUTS_DIR / filename, dpi=150)\n",
+    "    plt.show()\n",
+    "\n",
+    "plot_cm(y_test, deep_preds, 'ScribblNet Confusion Matrix', 'deep_confusion_matrix.png')\n",
+    "plot_cm(y_test, rf_preds, 'Random Forest Confusion Matrix', 'classical_confusion_matrix.png')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# 12. Model comparison bar chart\n",
+    "names = ['Naive Baseline', 'Random Forest', 'ScribblNet']\n",
+    "accs = [naive_acc, rf_acc, best_acc]\n",
+    "\n",
+    "fig, ax = plt.subplots(figsize=(7, 4))\n",
+    "bars = ax.bar(names, accs, color=['#94a3b8', '#60a5fa', '#34d399'], width=0.5)\n",
+    "ax.set_ylim(0, 1)\n",
+    "ax.set_ylabel('Test Accuracy')\n",
+    "ax.set_title('Model Comparison')\n",
+    "for bar, acc in zip(bars, accs):\n",
+    "    ax.text(bar.get_x() + bar.get_width() / 2, bar.get_height() + 0.01,\n",
+    "            f'{acc:.3f}', ha='center', fontsize=12)\n",
+    "ax.grid(True, axis='y', alpha=0.3)\n",
+    "plt.tight_layout()\n",
+    "plt.savefig(OUTPUTS_DIR / 'model_comparison.png', dpi=150)\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# 13. Experiment: training set size sensitivity\n",
+    "# Sweeps over fractions of training data for both models.\n",
+    "# Shows how data volume affects each approach.\n",
+    "print('Running experiment: training size sensitivity sweep...')\n",
+    "\n",
+    "deep_accs_exp = []\n",
+    "rf_accs_exp = []\n",
+    "n_samples_list = []\n",
+    "\n",
+    "for frac in EXPERIMENT_FRACTIONS:\n",
+    "    n = int(len(X_train_raw) * frac)\n",
+    "    n_samples_list.append(n)\n",
+    "    print(f'\\nFraction {frac:.0%} (n={n})')\n",
+    "\n",
+    "    # Deep model\n",
+    "    tr_loader, te_loader = make_loaders(X_train_raw, y_train, X_test_raw, y_test,\n",
+    "                                         DEEP_BATCH_SIZE, fraction=frac)\n",
+    "    exp_model = ScribblNet().to(device)\n",
+    "    exp_opt = torch.optim.Adam(exp_model.parameters(), lr=DEEP_LR, weight_decay=DEEP_WEIGHT_DECAY)\n",
+    "    exp_sched = torch.optim.lr_scheduler.CosineAnnealingLR(exp_opt, T_max=EXPERIMENT_EPOCHS)\n",
+    "    exp_model.train()\n",
+    "    for ep in range(EXPERIMENT_EPOCHS):\n",
+    "        for imgs, labels in tr_loader:\n",
+    "            imgs, labels = imgs.to(device), labels.to(device)\n",
+    "            exp_opt.zero_grad()\n",
+    "            criterion(exp_model(imgs), labels).backward()\n",
+    "            exp_opt.step()\n",
+    "        exp_sched.step()\n",
+    "    acc_deep, _ = evaluate_model(exp_model, te_loader)\n",
+    "    deep_accs_exp.append(acc_deep)\n",
+    "    print(f'  ScribblNet acc: {acc_deep:.4f}')\n",
+    "\n",
+    "    # Random Forest\n",
+    "    idx = np.random.default_rng(seed=42).permutation(len(X_train_hog))[:n]\n",
+    "    sc = StandardScaler()\n",
+    "    X_tr_exp = sc.fit_transform(X_train_hog[idx])\n",
+    "    X_te_exp = sc.transform(X_test_hog)\n",
+    "    rf_exp = RandomForestClassifier(n_estimators=100, n_jobs=-1, random_state=42)\n",
+    "    rf_exp.fit(X_tr_exp, y_train[idx])\n",
+    "    acc_rf = accuracy_score(y_test, rf_exp.predict(X_te_exp))\n",
+    "    rf_accs_exp.append(acc_rf)\n",
+    "    print(f'  Random Forest acc: {acc_rf:.4f}')\n",
+    "\n",
+    "# Plot\n",
+    "fig, ax = plt.subplots(figsize=(8, 5))\n",
+    "ax.plot(n_samples_list, deep_accs_exp, marker='o', linestyle='solid',\n",
+    "        label='ScribblNet (CNN)', linewidth=2, markersize=7)\n",
+    "ax.plot(n_samples_list, rf_accs_exp, marker='s', linestyle='dashed',\n",
+    "        label='Random Forest (HOG)', linewidth=2, markersize=7)\n",
+    "ax.set_xlabel('Training samples')\n",
+    "ax.set_ylabel('Test accuracy')\n",
+    "ax.set_title('Training Set Size Sensitivity')\n",
+    "ax.legend()\n",
+    "ax.grid(True, alpha=0.3)\n",
+    "ax.set_ylim(0, 1)\n",
+    "plt.tight_layout()\n",
+    "plt.savefig(OUTPUTS_DIR / 'experiment_sensitivity.png', dpi=150)\n",
+    "plt.show()\n",
+    "\n",
+    "import json\n",
+    "with open(OUTPUTS_DIR / 'experiment_results.json', 'w') as f:\n",
+    "    json.dump({'fractions': EXPERIMENT_FRACTIONS, 'n_samples': n_samples_list,\n",
+    "               'deep_accs': deep_accs_exp, 'rf_accs': rf_accs_exp}, f, indent=2)\n",
+    "\n",
+    "print('Experiment complete.')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# 14. Save everything to Google Drive\n",
+    "import shutil\n",
+    "\n",
+    "files_to_save = [\n",
+    "    (MODELS_DIR / 'deep_model.pth',       'deep_model.pth'),\n",
+    "    (MODELS_DIR / 'classical_model.pkl',  'classical_model.pkl'),\n",
+    "    (MODELS_DIR / 'naive_model.pkl',       'naive_model.pkl'),\n",
+    "    (OUTPUTS_DIR / 'deep_training_curves.png',   'deep_training_curves.png'),\n",
+    "    (OUTPUTS_DIR / 'deep_confusion_matrix.png',  'deep_confusion_matrix.png'),\n",
+    "    (OUTPUTS_DIR / 'classical_confusion_matrix.png', 'classical_confusion_matrix.png'),\n",
+    "    (OUTPUTS_DIR / 'model_comparison.png',       'model_comparison.png'),\n",
+    "    (OUTPUTS_DIR / 'experiment_sensitivity.png', 'experiment_sensitivity.png'),\n",
+    "    (OUTPUTS_DIR / 'experiment_results.json',    'experiment_results.json'),\n",
+    "]\n",
+    "\n",
+    "for src, name in files_to_save:\n",
+    "    dest = Path(SAVE_DIR) / name\n",
+    "    shutil.copy(src, dest)\n",
+    "    print(f'Saved {name}')\n",
+    "\n",
+    "print(f'\\nAll files saved to Google Drive at: {SAVE_DIR}')\n",
+    "print('Download deep_model.pth and put it in your local models/ folder.')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# 15. Results summary\n",
+    "print('Results Summary')\n",
+    "print(f'  Naive baseline:  {naive_acc:.4f}')\n",
+    "print(f'  Random Forest:   {rf_acc:.4f}')\n",
+    "print(f'  ScribblNet:      {best_acc:.4f}')\n",
+    "\n",
+    "with open(OUTPUTS_DIR / 'results_summary.json', 'w') as f:\n",
+    "    json.dump({'naive_accuracy': naive_acc, 'classical_accuracy': rf_acc,\n",
+    "               'deep_accuracy': best_acc}, f, indent=2)\n",
+    "shutil.copy(OUTPUTS_DIR / 'results_summary.json', Path(SAVE_DIR) / 'results_summary.json')\n",
+    "print('results_summary.json saved to Drive.')"
+   ]
+  }
+ ],
+ "metadata": {
+  "accelerator": "GPU",
+  "colab": {
+   "gpuType": "T4",
+   "provenance": []
+  },
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.10.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

notebooks/exploration.ipynb

@@ -0,0 +1,43 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# ScribblBot — Data Exploration"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import sys\n",
+    "sys.path.insert(0, '..')\n",
+    "\n",
+    "import numpy as np\n",
+    "import matplotlib.pyplot as plt\n",
+    "from config import CLASSES, RAW_DIR\n",
+    "\n",
+    "cls = 'cat'\n",
+    "data = np.load(RAW_DIR / f'{cls}.npy')\n",
+    "print(f'{cls}: {data.shape}')\n",
+    "\n",
+    "fig, axes = plt.subplots(2, 8, figsize=(16, 4))\n",
+    "for i, ax in enumerate(axes.flat):\n",
+    "    ax.imshow(data[i].reshape(28, 28), cmap='gray_r')\n",
+    "    ax.axis('off')\n",
+    "plt.suptitle(cls)\n",
+    "plt.tight_layout()\n",
+    "plt.show()"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" },
+  "language_info": { "name": "python", "version": "3.10.0" }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

requirements.txt

@@ -0,0 +1,15 @@
+torch>=2.1.0
+torchvision>=0.16.0
+scikit-learn>=1.3.0
+scikit-image>=0.21.0
+numpy>=1.24.0
+pandas>=2.0.0
+matplotlib>=3.7.0
+seaborn>=0.12.0
+Pillow>=9.5.0
+tqdm>=4.65.0
+joblib>=1.3.0
+gradio>=5.0.0
+huggingface_hub>=0.20
+jinja2>=3.1.4
+requests>=2.31.0

scripts/__init__.py

@@ -0,0 +1 @@
+# scripts package

scripts/build_features.py

@@ -0,0 +1,145 @@
+"""
+build_features.py – Load raw Quick Draw .npy files, split into train/test,
+and extract HOG features for the classical ML pipeline.
+
+Saved artefacts (under data/processed/):
+    X_train_raw.npy, y_train.npy  -> pixel arrays for deep model
+    X_test_raw.npy,  y_test.npy   -> pixel arrays for evaluation
+    X_train_hog.npy               -> HOG feature matrix for Random Forest
+    X_test_hog.npy
+
+Usage:
+    python scripts/build_features.py
+"""
+
+import sys
+from pathlib import Path
+
+import numpy as np
+from skimage.feature import hog
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from config import (
+    CLASSES,
+    RAW_DIR,
+    PROCESSED_DIR,
+    TRAIN_SAMPLES_PER_CLASS,
+    TEST_SAMPLES_PER_CLASS,
+    IMG_SIZE,
+    HOG_ORIENTATIONS,
+    HOG_PIXELS_PER_CELL,
+    HOG_CELLS_PER_BLOCK,
+)
+
+
+def load_class_data(cls: str, n_train: int, n_test: int) -> tuple[np.ndarray, np.ndarray]:
+    """Load and slice pixel data for a single class.
+
+    The Quick Draw .npy files contain rows of 784-element uint8 vectors
+    (28×28 flattened, pixel values 0–255, white stroke on black background).
+
+    Args:
+        cls:    Class name.
+        n_train: Number of training samples to keep.
+        n_test:  Number of test samples to keep.
+
+    Returns:
+        Tuple of (train_pixels, test_pixels) each shaped (n, 784).
+    """
+    path = RAW_DIR / f"{cls}.npy"
+    if not path.exists():
+        raise FileNotFoundError(
+            f"Missing {path}. Run scripts/make_dataset.py first."
+        )
+    data = np.load(path, mmap_mode="r")  # memory mapped for large files
+
+    # Shuffle deterministically so splits are reproducible
+    rng = np.random.default_rng(seed=42)
+    indices = rng.permutation(len(data))[: n_train + n_test]
+    data = data[indices]
+
+    return data[:n_train], data[n_train : n_train + n_test]
+
+
+def extract_hog_features(pixel_matrix: np.ndarray) -> np.ndarray:
+    """Compute HOG descriptors for a batch of flat pixel vectors.
+
+    Args:
+        pixel_matrix: Array of shape (N, 784), dtype uint8.
+
+    Returns:
+        Feature matrix of shape (N, D) where D is the HOG descriptor length.
+    """
+    features = []
+    for row in pixel_matrix:
+        img = row.reshape(IMG_SIZE, IMG_SIZE)
+        desc = hog(
+            img,
+            orientations=HOG_ORIENTATIONS,
+            pixels_per_cell=HOG_PIXELS_PER_CELL,
+            cells_per_block=HOG_CELLS_PER_BLOCK,
+            visualize=False,
+            channel_axis=None,
+        )
+        features.append(desc)
+    return np.array(features, dtype=np.float32)
+
+
+def build_splits() -> None:
+    """Assemble train/test raw arrays and labels from all classes."""
+    train_raws, test_raws = [], []
+    train_labels, test_labels = [], []
+
+    print("Loading raw data …")
+    for label_idx, cls in enumerate(CLASSES):
+        print(f"  {cls} ({label_idx + 1}/{len(CLASSES)})")
+        tr, te = load_class_data(cls, TRAIN_SAMPLES_PER_CLASS, TEST_SAMPLES_PER_CLASS)
+        train_raws.append(tr)
+        test_raws.append(te)
+        train_labels.append(np.full(len(tr), label_idx, dtype=np.int64))
+        test_labels.append(np.full(len(te), label_idx, dtype=np.int64))
+
+    X_train_raw = np.concatenate(train_raws)
+    X_test_raw = np.concatenate(test_raws)
+    y_train = np.concatenate(train_labels)
+    y_test = np.concatenate(test_labels)
+
+    # Shuffle training set
+    rng = np.random.default_rng(seed=0)
+    perm = rng.permutation(len(X_train_raw))
+    X_train_raw = X_train_raw[perm]
+    y_train = y_train[perm]
+
+    PROCESSED_DIR.mkdir(parents=True, exist_ok=True)
+    np.save(PROCESSED_DIR / "X_train_raw.npy", X_train_raw)
+    np.save(PROCESSED_DIR / "X_test_raw.npy", X_test_raw)
+    np.save(PROCESSED_DIR / "y_train.npy", y_train)
+    np.save(PROCESSED_DIR / "y_test.npy", y_test)
+    print(f"\nSaved raw splits  →  train {X_train_raw.shape}, test {X_test_raw.shape}")
+
+
+def build_hog_features() -> None:
+    """Extract HOG features from saved raw arrays."""
+    X_train_raw = np.load(PROCESSED_DIR / "X_train_raw.npy")
+    X_test_raw = np.load(PROCESSED_DIR / "X_test_raw.npy")
+
+    print("Extracting HOG features (train) …")
+    X_train_hog = extract_hog_features(X_train_raw)
+    print("Extracting HOG features (test) …")
+    X_test_hog = extract_hog_features(X_test_raw)
+
+    np.save(PROCESSED_DIR / "X_train_hog.npy", X_train_hog)
+    np.save(PROCESSED_DIR / "X_test_hog.npy", X_test_hog)
+    print(f"Saved HOG features  →  train {X_train_hog.shape}, test {X_test_hog.shape}")
+
+
+def build_all() -> None:
+    """Run the complete feature building pipeline."""
+    build_splits()
+    build_hog_features()
+    print("\nFeature pipeline complete.")
+
+
+if __name__ == "__main__":
+    build_all()

scripts/make_dataset.py

@@ -0,0 +1,65 @@
+"""
+make_dataset.py – Download Quick Draw .npy files for all configured classes.
+
+Usage:
+    python scripts/make_dataset.py
+"""
+
+import sys
+from pathlib import Path
+import urllib.request
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from config import CLASSES, RAW_DIR, QUICKDRAW_URL
+
+
+def download_class(cls: str, dest_dir: Path, force: bool = False) -> Path:
+    """Download the numpy bitmap file for a single Quick Draw class.
+
+    Args:
+        cls:      Class name matching a Quick Draw category (e.g. 'cat').
+        dest_dir: Directory to write the .npy file into.
+        force:    Redownload even if the file already exists.
+
+    Returns:
+        Path to the downloaded file.
+    """
+    url = QUICKDRAW_URL.format(cls=cls.replace(" ", "%20"))
+    dest = dest_dir / f"{cls}.npy"
+    if dest.exists() and not force:
+        print(f"  [skip] {cls}.npy already exists")
+        return dest
+
+    print(f"  [down] {cls}.npy  ->  {url}")
+
+    def _reporthook(block_num: int, block_size: int, total_size: int) -> None:
+        downloaded = block_num * block_size
+        pct = min(100, downloaded * 100 // total_size) if total_size > 0 else 0
+        print(f"\r         {pct:3d}%", end="", flush=True)
+
+    urllib.request.urlretrieve(url, dest, reporthook=_reporthook)
+    print()
+    return dest
+
+
+def download_all(force: bool = False) -> None:
+    """Download .npy files for every class listed in config.CLASSES.
+
+    Args:
+        force: Redownload files that already exist on disk.
+    """
+    RAW_DIR.mkdir(parents=True, exist_ok=True)
+    print(f"Downloading {len(CLASSES)} classes to {RAW_DIR} …\n")
+    for cls in CLASSES:
+        download_class(cls, RAW_DIR, force=force)
+    print("\nAll downloads complete.")
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Download Quick Draw dataset")
+    parser.add_argument("--force", action="store_true", help="Redownload existing files")
+    args = parser.parse_args()
+    download_all(force=args.force)

scripts/model.py

@@ -0,0 +1,616 @@
+"""
+model.py – Define, train, and evaluate all three models:
+    1. Naive baseline (majority class classifier)
+    2. Classical ML  (Random Forest on HOG features)
+    3. Deep learning (ScribblNet CNN)
+
+Also runs the training size sensitivity experiment and saves results/plots.
+
+Usage:
+    python scripts/model.py
+"""
+
+import json
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+import joblib
+import matplotlib
+matplotlib.use("Agg")  # headless backend
+import matplotlib.pyplot as plt
+import numpy as np
+import torch
+import torch.nn as nn
+from sklearn.ensemble import RandomForestClassifier
+from sklearn.metrics import (
+    accuracy_score,
+    classification_report,
+    confusion_matrix,
+)
+from sklearn.preprocessing import StandardScaler
+from torch.utils.data import DataLoader, TensorDataset
+import seaborn as sns
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from config import (
+    CLASSES,
+    MODELS_DIR,
+    OUTPUTS_DIR,
+    PROCESSED_DIR,
+    NUM_CLASSES,
+    RF_MAX_DEPTH,
+    RF_N_ESTIMATORS,
+    DEEP_BATCH_SIZE,
+    DEEP_EPOCHS,
+    DEEP_LR,
+    DEEP_WEIGHT_DECAY,
+    IMG_SIZE,
+    EXPERIMENT_FRACTIONS,
+    EXPERIMENT_EPOCHS,
+)
+
+
+# Utility
+
+def get_device() -> torch.device:
+    """Return the best available torch device (MPS > CUDA > CPU)."""
+    if torch.backends.mps.is_available():
+        return torch.device("mps")
+    if torch.cuda.is_available():
+        return torch.device("cuda")
+    return torch.device("cpu")
+
+
+def load_processed_data() -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
+    """Load all processed arrays from disk.
+
+    Returns:
+        X_train_raw, X_test_raw, y_train, y_test, X_train_hog, X_test_hog
+    """
+    X_train_raw = np.load(PROCESSED_DIR / "X_train_raw.npy")
+    X_test_raw = np.load(PROCESSED_DIR / "X_test_raw.npy")
+    y_train = np.load(PROCESSED_DIR / "y_train.npy")
+    y_test = np.load(PROCESSED_DIR / "y_test.npy")
+    X_train_hog = np.load(PROCESSED_DIR / "X_train_hog.npy")
+    X_test_hog = np.load(PROCESSED_DIR / "X_test_hog.npy")
+    return X_train_raw, X_test_raw, y_train, y_test, X_train_hog, X_test_hog
+
+
+# 1. Naive Baseline
+
+class MajorityClassifier:
+    """Naive baseline: always predicts the most frequent class in training."""
+
+    def __init__(self) -> None:
+        self.majority_class: int = 0
+
+    def fit(self, y: np.ndarray) -> "MajorityClassifier":
+        """Fit by finding the majority class label.
+
+        Args:
+            y: 1-D array of integer class labels.
+
+        Returns:
+            self
+        """
+        counts = np.bincount(y)
+        self.majority_class = int(np.argmax(counts))
+        return self
+
+    def predict(self, n_samples: int) -> np.ndarray:
+        """Return the majority class repeated n_samples times.
+
+        Args:
+            n_samples: Number of predictions to generate.
+
+        Returns:
+            Array of length n_samples, all equal to majority_class.
+        """
+        return np.full(n_samples, self.majority_class, dtype=np.int64)
+
+
+def train_naive(y_train: np.ndarray, y_test: np.ndarray) -> dict[str, Any]:
+    """Train and evaluate the majority class baseline.
+
+    Args:
+        y_train: Training labels.
+        y_test:  Test labels.
+
+    Returns:
+        Dictionary of evaluation metrics.
+    """
+    print(f"\nNaive Baseline")
+    clf = MajorityClassifier().fit(y_train)
+    preds = clf.predict(len(y_test))
+    acc = accuracy_score(y_test, preds)
+    print(f"  Majority class: {CLASSES[clf.majority_class]}")
+    print(f"  Test accuracy:  {acc:.4f}")
+
+    model_data = {"majority_class": clf.majority_class, "accuracy": acc}
+    joblib.dump(model_data, MODELS_DIR / "naive_model.pkl")
+
+    return {"model": "naive", "accuracy": acc}
+
+
+# 2. Classical ML
+
+def train_classical(
+    X_train_hog: np.ndarray,
+    X_test_hog: np.ndarray,
+    y_train: np.ndarray,
+    y_test: np.ndarray,
+) -> dict[str, Any]:
+    """Train Random Forest on HOG features and evaluate.
+
+    Args:
+        X_train_hog: Training HOG feature matrix.
+        X_test_hog:  Test HOG feature matrix.
+        y_train:     Training labels.
+        y_test:      Test labels.
+
+    Returns:
+        Dictionary of evaluation metrics.
+    """
+    print(f"\nClassical ML (Random Forest on HOG)")
+
+    # Standardise features
+    scaler = StandardScaler()
+    X_tr = scaler.fit_transform(X_train_hog)
+    X_te = scaler.transform(X_test_hog)
+
+    clf = RandomForestClassifier(
+        n_estimators=RF_N_ESTIMATORS,
+        max_depth=RF_MAX_DEPTH,
+        n_jobs=-1,
+        random_state=42,
+    )
+    t0 = time.time()
+    clf.fit(X_tr, y_train)
+    elapsed = time.time() - t0
+
+    preds = clf.predict(X_te)
+    acc = accuracy_score(y_test, preds)
+    report = classification_report(y_test, preds, target_names=CLASSES)
+
+    print(f"  Training time:  {elapsed:.1f}s")
+    print(f"  Test accuracy:  {acc:.4f}")
+    print(f"\n{report}")
+
+    joblib.dump({"clf": clf, "scaler": scaler}, MODELS_DIR / "classical_model.pkl")
+    _save_confusion_matrix(y_test, preds, "classical_confusion_matrix.png")
+
+    return {"model": "classical", "accuracy": acc, "training_time_s": elapsed}
+
+
+# 3. Deep Model
+
+class ScribblNet(nn.Module):
+    """Lightweight CNN for 28×28 grayscale sketch classification.
+
+    Architecture:
+        3 × (Conv2d → BatchNorm → ReLU → MaxPool)
+        Dropout → FC(1152→256) → ReLU → Dropout → FC(256→num_classes)
+    """
+
+    def __init__(self, num_classes: int = NUM_CLASSES) -> None:
+        super().__init__()
+        self.features = nn.Sequential(
+            nn.Conv2d(1, 32, kernel_size=3, padding=1),
+            nn.BatchNorm2d(32),
+            nn.ReLU(inplace=True),
+            nn.MaxPool2d(2),
+
+            nn.Conv2d(32, 64, kernel_size=3, padding=1),
+            nn.BatchNorm2d(64),
+            nn.ReLU(inplace=True),
+            nn.MaxPool2d(2),
+
+            nn.Conv2d(64, 128, kernel_size=3, padding=1),
+            nn.BatchNorm2d(128),
+            nn.ReLU(inplace=True),
+            nn.MaxPool2d(2),
+        )
+        # 28→14→7→3  ∴ feature map is 128×3×3 = 1152
+        self.classifier = nn.Sequential(
+            nn.Dropout(0.5),
+            nn.Linear(128 * 3 * 3, 256),
+            nn.ReLU(inplace=True),
+            nn.Dropout(0.3),
+            nn.Linear(256, num_classes),
+        )
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        """Forward pass.
+
+        Args:
+            x: Tensor of shape (B, 1, 28, 28), values in [0, 1].
+
+        Returns:
+            Logits tensor of shape (B, num_classes).
+        """
+        x = self.features(x)
+        x = x.view(x.size(0), -1)
+        return self.classifier(x)
+
+
+def make_dataloaders(
+    X_raw: np.ndarray,
+    y: np.ndarray,
+    X_test_raw: np.ndarray,
+    y_test: np.ndarray,
+    batch_size: int = DEEP_BATCH_SIZE,
+    train_fraction: float = 1.0,
+) -> tuple[DataLoader, DataLoader]:
+    """Build PyTorch DataLoaders from raw pixel arrays.
+
+    Pixel values are normalised to [0, 1].  Training set can be subsampled
+    via train_fraction for the sensitivity experiment.
+
+    Args:
+        X_raw:          Training pixel array (N, 784), uint8.
+        y:              Training labels.
+        X_test_raw:     Test pixel array.
+        y_test:         Test labels.
+        batch_size:     Minibatch size.
+        train_fraction: Fraction of training samples to use (0 < f ≤ 1).
+
+    Returns:
+        (train_loader, test_loader)
+    """
+    if train_fraction < 1.0:
+        n = max(1, int(len(X_raw) * train_fraction))
+        idx = np.random.default_rng(seed=7).permutation(len(X_raw))[:n]
+        X_raw = X_raw[idx]
+        y = y[idx]
+
+    def _to_tensor(X: np.ndarray, labels: np.ndarray) -> TensorDataset:
+        imgs = torch.from_numpy(X.astype(np.float32) / 255.0)
+        imgs = imgs.view(-1, 1, IMG_SIZE, IMG_SIZE)
+        return TensorDataset(imgs, torch.from_numpy(labels))
+
+    train_ds = _to_tensor(X_raw, y)
+    test_ds = _to_tensor(X_test_raw, y_test)
+
+    train_loader = DataLoader(train_ds, batch_size=batch_size, shuffle=True, num_workers=0)
+    test_loader = DataLoader(test_ds, batch_size=batch_size, shuffle=False, num_workers=0)
+    return train_loader, test_loader
+
+
+def train_one_epoch(
+    model: nn.Module,
+    loader: DataLoader,
+    optimizer: torch.optim.Optimizer,
+    criterion: nn.Module,
+    device: torch.device,
+) -> float:
+    """Run one training epoch and return average loss.
+
+    Args:
+        model:     ScribblNet instance.
+        loader:    Training DataLoader.
+        optimizer: Optimiser (Adam).
+        criterion: Loss function (CrossEntropyLoss).
+        device:    Torch device.
+
+    Returns:
+        Mean loss over all minibatches.
+    """
+    model.train()
+    total_loss = 0.0
+    for imgs, labels in loader:
+        imgs, labels = imgs.to(device), labels.to(device)
+        optimizer.zero_grad()
+        loss = criterion(model(imgs), labels)
+        loss.backward()
+        optimizer.step()
+        total_loss += loss.item()
+    return total_loss / len(loader)
+
+
+def evaluate(
+    model: nn.Module,
+    loader: DataLoader,
+    device: torch.device,
+) -> tuple[float, np.ndarray]:
+    """Evaluate model on a DataLoader.
+
+    Args:
+        model:  ScribblNet instance.
+        loader: Evaluation DataLoader.
+        device: Torch device.
+
+    Returns:
+        (accuracy, predictions_array)
+    """
+    model.eval()
+    all_preds, all_labels = [], []
+    with torch.no_grad():
+        for imgs, labels in loader:
+            imgs = imgs.to(device)
+            preds = model(imgs).argmax(dim=1).cpu().numpy()
+            all_preds.append(preds)
+            all_labels.append(labels.numpy())
+    preds = np.concatenate(all_preds)
+    labels = np.concatenate(all_labels)
+    return accuracy_score(labels, preds), preds
+
+
+def train_deep(
+    X_train_raw: np.ndarray,
+    X_test_raw: np.ndarray,
+    y_train: np.ndarray,
+    y_test: np.ndarray,
+    epochs: int = DEEP_EPOCHS,
+    train_fraction: float = 1.0,
+    save_model: bool = True,
+) -> dict[str, Any]:
+    """Train ScribblNet and evaluate on test set.
+
+    Args:
+        X_train_raw:    Raw training pixel array.
+        X_test_raw:     Raw test pixel array.
+        y_train:        Training labels.
+        y_test:         Test labels.
+        epochs:         Number of training epochs.
+        train_fraction: Fraction of training data to use.
+        save_model:     Whether to save weights to disk.
+
+    Returns:
+        Dictionary of evaluation metrics and training history.
+    """
+    print(f"\nDeep Model (ScribblNet, fraction={train_fraction:.0%})")
+    device = get_device()
+    print(f"  Device: {device}")
+
+    train_loader, test_loader = make_dataloaders(
+        X_train_raw, y_train, X_test_raw, y_test, train_fraction=train_fraction
+    )
+
+    model = ScribblNet(num_classes=NUM_CLASSES).to(device)
+    optimizer = torch.optim.Adam(
+        model.parameters(), lr=DEEP_LR, weight_decay=DEEP_WEIGHT_DECAY
+    )
+    scheduler = torch.optim.lr_scheduler.CosineAnnealingLR(optimizer, T_max=epochs)
+    criterion = nn.CrossEntropyLoss()
+
+    history = {"loss": [], "val_acc": []}
+    best_acc = 0.0
+
+    for epoch in range(1, epochs + 1):
+        loss = train_one_epoch(model, train_loader, optimizer, criterion, device)
+        acc, _ = evaluate(model, test_loader, device)
+        scheduler.step()
+        history["loss"].append(loss)
+        history["val_acc"].append(acc)
+        print(f"  epoch {epoch:02d}/{epochs}  loss={loss:.4f}  val_acc={acc:.4f}")
+
+        if acc > best_acc:
+            best_acc = acc
+            if save_model:
+                torch.save(model.state_dict(), MODELS_DIR / "deep_model.pth")
+
+    # Final evaluation with best weights
+    if save_model:
+        model.load_state_dict(torch.load(MODELS_DIR / "deep_model.pth", map_location=device))
+
+    final_acc, final_preds = evaluate(model, test_loader, device)
+    print(f"\n  Best test accuracy: {best_acc:.4f}")
+
+    if save_model:
+        report = classification_report(y_test, final_preds, target_names=CLASSES)
+        print(f"\n{report}")
+        _save_confusion_matrix(y_test, final_preds, "deep_confusion_matrix.png")
+        _save_training_curves(history)
+
+    return {"model": "deep", "accuracy": best_acc, "history": history}
+
+
+# Experiment: Training Size Sensitivity
+
+def run_experiment(
+    X_train_raw: np.ndarray,
+    X_test_raw: np.ndarray,
+    y_train: np.ndarray,
+    y_test: np.ndarray,
+    X_train_hog: np.ndarray,
+    X_test_hog: np.ndarray,
+) -> None:
+    """Training set size sensitivity analysis.
+
+    Sweeps over EXPERIMENT_FRACTIONS, training both the deep model and Random
+    Forest at each fraction, then plots accuracy vs number of training samples.
+
+    Motivation: Understanding how each model scales with data volume helps
+    justify architectural choices and highlights when more data is beneficial.
+
+    Args:
+        X_train_raw:  Raw training pixels.
+        X_test_raw:   Raw test pixels.
+        y_train:      Training labels.
+        y_test:       Test labels.
+        X_train_hog:  HOG training features.
+        X_test_hog:   HOG test features.
+    """
+    print(f"\nExperiment: Training Size Sensitivity")
+    deep_accs, rf_accs, n_samples = [], [], []
+    scaler = StandardScaler()
+    X_test_scaled = scaler.fit_transform(X_test_hog)
+
+    for frac in EXPERIMENT_FRACTIONS:
+        n = int(len(X_train_raw) * frac)
+        n_samples.append(n)
+        print(f"\n  Fraction={frac:.0%}  (n={n})")
+
+        # Deep model
+        result = train_deep(
+            X_train_raw, X_test_raw, y_train, y_test,
+            epochs=EXPERIMENT_EPOCHS, train_fraction=frac, save_model=False,
+        )
+        deep_accs.append(result["accuracy"])
+
+        # Random Forest
+        idx = np.random.default_rng(seed=42).permutation(len(X_train_hog))[:n]
+        X_tr = scaler.fit_transform(X_train_hog[idx])
+        rf = RandomForestClassifier(
+            n_estimators=100, n_jobs=-1, random_state=42
+        )
+        rf.fit(X_tr, y_train[idx])
+        rf_pred = rf.predict(X_test_scaled)
+        rf_accs.append(accuracy_score(y_test, rf_pred))
+        print(f"  RF acc={rf_accs[-1]:.4f}")
+
+    # Plot
+    fig, ax = plt.subplots(figsize=(8, 5))
+    ax.plot(n_samples, deep_accs, marker="o", linestyle="solid", label="ScribblNet (CNN)", linewidth=2, markersize=7)
+    ax.plot(n_samples, rf_accs, marker="s", linestyle="dashed", label="Random Forest (HOG)", linewidth=2, markersize=7)
+    ax.set_xlabel("Training samples", fontsize=12)
+    ax.set_ylabel("Test accuracy", fontsize=12)
+    ax.set_title("Training Set Size Sensitivity", fontsize=14)
+    ax.legend(fontsize=11)
+    ax.grid(True, alpha=0.3)
+    ax.set_ylim(0, 1)
+    plt.tight_layout()
+    out_path = OUTPUTS_DIR / "experiment_sensitivity.png"
+    fig.savefig(out_path, dpi=150)
+    plt.close(fig)
+    print(f"\n  Saved experiment plot → {out_path}")
+
+    results = {
+        "fractions": EXPERIMENT_FRACTIONS,
+        "n_samples": n_samples,
+        "deep_accs": deep_accs,
+        "rf_accs": rf_accs,
+    }
+    with open(OUTPUTS_DIR / "experiment_results.json", "w") as f:
+        json.dump(results, f, indent=2)
+    print("  Saved experiment_results.json")
+
+
+# Plotting Helpers
+
+def _save_confusion_matrix(
+    y_true: np.ndarray,
+    y_pred: np.ndarray,
+    filename: str,
+) -> None:
+    """Save a normalised confusion matrix heatmap.
+
+    Args:
+        y_true:   Ground truth labels.
+        y_pred:   Predicted labels.
+        filename: Output filename (saved under OUTPUTS_DIR).
+    """
+    cm = confusion_matrix(y_true, y_pred, normalize="true")
+    fig, ax = plt.subplots(figsize=(10, 8))
+    sns.heatmap(
+        cm,
+        annot=True,
+        fmt=".2f",
+        xticklabels=CLASSES,
+        yticklabels=CLASSES,
+        cmap="Blues",
+        ax=ax,
+        linewidths=0.5,
+    )
+    ax.set_xlabel("Predicted", fontsize=11)
+    ax.set_ylabel("True", fontsize=11)
+    ax.set_title(filename.replace("_", " ").replace(".png", "").title(), fontsize=13)
+    plt.xticks(rotation=45, ha="right")
+    plt.tight_layout()
+    fig.savefig(OUTPUTS_DIR / filename, dpi=150)
+    plt.close(fig)
+    print(f"  Saved {filename}")
+
+
+def _save_training_curves(history: dict[str, list[float]]) -> None:
+    """Save loss and validation accuracy curves for the deep model.
+
+    Args:
+        history: Dict with keys 'loss' and 'val_acc', each a list of per epoch values.
+    """
+    epochs = range(1, len(history["loss"]) + 1)
+    fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(11, 4))
+
+    ax1.plot(epochs, history["loss"], color="steelblue", marker="o", linestyle="solid", markersize=5)
+    ax1.set_xlabel("Epoch")
+    ax1.set_ylabel("Training Loss")
+    ax1.set_title("ScribblNet Training Loss")
+    ax1.grid(True, alpha=0.3)
+
+    ax2.plot(epochs, history["val_acc"], color="seagreen", marker="o", linestyle="solid", markersize=5)
+    ax2.set_xlabel("Epoch")
+    ax2.set_ylabel("Validation Accuracy")
+    ax2.set_title("ScribblNet Validation Accuracy")
+    ax2.grid(True, alpha=0.3)
+
+    plt.tight_layout()
+    fig.savefig(OUTPUTS_DIR / "deep_training_curves.png", dpi=150)
+    plt.close(fig)
+    print("  Saved deep_training_curves.png")
+
+
+def _save_model_comparison(results: list[dict[str, Any]]) -> None:
+    """Bar chart comparing test accuracy across all three models.
+
+    Args:
+        results: List of result dicts each containing 'model' and 'accuracy'.
+    """
+    names = [r["model"].capitalize() for r in results]
+    accs = [r["accuracy"] for r in results]
+
+    fig, ax = plt.subplots(figsize=(7, 4))
+    bars = ax.bar(names, accs, color=["#94a3b8", "#60a5fa", "#34d399"], width=0.5)
+    ax.set_ylim(0, 1)
+    ax.set_ylabel("Test Accuracy")
+    ax.set_title("Model Comparison")
+    for bar, acc in zip(bars, accs):
+        ax.text(
+            bar.get_x() + bar.get_width() / 2,
+            bar.get_height() + 0.01,
+            f"{acc:.3f}",
+            ha="center",
+            fontsize=12,
+        )
+    ax.grid(True, axis="y", alpha=0.3)
+    plt.tight_layout()
+    fig.savefig(OUTPUTS_DIR / "model_comparison.png", dpi=150)
+    plt.close(fig)
+    print("  Saved model_comparison.png")
+
+
+# Orchestrator
+
+def train_all() -> None:
+    """Train all three models, run the experiment, and save all artefacts."""
+    X_train_raw, X_test_raw, y_train, y_test, X_train_hog, X_test_hog = (
+        load_processed_data()
+    )
+
+    r_naive = train_naive(y_train, y_test)
+    r_classical = train_classical(X_train_hog, X_test_hog, y_train, y_test)
+    r_deep = train_deep(X_train_raw, X_test_raw, y_train, y_test)
+
+    _save_model_comparison([r_naive, r_classical, r_deep])
+
+    run_experiment(
+        X_train_raw, X_test_raw, y_train, y_test, X_train_hog, X_test_hog
+    )
+
+    summary = {
+        "naive_accuracy": r_naive["accuracy"],
+        "classical_accuracy": r_classical["accuracy"],
+        "deep_accuracy": r_deep["accuracy"],
+    }
+    with open(OUTPUTS_DIR / "results_summary.json", "w") as f:
+        json.dump(summary, f, indent=2)
+
+    print("\nTraining complete. Summary:")
+    for k, v in summary.items():
+        print(f"  {k}: {v:.4f}")
+
+
+if __name__ == "__main__":
+    train_all()

setup.py

@@ -0,0 +1,56 @@
+"""
+setup.py – Orchestrates the full ScribblBot pipeline:
+    1. Download Quick Draw data (make_dataset.py)
+    2. Build features           (build_features.py)
+    3. Train all models         (model.py)
+
+Usage:
+    python setup.py            # run full pipeline
+    python setup.py --skip_download  # skip if data already downloaded
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+from scripts.make_dataset import download_all
+from scripts.build_features import build_all
+from scripts.model import train_all
+
+
+def run(skip_download: bool = False) -> None:
+    """Execute the complete data and training pipeline.
+
+    Args:
+        skip_download: If True, skip the dataset download step.
+                       Useful when raw .npy files are already present.
+    """
+    print("ScribblBot setup pipeline starting")
+
+    if not skip_download:
+        print("\n[1/3] Downloading dataset ...")
+        download_all()
+    else:
+        print("\n[1/3] Skipping download (--skip_download)")
+
+    print("\n[2/3] Building features ...")
+    build_all()
+
+    print("\n[3/3] Training models ...")
+    train_all()
+
+    print("\nSetup complete. Run the app with:")
+    print("  python app.py")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="ScribblBot full pipeline setup")
+    parser.add_argument(
+        "--skip_download",
+        action="store_true",
+        help="Skip dataset download (use if .npy files already exist in data/raw/)",
+    )
+    args = parser.parse_args()
+    run(skip_download=args.skip_download)