chore: remove internal planning docs (drafts, scripts notes) from public repo

BLOG_POST.md

@@ -1,76 +0,0 @@
-# Building Apiarist: 10 days, 1 custom YOLO, and why small models win
-
-*Field notes from the Build Small Hackathon.*
-
----
-
-## The constraint that made this interesting
-
-The hackathon's only hard rule: **total parameters ≤ 32 billion**, and the whole thing must run on a laptop. No cloud APIs at runtime. Build something that solves a real problem for a real person, then prove a small model is genuinely the right tool for the job, not a cop-out for not having GPT-4o's API key.
-
-I built **Apiarist**: a fully-offline AI hive frame inspector for backyard beekeepers. You point a phone camera at any honeycomb frame and the app counts bees, flags the queen, spots varroa mites, and writes a narrative report you can actually log. No internet required.
-
-Live demo: [huggingface.co/spaces/build-small-hackathon/Apiarist](https://huggingface.co/spaces/build-small-hackathon/Apiarist)
-
-## Why beekeeping, why now
-
-Frank, a beekeeper a few streets over, keeps 14 hives. Every weekend he inspects each frame and writes notes by hand in a beat-up notebook. Last summer he lost four colonies because he didn't spot a queen failure in time.
-
-The problem is real but tiny: he's not going to upload private hive data to a cloud API, and his apiary has no signal anyway. He doesn't need a foundation model. He needs **a fast, focused tool that runs on his laptop in a field.**
-
-That's the entire pitch for small models, distilled.
-
-## Architecture: specialist + generalist
-
-Two models, two jobs:
-
-- **YOLOv8s, custom-trained** (22 MB, ~11M params): finds bees, drones, queens, and varroa mites with bounding boxes. Runs on CPU in ~200ms. This is the *specialist*.
-- **Qwen2.5-VL-3B-Instruct** (~6 GB, 3B params): takes the image + the YOLO detection counts and writes a narrative inspection report. Runs on a free ZeroGPU in ~5 seconds. This is the *generalist*.
-
-The trick: each model does what it's actually good at.
-
-Vision-language models are terrible at counting tiny things or picking subtle queens out of a sea of nearly-identical workers. Ask Qwen-3B "how many varroa mites?" and it will confidently hallucinate a number. Ask a specialist YOLO and you get a real count grounded in pixels.
-
-Inversely, YOLO can't write a useful report. "47 bees, 1 queen, 0 mites" is data, not language. Qwen takes those facts and produces "Healthy frame, queen present, brood pattern looks solid, no swarm prep visible."
-
-Together: structured + narrative. That's a real product.
-
-## Training a YOLO on Modal in one afternoon
-
-The first dataset I tried (Matt Nudi's 909-image honey-bee set) had only ~50 queen examples. Queen mAP came out at 0.37 with P=0.19, basically useless for queen detection.
-
-Pivoted to **hendricks_ricky/bee-project** on Roboflow Universe: 3,308 labeled images with 892 queens AND a Varroa class. Trained YOLOv8s for 60 epochs on a single Modal T4 in ~50 minutes for ~$0.40 of free hackathon credit.
-
-The Modal script is two functions. It pulls the dataset from Roboflow inside the container, trains, saves weights to a Modal Volume, and exits. No local GPU needed. No flaky Colab timeouts. Best money the credit program ever spent on me.
-
-## Off the Grid, intentionally
-
-For the demo Space to count for the "Off the Grid" badge, the live app can't call any cloud APIs at inference. So:
-
-- YOLO runs on the main HF Space container (CPU)
-- Qwen-3B runs via `@spaces.GPU` on ZeroGPU's free GPU pool
-- Both models live in the Space repo (YOLO weights via Git LFS, Qwen from HF Hub cache)
-- SQLite persists hive registry + inspection history
-- ReportLab generates weekly PDF reports
-
-The only network calls are *downloading* the models on first boot. After that, it's a closed loop.
-
-## What I'd do with more time
-
-- **More queen training data.** 892 examples is the most I could find, but the model still misses queens that aren't well-lit or facing the camera.
-- **A second specialist for swarm cells.** Right now those are detected by Qwen-3B's prose, which means false alarms.
-- **Voice notes**, with Whisper transcription. Beekeepers wear gloves, typing is bad UX in the field.
-- **Bee count trends over time** in the PDF report. Pretty graphs sell.
-
-## The thing I learned
-
-Specialist + generalist isn't just an architecture choice. It's a thesis: **you don't need a giant model if you know exactly what your tiny model needs to do.** A 11M-parameter YOLO trained on 3,000 images beats GPT-4o at counting bees because it was literally designed for that. The 3B VLM handles everything else.
-
-Small models win when you stop asking them to do everything.
-
----
-
-**Code:** [github / HF Space](https://huggingface.co/spaces/build-small-hackathon/Apiarist)
-**YOLO weights:** [huggingface.co/maryammeda/apiarist-honey-bee-detector](https://huggingface.co/maryammeda/apiarist-honey-bee-detector)
-**Built for:** [Build Small Hackathon](https://huggingface.co/build-small-hackathon)
-**Tools:** Hugging Face, Gradio, Modal, Roboflow, ultralytics, transformers

DEMO_VIDEO_SCRIPT.md

@@ -1,85 +0,0 @@
-# Apiarist, 60s Demo Video Script
-
-**Total runtime:** 60 seconds
-**Format:** Screen recording (your laptop) + voiceover. No face-on-camera needed.
-**Tool to record:** OBS (free) or Screen Recorder built into Windows (Win+G)
-**Mic:** Phone mic in a quiet room beats your laptop mic. Record separately, sync after.
-
----
-
-## Shot list (timecoded)
-
-### 0-5s, Hook
-**Visual:** Close-up still of a honeycomb frame from the dataset, full screen. Cut to a laptop sitting on a wooden surface (your desk works).
-**Voiceover:**
-> "Beekeepers inspect hives every weekend. Most still write notes in a beat-up notebook."
-
-### 5-15s, Problem
-**Visual:** Browser tab opening to Apiarist Space. Pause on the welcome screen.
-**Voiceover:**
-> "Last summer, Frank, a backyard beekeeper down the road, lost four colonies because he didn't spot queen failures in time. Apiarist is the assistant he should have had."
-
-### 15-30s, The App In Action (THE PROOF)
-**Visual:** Screen recording.
-1. Click **Inspect** tab
-2. Pick **"Hive #7"** from dropdown
-3. Upload a clean bee frame photo (use one with a visible queen, pre-test which ones the model nails)
-4. Click **Analyze Frame**
-5. ~5 seconds of "thinking", cut this short in edit if needed
-6. **Annotated frame appears** with bounding boxes
-7. **Pan over the result panel**, show queen badge (bright green), bee counts, brood pattern, notes
-
-**Voiceover (over the action):**
-> "Snap a photo of any comb frame. Apiarist runs a custom-trained YOLO detector to find queens, drones, workers, and varroa mites, then a 3-billion-parameter vision-language model writes a narrative report. All local. No cloud APIs. No subscription."
-
-### 30-42s, The Kill Shot (Compare tab)
-**Visual:** Switch to **Compare** tab. Upload same photo. Click "Run Comparison." Both sides analyze. Camera lingers on the side-by-side: clean structured output on the left (Apiarist), vague prose on the right (raw VLM).
-**Voiceover:**
-> "Compare a generic vision model on its own, it describes the photo, but can't count bees or pick out the queen. Apiarist's specialist YOLO + small VLM combo gives you something a beekeeper can actually log."
-
-### 42-52s, Workflow
-**Visual:**
-- Switch to **Hives** tab
-- Show the apiary table with multiple hives
-- Click into inspection history for one hive, show 4-5 past inspections
-- Click **"Generate PDF Report"**, show the downloaded PDF preview
-
-**Voiceover:**
-> "Every inspection auto-saves to that hive's log. Generate weekly PDF reports. Track which hives need attention. SQLite-backed, runs anywhere."
-
-### 52-60s, Close
-**Visual:** Apiarist logo full screen with text overlay:
-> Apiarist
-> Custom YOLOv8s + Qwen2.5-VL-3B
-> Fully offline. Built in 10 days.
-> huggingface.co/spaces/build-small-hackathon/Apiarist
-
-**Voiceover:**
-> "Apiarist. Small models, real work. Built for the Build Small Hackathon."
-
----
-
-## Recording checklist
-
-- [ ] Practice run the click-through 3 times before hitting record
-- [ ] Pre-load 3-4 bee photos in a folder, picked because the model handles them well
-- [ ] Pre-create at least 3 hives in the Hives tab with realistic names ("Hive #1, Northeast", "Hive #2, Apricot tree", "Hive #3, Backyard")
-- [ ] Log 4-5 inspections per hive before recording (so the history view has content)
-- [ ] Switch the Space to T4/ZeroGPU mode and prewarm by clicking Analyze once before recording (avoids 30s cold-start in the video)
-- [ ] Record voiceover separately on phone in a quiet room, read each section twice, pick best take
-- [ ] Edit in CapCut / Premiere / DaVinci Resolve (all free for this)
-- [ ] Add subtle background music (uncopyrighted, try YouTube Audio Library "instrumental folk")
-- [ ] Export as MP4 1920x1080 30fps, under 50MB
-
-## What NOT to do
-
-- Don't film your face. Wastes time, adds nothing.
-- Don't show real-time waiting. Cut directly from "click" to "result." Demo videos lie about latency, that's normal.
-- Don't show the Logs tab. Don't show errors. Don't show the Code editor. Stay in App view the entire time.
-- Don't read the script verbatim if it sounds robotic. Riff on it.
-
-## Where to upload
-
-- **Primary**: YouTube Unlisted, paste link in submission + LinkedIn post
-- **Backup**: Upload as `demo.mp4` in your HF Space (add it to repo via git LFS)
-- LinkedIn natively prefers uploaded video over external links, so upload **directly** to LinkedIn too

LINKEDIN_POST.md

@@ -1,61 +0,0 @@
-# LinkedIn submission post (June 15)
-
-Post this on submission day. Upload the demo video natively (LinkedIn throttles posts with external video links).
-
----
-
-I spent 10 days teaching a small AI to do something OpenAI's flagship can't: count bees on a honeycomb frame.
-
-For the Build Small Hackathon by Hugging Face × Gradio, I built **Apiarist**, a fully offline AI hive inspector for backyard beekeepers. Point a phone at any comb frame and it tells you:
-
- how many bees, drones, and queen candidates it sees
- where the queen is (with a green box around her)
- whether varroa mites are visible
- what the brood pattern looks like
- generates a weekly PDF inspection report
-
-Why small models? Because apiaries don't have signal. Hive-health data isn't for the cloud. And a custom YOLOv8s trained on 3,308 labeled bee images, paired with Qwen2.5-VL-3B running locally on ZeroGPU, beats GPT-4o at counting bees, because that's literally what it was designed for.
-
-Specialist (YOLO) finds and counts the things. Generalist (VLM) writes the narrative report. Together: structured + narrative inspection in 5 seconds, no internet required.
-
-Total params: ~3 billion. Total cost per inspection: zero.
-
- Demo video below
- Try it: huggingface.co/spaces/build-small-hackathon/Apiarist
- Field notes: [link to your blog post once published]
-
-Thanks to Hugging Face, Gradio, Modal, OpenAI, NVIDIA, Cohere, Black Forest Labs, and OpenBMB for the hackathon and the compute.
-
-#BuildSmall #SmallModels #Gradio #OpenSourceAI #HuggingFace #Beekeeping
-
----
-
-## Tagging instructions
-
-When you paste this into LinkedIn, type @ then the company name and pick the verified page (blue checkmark):
-- Hugging Face
-- Gradio
-- Modal
-- OpenAI
-- NVIDIA
-- Cohere
-- Black Forest Labs
-- OpenBMB
-
-The names turn **bold blue** when they're real tags.
-
-## Upload order
-
-1. Open new LinkedIn post
-2. **Upload demo video file directly** (not a YouTube link), LinkedIn favors native video
-3. Type the post text above (with tags applied)
-4. **Put the Space URL in the first comment**, not the post body, LinkedIn throttles posts with external links in the body
-5. Post
-
-## Backup channels
-
-If you don't get traction on LinkedIn, cross-post to:
-- Twitter / X (split into 3 tweets, hook + features + link)
-- Bluesky (same as Twitter)
-- Reddit r/beekeeping (separate post, lead with "I built an AI hive inspector, would love your feedback")
-- Reddit r/LocalLLaMA (lead with the tech story, specialist+generalist, 3B params, ZeroGPU)

data/SOURCES.md

@@ -1,73 +0,0 @@
-# Bee Dataset Sources
-
-The Apiarist model needs photos of **honeycomb frames** (the wooden rectangles
-bees build comb on), not just bees flying around. iNaturalist gives us a base
-of bee imagery but is light on hive-frame shots, we supplement from other
-sources below.
-
-## 1. iNaturalist (auto-scraped)
-
-Apis mellifera observations, CC-licensed.
-
-```powershell
-C:\Users\marya\Apiarist\.venv\Scripts\python.exe scripts\scrape_inaturalist.py --pages 10
-```
-
-Output: `data/raw/inaturalist/` + `metadata.jsonl`. Resumable.
-
-## 2. Roboflow Universe (hand-search, often pre-labeled)
-
-Search these queries, many datasets ship with YOLO labels already.
-
-- https://universe.roboflow.com/search?q=honeycomb
-- https://universe.roboflow.com/search?q=varroa+mite
-- https://universe.roboflow.com/search?q=queen+bee
-- https://universe.roboflow.com/search?q=beehive+frame
-
-Download as YOLOv8 format. Drop the zip into `data/raw/roboflow/<dataset-name>/`.
-
-## 3. Kaggle
-
-- https://www.kaggle.com/search?q=honeybee+dataset
-- https://www.kaggle.com/search?q=bee+image+classification
-
-Useful: "BeeImage Dataset" (5k+ bee close-ups labeled by species/health).
-
-## 4. Flickr (Creative Commons)
-
-Search queries that find frame shots:
-- `"honeycomb frame" beekeeping`
-- `"hive inspection"`
-- `"queen bee marked"`
-- `"varroa mite"`
-
-Filter to CC-BY / CC-BY-SA. Manual download.
-
-## 5. YouTube frame extraction
-
-Beekeeping channels regularly show frame inspections. Use `yt-dlp` + `ffmpeg`
-to pull frames at 1fps from videos.
-
-Suggested channels (manual licensing review required):
-- Jeff Horchoff Bees
-- Frederick Dunn
-- BoB the Bee Guy
-- The Beekeeper's Apprentice
-
-## Target counts for YOLO fine-tuning
-
-| Class | Target | Source priority |
-|---|---|---|
-| `queen` | 200+ | Flickr, YouTube, Roboflow |
-| `mite` | 100+ | Roboflow (best), Flickr macro |
-| `swarm_cell` | 50+ | Roboflow, YouTube |
-| `brood_pattern_normal` | 200+ (negatives) | All |
-
-## Labeling
-
-Use Roboflow's free tier (up to 1k images). Define 3 classes:
-- `queen`, bounding box around the queen
-- `mite`, small box per visible mite
-- `swarm_cell`, box around each peanut-shaped cell
-
-Export as YOLOv8 format → drop into `data/processed/yolo/`.