DEPLOYMENT_GUIDE.md

Deployment Guide: Theorem Explanation Agent

Overview

This guide explains how to deploy the Theorem Explanation Agent to Hugging Face Spaces for actual video generation.

Prerequisites

• Hugging Face account
• Gemini API key(s) from Google AI Studio
• Basic understanding of environment variables

Quick Start

1. Create New Hugging Face Space

1. Go to Hugging Face Spaces
2. Click "Create new Space"
3. Configure:
   • Space name: Your choice (e.g., "theorem-explanation-agent")
   • License: MIT
   • SDK: Gradio
   • Hardware: CPU Basic (sufficient for most cases)
   • Visibility: Public or Private

2. Upload Files

Upload these files to your space:

• app.py (main application)
• requirements_hf.txt (rename to requirements.txt)
• README_HUGGINGFACE.md (rename to README.md)
• All source files from src/, mllm_tools/, etc.

3. Set Environment Variables

In your Hugging Face Space settings, add:

For Single API Key:

GEMINI_API_KEY=your-actual-gemini-api-key
DEMO_MODE=false

For Multiple API Keys (Recommended):

GEMINI_API_KEY=key1,key2,key3,key4
DEMO_MODE=false

Optional Settings:

ELEVENLABS_API_KEY=your-elevenlabs-key  # For TTS
LANGFUSE_SECRET_KEY=your-langfuse-key   # For logging

Features Enabled

✅ Real Video Generation

• DEMO_MODE=false: Enables actual video generation
• Gemini 2.0 Flash Exp: Latest model for best results
• Manim Integration: Professional mathematical animations

✅ Comma-Separated API Keys

• Load Balancing: Distributes requests across multiple keys
• Failover: Automatic switching if one key fails
• Cost Distribution: Spreads usage across billing accounts

✅ Educational Focus

• Mathematical Concepts: Optimized for STEM education
• Visual Learning: Geometric proofs and demonstrations
• Progressive Difficulty: Suitable for various learning levels

Usage Instructions

1. Access Your Space

Visit: https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME

2. Generate Videos

1. Enter Topic: e.g., "Pythagorean Theorem"
2. Add Context: Specify focus areas or audience
3. Set Scenes: 2-3 scenes for testing, up to 6 for full videos
4. Click Generate: Wait for processing (2-10 minutes)

3. Download Results

• Videos appear in the interface
• Download links provided for MP4 files
• Individual scene videos also available

Troubleshooting

Common Issues

1. "Demo Mode" Message

Problem: App shows demo simulation instead of real generation
Solution: Set DEMO_MODE=false in environment variables

2. "No API Keys Found"

Problem: Missing or incorrect API key configuration
Solution: Set GEMINI_API_KEY with valid key(s)

3. "Import Error"

Problem: Missing dependencies
Solution: Ensure requirements.txt includes all packages

4. "Generation Failed"

Problem: API quota exceeded or invalid topic
Solution: Check API limits, try different topic

Verification Steps

1. Test Local Setup:

python test_video_generation.py

2. Check API Keys:

echo $GEMINI_API_KEY | tr ',' '\n' | wc -l
# Should show number of keys

3. Verify Dependencies:

pip install -r requirements.txt
python -c "from generate_video import VideoGenerator; print('✅ Imports work')"

Performance Optimization

API Key Management

• 4+ Keys: Optimal for high usage
• Rate Limiting: 60 requests/minute per key
• Monitoring: Check usage in Google AI Studio

Hardware Requirements

• CPU Basic: Sufficient for most educational videos
• CPU Upgrade: Consider for complex visualizations
• Persistent Storage: Enable for caching (optional)

Content Guidelines

• Educational Topics: Math, science, engineering concepts
• Clear Descriptions: Specific learning objectives
• Reasonable Scope: 2-6 scenes per video

Advanced Configuration

Custom Model Settings

Edit app.py to modify:

planner_model = LiteLLMWrapper(
    model_name="gemini/gemini-2.0-flash-exp",  # Model choice
    temperature=0.7,  # Creativity level
    print_cost=True,  # Cost tracking
    verbose=True      # Debug output
)

Output Customization

Modify GRADIO_OUTPUT_DIR in app.py:

GRADIO_OUTPUT_DIR = "custom_outputs"  # Change output folder

Feature Toggles

# In VideoGenerator initialization
use_rag=False,              # Retrieval augmented generation
use_context_learning=True,  # Few-shot learning
use_visual_fix_code=True,   # Visual debugging
verbose=True                # Detailed logging

Security Considerations

API Key Protection

• Never commit keys to version control
• Use HF Spaces environment variables
• Monitor usage regularly

Content Moderation

• Educational content only
• Avoid sensitive topics
• Review generated content

Support

Getting Help

1. Check Logs: HF Spaces build logs
2. Test Locally: Use test_video_generation.py
3. Issues: Report problems with error messages
4. Community: HF Spaces forums

Useful Resources

• Hugging Face Spaces Documentation
• Gradio Documentation
• Gemini API Documentation
• Manim Documentation

Example Successful Deployment

Space URL: https://huggingface.co/spaces/ManojINaik/menamiai Features: Full video generation with comma-separated API keys Status: Operational with educational content focus

---

This deployment guide ensures your Theorem Explanation Agent works with actual video generation capabilities on Hugging Face Spaces.