README.md

---
title: Bio-Bite Recovery Nutrition Engine
emoji: 🥗
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: 5.9.1
app_file: app.py
pinned: false
license: mit
short_description: Turn wearable recovery data into a meal and a next-day plan
---

# 🥗 Bio-Bite — Recovery Nutrition Engine

Your smartwatch tells you that you slept 5 hours and hit a strain of 18/21. **So what should you eat?**

Bio-Bite closes the gap between *seeing* your recovery numbers and *knowing what to do with them*. Upload a WHOOP/watch screenshot or explicitly choose the metrics you have, select how you feel, then choose meal preferences. It returns three matched recovery meals, one brand-new recipe that is guaranteed to contain the selected ingredients, the science behind it, and a plan for tomorrow.

## How it works

```
USER INPUT (reviewed screenshot values or manual metrics + feeling + food choices)
        ↓
  hybrid route to 1 of 6 recovery states
  (65% semantic retrieval + 35% wearable-range fit)
        ↓
  embed query → FAISS search over 10,000 recipes
        ↓
  ingredient-aware 3 recommendations  +  RAG generation
        ↓
AI OUTPUT: new recipe · why it works · tomorrow's plan
```

| Component | Choice | Why |
|---|---|---|
| **Dataset** | [`benjac8/bio-bite-recovery-nutrition`](https://huggingface.co/datasets/benjac8/bio-bite-recovery-nutrition) — 10,000 rows | Read live from the Hub |
| **Embeddings** | [`benjac8/biobite-retriever`](https://huggingface.co/benjac8/biobite-retriever) (`e5-small-v2` snapshot) | Best neural retriever in the leakage-free 72-query v2 benchmark: **precision@3 = 0.551**, MRR = 0.677, nDCG@10 = 0.538 |
| **Search** | FAISS `IndexFlatIP` on normalised vectors | Cosine similarity, fast enough for live use |
| **Generation** | `Qwen/Qwen2.5-3B-Instruct` | Won the 18-case deterministic v2 benchmark: **66.7% overall pass**, 77.8% valid JSON, 100% science-claim pass |

The completed v2 benchmark remains the model-selection evidence. Production v3
uses a shorter four-field recipe-only JSON contract; its full three-model rerun
is provided as `evaluation/generator_benchmark_v3.py` and must be completed on a
GPU before any new benchmark score is claimed.

### Grounded and validated

The recovery guidance is **encoded in code**, not invented by the model. Each of
the six recovery states maps to cautious guidance. The language model creates the
new recipe, but every result must pass structure, required-ingredient,
excluded-ingredient, diet and preparation-time checks before it is shown.
Impossible choices such as `vegan + steak` or requiring and excluding eggs at the
same time are blocked before generation. Scientific wording and the next-day plan
are supplied deterministically from code.

Screenshot OCR is conservative: it accepts only labelled Sleep, Strain and HRV
values inside valid ranges, asks the user to review them, and does not add the
image to the dataset or application logs. WHOOP percentage scores stay separate:
Sleep Performance is not converted to sleep duration, Recovery is not treated as
HRV, and a relative HRV percentage is never inserted as absolute HRV in
milliseconds. Visible manual defaults are ignored unless their metric is
explicitly enabled. Direct WHOOP OAuth is intentionally not presented as active until real
API credentials and a tested callback are configured.

The dataset revision and embedding row order are pinned. Stable content IDs and
a sequence hash are checked at startup, preventing a silently updated dataset
from being paired with vectors from a different row order.

If the free ZeroGPU generator is unavailable, the deterministic fallback still
honours selected ingredients, exclusions, diet and maximum preparation time. This
keeps the app usable without silently ignoring the user's request.

The 4 Aug 2026 live acceptance run passed all 8/8 functional scenarios. The
model produced 1/8 recipes before the free daily quota expired; the validated
fallback served 7/8. Screenshot OCR was verified separately with exact Sleep
5.5 h, Strain 18.2 and HRV 32 extraction from a synthetic WHOOP image.

The app deliberately uses cautious language for uncertain relationships. For
example, magnesium-rich foods may support nutritional adequacy, but the app does
not claim that magnesium treats insomnia, anxiety, stress, or cortisol levels.

### Evaluation v2

The project package includes two reproducible benchmarks:

- **Retrieval:** 72 balanced external queries, with label leakage removed from
  the embedded corpus text; precision@3 with a bootstrap 95% confidence interval,
  MRR, nDCG@10, per-category scores, latency, and a TF-IDF baseline.
- **Generation:** 18 deterministic cases covering all six recovery categories,
  diets, exclusions and time limits; JSON validity, constraint pass rate,
  scientific-claim checks, median latency and p95 latency.

The lexical TF-IDF baseline scored precision@3 = 0.634, above all three neural
retrievers on this synthetic, vocabulary-regular corpus. E5 is therefore
described precisely as the best embedding model, not as the overall benchmark
winner.

## Files

- `app.py` — the Gradio application (retrieval + generation)
- `biobite_logic.py` — hybrid routing, JSON parsing and deterministic guardrails
- `biobite_embeddings.parquet` — 10,000 × 384 precomputed embeddings
- `recovery_guidance.json` — the coded recovery science

## Optional: live dish photos

Set a `SPOONACULAR_API_KEY` secret in the Space settings to fetch a real photo of the generated dish. The app works fine without it.

---

⚠️ **Educational prototype — not medical, nutritional or training advice.** The dataset is synthetic (generated by a language model) and has not been reviewed by a registered dietitian. Consult a qualified professional for personal guidance.

*Built for the Intro to Data Science final project, Reichman University.*