Spaces:
Sleeping
Sleeping
| title: Apiarist | |
| emoji: 馃悵 | |
| colorFrom: yellow | |
| colorTo: red | |
| sdk: gradio | |
| sdk_version: 6.16.0 | |
| python_version: '3.12' | |
| app_file: app.py | |
| pinned: true | |
| license: apache-2.0 | |
| short_description: Offline AI inspector for honeybee hive frames | |
| tags: | |
| - beekeeping | |
| - object-detection | |
| - vision-language-model | |
| - small-models | |
| - zerogpu | |
| - track:backyard | |
| - sponsor:modal | |
| - achievement:offgrid | |
| - achievement:welltuned | |
| - achievement:offbrand | |
| - achievement:sharing | |
| models: | |
| - Qwen/Qwen2.5-VL-3B-Instruct | |
| - maryammeda/apiarist-honey-bee-detector | |
| datasets: | |
| - maryammeda/apiarist-inaturalist-bees | |
| # Apiarist | |
| A fully-offline AI hive frame inspector for backyard beekeepers. Built | |
| in 10 days for the [Build Small Hackathon](https://huggingface.co/build-small-hackathon). | |
| ## Submission | |
| - **Track:** Backyard AI | |
| - **Demo video:** [Watch the demo](https://www.dropbox.com/scl/fi/k9143ji7ioxlu3vxk0e1f/Apiarist-Demo.mp4?rlkey=n6w49ud1trpkm9t20rhvp3nnd&dl=0) | |
| - **Social post:** [LinkedIn](https://www.linkedin.com/posts/maryammeda_i-almost-scrapped-the-queen-detection-part-ugcPost-7472279288315097088-H4E8/) | |
| - **Badges:** Off the Grid (no cloud APIs at inference) 路 Well-Tuned (two custom-trained models) 路 Off-Brand (custom Gradio theme) 路 Sharing is Caring (2 models + 1 dataset published to the Hub) | |
| ## What it does | |
| Point a phone at any honeycomb frame, get back: | |
| - 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: two tiny specialists + one small generalist | |
| | 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 | | |
| |---|---|---|---| | |
| | `train_yolo_on_modal.py` | Fine-tunes YOLOv8s on 3,308 labeled bee images (60 epochs) | 1x T4 | ~50 min | | |
| | `train_queen_classifier.py` | Trains EfficientNet-B0 queen-vs-worker on ~31k bee crops | 1x T4 | ~12 min | | |
| 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 | |
| ``` | |
| Every training run across the build was done on Modal, for a few dollars | |
| of the free hackathon credit. | |
| ## Stack | |
| - [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 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) | |
| ## 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 | |
| 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 | |
| Apache 2.0 | |
| <!-- cache-bust dc2bfb3 --> | |