feat: ranked top-3 queen candidates with probability shown - honest AI, user verifies

.gitignore

@@ -14,3 +14,4 @@ weights/*
 !sample_photos/
 
 .env
+debug_photos/

app.py

@@ -100,12 +100,17 @@ def parse_response(text: str, hive_name: str) -> dict:
 
 
 def build_narrative(r: dict, raw: str) -> str:
+    top_probs = r.get("cascade_top_probs", [])
     if r["queen_detected"]:
-        queen_line = "Queen detected (specialist classifier)"
-    elif r.get("queen_candidate"):
         queen_line = (
-            f"Likely queen flagged in cyan - **confirm by eye** "
-            f"(stands out by {r.get('queen_standout', 0):.1f} vs the other bees)"
+            f"**Queen detected** (specialist classifier, {int(top_probs[0]*100)}% confidence)"
+            if top_probs else "**Queen detected** (specialist classifier)"
+        )
+    elif r.get("queen_candidate") and top_probs:
+        cand_strs = [f"{int(p*100)}%" for p in top_probs[:3] if p >= 0.5]
+        queen_line = (
+            f"No high-confidence queen, but top candidates flagged in cyan "
+            f"({', '.join(cand_strs)}) - **confirm by eye**"
         )
     else:
         queen_line = (
@@ -281,6 +286,7 @@ def analyze_frame(image: Image.Image, hive_name: str):
         results["detector_used"] = True
         results["cascade_grid_size"] = cascade_info.get("grid_size", 0)
         results["cascade_queen_idx"] = sorted(cascade_info.get("queen_indices", set()))
+        results["cascade_top_probs"] = cascade_info.get("top_3_probs", [])
     else:
         results["detector_used"] = False
 

cascade.py

@@ -168,29 +168,49 @@ def verify_queens(
     if queen_clf.is_available():
         crops = [_crop_with_padding(image, d["bbox"]) for d in candidates]
         probs = queen_clf.classify_crops(crops)
-        # Best candidate = highest queen probability
-        best_idx = max(range(len(probs)), key=lambda i: probs[i]["queen_prob"])
-        best_prob = probs[best_idx]["queen_prob"]
-        is_queen = probs[best_idx]["is_queen"]
+
+        # Rank all candidates by queen probability, descending.
+        ranked = sorted(
+            range(len(candidates)),
+            key=lambda i: probs[i]["queen_prob"],
+            reverse=True,
+        )
+        top_idx = ranked[0] if ranked else None
+        top_prob = probs[top_idx]["queen_prob"] if top_idx is not None else 0.0
+
+        # Class promotion rules:
+        #  - The single highest-scoring crop above QUEEN_PROB_THRESHOLD -> "queen"
+        #  - The next two crops above 0.5 -> stay "bee" but tagged as
+        #    queen_candidate with their probability (drawn as cyan dashed boxes)
+        promoted_queen_idx = top_idx if top_prob >= queen_clf.QUEEN_PROB_THRESHOLD else None
+        candidate_indices = [
+            i for i in ranked[:3]
+            if i != promoted_queen_idx
+            and probs[i]["queen_prob"] >= 0.50
+        ]
 
         new_detections = []
         others = [d for d in detections if d not in candidates]
         for i, d in enumerate(candidates):
             new_d = dict(d)
-            if i == best_idx and is_queen:
+            new_d["queen_prob"] = probs[i]["queen_prob"]
+            if i == promoted_queen_idx:
                 new_d["class"] = "queen"
-                new_d["queen_prob"] = best_prob
             else:
                 new_d["class"] = "bee"
-                new_d["queen_prob"] = probs[i]["queen_prob"]
+                if i in candidate_indices:
+                    new_d["queen_candidate"] = True
+                    new_d["queen_standout"] = probs[i]["queen_prob"]
             new_detections.append(new_d)
         new_detections.extend(others)
 
+        top_probs = [probs[i]["queen_prob"] for i in ranked[:3]]
         return new_detections, {
             "method": "classifier",
             "n_candidates": len(candidates),
-            "queen_prob": best_prob,
-            "queen_found": is_queen,
+            "queen_prob": top_prob,
+            "queen_found": promoted_queen_idx is not None,
+            "top_3_probs": top_probs,
             "raw_response": "",
         }
 

detector.py

@@ -294,21 +294,30 @@ def _draw_annotations(image: Image.Image, detections: list[dict]) -> Image.Image
             draw.rectangle([bx1, by1, bx2, by2], fill=color + (235,))
             draw.text((bx1 + 5, by1 + 1), label, fill=(20, 16, 8), font=font_queen)
 
-    # Best-effort queen candidate (geometric outlier). Drawn last so it sits
-    # on top, with a dashed cyan box + a question mark - it is a "confirm by
-    # eye" hint, deliberately NOT styled like the confident green queen box.
-    cand = next((d for d in detections if d.get("queen_candidate")), None)
-    if cand is not None:
+    # Queen candidates: every bee tagged by the cascade with
+    # queen_candidate=True gets a dashed cyan box and a probability
+    # label. Drawn last so they sit on top of the worker bee outlines.
+    font_cand = _font(13)
+    candidates = [d for d in detections if d.get("queen_candidate")]
+    # Sort by probability descending so the highest gets drawn last (on top)
+    candidates.sort(key=lambda d: d.get("queen_prob", 0))
+    for cand in candidates:
         cx1, cy1, cx2, cy2 = cand["bbox"]
-        _dashed_rectangle(draw, [cx1, cy1, cx2, cy2],
-                          _CANDIDATE_COLOR + (255,), width=3)
-        label = "LIKELY QUEEN?"
-        tw = draw.textlength(label, font=font_queen)
-        th = font_queen.size + 4
+        _dashed_rectangle(
+            draw, [cx1, cy1, cx2, cy2], _CANDIDATE_COLOR + (255,), width=3
+        )
+        prob = cand.get("queen_prob") or cand.get("queen_standout", 0)
+        label = f"queen? {int(prob * 100)}%"
+        tw = draw.textlength(label, font=font_cand)
+        th = font_cand.size + 3
         bx1, by1 = cx1, max(0, cy1 - th - 2)
-        draw.rectangle([bx1, by1, bx1 + tw + 10, by1 + th],
-                       fill=_CANDIDATE_COLOR + (235,))
-        draw.text((bx1 + 5, by1 + 1), label, fill=(8, 16, 20), font=font_queen)
+        draw.rectangle(
+            [bx1, by1, bx1 + tw + 10, by1 + th],
+            fill=_CANDIDATE_COLOR + (235,),
+        )
+        draw.text(
+            (bx1 + 5, by1 + 1), label, fill=(8, 16, 20), font=font_cand
+        )
 
     return out
 

scripts/push_classifier_to_hub.py

@@ -0,0 +1,132 @@
+"""Push the trained queen vs worker classifier to its own HF model repo."""
+
+import argparse
+import os
+from pathlib import Path
+
+from dotenv import load_dotenv
+from huggingface_hub import HfApi
+
+
+WEIGHTS = Path(__file__).parent.parent / "weights" / "queen_classifier.pt"
+
+README = """---
+license: apache-2.0
+library_name: timm
+tags:
+- bees
+- beekeeping
+- image-classification
+- efficientnet
+pipeline_tag: image-classification
+---
+
+# Apiarist Queen-vs-Worker Bee Classifier
+
+Binary image classifier (EfficientNet-B0, ~5M params) trained to
+distinguish queen bees from worker bees on cropped bee images.
+
+Built as part of [Apiarist](https://huggingface.co/spaces/build-small-hackathon/Apiarist),
+an offline AI hive inspector for backyard beekeepers, made for the
+[Build Small Hackathon](https://huggingface.co/build-small-hackathon).
+
+## Why a dedicated classifier?
+
+Multi-class YOLO detectors fight two problems at once (localize + classify)
+and queens lose because they're rare and visually subtle. A focused
+binary classifier on cropped bee images is the right architecture:
+small, fast, trained specifically for one decision.
+
+## Training
+
+- Backbone: `efficientnet_b0` (ImageNet pretrained)
+- Training data: bee crops extracted from labelled bounding boxes in two
+  Roboflow datasets (Matt Nudi honey bees + Hendricks Ricky bee-project)
+- 1,146 queen crops + 29,825 worker crops, balanced via weighted sampling
+- Heavy augmentation: rotations, flips, color jitter
+- 90/10 train/val split, weighted random sampling for class balance
+- AdamW + cosine schedule, mixed precision on a single T4 GPU
+- Trained on [Modal](https://modal.com)
+
+## Validation metrics
+
+- Accuracy: 0.997
+- Precision (queen): 0.991
+- Recall (queen): 0.934
+- **F1: 0.962**
+
+## Recommended use
+
+Pair with a bee detector (e.g. YOLOv8). Run the detector first, then
+classify each cropped bee through this model. Threshold queen
+probability at 0.85 for high-precision flagging.
+
+```python
+import torch, timm
+from torchvision import transforms
+
+ckpt = torch.load("queen_classifier.pt", map_location="cpu")
+model = timm.create_model(ckpt["arch"], pretrained=False, num_classes=2)
+model.load_state_dict(ckpt["state_dict"])
+model.eval()
+
+tf = transforms.Compose([
+    transforms.Resize((224, 224)),
+    transforms.ToTensor(),
+    transforms.Normalize([0.485,0.456,0.406], [0.229,0.224,0.225]),
+])
+
+with torch.no_grad():
+    probs = torch.softmax(model(tf(crop).unsqueeze(0)), dim=1)
+queen_idx = ckpt["class_to_idx"]["queen"]
+queen_prob = probs[0, queen_idx].item()
+```
+
+## Caveats
+
+The training distribution leans toward close-up macro photos of bees on
+honeycomb. Generalization to wide-angle inspection photos (with hands /
+background visible) is weaker, since YOLO's bee bounding boxes on those
+photos are often smaller and less precise than the training crops.
+
+## License
+
+Apache 2.0. Trained on data released under CC BY 4.0.
+"""
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--repo-id", required=True)
+    parser.add_argument("--private", action="store_true")
+    args = parser.parse_args()
+
+    load_dotenv()
+    token = os.environ.get("HF_TOKEN") or os.environ.get("HUGGING_FACE_HUB_TOKEN")
+    if not token:
+        raise SystemExit("Set HF_TOKEN in .env")
+    if not WEIGHTS.exists():
+        raise SystemExit(f"Weights not at {WEIGHTS}")
+
+    api = HfApi(token=token)
+    print(f"Creating repo {args.repo_id} ...")
+    api.create_repo(args.repo_id, repo_type="model", private=args.private,
+                    exist_ok=True)
+
+    api.upload_file(
+        path_or_fileobj=README.encode("utf-8"),
+        path_in_repo="README.md",
+        repo_id=args.repo_id, repo_type="model",
+        commit_message="Add model card",
+    )
+    api.upload_file(
+        path_or_fileobj=str(WEIGHTS),
+        path_in_repo="queen_classifier.pt",
+        repo_id=args.repo_id, repo_type="model",
+        commit_message="Upload EfficientNet-B0 queen classifier weights",
+    )
+    print(f"\n[OK] Model live at: https://huggingface.co/{args.repo_id}")
+
+
+if __name__ == "__main__":
+    main()