---
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 -->