DEPLOY_GUIDE.md

Deploying Bio-Bite to a Hugging Face Space

1. Create the Space

1. Go to huggingface.co → profile picture → New Space
2. Space name: bio-bite (owner: benjac8)
3. License: MIT
4. SDK: Gradio
5. Hardware: ZeroGPU ⚠️ this is the important one — the free CPU tier is far too slow for a 3B model
6. Visibility: Public
7. Create

ZeroGPU is free but requires a verified email and an account older than 30 days, with a limit of 2 ZeroGPU Spaces per free account. If ZeroGPU isn't offered, see Troubleshooting below.

2. Upload the four files

Files tab → Add file → Upload files, then drag in all of these:

File	Size	Purpose
app.py	13 KB	The application
requirements.txt	<1 KB	Dependencies
README.md	3 KB	Space card (its YAML header configures the Space)
biobite_embeddings.parquet	22 MB	Precomputed embeddings (uploads via Git LFS automatically)
recovery_guidance.json	2 KB	The coded recovery science

Commit. The Space will start building — watch the Logs tab.

First build takes ~5–10 minutes (installing torch/transformers, then downloading the models on first run).

3. Optional: the live-data bonus

Settings → Variables and secrets → New secret

• Name: SPOONACULAR_API_KEY
• Value: your free key from spoonacular.com/food-api

The app then shows a real photo of the generated dish. Without the key it simply skips the image — nothing breaks.

4. Test it

Click a Quick Starter, then Generate My Bio-Bite. Expect ~15–25 seconds for the first response (model warm-up), faster afterwards.

Verify:

• 3 recipe cards appear with sensible macros
• The detected recovery state matches the description
• The generated recipe respects the constraint (e.g. no salmon when you said "no salmon")
• "Why this works" mentions relevant nutrients
• Tomorrow's plan has timed bullets
• Disclaimer is visible

5. Submit

Put both links on Moodle:

• Dataset: https://huggingface.co/datasets/benjac8/bio-bite-recovery-nutrition
• Space: https://huggingface.co/spaces/benjac8/bio-bite

---

Troubleshooting

Build fails on spaces import — that's normal locally; on a ZeroGPU Space the package is preinstalled. If you're on CPU hardware, the app falls back automatically (just slowly).

"GPU quota exceeded" — the free ZeroGPU allowance is ~5 minutes of GPU time per day (roughly 15–20 requests). Don't burn it on casual testing; save it for the demo. It resets daily.

Out of memory — reduce max_new_tokens in app.py (760 → 500), or switch GEN_MODEL to Qwen/Qwen2.5-1.5B-Instruct (note: it failed JSON validation in benchmarking, so quality will drop).

Model returns unexpected format — the app catches this and asks the user to press again. It's occasional and expected with sampling; pressing again resolves it.

Slow first request — the models download on first run (~6 GB). Subsequent requests are much faster. Warm the Space up a few minutes before presenting.

Demo-day checklist

• Open the Space ~10 minutes early and run one query to warm it up
• Have the dataset page open in a second tab
• Know your headline numbers: 10,000 rows · precision@3 = 0.806 · 3 embedding models compared · 3 generators benchmarked
• Be ready to explain: why the science is coded rather than generated, and why the 3B model was both faster and more reliable than the smaller ones