HUGGINGFACE_DEPLOYMENT.md

🤗 Deploy to Hugging Face Spaces (FREE)

Complete step-by-step guide to deploy your Smart Escalation API to Hugging Face Spaces for FREE.

Why Hugging Face Spaces?

• ✅ FREE - No credit card required
• ✅ 2GB RAM - Enough for ML models (vs Render's 512MB free tier)
• ✅ Optimized for ML - Built for apps like yours
• ✅ Easy deployment - Push code via Git
• ✅ Automatic HTTPS - Secure by default

---

Step 1: Create Hugging Face Account (2 minutes)

1. Go to Hugging Face

   • Visit: https://huggingface.co/join

2. Sign Up

   • Enter your email
   • Choose a username (e.g., yourname)
   • Create password
   • Verify email

3. Get Access Token

   • Go to: https://huggingface.co/settings/tokens
   • Click "New token"
   • Name: escalation-api-deploy
   • Role: Write
   • Click "Generate a token"
   • Copy the token - you'll need it soon!

---

Step 2: Create a New Space (3 minutes)

1. Create Space

   • Go to: https://huggingface.co/new-space
   • Or click your profile → "New Space"

2. Configure Space

   • Owner: Your username
   • Space name: escalation-api (or any name you like)
   • License: MIT
   • Select the Space SDK: Choose "Docker" (important!)
   • Space hardware: CPU basic (free)
   • Visibility: Public
   • Click "Create Space"

3. Wait for Space Creation

   • You'll see a page with instructions
   • Keep this page open

---

Step 3: Add Required Files (5 minutes)

We need to add a few files for Hugging Face Spaces:

3.1: Create Dockerfile

I'll create a Dockerfile for you:

# This will be created automatically in the next step

3.2: Create .env.example for Spaces

# This will be created automatically in the next step

Let me create these files now:

---

Step 4: Push Code to Hugging Face (5 minutes)

4.1: Add Hugging Face Remote

Open your terminal and run:

# Add Hugging Face as a git remote
# Replace YOUR_USERNAME with your actual Hugging Face username
git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/escalation-api

Example:

git remote add hf https://huggingface.co/spaces/john/escalation-api

4.2: Commit New Files

# Add the new Hugging Face files
git add Dockerfile README_SPACES.md app.py

# Commit
git commit -m "Add Hugging Face Spaces deployment files"

4.3: Push to Hugging Face

# Push to Hugging Face Spaces
git push hf main

You'll be prompted for credentials:

• Username: Your Hugging Face username
• Password: Use the access token you created in Step 1 (NOT your password!)

---

Step 5: Configure Environment Variables (3 minutes)

1. Go to Your Space

   • Visit: https://huggingface.co/spaces/YOUR_USERNAME/escalation-api

2. Open Settings

   • Click the "Settings" tab at the top

3. Add Secrets (Environment Variables)

   • Scroll down to "Repository secrets"
   • Click "New secret" for each variable:

   Name	Value
   GOOGLE_API_KEY	Your Gemini API key from https://makersuite.google.com/app/apikey
   ARTICLES_DIR	data/articles
   EMBEDDING_MODEL	all-MiniLM-L6-v2
   RELEVANCE_THRESHOLD	0.5
   TOP_K_CHUNKS	3
   CHUNK_SIZE	500
   CHUNK_OVERLAP	50
   LLM_MODEL	gemini-1.5-flash
   LLM_TEMPERATURE	0.3
   CORS_ORIGINS	https://escalation-api-frontend.vercel.app,http://localhost:5173

4. Save Each Secret

   • Click "Add secret" after entering each one

---

Step 6: Wait for Build (10-15 minutes)

1. Go to "App" Tab

   • Click the "App" tab at the top

2. Watch Build Logs

   • You'll see the Docker build progress
   • It will download ML models (~2GB)
   • This takes 10-15 minutes on first build

3. Build Complete

   • When done, you'll see: "Running" status
   • Your API is now live! 🎉

---

Step 7: Test Your API (2 minutes)

7.1: Get Your API URL

Your API is available at:

https://YOUR_USERNAME-escalation-api.hf.space

Example:

https://john-escalation-api.hf.space

7.2: Test with curl

curl -X POST https://YOUR_USERNAME-escalation-api.hf.space/ask \
  -H "Content-Type: application/json" \
  -d '{"question": "How do I reset my password?"}'

7.3: Test in Browser

Visit:

https://YOUR_USERNAME-escalation-api.hf.space/docs

You'll see interactive API documentation where you can test the /ask endpoint.

---

Step 8: Connect Frontend to Backend (5 minutes)

Now connect your Vercel frontend to the Hugging Face backend:

8.1: Copy Your Backend URL

https://YOUR_USERNAME-escalation-api.hf.space

8.2: Add to Vercel

1. Go to https://vercel.com/dashboard
2. Open your project: escalation-api-frontend
3. Go to Settings → Environment Variables
4. Click "Add New"
   • Key: VITE_API_URL
   • Value: https://YOUR_USERNAME-escalation-api.hf.space
   • Environments: Check all (Production, Preview, Development)
5. Click "Save"

8.3: Redeploy Frontend

1. Go to Deployments tab
2. Find the latest deployment
3. Click "⋯" (three dots) → "Redeploy"
4. Click "Redeploy" to confirm
5. Wait 1-2 minutes

---

Step 9: Test End-to-End (1 minute)

1. Visit Your Frontend

   • Go to: https://escalation-api-frontend.vercel.app/

2. Ask a Question

   • Type: "How do I reset my password?"
   • Click "Send"

3. Success! 🎉

   • You should get an answer from your Hugging Face backend
   • Your full-stack ML app is now live!

---

🎉 Deployment Complete!

Your app is now fully deployed:

• Frontend: https://escalation-api-frontend.vercel.app/ (Vercel - FREE)
• Backend: https://YOUR_USERNAME-escalation-api.hf.space (Hugging Face - FREE)
• Total Cost: $0/month 🎊

---

Troubleshooting

Build fails with "Out of memory"

Solution: Upgrade to Hugging Face Pro ($9/month) for more resources, or:

• Use a smaller embedding model: all-MiniLM-L6-v2 → paraphrase-MiniLM-L3-v2
• Reduce dependencies in requirements.txt

"Application startup failed"

Solution: Check the logs in the "App" tab:

• Verify GOOGLE_API_KEY is set correctly
• Check that all environment variables are set
• Look for Python errors in the logs

API returns 404

Solution:

• Make sure the Space is "Running" (not "Building" or "Sleeping")
• Check the URL is correct: https://YOUR_USERNAME-escalation-api.hf.space
• Visit /docs to see available endpoints

Frontend shows "Failed to fetch"

Solution:

• Verify VITE_API_URL is set in Vercel
• Check backend URL is correct (no trailing slash)
• Make sure Hugging Face Space is running
• Check CORS_ORIGINS includes your Vercel frontend URL

Space goes to sleep

Solution: Hugging Face Spaces on free tier sleep after inactivity:

• First request after sleep takes 30-60 seconds (cold start)
• Subsequent requests are fast
• Upgrade to Pro ($9/month) for always-on instances

---

Updating Your App

To update your code:

# Make changes to your code
git add .
git commit -m "Update feature"

# Push to GitHub (for version control)
git push origin main

# Push to Hugging Face (to deploy)
git push hf main

Hugging Face will automatically rebuild and redeploy.

---

Cost Comparison

Platform	Free Tier	Paid Tier	RAM	Notes
Hugging Face	FREE	$9/month	2GB	Best for ML apps
Render	512MB (too small)	$7/month	512MB+	Good for web apps
Railway	$5 credit	$5-20/month	512MB+	Pay as you go
Vercel	❌ Can't deploy ML	❌ Can't deploy ML	500MB limit	Frontend only

---

Next Steps

• ✅ Your app is live and working!
• 📊 Monitor usage in Hugging Face dashboard
• 🔧 Add more help articles in data/articles/
• 🎨 Customize the frontend
• 📈 Track API usage and performance

---

Need Help?

• Hugging Face Docs: https://huggingface.co/docs/hub/spaces
• Hugging Face Discord: https://discord.gg/hugging-face
• Your Space Settings: https://huggingface.co/spaces/YOUR_USERNAME/escalation-api/settings

Enjoy your FREE ML-powered API! 🚀