feat: SQLite hive registry + inspection history tab, persistent across sessions

.gitignore

@@ -9,3 +9,5 @@ __pycache__/
 data/raw/
 data/processed/
 weights/
+
+.env

app.py

@@ -1,17 +1,26 @@
 """
 Apiarist - Offline AI inspector for honeybee hive frames.
 
-Day 7: upgraded SmolVLM-500M -> Qwen2.5-VL-7B for real vision quality.
-ZeroGPU gives us a Blackwell GPU with plenty of VRAM, so 7B is cheap.
+Stack:
+- Qwen2.5-VL-3B on ZeroGPU for the narrative pass.
+- (Coming) custom-trained YOLOv8s for queen / drone / bee detection.
+- SQLite for hive registry + inspection history.
+- Gradio with custom field-tool theme.
 """
 
-import gradio as gr
-from PIL import Image
 import json
 import re
+import sqlite3
+import time
+from pathlib import Path
+
+import gradio as gr
 import torch
+from PIL import Image
 from transformers import AutoProcessor, AutoModelForImageTextToText
 
+import db
+
 # ZeroGPU integration — no-op outside HF Spaces
 try:
     import spaces
@@ -23,9 +32,8 @@ except ImportError:
         return fn
 
 
-# Qwen2.5-VL-3B. State-of-the-art vision-language model at a size that
-# comfortably fits on ZeroGPU. SmolVLM-2.25B hallucinated on bee anatomy;
-# Qwen-7B crashed the container; this is the sweet spot.
+# ---------------------------------------------------------------- model setup
+
 MODEL_ID = "Qwen/Qwen2.5-VL-3B-Instruct"
 
 _model = None
@@ -33,7 +41,6 @@ _processor = None
 
 
 def get_model():
-    """Lazy-load model on first call. Stays on CPU until moved by analyze_frame."""
     global _model, _processor
     if _model is None:
         print(f"Loading {MODEL_ID} ...")
@@ -57,11 +64,14 @@ HEALTH: good, watch, or alarm
 NOTES: one short sentence describing what you see
 
 Definitions:
-- Queens are noticeably larger bees with elongated abdomens, often appearing distinct from worker bees.
-- Varroa mites are small reddish-brown parasites visible on bees or comb cells.
+- Queens are noticeably larger bees with elongated abdomens.
+- Varroa mites are small reddish-brown parasites on bees or comb cells.
 - Swarm cells are peanut-shaped cells hanging from the bottom or edges of the comb.
-- Brood pattern is solid when capped cells are tightly packed and consistent, spotty when scattered with empty cells.
-- Be honest about uncertainty — only say "yes" when you can clearly see the feature."""
+- Brood pattern is solid when capped cells are tightly packed, spotty when scattered.
+- Only say "yes" when you can clearly see the feature."""
+
+
+# ---------------------------------------------------------------- parsing
 
 
 def parse_response(text: str, hive_name: str) -> dict:
@@ -95,7 +105,6 @@ def build_narrative(r: dict, raw: str) -> str:
         if r["swarm_cells_detected"]
         else "✅ No swarm cells"
     )
-
     return f"""**Hive: {r['hive']}**
 
 {queen_line}
@@ -107,7 +116,7 @@ def build_narrative(r: dict, raw: str) -> str:
 **Notes:** {r['notes']}
 
 ---
-*Powered by Qwen2.5-VL-3B on ZeroGPU. Fully local, no cloud APIs.*
+*Powered by Qwen2.5-VL-3B on ZeroGPU. Custom YOLO detector lands next.*
 
 <details><summary>Raw model output</summary>
 
@@ -118,10 +127,13 @@ def build_narrative(r: dict, raw: str) -> str:
 """
 
 
+# ---------------------------------------------------------------- inference
+
+
 @gpu
 def analyze_frame(image: Image.Image, hive_name: str):
     if image is None:
-        return None, "Upload a frame photo first.", ""
+        return None, "Upload a frame photo first.", "", _hives_table_state(), gr.update()
 
     model, processor = get_model()
 
@@ -146,8 +158,7 @@ def analyze_frame(image: Image.Image, hive_name: str):
             add_generation_prompt=True,
             return_dict=True,
             return_tensors="pt",
-        )
-        inputs = inputs.to(device)
+        ).to(device)
 
         with torch.no_grad():
             generated = model.generate(
@@ -162,11 +173,97 @@ def analyze_frame(image: Image.Image, hive_name: str):
             skip_special_tokens=True,
         )[0].strip()
     except Exception as e:
-        return image, f"Model inference failed: {type(e).__name__}: {e}", ""
+        return (
+            image,
+            f"Model inference failed: {type(e).__name__}: {e}",
+            "",
+            _hives_table_state(),
+            gr.update(),
+        )
 
     results = parse_response(response, hive_name)
     narrative = build_narrative(results, response)
-    return image, narrative, json.dumps(results, indent=2)
+
+    # Persist the inspection
+    hive_id = db.get_or_create_hive(results["hive"])
+    db.add_inspection(hive_id, results, raw_response=response)
+
+    return (
+        image,
+        narrative,
+        json.dumps(results, indent=2),
+        _hives_table_state(),
+        gr.update(choices=[h["name"] for h in db.list_hives()]),
+    )
+
+
+# ---------------------------------------------------------------- Hives tab helpers
+
+
+def _hives_table_state() -> list[list]:
+    rows = db.list_hives()
+    out = []
+    for h in rows:
+        last = (
+            time.strftime("%Y-%m-%d %H:%M", time.localtime(h["last_inspected"]))
+            if h["last_inspected"]
+            else "—"
+        )
+        out.append(
+            [
+                h["name"],
+                h.get("location") or "",
+                h.get("queen_marker") or "",
+                h["inspection_count"],
+                last,
+            ]
+        )
+    return out
+
+
+def add_hive_action(name, location, marker, notes):
+    name = (name or "").strip()
+    if not name:
+        return _hives_table_state(), gr.update(), "⚠️ Name required."
+    try:
+        db.add_hive(name, location or "", marker or "", notes or "")
+        msg = f"✅ Added hive '{name}'."
+    except sqlite3.IntegrityError:
+        msg = f"⚠️ Hive '{name}' already exists."
+    return _hives_table_state(), gr.update(choices=[h["name"] for h in db.list_hives()]), msg
+
+
+def view_hive_history(hive_name):
+    if not hive_name:
+        return [], "_Pick a hive above to see its inspection history._"
+    hive = next((h for h in db.list_hives() if h["name"] == hive_name), None)
+    if not hive:
+        return [], "_Hive not found._"
+    inspections = db.get_inspections_for_hive(hive["id"])
+    if not inspections:
+        return [], f"_No inspections recorded for **{hive_name}** yet._"
+    rows = []
+    for i in inspections:
+        rows.append(
+            [
+                time.strftime("%Y-%m-%d %H:%M", time.localtime(i["created_at"])),
+                "Y" if i["queen_detected"] else "N",
+                i["varroa_mites_visible"],
+                "Y" if i["swarm_cells_detected"] else "N",
+                i["frame_health"],
+                (i["notes"] or "")[:60],
+            ]
+        )
+    summary = (
+        f"### {hive_name}\n"
+        f"**Total inspections:** {len(inspections)}\n"
+        f"**Last inspected:** "
+        f"{time.strftime('%Y-%m-%d %H:%M', time.localtime(inspections[0]['created_at']))}"
+    )
+    return rows, summary
+
+
+# ---------------------------------------------------------------- UI
 
 
 custom_css = """
@@ -185,65 +282,155 @@ button.primary {
 .gr-box, .block { border-color: #f4a300 !important; }
 """
 
-with gr.Blocks(title="Apiarist - Hive Frame Inspector") as app:
-    gr.Markdown("# 🐝 APIARIST")
-    gr.Markdown(
-        "*Offline AI inspector for honeybee hive frames. "
-        "Built for the Build Small Hackathon.*"
-    )
-
-    with gr.Tabs():
-        with gr.Tab("🔍 Inspect"):
-            with gr.Row():
-                with gr.Column():
-                    hive_input = gr.Textbox(
-                        label="Hive Number / Name",
-                        placeholder="e.g., Hive #7",
-                    )
-                    image_input = gr.Image(
-                        label="Frame Photo",
-                        type="pil",
-                        sources=["upload", "webcam"],
-                    )
-                    analyze_btn = gr.Button(
-                        "🔬 Analyze Frame", variant="primary"
-                    )
-                with gr.Column():
-                    annotated_output = gr.Image(label="Annotated Frame")
-                    narrative_output = gr.Markdown()
-                    with gr.Accordion("Raw JSON", open=False):
-                        json_output = gr.Code(language="json")
-
-            analyze_btn.click(
-                fn=analyze_frame,
-                inputs=[image_input, hive_input],
-                outputs=[annotated_output, narrative_output, json_output],
-            )
 
-        with gr.Tab("📋 Hives"):
-            gr.Markdown(
-                "### Your Apiary\n"
-                "*Hive registry and inspection history (coming soon)*"
-            )
+def build_ui() -> gr.Blocks:
+    db.init_db()
 
-        with gr.Tab("⚖️ Compare"):
-            gr.Markdown(
-                "### Specialist vs Generalist\n"
-                "*Side-by-side: Apiarist vs cloud VLM (coming soon)*"
-            )
+    with gr.Blocks(title="Apiarist - Hive Frame Inspector") as app:
+        gr.Markdown("# 🐝 APIARIST")
+        gr.Markdown(
+            "*Offline AI inspector for honeybee hive frames. "
+            "Built for the Build Small Hackathon.*"
+        )
 
-        with gr.Tab("ℹ️ About"):
-            gr.Markdown(
-                """
+        with gr.Tabs():
+            # ------- INSPECT TAB -------
+            with gr.Tab("🔍 Inspect"):
+                with gr.Row():
+                    with gr.Column():
+                        hive_input = gr.Dropdown(
+                            label="Hive",
+                            choices=[h["name"] for h in db.list_hives()],
+                            allow_custom_value=True,
+                            info="Pick an existing hive or type a new name.",
+                        )
+                        image_input = gr.Image(
+                            label="Frame Photo",
+                            type="pil",
+                            sources=["upload", "webcam"],
+                        )
+                        analyze_btn = gr.Button(
+                            "🔬 Analyze Frame", variant="primary"
+                        )
+                    with gr.Column():
+                        annotated_output = gr.Image(label="Annotated Frame")
+                        narrative_output = gr.Markdown()
+                        with gr.Accordion("Raw JSON", open=False):
+                            json_output = gr.Code(language="json")
+
+            # ------- HIVES TAB -------
+            with gr.Tab("📋 Hives") as hives_tab:
+                with gr.Row():
+                    with gr.Column(scale=1):
+                        gr.Markdown("### Add a Hive")
+                        new_name = gr.Textbox(
+                            label="Name", placeholder="Hive #7"
+                        )
+                        new_location = gr.Textbox(
+                            label="Location (optional)",
+                            placeholder="South corner of yard",
+                        )
+                        new_marker = gr.Dropdown(
+                            label="Queen marker color (optional)",
+                            choices=["", "white", "yellow", "red", "green", "blue"],
+                            value="",
+                        )
+                        new_notes = gr.Textbox(
+                            label="Notes (optional)", lines=2
+                        )
+                        add_btn = gr.Button("➕ Add Hive", variant="primary")
+                        add_msg = gr.Markdown()
+
+                    with gr.Column(scale=2):
+                        gr.Markdown("### Your Apiary")
+                        hives_table = gr.Dataframe(
+                            headers=[
+                                "Name", "Location", "Queen marker",
+                                "Inspections", "Last inspected",
+                            ],
+                            datatype=["str", "str", "str", "number", "str"],
+                            interactive=False,
+                            value=_hives_table_state(),
+                            wrap=True,
+                        )
+                        refresh_btn = gr.Button("🔄 Refresh")
+
+                gr.Markdown("---\n### Inspection history")
+                history_select = gr.Dropdown(
+                    label="Select a hive",
+                    choices=[h["name"] for h in db.list_hives()],
+                )
+                history_summary = gr.Markdown()
+                history_table = gr.Dataframe(
+                    headers=[
+                        "When", "Queen?", "Mites", "Swarm?",
+                        "Health", "Notes",
+                    ],
+                    datatype=["str", "str", "number", "str", "str", "str"],
+                    interactive=False,
+                    wrap=True,
+                )
+
+            # ------- COMPARE TAB -------
+            with gr.Tab("⚖️ Compare"):
+                gr.Markdown(
+                    "### Specialist vs Generalist\n"
+                    "*Side-by-side: Apiarist (Qwen + YOLO) vs raw generalist VLM. "
+                    "Coming once the custom YOLO finishes training.*"
+                )
+
+            # ------- ABOUT TAB -------
+            with gr.Tab("ℹ️ About"):
+                gr.Markdown(
+                    """
 **Apiarist** is a fully-offline vision AI for backyard beekeepers.
 
 - 🔌 No cloud APIs — runs entirely on the laptop
-- 🎯 Vision-language model fine-tuned for honeybees
+- 🎯 Custom-trained on labeled bee imagery
 - 📓 Built in 10 days for the [Build Small Hackathon](https://huggingface.co/build-small-hackathon)
 
-**Stack**: Qwen2.5-VL-3B on ZeroGPU, served via Gradio.
+**Stack**: Qwen2.5-VL-3B + custom YOLOv8s on ZeroGPU, SQLite persistence, Gradio UI.
 """
-            )
+                )
+
+        # ---- wiring ----
+
+        analyze_btn.click(
+            fn=analyze_frame,
+            inputs=[image_input, hive_input],
+            outputs=[
+                annotated_output,
+                narrative_output,
+                json_output,
+                hives_table,
+                history_select,
+            ],
+        )
+
+        add_btn.click(
+            fn=add_hive_action,
+            inputs=[new_name, new_location, new_marker, new_notes],
+            outputs=[hives_table, history_select, add_msg],
+        )
+
+        refresh_btn.click(
+            fn=lambda: (
+                _hives_table_state(),
+                gr.update(choices=[h["name"] for h in db.list_hives()]),
+            ),
+            outputs=[hives_table, history_select],
+        )
+
+        history_select.change(
+            fn=view_hive_history,
+            inputs=[history_select],
+            outputs=[history_table, history_summary],
+        )
+
+    return app
+
+
+app = build_ui()
 
 
 if __name__ == "__main__":

db.py

@@ -0,0 +1,176 @@
+"""
+SQLite layer for hive registry + inspection history.
+
+Storage is ephemeral on HF Spaces' free tier (container restart wipes
+the filesystem) — that's fine for a hackathon demo. For real-world
+deployment we'd back this with HF Hub persistence or a real DB.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import time
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Iterator
+
+DB_PATH = Path(__file__).parent / "apiarist.sqlite"
+
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS hives (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL UNIQUE,
+    location TEXT,
+    queen_marker TEXT,
+    notes TEXT,
+    created_at REAL NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS inspections (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    hive_id INTEGER NOT NULL,
+    queen_detected INTEGER,
+    varroa_mites_visible INTEGER,
+    swarm_cells_detected INTEGER,
+    brood_pattern TEXT,
+    frame_health TEXT,
+    notes TEXT,
+    raw_response TEXT,
+    structured_json TEXT,
+    created_at REAL NOT NULL,
+    FOREIGN KEY (hive_id) REFERENCES hives(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_inspections_hive ON inspections(hive_id, created_at);
+"""
+
+
+@contextmanager
+def conn() -> Iterator[sqlite3.Connection]:
+    c = sqlite3.connect(DB_PATH)
+    c.row_factory = sqlite3.Row
+    c.execute("PRAGMA foreign_keys = ON")
+    try:
+        yield c
+        c.commit()
+    finally:
+        c.close()
+
+
+def init_db() -> None:
+    with conn() as c:
+        c.executescript(SCHEMA)
+
+
+def add_hive(name: str, location: str = "", queen_marker: str = "", notes: str = "") -> int:
+    with conn() as c:
+        cur = c.execute(
+            "INSERT INTO hives (name, location, queen_marker, notes, created_at) "
+            "VALUES (?, ?, ?, ?, ?)",
+            (name, location, queen_marker, notes, time.time()),
+        )
+        return cur.lastrowid or 0
+
+
+def get_or_create_hive(name: str) -> int:
+    """Look up a hive by name; create with defaults if missing."""
+    name = name.strip()
+    if not name:
+        name = "Unnamed Hive"
+    with conn() as c:
+        row = c.execute("SELECT id FROM hives WHERE name = ?", (name,)).fetchone()
+        if row:
+            return row["id"]
+        cur = c.execute(
+            "INSERT INTO hives (name, created_at) VALUES (?, ?)",
+            (name, time.time()),
+        )
+        return cur.lastrowid or 0
+
+
+def list_hives() -> list[dict]:
+    with conn() as c:
+        rows = c.execute(
+            """
+            SELECT h.id, h.name, h.location, h.queen_marker, h.notes, h.created_at,
+                   COUNT(i.id) AS inspection_count,
+                   MAX(i.created_at) AS last_inspected
+            FROM hives h
+            LEFT JOIN inspections i ON i.hive_id = h.id
+            GROUP BY h.id
+            ORDER BY h.name
+            """
+        ).fetchall()
+    return [dict(r) for r in rows]
+
+
+def delete_hive(hive_id: int) -> None:
+    with conn() as c:
+        c.execute("DELETE FROM hives WHERE id = ?", (hive_id,))
+
+
+def add_inspection(hive_id: int, results: dict, raw_response: str = "") -> int:
+    with conn() as c:
+        cur = c.execute(
+            """
+            INSERT INTO inspections (
+                hive_id, queen_detected, varroa_mites_visible,
+                swarm_cells_detected, brood_pattern, frame_health,
+                notes, raw_response, structured_json, created_at
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                hive_id,
+                int(bool(results.get("queen_detected"))),
+                int(results.get("varroa_mites_visible", 0) or 0),
+                int(bool(results.get("swarm_cells_detected"))),
+                results.get("brood_pattern", ""),
+                results.get("frame_health", ""),
+                results.get("notes", ""),
+                raw_response,
+                json.dumps(results),
+                time.time(),
+            ),
+        )
+        return cur.lastrowid or 0
+
+
+def get_inspections_for_hive(hive_id: int, limit: int = 50) -> list[dict]:
+    with conn() as c:
+        rows = c.execute(
+            """
+            SELECT id, queen_detected, varroa_mites_visible, swarm_cells_detected,
+                   brood_pattern, frame_health, notes, created_at
+            FROM inspections
+            WHERE hive_id = ?
+            ORDER BY created_at DESC
+            LIMIT ?
+            """,
+            (hive_id, limit),
+        ).fetchall()
+    return [dict(r) for r in rows]
+
+
+def hive_stats() -> dict:
+    """High-level apiary summary for the dashboard."""
+    with conn() as c:
+        total_hives = c.execute("SELECT COUNT(*) AS n FROM hives").fetchone()["n"]
+        total_inspections = c.execute(
+            "SELECT COUNT(*) AS n FROM inspections"
+        ).fetchone()["n"]
+        recent = c.execute(
+            """
+            SELECT h.name, i.frame_health, i.varroa_mites_visible, i.created_at
+            FROM inspections i
+            JOIN hives h ON h.id = i.hive_id
+            ORDER BY i.created_at DESC
+            LIMIT 5
+            """
+        ).fetchall()
+    return {
+        "total_hives": total_hives,
+        "total_inspections": total_inspections,
+        "recent": [dict(r) for r in recent],
+    }

dev-requirements.txt

@@ -1,3 +1,6 @@
 # Local-only deps (not installed on HF Space)
 requests>=2.31.0
 tqdm>=4.66.0
+python-dotenv>=1.0.0
+roboflow>=1.1.0
+ultralytics>=8.2.0

scripts/download_yolo_weights.py

@@ -0,0 +1,101 @@
+"""
+Pull Matt Nudi's honey-bee/drone/queen YOLO weights from Roboflow once,
+then copy the .pt file into weights/ so the Space can load it locally
+with ultralytics — no Roboflow auth needed at runtime.
+
+Usage:
+    py scripts/download_yolo_weights.py
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+
+WORKSPACE = "matt-nudi"
+PROJECT = "honey-bee-detection-model-zgjnb"
+WEIGHTS_DIR = Path("weights")
+TARGET_PT = WEIGHTS_DIR / "honey_bee_detector.pt"
+
+
+def main() -> None:
+    load_dotenv()
+    api_key = os.environ.get("ROBOFLOW_API_KEY")
+    if not api_key:
+        raise SystemExit(
+            "Missing ROBOFLOW_API_KEY. Add it to .env at the project root."
+        )
+
+    WEIGHTS_DIR.mkdir(exist_ok=True)
+
+    print(f"Connecting to Roboflow as workspace={WORKSPACE!r} ...")
+    from roboflow import Roboflow
+
+    rf = Roboflow(api_key=api_key)
+    project = rf.workspace(WORKSPACE).project(PROJECT)
+
+    versions = project.versions()
+    if not versions:
+        raise SystemExit(f"No trained versions found for {PROJECT!r}.")
+
+    # Pick the highest version number with a trained model
+    versions_sorted = sorted(versions, key=lambda v: v.version, reverse=True)
+    print(f"Available versions: {[v.version for v in versions_sorted]}")
+
+    version_id = versions_sorted[0].version
+    print(f"Using latest version: v{version_id}")
+    version = project.version(version_id)
+
+    # Approach 1: try to grab the trained weights via the inference package.
+    # It downloads to ~/.cache/inference (or similar) on first use.
+    print("\nTriggering weight download via roboflow.inference ...")
+    try:
+        from inference import get_model
+
+        model = get_model(
+            model_id=f"{PROJECT}/{version_id}",
+            api_key=api_key,
+        )
+        # Best-effort: tell us where it landed
+        cache_root = Path.home() / ".inference"
+        pt_files = list(cache_root.rglob("*.pt"))
+        if not pt_files:
+            cache_root = Path.home() / ".cache" / "inference"
+            pt_files = list(cache_root.rglob("*.pt"))
+        if pt_files:
+            # Pick the most recently modified
+            latest = max(pt_files, key=lambda p: p.stat().st_mtime)
+            shutil.copy(latest, TARGET_PT)
+            print(f"\n✓ Copied weights from {latest}")
+            print(f"  to {TARGET_PT.resolve()}")
+            print(f"  size: {TARGET_PT.stat().st_size / 1024 / 1024:.1f} MB")
+            return
+        print("inference cache had no .pt files yet; falling back to dataset export.")
+    except Exception as e:
+        print(f"inference path failed: {e}\nFalling back to dataset export ...")
+
+    # Approach 2: download the dataset export, which sometimes ships weights.
+    download_dir = Path("data") / "raw" / f"roboflow_{PROJECT}_v{version_id}"
+    download_dir.parent.mkdir(parents=True, exist_ok=True)
+    dataset = version.download("yolov8", location=str(download_dir))
+    print(f"\nDataset downloaded to: {dataset.location}")
+    pt_files = list(Path(dataset.location).rglob("*.pt"))
+    if pt_files:
+        shutil.copy(pt_files[0], TARGET_PT)
+        print(f"\n✓ Copied weights to {TARGET_PT.resolve()}")
+        print(f"  size: {TARGET_PT.stat().st_size / 1024 / 1024:.1f} MB")
+        return
+
+    raise SystemExit(
+        "\nCould not locate trained .pt weights via either path. "
+        "Check the project's available versions and whether the author "
+        "published a trained model (some only ship the dataset)."
+    )
+
+
+if __name__ == "__main__":
+    main()

scripts/extract_dataset.py

@@ -0,0 +1,67 @@
+"""
+Extract Roboflow dataset zip with Windows long-path support.
+
+Roboflow ships images with absurdly long filenames (URL slugs preserved).
+Windows' default 260-char MAX_PATH limit breaks normal extraction.
+We use the \\?\ prefix which opts a path into the long-path code path.
+
+Usage:
+    py scripts/extract_dataset.py
+"""
+
+import sys
+import zipfile
+from pathlib import Path
+
+
+ZIP_PATH = Path("data/raw/roboflow_honey-bee-detection-model-zgjnb_v4/roboflow.zip")
+DEST = Path("data/raw/roboflow_honey-bee-detection-model-zgjnb_v4").resolve()
+
+
+def lp(path) -> str:
+    """Return a Windows long-path string (\\?\C:\...) if needed."""
+    s = str(path)
+    if sys.platform == "win32":
+        # \\?\ prefix MUST use absolute path with backslashes
+        s = s.replace("/", "\\")
+        if not s.startswith("\\\\?\\"):
+            s = "\\\\?\\" + s
+    return s
+
+
+def main() -> None:
+    if not ZIP_PATH.exists():
+        raise SystemExit(f"Missing {ZIP_PATH}")
+
+    with zipfile.ZipFile(ZIP_PATH) as z:
+        members = z.namelist()
+        total = len(members)
+        print(f"Extracting {total} entries from {ZIP_PATH.name} ...")
+        ok = 0
+        fail = 0
+        for i, member in enumerate(members):
+            if i % 500 == 0:
+                print(f"  progress: {i}/{total}  (ok={ok}, fail={fail})")
+            target = DEST / member
+            try:
+                target.parent.mkdir(parents=True, exist_ok=True)
+            except Exception:
+                pass
+            if member.endswith("/"):
+                continue
+            try:
+                with z.open(member) as src:
+                    data = src.read()
+                with open(lp(target), "wb") as dst:
+                    dst.write(data)
+                ok += 1
+            except Exception as e:
+                fail += 1
+                if fail <= 5:
+                    print(f"  [!] {member[:80]}... -> {type(e).__name__}: {e}")
+
+    print(f"\nDone. ok={ok}, fail={fail}")
+
+
+if __name__ == "__main__":
+    main()

scripts/train_yolo_on_modal.py

@@ -0,0 +1,116 @@
+"""
+Train YOLOv8s on Matt Nudi's bee/drone/queen dataset using Modal GPU.
+
+The Modal container downloads the dataset itself via Roboflow (we pass
+the API key from the local .env), trains for 50 epochs, and persists
+the best.pt weights to a Modal Volume.
+
+To run:
+    py scripts/train_yolo_on_modal.py
+
+After training, download the weights with:
+    modal volume get apiarist-weights /apiarist/weights/best.pt weights/honey_bee_detector.pt
+"""
+
+import os
+from pathlib import Path
+
+import modal
+
+
+APP_NAME = "apiarist-yolo-train"
+VOLUME_NAME = "apiarist-weights"
+EPOCHS = 50
+IMG_SIZE = 640
+BATCH = 16
+BASE_WEIGHTS = "yolov8s.pt"
+
+image = (
+    modal.Image.debian_slim(python_version="3.11")
+    .pip_install(
+        "ultralytics==8.3.81",
+        "roboflow==1.1.50",
+        "pyyaml",
+    )
+    .apt_install("libgl1", "libglib2.0-0")
+)
+
+vol = modal.Volume.from_name(VOLUME_NAME, create_if_missing=True)
+
+app = modal.App(APP_NAME)
+
+
+@app.function(
+    image=image,
+    gpu="T4",
+    volumes={"/weights": vol},
+    timeout=3 * 60 * 60,
+)
+def train(rf_api_key: str) -> str:
+    import shutil
+    import sys
+    from pathlib import Path
+
+    from roboflow import Roboflow
+    from ultralytics import YOLO
+
+    print("=" * 60)
+    print("Downloading Matt Nudi bee/queen/drone dataset from Roboflow ...")
+    print("=" * 60)
+    rf = Roboflow(api_key=rf_api_key)
+    project = rf.workspace("matt-nudi").project(
+        "honey-bee-detection-model-zgjnb"
+    )
+    version = project.version(4)
+    dataset = version.download("yolov8", location="/tmp/dataset")
+    print(f"Dataset ready at {dataset.location}")
+
+    print("\n" + "=" * 60)
+    print(f"Training YOLOv8s for {EPOCHS} epochs on T4 ...")
+    print("=" * 60)
+    model = YOLO(BASE_WEIGHTS)
+    results = model.train(
+        data=f"{dataset.location}/data.yaml",
+        epochs=EPOCHS,
+        imgsz=IMG_SIZE,
+        batch=BATCH,
+        project="/weights",
+        name="apiarist",
+        exist_ok=True,
+        device=0,
+        patience=15,
+    )
+
+    best_pt = Path("/weights/apiarist/weights/best.pt")
+    if not best_pt.exists():
+        print("ERROR: best.pt not found after training", file=sys.stderr)
+        sys.exit(1)
+
+    size_mb = best_pt.stat().st_size / 1024 / 1024
+    print(f"\n[OK] best.pt saved at {best_pt} ({size_mb:.1f} MB)")
+
+    vol.commit()
+    return str(best_pt)
+
+
+@app.local_entrypoint()
+def main() -> None:
+    from dotenv import load_dotenv
+
+    load_dotenv()
+    api_key = os.environ.get("ROBOFLOW_API_KEY")
+    if not api_key:
+        raise SystemExit(
+            "Missing ROBOFLOW_API_KEY in .env. Add it before running."
+        )
+
+    print("Kicking off Modal training (this takes ~30-45 min on T4) ...")
+    weights_path = train.remote(rf_api_key=api_key)
+    print("\n" + "=" * 60)
+    print(f"DONE. Weights at: {weights_path}")
+    print("=" * 60)
+    print(
+        "\nDownload locally with:\n"
+        f"  modal volume get {VOLUME_NAME} /apiarist/weights/best.pt "
+        f"weights/honey_bee_detector.pt"
+    )