Add Hugging Face Spaces frontend with API key fallback system

.cursor/rules/rules.mdc

@@ -0,0 +1,9 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+always use the powershell commands don't use the command prompt command and always use the .venv virual environ ment.
+
+
+At last always use the rewiew-gate mcp to get review from user about your work form that you have to fix/ do what user told if it fails because of any reson call terminal with {echo"user review"}.

.specstory/history/.what-is-this.md

@@ -0,0 +1,65 @@
+
+# SpecStory Artifacts Directory
+    
+This directory is automatically created and maintained by the SpecStory extension to preserve your Cursor composer and chat history.
+    
+## What's Here?
+    
+- `.specstory/history`: Contains markdown files of your AI coding sessions
+    - Each file represents a separate chat or composer session
+    - Files are automatically updated as you work
+- `.specstory/cursor_rules_backups`: Contains backups of the `.cursor/rules/derived-cursor-rules.mdc` file
+    - Backups are automatically created each time the `.cursor/rules/derived-cursor-rules.mdc` file is updated
+    - You can enable/disable the Cursor Rules feature in the SpecStory settings
+
+## Valuable Uses
+    
+- Capture: Keep your context window up-to-date when starting new Chat/Composer sessions via @ references
+- Search: For previous prompts and code snippets 
+- Learn: Meta-analyze your patterns and learn from your past experiences
+- Derive: Keep Cursor on course with your past decisions by automatically deriving Cursor rules from your AI interactions
+    
+## Version Control
+    
+We recommend keeping this directory under version control to maintain a history of your AI interactions. However, if you prefer not to version these files, you can exclude them by adding this to your `.gitignore`:
+    
+```
+.specstory
+```
+
+We recommend not keeping the `.specstory/cursor_rules_backups` directory under version control if you are already using git to version the `.cursor/rules` directory, and committing regularly. You can exclude it by adding this to your `.gitignore`:
+
+```
+.specstory/cursor_rules_backups
+```
+
+## Searching Your Codebase
+    
+When searching your codebase in Cursor, search results may include your previous AI coding interactions. To focus solely on your actual code files, you can exclude the AI interaction history from search results.
+    
+To exclude AI interaction history:
+    
+1. Open the "Find in Files" search in Cursor (Cmd/Ctrl + Shift + F)
+2. Navigate to the "files to exclude" section
+3. Add the following pattern:
+    
+```
+.specstory/*
+```
+    
+This will ensure your searches only return results from your working codebase files.
+
+## Notes
+
+- Auto-save only works when Cursor/sqlite flushes data to disk. This results in a small delay after the AI response is complete before SpecStory can save the history.
+- Auto-save does not yet work on remote WSL workspaces.
+
+## Settings
+    
+You can control auto-saving behavior in Cursor:
+    
+1. Open Cursor → Settings → VS Code Settings (Cmd/Ctrl + ,)
+2. Search for "SpecStory"
+3. Find "Auto Save" setting to enable/disable
+    
+Auto-save occurs when changes are detected in Cursor's sqlite database, or every 2 minutes as a safety net.

DEPLOYMENT_GUIDE.md

@@ -0,0 +1,230 @@
+# 🚀 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! 

Dockerfile.hf

@@ -0,0 +1,32 @@
+FROM python:3.9-slim
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies for video processing
+RUN apt-get update && apt-get install -y \
+    ffmpeg \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first for better caching
+COPY requirements_hf.txt .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements_hf.txt
+
+# Copy the application code
+COPY . .
+
+# Create output directory
+RUN mkdir -p output
+
+# Expose port
+EXPOSE 7860
+
+# Set environment variables
+ENV GRADIO_SERVER_NAME="0.0.0.0"
+ENV GRADIO_SERVER_PORT=7860
+
+# Run the application
+CMD ["python", "app.py"] 

README.md

@@ -4,9 +4,11 @@ emoji: 🎓
 colorFrom: blue
 colorTo: purple
 sdk: gradio
+sdk_version: 4.44.0
 app_file: app.py
 pinned: false
 license: mit
+python_version: 3.11
 ---
 
 # 🎓 Theorem Explanation Agent

README_HUGGINGFACE.md

@@ -0,0 +1,135 @@
+# 🎓 Theorem Explanation Agent - Hugging Face Spaces
+
+This is a Gradio web interface for generating educational videos that explain mathematical theorems and scientific concepts using AI.
+
+## 🚀 Features
+
+- **AI-Powered Video Generation**: Uses Gemini 2.0 Flash to create educational content
+- **Automatic API Key Rotation**: Supports multiple Gemini API keys with fallback mechanism
+- **Educational Focus**: Specializes in mathematical and scientific explanations
+- **Interactive Interface**: Clean, user-friendly Gradio interface
+- **Demo Mode**: Works without API keys for demonstration purposes
+
+## 🔑 Setting Up API Keys on Hugging Face Spaces
+
+### Step 1: Get Your Gemini API Keys
+
+1. Go to [Google AI Studio](https://makersuite.google.com/app/apikey)
+2. Create one or more API keys
+3. Copy the keys (they look like: `AIzaSyA...`)
+
+### Step 2: Configure Secrets on Hugging Face Spaces
+
+1. Go to your Space's **Settings** tab
+2. Click on **Repository secrets**
+3. Add the following secrets:
+
+#### For Multiple API Keys (Recommended)
+```
+Name: GEMINI_API_KEY
+Value: AIzaSyA...,AIzaSyB...,AIzaSyC...,AIzaSyD...
+```
+
+#### For Single API Key
+```
+Name: GEMINI_API_KEY  
+Value: AIzaSyA...
+```
+
+#### Optional: Text-to-Speech
+```
+Name: ELEVENLABS_API_KEY
+Value: your_elevenlabs_api_key
+```
+
+#### Enable Full Mode
+```
+Name: DEMO_MODE
+Value: false
+```
+
+### Step 3: How the Fallback System Works
+
+The app automatically handles multiple API keys:
+
+1. **Comma-Separated Keys**: When you provide multiple keys separated by commas, the system randomly selects one for each request
+2. **Automatic Rotation**: This helps avoid rate limits and distributes load
+3. **Error Handling**: If one key fails, the system continues working
+4. **Usage Tracking**: Each key selection is logged for monitoring
+
+## 📝 Example Usage
+
+### Basic Topics
+- "Velocity" - Physics concepts with examples
+- "Pythagorean Theorem" - Mathematical proofs
+- "Derivatives" - Calculus with geometric interpretation
+
+### Advanced Topics  
+- "Newton's Laws" - Physics with demonstrations
+- "Chemical Bonding" - Chemistry with molecular examples
+- "Probability" - Statistics with practical examples
+
+## 🛠️ Configuration Options
+
+### Environment Variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `GEMINI_API_KEY` | Gemini API key(s) - supports comma-separated multiple keys | `key1,key2,key3` |
+| `ELEVENLABS_API_KEY` | Optional: ElevenLabs API key for TTS | `your_elevenlabs_key` |
+| `DEMO_MODE` | Set to "false" to enable full functionality | `false` |
+
+### Video Generation Settings
+
+- **Max Scenes**: 1-6 scenes per video (more scenes = longer videos, higher cost)
+- **Context**: Optional additional requirements or focus areas
+- **Topic**: Any mathematical or scientific concept
+
+## 💡 Tips for Best Results
+
+1. **Use Clear Topics**: "velocity in physics" works better than just "motion"
+2. **Provide Context**: Specify difficulty level, target audience, or focus areas
+3. **Start Simple**: Try basic concepts first, then move to advanced topics
+4. **Multiple Keys**: Use 3-4 API keys for better rate limit handling
+
+## 🔧 Troubleshooting
+
+### Common Issues
+
+1. **"No API keys found"**: Check that `GEMINI_API_KEY` is set in Secrets
+2. **Rate limit errors**: Add more API keys separated by commas
+3. **Generation fails**: Try simpler topics or shorter context
+4. **Slow response**: Normal for complex topics, progress bar shows status
+
+### Error Messages
+
+- **"Demo mode active"**: API keys not configured properly
+- **"Generation failed"**: Check topic validity and API key status
+- **"Rate limit exceeded"**: Add more API keys for rotation
+
+## 📊 Cost Considerations
+
+- Each scene costs approximately $0.001-0.01 in API calls
+- Multiple API keys help distribute costs
+- Demo mode is completely free but only simulates generation
+- Monitor usage through Google Cloud Console
+
+## 🚀 Deployment Checklist
+
+- [ ] Fork/clone the repository
+- [ ] Set up Gemini API key(s) in Secrets
+- [ ] Set `DEMO_MODE=false` if you want full functionality
+- [ ] Test with simple topics first
+- [ ] Monitor API usage and costs
+
+## 📞 Support
+
+For issues with:
+- **API Keys**: Check Google AI Studio documentation
+- **Rate Limits**: Add more API keys or wait before retrying  
+- **Video Generation**: Verify topic is educational/mathematical
+- **Hugging Face**: Check Spaces documentation
+
+---
+
+**Note**: This app is designed for educational content generation. The AI models work best with mathematical, scientific, and educational topics. 

app.py

@@ -1 +1,11 @@
- 
+#!/usr/bin/env python3
+"""
+Theorem Explanation Agent - Main entry point for Hugging Face Spaces
+"""
+
+# Import from our Hugging Face Spaces app
+from huggingface_spaces_app import create_interface
+
+if __name__ == "__main__":
+    demo = create_interface()
+    demo.launch() 

app_backup.py

@@ -0,0 +1,253 @@
+#!/usr/bin/env python3
+"""
+Theorem Explanation Agent - Gradio Interface
+A web interface for generating educational videos explaining mathematical theorems and concepts.
+"""
+
+import os
+import sys
+import json
+import traceback
+import tempfile
+import shutil
+from typing import Optional, List, Dict, Any
+import gradio as gr
+from pathlib import Path
+import asyncio
+import threading
+from datetime import datetime
+
+# Add the project root to Python path
+project_root = Path(__file__).parent
+sys.path.insert(0, str(project_root))
+
+# Demo mode flag - set to True for deployment environments with limited resources
+DEMO_MODE = os.getenv("DEMO_MODE", "true").lower() == "true"  # Default to demo mode for HF Spaces
+
+# Global variables for managing video generation
+video_generator = None
+generation_status = {}
+
+# Flag to track if we can import all dependencies
+CAN_IMPORT_DEPENDENCIES = True
+
+def initialize_video_generator():
+    """Initialize the video generator with default settings."""
+    global video_generator, CAN_IMPORT_DEPENDENCIES
+    try:
+        if DEMO_MODE:
+            return "✅ Demo mode - Video generator simulation enabled"
+        
+        if not CAN_IMPORT_DEPENDENCIES:
+            return "⚠️ Running in fallback mode due to missing dependencies"
+        
+        from generate_video import VideoGenerator
+        
+        video_generator = VideoGenerator(
+            planner_model="gemini/gemini-2.0-flash",
+            helper_model="gemini/gemini-2.0-flash",
+            scene_model="gemini/gemini-2.0-flash",
+            output_dir="output",
+            use_rag=False,
+            use_context_learning=False,
+            use_visual_fix_code=False,
+            print_response=False
+        )
+        return "✅ Video generator initialized successfully"
+    except Exception as e:
+        CAN_IMPORT_DEPENDENCIES = False
+        return f"❌ Failed to initialize video generator: {str(e)}\n\n🔧 Running in demo mode"
+
+def simulate_video_generation(topic: str, context: str, max_scenes: int) -> Dict[str, Any]:
+    """Simulate video generation for demo purposes."""
+    import time
+    import random
+    
+    # Simulate different stages
+    stages = [
+        ("Planning video structure", 20),
+        ("Generating scene outlines", 40),
+        ("Creating animations", 60),
+        ("Rendering videos", 80),
+        ("Finalizing output", 100)
+    ]
+    
+    for stage, progress in stages:
+        time.sleep(random.uniform(0.1, 0.3))  # Faster for demo
+    
+    return {
+        "success": True,
+        "message": f"Demo video generated for topic: {topic}",
+        "scenes_created": max_scenes,
+        "total_duration": "2.5 minutes",
+        "demo_note": "This is a simulated result. In production, actual Manim videos would be generated."
+    }
+
+def generate_video_demo(topic: str, context: str = "", max_scenes: int = 3) -> str:
+    """Generate a video explanation for the given topic (demo version)."""
+    if not topic.strip():
+        return "❌ Please enter a topic to explain"
+    
+    try:
+        # Simulate video generation
+        result = simulate_video_generation(topic, context, max_scenes)
+        
+        output = f"""🎓 **Theorem Explanation Agent**
+
+**Topic:** {topic}
+**Context:** {context if context else "None provided"}
+**Max Scenes:** {max_scenes}
+
+**✅ Demo Generation Complete!**
+
+📊 **Results:**
+- Scenes Created: {result['scenes_created']}
+- Total Duration: {result['total_duration']}
+- Status: {result['message']}
+
+⚠️ **Demo Mode Note:**
+{result['demo_note']}
+
+🚀 **To enable full video generation:**
+1. Set up API keys (GEMINI_API_KEY, etc.)
+2. Install full dependencies (Manim, FFmpeg, etc.)
+3. Set DEMO_MODE=false
+
+📝 **Example topics to try:**
+- Pythagorean Theorem
+- Velocity in Physics
+- Derivatives in Calculus
+- Newton's Laws of Motion
+"""
+        return output
+        
+    except Exception as e:
+        return f"❌ Error during generation: {str(e)}\n\nPlease try with a simpler topic."
+
+def get_example_topics() -> List[List[str]]:
+    """Get example topics for the interface."""
+    return [
+        ["Pythagorean Theorem", "Explain with visual proof and real-world applications"],
+        ["Velocity", "Explain velocity in physics with detailed examples"],
+        ["Derivatives", "Explain derivatives in calculus with geometric interpretation"],
+        ["Newton's Laws", "Explain Newton's three laws of motion with examples"],
+        ["Quadratic Formula", "Derive and explain the quadratic formula step by step"],
+        ["Logarithms", "Explain logarithms and their properties with examples"],
+        ["Probability", "Explain basic probability concepts with practical examples"],
+        ["Trigonometry", "Explain basic trigonometric functions and their uses"]
+    ]
+
+# Create the main interface
+with gr.Blocks(
+    title="🎓 Theorem Explanation Agent",
+    theme=gr.themes.Soft(),
+    css="""
+    .main-header {
+        text-align: center;
+        margin-bottom: 30px;
+        padding: 20px;
+        background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+        border-radius: 10px;
+        color: white;
+    }
+    .demo-warning {
+        background-color: #fff3cd;
+        border: 1px solid #ffeaa7;
+        border-radius: 5px;
+        padding: 15px;
+        margin: 10px 0;
+        color: #856404;
+    }
+    """
+) as demo:
+    
+    # Header
+    gr.HTML(f"""
+    <div class="main-header">
+        <h1>🎓 Theorem Explanation Agent</h1>
+        <p>Generate educational videos explaining mathematical theorems and concepts using AI</p>
+        {'<div class="demo-warning">⚠️ <strong>Demo Mode Active</strong> - This is a simulation for demonstration purposes.</div>' if DEMO_MODE else ''}
+    </div>
+    """)
+    
+    with gr.Row():
+        with gr.Column(scale=2):
+            gr.HTML("<h3>📝 Video Generation Settings</h3>")
+            
+            # Topic input
+            topic_input = gr.Textbox(
+                label="Topic to Explain",
+                placeholder="Enter the topic you want to explain (e.g., 'velocity', 'pythagorean theorem')",
+                lines=1
+            )
+            
+            # Context input
+            context_input = gr.Textbox(
+                label="Additional Context (Optional)",
+                placeholder="Provide additional context or specific requirements for the explanation",
+                lines=3
+            )
+            
+            # Max scenes
+            max_scenes_slider = gr.Slider(
+                label="Maximum Number of Scenes",
+                minimum=1,
+                maximum=5,
+                value=3,
+                step=1
+            )
+            
+            # Example topics
+            gr.HTML("<h4>💡 Example Topics</h4>")
+            examples = gr.Examples(
+                examples=get_example_topics(),
+                inputs=[topic_input, context_input]
+            )
+            
+            # Generate button
+            generate_btn = gr.Button(
+                "🚀 Generate Educational Video",
+                variant="primary",
+                size="lg"
+            )
+    
+        with gr.Column(scale=1):
+            gr.HTML("<h3>📊 System Status</h3>")
+            
+            # Initialization status
+            init_status = gr.Textbox(
+                label="System Status",
+                value="Click 'Initialize System' to check status",
+                interactive=False,
+                lines=3
+            )
+            init_btn = gr.Button("🔧 Initialize System")
+            
+            # Generation result
+            gr.HTML("<h3>📋 Generation Results</h3>")
+            result_display = gr.Textbox(
+                label="Generation Output",
+                lines=15,
+                interactive=False
+            )
+    
+    # Event handlers
+    init_btn.click(
+        fn=initialize_video_generator,
+        outputs=init_status
+    )
+    
+    generate_btn.click(
+        fn=generate_video_demo,
+        inputs=[topic_input, context_input, max_scenes_slider],
+        outputs=result_display
+    )
+
+# Launch the interface if run directly
+if __name__ == "__main__":
+    demo.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        share=False,
+        show_error=True
+    ) 

app_broken.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""
+Theorem Explanation Agent - Gradio Interface
+A web interface for generating educational videos explaining mathematical theorems and concepts.
+"""
+
+import gradio as gr
+
+def generate_explanation(topic, context, max_scenes):
+    """Generate educational content explanation."""
+    if not topic.strip():
+        return "❌ Please enter a topic to explain"
+    
+    result = f"""🎓 **Theorem Explanation Agent**
+
+📚 **Topic:** {topic}
+📋 **Context:** {context if context else "None specified"}
+🎬 **Scenes:** {max_scenes}
+
+✅ **Demo Generation Complete!**
+
+🎯 **Generated Educational Content:**
+• Introduction to {topic}
+• Fundamental concepts and definitions  
+• Step-by-step mathematical derivation
+• Visual demonstrations and proofs
+• Real-world applications and examples
+• Practice problems and solutions
+
+📊 **Video Specifications:**
+• Duration: ~{max_scenes * 0.8:.1f} minutes
+• Scene count: {max_scenes}
+• Style: Mathematical animations
+• Voiceover: AI-generated narration
+
+⚠️ **Demo Mode Active**
+This is a simulation showing the interface capabilities. 
+In production mode, actual Manim animations would be generated.
+
+🚀 **Production Features:**
+✓ Manim mathematical animations
+✓ AI-powered script generation  
+✓ Professional voiceover synthesis
+✓ Multiple output formats
+✓ Custom styling and branding
+"""
+    return result
+
+# Define the interface explicitly
+iface = gr.Interface(
+    fn=generate_explanation,
+    inputs=[
+        gr.Textbox(
+            label="🎯 Mathematical Topic", 
+            placeholder="Enter any mathematical concept (e.g., Pythagorean Theorem, Derivatives, etc.)",
+            value=""
+        ),
+        gr.Textbox(
+            label="📝 Additional Context", 
+            placeholder="Specify learning level, focus areas, or special requirements (optional)",
+            value=""
+        ),
+        gr.Slider(
+            label="🎬 Number of Video Scenes", 
+            minimum=1, 
+            maximum=8, 
+            value=4, 
+            step=1,
+            info="More scenes = more detailed explanation"
+        )
+    ],
+    outputs=gr.Textbox(
+        label="📊 Generated Educational Content", 
+        lines=20,
+        show_copy_button=True
+    ),
+    title="🎓 Theorem Explanation Agent",
+    description="🚀 Generate educational videos explaining mathematical theorems and concepts using AI-powered animations",
+    examples=[
+        ["Pythagorean Theorem", "Include visual proof and real-world applications", 4],
+        ["Calculus Derivatives", "Focus on geometric interpretation for beginners", 5], 
+        ["Newton's Laws of Motion", "Physics applications with practical examples", 3],
+        ["Quadratic Formula", "Step-by-step derivation with examples", 4],
+        ["Probability Distributions", "Visual explanations with real-world data", 5]
+    ],
+    theme=gr.themes.Soft(),
+    css="footer {visibility: hidden}"
+)
+
+# Export for HF Spaces
+demo = iface
+
+if __name__ == "__main__":
+    demo.launch() 

generate_video.py

@@ -18,7 +18,7 @@ from mllm_tools.utils import _prepare_text_inputs # Keep _prepare_text_inputs if
 from src.core.video_planner import VideoPlanner
 from src.core.code_generator import CodeGenerator
 from src.core.video_renderer import VideoRenderer
-from src.utils.utils import _print_response, _extract_code, extract_xml # Import utility functions
+from src.utils.utils import _print_response, _extract_code, extract_xml, extract_xml_tag # Import utility functions
 from src.config.config import Config # Import Config class
 
 # Video parsing
@@ -96,9 +96,12 @@ class VideoGenerator:
         self.scene_semaphore = asyncio.Semaphore(max_scene_concurrency)
         self.banned_reasonings = get_banned_reasonings()
 
+        # Initialize the planner with the model instance, not a string
+        self.planner_model = planner_model
+
         # Initialize separate modules
         self.planner = VideoPlanner(
-            planner_model=planner_model,
+            planner_model=self.planner_model, # Pass the initialized model
             helper_model=helper_model,
             output_dir=output_dir,
             print_response=verbose,
@@ -112,8 +115,8 @@ class VideoGenerator:
             use_langfuse=use_langfuse
         )
         self.code_generator = CodeGenerator(
-            scene_model=scene_model if scene_model is not None else planner_model,
-            helper_model=helper_model if helper_model is not None else planner_model,
+            scene_model=scene_model if scene_model is not None else self.planner_model, # Pass the model
+            helper_model=helper_model if helper_model is not None else self.planner_model, # Pass the model
             output_dir=output_dir,
             print_response=verbose,
             use_rag=use_rag,
@@ -201,12 +204,13 @@ class VideoGenerator:
         Args:
             topic (str): The topic of the video
             description (str): Description of the video content
-            session_id (str): Session identifier for tracking
+            session_id (str): Session identifier
 
         Returns:
-            str: Generated scene outline
+            str: Generated and extracted scene outline
         """
-        return self.planner.generate_scene_outline(topic, description, session_id)
+        scene_outline = self.planner.generate_scene_outline(topic, description, session_id)
+        return scene_outline
 
     async def generate_scene_implementation(self,
                                       topic: str,
@@ -405,7 +409,7 @@ class VideoGenerator:
 
                 curr_version += 1
                 # if program runs this, it means that the code is not rendered successfully
-                code, log = self.code_generator.fix_code_errors(
+                code = self.code_generator.fix_code_errors(
                     implementation_plan=scene_implementation,
                     code=code,
                     error=error_message,
@@ -417,7 +421,7 @@ class VideoGenerator:
                 )
 
                 with open(os.path.join(code_dir, f"{file_prefix}_scene{curr_scene}_v{curr_version}_fix_log.txt"), "w", encoding='utf-8') as f:
-                    f.write(log)
+                    f.write(error_message)
                 with open(os.path.join(code_dir, f"{file_prefix}_scene{curr_scene}_v{curr_version}.py"), "w", encoding='utf-8') as f:
                     f.write(code)
 
@@ -475,7 +479,7 @@ class VideoGenerator:
         """
         return await self.planner._generate_scene_implementation_single(topic, description, scene_outline_i, i, file_prefix, session_id, scene_trace_id)
 
-    async def generate_video_pipeline(self, topic: str, description: str, max_retries: int, only_plan: bool = False, specific_scenes: List[int] = None):
+    async def generate_video_pipeline(self, topic: str, description: str, max_retries: int, only_plan: bool = False, specific_scenes: List[int] = None, only_render: bool = False, only_combine: bool = False):
         """
         Modified pipeline to handle partial scene completions and option to only generate plans for specific scenes.
 
@@ -485,6 +489,8 @@ class VideoGenerator:
             max_retries (int): Maximum number of code fix attempts
             only_plan (bool, optional): Whether to only generate plans without rendering. Defaults to False.
             specific_scenes (List[int], optional): List of specific scenes to process. Defaults to None.
+            only_render (bool, optional): Whether to only render scenes without combining videos. Defaults to False.
+            only_combine (bool, optional): Whether to only combine videos. Defaults to False.
         """
         session_id = self._load_or_create_session_id()
         self._save_topic_session_id(topic, session_id)
@@ -495,7 +501,11 @@ class VideoGenerator:
         # Load or generate scene outline
         scene_outline_path = os.path.join(self.output_dir, file_prefix, f"{file_prefix}_scene_outline.txt")
         if not os.path.exists(scene_outline_path):
-            scene_outline = self.generate_scene_outline(topic, description, session_id)
+            scene_outline = self.planner.generate_scene_outline(topic, description, session_id)
+            if not scene_outline or not extract_xml(scene_outline):
+                print(f"❌ Failed to generate a valid scene outline for topic: {topic}. Aborting.")
+                raise ValueError("Failed to generate a valid scene outline from the AI model. Please try a different topic or model.")
+            
             os.makedirs(os.path.join(self.output_dir, file_prefix), exist_ok=True)
             with open(scene_outline_path, "w", encoding='utf-8') as f:
                 f.write(scene_outline)
@@ -504,6 +514,14 @@ class VideoGenerator:
             with open(scene_outline_path, "r", encoding='utf-8') as f:
                 scene_outline = f.read()
 
+        # After loading or generating, verify the outline has content
+        scene_outline_content = extract_xml(scene_outline)
+        if not scene_outline_content or len(re.findall(r'<SCENE_(\d+)>[^<]', scene_outline_content)) == 0:
+            print(f"❌ Scene outline for '{topic}' is empty or invalid. Deleting and aborting.")
+            if os.path.exists(scene_outline_path):
+                os.remove(scene_outline_path)
+            raise ValueError(f"The generated scene outline for '{topic}' was empty or invalid. The process cannot continue.")
+
         # Load or generate implementation plans
         implementation_plans_dict = self.load_implementation_plans(topic)
         if not implementation_plans_dict:
@@ -553,12 +571,10 @@ class VideoGenerator:
                     has_code = True
             
             # For only_render mode, only process scenes without code
-            if args.only_render:
+            if only_render:
                 if not has_code:
                     scenes_to_process.append((i+1, implementation_plan))
                     print(f"Scene {i+1} has no code, will process")
-                else:
-                    print(f"Scene {i+1} already has code, skipping")
             # For normal mode, process scenes that haven't been successfully rendered
             elif not os.path.exists(os.path.join(scene_dir, "succ_rendered.txt")):
                 scenes_to_process.append((i+1, implementation_plan))
@@ -576,7 +592,7 @@ class VideoGenerator:
             await self.render_video_fix_code(topic, description, scene_outline, filtered_implementation_plans,
                                            max_retries=max_retries, session_id=session_id)
         
-        if not args.only_render:  # Skip video combination in only_render mode
+        if not only_render:  # Skip video combination in only_render mode
             print(f"Video rendering completed for topic '{topic}'.")
 
     def check_theorem_status(self, theorem: Dict) -> Dict[str, bool]:
@@ -896,7 +912,9 @@ if __name__ == "__main__":
                             description, 
                             max_retries=args.max_retries,
                             only_plan=args.only_plan,
-                            specific_scenes=args.scenes
+                            specific_scenes=args.scenes,
+                            only_render=args.only_render,
+                            only_combine=args.only_combine
                         )
                         if not args.only_plan and not args.only_render:  # Add condition for only_render
                             video_generator.combine_videos(topic)
@@ -941,6 +959,8 @@ if __name__ == "__main__":
                 args.context,
                 max_retries=args.max_retries,
                 only_plan=args.only_plan,
+                only_render=args.only_render,
+                only_combine=args.only_combine
             ))
             if not args.only_plan and not args.only_render:
                 video_generator.combine_videos(args.topic)

huggingface_app.py

@@ -0,0 +1,421 @@
+#!/usr/bin/env python3
+"""
+Theorem Explanation Agent - Gradio Interface for Hugging Face Spaces
+A web interface for generating educational videos explaining mathematical theorems and concepts.
+"""
+
+import os
+import sys
+import json
+import traceback
+import tempfile
+import shutil
+import asyncio
+import threading
+import time
+import random
+from typing import Optional, List, Dict, Any, Tuple
+from pathlib import Path
+from datetime import datetime
+import gradio as gr
+import zipfile
+
+# Add the project root to Python path
+project_root = Path(__file__).parent
+sys.path.insert(0, str(project_root))
+
+# Environment setup for Hugging Face Spaces
+SPACE_ID = os.getenv("SPACE_ID", "")
+HF_TOKEN = os.getenv("HF_TOKEN", "")
+DEMO_MODE = os.getenv("DEMO_MODE", "true").lower() == "true"
+
+# Global variables
+video_generator = None
+generation_status = {}
+CAN_IMPORT_DEPENDENCIES = True
+
+def setup_environment():
+    """Setup environment variables and dependencies for Hugging Face Spaces."""
+    print("🚀 Setting up Theorem Explanation Agent...")
+    
+    # Check for API keys
+    gemini_keys = os.getenv("GEMINI_API_KEY", "")
+    if gemini_keys:
+        key_count = len([k.strip() for k in gemini_keys.split(',') if k.strip()])
+        print(f"✅ Found {key_count} Gemini API key(s)")
+    else:
+        print("⚠️ No Gemini API keys found - running in demo mode")
+    
+    # Check for optional environment variables
+    elevenlabs_key = os.getenv("ELEVENLABS_API_KEY", "")
+    if elevenlabs_key:
+        print("✅ ElevenLabs API key found")
+    else:
+        print("⚠️ No ElevenLabs API key found - TTS will be disabled")
+    
+    return True
+
+def initialize_video_generator():
+    """Initialize the video generator with error handling."""
+    global video_generator, CAN_IMPORT_DEPENDENCIES
+    
+    try:
+        if DEMO_MODE:
+            return "✅ Demo mode enabled - Video generation will be simulated"
+        
+        # Try importing dependencies
+        from generate_video import VideoGenerator
+        from mllm_tools.litellm import LiteLLMWrapper
+        
+        # Initialize models
+        planner_model = LiteLLMWrapper(
+            model_name="gemini/gemini-2.0-flash",
+            temperature=0.7,
+            print_cost=True,
+            verbose=False,
+            use_langfuse=False
+        )
+        
+        helper_model = LiteLLMWrapper(
+            model_name="gemini/gemini-2.0-flash",
+            temperature=0.7,
+            print_cost=True,
+            verbose=False,
+            use_langfuse=False
+        )
+        
+        video_generator = VideoGenerator(
+            planner_model=planner_model,
+            helper_model=helper_model,
+            scene_model=helper_model,
+            output_dir="output",
+            use_rag=False,
+            use_context_learning=False,
+            use_visual_fix_code=False,
+            verbose=False
+        )
+        
+        return "✅ Video generator initialized successfully with Gemini models"
+        
+    except ImportError as e:
+        CAN_IMPORT_DEPENDENCIES = False
+        print(f"Import error: {e}")
+        return f"⚠️ Missing dependencies - running in demo mode: {str(e)}"
+    except Exception as e:
+        CAN_IMPORT_DEPENDENCIES = False
+        print(f"Initialization error: {e}")
+        return f"⚠️ Failed to initialize - running in demo mode: {str(e)}"
+
+def simulate_video_generation(topic: str, context: str, max_scenes: int, progress_callback=None) -> Dict[str, Any]:
+    """Simulate video generation for demo purposes with progress updates."""
+    stages = [
+        ("🔍 Analyzing topic and context", 10),
+        ("📝 Planning video structure", 25),
+        ("🎬 Generating scene outlines", 45),
+        ("✨ Creating animations", 70),
+        ("🎥 Rendering videos", 85),
+        ("🔗 Combining scenes", 95),
+        ("✅ Finalizing output", 100)
+    ]
+    
+    results = []
+    for stage, progress in stages:
+        if progress_callback:
+            progress_callback(progress, stage)
+        time.sleep(random.uniform(0.2, 0.8))  # Simulate processing time
+        results.append(f"• {stage}")
+    
+    return {
+        "success": True,
+        "message": f"Demo video generated for topic: {topic}",
+        "scenes_created": max_scenes,
+        "total_duration": f"{max_scenes * 45} seconds",
+        "processing_steps": results,
+        "output_files": [
+            f"scene_{i+1}.mp4" for i in range(max_scenes)
+        ] + ["combined_video.mp4"],
+        "demo_note": "This is a simulated result for demonstration purposes."
+    }
+
+async def generate_video_async(topic: str, context: str, max_scenes: int, progress_callback=None):
+    """Asynchronously generate video with progress updates."""
+    global video_generator
+    
+    if not topic.strip():
+        return {"success": False, "error": "Please enter a topic to explain"}
+    
+    try:
+        if DEMO_MODE or not CAN_IMPORT_DEPENDENCIES:
+            return simulate_video_generation(topic, context, max_scenes, progress_callback)
+        
+        # Real video generation
+        if progress_callback:
+            progress_callback(10, "🚀 Starting video generation...")
+        
+        result = await video_generator.generate_video_pipeline(
+            topic=topic,
+            description=context,
+            max_retries=3,
+            only_plan=False,
+            specific_scenes=list(range(1, max_scenes + 1)),
+            only_render=False,
+            only_combine=False
+        )
+        
+        if progress_callback:
+            progress_callback(100, "✅ Video generation completed!")
+        
+        return {
+            "success": True,
+            "message": f"Video generated successfully for topic: {topic}",
+            "result": result
+        }
+        
+    except Exception as e:
+        error_msg = f"Error during generation: {str(e)}"
+        print(f"Generation error: {traceback.format_exc()}")
+        return {"success": False, "error": error_msg}
+
+def generate_video_gradio(topic: str, context: str, max_scenes: int, progress=gr.Progress()) -> Tuple[str, str]:
+    """Main function called by Gradio interface."""
+    def progress_callback(percent, message):
+        progress(percent / 100, desc=message)
+    
+    # Run async function in sync context
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    
+    try:
+        result = loop.run_until_complete(
+            generate_video_async(topic, context, max_scenes, progress_callback)
+        )
+    finally:
+        loop.close()
+    
+    if result["success"]:
+        output = f"""# 🎓 Video Generation Complete!
+
+## 📋 Generation Details
+- **Topic:** {topic}
+- **Context:** {context if context else "None provided"}
+- **Max Scenes:** {max_scenes}
+
+## ✅ Results
+{result["message"]}
+
+"""
+        
+        if "processing_steps" in result:
+            output += "## 🔄 Processing Steps\n"
+            for step in result["processing_steps"]:
+                output += f"{step}\n"
+            output += "\n"
+        
+        if "output_files" in result:
+            output += "## 📁 Generated Files\n"
+            for file in result["output_files"]:
+                output += f"• {file}\n"
+            output += "\n"
+        
+        if "demo_note" in result:
+            output += f"## ⚠️ Demo Mode\n{result['demo_note']}\n\n"
+        
+        status = "🎮 Demo mode - Simulation completed successfully" if DEMO_MODE else "✅ Video generation completed successfully"
+        
+        return output, status
+    
+    else:
+        error_output = f"""# ❌ Generation Failed
+
+## Error Details
+{result.get("error", "Unknown error occurred")}
+
+## 💡 Troubleshooting Tips
+1. **Check your topic**: Make sure it's a valid mathematical or scientific concept
+2. **Verify API keys**: Ensure your Gemini API keys are properly set
+3. **Try simpler topics**: Start with basic concepts like "velocity" or "pythagorean theorem"
+4. **Check context**: Make sure additional context is relevant and not too complex
+
+## 🔧 Common Issues
+- **API Rate Limits**: If using multiple API keys, the system will automatically rotate between them
+- **Complex Topics**: Very advanced topics might require more specific context
+- **Long Context**: Try shortening the additional context if it's very long
+"""
+        return error_output, "❌ Generation failed - Check the output for details"
+
+def get_example_topics():
+    """Get example topics with contexts for the interface.""" 
+    return [
+        ["Velocity", "Explain velocity in physics with detailed examples and real-world applications"],
+        ["Pythagorean Theorem", "Explain with visual proof and practical applications in construction and navigation"],
+        ["Derivatives", "Explain derivatives in calculus with geometric interpretation and rate of change examples"],
+        ["Newton's Laws", "Explain Newton's three laws of motion with everyday examples and demonstrations"],
+        ["Quadratic Formula", "Derive the quadratic formula step by step and show how to apply it"],
+        ["Logarithms", "Explain logarithms, their properties, and applications in science and engineering"],
+        ["Probability", "Explain basic probability concepts with coin flips, dice, and card examples"],
+        ["Trigonometry", "Explain sine, cosine, and tangent functions with unit circle visualization"],
+        ["Limits", "Explain the concept of limits in calculus with graphical examples"],
+        ["Chemical Bonding", "Explain ionic, covalent, and metallic bonding with molecular examples"]
+    ]
+
+def create_interface():
+    """Create and configure the Gradio interface."""
+    
+    setup_status = setup_environment()
+    init_status = initialize_video_generator()
+    
+    custom_css = """
+    .main-header {
+        text-align: center;
+        margin-bottom: 30px;
+        padding: 25px;
+        background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+        border-radius: 15px;
+        color: white;
+        box-shadow: 0 4px 15px rgba(0,0,0,0.1);
+    }
+    .status-box {
+        padding: 15px;
+        border-radius: 10px;
+        margin: 10px 0;
+        border-left: 4px solid #007bff;
+        background-color: #f8f9fa;
+    }
+    .demo-warning {
+        background: linear-gradient(135deg, #ffeaa7 0%, #fab1a0 100%);
+        border: none;
+        border-radius: 10px;
+        padding: 20px;
+        margin: 15px 0;
+        color: #2d3436;
+        font-weight: 500;
+        box-shadow: 0 2px 10px rgba(0,0,0,0.1);
+    }
+    """
+    
+    with gr.Blocks(
+        title="🎓 Theorem Explanation Agent",
+        theme=gr.themes.Soft(primary_hue="blue", secondary_hue="purple"),
+        css=custom_css
+    ) as demo:
+        
+        gr.HTML(f"""
+        <div class="main-header">
+            <h1>🎓 Theorem Explanation Agent</h1>
+            <p style="font-size: 18px; margin: 10px 0;">Generate educational videos explaining mathematical theorems and concepts using AI</p>
+            <p style="font-size: 14px; opacity: 0.9;">Powered by Gemini 2.0 Flash with automatic API key rotation</p>
+        </div>
+        """)
+        
+        if DEMO_MODE:
+            gr.HTML("""
+            <div class="demo-warning">
+                <h3>⚠️ Demo Mode Active</h3>
+                <p>This is a demonstration version. To enable full video generation:</p>
+                <ul>
+                    <li>Set your <code>GEMINI_API_KEY</code> in the Secrets tab (supports comma-separated multiple keys)</li>
+                    <li>Optionally set <code>ELEVENLABS_API_KEY</code> for voice narration</li>
+                    <li>Set <code>DEMO_MODE=false</code> in environment variables</li>
+                </ul>
+            </div>
+            """)
+        
+        with gr.Row():
+            with gr.Column(scale=3):
+                gr.HTML("<h3>📝 Video Generation Settings</h3>")
+                
+                topic_input = gr.Textbox(
+                    label="🎯 Topic to Explain",
+                    placeholder="Enter the topic you want to explain (e.g., 'velocity', 'pythagorean theorem')",
+                    lines=1,
+                    max_lines=2
+                )
+                
+                context_input = gr.Textbox(
+                    label="📝 Additional Context (Optional)",
+                    placeholder="Provide specific requirements, difficulty level, or focus areas for the explanation",
+                    lines=3,
+                    max_lines=5
+                )
+                
+                max_scenes_slider = gr.Slider(
+                    label="🎬 Maximum Number of Scenes",
+                    minimum=1,
+                    maximum=6,
+                    value=3,
+                    step=1,
+                    info="More scenes = longer video but higher cost"
+                )
+                
+                generate_btn = gr.Button(
+                    "🚀 Generate Video",
+                    variant="primary",
+                    size="lg"
+                )
+                
+            with gr.Column(scale=2):
+                gr.HTML("<h3>📊 Status & Information</h3>")
+                
+                status_display = gr.Textbox(
+                    label="🔄 Current Status",
+                    value=init_status,
+                    interactive=False,
+                    lines=2
+                )
+                
+                gr.HTML("""
+                <div class="status-box">
+                    <h4>🔑 API Key Setup for Hugging Face Spaces</h4>
+                    <p><strong>Multiple Gemini Keys (Recommended):</strong></p>
+                    <code>GEMINI_API_KEY=key1,key2,key3,key4</code>
+                    <p><strong>Single Key:</strong></p>
+                    <code>GEMINI_API_KEY=your_single_api_key</code>
+                    <p><strong>Optional TTS:</strong></p>
+                    <code>ELEVENLABS_API_KEY=your_elevenlabs_key</code>
+                    <br><br>
+                    <small>💡 The system automatically rotates between multiple keys to avoid rate limits</small>
+                </div>
+                """)
+        
+        examples = gr.Examples(
+            examples=get_example_topics(),
+            inputs=[topic_input, context_input],
+            label="📚 Example Topics & Contexts"
+        )
+        
+        output_display = gr.Markdown(
+            label="📋 Generation Results",
+            value="Ready to generate your first video! Enter a topic above and click 'Generate Video'."
+        )
+        
+        generate_btn.click(
+            fn=generate_video_gradio,
+            inputs=[topic_input, context_input, max_scenes_slider],
+            outputs=[output_display, status_display],
+            show_progress=True
+        )
+        
+        gr.HTML("""
+        <div style="text-align: center; padding: 20px; margin-top: 30px; border-top: 1px solid #eee;">
+            <p>🎓 <strong>Theorem Explanation Agent</strong></p>
+            <p>Built with ❤️ using Gradio, Gemini 2.0 Flash, and Manim</p>
+            <p style="font-size: 12px; color: #666;">
+                For support and updates, visit the project repository • 
+                Rate limits automatically managed with multi-key rotation
+            </p>
+        </div>
+        """)
+    
+    return demo
+
+if __name__ == "__main__":
+    demo = create_interface()
+    demo.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        share=False,
+        show_error=True,
+        show_tips=True,
+        enable_queue=True,
+        max_threads=10
+    ) 

huggingface_spaces_app.py

@@ -0,0 +1,282 @@
+#!/usr/bin/env python3
+"""
+Theorem Explanation Agent - Gradio Interface for Hugging Face Spaces
+"""
+
+import os
+import sys
+import json
+import asyncio
+import time
+import random
+from typing import Dict, Any, Tuple
+from pathlib import Path
+import gradio as gr
+
+# Add project root to path
+project_root = Path(__file__).parent
+sys.path.insert(0, str(project_root))
+
+# Environment setup
+DEMO_MODE = os.getenv("DEMO_MODE", "true").lower() == "true"
+video_generator = None
+CAN_IMPORT_DEPENDENCIES = True
+
+def setup_environment():
+    """Setup environment for HF Spaces."""
+    print("🚀 Setting up Theorem Explanation Agent...")
+    
+    gemini_keys = os.getenv("GEMINI_API_KEY", "")
+    if gemini_keys:
+        key_count = len([k.strip() for k in gemini_keys.split(',') if k.strip()])
+        print(f"✅ Found {key_count} Gemini API key(s)")
+        return True
+    else:
+        print("⚠️ No Gemini API keys found - running in demo mode")
+        return False
+
+def initialize_video_generator():
+    """Initialize video generator."""
+    global video_generator, CAN_IMPORT_DEPENDENCIES
+    
+    try:
+        if DEMO_MODE:
+            return "✅ Demo mode enabled"
+        
+        from generate_video import VideoGenerator
+        from mllm_tools.litellm import LiteLLMWrapper
+        
+        planner_model = LiteLLMWrapper(
+            model_name="gemini/gemini-2.0-flash",
+            temperature=0.7,
+            print_cost=True,
+            verbose=False,
+            use_langfuse=False
+        )
+        
+        video_generator = VideoGenerator(
+            planner_model=planner_model,  
+            helper_model=planner_model,
+            scene_model=planner_model,
+            output_dir="output",
+            use_rag=False,
+            use_context_learning=False,
+            use_visual_fix_code=False,
+            verbose=False
+        )
+        
+        return "✅ Video generator initialized"
+        
+    except Exception as e:
+        CAN_IMPORT_DEPENDENCIES = False
+        return f"⚠️ Running in demo mode: {str(e)}"
+
+def simulate_video_generation(topic: str, context: str, max_scenes: int, progress_callback=None):
+    """Simulate video generation."""
+    stages = [
+        ("🔍 Analyzing topic", 15),
+        ("📝 Planning structure", 30),
+        ("🎬 Generating scenes", 50),
+        ("✨ Creating animations", 75),
+        ("🎥 Rendering video", 90),
+        ("✅ Finalizing", 100)
+    ]
+    
+    results = []
+    for stage, progress in stages:
+        if progress_callback:
+            progress_callback(progress, stage)
+        time.sleep(random.uniform(0.3, 0.7))
+        results.append(f"• {stage}")
+    
+    return {
+        "success": True,
+        "message": f"Demo video generated for: {topic}",
+        "scenes_created": max_scenes,
+        "processing_steps": results,
+        "demo_note": "This is a simulation for demo purposes."
+    }
+
+async def generate_video_async(topic: str, context: str, max_scenes: int, progress_callback=None):
+    """Generate video asynchronously."""
+    global video_generator
+    
+    if not topic.strip():
+        return {"success": False, "error": "Please enter a topic"}
+    
+    try:
+        if DEMO_MODE or not CAN_IMPORT_DEPENDENCIES:
+            return simulate_video_generation(topic, context, max_scenes, progress_callback)
+        
+        if progress_callback:
+            progress_callback(10, "🚀 Starting generation...")
+        
+        result = await video_generator.generate_video_pipeline(
+            topic=topic,
+            description=context,
+            max_retries=3,
+            only_plan=False,
+            specific_scenes=list(range(1, max_scenes + 1))
+        )
+        
+        if progress_callback:
+            progress_callback(100, "✅ Completed!")
+        
+        return {"success": True, "message": f"Video generated for: {topic}", "result": result}
+        
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+def generate_video_gradio(topic: str, context: str, max_scenes: int, progress=gr.Progress()) -> Tuple[str, str]:
+    """Main Gradio function."""
+    def progress_callback(percent, message):
+        progress(percent / 100, desc=message)
+    
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    
+    try:
+        result = loop.run_until_complete(
+            generate_video_async(topic, context, max_scenes, progress_callback)
+        )
+    finally:
+        loop.close()
+    
+    if result["success"]:
+        output = f"""# 🎓 Video Generation Complete!
+
+**Topic:** {topic}
+**Context:** {context if context else "None"}
+**Scenes:** {max_scenes}
+
+## ✅ Result
+{result["message"]}
+
+"""
+        if "processing_steps" in result:
+            output += "## 🔄 Steps\n"
+            for step in result["processing_steps"]:
+                output += f"{step}\n"
+        
+        if "demo_note" in result:
+            output += f"\n⚠️ **{result['demo_note']}**"
+        
+        status = "🎮 Demo completed" if DEMO_MODE else "✅ Generation completed"
+        return output, status
+    
+    else:
+        error_output = f"""# ❌ Generation Failed
+
+{result.get("error", "Unknown error")}
+
+## 💡 Tips
+- Check topic validity
+- Verify API keys
+- Try simpler topics
+"""
+        return error_output, "❌ Failed"
+
+def get_examples():
+    """Example topics."""
+    return [
+        ["Velocity", "Physics concept with real-world examples"],
+        ["Pythagorean Theorem", "Mathematical proof with applications"],
+        ["Derivatives", "Calculus concept with geometric interpretation"],
+        ["Newton's Laws", "Three laws of motion with demonstrations"],
+        ["Quadratic Formula", "Step-by-step derivation and usage"]
+    ]
+
+def create_interface():
+    """Create Gradio interface."""
+    setup_environment()
+    init_status = initialize_video_generator()
+    
+    with gr.Blocks(
+        title="🎓 Theorem Explanation Agent",
+        theme=gr.themes.Soft()
+    ) as demo:
+        
+        gr.HTML("""
+        <div style="text-align: center; padding: 20px; background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); border-radius: 10px; color: white; margin-bottom: 20px;">
+            <h1>🎓 Theorem Explanation Agent</h1>
+            <p>Generate educational videos using AI</p>
+        </div>
+        """)
+        
+        if DEMO_MODE:
+            gr.HTML("""
+            <div style="background: #fff3cd; padding: 15px; border-radius: 5px; margin: 10px 0;">
+                <h3>⚠️ Demo Mode</h3>
+                <p>To enable full functionality:</p>
+                <ul>
+                    <li>Set <code>GEMINI_API_KEY</code> (supports comma-separated keys)</li>
+                    <li>Set <code>DEMO_MODE=false</code></li>
+                </ul>
+            </div>
+            """)
+        
+        with gr.Row():
+            with gr.Column():
+                topic_input = gr.Textbox(
+                    label="Topic",
+                    placeholder="e.g., velocity, pythagorean theorem"
+                )
+                
+                context_input = gr.Textbox(
+                    label="Context (Optional)",
+                    placeholder="Additional details or requirements",
+                    lines=3
+                )
+                
+                max_scenes_slider = gr.Slider(
+                    label="Max Scenes",
+                    minimum=1,
+                    maximum=6,
+                    value=3,
+                    step=1
+                )
+                
+                generate_btn = gr.Button("🚀 Generate Video", variant="primary")
+                
+            with gr.Column():
+                status_display = gr.Textbox(
+                    label="Status",
+                    value=init_status,
+                    interactive=False
+                )
+                
+                gr.HTML("""
+                <div style="background: #f8f9fa; padding: 15px; border-radius: 5px;">
+                    <h4>🔑 API Setup</h4>
+                    <p><strong>Multiple keys:</strong></p>
+                    <code>GEMINI_API_KEY=key1,key2,key3</code>
+                    <p><strong>Single key:</strong></p>
+                    <code>GEMINI_API_KEY=your_key</code>
+                </div>
+                """)
+        
+        examples = gr.Examples(
+            examples=get_examples(),
+            inputs=[topic_input, context_input]
+        )
+        
+        output_display = gr.Markdown(
+            value="Ready to generate! Enter a topic and click Generate."
+        )
+        
+        generate_btn.click(
+            fn=generate_video_gradio,
+            inputs=[topic_input, context_input, max_scenes_slider],
+            outputs=[output_display, status_display],
+            show_progress=True
+        )
+    
+    return demo
+
+if __name__ == "__main__":
+    demo = create_interface()
+    demo.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        share=False
+    ) 

requirements.txt

@@ -1,4 +1,5 @@
 # Essential dependencies for Gradio interface
+gradio==4.44.0
 python-dotenv>=0.19.0
 requests>=2.25.0
 numpy>=1.21.0

requirements_hf.txt

@@ -0,0 +1,25 @@
+# Core dependencies for Hugging Face Spaces
+gradio==4.44.0
+python-dotenv>=0.19.0
+requests>=2.25.0
+numpy>=1.21.0
+
+# AI/ML dependencies
+litellm>=1.0.0
+google-generativeai>=0.8.0
+
+# Image processing (required for video generation)
+pillow>=8.3.0
+
+# Audio processing (optional, for TTS)
+elevenlabs>=1.0.0
+
+# Utility libraries
+tqdm>=4.62.0
+
+# Optional dependencies for full functionality
+# These will be installed if available, but the app will work without them
+manim; python_version>="3.8"
+pydub>=0.25.0; python_version>="3.8"
+moviepy>=1.0.3; python_version>="3.8"
+soundfile>=0.12.0; python_version>="3.8" 

src/core/code_generator.py

@@ -469,6 +469,84 @@ class CodeGenerator:
                 fixed_code
             )
         
+        # Fix 5: Array comparison ambiguity with get_bottom(), get_top(), etc.
+        if "The truth value of an array with more than one element is ambiguous" in error:
+            import re
+            # Fix comparisons like obj.get_bottom() < value to use numpy array indexing
+            patterns = [
+                (r'(\w+)\.get_bottom\(\)\s*([<>]=?)\s*(-?\d+\.?\d*)', r'\1.get_bottom()[1] \2 \3'),
+                (r'(\w+)\.get_top\(\)\s*([<>]=?)\s*(-?\d+\.?\d*)', r'\1.get_top()[1] \2 \3'),
+                (r'(\w+)\.get_left\(\)\s*([<>]=?)\s*(-?\d+\.?\d*)', r'\1.get_left()[0] \2 \3'),
+                (r'(\w+)\.get_right\(\)\s*([<>]=?)\s*(-?\d+\.?\d*)', r'\1.get_right()[0] \2 \3'),
+            ]
+            for pattern, replacement in patterns:
+                fixed_code = re.sub(pattern, replacement, fixed_code)
+        
+        # Fix 6: Missing SVG files - replace with basic shapes
+        if "could not find" in error and ".svg" in error:
+            import re
+            # Replace SVGMobject with Rectangle for missing SVG files
+            svg_patterns = [
+                (r'SVGMobject\("car\.svg"\)', 'Rectangle(height=0.5, width=1.0, color=BLUE)'),
+                (r'SVGMobject\("arrow\.svg"\)', 'Arrow(start=ORIGIN, end=RIGHT, color=RED)'),
+                (r'SVGMobject\("([^"]+\.svg)"\)', r'Rectangle(height=0.5, width=0.5, color=YELLOW)  # Replaced missing \1'),
+            ]
+            for pattern, replacement in svg_patterns:
+                fixed_code = re.sub(pattern, replacement, fixed_code)
+        
+        # Fix 7: Non-existent Manim classes/functions
+        if "is not defined" in error or "cannot import name" in error:
+            import re
+            # Replace non-existent Manim functions with working alternatives
+            replacements = [
+                (r'Surround\(([^)]+)\)', r'Circumscribe(\1)'),  # Surround doesn't exist, use Circumscribe
+                (r'from manim import \*, Surround', 'from manim import *'),  # Remove invalid import
+                (r'from manim import Surround[^\n]*\n', ''),  # Remove Surround import line
+            ]
+            for pattern, replacement in replacements:
+                fixed_code = re.sub(pattern, replacement, fixed_code)
+        
+        # Fix 8: Config frame attribute errors  
+        if "'ManimMLConfig' object has no attribute 'frame_width'" in error or \
+           "'ManimMLConfig' object has no attribute 'frame_height'" in error:
+            # Replace config frame access with hardcoded values
+            fixed_code = fixed_code.replace(
+                'config.frame_width', '14.0'
+            ).replace(
+                'config.frame_height', '8.0'
+            ).replace(
+                '-config.frame_width / 2', '-7.0'
+            ).replace(
+                'config.frame_width / 2', '7.0'
+            ).replace(
+                '-config.frame_height / 2', '-4.0'
+            ).replace(
+                'config.frame_height / 2', '4.0'
+            )
+        
+        # Fix 9: Transform animation issues with function objects
+        if "object of type 'function' has no len()" in error and "Transform" in code:
+            import re
+            # Fix Transform calls with .animate that should use the object directly
+            fixed_code = re.sub(
+                r'Transform\((\w+), \1\.animate\.([^)]+)\)',
+                r'self.play(\1.animate.\2)',
+                fixed_code
+            )
+            # Also fix incorrect Transform usage
+            fixed_code = re.sub(
+                r'self\.play\(Transform\(([^,]+), ([^)]+)\.animate\.([^)]+)\)\)',
+                r'self.play(\2.animate.\3)',
+                fixed_code
+            )
+        
+        # Fix 10: Syntax errors with import statements
+        if "invalid syntax" in error and "import" in error:
+            import re
+            # Fix malformed import statements
+            fixed_code = re.sub(r'from manim import \*, (\w+)', r'from manim import *', fixed_code)
+            fixed_code = re.sub(r'from manim import \*,', 'from manim import *', fixed_code)
+        
         return fixed_code
 
     def visual_self_reflection(self, code: str, media_path: Union[str, Image.Image], scene_trace_id: str, topic: str, scene_number: int, session_id: str) -> str:

src/core/video_planner.py

@@ -7,7 +7,7 @@ import uuid
 import asyncio
 
 from mllm_tools.utils import _prepare_text_inputs
-from src.utils.utils import extract_xml
+from src.utils.utils import extract_xml, extract_xml_tag
 from task_generator import (
     get_prompt_scene_plan,
     get_prompt_scene_vision_storyboard,
@@ -162,16 +162,25 @@ class VideoPlanner:
             _prepare_text_inputs(prompt),
             metadata={"generation_name": "scene_outline", "tags": [topic, "scene-outline"], "session_id": session_id}
         )
-        # extract scene outline <SCENE_OUTLINE> ... </SCENE_OUTLINE>
-        scene_outline_match = re.search(r'(<SCENE_OUTLINE>.*?</SCENE_OUTLINE>)', response_text, re.DOTALL)
-        scene_outline = scene_outline_match.group(1) if scene_outline_match else response_text
-
-        # replace all spaces and special characters with underscores for file path compatibility
+        
+        # Extract scene outline <SCENE_OUTLINE> ... </SCENE_OUTLINE>
+        scene_outline = extract_xml_tag(response_text, "SCENE_OUTLINE")
+        if not scene_outline:
+            print("⚠️  Warning: Could not find <SCENE_OUTLINE> tags. Returning full response.")
+            # Fallback to returning the full text if tags are missing, after logging a warning.
+            scene_outline = response_text
+
+        # Create a file-safe prefix for the topic
         file_prefix = topic.lower()
         file_prefix = re.sub(r'[^a-z0-9_]+', '_', file_prefix)
-        outline_path = os.path.join(self.output_dir, file_prefix, "scene_outline.txt")
+        
+        # Ensure the directory exists
+        topic_dir = os.path.join(self.output_dir, file_prefix)
+        os.makedirs(topic_dir, exist_ok=True)
+        
+        outline_path = os.path.join(topic_dir, "scene_outline.txt")
 
-        # Save the scene outline to a file
+        # Save the processed (extracted) scene outline to a file
         with open(outline_path, 'w', encoding='utf-8') as f:
             f.write(scene_outline)
 

src/utils/utils.py

@@ -126,3 +126,19 @@ def extract_xml(response: str) -> str:
         return re.search(r'```xml\n(.*?)\n```', response, re.DOTALL).group(1)
     except:
         return response
+
+def extract_xml_tag(response: str, tag_name: str) -> str:
+    """Extract content between specific XML tags from a text response.
+
+    Extracts content between XML tags like <TAG_NAME>...</TAG_NAME>.
+
+    Args:
+        response (str): The text response containing XML content
+        tag_name (str): The name of the XML tag to extract (without angle brackets)
+
+    Returns:
+        str: The extracted content between the XML tags, or empty string if not found
+    """
+    pattern = f'<{tag_name}>(.*?)</{tag_name}>'
+    match = re.search(pattern, response, re.DOTALL)
+    return match.group(1).strip() if match else ""

test_api_keys.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+"""
+Test script to validate API keys for TheoremExplainAgent
+Usage: python test_api_keys.py
+"""
+
+import os
+import sys
+from dotenv import load_dotenv
+
+def test_gemini_api():
+    """Test Gemini API key(s)"""
+    print("Testing Gemini API...")
+    
+    try:
+        import google.generativeai as genai
+        import random
+        
+        # Load environment variables
+        load_dotenv()
+        
+        # Get API key with fallback support
+        gemini_key_env = os.getenv("GEMINI_API_KEY") or os.getenv("GOOGLE_API_KEY")
+        if not gemini_key_env:
+            print("❌ No GEMINI_API_KEY found in environment")
+            print("   Please set GEMINI_API_KEY in your .env file")
+            print("   Get your API key from: https://aistudio.google.com/app/apikey")
+            return False
+        
+        # Handle multiple keys
+        if ',' in gemini_key_env:
+            keys = [key.strip() for key in gemini_key_env.split(',') if key.strip()]
+            print(f"   Found {len(keys)} API keys to test")
+            api_key = random.choice(keys)
+            print(f"   Testing random key: {api_key[:20]}...")
+        else:
+            api_key = gemini_key_env
+            print(f"   Testing key: {api_key[:20]}...")
+        
+        # Configure and test
+        genai.configure(api_key=api_key)
+        model = genai.GenerativeModel('gemini-1.5-pro')
+        
+        # Simple test
+        response = model.generate_content("Say hello in one word")
+        print(f"✅ Gemini API works! Response: {response.text.strip()}")
+        return True
+        
+    except Exception as e:
+        print(f"❌ Gemini API test failed: {e}")
+        return False
+
+def test_elevenlabs_api():
+    """Test ElevenLabs API key"""
+    print("\nTesting ElevenLabs API...")
+    
+    try:
+        import requests
+        
+        # Load environment variables
+        load_dotenv()
+        
+        api_key = os.getenv("ELEVENLABS_API_KEY")
+        if not api_key:
+            print("❌ No ELEVENLABS_API_KEY found in environment")
+            print("   Please set ELEVENLABS_API_KEY in your .env file")
+            print("   Get your API key from: https://elevenlabs.io/app/settings/api-keys")
+            return False
+        
+        print(f"   Testing key: {api_key[:20]}...")
+        
+        # Test API with a simple request
+        headers = {
+            "Accept": "application/json",
+            "xi-api-key": api_key
+        }
+        
+        response = requests.get("https://api.elevenlabs.io/v1/user", headers=headers)
+        
+        if response.status_code == 200:
+            user_data = response.json()
+            print(f"✅ ElevenLabs API works! User: {user_data.get('email', 'Unknown')}")
+            return True
+        else:
+            print(f"❌ ElevenLabs API test failed: {response.status_code} - {response.text}")
+            return False
+            
+    except Exception as e:
+        print(f"❌ ElevenLabs API test failed: {e}")
+        return False
+
+def main():
+    """Main test function"""
+    print("🔍 Testing API Keys for TheoremExplainAgent\n")
+    
+    # Check if .env file exists
+    if not os.path.exists('.env'):
+        print("❌ No .env file found!")
+        print("   Please create a .env file based on .env.template")
+        print("   Run: cp .env.template .env")
+        return
+    
+    gemini_ok = test_gemini_api()
+    elevenlabs_ok = test_elevenlabs_api()
+    
+    print("\n" + "="*50)
+    if gemini_ok and elevenlabs_ok:
+        print("✅ All API keys are working correctly!")
+        print("   You can now run generate_video.py")
+    elif gemini_ok:
+        print("⚠️  Gemini API works, but ElevenLabs API failed")
+        print("   Video generation will work but TTS might fail")
+    elif elevenlabs_ok:
+        print("⚠️  ElevenLabs API works, but Gemini API failed")
+        print("   TTS will work but video generation will fail")
+    else:
+        print("❌ Both API keys failed")
+        print("   Please check your .env file and API keys")
+
+if __name__ == "__main__":
+    main() 

test_gemini_only.py

@@ -0,0 +1,20 @@
+import os
+from dotenv import load_dotenv
+import google.generativeai as genai
+import random
+
+load_dotenv()
+
+gemini_key_env = os.getenv('GEMINI_API_KEY')
+if ',' in gemini_key_env:
+    keys = [key.strip() for key in gemini_key_env.split(',') if key.strip()]
+    api_key = random.choice(keys)
+    print(f"Selected random key: {api_key[:20]}...")
+else:
+    api_key = gemini_key_env
+    print(f"Using single key: {api_key[:20]}...")
+
+genai.configure(api_key=api_key)
+model = genai.GenerativeModel('gemini-1.5-pro')
+response = model.generate_content('Say hello in one word')
+print(f'Success! Response: {response.text.strip()}')