polish: hero header + detection legend + footer (Off-Brand); document Modal training pipeline + published artifacts

README.md

@@ -32,33 +32,69 @@ in 10 days for the [Build Small Hackathon](https://huggingface.co/build-small-ha
 
 Point a phone at any honeycomb frame, get back:
 
-- bee / drone / queen / varroa-mite detections with bounding boxes
+- queen / worker / drone / varroa-mite detections with bounding boxes
 - a narrative inspection report
 - auto-saved to a per-hive registry
 - weekly PDF report on demand
 
 All local. No cloud APIs at inference.
 
-## Architecture
+## Architecture: two tiny specialists + one small generalist
 
-| Layer | Model | Job |
-|---|---|---|
-| Specialist | [Custom YOLOv8s](https://huggingface.co/maryammeda/apiarist-honey-bee-detector) (22 MB) | Detects + counts bees, drones, queens, varroa mites |
-| Generalist | [Qwen2.5-VL-3B-Instruct](https://huggingface.co/Qwen/Qwen2.5-VL-3B-Instruct) | Writes the narrative inspection report |
-| Persistence | SQLite | Hive registry + inspection history |
-| Reports | ReportLab | Weekly PDF generation |
+| Layer | Model | Params | Job |
+|---|---|---|---|
+| Detector | [Custom YOLOv8s](https://huggingface.co/maryammeda/apiarist-honey-bee-detector) | ~11M | Locates + counts bees, drones, queens, varroa mites |
+| Queen verifier | [Custom EfficientNet-B0](https://huggingface.co/maryammeda/apiarist-queen-classifier) | ~5M | Confirms the queen on cropped bees (F1 0.96) |
+| Narrator | [Qwen2.5-VL-3B-Instruct](https://huggingface.co/Qwen/Qwen2.5-VL-3B-Instruct) | 3B | Writes the narrative inspection report |
+| Persistence | SQLite | - | Hive registry + inspection history |
+| Reports | ReportLab | - | Weekly PDF generation |
+
+The two custom models do the precise work (localization + queen ID); the
+3B VLM only writes prose grounded in their findings. That's why a tiny
+specialist beats a giant generalist at counting bees.
+
+## Built with Modal
+
+Both custom models were fine-tuned on [Modal](https://modal.com) using
+the hackathon's free GPU credits. Reproducible scripts live in `scripts/`:
+
+| Script | What it does | GPU | Time | Cost |
+|---|---|---|---|---|
+| `train_yolo_on_modal.py` | Fine-tunes YOLOv8s on 3,308 labeled bee images (60 epochs) | 1x T4 | ~50 min | ~$0.40 |
+| `train_queen_classifier.py` | Trains EfficientNet-B0 queen-vs-worker on ~31k bee crops | 1x T4 | ~12 min | ~$0.15 |
+
+Each script is a self-contained Modal app: it pulls the dataset from
+Roboflow inside the container, trains, writes weights to a Modal Volume,
+and exits. No local GPU, no notebook babysitting. Run with:
+
+```bash
+modal run scripts/train_yolo_on_modal.py
+modal run scripts/train_queen_classifier.py
+```
+
+Across the build we ran four training jobs on Modal (dataset iterations
++ the final two shipped models) for well under $1 of credit.
 
 ## Stack
 
-- [Hugging Face Spaces](https://huggingface.co/spaces) on ZeroGPU
+- [Hugging Face Spaces](https://huggingface.co/spaces) on ZeroGPU for inference
 - [Gradio](https://gradio.app) with a custom field-tool theme
-- [Modal](https://modal.com) for fine-tuning the YOLO (1× T4, 60 epochs)
-- Training data: [Hendricks Ricky bee-project](https://universe.roboflow.com/hendricks_ricky-hotmail-de/bee-project) (3,308 imgs, 892 queens)
+- [Modal](https://modal.com) for all model fine-tuning
+- Training data: [Hendricks Ricky bee-project](https://universe.roboflow.com/hendricks_ricky-hotmail-de/bee-project) (3,308 imgs, 892 queens) on Roboflow Universe
 - Context imagery: [Apiarist iNaturalist bees dataset](https://huggingface.co/datasets/maryammeda/apiarist-inaturalist-bees)
 
-## Badges chased
+## Published artifacts (all open, CC/Apache licensed)
+
+- Model: [apiarist-honey-bee-detector](https://huggingface.co/maryammeda/apiarist-honey-bee-detector)
+- Model: [apiarist-queen-classifier](https://huggingface.co/maryammeda/apiarist-queen-classifier)
+- Dataset: [apiarist-inaturalist-bees](https://huggingface.co/datasets/maryammeda/apiarist-inaturalist-bees)
+
+## Operating note
 
- Off the Grid · Well-Tuned · Off-Brand · Sharing is Caring · Field Notes
+Queen detection is strongest on close-up macro shots of frames (a bee or
+small cluster filling the frame). Very wide shots with hands and
+background are harder. The app shows the specialist's confidence so you
+always know how much to trust a given call.
 
 ## License
 

app.py

@@ -461,46 +461,106 @@ def view_hive_history(hive_name):
 
 
 custom_css = """
+@import url('https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,600;9..144,800&family=JetBrains+Mono:wght@400;600&display=swap');
+
 .gradio-container {
-    background: linear-gradient(180deg, #1a1410 0%, #2a1f15 100%) !important;
+    background:
+        radial-gradient(1200px 500px at 80% -10%, rgba(244,163,0,0.10), transparent 60%),
+        linear-gradient(180deg, #17110c 0%, #221913 55%, #2a1f15 100%) !important;
     color: #f4e4bc !important;
-    font-family: 'JetBrains Mono', 'Courier New', monospace !important;
-    max-width: 1400px !important;
+    font-family: 'JetBrains Mono', ui-monospace, 'Courier New', monospace !important;
+    max-width: 1320px !important;
     margin: 0 auto !important;
 }
-h1 { color: #f4a300 !important; letter-spacing: 0.05em; }
-h2, h3 { color: #f4a300 !important; }
+
+/* ----- Hero header ----- */
+#apiarist-hero {
+    border: 1px solid rgba(244,163,0,0.30);
+    border-radius: 18px;
+    padding: 22px 26px;
+    margin: 6px 0 14px 0;
+    background:
+        linear-gradient(135deg, rgba(244,163,0,0.14) 0%, rgba(42,31,21,0.20) 55%);
+    box-shadow: 0 8px 30px rgba(0,0,0,0.35), inset 0 1px 0 rgba(255,214,102,0.15);
+}
+#apiarist-hero h1 {
+    font-family: 'Fraunces', Georgia, serif !important;
+    font-weight: 800 !important;
+    font-size: 2.5rem !important;
+    letter-spacing: 0.04em;
+    margin: 0 0 4px 0 !important;
+    color: #ffc23d !important;
+    text-shadow: 0 2px 12px rgba(244,163,0,0.25);
+}
+#apiarist-hero .tagline {
+    color: #e8d2a0 !important;
+    font-size: 0.98rem;
+    margin: 0;
+}
+#apiarist-hero .pills { margin-top: 12px; }
+#apiarist-hero .pill {
+    display: inline-block;
+    border: 1px solid rgba(244,163,0,0.40);
+    border-radius: 999px;
+    padding: 3px 11px;
+    margin: 3px 6px 0 0;
+    font-size: 0.74rem;
+    color: #ffd066;
+    background: rgba(244,163,0,0.08);
+    white-space: nowrap;
+}
+
+h1, h2, h3 { color: #f4a300 !important; font-family: 'Fraunces', Georgia, serif !important; }
 h4 { color: #ffd066 !important; }
-button.primary,
-button[variant="primary"] {
-    background: linear-gradient(180deg, #ffb733 0%, #f4a300 100%) !important;
+
+button.primary, button[variant="primary"] {
+    background: linear-gradient(180deg, #ffc23d 0%, #f4a300 100%) !important;
     color: #1a1410 !important;
-    font-weight: bold !important;
+    font-weight: 700 !important;
     border: none !important;
-    box-shadow: 0 2px 8px rgba(244, 163, 0, 0.25) !important;
+    border-radius: 12px !important;
+    box-shadow: 0 3px 12px rgba(244,163,0,0.30) !important;
     transition: transform 80ms ease, box-shadow 200ms ease !important;
 }
 button.primary:hover {
     transform: translateY(-1px);
-    box-shadow: 0 4px 14px rgba(244, 163, 0, 0.40) !important;
+    box-shadow: 0 6px 20px rgba(244,163,0,0.45) !important;
 }
+
 .gr-box, .block, .gradio-container .block {
-    border-color: rgba(244, 163, 0, 0.35) !important;
-    background: rgba(42, 31, 21, 0.4) !important;
+    border-color: rgba(244,163,0,0.28) !important;
+    background: rgba(36,26,18,0.55) !important;
+    border-radius: 14px !important;
 }
 .tabs > .tab-nav > button.selected {
-    color: #f4a300 !important;
+    color: #ffc23d !important;
     border-bottom: 2px solid #f4a300 !important;
 }
-.gradio-container a {
-    color: #ffd066 !important;
+.gradio-container a { color: #ffd066 !important; }
+.gradio-container a:hover { color: #ffe599 !important; text-decoration: underline; }
+table { border-color: rgba(244,163,0,0.25) !important; }
+
+/* ----- Detection legend ----- */
+#legend {
+    display: flex; flex-wrap: wrap; gap: 14px;
+    font-size: 0.82rem; color: #e8d2a0;
+    padding: 4px 2px 2px 2px;
 }
-.gradio-container a:hover {
-    color: #ffe599 !important;
-    text-decoration: underline;
+#legend .chip { display: inline-flex; align-items: center; gap: 6px; }
+#legend .sw {
+    width: 13px; height: 13px; border-radius: 3px; display: inline-block;
+    border: 1px solid rgba(255,255,255,0.25);
 }
-table {
-    border-color: rgba(244, 163, 0, 0.25) !important;
+.sw-queen  { background: #32ff64; }
+.sw-bee    { background: #f4a300; }
+.sw-drone  { background: #ff5050; }
+.sw-mite   { background: #dc32dc; }
+
+/* ----- Footer ----- */
+#apiarist-footer {
+    margin-top: 22px; padding-top: 14px;
+    border-top: 1px solid rgba(244,163,0,0.20);
+    color: #b8a079; font-size: 0.8rem; text-align: center;
 }
 """
 
@@ -530,15 +590,27 @@ def build_ui() -> gr.Blocks:
     _seed_sample_data()
 
     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.*"
+        gr.HTML(
+            """
+            <div id="apiarist-hero">
+              <h1>&#128029; APIARIST</h1>
+              <p class="tagline">Offline AI hive-frame inspector for backyard
+              beekeepers &mdash; finds the queen, counts bees &amp; drones,
+              flags varroa mites, all on a laptop with no cloud.</p>
+              <div class="pills">
+                <span class="pill">Custom YOLOv8s detector</span>
+                <span class="pill">EfficientNet-B0 queen classifier</span>
+                <span class="pill">Qwen2.5-VL-3B narrator</span>
+                <span class="pill">Runs on ZeroGPU</span>
+                <span class="pill">No cloud APIs</span>
+              </div>
+            </div>
+            """
         )
 
         with gr.Tabs():
             # ------- INSPECT TAB -------
-            with gr.Tab(" Inspect"):
+            with gr.Tab("Inspect"):
                 with gr.Row():
                     with gr.Column():
                         hive_input = gr.Dropdown(
@@ -595,12 +667,22 @@ def build_ui() -> gr.Blocks:
                             )
                     with gr.Column():
                         annotated_output = gr.Image(label="Annotated Frame")
+                        gr.HTML(
+                            """
+                            <div id="legend">
+                              <span class="chip"><span class="sw sw-queen"></span>Queen</span>
+                              <span class="chip"><span class="sw sw-bee"></span>Worker bee</span>
+                              <span class="chip"><span class="sw sw-drone"></span>Drone</span>
+                              <span class="chip"><span class="sw sw-mite"></span>Varroa mite</span>
+                            </div>
+                            """
+                        )
                         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.Tab("Hives") as hives_tab:
                 with gr.Row():
                     with gr.Column(scale=1):
                         gr.Markdown("### Add a Hive")
@@ -662,7 +744,7 @@ def build_ui() -> gr.Blocks:
                     )
 
             # ------- COMPARE TAB -------
-            with gr.Tab(" Compare"):
+            with gr.Tab("Compare"):
                 gr.Markdown(
                     "### Apiarist vs raw generalist VLM\n"
                     "Same image, two pipelines. Apiarist combines a "
@@ -739,10 +821,22 @@ internet required.
 
 ### Badges chased
 
- Off the Grid · Well-Tuned · Off-Brand · Sharing is Caring · Field Notes
+Off the Grid - Well-Tuned - Off-Brand - Sharing is Caring
 """
                 )
 
+        gr.HTML(
+            """
+            <div id="apiarist-footer">
+              Apiarist - built for the Build Small Hackathon -
+              custom YOLOv8s + EfficientNet-B0 + Qwen2.5-VL-3B -
+              trained on <a href="https://modal.com">Modal</a>,
+              served on <a href="https://huggingface.co/docs/hub/spaces-zerogpu">ZeroGPU</a>.
+              Fully offline at inference.
+            </div>
+            """
+        )
+
         # ---- wiring ----
 
         analyze_btn.click(