Upload 8 files

CHANGELOG.md

@@ -0,0 +1,133 @@
+# Changelog
+
+All notable changes to ConversAI will be documented in this file.
+
+## [1.1.0] - 2025-11-XX
+
+### Changed
+- **🔄 IMPORTANT**: Updated HuggingFace Inference API endpoint
+  - Migrated from deprecated `api-inference.huggingface.co` to new `router.huggingface.co/hf-inference/`
+  - This change is required as of November 2025 (old endpoint returns 404 errors)
+  - No user action required - update is automatic
+
+### Fixed
+- Fixed HuggingFace API 404 errors due to deprecated endpoint
+- Updated all documentation to reflect new API
+
+### Technical Details
+- Old endpoint: `https://api-inference.huggingface.co/models/{model}`
+- New endpoint: `https://router.huggingface.co/hf-inference/models/{model}`
+- Affects: `llm_backend.py` line 81
+
+---
+
+## [1.0.0] - 2025-10-25
+
+### Added
+- ✨ Initial release of ConversAI
+- 📝 Survey generation from outlines with AI
+- 🌍 Multi-language translation (18+ languages)
+- 📊 AI-assisted qualitative data analysis
+- 🔧 Support for multiple LLM providers (OpenAI, Anthropic, HuggingFace, LM Studio)
+- 📱 Gradio web interface
+- 📦 Export functionality (JSON, Markdown)
+- 🔒 Privacy-focused design (no permanent storage)
+- 📚 Comprehensive documentation suite
+- 🛠️ Diagnostic tools (check_env.py, test_hf_backend.py)
+
+### Documentation
+- USER_GUIDE.md - Complete user guide
+- QUICK_START_HF_SPACES.md - Fast deployment guide
+- TROUBLESHOOTING.md - Common issues and solutions
+- DEPLOYMENT.md - Detailed deployment instructions
+- USAGE_GUIDE.md - Technical usage guide
+- DOCUMENTATION_INDEX.md - Documentation navigation
+
+### Features
+
+**Survey Generation:**
+- Industry best practices automatically applied
+- Qualitative, quantitative, and mixed method support
+- Customizable question count and audience targeting
+- Professional introduction and closing messages
+
+**Translation:**
+- 18+ language support
+- Cultural adaptation, not just word-for-word translation
+- Batch translation capability
+- Back-translation support for validation
+
+**Data Analysis:**
+- Thematic analysis with theme extraction
+- Sentiment analysis and emotional insights
+- Executive summaries
+- Key insights and trends identification
+- Statistics and quality metrics
+
+**Technical:**
+- Modular architecture with clean code
+- Comprehensive error handling
+- Environment-based configuration
+- Production-ready deployment options
+- Zero-config HuggingFace Spaces support
+
+---
+
+## Migration Notes
+
+### From 1.0.0 to 1.1.0
+
+**HuggingFace Users:**
+- If you deployed before November 2025, update your `llm_backend.py` file
+- No configuration changes needed
+- API token usage remains the same
+
+**How to Update:**
+Replace line 80 in `llm_backend.py`:
+```python
+# Old (deprecated)
+return f"https://api-inference.huggingface.co/models/{self.model}"
+
+# New (required)
+return f"https://router.huggingface.co/hf-inference/models/{self.model}"
+```
+
+Or simply pull the latest version from the repository.
+
+---
+
+## Future Roadmap
+
+### Planned Features
+- API integration for programmatic access
+- Custom model fine-tuning support
+- Survey response collection module
+- Advanced analytics (cross-tab analysis, statistical tests)
+- Template library for common survey types
+- Collaboration features (team sharing, comments)
+- Integration with popular survey platforms
+- Mobile app for data collection
+
+### Potential Enhancements
+- Real-time response streaming
+- Batch processing for large datasets
+- Custom AI prompt templates
+- Survey versioning and A/B testing
+- Advanced visualization options
+- Export to more formats (PDF, PowerPoint)
+- Multi-user authentication
+- Admin dashboard
+
+---
+
+## Support
+
+For issues, questions, or feature requests:
+- Check TROUBLESHOOTING.md
+- Review DOCUMENTATION_INDEX.md
+- Run diagnostic tools (check_env.py)
+- Open an issue on GitHub
+
+---
+
+**ConversAI** - AI-Powered Qualitative Research Assistant

DOCUMENTATION_INDEX.md

@@ -0,0 +1,489 @@
+# ConversAI Documentation Index
+
+Complete guide to all available documentation for ConversAI.
+
+---
+
+## 📚 Documentation Overview
+
+ConversAI comes with comprehensive documentation covering everything from quick setup to advanced usage. Choose the document that best fits your needs.
+
+---
+
+## 🎯 Quick Navigation
+
+### 🔄 Important Update (Nov 2025)
+**[MIGRATION_NOTICE.md](MIGRATION_NOTICE.md)** - HuggingFace API update (if you see 404 errors)
+
+### New Users - Start Here!
+1. **[USER_GUIDE.md](USER_GUIDE.md)** ⭐ **START HERE** - Complete user guide
+2. **[QUICK_START_HF_SPACES.md](QUICK_START_HF_SPACES.md)** - 5-minute deployment guide
+3. **[README.md](README.md)** - Project overview and quick reference
+
+### Having Issues?
+4. **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** - Solutions to common problems
+5. **[MIGRATION_NOTICE.md](MIGRATION_NOTICE.md)** - Fix 404 errors (HuggingFace API update)
+6. **Run `python check_env.py`** - Diagnose configuration issues
+
+### Developers & Advanced Users
+6. **[DEPLOYMENT.md](DEPLOYMENT.md)** - Detailed deployment instructions
+7. **[USAGE_GUIDE.md](USAGE_GUIDE.md)** - Technical usage documentation
+
+---
+
+## 📖 Document Descriptions
+
+### MIGRATION_NOTICE.md - HuggingFace API Update
+**👤 Audience:** All HuggingFace users (CRITICAL if you see 404 errors)
+**📏 Length:** Quick reference (~1,500 words)
+**⏱️ Read Time:** 5 minutes
+
+**What's Inside:**
+- ✅ Explanation of HuggingFace API endpoint change
+- ✅ How to verify you're using the new endpoint
+- ✅ Update instructions if needed
+- ✅ Troubleshooting 404 errors
+- ✅ FAQ about the migration
+
+**Best For:**
+- Fixing 404 errors with HuggingFace
+- Understanding the API migration
+- Verifying your deployment is updated
+- Users who deployed before November 2025
+
+---
+
+### CHANGELOG.md - Version History
+**👤 Audience:** All users, especially those tracking changes
+**📏 Length:** Growing document
+**⏱️ Read Time:** 5 minutes
+
+**What's Inside:**
+- ✅ All version changes and updates
+- ✅ Migration notes between versions
+- ✅ Bug fixes and improvements
+- ✅ Future roadmap
+
+**Best For:**
+- Understanding what's changed
+- Migration between versions
+- Tracking new features
+- Planning upgrades
+
+---
+
+### USER_GUIDE.md - Complete User Guide
+**👤 Audience:** All users (non-technical friendly)
+**📏 Length:** Comprehensive (~8,000 words)
+**⏱️ Read Time:** 30-40 minutes (or use as reference)
+
+**What's Inside:**
+- ✅ What ConversAI does and why it's production-grade
+- ✅ Step-by-step guides for all three features
+- ✅ Complete workflow examples
+- ✅ Best practices and tips
+- ✅ Use case library with real scenarios
+- ✅ Privacy and security information
+- ✅ Success stories and metrics
+- ✅ Quality checklists
+- ✅ When to use vs. traditional methods
+
+**Best For:**
+- First-time users learning the platform
+- Understanding production-grade features
+- Learning best practices
+- Seeing real-world examples
+- Understanding capabilities and limitations
+
+---
+
+### QUICK_START_HF_SPACES.md - Fast Deployment
+**👤 Audience:** Anyone deploying to HuggingFace Spaces
+**📏 Length:** Quick reference (~2,000 words)
+**⏱️ Read Time:** 5-10 minutes
+
+**What's Inside:**
+- ✅ 5-minute deployment steps
+- ✅ Zero-configuration setup
+- ✅ Troubleshooting common issues
+- ✅ Performance tips
+- ✅ Testing instructions
+
+**Best For:**
+- Getting started quickly
+- Deploying to HuggingFace Spaces
+- Zero-config setup
+- Quick reference during deployment
+
+---
+
+### TROUBLESHOOTING.md - Problem Solving
+**👤 Audience:** Users experiencing issues
+**📏 Length:** Comprehensive reference (~3,000 words)
+**⏱️ Read Time:** 10-15 minutes (or search for your issue)
+
+**What's Inside:**
+- ✅ Common errors and solutions
+- ✅ Configuration problems
+- ✅ Performance issues
+- ✅ Debugging steps
+- ✅ Emergency fixes
+- ✅ Environment diagnostics
+
+**Best For:**
+- Fixing "LLM backend not configured" errors
+- Solving slow performance
+- Debugging startup issues
+- Understanding error messages
+- Getting unstuck quickly
+
+---
+
+### README.md - Project Overview
+**👤 Audience:** All users, especially new visitors
+**📏 Length:** Quick overview (~1,500 words)
+**⏱️ Read Time:** 5 minutes
+
+**What's Inside:**
+- ✅ Project description
+- ✅ Key features overview
+- ✅ Quick start instructions
+- ✅ Configuration basics
+- ✅ Architecture overview
+- ✅ Installation steps
+
+**Best For:**
+- First impression of the project
+- Understanding what ConversAI does
+- Quick setup reference
+- GitHub/HuggingFace Space homepage
+
+---
+
+### DEPLOYMENT.md - Detailed Deployment
+**👤 Audience:** Developers, DevOps, advanced users
+**📏 Length:** Comprehensive (~3,500 words)
+**⏱️ Read Time:** 15-20 minutes
+
+**What's Inside:**
+- ✅ HuggingFace Spaces deployment
+- ✅ Local development setup
+- ✅ Docker deployment
+- ✅ Provider configuration details
+- ✅ Monitoring and maintenance
+- ✅ Scaling considerations
+- ✅ Security best practices
+
+**Best For:**
+- Production deployments
+- Self-hosting
+- Docker containerization
+- Scaling for heavy usage
+- Enterprise deployments
+
+---
+
+### USAGE_GUIDE.md - Technical Usage
+**👤 Audience:** Technical users, researchers
+**📏 Length:** Detailed reference (~4,000 words)
+**⏱️ Read Time:** 20 minutes
+
+**What's Inside:**
+- ✅ Detailed feature workflows
+- ✅ File format specifications
+- ✅ JSON examples
+- ✅ API usage patterns
+- ✅ Command-line tips
+- ✅ Advanced configurations
+
+**Best For:**
+- Technical implementation details
+- Understanding file formats
+- Programmatic usage
+- Advanced configurations
+- Integration with other tools
+
+---
+
+### check_env.py - Environment Checker
+**👤 Audience:** All users (diagnostic tool)
+**📏 Type:** Executable Python script
+**⏱️ Run Time:** 5 seconds
+
+**What It Does:**
+- ✅ Checks for API keys and tokens
+- ✅ Validates Python dependencies
+- ✅ Shows which LLM provider will be used
+- ✅ Diagnoses configuration issues
+- ✅ Provides fix suggestions
+
+**How to Use:**
+```bash
+python check_env.py
+```
+
+**Best For:**
+- Diagnosing "backend not configured" errors
+- Verifying setup before deployment
+- Troubleshooting credential issues
+- Understanding environment state
+
+---
+
+### test_hf_backend.py - Connection Tester
+**👤 Audience:** Developers, troubleshooters
+**📏 Type:** Executable Python script
+**⏱️ Run Time:** 30-60 seconds
+
+**What It Does:**
+- ✅ Tests HuggingFace Inference API connection
+- ✅ Validates token functionality
+- ✅ Tests survey generation
+- ✅ Shows detailed error messages
+
+**How to Use:**
+```bash
+python test_hf_backend.py
+```
+
+**Best For:**
+- Testing HuggingFace connectivity
+- Validating API tokens
+- Debugging generation issues
+- Verifying setup works end-to-end
+
+---
+
+## 🗺️ Documentation Roadmap by User Journey
+
+### Journey 1: First-Time User on HuggingFace Spaces
+
+```
+1. README.md (2 min)
+   ↓ "What is this?"
+
+2. QUICK_START_HF_SPACES.md (5 min)
+   ↓ "How do I deploy?"
+
+3. USER_GUIDE.md - "How to Use" section (10 min)
+   ↓ "How do I use it?"
+
+4. Try the app!
+   ↓ If issues arise...
+
+5. TROUBLESHOOTING.md (as needed)
+```
+
+**Total Time to Success:** 20-30 minutes
+
+---
+
+### Journey 2: Self-Hosting Developer
+
+```
+1. README.md (5 min)
+   ↓ "What is this?"
+
+2. DEPLOYMENT.md - Local Setup (10 min)
+   ↓ "How do I install?"
+
+3. Run: python check_env.py (1 min)
+   ↓ "Is it configured?"
+
+4. USAGE_GUIDE.md (15 min)
+   ↓ "How do I use it?"
+
+5. USER_GUIDE.md - Best Practices (skim)
+   ↓ If issues arise...
+
+6. TROUBLESHOOTING.md (as needed)
+```
+
+**Total Time to Success:** 30-45 minutes
+
+---
+
+### Journey 3: Researcher/End User
+
+```
+1. USER_GUIDE.md - "What ConversAI Does" (5 min)
+   ↓ "Can this help my research?"
+
+2. USER_GUIDE.md - "How to Use" for your feature (10 min)
+   ↓ "How do I do X?"
+
+3. USER_GUIDE.md - Workflow Examples (10 min)
+   ↓ "Show me a real example"
+
+4. Try the app with examples
+   ↓ Regular usage...
+
+5. USER_GUIDE.md - Tips for Power Users (reference)
+```
+
+**Total Time to Productivity:** 30 minutes
+
+---
+
+### Journey 4: Enterprise Deployment
+
+```
+1. README.md (5 min)
+   ↓ "Is this production-ready?"
+
+2. USER_GUIDE.md - Production-Grade section (10 min)
+   ↓ "What makes it production-grade?"
+
+3. DEPLOYMENT.md - Complete guide (30 min)
+   ↓ "How do we deploy?"
+
+4. USER_GUIDE.md - Privacy & Security (5 min)
+   ↓ "Is it secure for our data?"
+
+5. DEPLOYMENT.md - Scaling & Monitoring (10 min)
+   ↓ "How do we operate it?"
+
+6. Set up with enterprise LLM provider
+```
+
+**Total Time to Production:** 1-2 hours of reading, plus setup time
+
+---
+
+## 📊 Documentation by Topic
+
+### Setup & Installation
+- **Quick Setup:** QUICK_START_HF_SPACES.md
+- **Detailed Setup:** DEPLOYMENT.md
+- **Troubleshooting:** TROUBLESHOOTING.md
+- **Environment Check:** check_env.py
+
+### Using ConversAI
+- **Complete Guide:** USER_GUIDE.md
+- **Technical Details:** USAGE_GUIDE.md
+- **Quick Reference:** README.md
+
+### Problem Solving
+- **Common Issues:** TROUBLESHOOTING.md
+- **Environment Issues:** check_env.py
+- **Connection Issues:** test_hf_backend.py
+
+### Advanced Topics
+- **Production Deployment:** DEPLOYMENT.md
+- **Scaling:** DEPLOYMENT.md - Scaling section
+- **Security:** USER_GUIDE.md - Privacy section
+- **API Integration:** USAGE_GUIDE.md
+
+---
+
+## 🔍 Finding What You Need
+
+### By Question
+
+**"How do I deploy this?"**
+→ QUICK_START_HF_SPACES.md or DEPLOYMENT.md
+
+**"What can this do?"**
+→ README.md or USER_GUIDE.md - What ConversAI Does
+
+**"How do I use feature X?"**
+→ USER_GUIDE.md - Feature Guide: [Feature Name]
+
+**"Why isn't it working?"**
+→ TROUBLESHOOTING.md or run check_env.py
+
+**"Is this production-ready?"**
+→ USER_GUIDE.md - Production-Grade section
+
+**"How do I translate surveys?"**
+→ USER_GUIDE.md - Feature Guide: Survey Translation
+
+**"What are best practices?"**
+→ USER_GUIDE.md - Tips sections
+
+**"How much does it cost?"**
+→ USER_GUIDE.md - Optimizing for Cost
+
+**"Is my data safe?"**
+→ USER_GUIDE.md - Privacy & Data Security
+
+**"Can I use this for [use case]?"**
+→ USER_GUIDE.md - Use Case Library
+
+---
+
+## 💡 Documentation Tips
+
+### For Readers
+
+1. **Don't read everything** - Use the index to find what you need
+2. **Start with USER_GUIDE.md** if unsure where to begin
+3. **Use search** (Ctrl+F) within documents
+4. **Check examples** - Most docs include real examples
+5. **Run diagnostics first** - check_env.py saves time
+
+### For Contributors
+
+1. **Keep docs in sync** - Update all relevant docs when making changes
+2. **Include examples** - Show, don't just tell
+3. **Link between docs** - Help readers navigate
+4. **Test instructions** - Verify steps actually work
+5. **Update this index** - When adding new documentation
+
+---
+
+## 📋 Documentation Checklist
+
+When starting with ConversAI, ensure you've read:
+
+**Minimum (Quick Start):**
+- [ ] README.md - Know what it does
+- [ ] QUICK_START_HF_SPACES.md - Deploy it
+- [ ] USER_GUIDE.md - "How to Use" sections for features you need
+
+**Recommended (Full Setup):**
+- [ ] USER_GUIDE.md - Complete guide
+- [ ] TROUBLESHOOTING.md - Skim common issues
+- [ ] Run check_env.py - Verify setup
+
+**Advanced (Production):**
+- [ ] DEPLOYMENT.md - Full deployment guide
+- [ ] USER_GUIDE.md - Privacy & Production sections
+- [ ] USAGE_GUIDE.md - Technical details
+
+---
+
+## 🔄 Documentation Updates
+
+**Last Updated:** 2025
+**Version:** 1.0
+
+**Recent Changes:**
+- Added comprehensive USER_GUIDE.md
+- Created this documentation index
+- Enhanced troubleshooting guide
+- Added diagnostic scripts
+
+**Upcoming:**
+- Video tutorials
+- API documentation
+- Integration guides
+- Case study library
+
+---
+
+## 📞 Still Need Help?
+
+After reading the relevant documentation:
+
+1. **Check logs** - Look for error messages
+2. **Run diagnostics** - `python check_env.py`
+3. **Search docs** - Use Ctrl+F in documents
+4. **Check issues** - GitHub issues for similar problems
+5. **Ask for help** - Provide diagnostic output and what you tried
+
+---
+
+**Happy researching!** 🔬
+
+*Choose your documentation path above and get started with ConversAI.*

MIGRATION_NOTICE.md

@@ -0,0 +1,199 @@
+# 🔄 IMPORTANT: HuggingFace API Migration Notice
+
+## Critical Update - November 2025
+
+HuggingFace has deprecated their old Inference API endpoint and migrated to a new Inference Providers API.
+
+---
+
+## ⚠️ What Changed
+
+**Old Endpoint (DEPRECATED - Returns 404):**
+```
+https://api-inference.huggingface.co/models/{model}
+```
+
+**New Endpoint (REQUIRED as of Nov 1, 2025):**
+```
+https://router.huggingface.co/hf-inference/models/{model}
+```
+
+---
+
+## ✅ This Version is Updated
+
+**Good news:** If you're using this version of ConversAI, the update is already applied!
+
+The code has been updated to use the new Inference Providers API automatically.
+
+---
+
+## 🔍 How to Verify
+
+**Run the test script:**
+```bash
+python test_hf_backend.py
+```
+
+**Look for this line:**
+```
+✓ Using new Inference Providers API endpoint
+```
+
+**Or check manually:**
+```bash
+python check_env.py
+```
+
+---
+
+## 📦 What You Need to Do
+
+### If You Deployed BEFORE November 2025:
+
+**Option 1: Update the Code (Recommended)**
+1. Pull the latest version of `llm_backend.py`
+2. Restart your application
+3. Test with `python test_hf_backend.py`
+
+**Option 2: Manual Update**
+
+Edit `llm_backend.py` around line 80:
+
+```python
+# Find this line:
+return f"https://api-inference.huggingface.co/models/{self.model}"
+
+# Replace with:
+return f"https://router.huggingface.co/hf-inference/models/{self.model}"
+```
+
+### If You're Deploying NEW:
+
+**No action needed!** The latest code already uses the new endpoint.
+
+---
+
+## 🐛 Symptoms of Old Endpoint
+
+If you're still using the old endpoint, you'll see:
+
+```
+❌ Error generating survey: Survey generation failed:
+LLM generation failed: 404 Client Error: Not Found for url:
+https://api-inference.huggingface.co/models/mistralai/Mixtral-8x7B-Instruct-v0.1
+```
+
+**Solution:** Update to the new endpoint as described above.
+
+---
+
+## 📚 More Information
+
+**Official HuggingFace Announcement:**
+- Migration deadline: November 1, 2025
+- Old endpoint returns 404 errors after deadline
+- New API docs: https://huggingface.co/docs/inference-providers
+
+**Benefits of New API:**
+- Access to more models
+- Better performance and reliability
+- Unified API across all inference services
+- Future-proof for new features
+
+---
+
+## ❓ FAQ
+
+**Q: Do I need a new API token?**
+A: No, your existing HF_TOKEN or HUGGINGFACE_API_KEY works with the new endpoint.
+
+**Q: Will this affect my deployed HuggingFace Space?**
+A: Yes, if it was deployed before this update. Simply update the code and restart.
+
+**Q: Do I need to change any configuration?**
+A: No, just update the code. All configuration remains the same.
+
+**Q: What if I use OpenAI or Anthropic?**
+A: This change only affects HuggingFace users. Other providers are unaffected.
+
+**Q: Will my old surveys/data still work?**
+A: Yes, this is only an API endpoint change. All data formats remain compatible.
+
+**Q: How do I know if I'm affected?**
+A: If you see 404 errors when using HuggingFace provider, you need to update.
+
+---
+
+## ✅ Verification Checklist
+
+After updating, verify everything works:
+
+- [ ] Updated `llm_backend.py` to use new endpoint
+- [ ] Ran `python test_hf_backend.py` - shows new endpoint
+- [ ] Tested survey generation - works without 404 errors
+- [ ] Tested translation - works correctly
+- [ ] Tested analysis - works correctly
+- [ ] No 404 errors in logs
+- [ ] Application runs normally
+
+---
+
+## 🆘 Need Help?
+
+**If you're still getting 404 errors after updating:**
+
+1. **Verify the update:**
+   ```bash
+   grep "router.huggingface.co" llm_backend.py
+   ```
+   Should return a match. If not, update wasn't applied.
+
+2. **Check you're using HuggingFace:**
+   ```bash
+   python check_env.py
+   ```
+   Look for which provider is being used.
+
+3. **Test the connection:**
+   ```bash
+   python test_hf_backend.py
+   ```
+   Should show "✓ Using new Inference Providers API endpoint"
+
+4. **Clear any caches:**
+   - Restart your application
+   - On HF Spaces: Factory reboot the Space
+
+5. **Still stuck?**
+   - Check TROUBLESHOOTING.md
+   - Verify your HF_TOKEN is still valid
+   - Try with a different model
+
+---
+
+## 📋 Migration Timeline
+
+| Date | Event |
+|------|-------|
+| January 2025 | Old endpoint deprecated, warnings sent |
+| November 1, 2025 | Old endpoint returns 404 errors |
+| **Today** | **This version updated to new endpoint** |
+
+---
+
+## 🚀 Bottom Line
+
+**If you're using this version:** ✅ You're all set! The update is already applied.
+
+**If you deployed before:** 🔄 Update your code to the latest version.
+
+**If you see 404 errors:** ⚠️ Follow the update instructions above.
+
+---
+
+**Updated:** November 2025
+**Status:** Migration Complete ✅
+**Action Required:** Update existing deployments to latest code
+
+For more details, see [CHANGELOG.md](CHANGELOG.md)

QUICK_START_HF_SPACES.md

@@ -38,7 +38,7 @@ Upload these files to your Space (drag and drop or use Git):
 
 ### 4. Test It!
 
-**That's it!** No configuration needed. The app automatically uses HuggingFace's free Inference API.
+**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

README.md

@@ -14,6 +14,12 @@ license: mit
 
 Battle the blank page, reach global audiences, and uncover insights with AI assistance.
 
+---
+
+> **🔄 IMPORTANT UPDATE (Nov 2025):** HuggingFace API endpoint updated to new Inference Providers API. This version is already updated. See [MIGRATION_NOTICE.md](MIGRATION_NOTICE.md) if you're experiencing 404 errors.
+
+---
+
 ## 🌟 Features
 
 ### 📝 Survey Generation
@@ -49,11 +55,12 @@ Battle the blank page, reach global audiences, and uncover insights with AI assi
 
 ### HuggingFace Spaces (Default)
 
-**No configuration needed!** The app automatically uses HuggingFace's Inference API.
+**No configuration needed!** The app automatically uses HuggingFace's Inference Providers API.
 
 - Uses built-in `HF_TOKEN` (automatically available in **PUBLIC** Spaces)
 - Default model: `mistralai/Mixtral-8x7B-Instruct-v0.1`
 - Free tier available
+- **Updated**: Now uses new Inference Providers API endpoint (Nov 2025)
 
 **⚠️ Important:** Your Space must be **PUBLIC** for HF_TOKEN to be automatically available.
 
@@ -126,4 +133,23 @@ MIT License - Feel free to use for research and commercial purposes.
 
 ---
 
+## 📚 Documentation
+
+**New to ConversAI?** Start with **[USER_GUIDE.md](USER_GUIDE.md)** for a complete walkthrough.
+
+**Full Documentation Index:** See **[DOCUMENTATION_INDEX.md](DOCUMENTATION_INDEX.md)** for all available guides.
+
+**Quick Links:**
+- 📖 [Complete User Guide](USER_GUIDE.md) - How to use ConversAI (START HERE)
+- ⚡ [Quick Start for HF Spaces](QUICK_START_HF_SPACES.md) - 5-minute deployment
+- 🔧 [Troubleshooting](TROUBLESHOOTING.md) - Common issues and solutions
+- 🚀 [Deployment Guide](DEPLOYMENT.md) - Detailed deployment instructions
+- 📋 [Usage Guide](USAGE_GUIDE.md) - Technical usage documentation
+
+**Diagnostic Tools:**
+- Run `python check_env.py` - Check your environment setup
+- Run `python test_hf_backend.py` - Test HuggingFace connection
+
+---
+
 Built with ❤️ using Gradio and state-of-the-art LLMs

TROUBLESHOOTING.md

@@ -2,6 +2,19 @@
 
 ## Common Issues and Solutions
 
+### 🔄 HuggingFace API Update (November 2025)
+
+**Important:** HuggingFace has updated their Inference API endpoint.
+
+**If you see 404 errors:**
+- ✅ Make sure you're using the latest version of `llm_backend.py`
+- ✅ The new endpoint is: `https://router.huggingface.co/hf-inference/`
+- ✅ Old endpoint (`api-inference.huggingface.co`) is deprecated
+
+**Already updated:** This version uses the new Inference Providers API automatically.
+
+---
+
 ### ❌ "LLM backend not configured" Error
 
 **Symptom:** App shows warning banner, features don't work

llm_backend.py

@@ -77,7 +77,8 @@ class LLMBackend:
         elif self.provider == LLMProvider.ANTHROPIC:
             return "https://api.anthropic.com/v1/messages"
         elif self.provider == LLMProvider.HUGGINGFACE:
-            return f"https://api-inference.huggingface.co/models/{self.model}"
+            # Updated to new Inference Providers API (Nov 2025)
+            return f"https://router.huggingface.co/hf-inference/models/{self.model}"
         elif self.provider == LLMProvider.LM_STUDIO:
             return os.getenv("LM_STUDIO_URL", "http://192.168.1.245:1234/v1/chat/completions")
 

test_hf_backend.py

@@ -8,7 +8,8 @@ from llm_backend import LLMBackend, LLMProvider
 def test_hf_connection():
     """Test HuggingFace Inference API connection"""
     print("="*60)
-    print("Testing HuggingFace Inference API Connection")
+    print("Testing HuggingFace Inference Providers API Connection")
+    print("(Updated Nov 2025 - New Endpoint)")
     print("="*60)
 
     # Check for token
@@ -27,6 +28,13 @@ def test_hf_connection():
         print(f"  Provider: {backend.provider.value}")
         print(f"  Model: {backend.model}")
         print(f"  API URL: {backend.api_url}")
+
+        # Verify we're using the new endpoint
+        if "router.huggingface.co/hf-inference" in backend.api_url:
+            print(f"  ✓ Using new Inference Providers API endpoint")
+        else:
+            print(f"  ⚠️  WARNING: Not using new endpoint! Update llm_backend.py")
+
     except Exception as e:
         print(f"✗ Backend initialization failed: {e}")
         return False