# 🚀 Hugging Face Spaces Deployment Guide

This guide will walk you through deploying the Theorem Explanation Agent to Hugging Face Spaces.

## 📋 Prerequisites

1. **Hugging Face Account**: Create an account at [huggingface.co](https://huggingface.co)
2. **Gemini API Key(s)**: Get from [Google AI Studio](https://makersuite.google.com/app/apikey)
3. **Optional**: ElevenLabs API key for text-to-speech

## 🔧 Step-by-Step Deployment

### Step 1: Create a New Space

1. Go to [Hugging Face Spaces](https://huggingface.co/spaces)
2. Click "Create new Space"
3. Fill in details:
   - **Space name**: `theorem-explanation-agent` (or your choice)
   - **License**: MIT
   - **SDK**: Gradio
   - **Hardware**: CPU Basic (can upgrade later)
   - **Visibility**: Public

### Step 2: Upload Your Code

You have two options:

#### Option A: Git Clone (Recommended)
```bash
git clone https://github.com/yourusername/theorem-explanation-agent
cd theorem-explanation-agent
git remote add hf https://huggingface.co/spaces/yourusername/theorem-explanation-agent
git push hf main
```

#### Option B: Upload Files Manually
1. Upload these key files to your Space:
   - `app.py`
   - `huggingface_spaces_app.py`
   - `requirements_hf.txt`
   - `README_HUGGINGFACE.md`
   - All folders: `src/`, `mllm_tools/`, etc.

### Step 3: Configure API Keys

1. Go to your Space's **Settings** tab
2. Scroll down to **Repository secrets**
3. Add these secrets:

#### Required Secrets

**Multiple API Keys (Recommended)**
```
Name: GEMINI_API_KEY
Value: AIzaSyA1...,AIzaSyB2...,AIzaSyC3...,AIzaSyD4...
```

**Single API Key**
```  
Name: GEMINI_API_KEY
Value: AIzaSyA1...
```

#### Optional Secrets

**Enable Full Mode**
```
Name: DEMO_MODE
Value: false
```

**Text-to-Speech (Optional)**
```
Name: ELEVENLABS_API_KEY
Value: your_elevenlabs_api_key
```

### Step 4: Configure App Settings

In your Space settings:

1. **Hardware**: 
   - Start with CPU Basic (free)
   - Upgrade to CPU Optimized for better performance
   - Use GPU only if you enable advanced features

2. **Environment**:
   - Python version: 3.9+
   - Gradio SDK will be automatically detected

3. **Persistent Storage** (Optional):
   - Enable if you want to keep generated videos
   - Useful for caching and avoiding regeneration

## 🔑 API Key Setup Details

### How the Fallback System Works

The app uses a smart API key rotation system:

```python
# Your GEMINI_API_KEY can be:
# Single key: "AIzaSyA..."
# Multiple keys: "AIzaSyA...,AIzaSyB...,AIzaSyC..."

# The system will:
# 1. Parse comma-separated keys
# 2. Randomly select one for each request
# 3. Automatically retry with different keys if one fails
# 4. Log which key is being used (first 20 chars only)
```

### Benefits of Multiple Keys

1. **Rate Limit Avoidance**: Distributes requests across keys
2. **Higher Throughput**: Can handle more concurrent requests
3. **Fault Tolerance**: If one key fails, others continue working
4. **Cost Distribution**: Spreads usage across multiple billing accounts

### Recommended Setup

For production use, we recommend **4 API keys**:

```
GEMINI_API_KEY=key1,key2,key3,key4
```

This provides good balance between rate limit avoidance and key management complexity.

## 📊 Monitoring and Costs

### Cost Estimation

- **Demo Mode**: Free (no API calls)
- **Single Scene**: ~$0.001-0.01 per generation
- **Full Video (3-6 scenes)**: ~$0.01-0.05 per generation
- **Multiple API Keys**: Costs distributed across accounts

### Monitoring Usage

1. **Google Cloud Console**: Monitor API usage per key
2. **Hugging Face Metrics**: View Space usage and performance
3. **App Logs**: Check which API keys are being selected

### Usage Patterns

```
Selected random Gemini API key from 4 available keys: AIzaSyDuKKriNMayoPwn...
Selected random Gemini API key from 4 available keys: AIzaSyDa44QjZES9qp8L...
```

## 🔧 Troubleshooting

### Common Issues

1. **"Demo mode active"**
   - Check `GEMINI_API_KEY` is set in Secrets
   - Verify key format (comma-separated if multiple)
   - Ensure `DEMO_MODE=false` if you want full functionality

2. **"Rate limit exceeded"**
   - Add more API keys to your `GEMINI_API_KEY`
   - Wait a few minutes before retrying
   - Consider upgrading to paid Gemini tier

3. **"Generation failed"**
   - Try simpler topics first
   - Check API key validity
   - Verify topic is educational/mathematical

4. **Slow performance**
   - Upgrade Hardware tier in Space settings
   - Use multiple API keys for better throughput
   - Enable persistent storage for caching

### Error Messages and Solutions

| Error | Solution |
|-------|----------|
| `No API_KEY found` | Set `GEMINI_API_KEY` in Secrets |
| `Model is overloaded` | Add more API keys or retry later |
| `Invalid API key` | Check key format and validity |
| `Demo mode active` | Set API keys and `DEMO_MODE=false` |

## 🚀 Performance Optimization

### Hardware Recommendations

- **CPU Basic**: Good for demo and light usage
- **CPU Optimized**: Better for regular usage  
- **GPU**: Only needed for advanced video processing

### API Key Strategy

```python
# Optimal setup for production:
GEMINI_API_KEY=key1,key2,key3,key4
DEMO_MODE=false
ELEVENLABS_API_KEY=optional_tts_key
```

### Scaling Considerations

1. **Multiple Keys**: 4-6 keys for high usage
2. **Persistent Storage**: Cache results to avoid regeneration
3. **Hardware Upgrade**: CPU Optimized or GPU for faster processing
4. **Rate Limiting**: Implement user request limiting if needed

## 📞 Support and Resources

### Hugging Face Resources
- [Spaces Documentation](https://huggingface.co/docs/hub/spaces)
- [Gradio Documentation](https://gradio.app/docs/)
- [Community Forums](https://discuss.huggingface.co/)

### API Resources
- [Google AI Studio](https://makersuite.google.com/)
- [Gemini API Documentation](https://ai.google.dev/)
- [ElevenLabs API](https://elevenlabs.io/docs/)

### Getting Help

1. **Check app logs** in Space settings
2. **Test with simple topics** first
3. **Verify API keys** in Google Cloud Console
4. **Monitor costs** and usage patterns

---

**Ready to deploy?** Follow these steps and you'll have your Theorem Explanation Agent running on Hugging Face Spaces with automatic API key rotation!