OPENAI_SETUP.md

# Quick Setup with OpenAI (Recommended)

Due to HuggingFace API migration issues, **we recommend using OpenAI for reliable production use**.

---

## ⚡ 5-Minute OpenAI Setup

### Step 1: Get OpenAI API Key (2 minutes)

1. Go to https://platform.openai.com/api-keys
2. Sign up or log in
3. Click "Create new secret key"
4. **Copy the key** (starts with `sk-`)
5. **Save it somewhere safe** (you won't see it again)

### Step 2: Add Credits (1 minute)

1. Go to https://platform.openai.com/account/billing
2. Click "Add payment method"
3. Add $5-10 to start (lasts for 200-1000 surveys)
4. Set up usage limits to control costs

### Step 3: Configure ConversAI (2 minutes)

**On HuggingFace Spaces:**
1. Go to your Space Settings
2. Click "Variables" or "Secrets"
3. Add these two variables:
   ```
   Name: LLM_PROVIDER
   Value: openai

   Name: OPENAI_API_KEY
   Value: sk-your-actual-key-here
   ```
4. Restart your Space

**Running Locally:**
```bash
export LLM_PROVIDER=openai
export OPENAI_API_KEY=sk-your-actual-key-here
python app.py
```

### Step 4: Test It! (30 seconds)

1. Open your ConversAI app
2. Look for green banner: "✅ Active LLM Provider: OPENAI"
3. Try generating a survey
4. Should work in ~5 seconds!

---

## 💰 Cost Breakdown

OpenAI is **very affordable** for survey work:

### Typical Costs with GPT-4o-mini (Recommended):

| Task | Approximate Cost |
|------|------------------|
| Generate 10-question survey | $0.01 - $0.02 |
| Translate to 5 languages | $0.03 - $0.05 |
| Analyze 50 responses | $0.05 - $0.10 |
| **Complete workflow** | **$0.09 - $0.17** |

### With $10 credit, you can:
- Generate ~500 surveys
- Translate ~200 surveys to 5 languages each
- Analyze ~100 datasets with 50 responses each
- Run ~60-100 complete workflows (generate + translate + analyze)

### Cost Control Tips:

1. **Use GPT-4o-mini** (default) - Much cheaper than GPT-4
   ```bash
   LLM_MODEL=gpt-4o-mini  # Already the default
   ```

2. **Set usage limits:**
   - Go to https://platform.openai.com/account/limits
   - Set monthly limit (e.g., $10/month)
   - Get email alerts at 50%, 75%, 90%

3. **Monitor usage:**
   - Check https://platform.openai.com/usage daily
   - Review costs per request
   - Adjust if needed

---

## 🎯 Why OpenAI Over HuggingFace?

| Feature | OpenAI | HuggingFace Free |
|---------|--------|------------------|
| **Speed** | 3-10 seconds | 30-120 seconds |
| **Reliability** | 99.9% uptime | Variable |
| **Quality** | Excellent | Good |
| **Rate Limits** | Generous | Restrictive |
| **API Issues** | Stable | Migrating |
| **Support** | Commercial | Community |
| **Cost** | ~$0.02/survey | Free |

**Bottom line:** For $10, you get 500+ surveys with:
- ⚡ 10x faster generation
- ✅ Reliable service
- ⭐ Better quality
- 🔒 Production-ready

---

## 🔄 Switching from HuggingFace

Already using HuggingFace? Here's how to switch:

### On HuggingFace Spaces:

1. **Add OpenAI credentials** (see Step 3 above)
2. **Restart Space**
3. **That's it!** No code changes needed

The app automatically detects OpenAI credentials and uses them.

### What happens to HuggingFace?

- HuggingFace still works as fallback
- OpenAI takes priority if both are configured
- You can remove HF token if you want

---

## 🧪 Test Your Setup

Run this to verify OpenAI is working:

```bash
python check_env.py
```

Should show:
```
✅ OPENAI_API_KEY     SET (sk-proj-...)
✅ LLM_PROVIDER       SET (openai)
```

And at the bottom:
```
✅ Will use: OpenAI (explicit)
```

Or test directly in the app - look for:
```
✅ Active LLM Provider: OPENAI | Model: gpt-4o-mini
```

---

## 🆘 Troubleshooting

### "Invalid API key"
- Check key starts with `sk-`
- Make sure you copied the full key
- Regenerate if needed: https://platform.openai.com/api-keys

### "Insufficient quota"
- Add credits: https://platform.openai.com/account/billing
- Minimum: $5 recommended

### "Rate limit exceeded"
- You're on free tier - upgrade to pay-as-you-go
- Or wait a few minutes

### Still using HuggingFace?
- Check LLM_PROVIDER is set to "openai"
- Check OPENAI_API_KEY is set correctly
- Run `python check_env.py`

---

## 💡 Pro Tips

### 1. Use Different Models for Different Tasks

```bash
# For survey generation (fast, cheap)
LLM_MODEL=gpt-4o-mini

# For complex analysis (better quality, more expensive)
LLM_MODEL=gpt-4o
```

### 2. Monitor Costs

Set up email alerts:
- 50% of limit: Review usage
- 75% of limit: Check if expected
- 90% of limit: Urgent review

### 3. Batch Operations

- Generate multiple survey versions at once
- Translate to all languages together
- More efficient than one at a time

### 4. Cache Results

- Save generated surveys
- Reuse translations when possible
- Don't regenerate unnecessarily

---

## 📊 Monthly Cost Estimates

Based on typical usage:

**Light Use (10 surveys/month):**
- Generate: 10 surveys × $0.02 = $0.20
- Translate: 5 translations × $0.04 = $0.20
- Analyze: 5 analyses × $0.08 = $0.40
- **Total: ~$1/month**

**Medium Use (50 surveys/month):**
- Generate: 50 × $0.02 = $1.00
- Translate: 25 × $0.04 = $1.00
- Analyze: 25 × $0.08 = $2.00
- **Total: ~$4/month**

**Heavy Use (200 surveys/month):**
- Generate: 200 × $0.02 = $4.00
- Translate: 100 × $0.04 = $4.00
- Analyze: 100 × $0.08 = $8.00
- **Total: ~$16/month**

**Enterprise (1000+ surveys/month):**
- Contact OpenAI for volume pricing
- Consider fine-tuned models
- Estimated: $50-100/month

---

## ✅ Recommendation

**For ConversAI production use:**

1. ✅ **Use OpenAI** (not HuggingFace)
2. ✅ **Start with GPT-4o-mini** (cheapest, fast)
3. ✅ **Add $10 credit** (lasts months for typical use)
4. ✅ **Set $10/month limit** (safety)
5. ✅ **Monitor usage weekly**

**Cost:** ~$1-5/month for typical use
**Benefit:** Reliable, fast, production-ready
**ROI:** Saves hours vs manual survey design

---

## 🚀 Ready to Start?

1. Get API key: https://platform.openai.com/api-keys
2. Add $5-10 credit
3. Configure ConversAI (see Step 3 above)
4. Start creating surveys!

**Questions?** See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) or [USER_GUIDE.md](USER_GUIDE.md)

---

**Updated:** November 2025
**Recommended for:** All production deployments
**Alternative:** Anthropic Claude (similar cost, great quality)