DEPLOY.md

Deploying to Hugging Face Spaces — Step-by-step guide

What you need

• A free Hugging Face account → https://huggingface.co/join
• Git installed on your machine (or use the HF web UI)
• Optional: a free USDA API key → https://fdc.nal.usda.gov/api-key-signup.html

---

Option A — Upload via web UI (easiest, no git needed)

1. Create the Space

1. Go to https://huggingface.co/new-space
2. Fill in:
   • Space name: recipe-health-analyzer (or anything you like)
   • License: MIT
   • SDK: Gradio
   • SDK version: 4.15.0
   • Hardware: CPU basic (free)
3. Click Create Space

2. Upload files

1. In your new Space, click Files → Add file → Upload files
2. Upload every file from this zip, preserving the folder structure:

   app.py
   requirements.txt
   README.md
   utils/__init__.py
   utils/config.py
   utils/logger.py
   speech_module/__init__.py
   speech_module/transcriber.py
   recipe_nlp/__init__.py
   recipe_nlp/parser.py
   recipe_nlp/extractor.py
   nutrition_engine/__init__.py
   nutrition_engine/usda_client.py
   nutrition_engine/mapper.py
   health_classifier/__init__.py
   health_classifier/feature_engineering.py
   health_classifier/model.py
   health_classifier/explainer.py
   

3. Click Commit changes to main

HF will automatically detect app.py and start building.

3. Add your USDA API key (optional but recommended)

1. Go to Settings → Variables and secrets
2. Click New secret
3. Name: USDA_API_KEY Value: your key from fdc.nal.usda.gov
4. Click Save
5. The Space will restart and pick up the key automatically

---

Option B — Deploy via Git (recommended for ongoing development)

1. Create the Space (same as Option A step 1)

2. Clone the Space repo

git clone https://huggingface.co/spaces/YOUR_USERNAME/recipe-health-analyzer
cd recipe-health-analyzer

3. Copy all files into the repo

# From wherever you unzipped the deployment package:
cp -r /path/to/hf_space/* .

4. Push

git add .
git commit -m "Initial deployment"
git push

5. Add your USDA API key

Same as Option A step 3 — use the web UI under Settings → Secrets.

---

What happens on first startup

The Space build takes about 3–5 minutes the first time because:

1. pip installs all dependencies from requirements.txt
2. torch (CPU-only wheels) is ~800 MB — biggest download
3. openai-whisper downloads the tiny model (~75 MB) on first audio request

On subsequent cold starts (Space wakes from sleep):

• Dependencies are cached — startup is ~30 s
• The trained RandomForest classifier is saved to models/ and reloaded automatically
• The spaCy model is cached after first download

---

Hardware tier recommendation

Tier	RAM	Cost	Notes
CPU basic	2 GB	Free	Works for text input; audio transcription is slow (~20 s)
CPU upgrade	8 GB	$0.03/hr	Recommended — comfortable for both text and audio
T4 GPU	16 GB	$0.60/hr	Overkill for this app; no GPU-specific code used

The app is optimised for CPU — Whisper uses tiny model + fp16=False for CPU compatibility.

---

Troubleshooting

Space is stuck on "Building" → Check the build logs (Logs tab in the Space). Usually a missing file or bad import.

"No module named spacy" → Make sure spacy>=3.7.0 is in requirements.txt (it is — check the file uploaded correctly).

"Error loading en_core_web_sm" → The app auto-downloads it on startup via spacy.cli.download. Check Logs to confirm.

Audio transcription returns empty text → Whisper needs audio at 16 kHz mono. The app handles conversion via librosa automatically. If you get an error, confirm librosa and soundfile are in your requirements.txt.

USDA API returns 403 → Your USDA_API_KEY secret is not set or incorrect. The app will fall back to the built-in nutrition database automatically — functionality is not broken.

Space sleeps after 48 hours (free tier) → Free CPU Spaces sleep when inactive. First request after sleep takes ~30 s to wake up. This is normal HF free-tier behaviour.

---

Sharing your Space

Once deployed, your Space URL is:

https://huggingface.co/spaces/YOUR_USERNAME/recipe-health-analyzer

You can embed it in any webpage with:

<iframe
  src="https://YOUR_USERNAME-recipe-health-analyzer.hf.space"
  width="100%" height="800"
  frameborder="0">
</iframe>

---

Updating after deployment

Edit files locally and push:

# Edit a file, then:
git add .
git commit -m "Update something"
git push

The Space rebuilds automatically on every push.