QUICK_START_HF_SPACES.md

Quick Start: Deploy to HuggingFace Spaces

⚡ Super Quick Start (5 Minutes)

1. Create Space

1. Go to https://huggingface.co/spaces
2. Click "Create new Space"
3. Name: conversai (or your choice)
4. SDK: Gradio
5. Visibility: PUBLIC ⚠️ (Required for auto HF_TOKEN)
6. Click "Create Space"

⚠️ IMPORTANT: The Space MUST be PUBLIC for HF_TOKEN to work automatically!

2. Upload Files

Upload these files to your Space (drag and drop or use Git):

Required:

• app.py
• llm_backend.py
• survey_generator.py
• survey_translator.py
• data_analyzer.py
• export_utils.py
• requirements.txt
• README.md

Optional (recommended):

• USAGE_GUIDE.md
• test_hf_backend.py

3. Wait for Build

• Space will auto-build (2-3 minutes)
• Watch the "Logs" tab for progress
• When you see "Running on local URL", it's ready!

4. Test It!

That's it! No configuration needed. The app automatically uses HuggingFace's free Inference Providers API (updated Nov 2025).

Try these:

1. Go to "Generate Survey" tab
2. Enter: "I want to understand customer satisfaction with our product"
3. Click "Generate Survey"
4. Wait ~30 seconds for the first generation

🎯 What Works Out of the Box

✅ Survey Generation - Create professional surveys from outlines ✅ Translation - Translate to 18+ languages ✅ Data Analysis - Analyze survey responses with AI ✅ Export - Download results as JSON

⚙️ Optional: Upgrade to Premium LLMs

For faster, better results, add environment variables in Space Settings:

OpenAI (Recommended)

LLM_PROVIDER=openai
OPENAI_API_KEY=sk-your-key-here

Anthropic Claude

LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=your-key-here

🐛 Troubleshooting

"LLM backend not configured"

Cause: Your Space can't access HF_TOKEN.

Solutions:

1. Make Space PUBLIC (easiest):

   • Go to Space Settings
   • Change visibility from Private → Public
   • Restart the Space

2. Add token manually (if Space must be private):

   • Go to https://huggingface.co/settings/tokens
   • Create/copy a token with "Read" permission
   • Go to Space Settings → Variables
   • Add: HUGGINGFACE_API_KEY = your token
   • Restart the Space

3. Use different provider:

   • Add OPENAI_API_KEY in Variables
   • Or add ANTHROPIC_API_KEY

"Generation takes too long"

Cause: Free HuggingFace Inference API can be slow during high usage.

Solutions:

1. Wait longer - First request can take 30-60 seconds
2. Try again - May hit a faster server
3. Upgrade to OpenAI - Much faster (costs ~$0.01 per survey)

"Model returned error"

Common causes:

• Rate limit hit (wait a few minutes)
• Model is loading (first request after idle)
• Input too long (reduce outline length)

Solutions:

• Wait 2-3 minutes and retry
• Use shorter, simpler outlines
• Upgrade to paid provider (OpenAI/Anthropic)

📊 Performance Comparison

Provider	Speed	Quality	Cost	Setup
HuggingFace (Free)	Slow	Good	Free	Auto
OpenAI	Fast	Excellent	~$0.01-0.05/survey	Need API key
Anthropic	Fast	Excellent	~$0.01-0.05/survey	Need API key

🔍 Testing Your Deployment

Run the test script:

1. Add test_hf_backend.py to your Space
2. Open the Space's terminal (if available) or check logs
3. Look for "✅ ALL TESTS PASSED!"

💡 Pro Tips

1. First Request is Slow - HuggingFace models "cold start". First request may take 60+ seconds.

2. Keep It Simple - For free tier, use:

   • Shorter outlines (2-3 sentences)
   • Fewer questions (5-10)
   • One language at a time

3. Monitor Usage - Check HuggingFace usage limits at https://huggingface.co/settings/billing

4. Upgrade When Ready - For production, switch to OpenAI:

   LLM_PROVIDER=openai
   OPENAI_API_KEY=sk-your-key
   

🎓 Next Steps

Once deployed:

1. ✅ Test all features - Generation, Translation, Analysis
2. ✅ Read USAGE_GUIDE.md - Learn best practices
3. ✅ Try examples - Use the built-in example data
4. ✅ Share your Space - Get feedback from users
5. ✅ Upgrade when ready - Add premium LLM for production

📚 Additional Resources

• Full Documentation: See USAGE_GUIDE.md
• Deployment Guide: See DEPLOYMENT.md
• HuggingFace Docs: https://huggingface.co/docs/hub/spaces
• Gradio Docs: https://gradio.app/docs

❓ FAQ

Q: Is it really free? A: Yes! HuggingFace provides free inference API access. Limits apply.

Q: Can I use my own model? A: Yes! Set LLM_MODEL=your/model-name environment variable.

Q: How do I upgrade to OpenAI? A: Add OPENAI_API_KEY in Space Settings, set LLM_PROVIDER=openai.

Q: Can I make it private? A: Yes, but you may need to configure HF_TOKEN manually.

Q: How much does OpenAI cost? A: Typically $0.01-0.05 per survey with GPT-4o-mini.

---

Happy researching! 🔬 Need help? Check USAGE_GUIDE.md or open an issue.