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)