MIGRATION_NOTICE.md

# 🔄 IMPORTANT: HuggingFace API Migration Notice

## Critical Update - November 2025

HuggingFace is migrating from their old Inference API endpoint to a new Inference Providers API.

**⚠️ UPDATE:** The new endpoint format is still being tested. **For now, we recommend using OpenAI or Anthropic for production use.**

---

## ⚠️ 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)