# Deploying Bio-Bite to a Hugging Face Space

## 1. Create the Space

1. Go to [huggingface.co](https://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](https://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*