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:

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

   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:

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

# 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 or USER_GUIDE.md

---

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