README.md

---
title: FitGenie CalorieCLIP
emoji: 🍎
colorFrom: green
colorTo: blue
sdk: docker
app_port: 8000
pinned: false
license: mit
short_description: Instant food calorie estimate API for FitGenie (~51 MAE)
---

# FitGenie CalorieCLIP

Free-to-host **instant calorie estimate** from food photos for the [FitGenie](https://github.com) nutrition app.

| | |
|---|---|
| **Model** | [jc-builds/CalorieCLIP](https://huggingface.co/jc-builds/CalorieCLIP) (CLIP ViT-B/32 + regression) |
| **Output** | Calories only (not protein/carbs/fat) |
| **Speed** | ~50–200 ms on CPU |
| **Cost** | **$0** on Hugging Face Spaces free tier |

---

## One-click deploy on Hugging Face (free)

### Step 1 — Create the Space

1. Go to **[huggingface.co/new-space](https://huggingface.co/new-space)**
2. Fill in:
   - **Owner:** your username
   - **Space name:** `fitgenie-calorie-clip` (or any name)
   - **License:** MIT
   - **SDK:** **Docker**
   - **Hardware:** **CPU basic** (free — 16 GB RAM)
3. Click **Create Space**

### Step 2 — Upload these files

Upload the contents of `fitgenie_calorie_clip/` to the Space repo:

```
app.py
model_core.py
gradio_app.py
Dockerfile
requirements.txt
README.md          ← this file (frontmatter configures the Space)
```

**Or** connect your GitHub repo and set the Space to sync from `fitgenie_calorie_clip/`.

### Step 3 — Wait for build

First build takes **5–15 minutes** (downloads CLIP + CalorieCLIP weights).

When status is **Running**, your API base URL is:

```
https://YOUR-USERNAME-fitgenie-calorie-clip.hf.space
```

### Step 4 — Test

```bash
curl https://YOUR-USERNAME-fitgenie-calorie-clip.hf.space/health
# → {"status":"ok","model":"CalorieCLIP"}

curl -X POST https://YOUR-USERNAME-fitgenie-calorie-clip.hf.space/predict \
  -H "Content-Type: application/json" \
  -d '{"image":"'$(base64 -i food.jpg | tr -d '\n')'"}'
# → {"calories":342}
```

### Step 5 — Wire to FitGenie backend

On **Render** → your `fitgenie-backend` service → **Environment**:

```bash
CALORIE_CLIP_URL=https://YOUR-USERNAME-fitgenie-calorie-clip.hf.space/predict
CALORIE_CLIP_API_KEY=choose-a-secret-string
FOOD_ANALYSIS_PROVIDER=gpt
OPENAI_API_KEY=sk-...
```

On the **HF Space** → **Settings** → **Variables**:

```bash
CALORIE_CLIP_API_KEY=same-secret-as-backend
```

Redeploy backend. Photo flow will show real kcal estimates instead of ~400 fallback.

### Step 6 — Keep Space awake (optional, free)

Free Spaces sleep after **48 hours** of no traffic.

1. Sign up at [uptimerobot.com](https://uptimerobot.com) (free)
2. Add monitor: URL `https://YOUR-SPACE.hf.space/health`, interval **30 min**

---

## Optional: Gradio demo Space (browser UI)

For a **visual demo** (no API), create a second Space:

| Setting | Value |
|---------|-------|
| SDK | **Gradio** |
| Hardware | CPU basic |
| App file | `gradio_app.py` |

Use this README frontmatter instead:

```yaml
---
title: FitGenie CalorieCLIP Demo
sdk: gradio
sdk_version: 4.44.1
app_file: gradio_app.py
hardware: cpu-basic
---
```

---

## API reference

| Endpoint | Method | Body | Response |
|----------|--------|------|----------|
| `/health` | GET | — | `{ "status": "ok", "model": "CalorieCLIP" }` |
| `/predict` | POST | `{ "image": "<base64>" }` | `{ "calories": 342 }` |

Optional header: `X-API-Key: your-secret` (when `CALORIE_CLIP_API_KEY` is set).

---

## Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| `CALORIE_CLIP_API_KEY` | (empty) | Require `X-API-Key` header |
| `CALORIE_CLIP_MODEL_REPO` | `jc-builds/CalorieCLIP` | HuggingFace weights repo |
| `MAX_IMAGE_BYTES` | `8388608` | Max upload size (8 MB) |

---

## Limits (free tier)

| Topic | Detail |
|-------|--------|
| Indian food | Weak — trained on US cafeteria + 2 Indian Food-101 classes |
| Macros | **Not supported** — use GPT-4o or `fitgenie_food_analysis` for P/C/F |
| Thali / multi-item | Poor — single calorie number for whole image |
| Sleep | After 48h idle — use UptimeRobot |

---

## Local dev

```bash
pip install -r requirements.txt
uvicorn app:app --reload --port 8000
# or visual demo:
python gradio_app.py
```

---

## License

MIT (service code) · CalorieCLIP model MIT · FitGenie integration