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.