# Testing Rate Limiters on Hugging Face Space

## Overview
This guide explains how to test the rate limiters directly on your HF Space where the NCBI API key is configured.

---

## Option 1: Run via HF Space Terminal (Recommended)

### Steps:

1. **Open your HF Space**:
   - Go to: https://huggingface.co/spaces/John-jero/IDWeekAgents

2. **Click "⋮" menu → "Open Terminal"**:
   - This opens a terminal directly on the Space

3. **Run the test script**:
   ```bash
   python scripts/test_rate_limiters.py
   ```

4. **Review the results**:
   - ✅ Success: No HTTP 429 errors = rate limiters working
   - ❌ Failure: HTTP 429 errors = rate limiters need adjustment

---

## Option 2: Add Test Button to Gradio Interface

### Create a test interface in `app.py`:

```python
def test_rate_limiters():
    """Run rate limiter tests"""
    import subprocess
    result = subprocess.run(
        ["python", "scripts/test_rate_limiters.py"],
        capture_output=True,
        text=True
    )
    return result.stdout + "\n" + result.stderr

# Add to Gradio interface
with gr.Tab("Admin Tests"):
    test_btn = gr.Button("Test Rate Limiters")
    test_output = gr.Textbox(label="Test Results", lines=30)
    test_btn.click(test_rate_limiters, outputs=test_output)
```

---

## Option 3: Run Locally with API Keys

If you want to test locally, add both API keys to your `.env` file:

```bash
SERPER_API_KEY=your_serper_key_here
NCBI_API_KEY=your_ncbi_key_here
```

Then run:
```bash
python scripts/test_rate_limiters.py
```

---

## What the Test Does

### 1. **Serper API Test** (15 concurrent requests)
   - Tests rate limiting at 50 req/s (Dev tier)
   - Checks for HTTP 429 errors
   - Measures response times

### 2. **NCBI API Test** (15 concurrent requests)
   - Tests rate limiting at 8 req/s (with API key)
   - Checks for HTTP 429 errors
   - Measures response times

### 3. **Cache Effectiveness Test**
   - Runs same query twice
   - Verifies 2nd request is faster (cache hit)
   - Tests both Serper and NCBI caches

---

## Expected Results

### ✅ **Success:**
```
📊 Overall Success Rates:
   Serper API: 100.0%
   NCBI API: 100.0%

🎉 SUCCESS: No HTTP 429 errors detected!
   ✅ Rate limiters are working correctly
   ✅ Ready for 150-user workshop
```

### ⚠️ **Warning:**
```
⚠️ WARNING: HTTP 429 errors detected:
   - Serper API: 3 rate limit errors
   - NCBI API: 5 rate limit errors
   ⚠️ Rate limiters may need adjustment
```

---

## Troubleshooting

### If you see HTTP 429 errors:

1. **Check API Keys**:
   ```python
   import os
   print("Serper:", os.getenv("SERPER_API_KEY")[:10] if os.getenv("SERPER_API_KEY") else "Missing")
   print("NCBI:", os.getenv("NCBI_API_KEY")[:10] if os.getenv("NCBI_API_KEY") else "Missing")
   ```

2. **Check Rate Limiter Config**:
   - Serper: `core/utils/serper_rate_limited.py` line 53 (should be 50 req/s)
   - NCBI: `core/utils/ncbi_rate_limited.py` line 57-58 (should be 8 req/s with key)

3. **Check HF Space Secrets**:
   - Go to: Settings → Repository secrets
   - Verify `SERPER_API_KEY` and `NCBI_API_KEY` are set

4. **Restart HF Space**:
   - Sometimes environment variables need a restart
   - Go to: Settings → Factory reboot

---

## Performance Benchmarks

### Expected Response Times:

**Serper API:**
- First request (no cache): 500-800ms
- Cached request: <50ms
- Throttled request: 1-2s delay (when at limit)

**NCBI API:**
- First request (no cache): 200-400ms
- Cached request: <50ms
- Throttled request: 1-2s delay (when at limit)

### Expected Throughput:

**15 Concurrent Requests:**
- Serper: ~3-5 seconds total (throttled to 50 req/s)
- NCBI: ~2-3 seconds total (throttled to 8 req/s)

---

## Next Steps After Testing

### ✅ If All Tests Pass:
1. You're ready for the workshop! 🎉
2. Optional: Run a larger test (50-100 concurrent)
3. Optional: Set HF Space sleep timer for cost savings

### ⚠️ If Tests Fail:
1. Review error messages carefully
2. Check API key configuration
3. Verify rate limiter settings
4. Contact support if issues persist

---

## Additional Test: Manual Concurrent Testing

You can also test manually by having multiple people use the app:

1. Share your HF Space link with 5-10 colleagues
2. Have everyone search at the same time
3. Monitor for errors or slowdowns
4. Check HF Space logs for HTTP 429 errors

---

## Contact & Support

- **HF Space**: https://huggingface.co/spaces/John-jero/IDWeekAgents
- **GitHub**: Your repository
- **Test Script**: `scripts/test_rate_limiters.py`
- **Documentation**: `docs/RATE_LIMITER_INTEGRATION.md`

---

**Last Updated**: October 12, 2025  
**Status**: Ready for testing on HF Space