Complete NeuroAnim HF Spaces deployment - all source files

.gitignore

@@ -0,0 +1,43 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+venv/
+env/
+
+# Environment variables (IMPORTANT: Never commit API keys!)
+.env
+
+# Docker
+*.bak
+
+# Sandbox deployment artifacts
+.docker/
+
+# Output files
+outputs/
+animations/
+test_output/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+.env
+.env.*
+.txt
+
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log

README.md

@@ -0,0 +1,101 @@
+---
+title: NeuroAnim - STEM Animation Generator
+emoji: 🧠
+colorFrom: blue
+colorTo: purple
+sdk: gradio
+sdk_version: 6.0.1
+app_file: app.py
+pinned: false
+license: mit
+---
+
+# 🧠 NeuroAnim - AI-Powered Educational Animation Generator
+
+NeuroAnim is an AI-powered system that automatically generates educational STEM animations with narration and quiz questions. Simply enter a topic, and watch as AI creates a complete animated video!
+
+## 🎯 Features
+
+- **🎨 Automatic Animation Generation**: Creates professional Manim animations from topic descriptions
+- **🗣️ AI Narration**: Generates educational narration scripts tailored to your audience
+- **🔊 Text-to-Speech**: Converts narration to high-quality audio
+- **📹 Video Production**: Renders and merges video with synchronized audio
+- **❓ Quiz Generation**: Creates assessment questions to test understanding
+- **🎓 Multi-Level Support**: Content appropriate for elementary through PhD levels
+
+## 🚀 How to Use
+
+1. **Enter a Topic**: Type any STEM concept (e.g., "Pythagorean Theorem", "Photosynthesis", "Newton's Laws")
+2. **Select Audience**: Choose the appropriate education level
+3. **Set Duration**: Pick animation length (0.5-10 minutes)
+4. **Choose Quality**: Select video quality (higher = slower but better)
+5. **Generate**: Click the button and wait for your animation!
+
+## 💡 Example Topics
+
+- **Mathematics**: Pythagorean Theorem, Quadratic Formula, Circle Area Derivation
+- **Physics**: Newton's Laws, Laws of Motion, Wave Properties
+- **Biology**: Photosynthesis, Cell Division, DNA Structure
+- **Computer Science**: Binary Numbers, Sorting Algorithms, Data Structures
+
+## 🔧 Technology Stack
+
+- **Manim Community Edition**: Mathematical animation engine
+- **Hugging Face Models**: AI-powered content generation
+- **ElevenLabs**: High-quality text-to-speech synthesis
+- **Blaxel**: Cloud-based secure rendering
+- **Gradio**: Interactive web interface
+
+## 🔑 Setup Requirements
+
+To run this space, you need:
+
+1. **Hugging Face API Key**: For AI content generation (required)
+2. **ElevenLabs API Key**: For high-quality TTS (optional, falls back to HF TTS)
+3. **Blaxel API Key**: For cloud rendering (optional, can use local rendering)
+
+Set these as **Secrets** in your Hugging Face Space settings:
+- `HUGGINGFACE_API_KEY`
+- `ELEVENLABS_API_KEY` (optional)
+- `BLAXEL_API_KEY` (optional)
+- `MANIM_SANDBOX_IMAGE` (optional, for Blaxel cloud rendering)
+
+## 📝 Tips for Best Results
+
+- **Be Specific**: Instead of "math", try "solving linear equations" or "area of a circle"
+- **Choose Right Audience**: Match the complexity level to your target viewers
+- **Optimal Duration**: 1.5-3 minutes works best for most concepts
+- **Review Generated Content**: Check the narration and code tabs to see what was created
+
+## 🎬 How It Works
+
+1. **Concept Planning**: AI analyzes your topic and creates an educational plan
+2. **Script Writing**: Generates age-appropriate narration aligned with learning objectives
+3. **Code Generation**: Creates Manim Python code for visual representation
+4. **Rendering**: Executes Manim to produce the base animation
+5. **Audio Synthesis**: Converts narration to speech using TTS
+6. **Final Production**: Merges video and audio into complete animation
+7. **Assessment**: Generates quiz questions for the content
+
+## 📚 Use Cases
+
+- **Teachers**: Create engaging lesson materials
+- **Students**: Visualize complex concepts for better understanding
+- **Content Creators**: Produce educational YouTube/social media content
+- **Tutors**: Generate custom explanations for specific topics
+- **Course Developers**: Build comprehensive educational video libraries
+
+## 🤝 Contributing
+
+NeuroAnim is open source! Visit the [GitHub repository](https://github.com/yourusername/manim-agent) to:
+- Report bugs or suggest features
+- Submit pull requests with improvements
+- Share your generated animations
+
+## 📄 License
+
+MIT License - Free to use for educational and commercial purposes
+
+---
+
+Made with ❤️ for educational content creation

README_HF.md

@@ -0,0 +1,101 @@
+---
+title: NeuroAnim - STEM Animation Generator
+emoji: 🧠
+colorFrom: blue
+colorTo: purple
+sdk: gradio
+sdk_version: 6.0.1
+app_file: app.py
+pinned: false
+license: mit
+---
+
+# 🧠 NeuroAnim - AI-Powered Educational Animation Generator
+
+NeuroAnim is an AI-powered system that automatically generates educational STEM animations with narration and quiz questions. Simply enter a topic, and watch as AI creates a complete animated video!
+
+## 🎯 Features
+
+- **🎨 Automatic Animation Generation**: Creates professional Manim animations from topic descriptions
+- **🗣️ AI Narration**: Generates educational narration scripts tailored to your audience
+- **🔊 Text-to-Speech**: Converts narration to high-quality audio
+- **📹 Video Production**: Renders and merges video with synchronized audio
+- **❓ Quiz Generation**: Creates assessment questions to test understanding
+- **🎓 Multi-Level Support**: Content appropriate for elementary through PhD levels
+
+## 🚀 How to Use
+
+1. **Enter a Topic**: Type any STEM concept (e.g., "Pythagorean Theorem", "Photosynthesis", "Newton's Laws")
+2. **Select Audience**: Choose the appropriate education level
+3. **Set Duration**: Pick animation length (0.5-10 minutes)
+4. **Choose Quality**: Select video quality (higher = slower but better)
+5. **Generate**: Click the button and wait for your animation!
+
+## 💡 Example Topics
+
+- **Mathematics**: Pythagorean Theorem, Quadratic Formula, Circle Area Derivation
+- **Physics**: Newton's Laws, Laws of Motion, Wave Properties
+- **Biology**: Photosynthesis, Cell Division, DNA Structure
+- **Computer Science**: Binary Numbers, Sorting Algorithms, Data Structures
+
+## 🔧 Technology Stack
+
+- **Manim Community Edition**: Mathematical animation engine
+- **Hugging Face Models**: AI-powered content generation
+- **ElevenLabs**: High-quality text-to-speech synthesis
+- **Blaxel**: Cloud-based secure rendering
+- **Gradio**: Interactive web interface
+
+## 🔑 Setup Requirements
+
+To run this space, you need:
+
+1. **Hugging Face API Key**: For AI content generation (required)
+2. **ElevenLabs API Key**: For high-quality TTS (optional, falls back to HF TTS)
+3. **Blaxel API Key**: For cloud rendering (optional, can use local rendering)
+
+Set these as **Secrets** in your Hugging Face Space settings:
+- `HUGGINGFACE_API_KEY`
+- `ELEVENLABS_API_KEY` (optional)
+- `BLAXEL_API_KEY` (optional)
+- `MANIM_SANDBOX_IMAGE` (optional, for Blaxel cloud rendering)
+
+## 📝 Tips for Best Results
+
+- **Be Specific**: Instead of "math", try "solving linear equations" or "area of a circle"
+- **Choose Right Audience**: Match the complexity level to your target viewers
+- **Optimal Duration**: 1.5-3 minutes works best for most concepts
+- **Review Generated Content**: Check the narration and code tabs to see what was created
+
+## 🎬 How It Works
+
+1. **Concept Planning**: AI analyzes your topic and creates an educational plan
+2. **Script Writing**: Generates age-appropriate narration aligned with learning objectives
+3. **Code Generation**: Creates Manim Python code for visual representation
+4. **Rendering**: Executes Manim to produce the base animation
+5. **Audio Synthesis**: Converts narration to speech using TTS
+6. **Final Production**: Merges video and audio into complete animation
+7. **Assessment**: Generates quiz questions for the content
+
+## 📚 Use Cases
+
+- **Teachers**: Create engaging lesson materials
+- **Students**: Visualize complex concepts for better understanding
+- **Content Creators**: Produce educational YouTube/social media content
+- **Tutors**: Generate custom explanations for specific topics
+- **Course Developers**: Build comprehensive educational video libraries
+
+## 🤝 Contributing
+
+NeuroAnim is open source! Visit the [GitHub repository](https://github.com/yourusername/manim-agent) to:
+- Report bugs or suggest features
+- Submit pull requests with improvements
+- Share your generated animations
+
+## 📄 License
+
+MIT License - Free to use for educational and commercial purposes
+
+---
+
+Made with ❤️ for educational content creation

app.py

@@ -0,0 +1,661 @@
+#!/usr/bin/env python3
+"""
+NeuroAnim Gradio Web Interface
+
+A comprehensive web UI for generating educational STEM animations with:
+- Topic input and configuration
+- Real-time progress tracking
+- Video preview and download
+- Generated content display (narration, code, quiz)
+- Error handling and logging
+"""
+
+import asyncio
+import logging
+import os
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, Optional, Tuple
+
+import gradio as gr
+from dotenv import load_dotenv
+
+from orchestrator import NeuroAnimOrchestrator
+
+load_dotenv()
+
+# Set up logging
+logging.basicConfig(
+    level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+)
+logger = logging.getLogger(__name__)
+
+
+def format_quiz_markdown(quiz_text: str) -> str:
+    """Format quiz text into a nice markdown display."""
+    if not quiz_text or quiz_text == "Not available":
+        return "❓ No quiz generated yet."
+
+    # If it's already formatted or looks good, return as is with some styling
+    formatted = f"## 📝 Assessment Questions\n\n{quiz_text}"
+
+    # Try to add some structure if it's plain text
+    lines = quiz_text.split("\n")
+    formatted_lines = []
+    question_num = 0
+
+    for line in lines:
+        line = line.strip()
+        if not line:
+            formatted_lines.append("")
+            continue
+
+        # Detect question patterns
+        if line.lower().startswith(("q:", "question", "q.", f"{question_num + 1}.")):
+            question_num += 1
+            formatted_lines.append(f"\n### Question {question_num}")
+            # Remove the question prefix
+            clean_line = line.split(":", 1)[-1].strip() if ":" in line else line
+            formatted_lines.append(f"**{clean_line}**\n")
+        elif line.lower().startswith(("a)", "b)", "c)", "d)", "a.", "b.", "c.", "d.")):
+            # Format multiple choice options
+            formatted_lines.append(f"- {line}")
+        elif line.lower().startswith(("answer:", "a:", "correct:")):
+            # Format answers
+            formatted_lines.append(f"\n> ✅ {line}\n")
+        else:
+            formatted_lines.append(line)
+
+    # If we detected structure, use the formatted version
+    if question_num > 0:
+        return "## 📝 Assessment Questions\n\n" + "\n".join(formatted_lines)
+
+    # Otherwise return with basic formatting
+    return formatted
+
+
+class NeuroAnimApp:
+    """Main application class for Gradio interface."""
+
+    def __init__(self):
+        self.orchestrator: Optional[NeuroAnimOrchestrator] = None
+        self.current_task: Optional[asyncio.Task] = None
+        self.is_generating = False
+        self.event_loop: Optional[asyncio.AbstractEventLoop] = None
+        self.current_progress = None  # Store progress callback for dynamic updates
+
+    async def initialize_orchestrator(self):
+        """Initialize the orchestrator if not already done."""
+        if self.orchestrator is None:
+            self.orchestrator = NeuroAnimOrchestrator()
+            await self.orchestrator.initialize()
+            logger.info("Orchestrator initialized successfully")
+
+    async def cleanup_orchestrator(self):
+        """Clean up orchestrator resources."""
+        if self.orchestrator is not None:
+            await self.orchestrator.cleanup()
+            self.orchestrator = None
+            logger.info("Orchestrator cleaned up")
+    
+    def cleanup_event_loop(self):
+        """Clean up the event loop on application shutdown."""
+        if self.event_loop is not None and not self.event_loop.is_closed():
+            self.event_loop.close()
+            self.event_loop = None
+            logger.info("Event loop closed")
+
+    async def generate_animation_async(
+        self, topic: str, audience: str, duration: float, quality: str, progress=gr.Progress()
+    ) -> Dict[str, Any]:
+        """
+        Generate animation with progress tracking.
+
+        Args:
+            topic: STEM topic to animate
+            audience: Target audience level
+            duration: Animation duration in minutes
+            quality: Video quality (low, medium, high, production_quality)
+            progress: Gradio progress tracker
+
+        Returns:
+            Results dictionary with generated content
+        """
+        try:
+            self.is_generating = True
+
+            # Validate inputs
+            if not topic or len(topic.strip()) < 3:
+                return {
+                    "success": False,
+                    "error": "Please provide a valid topic (at least 3 characters)",
+                }
+
+            if duration < 0.5 or duration > 10:
+                return {
+                    "success": False,
+                    "error": "Duration must be between 0.5 and 10 minutes",
+                }
+
+            # Initialize orchestrator
+            progress(0.05, desc="Initializing system...")
+            await self.initialize_orchestrator()
+
+            # Generate unique filename
+            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+            safe_topic = "".join(c if c.isalnum() else "_" for c in topic)[:30]
+            output_filename = f"{safe_topic}_{timestamp}.mp4"
+
+            # Map quality from UI to orchestrator format
+            quality_map = {
+                "Low (480p, faster)": "low",
+                "Medium (720p, balanced)": "medium",
+                "High (1080p, slower)": "high",
+                "Production (4K, slowest)": "production_quality",
+            }
+            quality_param = quality_map.get(quality, "medium")
+
+            # Map audience from UI to orchestrator format
+            audience_map = {
+                "elementary": "elementary",
+                "middle_school": "middle_school",
+                "high_school": "high_school",
+                "undergraduate": "college",  # Map to 'college' for LLM compatibility
+                "phd": "graduate",  # Map to 'graduate' for LLM compatibility
+                "general": "general",
+            }
+            audience_param = audience_map.get(audience, audience)
+
+            # Dynamic progress tracking with step-based updates
+            step_times = {}  # Track step start times
+            step_index = [0]  # Current step index
+            
+            steps = [
+                (0.1, "Planning concept"),
+                (0.25, "Generating narration script"),
+                (0.40, "Creating Manim animation code"),
+                (0.55, "Rendering animation video"),
+                (0.75, "Generating audio narration"),
+                (0.90, "Merging video and audio"),
+                (0.95, "Creating quiz questions"),
+            ]
+            
+            import time
+            
+            def progress_callback(step_name: str, step_progress: float):
+                """Callback for orchestrator to report progress."""
+                # Find matching step
+                for idx, (prog, desc) in enumerate(steps):
+                    if desc.lower() in step_name.lower():
+                        step_index[0] = idx
+                        
+                        # Track timing
+                        current_time = time.time()
+                        if step_name not in step_times:
+                            step_times[step_name] = current_time
+                        elapsed = current_time - step_times[step_name]
+                        
+                        # Add timing info for long steps
+                        if elapsed > 30:  # Show message if step takes more than 30s
+                            desc_with_time = f"{desc} (taking longer than usual, please wait...)"
+                        else:
+                            desc_with_time = f"{desc}..."
+                        
+                        progress(prog, desc=desc_with_time)
+                        return
+                
+                # If no match, use the provided progress directly
+                progress(step_progress, desc=f"{step_name}...")
+
+            # Start generation with dynamic progress
+            result = await self.orchestrator.generate_animation(
+                topic=topic,
+                target_audience=audience_param,
+                animation_length_minutes=duration,
+                output_filename=output_filename,
+                quality=quality_param,
+                progress_callback=progress_callback,
+            )
+            
+            progress(1.0, desc="Complete!")
+            logger.info("Async generation completed, returning result")
+
+            return result
+
+        except Exception as e:
+            logger.error(f"Generation failed: {e}", exc_info=True)
+            return {"success": False, "error": str(e)}
+        finally:
+            self.is_generating = False
+
+    def generate_animation_sync(
+        self, topic: str, audience: str, duration: float, quality: str, progress=gr.Progress()
+    ) -> Tuple[str, str, str, str, str, str]:
+        """
+        Synchronous wrapper for Gradio interface.
+
+        Returns:
+            Tuple of (video_path, status, narration, code, quiz, concept_plan)
+        """
+        try:
+            # Reuse existing event loop or create a persistent one
+            if self.event_loop is None or self.event_loop.is_closed():
+                self.event_loop = asyncio.new_event_loop()
+                asyncio.set_event_loop(self.event_loop)
+                logger.info("Created new persistent event loop")
+            else:
+                asyncio.set_event_loop(self.event_loop)
+                logger.info("Reusing existing event loop")
+
+            logger.info("Starting event loop execution...")
+            result = self.event_loop.run_until_complete(
+                self.generate_animation_async(topic, audience, duration, quality, progress)
+            )
+            logger.info("Event loop execution completed")
+            # DO NOT close the loop - keep it for subsequent generations
+
+            if result["success"]:
+                logger.info("Processing successful result...")
+                video_path = result["output_file"]
+                status = f"✅ **Animation Generated Successfully!**\n\n**Topic:** {result['topic']}\n**Audience:** {result['target_audience']}\n**Output:** {os.path.basename(video_path)}"
+                narration = result.get("narration", "Not available")
+                code = result.get("manim_code", "Not available")
+                quiz_raw = result.get("quiz", "Not available")
+                quiz = format_quiz_markdown(quiz_raw)
+                concept = result.get("concept_plan", "Not available")
+
+                logger.info(f"Returning result to Gradio: {video_path}")
+                return video_path, video_path, status, narration, code, quiz, concept
+            else:
+                error_msg = result.get("error", "Unknown error")
+                status = f"❌ **Generation Failed**\n\n{error_msg}"
+                return None, None, status, "", "", "", ""
+
+        except Exception as e:
+            logger.error(f"Sync wrapper error: {e}", exc_info=True)
+            status = f"💥 **Unexpected Error**\n\n{str(e)}"
+            return None, None, status, "", "", "", ""
+
+
+def create_interface() -> gr.Blocks:
+    """Create the Gradio interface."""
+
+    app = NeuroAnimApp()
+
+    # Custom CSS for better styling
+    custom_css = """
+    .main-title {
+        text-align: center;
+        color: #2563eb;
+        font-size: 2.5em;
+        font-weight: bold;
+        margin-bottom: 0.5em;
+    }
+    .subtitle {
+        text-align: center;
+        color: #64748b;
+        font-size: 1.2em;
+        margin-bottom: 2em;
+    }
+    .status-box {
+        padding: 1em;
+        border-radius: 8px;
+        margin: 1em 0;
+    }
+    .gradio-container {
+        max-width: 1400px !important;
+    }
+    /* Video player styling */
+    video {
+        border-radius: 8px;
+        box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
+    }
+    /* Quiz and content styling */
+    .markdown-text h2 {
+        color: #1e40af;
+        border-bottom: 2px solid #3b82f6;
+        padding-bottom: 0.5em;
+        margin-top: 1em;
+    }
+    .markdown-text h3 {
+        color: #1e293b;
+        margin-top: 1em;
+    }
+    .markdown-text blockquote {
+        background-color: #f0fdf4;
+        border-left: 4px solid #22c55e;
+        padding: 0.5em 1em;
+        margin: 1em 0;
+    }
+    /* Button styling */
+    .primary {
+        background: linear-gradient(135deg, #2563eb 0%, #1d4ed8 100%);
+    }
+    /* Code block styling */
+    .code-container {
+        border-radius: 8px;
+        margin: 1em 0;
+    }
+    """
+
+    with gr.Blocks(title="NeuroAnim - STEM Animation Generator") as interface:
+        # Apply custom CSS
+        interface.css = custom_css
+        # Header
+        gr.HTML("""
+        <div class="main-title">🧠 NeuroAnim</div>
+        <div class="subtitle">AI-Powered Educational Animation Generator</div>
+        """)
+
+        with gr.Tabs() as tabs:
+            # Main Generation Tab
+            with gr.TabItem("🎬 Generate Animation", id=0):
+                gr.Markdown("""
+                ### Create Your Educational Animation
+                Enter a mathematical or scientific concept, and NeuroAnim will generate a complete animated video with narration and quiz questions.
+                """)
+
+                with gr.Row():
+                    with gr.Column(scale=1):
+                        # Input Section
+                        gr.Markdown("#### 📝 Animation Configuration")
+
+                        topic_input = gr.Textbox(
+                            label="Topic / Concept",
+                            placeholder="e.g., Pythagorean Theorem, Photosynthesis, Newton's Laws, etc.",
+                            lines=2,
+                            info="Enter the STEM concept you want to explain",
+                        )
+
+                        with gr.Row():
+                            audience_input = gr.Dropdown(
+                                label="Target Audience",
+                                choices=[
+                                    "elementary",
+                                    "middle_school",
+                                    "high_school",
+                                    "undergraduate",
+                                    "phd",
+                                    "general",
+                                ],
+                                value="high_school",
+                                info="Select the appropriate education level",
+                            )
+
+                            duration_input = gr.Slider(
+                                label="Duration (minutes)",
+                                minimum=0.5,
+                                maximum=10,
+                                value=2.0,
+                                step=0.5,
+                                info="Animation length",
+                            )
+
+                        quality_input = gr.Dropdown(
+                            label="Video Quality",
+                            choices=[
+                                "Low (480p, faster)",
+                                "Medium (720p, balanced)",
+                                "High (1080p, slower)",
+                                "Production (4K, slowest)",
+                            ],
+                            value="Medium (720p, balanced)",
+                            info="Higher quality takes longer to render",
+                        )
+
+                        generate_btn = gr.Button(
+                            "🚀 Generate Animation", variant="primary", size="lg"
+                        )
+
+                        status_output = gr.Markdown(
+                            label="Status",
+                            value="Ready to generate...",
+                            elem_classes=["status-box"],
+                        )
+
+                        # Example inputs
+                        gr.Markdown("#### 💡 Example Topics")
+                        gr.Examples(
+                            examples=[
+                                ["Pythagorean Theorem", "high_school", 2.0, "Medium (720p, balanced)"],
+                                ["Laws of Motion", "middle_school", 2.5, "Low (480p, faster)"],
+                                ["Binary Numbers", "middle_school", 1.5, "Medium (720p, balanced)"],
+                                ["Photosynthesis Process", "elementary", 2.0, "Low (480p, faster)"],
+                                ["Quadratic Formula", "high_school", 3.0, "Medium (720p, balanced)"],
+                                ["Circle Area Derivation", "undergraduate", 2.5, "High (1080p, slower)"],
+                            ],
+                            inputs=[topic_input, audience_input, duration_input, quality_input],
+                        )
+
+                    with gr.Column(scale=1):
+                        # Output Section
+                        gr.Markdown("#### 🎥 Generated Animation")
+
+                        video_output = gr.Video(
+                            label="Animation Video", height=400, interactive=False
+                        )
+
+                        # Download button
+                        download_file = gr.File(
+                            label="📥 Download Animation",
+                            interactive=False,
+                            visible=True,
+                        )
+
+                        gr.Markdown(
+                            "**Tip:** Click the download button above or use the ⋮ menu on the video player"
+                        )
+
+                # Additional outputs in accordion
+                with gr.Accordion("📄 View Generated Content", open=True):
+                    with gr.Tabs():
+                        with gr.TabItem("📖 Narration Script"):
+                            narration_output = gr.Textbox(
+                                label="Narration Text",
+                                lines=8,
+                                interactive=False,
+                            )
+
+                        with gr.TabItem("💻 Manim Code"):
+                            code_output = gr.Code(
+                                label="Generated Python Code",
+                                language="python",
+                                interactive=False,
+                                lines=15,
+                            )
+
+                        with gr.TabItem("❓ Quiz Questions"):
+                            quiz_output = gr.Markdown(
+                                label="Assessment Questions",
+                                value="Quiz will appear here after generation...",
+                            )
+
+                        with gr.TabItem("📋 Concept Plan"):
+                            concept_output = gr.Textbox(
+                                label="Educational Plan",
+                                lines=10,
+                                interactive=False,
+                            )
+
+                # Connect the generate button
+                generate_btn.click(
+                    fn=app.generate_animation_sync,
+                    inputs=[topic_input, audience_input, duration_input, quality_input],
+                    outputs=[
+                        video_output,
+                        download_file,
+                        status_output,
+                        narration_output,
+                        code_output,
+                        quiz_output,
+                        concept_output,
+                    ],
+                    api_name="generate",
+                )
+
+            # About Tab
+            with gr.TabItem("ℹ️ About", id=1):
+                gr.Markdown("""
+                # About NeuroAnim
+
+                NeuroAnim is an AI-powered educational animation generator that creates engaging STEM content automatically.
+
+                ## 🎯 Features
+
+                - **🎨 Automatic Animation Generation**: Creates professional Manim animations from topic descriptions
+                - **🗣️ AI Narration**: Generates educational narration scripts tailored to your audience
+                - **🔊 Text-to-Speech**: Converts narration to high-quality audio with ElevenLabs or Hugging Face
+                - **📹 Video Production**: Renders and merges video with synchronized audio
+                - **❓ Quiz Generation**: Creates assessment questions to test understanding
+                - **🎓 Multi-Level Support**: Content appropriate for elementary through undergraduate levels
+
+                ## 🔧 Technology Stack
+
+                - **Manim Community Edition**: Mathematical animation engine
+                - **Hugging Face Models**: AI-powered content generation
+                - **ElevenLabs**: High-quality text-to-speech synthesis
+                - **MCP (Model Context Protocol)**: Modular server architecture
+                - **Gradio**: Interactive web interface
+
+                ## 🚀 How It Works
+
+                1. **Concept Planning**: AI analyzes your topic and creates an educational plan
+                2. **Script Writing**: Generates age-appropriate narration aligned with learning objectives
+                3. **Code Generation**: Creates Manim Python code for visual representation
+                4. **Rendering**: Executes Manim to produce the base animation
+                5. **Audio Synthesis**: Converts narration to speech using TTS
+                6. **Final Production**: Merges video and audio into complete animation
+                7. **Assessment**: Generates quiz questions for the content
+
+                ## 📝 Tips for Best Results
+
+                - **Be Specific**: Instead of "math", try "solving linear equations" or "area of a circle"
+                - **Choose Right Audience**: Match the complexity level to your target viewers
+                - **Optimal Duration**: 1.5-3 minutes works best for most concepts
+                - **Review Generated Content**: Check the narration and code tabs to see what was created
+                - **Iterate**: If results aren't perfect, try rewording your topic or adjusting parameters
+
+                ## 🔑 Setup Requirements
+
+                To use NeuroAnim, you need:
+                - **Hugging Face API Key**: For AI content generation (required)
+                - **ElevenLabs API Key**: For high-quality TTS (optional, falls back to HF TTS)
+
+                Set these in your `.env` file:
+                ```bash
+                HUGGINGFACE_API_KEY=your_key_here
+                ELEVENLABS_API_KEY=your_key_here  # Optional
+                ```
+
+                ## 📚 Example Use Cases
+
+                - **Teachers**: Create engaging lesson materials
+                - **Students**: Visualize complex concepts for better understanding
+                - **Content Creators**: Produce educational YouTube/social media content
+                - **Tutors**: Generate custom explanations for specific topics
+                - **Course Developers**: Build comprehensive educational video libraries
+
+                ## 🤝 Contributing
+
+                NeuroAnim is open source! Contributions are welcome:
+                - Report bugs or suggest features via GitHub Issues
+                - Submit pull requests with improvements
+                - Share your generated animations with the community
+
+                ## 📄 License
+
+                MIT License - Free to use for educational and commercial purposes
+
+                ---
+
+                Made with ❤️ for educational content creation
+                """)
+
+            # Settings Tab
+            with gr.TabItem("⚙️ Settings", id=2):
+                gr.Markdown("""
+                # System Configuration
+
+                Configure API keys and system settings here.
+                """)
+
+                with gr.Group():
+                    gr.Markdown("### 🔑 API Keys")
+
+                    hf_key_status = gr.Textbox(
+                        label="Hugging Face API Key Status",
+                        value="✅ Configured"
+                        if os.getenv("HUGGINGFACE_API_KEY")
+                        else "❌ Not Set",
+                        interactive=False,
+                    )
+
+                    eleven_key_status = gr.Textbox(
+                        label="ElevenLabs API Key Status",
+                        value="✅ Configured"
+                        if os.getenv("ELEVENLABS_API_KEY")
+                        else "⚠️ Not Set (will use fallback TTS)",
+                        interactive=False,
+                    )
+
+                    gr.Markdown("""
+                    **To configure API keys:**
+                    1. Create a `.env` file in the project root
+                    2. Add your keys:
+                       ```
+                       HUGGINGFACE_API_KEY=your_hf_key
+                       ELEVENLABS_API_KEY=your_elevenlabs_key
+                       ```
+                    3. Restart the application
+                    """)
+
+                with gr.Group():
+                    gr.Markdown("### 📊 System Info")
+
+                    system_info = gr.Textbox(
+                        label="System Status",
+                        value=f"""
+Output Directory: {Path("outputs").absolute()}
+Working Directory: Temporary (auto-created)
+Manim Version: Community Edition
+Default Quality: Medium (720p, 30fps)
+                        """.strip(),
+                        interactive=False,
+                        lines=6,
+                    )
+
+    return interface
+
+
+def main():
+    """Launch the Gradio application."""
+
+    # Check for API keys
+    if not os.getenv("HUGGINGFACE_API_KEY"):
+        logger.warning("HUGGINGFACE_API_KEY not set! Generation will fail.")
+        print("\n⚠️  WARNING: HUGGINGFACE_API_KEY environment variable not set!")
+        print("Please set it in your .env file or environment.\n")
+
+    if not os.getenv("ELEVENLABS_API_KEY"):
+        logger.info("ELEVENLABS_API_KEY not set, will use fallback TTS")
+        print(
+            "\nℹ️  Note: ELEVENLABS_API_KEY not set. Using fallback TTS (may have lower quality).\n"
+        )
+
+    # Create outputs directory
+    Path("outputs").mkdir(exist_ok=True)
+
+    # Build and launch interface
+    interface = create_interface()
+
+    logger.info("Launching Gradio interface...")
+
+    interface.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        share=False,
+    )
+
+
+if __name__ == "__main__":
+    main()

manim_mcp/README.md

@@ -0,0 +1,337 @@
+# Manim MCP Server
+
+A comprehensive Model Context Protocol (MCP) server for creating educational STEM animations using Manim. This server combines AI-powered creative tools with rendering and video processing capabilities to streamline the animation creation workflow.
+
+## Features
+
+### 🎨 Creative Tools
+- **Concept Planning**: AI-powered STEM concept planning with learning objectives and scene flow
+- **Code Generation**: Intelligent Manim code generation with syntax validation
+- **Code Refinement**: Automatic code improvement based on errors and feedback
+- **Narration Generation**: Educational script writing tailored to target audiences
+- **Quiz Generation**: Automated assessment question creation
+
+### 🎬 Rendering & Processing
+- **Manim Rendering**: Full Manim animation rendering with quality controls
+- **Video Processing**: FFmpeg-based video manipulation and conversion
+- **Audio/Video Merging**: Seamless integration of narration with animations
+- **File Management**: Comprehensive file system operations
+
+### 🤖 AI Integration
+- **Vision Analysis**: Frame-by-frame quality assessment using vision models
+- **Text-to-Speech**: Natural voice synthesis for narration
+- **Multi-Model Support**: Flexible model selection for different tasks
+
+## Installation
+
+### Prerequisites
+
+- Python 3.12+
+- Manim Community Edition (`manim>=0.18.1`)
+- FFmpeg (for video processing)
+- HuggingFace API key (for AI features)
+
+### Setup
+
+1. Install the package and dependencies:
+
+```bash
+pip install mcp huggingface_hub manim pydantic aiohttp httpx numpy Pillow
+```
+
+2. Set up your environment variables:
+
+```bash
+export HUGGINGFACE_API_KEY="your_api_key_here"
+```
+
+3. Run the MCP server:
+
+```bash
+python manim_mcp/server.py
+```
+
+## Usage
+
+### As an MCP Server
+
+The server can be integrated into any MCP-compatible client (like Claude Desktop):
+
+```json
+{
+  "mcpServers": {
+    "manim": {
+      "command": "python",
+      "args": ["path/to/manim_mcp/server.py"],
+      "env": {
+        "HUGGINGFACE_API_KEY": "your_key"
+      }
+    }
+  }
+}
+```
+
+### Programmatic Usage
+
+```python
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+# Initialize MCP client
+params = StdioServerParameters(
+    command="python",
+    args=["manim_mcp/server.py"],
+    env={"HUGGINGFACE_API_KEY": "your_key"}
+)
+
+async with stdio_client(params) as (read, write):
+    session = ClientSession(read, write)
+    await session.initialize()
+    
+    # Plan a concept
+    result = await session.call_tool("plan_concept", {
+        "topic": "Pythagorean Theorem",
+        "target_audience": "high_school",
+        "animation_length_minutes": 2.0
+    })
+```
+
+## Available Tools
+
+### Planning & Creative
+
+#### `plan_concept`
+Plan a STEM concept for animation with learning objectives and scene flow.
+
+**Parameters:**
+- `topic` (string, required): The STEM topic to animate
+- `target_audience` (enum, required): elementary | middle_school | high_school | college | general
+- `animation_length_minutes` (number, optional): Desired length in minutes
+- `model` (string, optional): HuggingFace model to use
+
+#### `generate_manim_code`
+Generate complete, runnable Manim Python code.
+
+**Parameters:**
+- `concept` (string, required): Animation concept
+- `scene_description` (string, required): Detailed scene description
+- `visual_elements` (array, optional): List of visual elements to include
+- `previous_code` (string, optional): For retry attempts
+- `error_message` (string, optional): Error from previous attempt
+
+#### `refine_animation`
+Refine existing Manim code based on feedback.
+
+**Parameters:**
+- `original_code` (string, required): Code to refine
+- `feedback` (string, required): Feedback or error message
+- `improvement_goals` (array, optional): Specific improvements to make
+
+#### `generate_narration`
+Generate educational narration scripts.
+
+**Parameters:**
+- `concept` (string, required): Animation concept
+- `scene_description` (string, required): Scene details
+- `target_audience` (string, required): Target audience level
+- `duration_seconds` (integer, optional): Script duration
+
+#### `generate_quiz`
+Generate educational quiz questions.
+
+**Parameters:**
+- `concept` (string, required): STEM concept
+- `difficulty` (enum, required): easy | medium | hard
+- `num_questions` (integer, required): Number of questions
+- `question_types` (array, optional): Types of questions
+
+### Rendering & Processing
+
+#### `write_manim_file`
+Write Manim code to a file.
+
+**Parameters:**
+- `filepath` (string, required): Destination path
+- `code` (string, required): Manim code to write
+
+#### `render_manim_animation`
+Render a Manim animation from a Python file.
+
+**Parameters:**
+- `scene_name` (string, required): Scene class name
+- `file_path` (string, required): Path to Python file
+- `output_dir` (string, required): Output directory
+- `quality` (enum, optional): low | medium | high | production_quality
+- `format` (enum, optional): mp4 | gif | png
+- `frame_rate` (integer, optional): Frame rate (default: 30)
+
+#### `merge_video_audio`
+Merge video and audio files.
+
+**Parameters:**
+- `video_file` (string, required): Path to video
+- `audio_file` (string, required): Path to audio
+- `output_file` (string, required): Output path
+
+#### `process_video_with_ffmpeg`
+Process videos with custom FFmpeg arguments.
+
+**Parameters:**
+- `input_files` (array, required): Input file paths
+- `output_file` (string, required): Output path
+- `ffmpeg_args` (array, optional): Additional FFmpeg arguments
+
+#### `check_file_exists`
+Check file existence and get metadata.
+
+**Parameters:**
+- `filepath` (string, required): File path to check
+
+### Analysis
+
+#### `analyze_frame`
+Analyze animation frames using vision models.
+
+**Parameters:**
+- `image_path` (string, required): Path to image
+- `analysis_type` (string, required): Type of analysis
+- `context` (string, optional): Additional context
+- `model` (string, optional): Vision model to use
+
+#### `generate_speech`
+Convert text to speech audio.
+
+**Parameters:**
+- `text` (string, required): Text to convert
+- `output_path` (string, required): Audio output path
+- `voice` (string, optional): Voice to use
+- `model` (string, optional): TTS model to use
+
+## Complete Workflow Example
+
+Here's a typical animation generation workflow:
+
+1. **Plan** the concept
+2. **Generate** narration script
+3. **Generate** Manim code
+4. **Write** code to file
+5. **Render** the animation
+6. **Generate** speech audio
+7. **Merge** video and audio
+8. **Generate** quiz questions
+
+```python
+# 1. Plan concept
+plan = await session.call_tool("plan_concept", {
+    "topic": "Newton's Laws of Motion",
+    "target_audience": "high_school"
+})
+
+# 2. Generate narration
+narration = await session.call_tool("generate_narration", {
+    "concept": "Newton's Laws",
+    "scene_description": plan["text"],
+    "target_audience": "high_school",
+    "duration_seconds": 120
+})
+
+# 3. Generate code
+code = await session.call_tool("generate_manim_code", {
+    "concept": "Newton's Laws",
+    "scene_description": plan["text"],
+    "visual_elements": ["text", "shapes", "arrows"]
+})
+
+# 4-7. Continue workflow...
+```
+
+## Configuration
+
+### Environment Variables
+
+- `HUGGINGFACE_API_KEY`: Required for AI-powered tools
+- `ELEVENLABS_API_KEY`: Optional for premium TTS (falls back to free alternatives)
+
+### Model Selection
+
+By default, the server uses sensible model defaults, but you can specify custom models:
+
+```python
+await session.call_tool("generate_manim_code", {
+    "concept": "topic",
+    "scene_description": "description",
+    "model": "Qwen/Qwen2.5-Coder-32B-Instruct"  # Custom model
+})
+```
+
+## Quality Settings
+
+Rendering quality options:
+- **low**: 480p15 - Fast, good for testing
+- **medium**: 720p30 - Balanced quality/speed (default)
+- **high**: 1080p60 - High quality, slower
+- **production_quality**: 2160p60 - 4K, very slow
+
+## Error Handling
+
+The server includes comprehensive error handling:
+- Syntax validation for generated code
+- Retry logic for code generation failures
+- Graceful fallbacks for AI services
+- Detailed error messages for debugging
+
+## Architecture
+
+The server is organized into modular tool categories:
+
+```
+manim_mcp/
+├── server.py           # Main MCP server
+├── tools/
+│   ├── planning.py     # Concept planning
+│   ├── code_generation.py  # Code generation & refinement
+│   ├── rendering.py    # Manim rendering
+│   ├── vision.py       # Frame analysis
+│   ├── audio.py        # TTS & narration
+│   ├── video.py        # Video processing
+│   └── quiz.py         # Quiz generation
+```
+
+## Requirements
+
+- Python >= 3.12
+- mcp >= 1.0.0
+- huggingface_hub >= 0.25.0
+- manim >= 0.18.1
+- pydantic >= 2.0.0
+- aiohttp >= 3.8.0
+- FFmpeg (system dependency)
+
+## Contributing
+
+Contributions are welcome! Areas for improvement:
+- Additional AI model integrations
+- More video processing tools
+- Enhanced error recovery
+- Performance optimizations
+
+## License
+
+MIT License - see LICENSE file for details
+
+## Support
+
+For issues, questions, or feature requests, please open an issue on the repository.
+
+## Credits
+
+Built with:
+- [Manim Community Edition](https://www.manim.community/) - Mathematical animation engine
+- [Model Context Protocol](https://modelcontextprotocol.io/) - AI integration framework
+- [HuggingFace](https://huggingface.co/) - AI model hosting and inference
+
+---
+
+**Version**: 0.1.0  
+**Author**: NeuroAnim Team  
+**Status**: Beta - Ready for production use with active development

manim_mcp/__init__.py

@@ -0,0 +1,19 @@
+"""
+Manim MCP - Model Context Protocol Server for Manim Animations
+
+A unified MCP server providing comprehensive tools for STEM animation creation:
+- Planning and ideation
+- AI-powered code generation
+- Manim rendering
+- Vision-based analysis
+- Audio narration and TTS
+- Video processing
+
+This package can be used standalone as an MCP server or integrated into
+larger animation pipelines.
+"""
+
+from .server import main, server
+
+__version__ = "0.1.0"
+__all__ = ["server", "main"]

manim_mcp/server.py

@@ -0,0 +1,480 @@
+"""
+Manim MCP Server
+
+A unified MCP server providing tools for STEM animation creation with Manim.
+Combines creative AI tools (planning, code generation, narration) with
+rendering and video processing capabilities.
+
+This server is designed to be used standalone or integrated into larger
+animation generation pipelines.
+"""
+
+import asyncio
+import logging
+import os
+import sys
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+# Ensure project root is on sys.path
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+from mcp.server import NotificationOptions, Server
+from mcp.server.models import InitializationOptions
+from mcp.server.stdio import stdio_server
+from mcp.types import CallToolResult, ListToolsResult, TextContent, Tool
+
+from manim_mcp.tools import (
+    analyze_frame,
+    check_file_exists,
+    generate_manim_code,
+    generate_narration,
+    generate_quiz,
+    generate_speech,
+    merge_video_audio,
+    plan_concept,
+    process_video_with_ffmpeg,
+    refine_animation,
+    render_manim_animation,
+    write_manim_file,
+)
+from utils.hf_wrapper import HFInferenceWrapper, get_hf_wrapper
+
+# Set up logging
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+# Create MCP server
+server = Server("manim-mcp")
+
+# Global HF wrapper instance
+hf_wrapper: Optional[HFInferenceWrapper] = None
+
+
+def get_hf_wrapper_instance() -> HFInferenceWrapper:
+    """Get or create the HuggingFace wrapper instance."""
+    global hf_wrapper
+    if hf_wrapper is None:
+        api_key = os.getenv("HUGGINGFACE_API_KEY")
+        hf_wrapper = get_hf_wrapper(api_key=api_key)
+        logger.info("Initialized HuggingFace wrapper")
+    return hf_wrapper
+
+
+@server.list_tools()
+async def list_tools() -> ListToolsResult:
+    """List all available tools in the Manim MCP server."""
+    tools = [
+        # Planning Tools
+        Tool(
+            name="plan_concept",
+            description="Plan a STEM concept for animation. Creates a structured plan with learning objectives, visual metaphors, scene flow, and educational value assessment.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "topic": {
+                        "type": "string",
+                        "description": "The STEM topic to create an animation for",
+                    },
+                    "target_audience": {
+                        "type": "string",
+                        "enum": [
+                            "elementary",
+                            "middle_school",
+                            "high_school",
+                            "college",
+                            "general",
+                        ],
+                        "description": "Target audience level",
+                    },
+                    "animation_length_minutes": {
+                        "type": "number",
+                        "description": "Desired animation length in minutes (default: 2.0)",
+                    },
+                    "model": {
+                        "type": "string",
+                        "description": "Hugging Face model to use (optional)",
+                    },
+                },
+                "required": ["topic", "target_audience"],
+            },
+        ),
+        # Code Generation Tools
+        Tool(
+            name="generate_manim_code",
+            description="Generate Manim Python code for an animation concept. Produces complete, runnable code with proper syntax and Manim best practices.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "concept": {
+                        "type": "string",
+                        "description": "The animation concept",
+                    },
+                    "scene_description": {
+                        "type": "string",
+                        "description": "Detailed scene description",
+                    },
+                    "visual_elements": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "List of visual elements to include",
+                    },
+                    "model": {
+                        "type": "string",
+                        "description": "Hugging Face code model to use (optional)",
+                    },
+                    "previous_code": {
+                        "type": "string",
+                        "description": "Previous code attempt (for retries)",
+                    },
+                    "error_message": {
+                        "type": "string",
+                        "description": "Error from previous attempt (for retries)",
+                    },
+                },
+                "required": ["concept", "scene_description"],
+            },
+        ),
+        Tool(
+            name="refine_animation",
+            description="Refine and improve existing Manim code based on feedback or errors. Outputs complete corrected code.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "original_code": {
+                        "type": "string",
+                        "description": "The original Manim code to refine",
+                    },
+                    "feedback": {
+                        "type": "string",
+                        "description": "Feedback or error message about the code",
+                    },
+                    "improvement_goals": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "List of specific improvement goals",
+                    },
+                    "model": {
+                        "type": "string",
+                        "description": "Hugging Face code model to use (optional)",
+                    },
+                },
+                "required": ["original_code", "feedback"],
+            },
+        ),
+        # Rendering Tools
+        Tool(
+            name="write_manim_file",
+            description="Write Manim Python code to a file on the filesystem.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "filepath": {
+                        "type": "string",
+                        "description": "Path where to write the Manim file",
+                    },
+                    "code": {
+                        "type": "string",
+                        "description": "Manim Python code to write",
+                    },
+                },
+                "required": ["filepath", "code"],
+            },
+        ),
+        Tool(
+            name="render_manim_animation",
+            description="Render a Manim animation from a Python file. Uses local Manim installation with quality and format options.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "scene_name": {
+                        "type": "string",
+                        "description": "Name of the Manim scene class to render",
+                    },
+                    "file_path": {
+                        "type": "string",
+                        "description": "Path to the Manim Python file",
+                    },
+                    "output_dir": {
+                        "type": "string",
+                        "description": "Directory to save the output animation",
+                    },
+                    "quality": {
+                        "type": "string",
+                        "enum": ["low", "medium", "high", "production_quality"],
+                        "description": "Rendering quality (default: medium)",
+                    },
+                    "format": {
+                        "type": "string",
+                        "enum": ["mp4", "gif", "png"],
+                        "description": "Output format (default: mp4)",
+                    },
+                    "frame_rate": {
+                        "type": "integer",
+                        "description": "Frame rate (default: 30)",
+                    },
+                },
+                "required": ["scene_name", "file_path", "output_dir"],
+            },
+        ),
+        # Vision Tools
+        Tool(
+            name="analyze_frame",
+            description="Analyze an animation frame using vision models. Provides feedback on visual quality, clarity, and educational effectiveness.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "image_path": {
+                        "type": "string",
+                        "description": "Path to the image file to analyze",
+                    },
+                    "analysis_type": {
+                        "type": "string",
+                        "description": "Type of analysis (e.g., quality, educational_value, clarity)",
+                    },
+                    "context": {
+                        "type": "string",
+                        "description": "Additional context about the animation",
+                    },
+                    "model": {
+                        "type": "string",
+                        "description": "Hugging Face vision model to use (optional)",
+                    },
+                },
+                "required": ["image_path", "analysis_type"],
+            },
+        ),
+        # Audio Tools
+        Tool(
+            name="generate_narration",
+            description="Generate an educational narration script for an animation. Creates age-appropriate, engaging content aligned with learning objectives.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "concept": {
+                        "type": "string",
+                        "description": "The animation concept",
+                    },
+                    "scene_description": {
+                        "type": "string",
+                        "description": "Description of the scene/animation",
+                    },
+                    "target_audience": {
+                        "type": "string",
+                        "description": "Target audience level",
+                    },
+                    "duration_seconds": {
+                        "type": "integer",
+                        "description": "Duration in seconds (default: 30)",
+                    },
+                    "model": {
+                        "type": "string",
+                        "description": "Hugging Face model to use (optional)",
+                    },
+                },
+                "required": ["concept", "scene_description", "target_audience"],
+            },
+        ),
+        Tool(
+            name="generate_speech",
+            description="Convert text to speech audio file using TTS models.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "text": {
+                        "type": "string",
+                        "description": "Text to convert to speech",
+                    },
+                    "output_path": {
+                        "type": "string",
+                        "description": "Path where to save the audio file",
+                    },
+                    "voice": {
+                        "type": "string",
+                        "description": "Voice to use for TTS (optional)",
+                    },
+                    "model": {
+                        "type": "string",
+                        "description": "Hugging Face TTS model to use (optional)",
+                    },
+                },
+                "required": ["text", "output_path"],
+            },
+        ),
+        # Video Processing Tools
+        Tool(
+            name="process_video_with_ffmpeg",
+            description="Process video files using FFmpeg with custom arguments for conversion, filtering, and combining.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "input_files": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "List of input video/audio file paths",
+                    },
+                    "output_file": {
+                        "type": "string",
+                        "description": "Output file path",
+                    },
+                    "ffmpeg_args": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "Additional FFmpeg command-line arguments",
+                    },
+                },
+                "required": ["input_files", "output_file"],
+            },
+        ),
+        Tool(
+            name="merge_video_audio",
+            description="Merge a video file and an audio file into a single output file using FFmpeg.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "video_file": {
+                        "type": "string",
+                        "description": "Path to the input video file",
+                    },
+                    "audio_file": {
+                        "type": "string",
+                        "description": "Path to the input audio file",
+                    },
+                    "output_file": {
+                        "type": "string",
+                        "description": "Path to the output merged file",
+                    },
+                },
+                "required": ["video_file", "audio_file", "output_file"],
+            },
+        ),
+        Tool(
+            name="check_file_exists",
+            description="Check if a file exists and return its metadata (size, timestamps, type).",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "filepath": {
+                        "type": "string",
+                        "description": "Path to the file to check",
+                    }
+                },
+                "required": ["filepath"],
+            },
+        ),
+        # Quiz Tools
+        Tool(
+            name="generate_quiz",
+            description="Generate educational quiz questions based on a STEM concept. Creates questions with answers and explanations.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "concept": {
+                        "type": "string",
+                        "description": "The STEM concept to create quiz questions for",
+                    },
+                    "difficulty": {
+                        "type": "string",
+                        "enum": ["easy", "medium", "hard"],
+                        "description": "Difficulty level",
+                    },
+                    "num_questions": {
+                        "type": "integer",
+                        "description": "Number of questions to generate",
+                    },
+                    "question_types": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "Types of questions (e.g., multiple_choice, true_false)",
+                    },
+                    "model": {
+                        "type": "string",
+                        "description": "Hugging Face model to use (optional)",
+                    },
+                },
+                "required": ["concept", "difficulty", "num_questions"],
+            },
+        ),
+    ]
+
+    return ListToolsResult(tools=tools)
+
+
+@server.call_tool()
+async def call_tool(tool_name: str, arguments: Dict[str, Any]) -> CallToolResult:
+    """
+    Dispatch tool calls to the appropriate handler functions.
+
+    Routes requests to the correct tool implementation based on tool name.
+    Handles errors gracefully and returns appropriate error responses.
+    """
+    try:
+        # Get HF wrapper for AI-powered tools
+        wrapper = get_hf_wrapper_instance()
+
+        # Route to appropriate tool handler
+        if tool_name == "plan_concept":
+            return await plan_concept(wrapper, arguments)
+        elif tool_name == "generate_manim_code":
+            return await generate_manim_code(wrapper, arguments)
+        elif tool_name == "refine_animation":
+            return await refine_animation(wrapper, arguments)
+        elif tool_name == "write_manim_file":
+            return await write_manim_file(arguments)
+        elif tool_name == "render_manim_animation":
+            return await render_manim_animation(arguments)
+        elif tool_name == "analyze_frame":
+            return await analyze_frame(wrapper, arguments)
+        elif tool_name == "generate_narration":
+            return await generate_narration(wrapper, arguments)
+        elif tool_name == "generate_speech":
+            return await generate_speech(wrapper, arguments)
+        elif tool_name == "process_video_with_ffmpeg":
+            return await process_video_with_ffmpeg(arguments)
+        elif tool_name == "merge_video_audio":
+            return await merge_video_audio(arguments)
+        elif tool_name == "check_file_exists":
+            return await check_file_exists(arguments)
+        elif tool_name == "generate_quiz":
+            return await generate_quiz(wrapper, arguments)
+        else:
+            logger.error(f"Unknown tool requested: {tool_name}")
+            return CallToolResult(
+                content=[TextContent(type="text", text=f"Unknown tool: {tool_name}")],
+                isError=True,
+            )
+
+    except Exception as e:
+        logger.error(f"Error in tool {tool_name}: {e}", exc_info=True)
+        return CallToolResult(
+            content=[TextContent(type="text", text=f"Error: {str(e)}")],
+            isError=True,
+        )
+
+
+async def main():
+    """Main entry point for the Manim MCP server."""
+    logger.info("Starting Manim MCP Server...")
+
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(
+            read_stream,
+            write_stream,
+            InitializationOptions(
+                server_name="manim-mcp",
+                server_version="0.1.0",
+                capabilities=server.get_capabilities(
+                    notification_options=NotificationOptions(),
+                    experimental_capabilities={},
+                ),
+            ),
+        )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

manim_mcp/tools/__init__.py

@@ -0,0 +1,42 @@
+"""
+Manim MCP Tools
+
+This package contains all the tools for the Manim MCP server.
+Tools are organized into logical modules:
+- planning: Concept planning and ideation
+- code_generation: Manim code generation and refinement
+- rendering: Manim animation rendering
+- vision: Frame analysis and visual feedback
+- audio: Text-to-speech and narration
+- video: Video processing and merging
+"""
+
+from .audio import generate_narration, generate_speech
+from .code_generation import generate_manim_code, refine_animation
+from .planning import plan_concept
+from .quiz import generate_quiz
+from .rendering import render_manim_animation, write_manim_file
+from .video import check_file_exists, merge_video_audio, process_video_with_ffmpeg
+from .vision import analyze_frame
+
+__all__ = [
+    # Planning
+    "plan_concept",
+    # Code Generation
+    "generate_manim_code",
+    "refine_animation",
+    # Rendering
+    "write_manim_file",
+    "render_manim_animation",
+    # Vision
+    "analyze_frame",
+    # Audio
+    "generate_narration",
+    "generate_speech",
+    # Video
+    "process_video_with_ffmpeg",
+    "merge_video_audio",
+    "check_file_exists",
+    # Quiz
+    "generate_quiz",
+]

manim_mcp/tools/audio.py

@@ -0,0 +1,165 @@
+"""
+Audio Tools for Manim MCP Server
+
+This module provides tools for generating narration scripts and speech audio.
+"""
+
+import json
+import logging
+from typing import Any, Dict, Optional
+
+from mcp.types import CallToolResult, TextContent
+
+from utils.hf_wrapper import HFInferenceWrapper, ModelConfig
+
+logger = logging.getLogger(__name__)
+
+
+async def generate_narration(
+    hf_wrapper: HFInferenceWrapper, arguments: Dict[str, Any]
+) -> CallToolResult:
+    """
+    Generate a narration script for an educational animation.
+
+    Uses a text LLM to create an engaging, age-appropriate narration script
+    that aligns with the animation concept and scene description.
+
+    Args:
+        hf_wrapper: HuggingFace inference wrapper instance
+        arguments: Dictionary containing:
+            - concept (str): The animation concept
+            - scene_description (str): Description of the scene/animation
+            - target_audience (str): Target audience level
+            - duration_seconds (int, optional): Duration in seconds (default: 30)
+            - model (str, optional): Hugging Face model to use
+
+    Returns:
+        CallToolResult with the narration script
+    """
+    concept = arguments["concept"]
+    scene_description = arguments["scene_description"]
+    target_audience = arguments["target_audience"]
+    duration = arguments.get("duration_seconds", 30)
+    model = arguments.get("model")
+
+    try:
+        model_config = ModelConfig()
+        selected_model = model or model_config.text_models[0]
+
+        prompt = f"""
+Generate a narration script for an educational animation:
+
+Concept: {concept}
+Scene: {scene_description}
+Target Audience: {target_audience}
+Duration: {duration} seconds
+
+Requirements:
+1. Clear, engaging, and age-appropriate language
+2. Educational value aligned with learning objectives
+3. Natural speaking pace (approximately {duration / 150} words for {duration} seconds)
+4. Include pauses and emphasis markers where appropriate
+5. Make it interesting and memorable
+
+Format as a clean script ready for text-to-speech.
+"""
+
+        response = await hf_wrapper.text_generation(
+            model=selected_model,
+            prompt=prompt,
+            max_new_tokens=512,
+            temperature=0.6,
+        )
+
+        logger.info(f"Successfully generated narration for concept: {concept}")
+
+        return CallToolResult(
+            content=[
+                TextContent(
+                    type="text",
+                    text=f"Narration Script:\n\n{response}",
+                )
+            ]
+        )
+
+    except Exception as e:
+        logger.error(f"Narration generation failed: {str(e)}")
+        return CallToolResult(
+            content=[
+                TextContent(
+                    type="text",
+                    text=f"Narration generation failed: {str(e)}",
+                )
+            ],
+            isError=True,
+        )
+
+
+async def generate_speech(
+    hf_wrapper: HFInferenceWrapper, arguments: Dict[str, Any]
+) -> CallToolResult:
+    """
+    Convert text to speech audio file.
+
+    Uses a TTS model to generate speech audio from text and saves it to a file.
+
+    Args:
+        hf_wrapper: HuggingFace inference wrapper instance
+        arguments: Dictionary containing:
+            - text (str): Text to convert to speech
+            - output_path (str): Path where to save the audio file
+            - voice (str, optional): Voice to use for TTS
+            - model (str, optional): Hugging Face TTS model to use
+
+    Returns:
+        CallToolResult with audio generation info
+    """
+    text = arguments["text"]
+    output_path = arguments["output_path"]
+    voice = arguments.get("voice")
+    model = arguments.get("model")
+
+    try:
+        model_config = ModelConfig()
+        selected_model = model or model_config.tts_models[0]
+
+        # Generate audio
+        audio_bytes = await hf_wrapper.text_to_speech(
+            model=selected_model,
+            text=text,
+            voice=voice,
+        )
+
+        # Save to file
+        success = await hf_wrapper.save_audio_to_file(audio_bytes, output_path)
+
+        if not success:
+            raise Exception("Failed to save audio file")
+
+        # Return audio info
+        audio_info = {
+            "output_path": output_path,
+            "text_length": len(text),
+            "estimated_duration": len(text) / 150,  # Rough estimate
+            "model_used": selected_model,
+        }
+
+        logger.info(f"Successfully generated speech audio at: {output_path}")
+
+        return CallToolResult(
+            content=[
+                TextContent(
+                    type="text",
+                    text=f"Speech generated successfully!\n\n{json.dumps(audio_info, indent=2)}",
+                )
+            ]
+        )
+
+    except Exception as e:
+        logger.error(f"Speech generation failed: {str(e)}")
+        return CallToolResult(
+            content=[
+                TextContent(type="text", text=f"Speech generation failed: {str(e)}")
+            ],
+            isError=True,
+        )

manim_mcp/tools/code_generation.py

@@ -0,0 +1,239 @@
+"""
+Code Generation Tools for Manim MCP Server
+
+This module provides tools for generating and refining Manim animation code.
+"""
+
+import logging
+from typing import Any, Dict, Optional
+
+from mcp.types import CallToolResult, TextContent
+
+from utils.hf_wrapper import HFInferenceWrapper, ModelConfig
+
+logger = logging.getLogger(__name__)
+
+
+async def generate_manim_code(
+    hf_wrapper: HFInferenceWrapper, arguments: Dict[str, Any]
+) -> CallToolResult:
+    """
+    Generate Manim Python code for an animation concept.
+
+    Uses a code LLM to generate complete, runnable Manim code based on:
+    - A concept description
+    - Scene details
+    - Desired visual elements
+    - Optional error feedback for retries
+
+    Args:
+        hf_wrapper: HuggingFace inference wrapper instance
+        arguments: Dictionary containing:
+            - concept (str): The animation concept
+            - scene_description (str): Detailed scene description
+            - visual_elements (list, optional): List of visual elements to include
+            - model (str, optional): Hugging Face model to use
+            - previous_code (str, optional): Previous code attempt (for retries)
+            - error_message (str, optional): Error from previous attempt (for retries)
+
+    Returns:
+        CallToolResult with the generated Manim code
+    """
+    concept = arguments["concept"]
+    scene_description = arguments["scene_description"]
+    visual_elements = arguments.get("visual_elements", [])
+    model = arguments.get("model")
+    previous_code = arguments.get("previous_code")
+    error_message = arguments.get("error_message")
+
+    try:
+        model_config = ModelConfig()
+        selected_model = model or model_config.code_models[0]
+
+        # Build prompt based on whether this is a retry
+        if previous_code and error_message:
+            prompt = f"""
+You are an expert animation engineer using Manim Community Edition (v0.18.0+).
+
+The previous code attempt had an error. Your task is to FIX the code.
+
+PREVIOUS CODE:
+```python
+{previous_code}
+```
+
+ERROR ENCOUNTERED:
+{error_message}
+
+TASK: Fix the error in the code above. Pay special attention to:
+- Closing all parentheses, brackets, and braces
+- Completing all function calls
+- Proper indentation
+- Valid Python syntax
+
+Concept: {concept}
+Scene Description: {scene_description}
+Visual Elements: {", ".join(visual_elements)}
+
+STRICT CODE REQUIREMENTS:
+1. Header: MUST start with `from manim import *`
+2. Class Structure: Define a class inheriting from `MovingCameraScene` (use this instead of `Scene` to enable camera zoom/pan with `self.camera.frame`)
+3. Method: All logic must be inside the `def construct(self):` method
+4. SYNTAX: Ensure ALL parentheses, brackets, and function calls are properly closed
+5. Colors: Use ONLY valid Manim colors (WHITE, BLACK, RED, GREEN, BLUE, YELLOW, ORANGE, PINK, PURPLE, TEAL, GOLD, etc.)
+6. Text: Use `Text()` objects for strings
+7. Positioning: Use `.next_to()`, `.move_to()`, or `.shift()`
+8. Animations: Use Write(), Create(), FadeIn(), FadeOut(), Transform(), Flash(), Indicate() - capitalize properly!
+9. Pacing: Include `self.wait(1)` between animations
+
+OUTPUT FORMAT:
+Provide ONLY the complete, corrected Python code. No markdown blocks. No explanations.
+"""
+        else:
+            prompt = f"""
+You are an expert animation engineer using Manim Community Edition (v0.18.0+).
+Generate a complete, runnable Python script for the following request.
+
+Concept: {concept}
+Scene Description: {scene_description}
+Visual Elements: {", ".join(visual_elements)}
+
+STRICT CODE REQUIREMENTS:
+1. Header: MUST start with `from manim import *`
+2. Class Structure: Define a class inheriting from `MovingCameraScene` (e.g., `class GenScene(MovingCameraScene):`) - this enables camera operations like zoom/pan via `self.camera.frame`
+3. Method: All logic must be inside the `def construct(self):` method
+4. SYNTAX: Ensure ALL parentheses, brackets, and function calls are properly closed
+5. Colors: Use ONLY these valid Manim color constants:
+   - Basic: WHITE, BLACK, GRAY, GREY, LIGHT_GRAY, DARK_GRAY
+   - Primary: RED, GREEN, BLUE, YELLOW, ORANGE, PINK, PURPLE, TEAL, GOLD, MAROON
+   - Variants: RED_A, RED_B, RED_C, RED_D, RED_E, GREEN_A, GREEN_B, GREEN_C, GREEN_D, GREEN_E,
+     BLUE_A, BLUE_B, BLUE_C, BLUE_D, BLUE_E, YELLOW_A, YELLOW_B, YELLOW_C, YELLOW_D, YELLOW_E
+   - NEVER use: DARK_GREEN, LIGHT_GREEN, DARK_BLUE, LIGHT_BLUE, DARK_RED, LIGHT_RED (these don't exist!)
+6. Text: Use `Text()` objects for strings. Avoid `Tex()` or `MathTex()` unless necessary
+7. Positioning: Use `.next_to()`, `.move_to()`, or `.shift()` to arrange elements
+8. Animations: Use ONLY these valid animations:
+   - Write(), Create(), FadeIn(), FadeOut(), GrowFromCenter(), ShrinkToCenter()
+   - Transform(), ReplacementTransform(), MoveToTarget(), ApplyMethod()
+   - Rotate(), Indicate(), Flash(), ShowCreation() - DO NOT use lowercase like 'flash'
+   - For custom effects use .animate.method() (e.g., obj.animate.scale(2), obj.animate.shift(UP))
+9. Pacing: Include `self.wait(1)` between major animation groups
+
+OUTPUT FORMAT:
+Provide ONLY the raw Python code. Do not wrap in markdown blocks (no ```python). Do not include conversational text.
+"""
+
+        response = await hf_wrapper.text_generation(
+            model=selected_model,
+            prompt=prompt,
+            max_new_tokens=2048,
+            temperature=0.3,
+        )
+
+        logger.info(f"Successfully generated Manim code for concept: {concept}")
+
+        return CallToolResult(
+            content=[
+                TextContent(
+                    type="text",
+                    text=f"Generated Manim Code:\n\n```python\n{response}\n```",
+                )
+            ]
+        )
+
+    except Exception as e:
+        logger.error(f"Code generation failed: {str(e)}")
+        return CallToolResult(
+            content=[
+                TextContent(type="text", text=f"Code generation failed: {str(e)}")
+            ],
+            isError=True,
+        )
+
+
+async def refine_animation(
+    hf_wrapper: HFInferenceWrapper, arguments: Dict[str, Any]
+) -> CallToolResult:
+    """
+    Refine animation code based on feedback.
+
+    Uses a code LLM to improve existing Manim code based on:
+    - User feedback or error messages
+    - Specific improvement goals
+    - Visual or educational quality issues
+
+    Args:
+        hf_wrapper: HuggingFace inference wrapper instance
+        arguments: Dictionary containing:
+            - original_code (str): The original Manim code to refine
+            - feedback (str): Feedback or error message about the code
+            - improvement_goals (list, optional): List of specific improvement goals
+            - model (str, optional): Hugging Face model to use
+
+    Returns:
+        CallToolResult with the refined Manim code
+    """
+    original_code = arguments["original_code"]
+    feedback = arguments["feedback"]
+    improvement_goals = arguments.get("improvement_goals", [])
+    model = arguments.get("model")
+
+    try:
+        model_config = ModelConfig()
+        selected_model = model or model_config.code_models[0]
+
+        prompt = f"""
+You are a Manim Code Repair Agent. Your task is to rewrite the FULL Python script to fix issues or apply improvements.
+
+Previous Code:
+{original_code}
+
+User Feedback/Error:
+{feedback}
+
+Improvement Goals:
+{", ".join(improvement_goals)}
+
+INSTRUCTIONS:
+1. Output the COMPLETE corrected script, including `from manim import *`.
+2. Do not output diffs or partial snippets.
+3. Ensure the class inherits from `MovingCameraScene` and uses `def construct(self):`.
+4. Fix logic errors based on the feedback.
+5. Animations: Use ONLY valid animations like Write(), FadeIn(), FadeOut(), Create(), Flash(), Transform() - NEVER lowercase!
+6. Colors: Use ONLY these valid Manim color constants:
+   - Basic: WHITE, BLACK, GRAY, GREY, LIGHT_GRAY, DARK_GRAY
+   - Primary: RED, GREEN, BLUE, YELLOW, ORANGE, PINK, PURPLE, TEAL, GOLD, MAROON
+   - Variants: RED_A, RED_B, RED_C, RED_D, RED_E, GREEN_A, GREEN_B, GREEN_C, GREEN_D, GREEN_E,
+     BLUE_A, BLUE_B, BLUE_C, BLUE_D, BLUE_E, YELLOW_A, YELLOW_B, YELLOW_C, YELLOW_D, YELLOW_E
+   - NEVER use: DARK_GREEN, LIGHT_GREEN, DARK_BLUE, LIGHT_BLUE, DARK_RED, LIGHT_RED (these don't exist!)
+   - For darker/lighter variants, use the letter suffixes (e.g., GREEN_E for dark green, GREEN_A for light green).
+
+OUTPUT:
+Return ONLY the raw Python code. No markdown backticks. No explanation.
+"""
+
+        response = await hf_wrapper.text_generation(
+            model=selected_model,
+            prompt=prompt,
+            max_new_tokens=2048,
+            temperature=0.3,
+        )
+
+        logger.info("Successfully refined animation code")
+
+        return CallToolResult(
+            content=[
+                TextContent(
+                    type="text",
+                    text=f"Refined Manim Code:\n\n```python\n{response}\n```",
+                )
+            ]
+        )
+
+    except Exception as e:
+        logger.error(f"Code refinement failed: {str(e)}")
+        return CallToolResult(
+            content=[
+                TextContent(type="text", text=f"Code refinement failed: {str(e)}")
+            ],
+            isError=True,
+        )

manim_mcp/tools/planning.py

@@ -0,0 +1,102 @@
+"""
+Planning Tools for Manim MCP Server
+
+This module provides tools for concept planning and ideation for STEM animations.
+"""
+
+import json
+import logging
+from typing import Any, Dict, Optional
+
+from mcp.types import CallToolResult, TextContent
+
+from utils.hf_wrapper import HFInferenceWrapper, ModelConfig
+
+logger = logging.getLogger(__name__)
+
+
+async def plan_concept(
+    hf_wrapper: HFInferenceWrapper, arguments: Dict[str, Any]
+) -> CallToolResult:
+    """
+    Plan a STEM concept for animation.
+
+    Uses a text LLM to create a structured animation plan including:
+    - Learning objectives
+    - Visual metaphors
+    - Scene flow with timestamps
+    - Educational value assessment
+
+    Args:
+        hf_wrapper: HuggingFace inference wrapper instance
+        arguments: Dictionary containing:
+            - topic (str): The STEM topic to create an animation for
+            - target_audience (str): Target audience level (elementary, middle_school, high_school, college, general)
+            - animation_length_minutes (float, optional): Desired animation length in minutes
+            - model (str, optional): Hugging Face model to use
+
+    Returns:
+        CallToolResult with the structured animation plan
+    """
+    topic = arguments["topic"]
+    target_audience = arguments["target_audience"]
+    animation_length = arguments.get("animation_length_minutes", 2.0)
+    model = arguments.get("model")
+
+    try:
+        model_config = ModelConfig()
+        selected_model = model or model_config.text_models[0]
+
+        prompt = f"""
+You are a STEM Curriculum Designer. Create a structured animation plan.
+
+Topic: {topic}
+Audience: {target_audience}
+Length: {animation_length} min
+
+Return a valid JSON object with exactly these keys:
+{{
+    "learning_objectives": ["string", "string"],
+    "visual_metaphors": ["string", "string"],
+    "scene_flow": [
+        {{
+            "timestamp": "0:00-0:30",
+            "action": "description of visual action",
+            "voiceover": "key narration points"
+        }}
+    ],
+    "estimated_educational_value": "string"
+}}
+
+Do not include markdown formatting like ```json. Return raw JSON only.
+"""
+
+        response = await hf_wrapper.text_generation(
+            model=selected_model,
+            prompt=prompt,
+            max_new_tokens=1024,
+            temperature=0.7,
+        )
+
+        logger.info(f"Successfully planned concept for topic: {topic}")
+
+        return CallToolResult(
+            content=[
+                TextContent(
+                    type="text",
+                    text=f"Animation Concept Plan:\n\n{response}",
+                )
+            ]
+        )
+
+    except Exception as e:
+        logger.error(f"Concept planning failed: {str(e)}")
+        return CallToolResult(
+            content=[
+                TextContent(
+                    type="text",
+                    text=f"Concept planning failed: {str(e)}",
+                )
+            ],
+            isError=True,
+        )

manim_mcp/tools/quiz.py

@@ -0,0 +1,102 @@
+"""
+Quiz Tools for Manim MCP Server
+
+This module provides tools for generating educational quiz questions based on STEM concepts.
+"""
+
+import logging
+from typing import Any, Dict, Optional
+
+from mcp.types import CallToolResult, TextContent
+
+from utils.hf_wrapper import HFInferenceWrapper, ModelConfig
+
+logger = logging.getLogger(__name__)
+
+
+async def generate_quiz(
+    hf_wrapper: HFInferenceWrapper, arguments: Dict[str, Any]
+) -> CallToolResult:
+    """
+    Generate quiz questions for a STEM concept.
+
+    Uses a text LLM to create educational quiz questions that assess
+    understanding of the animation concept. Questions can be multiple choice,
+    true/false, or short answer format.
+
+    Args:
+        hf_wrapper: HuggingFace inference wrapper instance
+        arguments: Dictionary containing:
+            - concept (str): The STEM concept to create quiz questions for
+            - difficulty (str): Difficulty level (easy, medium, hard)
+            - num_questions (int): Number of questions to generate
+            - question_types (list, optional): Types of questions (default: ["multiple_choice"])
+            - model (str, optional): Hugging Face model to use
+
+    Returns:
+        CallToolResult with the generated quiz questions in JSON format
+    """
+    concept = arguments["concept"]
+    difficulty = arguments["difficulty"]
+    num_questions = arguments["num_questions"]
+    question_types = arguments.get("question_types", ["multiple_choice"])
+    model = arguments.get("model")
+
+    try:
+        model_config = ModelConfig()
+        selected_model = model or model_config.text_models[0]
+
+        prompt = f"""
+Generate {num_questions} quiz questions for the following STEM concept:
+
+Concept: {concept}
+Difficulty: {difficulty}
+Question Types: {", ".join(question_types)}
+
+For each question provide:
+1. The question
+2. Possible answers (for multiple choice)
+3. Correct answer
+4. Brief explanation
+
+Format as JSON array of question objects with this structure:
+[
+  {{
+    "question": "question text",
+    "options": ["A", "B", "C", "D"],
+    "correct_answer": "A",
+    "explanation": "why this is correct"
+  }}
+]
+
+Return only valid JSON without markdown formatting.
+"""
+
+        response = await hf_wrapper.text_generation(
+            model=selected_model,
+            prompt=prompt,
+            max_new_tokens=1024,
+            temperature=0.5,
+        )
+
+        logger.info(
+            f"Successfully generated {num_questions} quiz questions for concept: {concept}"
+        )
+
+        return CallToolResult(
+            content=[
+                TextContent(
+                    type="text",
+                    text=f"Generated Quiz Questions:\n\n{response}",
+                )
+            ]
+        )
+
+    except Exception as e:
+        logger.error(f"Quiz generation failed: {str(e)}")
+        return CallToolResult(
+            content=[
+                TextContent(type="text", text=f"Quiz generation failed: {str(e)}")
+            ],
+            isError=True,
+        )

manim_mcp/tools/rendering.py

@@ -0,0 +1,237 @@
+"""
+Rendering Tools for Manim MCP Server
+
+This module provides tools for writing and rendering Manim animations.
+"""
+
+import asyncio
+import glob
+import json
+import logging
+import os
+import shutil
+from pathlib import Path
+from typing import Any, Dict
+
+from mcp.types import CallToolResult, TextContent
+
+logger = logging.getLogger(__name__)
+
+
+async def write_manim_file(arguments: Dict[str, Any]) -> CallToolResult:
+    """
+    Write a Manim Python file to the filesystem.
+
+    Takes Manim code and writes it to a specified file path, creating
+    directories as needed.
+
+    Args:
+        arguments: Dictionary containing:
+            - filepath (str): Path where to write the Manim file
+            - code (str): Manim Python code to write
+
+    Returns:
+        CallToolResult indicating success or failure
+    """
+    filepath = arguments["filepath"]
+    code = arguments["code"]
+
+    try:
+        # Ensure directory exists
+        Path(filepath).parent.mkdir(parents=True, exist_ok=True)
+
+        # Write the file
+        with open(filepath, "w") as f:
+            f.write(code)
+
+        logger.info(f"Successfully wrote Manim file to: {filepath}")
+
+        return CallToolResult(
+            content=[
+                TextContent(
+                    type="text", text=f"Successfully wrote Manim file to {filepath}"
+                )
+            ]
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to write file: {str(e)}")
+        return CallToolResult(
+            content=[TextContent(type="text", text=f"Failed to write file: {str(e)}")],
+            isError=True,
+        )
+
+
+async def render_manim_animation(arguments: Dict[str, Any]) -> CallToolResult:
+    """
+    Render a Manim animation using local Manim installation.
+
+    Executes the Manim CLI to render an animation scene from a Python file.
+    Uses the project's .venv if available, otherwise falls back to system Manim.
+
+    Args:
+        arguments: Dictionary containing:
+            - scene_name (str): Name of the Manim scene class to render
+            - file_path (str): Path to the Manim Python file
+            - output_dir (str): Directory to save the output animation
+            - quality (str, optional): Rendering quality (low, medium, high, production_quality)
+            - format (str, optional): Output format (mp4, gif, png)
+            - frame_rate (int, optional): Frame rate (default: 30)
+
+    Returns:
+        CallToolResult with rendering status and output file location
+    """
+    scene_name = arguments["scene_name"]
+    file_path = arguments["file_path"]
+    output_dir = arguments["output_dir"]
+    quality = arguments.get("quality", "medium")
+    format_type = arguments.get("format", "mp4")
+    frame_rate = arguments.get("frame_rate", 30)
+
+    try:
+        # Ensure output directory exists
+        Path(output_dir).mkdir(parents=True, exist_ok=True)
+
+        # Map quality to manim flags
+        quality_flags = {
+            "low": "-ql",
+            "medium": "-qm",
+            "high": "-qh",
+            "production_quality": "-qp",
+        }
+        quality_flag = quality_flags.get(quality, "-qm")
+
+        # Find the project root and .venv
+        project_root = Path(__file__).resolve().parent.parent.parent
+        venv_python = project_root / ".venv" / "bin" / "python"
+        venv_manim = project_root / ".venv" / "bin" / "manim"
+
+        # Use venv manim if it exists, otherwise fall back to system manim
+        if venv_manim.exists():
+            manim_cmd = str(venv_manim)
+            logger.info(f"Using .venv manim at: {manim_cmd}")
+        else:
+            manim_cmd = "manim"
+            logger.warning(f".venv manim not found at {venv_manim}, using system manim")
+
+        # Build the manim command
+        cmd = [
+            manim_cmd,
+            quality_flag,
+            "--fps",
+            str(frame_rate),
+            "-o",
+            f"{scene_name}.{format_type}",
+            file_path,
+            scene_name,
+        ]
+
+        logger.info(f"Running Manim command: {' '.join(cmd)}")
+
+        # Execute the command with .venv in PATH
+        env = os.environ.copy()
+        if venv_manim.exists():
+            venv_bin = project_root / ".venv" / "bin"
+            env["PATH"] = f"{venv_bin}:{env.get('PATH', '')}"
+            env["VIRTUAL_ENV"] = str(project_root / ".venv")
+
+        # Execute the command
+        process = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=output_dir,
+            env=env,
+        )
+
+        stdout, stderr = await process.communicate()
+
+        if process.returncode != 0:
+            error_msg = f"Manim rendering failed:\nSTDOUT: {stdout.decode()}\nSTDERR: {stderr.decode()}"
+            logger.error(error_msg)
+            return CallToolResult(
+                content=[TextContent(type="text", text=error_msg)], isError=True
+            )
+
+        # Log output for debugging
+        logger.info(f"Manim stdout: {stdout.decode()}")
+        if stderr:
+            logger.info(f"Manim stderr: {stderr.decode()}")
+
+        # Find the output file
+        # Manim outputs to paths like: media/videos/{filename}/{resolution}/SceneName.mp4
+        quality_to_resolution = {
+            "low": ["480p15", "854x480", "480p"],
+            "medium": ["720p30", "1280x720", "720p"],
+            "high": ["1080p60", "1920x1080", "1080p"],
+            "production_quality": ["2160p60", "3840x2160", "2160p"],
+        }
+
+        resolutions = quality_to_resolution.get(quality, ["720p30"])
+
+        # Build search patterns
+        output_patterns = []
+        for res in resolutions:
+            output_patterns.extend(
+                [
+                    f"{output_dir}/media/videos/*/{res}/{scene_name}.{format_type}",
+                    f"{output_dir}/media/videos/**/{res}/{scene_name}.{format_type}",
+                ]
+            )
+
+        # Fallback patterns
+        output_patterns.extend(
+            [
+                f"{output_dir}/media/videos/*/*/{scene_name}.{format_type}",
+                f"{output_dir}/media/videos/**/{scene_name}.{format_type}",
+                f"{output_dir}/**/{scene_name}.{format_type}",
+                f"{output_dir}/{scene_name}.{format_type}",
+            ]
+        )
+
+        # Search for output file
+        output_files = []
+        for pattern in output_patterns:
+            matches = glob.glob(pattern, recursive=True)
+            if matches:
+                logger.info(f"Found output files: {matches}")
+                output_files.extend(matches)
+                break
+
+        if not output_files:
+            error_msg = f"Could not find rendered output file.\nSearched in: {output_dir}\nStdout: {stdout.decode()}"
+            logger.error(error_msg)
+            return CallToolResult(
+                content=[TextContent(type="text", text=error_msg)], isError=True
+            )
+
+        # Move output to expected location
+        output_file = output_files[0]
+        final_output = Path(output_dir) / f"{scene_name}.{format_type}"
+
+        shutil.move(output_file, final_output)
+
+        # Build success message
+        file_size = final_output.stat().st_size if final_output.exists() else 0
+        result_msg = (
+            f"Successfully rendered animation!\n"
+            f"Scene: {scene_name}\n"
+            f"Output: {final_output}\n"
+            f"Quality: {quality}\n"
+            f"Format: {format_type}\n"
+            f"Size: {file_size} bytes"
+        )
+
+        logger.info(result_msg)
+
+        return CallToolResult(content=[TextContent(type="text", text=result_msg)])
+
+    except Exception as e:
+        import traceback
+
+        error_details = traceback.format_exc()
+        error_msg = f"Error during rendering: {str(e)}\nDetails: {error_details}"
+        logger.error(error_msg)
+        return CallToolResult(
+            content=[TextContent(type="text", text=error_msg)], isError=True
+        )

manim_mcp/tools/video.py

@@ -0,0 +1,221 @@
+"""
+Video Processing Tools for Manim MCP Server
+
+This module provides tools for video processing, merging, and file management using FFmpeg.
+"""
+
+import asyncio
+import json
+import logging
+from pathlib import Path
+from typing import Any, Dict
+
+from mcp.types import CallToolResult, TextContent
+
+logger = logging.getLogger(__name__)
+
+
+async def process_video_with_ffmpeg(arguments: Dict[str, Any]) -> CallToolResult:
+    """
+    Process video files using FFmpeg.
+
+    Provides flexible video processing capabilities including conversion,
+    filtering, and combining multiple inputs.
+
+    Args:
+        arguments: Dictionary containing:
+            - input_files (list): List of input video/audio file paths
+            - output_file (str): Output file path
+            - ffmpeg_args (list, optional): Additional FFmpeg command-line arguments
+
+    Returns:
+        CallToolResult indicating success or failure
+    """
+    input_files = arguments["input_files"]
+    output_file = arguments["output_file"]
+    ffmpeg_args = arguments.get("ffmpeg_args", [])
+
+    try:
+        # Ensure output directory exists
+        Path(output_file).parent.mkdir(parents=True, exist_ok=True)
+
+        # Build FFmpeg command
+        cmd = ["ffmpeg"]
+
+        # Add input files
+        for input_file in input_files:
+            cmd.extend(["-i", input_file])
+
+        # Add additional arguments
+        cmd.extend(ffmpeg_args)
+
+        # Add output file
+        cmd.append(output_file)
+
+        logger.info(f"Running FFmpeg command: {' '.join(cmd)}")
+
+        # Execute FFmpeg
+        process = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+
+        stdout, stderr = await process.communicate()
+
+        if process.returncode != 0:
+            error_msg = f"FFmpeg processing failed:\n{stderr.decode()}"
+            logger.error(error_msg)
+            return CallToolResult(
+                content=[TextContent(type="text", text=error_msg)],
+                isError=True,
+            )
+
+        result_msg = f"Successfully processed video with FFmpeg: {output_file}"
+        logger.info(result_msg)
+
+        return CallToolResult(content=[TextContent(type="text", text=result_msg)])
+
+    except Exception as e:
+        error_msg = f"Error during FFmpeg processing: {str(e)}"
+        logger.error(error_msg)
+        return CallToolResult(
+            content=[TextContent(type="text", text=error_msg)],
+            isError=True,
+        )
+
+
+async def merge_video_audio(arguments: Dict[str, Any]) -> CallToolResult:
+    """
+    Merge video and audio files into a single output file.
+
+    Combines a video file with an audio file using FFmpeg. The video stream
+    is copied without re-encoding, while the audio is encoded to AAC.
+    The output duration matches the shorter of the two inputs.
+
+    Args:
+        arguments: Dictionary containing:
+            - video_file (str): Path to the input video file
+            - audio_file (str): Path to the input audio file
+            - output_file (str): Path to the output merged file
+
+    Returns:
+        CallToolResult indicating success or failure
+    """
+    video_file = arguments["video_file"]
+    audio_file = arguments["audio_file"]
+    output_file = arguments["output_file"]
+
+    try:
+        # Ensure output directory exists
+        Path(output_file).parent.mkdir(parents=True, exist_ok=True)
+
+        # Build FFmpeg merge command
+        cmd = [
+            "ffmpeg",
+            "-i",
+            video_file,
+            "-i",
+            audio_file,
+            "-c:v",
+            "copy",  # Copy video stream without re-encoding
+            "-c:a",
+            "aac",  # Encode audio to AAC
+            "-shortest",  # Match duration of shortest input
+            "-y",  # Overwrite output file if it exists
+            output_file,
+        ]
+
+        logger.info(f"Merging video and audio: {' '.join(cmd)}")
+
+        # Execute FFmpeg
+        process = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+
+        stdout, stderr = await process.communicate()
+
+        if process.returncode != 0:
+            error_msg = f"Video/audio merge failed:\n{stderr.decode()}"
+            logger.error(error_msg)
+            return CallToolResult(
+                content=[TextContent(type="text", text=error_msg)],
+                isError=True,
+            )
+
+        result_msg = f"Successfully merged video and audio: {output_file}"
+        logger.info(result_msg)
+
+        return CallToolResult(content=[TextContent(type="text", text=result_msg)])
+
+    except Exception as e:
+        error_msg = f"Error during video/audio merge: {str(e)}"
+        logger.error(error_msg)
+        return CallToolResult(
+            content=[TextContent(type="text", text=error_msg)],
+            isError=True,
+        )
+
+
+async def check_file_exists(arguments: Dict[str, Any]) -> CallToolResult:
+    """
+    Check if a file exists and return its metadata.
+
+    Provides information about file existence, type, size, and timestamps.
+    Useful for verifying outputs before processing or debugging file issues.
+
+    Args:
+        arguments: Dictionary containing:
+            - filepath (str): Path to the file to check
+
+    Returns:
+        CallToolResult with file metadata or error if file doesn't exist
+    """
+    filepath = arguments["filepath"]
+
+    try:
+        path = Path(filepath)
+
+        if not path.exists():
+            return CallToolResult(
+                content=[
+                    TextContent(
+                        type="text",
+                        text=f"File does not exist: {filepath}",
+                    )
+                ],
+                isError=True,
+            )
+
+        stat = path.stat()
+
+        metadata = {
+            "filepath": str(path.absolute()),
+            "exists": True,
+            "is_file": path.is_file(),
+            "is_directory": path.is_dir(),
+            "size_bytes": stat.st_size,
+            "created": stat.st_ctime,
+            "modified": stat.st_mtime,
+        }
+
+        logger.info(f"File exists: {filepath} ({stat.st_size} bytes)")
+
+        return CallToolResult(
+            content=[
+                TextContent(
+                    type="text",
+                    text=f"File metadata:\n{json.dumps(metadata, indent=2)}",
+                )
+            ]
+        )
+
+    except Exception as e:
+        error_msg = f"Error checking file: {str(e)}"
+        logger.error(error_msg)
+        return CallToolResult(
+            content=[TextContent(type="text", text=error_msg)],
+            isError=True,
+        )

manim_mcp/tools/vision.py

@@ -0,0 +1,88 @@
+"""
+Vision Tools for Manim MCP Server
+
+This module provides tools for analyzing animation frames using vision models.
+"""
+
+import logging
+from typing import Any, Dict, Optional
+
+from mcp.types import CallToolResult, TextContent
+
+from utils.hf_wrapper import HFInferenceWrapper, ModelConfig
+
+logger = logging.getLogger(__name__)
+
+
+async def analyze_frame(
+    hf_wrapper: HFInferenceWrapper, arguments: Dict[str, Any]
+) -> CallToolResult:
+    """
+    Analyze an animation frame using vision-language models.
+
+    Uses a vision model to provide feedback on:
+    - Visual clarity and composition
+    - Educational effectiveness
+    - Technical quality
+    - Suggestions for improvement
+
+    Args:
+        hf_wrapper: HuggingFace inference wrapper instance
+        arguments: Dictionary containing:
+            - image_path (str): Path to the image file to analyze
+            - analysis_type (str): Type of analysis (e.g., "quality", "educational_value", "clarity")
+            - context (str, optional): Additional context about the animation
+            - model (str, optional): Hugging Face vision model to use
+
+    Returns:
+        CallToolResult with the frame analysis feedback
+    """
+    image_path = arguments["image_path"]
+    analysis_type = arguments["analysis_type"]
+    context = arguments.get("context", "")
+    model = arguments.get("model")
+
+    try:
+        model_config = ModelConfig()
+        selected_model = model or model_config.vision_models[0]
+
+        # Read the image file
+        with open(image_path, "rb") as f:
+            image_bytes = f.read()
+
+        # Build analysis prompt
+        prompt = f"""
+Analyze this {analysis_type} for an educational animation frame.
+Context: {context}
+
+Provide specific feedback on:
+- {analysis_type.replace("_", " ").title()} assessment
+- Educational effectiveness
+- Visual clarity
+- Suggestions for improvement
+"""
+
+        # Call vision model
+        response = await hf_wrapper.vision_analysis(
+            model=selected_model,
+            image=image_bytes,
+            text=prompt,
+        )
+
+        logger.info(f"Successfully analyzed frame: {image_path} ({analysis_type})")
+
+        return CallToolResult(
+            content=[
+                TextContent(
+                    type="text",
+                    text=f"Frame Analysis ({analysis_type}):\n\n{response}",
+                )
+            ]
+        )
+
+    except Exception as e:
+        logger.error(f"Frame analysis failed: {str(e)}")
+        return CallToolResult(
+            content=[TextContent(type="text", text=f"Frame analysis failed: {str(e)}")],
+            isError=True,
+        )

mcp_servers/__init__.py

@@ -0,0 +1,12 @@
+"""
+MCP Servers for NeuroAnim.
+
+This package contains the MCP servers that provide different capabilities:
+- renderer.py: Animation rendering using Manim and FFmpeg
+- creative.py: Creative tasks using Hugging Face models
+"""
+
+from . import renderer
+from . import creative
+
+__all__ = ["renderer", "creative"]

mcp_servers/creative.py

@@ -0,0 +1,803 @@
+"""
+Creative MCP Server
+
+This MCP server provides tools for creative tasks using Hugging Face models:
+- Concept Planning (Text LLM)
+- Code Generation (Coder LLM)
+- Vision Analysis (Vision-Language LLM)
+- Text-to-Speech (Audio model)
+"""
+
+import asyncio
+import base64
+import json
+import logging
+import os
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+# Ensure project root (which contains the `utils` package) is on sys.path
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+from mcp.server import NotificationOptions, Server
+from mcp.server.models import InitializationOptions
+from mcp.server.stdio import stdio_server
+from mcp.types import (
+    CallToolResult,
+    ListToolsResult,
+    TextContent,
+    Tool,
+)
+
+from utils.hf_wrapper import HFInferenceWrapper, ModelConfig, get_hf_wrapper
+
+logger = logging.getLogger(__name__)
+
+# Create MCP server
+server = Server("neuroanim-creative")
+
+# Global HF wrapper instance
+hf_wrapper: Optional[HFInferenceWrapper] = None
+
+
+class CreativeTool:
+    """Base class for creative tools."""
+
+    @staticmethod
+    def get_hf_wrapper() -> HFInferenceWrapper:
+        """Get or create the HF wrapper instance."""
+        global hf_wrapper
+        if hf_wrapper is None:
+            api_key = os.getenv("HUGGINGFACE_API_KEY")
+            hf_wrapper = get_hf_wrapper(api_key=api_key)
+        return hf_wrapper
+
+
+@server.list_tools()
+async def list_tools() -> ListToolsResult:
+    """List available creative tools."""
+    tools = [
+        Tool(
+            name="plan_concept",
+            description="Plan a STEM concept for animation using text LLM",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "topic": {
+                        "type": "string",
+                        "description": "The STEM topic to create an animation for",
+                    },
+                    "target_audience": {
+                        "type": "string",
+                        "enum": [
+                            "elementary",
+                            "middle_school",
+                            "high_school",
+                            "college",
+                            "general",
+                        ],
+                        "description": "Target audience level",
+                    },
+                    "animation_length_minutes": {
+                        "type": "number",
+                        "description": "Desired animation length in minutes",
+                    },
+                    "model": {
+                        "type": "string",
+                        "description": "Hugging Face model to use (optional, will use default if not provided)",
+                    },
+                },
+                "required": ["topic", "target_audience"],
+            },
+        ),
+        Tool(
+            name="generate_manim_code",
+            description="Generate Manim Python code for an animation concept",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "concept": {
+                        "type": "string",
+                        "description": "The animation concept description",
+                    },
+                    "scene_description": {
+                        "type": "string",
+                        "description": "Detailed description of what should happen in the scene",
+                    },
+                    "visual_elements": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "List of visual elements to include",
+                    },
+                    "model": {
+                        "type": "string",
+                        "description": "Code model to use (optional, will use default if not provided)",
+                    },
+                },
+                "required": ["concept", "scene_description"],
+            },
+        ),
+        Tool(
+            name="analyze_frame",
+            description="Analyze an animation frame using vision model for quality assessment",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "image_path": {
+                        "type": "string",
+                        "description": "Path to the image file to analyze",
+                    },
+                    "analysis_type": {
+                        "type": "string",
+                        "enum": [
+                            "quality",
+                            "content",
+                            "educational_value",
+                            "clarity",
+                        ],
+                        "description": "Type of analysis to perform",
+                    },
+                    "context": {
+                        "type": "string",
+                        "description": "Context about what should be in the image",
+                    },
+                    "model": {
+                        "type": "string",
+                        "description": "Vision model to use (optional, will use default if not provided)",
+                    },
+                },
+                "required": ["image_path", "analysis_type"],
+            },
+        ),
+        Tool(
+            name="generate_narration",
+            description="Generate narration script for an animation",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "concept": {
+                        "type": "string",
+                        "description": "The animation concept",
+                    },
+                    "scene_description": {
+                        "type": "string",
+                        "description": "Description of the scene to narrate",
+                    },
+                    "target_audience": {
+                        "type": "string",
+                        "enum": [
+                            "elementary",
+                            "middle_school",
+                            "high_school",
+                            "college",
+                            "general",
+                        ],
+                        "description": "Target audience",
+                    },
+                    "duration_seconds": {
+                        "type": "number",
+                        "description": "Desired narration duration in seconds",
+                    },
+                    "model": {
+                        "type": "string",
+                        "description": "Text model to use (optional, will use default if not provided)",
+                    },
+                },
+                "required": ["concept", "scene_description", "target_audience"],
+            },
+        ),
+        Tool(
+            name="generate_speech",
+            description="Convert text narration to speech audio",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "text": {
+                        "type": "string",
+                        "description": "Text to convert to speech",
+                    },
+                    "voice": {
+                        "type": "string",
+                        "description": "Voice preference (optional)",
+                    },
+                    "output_path": {
+                        "type": "string",
+                        "description": "Path to save the audio file",
+                    },
+                    "model": {
+                        "type": "string",
+                        "description": "TTS model to use (optional, will use default if not provided)",
+                    },
+                },
+                "required": ["text", "output_path"],
+            },
+        ),
+        Tool(
+            name="refine_animation",
+            description="Refine and improve animation based on feedback",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "original_code": {
+                        "type": "string",
+                        "description": "Original Manim code",
+                    },
+                    "feedback": {
+                        "type": "string",
+                        "description": "Feedback or issues to address",
+                    },
+                    "improvement_goals": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "List of improvement goals",
+                    },
+                    "model": {
+                        "type": "string",
+                        "description": "Code model to use (optional, will use default if not provided)",
+                    },
+                },
+                "required": ["original_code", "feedback"],
+            },
+        ),
+        Tool(
+            name="generate_quiz",
+            description="Generate quiz questions based on animation content",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "concept": {
+                        "type": "string",
+                        "description": "The STEM concept covered in the animation",
+                    },
+                    "difficulty": {
+                        "type": "string",
+                        "enum": ["easy", "medium", "hard"],
+                        "description": "Quiz difficulty level",
+                    },
+                    "num_questions": {
+                        "type": "number",
+                        "description": "Number of questions to generate",
+                    },
+                    "question_types": {
+                        "type": "array",
+                        "items": {
+                            "type": "string",
+                            "enum": ["multiple_choice", "true_false", "short_answer"],
+                        },
+                        "description": "Types of questions to include",
+                    },
+                    "model": {
+                        "type": "string",
+                        "description": "Text model to use (optional, will use default if not provided)",
+                    },
+                },
+                "required": ["concept", "difficulty", "num_questions"],
+            },
+        ),
+    ]
+
+    return ListToolsResult(tools=tools)
+
+
+@server.call_tool()
+async def call_tool(tool_name: str, arguments: Dict[str, Any]) -> CallToolResult:
+    """Dispatch creative tool calls.
+
+    The low-level MCP server passes `(tool_name, arguments)` into this
+    handler, so we accept two positional arguments rather than a
+    `CallToolRequest` instance.
+    """
+
+    try:
+        if tool_name == "plan_concept":
+            return await plan_concept(arguments)
+        elif tool_name == "generate_manim_code":
+            return await generate_manim_code(arguments)
+        elif tool_name == "analyze_frame":
+            return await analyze_frame(arguments)
+        elif tool_name == "generate_narration":
+            return await generate_narration(arguments)
+        elif tool_name == "generate_speech":
+            return await generate_speech(arguments)
+        elif tool_name == "refine_animation":
+            return await refine_animation(arguments)
+        elif tool_name == "generate_quiz":
+            return await generate_quiz(arguments)
+        else:
+            return CallToolResult(
+                content=[TextContent(type="text", text=f"Unknown tool: {tool_name}")],
+                isError=True,
+            )
+    except Exception as e:
+        logger.error(f"Error in tool {tool_name}: {e}")
+        return CallToolResult(
+            content=[TextContent(type="text", text=f"Error: {str(e)}")],
+            isError=True,
+        )
+
+
+async def plan_concept(arguments: Dict[str, Any]) -> CallToolResult:
+    """Plan a STEM concept for animation."""
+    topic = arguments["topic"]
+    target_audience = arguments["target_audience"]
+    animation_length = arguments.get("animation_length_minutes", 2.0)
+    model = arguments.get("model")
+
+    try:
+        wrapper = CreativeTool.get_hf_wrapper()
+        model_config = ModelConfig()
+        selected_model = model or model_config.text_models[0]
+
+        prompt = f"""
+                You are a STEM Curriculum Designer. Create a structured animation plan.
+
+                Topic: {topic}
+                Audience: {target_audience}
+                Length: {animation_length} min
+
+                Return a valid JSON object with exactly these keys:
+                {{
+                    "learning_objectives": ["string", "string"],
+                    "visual_metaphors": ["string", "string"],
+                    "scene_flow": [
+                        {{
+                            "timestamp": "0:00-0:30",
+                            "action": "description of visual action",
+                            "voiceover": "key narration points"
+                        }}
+                    ],
+                    "estimated_educational_value": "string"
+                }}
+
+                Do not include markdown formatting like ```json. Return raw JSON only.
+                """
+
+        response = await wrapper.text_generation(
+            model=selected_model,
+            prompt=prompt,
+            max_new_tokens=1024,
+            temperature=0.7,
+        )
+
+        return CallToolResult(
+            content=[
+                TextContent(
+                    type="text",
+                    text=f"Animation Concept Plan:\n\n{response}",
+                )
+            ]
+        )
+
+    except Exception as e:
+        return CallToolResult(
+            content=[
+                TextContent(
+                    type="text",
+                    text=f"Concept planning failed: {str(e)}",
+                )
+            ],
+            isError=True,
+        )
+
+
+async def generate_manim_code(arguments: Dict[str, Any]) -> CallToolResult:
+    """Generate Manim Python code."""
+    concept = arguments["concept"]
+    scene_description = arguments["scene_description"]
+    visual_elements = arguments.get("visual_elements", [])
+    model = arguments.get("model")
+    previous_code = arguments.get("previous_code")
+    error_message = arguments.get("error_message")
+
+    try:
+        wrapper = CreativeTool.get_hf_wrapper()
+        model_config = ModelConfig()
+        selected_model = model or model_config.code_models[0]
+
+        # Build base prompt
+        if previous_code and error_message:
+            # This is a retry - include error feedback
+            prompt = f"""
+You are an expert animation engineer using Manim Community Edition (v0.18.0+).
+
+The previous code attempt had an error. Your task is to FIX the code.
+
+PREVIOUS CODE:
+```python
+{previous_code}
+```
+
+ERROR ENCOUNTERED:
+{error_message}
+
+TASK: Fix the error in the code above. Pay special attention to:
+- Closing all parentheses, brackets, and braces
+- Completing all function calls
+- Proper indentation
+- Valid Python syntax
+
+Concept: {concept}
+Scene Description: {scene_description}
+Visual Elements: {", ".join(visual_elements)}
+
+STRICT CODE REQUIREMENTS:
+1. Header: MUST start with `from manim import *`
+2. Class Structure: Define a class inheriting from `MovingCameraScene` (use this instead of `Scene` to enable camera zoom/pan with `self.camera.frame`)
+3. Method: All logic must be inside the `def construct(self):` method
+4. SYNTAX: Ensure ALL parentheses, brackets, and function calls are properly closed
+5. Colors: Use ONLY valid Manim colors (WHITE, BLACK, RED, GREEN, BLUE, YELLOW, ORANGE, PINK, PURPLE, TEAL, GOLD, etc.)
+6. Text: Use `Text()` objects for strings
+7. Positioning: Use `.next_to()`, `.move_to()`, or `.shift()`
+8. Animations: Use Write(), Create(), FadeIn(), FadeOut(), Transform(), Flash(), Indicate() - capitalize properly!
+9. Pacing: Include `self.wait(1)` between animations
+
+OUTPUT FORMAT:
+Provide ONLY the complete, corrected Python code. No markdown blocks. No explanations.
+"""
+        else:
+            # First attempt - generate fresh code
+            prompt = f"""
+You are an expert animation engineer using Manim Community Edition (v0.18.0+).
+Generate a complete, runnable Python script for the following request.
+
+Concept: {concept}
+Scene Description: {scene_description}
+Visual Elements: {", ".join(visual_elements)}
+
+STRICT CODE REQUIREMENTS:
+1. Header: MUST start with `from manim import *`
+2. Class Structure: Define a class inheriting from `MovingCameraScene` (e.g., `class GenScene(MovingCameraScene):`) - this enables camera operations like zoom/pan via `self.camera.frame`
+3. Method: All logic must be inside the `def construct(self):` method
+4. SYNTAX: Ensure ALL parentheses, brackets, and function calls are properly closed
+5. Colors: Use ONLY these valid Manim color constants:
+   - Basic: WHITE, BLACK, GRAY, GREY, LIGHT_GRAY, DARK_GRAY
+   - Primary: RED, GREEN, BLUE, YELLOW, ORANGE, PINK, PURPLE, TEAL, GOLD, MAROON
+   - Variants: RED_A, RED_B, RED_C, RED_D, RED_E, GREEN_A, GREEN_B, GREEN_C, GREEN_D, GREEN_E,
+     BLUE_A, BLUE_B, BLUE_C, BLUE_D, BLUE_E, YELLOW_A, YELLOW_B, YELLOW_C, YELLOW_D, YELLOW_E
+   - NEVER use: DARK_GREEN, LIGHT_GREEN, DARK_BLUE, LIGHT_BLUE, DARK_RED, LIGHT_RED (these don't exist!)
+6. Text: Use `Text()` objects for strings. Avoid `Tex()` or `MathTex()` unless necessary
+7. Positioning: Use `.next_to()`, `.move_to()`, or `.shift()` to arrange elements
+8. Animations: Use ONLY these valid animations:
+   - Write(), Create(), FadeIn(), FadeOut(), GrowFromCenter(), ShrinkToCenter()
+   - Transform(), ReplacementTransform(), MoveToTarget(), ApplyMethod()
+   - Rotate(), Indicate(), Flash(), ShowCreation() - DO NOT use lowercase like 'flash'
+   - For custom effects use .animate.method() (e.g., obj.animate.scale(2), obj.animate.shift(UP))
+9. Pacing: Include `self.wait(1)` between major animation groups
+
+OUTPUT FORMAT:
+Provide ONLY the raw Python code. Do not wrap in markdown blocks (no ```python). Do not include conversational text.
+"""
+
+        response = await wrapper.text_generation(
+            model=selected_model,
+            prompt=prompt,
+            max_new_tokens=2048,
+            temperature=0.3,
+        )
+
+        return CallToolResult(
+            content=[
+                TextContent(
+                    type="text",
+                    text=f"Generated Manim Code:\n\n```python\n{response}\n```",
+                )
+            ]
+        )
+
+    except Exception as e:
+        return CallToolResult(
+            content=[
+                TextContent(type="text", text=f"Code generation failed: {str(e)}")
+            ],
+            isError=True,
+        )
+
+
+async def analyze_frame(arguments: Dict[str, Any]) -> CallToolResult:
+    """Analyze an animation frame."""
+    image_path = arguments["image_path"]
+    analysis_type = arguments["analysis_type"]
+    context = arguments.get("context", "")
+    model = arguments.get("model")
+
+    try:
+        wrapper = CreativeTool.get_hf_wrapper()
+        model_config = ModelConfig()
+        selected_model = model or model_config.vision_models[0]
+
+        with open(image_path, "rb") as f:
+            image_bytes = f.read()
+
+        prompt = f"""
+        Analyze this {analysis_type} for an educational animation frame.
+        Context: {context}
+
+        Provide specific feedback on:
+        {analysis_type.replace("_", " ").title()} assessment
+        Educational effectiveness
+        Visual clarity
+        Suggestions for improvement
+        """
+
+        response = await wrapper.vision_analysis(
+            model=selected_model,
+            image=image_bytes,
+            text=prompt,
+        )
+
+        return CallToolResult(
+            content=[
+                TextContent(
+                    type="text",
+                    text=f"Frame Analysis ({analysis_type}):\n\n{response}",
+                )
+            ]
+        )
+
+    except Exception as e:
+        return CallToolResult(
+            content=[TextContent(type="text", text=f"Frame analysis failed: {str(e)}")],
+            isError=True,
+        )
+
+
+async def generate_narration(arguments: Dict[str, Any]) -> CallToolResult:
+    """Generate narration script."""
+    concept = arguments["concept"]
+    scene_description = arguments["scene_description"]
+    target_audience = arguments["target_audience"]
+    duration = arguments.get("duration_seconds", 30)
+    model = arguments.get("model")
+
+    try:
+        wrapper = CreativeTool.get_hf_wrapper()
+        model_config = ModelConfig()
+        selected_model = model or model_config.text_models[0]
+
+        prompt = f"""
+        Generate a narration script for an educational animation:
+
+        Concept: {concept}
+        Scene: {scene_description}
+        Target Audience: {target_audience}
+        Duration: {duration} seconds
+
+        Requirements:
+        1. Clear, engaging, and age-appropriate language
+        2. Educational value aligned with learning objectives
+        3. Natural speaking pace (approximately {duration / 150} words for {duration} seconds)
+        4. Include pauses and emphasis markers where appropriate
+        5. Make it interesting and memorable
+
+        Format as a clean script ready for text-to-speech.
+        """
+
+        response = await wrapper.text_generation(
+            model=selected_model,
+            prompt=prompt,
+            max_new_tokens=512,
+            temperature=0.6,
+        )
+
+        return CallToolResult(
+            content=[
+                TextContent(
+                    type="text",
+                    text=f"Narration Script:\n\n{response}",
+                )
+            ]
+        )
+
+    except Exception as e:
+        return CallToolResult(
+            content=[
+                TextContent(
+                    type="text",
+                    text=f"Narration generation failed: {str(e)}",
+                )
+            ],
+            isError=True,
+        )
+
+
+async def generate_speech(arguments: Dict[str, Any]) -> CallToolResult:
+    """Convert text to speech."""
+    text = arguments["text"]
+    voice = arguments.get("voice")
+    output_path = arguments["output_path"]
+    model = arguments.get("model")
+
+    try:
+        wrapper = CreativeTool.get_hf_wrapper()
+        model_config = ModelConfig()
+        selected_model = model or model_config.tts_models[0]
+
+        # Generate audio
+        audio_bytes = await wrapper.text_to_speech(
+            model=selected_model,
+            text=text,
+            voice=voice,
+        )
+
+        # Save to file
+        success = await wrapper.save_audio_to_file(audio_bytes, output_path)
+
+        if not success:
+            raise Exception("Failed to save audio file")
+
+        # Return audio info
+        audio_info = {
+            "output_path": output_path,
+            "text_length": len(text),
+            "estimated_duration": len(text) / 150,  # Rough estimate
+            "model_used": selected_model,
+        }
+
+        return CallToolResult(
+            content=[
+                TextContent(
+                    type="text",
+                    text=f"Speech generated successfully!\n\n{json.dumps(audio_info, indent=2)}",
+                )
+            ]
+        )
+
+    except Exception as e:
+        return CallToolResult(
+            content=[
+                TextContent(type="text", text=f"Speech generation failed: {str(e)}")
+            ],
+            isError=True,
+        )
+
+
+async def refine_animation(arguments: Dict[str, Any]) -> CallToolResult:
+    """Refine animation code based on feedback."""
+    original_code = arguments["original_code"]
+    feedback = arguments["feedback"]
+    improvement_goals = arguments.get("improvement_goals", [])
+    model = arguments.get("model")
+
+    try:
+        wrapper = CreativeTool.get_hf_wrapper()
+        model_config = ModelConfig()
+        selected_model = model or model_config.code_models[0]
+
+        prompt = f"""
+                You are a Manim Code Repair Agent. Your task is to rewrite the FULL Python script to fix issues or apply improvements.
+
+                Previous Code:
+                {original_code}
+
+                User Feedback/Error:
+                {feedback}
+
+                Improvement Goals:
+                {", ".join(improvement_goals)}
+
+                INSTRUCTIONS:
+                1. Output the COMPLETE corrected script, including `from manim import *`.
+                2. Do not output diffs or partial snippets.
+                3. Ensure the class inherits from `MovingCameraScene` and uses `def construct(self):`.
+                4. Fix logic errors based on the feedback.
+                5. Animations: Use ONLY valid animations like Write(), FadeIn(), FadeOut(), Create(), Flash(), Transform() - NEVER lowercase!
+                6. Colors: Use ONLY these valid Manim color constants:
+                   - Basic: WHITE, BLACK, GRAY, GREY, LIGHT_GRAY, DARK_GRAY
+                   - Primary: RED, GREEN, BLUE, YELLOW, ORANGE, PINK, PURPLE, TEAL, GOLD, MAROON
+                   - Variants: RED_A, RED_B, RED_C, RED_D, RED_E, GREEN_A, GREEN_B, GREEN_C, GREEN_D, GREEN_E,
+                     BLUE_A, BLUE_B, BLUE_C, BLUE_D, BLUE_E, YELLOW_A, YELLOW_B, YELLOW_C, YELLOW_D, YELLOW_E
+                   - NEVER use: DARK_GREEN, LIGHT_GREEN, DARK_BLUE, LIGHT_BLUE, DARK_RED, LIGHT_RED (these don't exist!)
+                   - For darker/lighter variants, use the letter suffixes (e.g., GREEN_E for dark green, GREEN_A for light green).
+
+                OUTPUT:
+                Return ONLY the raw Python code. No markdown backticks. No explanation.
+                """
+
+        response = await wrapper.text_generation(
+            model=selected_model,
+            prompt=prompt,
+            max_new_tokens=2048,
+            temperature=0.3,
+        )
+
+        return CallToolResult(
+            content=[
+                TextContent(
+                    type="text",
+                    text=f"Refined Manim Code:\n\n```python\n{response}\n```",
+                )
+            ]
+        )
+
+    except Exception as e:
+        return CallToolResult(
+            content=[
+                TextContent(type="text", text=f"Code refinement failed: {str(e)}")
+            ],
+            isError=True,
+        )
+
+
+async def generate_quiz(arguments: Dict[str, Any]) -> CallToolResult:
+    """Generate quiz questions."""
+    concept = arguments["concept"]
+    difficulty = arguments["difficulty"]
+    num_questions = arguments["num_questions"]
+    question_types = arguments.get("question_types", ["multiple_choice"])
+    model = arguments.get("model")
+
+    try:
+        wrapper = CreativeTool.get_hf_wrapper()
+        model_config = ModelConfig()
+        selected_model = model or model_config.text_models[0]
+
+        prompt = f"""
+        Generate {num_questions} quiz questions for the following STEM concept:
+
+        Concept: {concept}
+        Difficulty: {difficulty}
+        Question Types: {", ".join(question_types)}
+
+        For each question provide:
+        1. The question
+        2. Possible answers (for multiple choice)
+        3. Correct answer
+        4. Brief explanation
+
+        Format as JSON array of question objects.
+        """
+
+        response = await wrapper.text_generation(
+            model=selected_model,
+            prompt=prompt,
+            max_new_tokens=1024,
+            temperature=0.5,
+        )
+
+        return CallToolResult(
+            content=[
+                TextContent(
+                    type="text",
+                    text=f"Generated Quiz Questions:\n\n{response}",
+                )
+            ]
+        )
+
+    except Exception as e:
+        return CallToolResult(
+            content=[
+                TextContent(type="text", text=f"Quiz generation failed: {str(e)}")
+            ],
+            isError=True,
+        )
+
+
+async def main():
+    """Main entry point for the creative MCP server."""
+    # Set up logging
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    )
+
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(
+            read_stream,
+            write_stream,
+            InitializationOptions(
+                server_name="neuroanim-creative",
+                server_version="0.1.0",
+                capabilities=server.get_capabilities(
+                    notification_options=NotificationOptions(),
+                    experimental_capabilities={},
+                ),
+            ),
+        )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

mcp_servers/renderer.py

@@ -0,0 +1,1464 @@
+"""
+Renderer MCP Server
+
+This MCP server provides tools for rendering animations using Manim and
+processing videos with FFmpeg.
+"""
+
+import asyncio
+import base64
+import json
+import logging
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from blaxel.core.sandbox import SandboxInstance
+from mcp.server import NotificationOptions, Server
+from mcp.server.models import InitializationOptions
+from mcp.server.stdio import stdio_server
+from mcp.types import (
+    CallToolRequest,
+    CallToolResult,
+    ListToolsRequest,
+    ListToolsResult,
+    TextContent,
+    Tool,
+)
+from pydantic import BaseModel
+
+logger = logging.getLogger(__name__)
+
+# Create MCP server
+server = Server("neuroanim-renderer")
+
+
+class AnimationConfig(BaseModel):
+    """Configuration for Manim animations."""
+
+    scene_name: str
+    code: str
+    output_file: Optional[str] = None
+    quality: str = "medium"  # low, medium, high, production_quality
+    format: str = "mp4"  # mp4, gif, png
+    resolution: Optional[str] = None
+    frame_rate: int = 30
+
+
+class RendererTool:
+    """Base class for renderer tools."""
+
+    @staticmethod
+    def create_temp_dir() -> Path:
+        """Create a temporary directory for rendering."""
+        return Path(tempfile.mkdtemp(prefix="neuroanim_"))
+
+    @staticmethod
+    def cleanup_temp_dir(temp_dir: Path):
+        """Clean up temporary directory."""
+        import shutil
+
+        shutil.rmtree(temp_dir, ignore_errors=True)
+
+    @staticmethod
+    async def execute_sandbox_process(
+        sandbox, process_config: dict, logger, operation_name: str
+    ):
+        """Execute a sandbox process with retry logic for connection timeouts and process conflicts."""
+        import uuid
+
+        # Store original name for retries
+        original_name = process_config.get("name", "unnamed-process")
+
+        # Check for existing processes with the same name and clean them up
+        try:
+            existing_processes = await sandbox.process.list()
+            for proc in existing_processes:
+                if proc.name == original_name:
+                    logger.warning(
+                        f"Found existing process '{original_name}' (status: {proc.status}), terminating it..."
+                    )
+                    try:
+                        await sandbox.process.kill(original_name)
+                        logger.info(
+                            f"Successfully terminated process '{original_name}'"
+                        )
+                        # Wait a moment for cleanup
+                        await asyncio.sleep(1)
+                    except Exception as kill_error:
+                        logger.warning(
+                            f"Failed to kill process '{original_name}': {kill_error}"
+                        )
+                        # Continue anyway, might still work
+        except Exception as list_error:
+            logger.debug(f"Could not list existing processes: {list_error}")
+
+        # For the first attempt, use the original name
+        try:
+            result = await sandbox.process.exec(process_config)
+            return result
+        except Exception as exec_error:
+            error_str = str(exec_error).lower()
+            # Check if it's a duplicate process error
+            if "already exists" in error_str or "already running" in error_str:
+                logger.warning(
+                    f"Process {original_name} already exists, creating unique variant..."
+                )
+                # Create a unique name and retry
+                unique_name = f"{original_name}-{uuid.uuid4().hex[:8]}"
+                process_config["name"] = unique_name
+                try:
+                    result = await sandbox.process.exec(process_config)
+                    return result
+                except Exception as unique_error:
+                    logger.error(
+                        f"Unique process {unique_name} also failed: {unique_error}"
+                    )
+                    raise exec_error  # Raise original error
+            elif "timeout" in error_str or "connecttimeout" in error_str:
+                logger.warning(
+                    f"{operation_name} connection timed out, retrying after delay..."
+                )
+                await asyncio.sleep(3)  # Wait before retry
+                # For timeout, also try with a unique name to avoid conflicts
+                unique_name = f"{original_name}-{uuid.uuid4().hex[:8]}-retry"
+                process_config["name"] = unique_name
+                try:
+                    result = await sandbox.process.exec(process_config)
+                    logger.info(f"Retry successful for {operation_name}")
+                    return result
+                except Exception as retry_error:
+                    logger.error(f"Retry failed for {operation_name}: {retry_error}")
+                    raise exec_error  # Raise original error
+            else:
+                logger.error(
+                    f"{operation_name} failed with non-timeout error: {exec_error}"
+                )
+                raise exec_error
+
+    @staticmethod
+    async def read_sandbox_file(sandbox, file_path: str, logger):
+        """Read a file from sandbox with retry logic for connection timeouts."""
+        try:
+            content = await sandbox.fs.read(file_path)
+            return content
+        except Exception as read_error:
+            error_str = str(read_error).lower()
+            if "timeout" in error_str or "connecttimeout" in error_str:
+                logger.warning(
+                    f"File read from sandbox timed out, retrying after delay..."
+                )
+                await asyncio.sleep(3)  # Wait before retry
+                try:
+                    content = await sandbox.fs.read(file_path)
+                    logger.info(f"Retry successful for file read: {file_path}")
+                    return content
+                except Exception as retry_error:
+                    logger.error(f"Retry failed for file read: {retry_error}")
+                    raise read_error  # Raise original error
+            else:
+                logger.error(f"File read failed with non-timeout error: {read_error}")
+                raise read_error
+
+    @staticmethod
+    async def write_sandbox_file(sandbox, file_path: str, content: str, logger):
+        """Write a file to sandbox with retry logic for connection timeouts."""
+        try:
+            await sandbox.fs.write(file_path, content)
+            return
+        except Exception as write_error:
+            error_str = str(write_error).lower()
+            if "timeout" in error_str or "connecttimeout" in error_str:
+                logger.warning(
+                    f"File write to sandbox timed out, retrying after delay..."
+                )
+                await asyncio.sleep(3)  # Wait before retry
+                try:
+                    await sandbox.fs.write(file_path, content)
+                    logger.info(f"Retry successful for file write: {file_path}")
+                    return
+                except Exception as retry_error:
+                    logger.error(f"Retry failed for file write: {retry_error}")
+                    raise write_error  # Raise original error
+            else:
+                logger.error(f"File write failed with non-timeout error: {write_error}")
+                raise write_error
+
+
+@server.list_tools()
+async def list_tools() -> ListToolsResult:
+    """List available renderer tools."""
+    tools = [
+        Tool(
+            name="write_manim_file",
+            description="Write a Manim Python file to the filesystem",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "filepath": {
+                        "type": "string",
+                        "description": "Path where to write the Manim file",
+                    },
+                    "code": {
+                        "type": "string",
+                        "description": "Manim Python code to write",
+                    },
+                },
+                "required": ["filepath", "code"],
+            },
+        ),
+        Tool(
+            name="render_manim_animation",
+            description="Render a Manim animation using subprocess",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "scene_name": {
+                        "type": "string",
+                        "description": "Name of the Manim scene to render",
+                    },
+                    "file_path": {
+                        "type": "string",
+                        "description": "Path to the Manim Python file",
+                    },
+                    "output_dir": {
+                        "type": "string",
+                        "description": "Directory to save the output animation",
+                    },
+                    "quality": {
+                        "type": "string",
+                        "enum": ["low", "medium", "high", "production_quality"],
+                        "description": "Rendering quality (default: medium)",
+                    },
+                    "format": {
+                        "type": "string",
+                        "enum": ["mp4", "gif", "png"],
+                        "description": "Output format (default: mp4)",
+                    },
+                    "frame_rate": {
+                        "type": "integer",
+                        "description": "Frame rate (default: 30)",
+                    },
+                },
+                "required": ["scene_name", "file_path", "output_dir"],
+            },
+        ),
+        Tool(
+            name="process_video_with_ffmpeg",
+            description="Process video using FFmpeg for merging, conversion, etc.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "input_files": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "List of input video/audio files",
+                    },
+                    "output_file": {
+                        "type": "string",
+                        "description": "Output file path",
+                    },
+                    "ffmpeg_args": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "Additional FFmpeg arguments",
+                    },
+                },
+                "required": ["input_files", "output_file"],
+            },
+        ),
+        Tool(
+            name="merge_video_audio",
+            description="Merge video and audio files using FFmpeg",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "video_file": {
+                        "type": "string",
+                        "description": "Path to the video file",
+                    },
+                    "audio_file": {
+                        "type": "string",
+                        "description": "Path to the audio file",
+                    },
+                    "output_file": {
+                        "type": "string",
+                        "description": "Path to the output merged file",
+                    },
+                },
+                "required": ["video_file", "audio_file", "output_file"],
+            },
+        ),
+        Tool(
+            name="check_file_exists",
+            description="Check if a file exists and return its metadata",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "filepath": {
+                        "type": "string",
+                        "description": "Path to the file to check",
+                    }
+                },
+                "required": ["filepath"],
+            },
+        ),
+    ]
+
+    return ListToolsResult(tools=tools)
+
+
+@server.call_tool()
+async def call_tool(tool_name: str, arguments: Dict[str, Any]) -> CallToolResult:
+    """Dispatch renderer tool calls.
+
+    As with the creative server, the low-level MCP server passes
+    `(tool_name, arguments)` into this handler.
+    """
+
+    try:
+        if tool_name == "write_manim_file":
+            return await write_manim_file(arguments)
+        elif tool_name == "render_manim_animation":
+            return await render_manim_animation(arguments)
+        elif tool_name == "process_video_with_ffmpeg":
+            return await process_video_with_ffmpeg(arguments)
+        elif tool_name == "merge_video_audio":
+            return await merge_video_audio(arguments)
+        elif tool_name == "check_file_exists":
+            return await check_file_exists(arguments)
+        else:
+            return CallToolResult(
+                content=[TextContent(type="text", text=f"Unknown tool: {tool_name}")],
+                isError=True,
+            )
+    except Exception as e:
+        logger.error(f"Error in tool {tool_name}: {e}")
+        return CallToolResult(
+            content=[TextContent(type="text", text=f"Error: {str(e)}")],
+            isError=True,
+        )
+
+
+async def write_manim_file(arguments: Dict[str, Any]) -> CallToolResult:
+    """Write a Manim Python file."""
+    filepath = arguments["filepath"]
+    code = arguments["code"]
+
+    try:
+        # Ensure directory exists
+        Path(filepath).parent.mkdir(parents=True, exist_ok=True)
+
+        # Write the file
+        with open(filepath, "w") as f:
+            f.write(code)
+
+        logger.info(f"Manim file written to: {filepath}")
+
+        return CallToolResult(
+            content=[
+                TextContent(
+                    type="text", text=f"Successfully wrote Manim file to {filepath}"
+                )
+            ]
+        )
+    except Exception as e:
+        return CallToolResult(
+            content=[TextContent(type="text", text=f"Failed to write file: {str(e)}")],
+            isError=True,
+        )
+
+
+async def render_manim_animation(arguments: Dict[str, Any]) -> CallToolResult:
+    """Render a Manim animation using Blaxel sandbox execution with local fallback."""
+    scene_name = arguments["scene_name"]
+    file_path = arguments["file_path"]
+    output_dir = arguments["output_dir"]
+    quality = arguments.get("quality", "medium")
+    format_type = arguments.get("format", "mp4")
+    frame_rate = arguments.get("frame_rate", 30)
+
+    # Skip sandbox rendering and use local rendering directly with .venv
+    logger.info("Using local Manim rendering with .venv environment...")
+
+    local_result = await _render_manim_locally(
+        scene_name, file_path, output_dir, quality, format_type, frame_rate
+    )
+
+    return CallToolResult(
+        content=[TextContent(type="text", text=local_result["text"])],
+        isError=local_result.get("isError", False),
+    )
+
+
+async def _render_manim_with_sandbox(
+    scene_name: str,
+    file_path: str,
+    output_dir: str,
+    quality: str,
+    format_type: str,
+    frame_rate: int,
+) -> Dict[str, Any]:
+    """Render a Manim animation using Blaxel sandbox execution."""
+    # Map quality to manim flags
+    quality_flags = {
+        "low": "-ql",
+        "medium": "-qm",
+        "high": "-qh",
+        "production_quality": "-qp",
+    }
+    quality_flag = quality_flags.get(quality, "-qm")
+
+    try:
+        # Ensure output directory exists
+        Path(output_dir).mkdir(parents=True, exist_ok=True)
+
+        # Read the Manim code file
+        with open(file_path, "r") as f:
+            manim_code = f.read()
+
+        logger.info(f"Creating Blaxel sandbox for scene: {scene_name}")
+
+        # Sanitize scene name for valid sandbox name
+        sanitized_scene_name = scene_name.lower().replace(" ", "-").replace("_", "-")
+        # Ensure name is not too long and only contains valid characters
+        import re
+
+        sanitized_scene_name = re.sub(r"[^a-z0-9\-]", "", sanitized_scene_name)[:20]
+        if not sanitized_scene_name:
+            sanitized_scene_name = "default"
+
+        try:
+            # Create or get sandbox using Blaxel SDK
+            # Uses BL_WORKSPACE and BL_API_KEY from environment or .env file
+            logger.info(f"Creating Blaxel sandbox: manim-render-{sanitized_scene_name}")
+            try:
+                # Create sandbox with proper virtual environment
+                sandbox = await SandboxInstance.create(
+                    {
+                        "name": f"manim-render-{sanitized_scene_name}",
+                        "image": "blaxel/py-app:latest",
+                        "memory": 4096,
+                        # Use virtual environment instead of system
+                        "virtual": True,
+                    }
+                )
+                logger.info(f"Successfully created sandbox: {sandbox.metadata.name}")
+
+                # Wait a moment for sandbox to fully initialize
+                logger.info("Waiting for sandbox to initialize...")
+                await asyncio.sleep(2)
+
+            except Exception as create_error:
+                # Handle connection timeouts by retrying
+                error_str = str(create_error).lower()
+                if "timeout" in error_str or "connecttimeout" in error_str:
+                    logger.warning(
+                        "Sandbox creation connection timed out, retrying after delay..."
+                    )
+                    await asyncio.sleep(5)  # Wait longer before retry
+                    try:
+                        # Retry once
+                        sandbox = await SandboxInstance.create(
+                            {
+                                "name": f"manim-render-{sanitized_scene_name}",
+                                "image": "blaxel/py-app:latest",
+                                "memory": 4096,
+                            }
+                        )
+                        logger.info(
+                            f"Retry successful: Created sandbox: {sandbox.metadata.name}"
+                        )
+
+                        # Wait for sandbox to initialize
+                        logger.info("Waiting for sandbox to initialize after retry...")
+                        await asyncio.sleep(3)
+
+                    except Exception as retry_error:
+                        logger.error(f"Retry failed: {retry_error}")
+                        raise create_error  # Raise original error
+                else:
+                    logger.error(
+                        f"Sandbox creation failed with non-timeout error: {create_error}"
+                    )
+                    raise create_error
+        except Exception as sandbox_error:
+            error_msg = f"Failed to create Blaxel sandbox: {str(sandbox_error)}"
+            logger.error(error_msg)
+            return {"text": error_msg, "isError": True}
+
+        try:
+            # Write the Manim code to the sandbox
+            sandbox_file_path = f"/tmp/{scene_name}.py"
+            logger.info(f"Writing Manim code to sandbox: {sandbox_file_path}")
+            await RendererTool.write_sandbox_file(
+                sandbox, sandbox_file_path, manim_code, logger
+            )
+            logger.info(
+                f"Successfully wrote Manim code to sandbox: {sandbox_file_path}"
+            )
+
+            # Initialize flag for Manim installation check
+            manim_already_installed = False
+
+            # Test what's available in the sandbox
+            logger.info("Testing sandbox environment...")
+            try:
+                test_result = await RendererTool.execute_sandbox_process(
+                    sandbox,
+                    {
+                        "name": "test-environment",
+                        "command": "which python3 && python3 --version && which pip && pip --version",
+                        "wait_for_completion": True,
+                    },
+                    logger,
+                    "Environment test",
+                )
+                logger.info(f"Environment test result: {test_result}")
+
+                # Get test logs
+                try:
+                    test_logs = await sandbox.process.logs("test-environment", "all")
+                    logger.info(f"Environment test logs: {test_logs}")
+                except Exception as log_error:
+                    logger.warning(f"Could not retrieve test logs: {log_error}")
+            except Exception as test_error:
+                logger.warning(f"Environment test failed: {test_error}")
+
+            # Test if apt-get is available
+            logger.info("Testing if apt-get is available...")
+            try:
+                apt_test_result = await RendererTool.execute_sandbox_process(
+                    sandbox,
+                    {
+                        "name": "test-apt",
+                        "command": "which apt-get || echo 'apt-get not found'",
+                        "wait_for_completion": True,
+                    },
+                    logger,
+                    "Apt availability test",
+                )
+                logger.info(f"Apt test result: {apt_test_result}")
+
+                # Get apt test logs
+                try:
+                    apt_test_logs = await sandbox.process.logs("test-apt", "all")
+                    logger.info(f"Apt test logs: {apt_test_logs}")
+                except Exception as log_error:
+                    logger.warning(f"Could not retrieve apt test logs: {log_error}")
+            except Exception as apt_test_error:
+                logger.warning(f"Apt test failed: {apt_test_error}")
+
+            # Try a simple pip install first to see if it works
+            logger.info("Testing pip install...")
+            try:
+                pip_test_result = await RendererTool.execute_sandbox_process(
+                    sandbox,
+                    {
+                        "name": "test-pip",
+                        "command": "pip install --dry-run manim",
+                        "wait_for_completion": True,
+                    },
+                    logger,
+                    "Pip test",
+                )
+                logger.info(f"Pip test result: {pip_test_result}")
+
+                # Get pip test logs
+                try:
+                    pip_test_logs = await sandbox.process.logs("test-pip", "all")
+                    logger.info(f"Pip test logs: {pip_test_logs}")
+                except Exception as log_error:
+                    logger.warning(f"Could not retrieve pip test logs: {log_error}")
+            except Exception as pip_test_error:
+                logger.warning(f"Pip test failed: {pip_test_error}")
+
+            # Check if Manim is already installed
+            logger.info("Checking if Manim is already installed...")
+            try:
+                manim_check_result = await RendererTool.execute_sandbox_process(
+                    sandbox,
+                    {
+                        "name": "check-manim",
+                        "command": "python3 -c \"import manim; print('Manim version:', manim.__version__)\" || echo 'Manim not found'",
+                        "wait_for_completion": True,
+                    },
+                    logger,
+                    "Manim check",
+                )
+                logger.info(f"Manim check result: {manim_check_result}")
+
+                # Get manim check logs
+                try:
+                    manim_check_logs = await sandbox.process.logs("check-manim", "all")
+                    logger.info(f"Manim check logs: {manim_check_logs}")
+
+                    # Check if Manim is installed
+                    if "Manim version:" in str(manim_check_logs):
+                        logger.info("Manim is already installed, skipping installation")
+                        manim_already_installed = True
+                    else:
+                        logger.info(
+                            "Manim is not installed, proceeding with installation"
+                        )
+                        manim_already_installed = False
+                except Exception as log_error:
+                    logger.warning(f"Could not retrieve manim check logs: {log_error}")
+                    manim_already_installed = False
+            except Exception as manim_check_error:
+                logger.warning(f"Manim check failed: {manim_check_error}")
+                manim_already_installed = False
+
+            # Install manim and its dependencies in the sandbox
+            logger.info("Installing manim and dependencies in the sandbox...")
+
+            # Check if ffmpeg is already available
+            logger.info("Checking if ffmpeg is available...")
+            try:
+                ffmpeg_check_result = await RendererTool.execute_sandbox_process(
+                    sandbox,
+                    {
+                        "name": "check-ffmpeg",
+                        "command": "which ffmpeg || echo 'ffmpeg not found'",
+                        "wait_for_completion": True,
+                    },
+                    logger,
+                    "FFmpeg availability check",
+                )
+                logger.info(f"Ffmpeg check result: {ffmpeg_check_result}")
+
+                # Get ffmpeg check logs
+                try:
+                    ffmpeg_check_logs = await sandbox.process.logs(
+                        "check-ffmpeg", "all"
+                    )
+                    logger.info(f"Ffmpeg check logs: {ffmpeg_check_logs}")
+                except Exception as log_error:
+                    logger.warning(f"Could not retrieve ffmpeg check logs: {log_error}")
+            except Exception as ffmpeg_check_error:
+                logger.warning(f"Ffmpeg check failed: {ffmpeg_check_error}")
+
+            # Skip installation if Manim is already installed
+            if manim_already_installed:
+                logger.info(
+                    "Skipping dependencies installation as Manim is already installed"
+                )
+                manim_installed = True
+            else:
+                # Try to install system dependencies step-by-step for better reliability
+                logger.info("Installing system dependencies step-by-step...")
+
+                # First update package lists
+                try:
+                    logger.info("Updating package lists...")
+                    update_result = await RendererTool.execute_sandbox_process(
+                        sandbox,
+                        {
+                            "name": "apt-update",
+                            "command": "apt-get update",
+                            "wait_for_completion": True,
+                            "timeout": 120,
+                        },
+                        logger,
+                        "Package list update",
+                    )
+                    logger.info(f"Package update result: {update_result}")
+
+                    if update_result.status != "exited" or (
+                        hasattr(update_result, "exit_code")
+                        and update_result.exit_code != 0
+                    ):
+                        logger.warning("Package update failed, but continuing...")
+                except Exception as update_error:
+                    logger.warning(
+                        f"Package update failed: {update_error}, continuing..."
+                    )
+
+                # Install ffmpeg
+                try:
+                    logger.info("Installing ffmpeg...")
+                    ffmpeg_result = await RendererTool.execute_sandbox_process(
+                        sandbox,
+                        {
+                            "name": "install-ffmpeg",
+                            "command": "apt-get install -y ffmpeg",
+                            "wait_for_completion": True,
+                            "timeout": 180,
+                        },
+                        logger,
+                        "FFmpeg installation",
+                    )
+                    logger.info(f"FFmpeg installation result: {ffmpeg_result}")
+
+                    if ffmpeg_result.status != "exited" or (
+                        hasattr(ffmpeg_result, "exit_code")
+                        and ffmpeg_result.exit_code != 0
+                    ):
+                        logger.warning("FFmpeg installation failed, but continuing...")
+                except Exception as ffmpeg_error:
+                    logger.warning(
+                        f"FFmpeg installation failed: {ffmpeg_error}, continuing..."
+                    )
+
+                # Install libcairo2-dev
+                try:
+                    logger.info("Installing libcairo2-dev...")
+                    cairo_result = await RendererTool.execute_sandbox_process(
+                        sandbox,
+                        {
+                            "name": "install-cairo",
+                            "command": "apt-get install -y libcairo2-dev",
+                            "wait_for_completion": True,
+                            "timeout": 180,
+                        },
+                        logger,
+                        "Cairo installation",
+                    )
+                    logger.info(f"Cairo installation result: {cairo_result}")
+
+                    if cairo_result.status != "exited" or (
+                        hasattr(cairo_result, "exit_code")
+                        and cairo_result.exit_code != 0
+                    ):
+                        logger.warning("Cairo installation failed, but continuing...")
+                except Exception as cairo_error:
+                    logger.warning(
+                        f"Cairo installation failed: {cairo_error}, continuing..."
+                    )
+
+                # Install Python dependencies - try lighter alternatives first
+                logger.info("Installing Python dependencies...")
+                manim_installed = False
+
+                # Try installing manim Community Edition (lighter than full manim)
+                install_commands = [
+                    ("pip install manimlib", "manimlib installation"),
+                    ("pip install manim", "full manim installation"),
+                    (
+                        "pip install --no-deps manim && pip install numpy scipy matplotlib",
+                        "minimal manim with deps",
+                    ),
+                ]
+
+                for install_cmd, description in install_commands:
+                    if manim_installed:
+                        break
+
+                    try:
+                        logger.info(f"Trying {description}: {install_cmd}")
+                        install_result = await RendererTool.execute_sandbox_process(
+                            sandbox,
+                            {
+                                "name": "install-manim-attempt",
+                                "command": install_cmd,
+                                "wait_for_completion": True,
+                                "timeout": 600,  # 10 minute timeout
+                            },
+                            logger,
+                            description,
+                        )
+                        logger.info(f"{description} result: {install_result}")
+
+                        if install_result.status == "exited" and (
+                            not hasattr(install_result, "exit_code")
+                            or install_result.exit_code == 0
+                        ):
+                            logger.info(f"Successfully installed with: {install_cmd}")
+                            manim_installed = True
+
+                            # Verify installation
+                            try:
+                                verify_result = await RendererTool.execute_sandbox_process(
+                                    sandbox,
+                                    {
+                                        "name": "verify-manim",
+                                        "command": "python3 -c \"import manim; print('Manim version:', getattr(manim, '__version__', 'unknown'))\"",
+                                        "wait_for_completion": True,
+                                        "timeout": 30,
+                                    },
+                                    logger,
+                                    "Manim verification",
+                                )
+                                logger.info(
+                                    f"Manim verification result: {verify_result}"
+                                )
+                            except Exception as verify_error:
+                                logger.warning(
+                                    f"Manim verification failed: {verify_error}"
+                                )
+                        else:
+                            logger.warning(
+                                f"{description} failed, trying next option..."
+                            )
+
+                        # Get installation logs for debugging (for the last attempt)
+                        try:
+                            install_logs = await sandbox.process.logs(
+                                "install-manim-attempt", "all"
+                            )
+                            logger.info(f"Manim installation logs: {install_logs}")
+                        except Exception as log_error:
+                            logger.warning(
+                                f"Could not retrieve installation logs: {log_error}"
+                            )
+
+                        # Check if the last installation attempt was successful
+                        if install_result.status != "exited" or (
+                            hasattr(install_result, "exit_code")
+                            and install_result.exit_code != 0
+                        ):
+                            error_msg = f"Manim installation failed with status: {install_result.status}"
+                            if hasattr(install_result, "exit_code"):
+                                error_msg += f", exit code: {install_result.exit_code}"
+
+                            # Try to get more detailed logs
+                            try:
+                                install_logs = await sandbox.process.logs(
+                                    "install-manim-attempt", "all"
+                                )
+                                error_msg += f"\nLogs: {install_logs}"
+                            except Exception as log_error:
+                                error_msg += f"\nCould not retrieve logs: {log_error}"
+
+                            logger.error(error_msg)
+                            # Don't return error here, continue to check if any installation worked
+
+                    except Exception as install_error:
+                        # Handle timeout specifically
+                        error_str = str(install_error).lower()
+                        if "timeout" in error_str or "readtimeout" in error_str:
+                            logger.warning(
+                                "Pip install manim timed out - this might be OK if packages were already installed or partially installed"
+                            )
+                            # Try to check if manim was actually installed despite timeout
+                            try:
+                                manim_check_after = await RendererTool.execute_sandbox_process(
+                                    sandbox,
+                                    {
+                                        "name": "check-manim-after-install",
+                                        "command": "python3 -c \"import manim; print('Manim available after install timeout')\" || echo 'Manim not available after install timeout'",
+                                        "wait_for_completion": True,
+                                    },
+                                    logger,
+                                    "Post-install Manim check",
+                                )
+                                logger.info(
+                                    f"Post-install Manim check result: {manim_check_after}"
+                                )
+
+                                # Get logs
+                                try:
+                                    check_logs = await sandbox.process.logs(
+                                        "check-manim-after-install", "all"
+                                    )
+                                    logger.info(
+                                        f"Post-install check logs: {check_logs}"
+                                    )
+
+                                    if "manim available" in str(check_logs).lower():
+                                        logger.info(
+                                            "Manim appears to be installed despite timeout, continuing..."
+                                        )
+                                        manim_installed = True
+                                    else:
+                                        logger.warning(
+                                            "Manim not available after install timeout, may cause render failure"
+                                        )
+                                except Exception as log_error:
+                                    logger.warning(
+                                        f"Could not check post-install logs: {log_error}"
+                                    )
+                            except Exception as check_error:
+                                logger.warning(
+                                    f"Could not verify Manim installation after timeout: {check_error}"
+                                )
+                        else:
+                            import traceback
+
+                            error_details = traceback.format_exc()
+                            error_msg = f"Error during pip install manim: {str(install_error)}\nDetails: {error_details}"
+
+                            # Try to get installation logs for debugging
+                            try:
+                                install_logs = await sandbox.process.logs(
+                                    "install-manim-attempt", "all"
+                                )
+                                error_msg += f"\nInstallation logs: {install_logs}"
+                            except Exception as log_error:
+                                error_msg += f"\nCould not retrieve installation logs: {log_error}"
+
+                            logger.error(error_msg)
+                            # Don't return error here, continue to try other installation methods
+
+                        logger.warning(f"{description} failed: {install_error}")
+                        continue
+
+            # Final check: ensure Manim is actually installed before proceeding to render
+            if not manim_already_installed and not manim_installed:
+                logger.warning(
+                    "Manim installation appears to have failed, attempting final verification..."
+                )
+
+                # Final verification attempt
+                try:
+                    final_check = await RendererTool.execute_sandbox_process(
+                        sandbox,
+                        {
+                            "name": "final-manim-check",
+                            "command": "python3 -c \"import manim; print('SUCCESS: Manim is available')\" || echo 'FAILED: Manim not available'",
+                            "wait_for_completion": True,
+                            "timeout": 30,
+                        },
+                        logger,
+                        "Final Manim availability check",
+                    )
+
+                    # Get logs to check result
+                    try:
+                        check_logs = await sandbox.process.logs(
+                            "final-manim-check", "all"
+                        )
+                        if "SUCCESS" in str(check_logs):
+                            logger.info(
+                                "Final check confirms Manim is available, proceeding with render"
+                            )
+                            manim_installed = True
+                        else:
+                            error_msg = f"Final verification shows Manim is not available. Installation appears to have failed.\nCheck logs: {check_logs}"
+                            logger.error(error_msg)
+                            return {"text": error_msg, "isError": True}
+                    except Exception as log_error:
+                        logger.warning(
+                            f"Could not retrieve final check logs: {log_error}"
+                        )
+
+                except Exception as final_check_error:
+                    error_msg = f"Cannot verify Manim installation: {final_check_error}"
+                    logger.error(error_msg)
+                    return {"text": error_msg, "isError": True}
+
+            # Run the Manim render command - try different possible commands
+            render_commands = [
+                f"manim {quality_flag} --fps {frame_rate} -o {scene_name}.{format_type} {sandbox_file_path} {scene_name}",
+                f"python3 -m manim {quality_flag} --fps {frame_rate} -o {scene_name}.{format_type} {sandbox_file_path} {scene_name}",
+                f"manimce {quality_flag} --fps {frame_rate} -o {scene_name}.{format_type} {sandbox_file_path} {scene_name}",
+            ]
+
+            render_success = False
+            render_result = None
+
+            for cmd in render_commands:
+                if render_success:
+                    break
+
+                logger.info(f"Trying render command: {cmd}")
+                try:
+                    render_result = await RendererTool.execute_sandbox_process(
+                        sandbox,
+                        {
+                            "name": "render-manim",
+                            "command": cmd,
+                            "wait_for_completion": True,
+                            "timeout": 600,  # 10 minute timeout for rendering
+                        },
+                        logger,
+                        f"Manim rendering with '{cmd}'",
+                    )
+                    logger.info(f"Render result: {render_result}")
+
+                    if render_result.status == "exited" and (
+                        not hasattr(render_result, "exit_code")
+                        or render_result.exit_code == 0
+                    ):
+                        logger.info(f"Successfully rendered with: {cmd}")
+                        render_success = True
+                    else:
+                        logger.warning(
+                            f"Render failed with command '{cmd}', trying next option..."
+                        )
+
+                except Exception as render_error:
+                    logger.warning(f"Render failed with '{cmd}': {render_error}")
+                    continue
+                # Check if rendering was successful
+                if not render_success:
+                    error_msg = "All render command attempts failed."
+
+                    # Try to get logs for debugging from the last attempt
+                    try:
+                        logs = await sandbox.process.logs("render-manim", "all")
+                        error_msg += f"\nLast render logs: {logs}"
+                    except Exception as log_error:
+                        error_msg += f"\nCould not retrieve logs: {log_error}"
+
+                    logger.error(error_msg)
+                    return {"text": error_msg, "isError": True}
+            # If we get here and render wasn't successful, it's an error
+            if not render_success:
+                error_msg = "Manim rendering failed - no working render command found"
+                logger.error(error_msg)
+                return {"text": error_msg, "isError": True}
+
+        except Exception as render_error:
+            # Handle timeout specifically
+            error_str = str(render_error).lower()
+            if "timeout" in error_str or "readtimeout" in error_str:
+                logger.warning(
+                    "Manim render timed out - this indicates a long-running render process"
+                )
+                # Try to continue and check if output was generated
+            else:
+                error_msg = f"Error during manim rendering: {str(render_error)}"
+                logger.error(error_msg)
+                return {"text": error_msg, "isError": True}
+
+            # Find the output file in the sandbox
+            # Manim typically outputs to media/videos/{scene_name}/{quality}/
+            possible_paths = [
+                f"/tmp/media/videos/{scene_name}/{quality}/{scene_name}.{format_type}",
+                f"/tmp/media/videos/{scene_name.lower()}/{quality}/{scene_name}.{format_type}",
+                f"/tmp/{scene_name}.{format_type}",
+                f"/root/media/videos/{scene_name}/{quality}/{scene_name}.{format_type}",
+            ]
+
+            output_content = None
+            found_path = None
+
+            for sandbox_path in possible_paths:
+                try:
+                    output_content = await RendererTool.read_sandbox_file(
+                        sandbox, sandbox_path, logger
+                    )
+                    found_path = sandbox_path
+                    logger.info(f"Found output at: {sandbox_path}")
+                    break
+                except Exception:
+                    continue
+
+            if not output_content:
+                # List files to debug
+                try:
+                    ls_result = await RendererTool.execute_sandbox_process(
+                        sandbox,
+                        {
+                            "name": "find-output",
+                            "command": "find /tmp -name '*.mp4' -o -name '*.gif' 2>/dev/null || true",
+                            "wait_for_completion": True,
+                        },
+                        logger,
+                        "Find output files",
+                    )
+                    find_logs = await sandbox.process.logs("find-output", "stdout")
+                    logger.info(f"Found video files: {find_logs}")
+                except Exception:
+                    pass
+
+                error_msg = f"Could not find rendered output file. Searched paths: {possible_paths}"
+                logger.error(error_msg)
+                return {"text": error_msg, "isError": True}
+
+            # Write the output to local filesystem
+            output_path = Path(output_dir) / f"{scene_name}.{format_type}"
+
+            # Handle the content - it may be base64 encoded or bytes
+            if isinstance(output_content, str):
+                try:
+                    decoded_content = base64.b64decode(output_content)
+                    with open(output_path, "wb") as f:
+                        f.write(decoded_content)
+                except Exception:
+                    with open(output_path, "w") as f:
+                        f.write(output_content)
+            elif isinstance(output_content, (bytes, bytearray)):
+                with open(output_path, "wb") as f:
+                    f.write(output_content)
+            else:
+                with open(output_path, "wb") as f:
+                    f.write(output_content)
+
+            result_msg = (
+                f"Successfully rendered animation using Blaxel sandbox!\n"
+                f"Scene: {scene_name}\n"
+                f"Output file: {output_path}\n"
+                f"Quality: {quality}\n"
+                f"Format: {format_type}\n"
+                f"File size: {output_path.stat().st_size if output_path.exists() else 'Unknown'} bytes"
+            )
+
+            logger.info(result_msg)
+            return {"text": result_msg, "isError": False}
+
+        finally:
+            # Clean up sandbox
+            try:
+                await SandboxInstance.delete(sandbox.metadata.name)
+                logger.info(f"Deleted sandbox: {sandbox.metadata.name}")
+            except Exception as cleanup_error:
+                logger.warning(f"Failed to delete sandbox: {cleanup_error}")
+
+    except asyncio.TimeoutError:
+        error_msg = "Blaxel sandbox execution timed out"
+        logger.error(error_msg)
+        return {"text": error_msg, "isError": True}
+    except Exception as e:
+        # Get detailed exception information
+        import traceback
+
+        error_details = traceback.format_exc()
+        error_msg = (
+            f"Error during Blaxel sandbox rendering: {str(e)}\nDetails: {error_details}"
+        )
+        logger.error(error_msg)
+        return {"text": error_msg, "isError": True}
+
+
+async def _render_manim_locally(
+    scene_name: str,
+    file_path: str,
+    output_dir: str,
+    quality: str,
+    format_type: str,
+    frame_rate: int,
+) -> Dict[str, Any]:
+    """Render a Manim animation using local Manim installation."""
+    try:
+        # Ensure output directory exists
+        Path(output_dir).mkdir(parents=True, exist_ok=True)
+
+        # Map quality to manim flags
+        quality_flags = {
+            "low": "-ql",
+            "medium": "-qm",
+            "high": "-qh",
+            "production_quality": "-qp",
+        }
+        quality_flag = quality_flags.get(quality, "-qm")
+
+        # Find the project root and .venv
+        # Assume the project root contains .venv directory
+        project_root = Path(__file__).resolve().parent.parent
+        venv_python = project_root / ".venv" / "bin" / "python"
+        venv_manim = project_root / ".venv" / "bin" / "manim"
+
+        # Use venv manim if it exists, otherwise fall back to system manim
+        if venv_manim.exists():
+            manim_cmd = str(venv_manim)
+            logger.info(f"Using .venv manim at: {manim_cmd}")
+        else:
+            manim_cmd = "manim"
+            logger.warning(f".venv manim not found at {venv_manim}, using system manim")
+
+        # Build the manim command
+        cmd = [
+            manim_cmd,
+            quality_flag,
+            "--fps",
+            str(frame_rate),
+            "-o",
+            f"{scene_name}.{format_type}",
+            file_path,
+            scene_name,
+        ]
+
+        logger.info(f"Running local Manim command: {' '.join(cmd)}")
+
+        # Execute the command with .venv in PATH
+        env = os.environ.copy()
+        if venv_manim.exists():
+            venv_bin = project_root / ".venv" / "bin"
+            env["PATH"] = f"{venv_bin}:{env.get('PATH', '')}"
+            env["VIRTUAL_ENV"] = str(project_root / ".venv")
+
+        # Execute the command
+        process = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=output_dir,  # Run in output directory
+            env=env,
+        )
+
+        stdout, stderr = await process.communicate()
+
+        if process.returncode != 0:
+            error_msg = f"Local Manim rendering failed:\nSTDOUT: {stdout.decode()}\nSTDERR: {stderr.decode()}"
+            logger.error(error_msg)
+            return {"text": error_msg, "isError": True}
+
+        # Log the stdout for debugging
+        logger.info(f"Manim stdout: {stdout.decode()}")
+        logger.info(f"Manim stderr: {stderr.decode()}")
+
+        # Find the output file
+        # Manim typically outputs to media/videos/{filename}/{quality}/
+        import glob
+
+        # First, let's see what files actually exist in the output directory
+        logger.info(f"Listing all files in output directory: {output_dir}")
+        try:
+            all_files = list(Path(output_dir).rglob("*"))
+            logger.info(f"Found {len(all_files)} files/dirs:")
+            for f in all_files[:50]:  # Log first 50 to avoid spam
+                logger.info(f"  - {f}")
+        except Exception as list_error:
+            logger.warning(f"Could not list files: {list_error}")
+
+        # Manim outputs to paths like: media/videos/{filename}/{resolution}/SceneName.mp4
+        # where resolution is like: 720p30, 480p15, 1080p60, 2160p60
+        # Quality flags map to resolutions:
+        # -ql (low): 480p15
+        # -qm (medium): 720p30
+        # -qh (high): 1080p60
+        # -qp (production): 2160p60
+
+        # Map quality to likely resolution folder names
+        quality_to_resolution = {
+            "low": ["480p15", "854x480", "480p"],
+            "medium": ["720p30", "1280x720", "720p"],
+            "high": ["1080p60", "1920x1080", "1080p"],
+            "production_quality": ["2160p60", "3840x2160", "2160p"],
+        }
+
+        resolutions = quality_to_resolution.get(quality, ["720p30"])
+
+        output_patterns = []
+
+        # Search with specific resolutions
+        for res in resolutions:
+            output_patterns.extend(
+                [
+                    f"{output_dir}/media/videos/*/{res}/{scene_name}.{format_type}",
+                    f"{output_dir}/media/videos/**/{res}/{scene_name}.{format_type}",
+                ]
+            )
+
+        # Fallback: search all resolution patterns
+        output_patterns.extend(
+            [
+                f"{output_dir}/media/videos/*/*/{scene_name}.{format_type}",
+                f"{output_dir}/media/videos/**/{scene_name}.{format_type}",
+                f"{output_dir}/videos/*/*/{scene_name}.{format_type}",
+                f"{output_dir}/**/{scene_name}.{format_type}",
+                f"{output_dir}/{scene_name}.{format_type}",
+            ]
+        )
+
+        output_files = []
+        for pattern in output_patterns:
+            logger.info(f"Trying pattern: {pattern}")
+            matches = glob.glob(pattern, recursive=True)
+            if matches:
+                logger.info(f"  Found matches: {matches}")
+                output_files.extend(matches)
+                break
+
+        if not output_files:
+            error_msg = f"Could not find rendered output file.\nSearched patterns: {output_patterns}\nStdout: {stdout.decode()}\nStderr: {stderr.decode()}"
+            logger.error(error_msg)
+            return {"text": error_msg, "isError": True}
+
+        output_file = output_files[0]  # Take the first match
+        final_output = Path(output_dir) / f"{scene_name}.{format_type}"
+
+        # Move the output file to the expected location
+        import shutil
+
+        shutil.move(output_file, final_output)
+
+        result_msg = (
+            f"Successfully rendered animation locally!\n"
+            f"Scene: {scene_name}\n"
+            f"Output file: {final_output}\n"
+            f"Quality: {quality}\n"
+            f"Format: {format_type}\n"
+            f"File size: {final_output.stat().st_size if final_output.exists() else 'Unknown'} bytes"
+        )
+
+        logger.info(result_msg)
+        return {"text": result_msg, "isError": False}
+
+    except Exception as e:
+        import traceback
+
+        error_details = traceback.format_exc()
+        error_msg = (
+            f"Error during local Manim rendering: {str(e)}\nDetails: {error_details}"
+        )
+        logger.error(error_msg)
+        return {"text": error_msg, "isError": True}
+
+
+async def process_video_with_ffmpeg(arguments: Dict[str, Any]) -> CallToolResult:
+    """Process video using FFmpeg."""
+    input_files = arguments["input_files"]
+    output_file = arguments["output_file"]
+    ffmpeg_args = arguments.get("ffmpeg_args", [])
+
+    try:
+        # Ensure output directory exists
+        Path(output_file).parent.mkdir(parents=True, exist_ok=True)
+
+        # Build FFmpeg command
+        cmd = ["ffmpeg"]
+
+        # Add input files
+        for input_file in input_files:
+            cmd.extend(["-i", input_file])
+
+        # Add additional arguments
+        cmd.extend(ffmpeg_args)
+
+        # Add output file
+        cmd.append(output_file)
+
+        logger.info(f"Running FFmpeg command: {' '.join(cmd)}")
+
+        process = await asyncio.create_subprocess_exec(
+            *cmd, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE
+        )
+
+        stdout, stderr = await process.communicate()
+
+        if process.returncode != 0:
+            error_msg = f"FFmpeg processing failed: {stderr.decode()}"
+            logger.error(error_msg)
+            return CallToolResult(
+                content=[TextContent(type="text", text=error_msg)], isError=True
+            )
+
+        result_msg = f"Successfully processed video with FFmpeg: {output_file}"
+        logger.info(result_msg)
+
+        return CallToolResult(content=[TextContent(type="text", text=result_msg)])
+
+    except Exception as e:
+        error_msg = f"Error during FFmpeg processing: {str(e)}"
+        logger.error(error_msg)
+        return CallToolResult(
+            content=[TextContent(type="text", text=error_msg)], isError=True
+        )
+
+
+async def merge_video_audio(arguments: Dict[str, Any]) -> CallToolResult:
+    """Merge video and audio files."""
+    video_file = arguments["video_file"]
+    audio_file = arguments["audio_file"]
+    output_file = arguments["output_file"]
+
+    try:
+        # Ensure output directory exists
+        Path(output_file).parent.mkdir(parents=True, exist_ok=True)
+
+        # Build FFmpeg merge command
+        cmd = [
+            "ffmpeg",
+            "-i",
+            video_file,
+            "-i",
+            audio_file,
+            "-c:v",
+            "copy",
+            "-c:a",
+            "aac",
+            "-shortest",
+            "-y",  # Overwrite output file
+            output_file,
+        ]
+
+        logger.info(f"Merging video and audio: {' '.join(cmd)}")
+
+        process = await asyncio.create_subprocess_exec(
+            *cmd, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE
+        )
+
+        stdout, stderr = await process.communicate()
+
+        if process.returncode != 0:
+            error_msg = f"Video/audio merge failed: {stderr.decode()}"
+            logger.error(error_msg)
+            return CallToolResult(
+                content=[TextContent(type="text", text=error_msg)], isError=True
+            )
+
+        result_msg = f"Successfully merged video and audio: {output_file}"
+        logger.info(result_msg)
+
+        return CallToolResult(content=[TextContent(type="text", text=result_msg)])
+
+    except Exception as e:
+        error_msg = f"Error during video/audio merge: {str(e)}"
+        logger.error(error_msg)
+        return CallToolResult(
+            content=[TextContent(type="text", text=error_msg)], isError=True
+        )
+
+
+async def check_file_exists(arguments: Dict[str, Any]) -> CallToolResult:
+    """Check if a file exists and return its metadata."""
+    filepath = arguments["filepath"]
+
+    try:
+        path = Path(filepath)
+
+        if not path.exists():
+            return CallToolResult(
+                content=[
+                    TextContent(type="text", text=f"File does not exist: {filepath}")
+                ],
+                isError=True,
+            )
+
+        stat = path.stat()
+
+        metadata = {
+            "filepath": str(path.absolute()),
+            "exists": True,
+            "is_file": path.is_file(),
+            "is_directory": path.is_dir(),
+            "size_bytes": stat.st_size,
+            "created": stat.st_ctime,
+            "modified": stat.st_mtime,
+        }
+
+        return CallToolResult(
+            content=[
+                TextContent(
+                    type="text", text=f"File metadata: {json.dumps(metadata, indent=2)}"
+                )
+            ]
+        )
+
+    except Exception as e:
+        return CallToolResult(
+            content=[TextContent(type="text", text=f"Error checking file: {str(e)}")],
+            isError=True,
+        )
+
+
+async def main():
+    """Main entry point for the renderer MCP server."""
+    # Set up logging
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    )
+
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(
+            read_stream,
+            write_stream,
+            InitializationOptions(
+                server_name="neuroanim-renderer",
+                server_version="0.1.0",
+                capabilities=server.get_capabilities(
+                    notification_options=NotificationOptions(),
+                    experimental_capabilities={},
+                ),
+            ),
+        )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

neuroanim/__init__.py

@@ -0,0 +1,19 @@
+"""
+NeuroAnim - LangGraph-based Animation Pipeline
+
+This package provides a modular, graph-based workflow for generating
+educational STEM animations using Manim, AI models, and TTS.
+
+The pipeline uses LangGraph to coordinate multiple agent nodes that handle:
+- Concept planning
+- Code generation
+- Rendering
+- Audio generation
+- Video processing
+"""
+
+from neuroanim.graph.state import AnimationState, create_initial_state
+from neuroanim.graph.workflow import run_animation_pipeline
+
+__version__ = "0.1.0"
+__all__ = ["run_animation_pipeline", "create_initial_state", "AnimationState"]

neuroanim/agents/__init__.py

@@ -0,0 +1,10 @@
+"""
+NeuroAnim Agents Module
+
+This module contains agent node implementations for the LangGraph workflow.
+Each agent node handles a specific step in the animation generation pipeline.
+"""
+
+from neuroanim.agents.nodes import AnimationNodes
+
+__all__ = ["AnimationNodes"]

neuroanim/agents/nodes.py

@@ -0,0 +1,574 @@
+"""
+LangGraph Agent Nodes for NeuroAnim Pipeline
+
+This module contains all the node functions used in the LangGraph workflow.
+Each node represents a step in the animation generation pipeline and
+communicates with the Manim MCP server to perform its task.
+"""
+
+import ast
+import json
+import logging
+import re
+import tempfile
+import time
+from pathlib import Path
+from typing import Any, Dict
+
+from mcp import ClientSession
+
+from neuroanim.graph.state import AnimationState
+from utils.tts import TTSGenerator
+
+logger = logging.getLogger(__name__)
+
+
+class AnimationNodes:
+    """Container for all animation pipeline nodes."""
+
+    def __init__(
+        self,
+        mcp_session: ClientSession,
+        tts_generator: TTSGenerator,
+        work_dir: Path,
+        output_dir: Path,
+    ):
+        """
+        Initialize the animation nodes.
+
+        Args:
+            mcp_session: MCP client session for tool calls
+            tts_generator: TTS generator instance
+            work_dir: Working directory for temporary files
+            output_dir: Output directory for final files
+        """
+        self.mcp_session = mcp_session
+        self.tts_generator = tts_generator
+        self.work_dir = work_dir
+        self.output_dir = output_dir
+
+    async def call_mcp_tool(
+        self, tool_name: str, arguments: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Call an MCP tool and return the result.
+
+        Args:
+            tool_name: Name of the tool to call
+            arguments: Arguments to pass to the tool
+
+        Returns:
+            Dictionary with 'text' and 'isError' keys
+        """
+        try:
+            result = await self.mcp_session.call_tool(tool_name, arguments)
+
+            if hasattr(result, "content") and result.content:
+                content = result.content[0]
+                if hasattr(content, "text"):
+                    return {
+                        "text": content.text,
+                        "isError": getattr(result, "isError", False),
+                    }
+
+            return {"text": str(result), "isError": False}
+
+        except Exception as e:
+            logger.error(f"MCP tool call failed for {tool_name}: {e}")
+            return {"text": f"Tool call failed: {str(e)}", "isError": True}
+
+    async def initialize_node(self, state: AnimationState) -> AnimationState:
+        """
+        Initialize the pipeline state and working directories.
+
+        Args:
+            state: Current animation state
+
+        Returns:
+            Updated state with initialized paths and metadata
+        """
+        logger.info("🚀 Initializing animation pipeline")
+
+        state["start_time"] = time.time()
+        state["work_dir"] = str(self.work_dir)
+        state["output_dir"] = str(self.output_dir)
+        state["current_step"] = "initialization"
+        state["completed_steps"].append("initialization")
+
+        logger.info(f"Working directory: {self.work_dir}")
+        logger.info(f"Output directory: {self.output_dir}")
+
+        return state
+
+    async def plan_concept_node(self, state: AnimationState) -> AnimationState:
+        """
+        Plan the animation concept using AI.
+
+        Args:
+            state: Current animation state
+
+        Returns:
+            Updated state with concept plan
+        """
+        logger.info("📋 Planning concept...")
+        state["current_step"] = "concept_planning"
+
+        try:
+            result = await self.call_mcp_tool(
+                "plan_concept",
+                {
+                    "topic": state["topic"],
+                    "target_audience": state["target_audience"],
+                    "animation_length_minutes": state["animation_length_minutes"],
+                },
+            )
+
+            if result["isError"]:
+                state["errors"].append(f"Concept planning failed: {result['text']}")
+                return state
+
+            concept_plan = result["text"]
+            state["concept_plan"] = concept_plan
+
+            # Try to parse JSON from the concept plan
+            try:
+                # Extract JSON if it's embedded in the response
+                json_match = re.search(r"\{.*\}", concept_plan, re.DOTALL)
+                if json_match:
+                    plan_data = json.loads(json_match.group())
+                    state["learning_objectives"] = plan_data.get(
+                        "learning_objectives", []
+                    )
+                    state["visual_metaphors"] = plan_data.get("visual_metaphors", [])
+                    state["scene_flow"] = plan_data.get("scene_flow", [])
+            except json.JSONDecodeError:
+                logger.warning("Could not parse concept plan as JSON")
+
+            state["completed_steps"].append("concept_planning")
+            logger.info("✅ Concept planning completed")
+
+        except Exception as e:
+            logger.error(f"Concept planning failed: {e}")
+            state["errors"].append(f"Concept planning error: {str(e)}")
+
+        return state
+
+    async def generate_narration_node(self, state: AnimationState) -> AnimationState:
+        """
+        Generate narration script for the animation.
+
+        Args:
+            state: Current animation state
+
+        Returns:
+            Updated state with narration text
+        """
+        logger.info("🎙️  Generating narration...")
+        state["current_step"] = "narration_generation"
+
+        try:
+            duration_seconds = int(state["animation_length_minutes"] * 60)
+
+            result = await self.call_mcp_tool(
+                "generate_narration",
+                {
+                    "concept": state["topic"],
+                    "scene_description": state.get("concept_plan", ""),
+                    "target_audience": state["target_audience"],
+                    "duration_seconds": duration_seconds,
+                },
+            )
+
+            if result["isError"]:
+                state["errors"].append(f"Narration generation failed: {result['text']}")
+                return state
+
+            # Extract narration text from response
+            narration_text = result["text"]
+            if "Narration Script:" in narration_text:
+                narration_text = narration_text.split("Narration Script:")[-1].strip()
+
+            state["narration_text"] = narration_text
+            state["narration_duration"] = duration_seconds
+            state["completed_steps"].append("narration_generation")
+
+            logger.info("✅ Narration generation completed")
+
+        except Exception as e:
+            logger.error(f"Narration generation failed: {e}")
+            state["errors"].append(f"Narration generation error: {str(e)}")
+
+        return state
+
+    async def generate_code_node(self, state: AnimationState) -> AnimationState:
+        """
+        Generate Manim code for the animation.
+
+        Args:
+            state: Current animation state
+
+        Returns:
+            Updated state with generated code
+        """
+        logger.info("💻 Generating Manim code...")
+        state["current_step"] = "code_generation"
+
+        try:
+            # Check if this is a retry
+            previous_code = None
+            error_message = None
+            if state["code_generation_attempts"] > 0:
+                previous_code = state.get("manim_code")
+                if state.get("previous_code_errors"):
+                    error_message = state["previous_code_errors"][-1]
+
+            state["code_generation_attempts"] += 1
+
+            arguments = {
+                "concept": state["topic"],
+                "scene_description": state.get("concept_plan", ""),
+                "visual_elements": ["text", "shapes", "animations"],
+            }
+
+            if previous_code and error_message:
+                arguments["previous_code"] = previous_code
+                arguments["error_message"] = error_message
+                logger.info(
+                    f"Retrying code generation (attempt {state['code_generation_attempts']})"
+                )
+
+            result = await self.call_mcp_tool("generate_manim_code", arguments)
+
+            if result["isError"]:
+                state["errors"].append(f"Code generation failed: {result['text']}")
+                return state
+
+            # Extract Python code from response
+            code_text = result["text"]
+            manim_code = self._extract_python_code(code_text)
+
+            # Validate syntax
+            validation_error = self._validate_python_syntax(manim_code)
+            if validation_error:
+                logger.warning(f"Code validation failed: {validation_error}")
+                if not state.get("previous_code_errors"):
+                    state["previous_code_errors"] = []
+                state["previous_code_errors"].append(validation_error)
+                state["warnings"].append(f"Code validation issue: {validation_error}")
+            else:
+                logger.info("✅ Code validation passed")
+
+            state["manim_code"] = manim_code
+            state["scene_name"] = self._extract_scene_name(manim_code)
+            state["completed_steps"].append("code_generation")
+
+            logger.info(f"✅ Code generation completed (scene: {state['scene_name']})")
+
+        except Exception as e:
+            logger.error(f"Code generation failed: {e}")
+            state["errors"].append(f"Code generation error: {str(e)}")
+
+        return state
+
+    async def write_file_node(self, state: AnimationState) -> AnimationState:
+        """
+        Write the Manim code to a file.
+
+        Args:
+            state: Current animation state
+
+        Returns:
+            Updated state with file path
+        """
+        logger.info("📝 Writing Manim file...")
+        state["current_step"] = "file_writing"
+
+        try:
+            manim_file = Path(state["work_dir"]) / "animation.py"
+            state["manim_file_path"] = str(manim_file)
+
+            result = await self.call_mcp_tool(
+                "write_manim_file",
+                {"filepath": str(manim_file), "code": state["manim_code"]},
+            )
+
+            if result["isError"]:
+                state["errors"].append(f"File writing failed: {result['text']}")
+                return state
+
+            state["completed_steps"].append("file_writing")
+            logger.info(f"✅ Manim file written to {manim_file}")
+
+        except Exception as e:
+            logger.error(f"File writing failed: {e}")
+            state["errors"].append(f"File writing error: {str(e)}")
+
+        return state
+
+    async def render_animation_node(self, state: AnimationState) -> AnimationState:
+        """
+        Render the Manim animation.
+
+        Args:
+            state: Current animation state
+
+        Returns:
+            Updated state with rendered video path
+        """
+        logger.info("🎬 Rendering animation...")
+        state["current_step"] = "rendering"
+
+        try:
+            result = await self.call_mcp_tool(
+                "render_manim_animation",
+                {
+                    "scene_name": state["scene_name"],
+                    "file_path": state["manim_file_path"],
+                    "output_dir": state["work_dir"],
+                    "quality": state["rendering_quality"],
+                    "format": state["rendering_format"],
+                    "frame_rate": state["frame_rate"],
+                },
+            )
+
+            if result["isError"]:
+                state["errors"].append(f"Rendering failed: {result['text']}")
+                return state
+
+            # Find the rendered video file
+            video_file = (
+                Path(state["work_dir"])
+                / f"{state['scene_name']}.{state['rendering_format']}"
+            )
+            if not video_file.exists():
+                state["errors"].append(f"Rendered video not found at {video_file}")
+                return state
+
+            state["video_file_path"] = str(video_file)
+            state["completed_steps"].append("rendering")
+
+            logger.info(f"✅ Animation rendered: {video_file}")
+
+        except Exception as e:
+            logger.error(f"Rendering failed: {e}")
+            state["errors"].append(f"Rendering error: {str(e)}")
+
+        return state
+
+    async def generate_audio_node(self, state: AnimationState) -> AnimationState:
+        """
+        Generate speech audio from narration text.
+
+        Args:
+            state: Current animation state
+
+        Returns:
+            Updated state with audio file path
+        """
+        logger.info("🔊 Generating speech audio...")
+        state["current_step"] = "audio_generation"
+
+        try:
+            audio_file = Path(state["work_dir"]) / "narration.mp3"
+            state["audio_file_path"] = str(audio_file)
+
+            # Use TTS generator with automatic fallback
+            tts_result = await self.tts_generator.generate_speech(
+                text=state["narration_text"], output_path=audio_file, voice="rachel"
+            )
+
+            logger.info(f"Audio generated with {tts_result['provider']}")
+
+            # Validate audio file
+            validation = self.tts_generator.validate_audio_file(audio_file)
+            if not validation["valid"]:
+                state["warnings"].append(
+                    f"Audio validation warning: {validation.get('error', 'Unknown issue')}"
+                )
+            else:
+                logger.info(
+                    f"Audio validated: {validation.get('duration', 'N/A')}s, {validation.get('size', 0)} bytes"
+                )
+
+            state["completed_steps"].append("audio_generation")
+            logger.info(f"✅ Audio generated: {audio_file}")
+
+        except Exception as e:
+            logger.error(f"Audio generation failed: {e}")
+            state["errors"].append(f"Audio generation error: {str(e)}")
+
+        return state
+
+    async def merge_video_audio_node(self, state: AnimationState) -> AnimationState:
+        """
+        Merge video and audio into final output.
+
+        Args:
+            state: Current animation state
+
+        Returns:
+            Updated state with final output path
+        """
+        logger.info("🎞️  Merging video and audio...")
+        state["current_step"] = "video_audio_merge"
+
+        try:
+            final_output = Path(state["output_dir"]) / state["output_filename"]
+            state["final_output_path"] = str(final_output)
+
+            result = await self.call_mcp_tool(
+                "merge_video_audio",
+                {
+                    "video_file": state["video_file_path"],
+                    "audio_file": state["audio_file_path"],
+                    "output_file": str(final_output),
+                },
+            )
+
+            if result["isError"]:
+                state["errors"].append(f"Video/audio merge failed: {result['text']}")
+                return state
+
+            state["completed_steps"].append("video_audio_merge")
+            logger.info(f"✅ Video and audio merged: {final_output}")
+
+        except Exception as e:
+            logger.error(f"Video/audio merge failed: {e}")
+            state["errors"].append(f"Merge error: {str(e)}")
+
+        return state
+
+    async def generate_quiz_node(self, state: AnimationState) -> AnimationState:
+        """
+        Generate quiz questions for the topic.
+
+        Args:
+            state: Current animation state
+
+        Returns:
+            Updated state with quiz content
+        """
+        logger.info("❓ Generating quiz...")
+        state["current_step"] = "quiz_generation"
+
+        try:
+            result = await self.call_mcp_tool(
+                "generate_quiz",
+                {
+                    "concept": state["topic"],
+                    "difficulty": "medium",
+                    "num_questions": 3,
+                    "question_types": ["multiple_choice"],
+                },
+            )
+
+            if result["isError"]:
+                state["warnings"].append(f"Quiz generation failed: {result['text']}")
+                state["quiz_content"] = "Quiz generation failed"
+            else:
+                state["quiz_content"] = result["text"]
+                # Try to parse quiz questions
+                try:
+                    json_match = re.search(r"\[.*\]", result["text"], re.DOTALL)
+                    if json_match:
+                        state["quiz_questions"] = json.loads(json_match.group())
+                except json.JSONDecodeError:
+                    logger.warning("Could not parse quiz as JSON")
+
+            state["completed_steps"].append("quiz_generation")
+            logger.info("✅ Quiz generation completed")
+
+        except Exception as e:
+            logger.error(f"Quiz generation failed: {e}")
+            state["warnings"].append(f"Quiz generation error: {str(e)}")
+            state["quiz_content"] = "Quiz generation failed"
+
+        return state
+
+    async def finalize_node(self, state: AnimationState) -> AnimationState:
+        """
+        Finalize the pipeline and compute metadata.
+
+        Args:
+            state: Current animation state
+
+        Returns:
+            Final state with metadata
+        """
+        logger.info("🏁 Finalizing pipeline...")
+        state["current_step"] = "finalization"
+
+        state["end_time"] = time.time()
+        state["total_duration"] = state["end_time"] - state["start_time"]
+
+        # Check if pipeline succeeded
+        if not state["errors"] and state.get("final_output_path"):
+            state["success"] = True
+            logger.info(
+                f"✅ Pipeline completed successfully in {state['total_duration']:.2f}s"
+            )
+        else:
+            state["success"] = False
+            logger.error(f"❌ Pipeline failed with {len(state['errors'])} error(s)")
+
+        state["completed_steps"].append("finalization")
+
+        return state
+
+    # Helper methods
+
+    def _extract_python_code(self, response_text: str) -> str:
+        """Extract Python code from markdown response."""
+        if "```python" in response_text:
+            start = response_text.find("```python") + 9
+            end = response_text.find("```", start)
+            if end == -1:
+                end = len(response_text)
+            return response_text[start:end].strip()
+        elif "```" in response_text:
+            start = response_text.find("```") + 3
+            end = response_text.find("```", start)
+            if end == -1:
+                end = len(response_text)
+            return response_text[start:end].strip()
+        else:
+            return response_text.strip()
+
+    def _extract_scene_name(self, code: str) -> str:
+        """Extract the scene class name from Manim code."""
+        try:
+            tree = ast.parse(code)
+            for node in ast.walk(tree):
+                if isinstance(node, ast.ClassDef):
+                    # Check if it inherits from Scene or MovingCameraScene
+                    for base in node.bases:
+                        if isinstance(base, ast.Name) and base.id in [
+                            "Scene",
+                            "MovingCameraScene",
+                            "ThreeDScene",
+                        ]:
+                            return node.name
+        except SyntaxError:
+            pass
+
+        # Fallback: use regex
+        match = re.search(r"class\s+(\w+)\s*\(.*Scene.*\):", code)
+        if match:
+            return match.group(1)
+
+        return "GenScene"
+
+    def _validate_python_syntax(self, code: str) -> str | None:
+        """
+        Validate Python code syntax.
+
+        Returns:
+            Error message if validation fails, None if valid
+        """
+        try:
+            ast.parse(code)
+            return None
+        except SyntaxError as e:
+            return f"Syntax error at line {e.lineno}: {e.msg}"
+        except Exception as e:
+            return f"Validation error: {str(e)}"

neuroanim/graph/__init__.py

@@ -0,0 +1,16 @@
+"""
+NeuroAnim Graph Module
+
+This module contains the LangGraph workflow definition and state management
+for the animation generation pipeline.
+"""
+
+from neuroanim.graph.state import AnimationState, create_initial_state
+from neuroanim.graph.workflow import create_animation_workflow, run_animation_pipeline
+
+__all__ = [
+    "AnimationState",
+    "create_initial_state",
+    "create_animation_workflow",
+    "run_animation_pipeline",
+]

neuroanim/graph/state.py

@@ -0,0 +1,157 @@
+"""
+LangGraph State Definition for NeuroAnim Pipeline
+
+This module defines the state structure that flows through the animation
+generation workflow. The state is updated by each node in the graph.
+"""
+
+from typing import Any, Dict, List, Optional, TypedDict
+
+
+class AnimationState(TypedDict, total=False):
+    """
+    State for the animation generation pipeline.
+
+    This state is passed through all nodes in the LangGraph workflow.
+    Each node reads from and writes to this state to coordinate the
+    animation generation process.
+    """
+
+    # Input Parameters
+    topic: str
+    target_audience: str
+    animation_length_minutes: float
+    output_filename: str
+
+    # Concept Planning
+    concept_plan: Optional[str]
+    learning_objectives: Optional[List[str]]
+    visual_metaphors: Optional[List[str]]
+    scene_flow: Optional[List[Dict[str, str]]]
+
+    # Narration
+    narration_text: Optional[str]
+    narration_duration: Optional[float]
+
+    # Code Generation
+    manim_code: Optional[str]
+    scene_name: Optional[str]
+    code_generation_attempts: int
+    previous_code_errors: Optional[List[str]]
+
+    # File Paths
+    work_dir: Optional[str]
+    output_dir: Optional[str]
+    manim_file_path: Optional[str]
+    video_file_path: Optional[str]
+    audio_file_path: Optional[str]
+    final_output_path: Optional[str]
+
+    # Rendering
+    rendering_quality: str
+    rendering_format: str
+    frame_rate: int
+
+    # Analysis & Feedback
+    frame_analysis: Optional[str]
+    visual_quality_score: Optional[float]
+    needs_refinement: bool
+    refinement_feedback: Optional[str]
+
+    # Quiz
+    quiz_content: Optional[str]
+    quiz_questions: Optional[List[Dict[str, Any]]]
+
+    # Error Handling
+    errors: List[str]
+    warnings: List[str]
+    current_step: str
+    retry_count: Dict[str, int]
+    max_retries: int
+
+    # Status
+    success: bool
+    completed_steps: List[str]
+
+    # Metadata
+    start_time: Optional[float]
+    end_time: Optional[float]
+    total_duration: Optional[float]
+
+
+def create_initial_state(
+    topic: str,
+    target_audience: str = "general",
+    animation_length_minutes: float = 2.0,
+    output_filename: str = "animation.mp4",
+    rendering_quality: str = "medium",
+    rendering_format: str = "mp4",
+    frame_rate: int = 30,
+    max_retries: int = 3,
+) -> AnimationState:
+    """
+    Create the initial state for the animation pipeline.
+
+    Args:
+        topic: The STEM topic to animate
+        target_audience: Target audience level
+        animation_length_minutes: Desired animation length
+        output_filename: Name for the final output file
+        rendering_quality: Manim rendering quality
+        rendering_format: Output video format
+        frame_rate: Video frame rate
+        max_retries: Maximum retry attempts per step
+
+    Returns:
+        Initial AnimationState with default values
+    """
+    return AnimationState(
+        # Input parameters
+        topic=topic,
+        target_audience=target_audience,
+        animation_length_minutes=animation_length_minutes,
+        output_filename=output_filename,
+        # Initialize optional fields
+        concept_plan=None,
+        learning_objectives=None,
+        visual_metaphors=None,
+        scene_flow=None,
+        narration_text=None,
+        narration_duration=None,
+        manim_code=None,
+        scene_name=None,
+        code_generation_attempts=0,
+        previous_code_errors=None,
+        # File paths
+        work_dir=None,
+        output_dir=None,
+        manim_file_path=None,
+        video_file_path=None,
+        audio_file_path=None,
+        final_output_path=None,
+        # Rendering config
+        rendering_quality=rendering_quality,
+        rendering_format=rendering_format,
+        frame_rate=frame_rate,
+        # Analysis
+        frame_analysis=None,
+        visual_quality_score=None,
+        needs_refinement=False,
+        refinement_feedback=None,
+        # Quiz
+        quiz_content=None,
+        quiz_questions=None,
+        # Error handling
+        errors=[],
+        warnings=[],
+        current_step="initialization",
+        retry_count={},
+        max_retries=max_retries,
+        # Status
+        success=False,
+        completed_steps=[],
+        # Metadata
+        start_time=None,
+        end_time=None,
+        total_duration=None,
+    )

neuroanim/graph/workflow.py

@@ -0,0 +1,265 @@
+"""
+LangGraph Workflow Definition for NeuroAnim Pipeline
+
+This module defines the complete animation generation workflow using LangGraph.
+The workflow coordinates multiple agent nodes to transform a STEM topic into
+an educational animation with narration.
+"""
+
+import logging
+import tempfile
+from pathlib import Path
+from typing import Any, Dict
+
+from langgraph.graph import END, StateGraph
+
+from neuroanim.agents.nodes import AnimationNodes
+from neuroanim.graph.state import AnimationState, create_initial_state
+
+logger = logging.getLogger(__name__)
+
+
+def should_retry_code_generation(state: AnimationState) -> str:
+    """
+    Determine if code generation should be retried.
+
+    Args:
+        state: Current animation state
+
+    Returns:
+        Next node name: "generate_code" for retry, "write_file" to proceed
+    """
+    if (
+        state.get("previous_code_errors")
+        and state["code_generation_attempts"] < state["max_retries"]
+    ):
+        logger.info(
+            f"Code has errors, retrying (attempt {state['code_generation_attempts']}/{state['max_retries']})"
+        )
+        return "generate_code"
+    return "write_file"
+
+
+def should_continue_after_error(state: AnimationState) -> str:
+    """
+    Determine if pipeline should continue after errors.
+
+    Args:
+        state: Current animation state
+
+    Returns:
+        Next node name or END
+    """
+    if state["errors"]:
+        logger.error(f"Pipeline encountered {len(state['errors'])} error(s), stopping")
+        return "finalize"
+    return "next"
+
+
+def create_animation_workflow(nodes: AnimationNodes) -> StateGraph:
+    """
+    Create the LangGraph workflow for animation generation.
+
+    The workflow follows this sequence:
+    1. Initialize - Set up directories and state
+    2. Plan Concept - Generate animation concept plan
+    3. Generate Narration - Create narration script
+    4. Generate Code - Create Manim code (with retry logic)
+    5. Write File - Save code to file
+    6. Render Animation - Execute Manim rendering
+    7. Generate Audio - Create speech audio
+    8. Merge Video/Audio - Combine into final output
+    9. Generate Quiz - Create assessment questions
+    10. Finalize - Compute metadata and complete
+
+    Args:
+        nodes: AnimationNodes instance with all node functions
+
+    Returns:
+        Compiled StateGraph ready for execution
+    """
+    # Create the graph
+    workflow = StateGraph(AnimationState)
+
+    # Add all nodes
+    workflow.add_node("initialize", nodes.initialize_node)
+    workflow.add_node("plan_concept", nodes.plan_concept_node)
+    workflow.add_node("generate_narration", nodes.generate_narration_node)
+    workflow.add_node("generate_code", nodes.generate_code_node)
+    workflow.add_node("write_file", nodes.write_file_node)
+    workflow.add_node("render_animation", nodes.render_animation_node)
+    workflow.add_node("generate_audio", nodes.generate_audio_node)
+    workflow.add_node("merge_video_audio", nodes.merge_video_audio_node)
+    workflow.add_node("generate_quiz", nodes.generate_quiz_node)
+    workflow.add_node("finalize", nodes.finalize_node)
+
+    # Set entry point
+    workflow.set_entry_point("initialize")
+
+    # Define the workflow edges (sequential flow with error checking)
+
+    # Initialize -> Plan Concept
+    workflow.add_edge("initialize", "plan_concept")
+
+    # Plan Concept -> Check for errors -> Generate Narration
+    workflow.add_conditional_edges(
+        "plan_concept",
+        lambda state: "generate_narration" if not state["errors"] else "finalize",
+    )
+
+    # Generate Narration -> Check for errors -> Generate Code
+    workflow.add_conditional_edges(
+        "generate_narration",
+        lambda state: "generate_code" if not state["errors"] else "finalize",
+    )
+
+    # Generate Code -> Check syntax -> Retry or Write File
+    workflow.add_conditional_edges(
+        "generate_code",
+        should_retry_code_generation,
+    )
+
+    # Write File -> Check for errors -> Render
+    workflow.add_conditional_edges(
+        "write_file",
+        lambda state: "render_animation" if not state["errors"] else "finalize",
+    )
+
+    # Render -> Check for errors -> Generate Audio
+    workflow.add_conditional_edges(
+        "render_animation",
+        lambda state: "generate_audio" if not state["errors"] else "finalize",
+    )
+
+    # Generate Audio -> Check for errors -> Merge
+    workflow.add_conditional_edges(
+        "generate_audio",
+        lambda state: "merge_video_audio" if not state["errors"] else "finalize",
+    )
+
+    # Merge -> Check for errors -> Generate Quiz
+    workflow.add_conditional_edges(
+        "merge_video_audio",
+        lambda state: "generate_quiz" if not state["errors"] else "finalize",
+    )
+
+    # Generate Quiz -> Finalize (quiz errors are non-critical)
+    workflow.add_edge("generate_quiz", "finalize")
+
+    # Finalize -> END
+    workflow.add_edge("finalize", END)
+
+    # Compile the graph
+    return workflow.compile()
+
+
+async def run_animation_pipeline(
+    mcp_session: Any,
+    tts_generator: Any,
+    topic: str,
+    target_audience: str = "general",
+    animation_length_minutes: float = 2.0,
+    output_filename: str = "animation.mp4",
+    rendering_quality: str = "medium",
+    max_retries: int = 3,
+) -> Dict[str, Any]:
+    """
+    Run the complete animation generation pipeline.
+
+    This is the main entry point for generating animations. It creates
+    the workflow, initializes the state, and executes all steps.
+
+    Args:
+        mcp_session: MCP client session
+        tts_generator: TTS generator instance
+        topic: STEM topic to animate
+        target_audience: Target audience level
+        animation_length_minutes: Desired animation length
+        output_filename: Name for output file
+        rendering_quality: Manim rendering quality
+        max_retries: Maximum retry attempts
+
+    Returns:
+        Dictionary with pipeline results including:
+        - success: Whether pipeline completed successfully
+        - final_output_path: Path to final video
+        - errors: List of errors encountered
+        - warnings: List of warnings
+        - completed_steps: List of completed steps
+        - metadata: Timing and other metadata
+    """
+    # Create working directories
+    work_dir = Path(tempfile.mkdtemp(prefix="neuroanim_work_"))
+    output_dir = Path("outputs")
+    output_dir.mkdir(exist_ok=True)
+
+    logger.info(f"📁 Working directory: {work_dir}")
+    logger.info(f"📁 Output directory: {output_dir}")
+
+    # Initialize nodes
+    nodes = AnimationNodes(
+        mcp_session=mcp_session,
+        tts_generator=tts_generator,
+        work_dir=work_dir,
+        output_dir=output_dir,
+    )
+
+    # Create workflow
+    workflow = create_animation_workflow(nodes)
+
+    # Create initial state
+    initial_state = create_initial_state(
+        topic=topic,
+        target_audience=target_audience,
+        animation_length_minutes=animation_length_minutes,
+        output_filename=output_filename,
+        rendering_quality=rendering_quality,
+        max_retries=max_retries,
+    )
+
+    logger.info(f"🎬 Starting animation pipeline for topic: '{topic}'")
+
+    try:
+        # Run the workflow
+        final_state = await workflow.ainvoke(initial_state)
+
+        # Build result summary
+        result = {
+            "success": final_state.get("success", False),
+            "topic": final_state["topic"],
+            "target_audience": final_state["target_audience"],
+            "final_output_path": final_state.get("final_output_path"),
+            "concept_plan": final_state.get("concept_plan"),
+            "narration": final_state.get("narration_text"),
+            "manim_code": final_state.get("manim_code"),
+            "quiz": final_state.get("quiz_content"),
+            "errors": final_state.get("errors", []),
+            "warnings": final_state.get("warnings", []),
+            "completed_steps": final_state.get("completed_steps", []),
+            "total_duration": final_state.get("total_duration"),
+            "work_dir": str(work_dir),
+            "output_dir": str(output_dir),
+        }
+
+        if result["success"]:
+            logger.info(f"✅ Animation pipeline completed successfully!")
+            logger.info(f"📹 Output file: {result['final_output_path']}")
+            logger.info(f"⏱️  Total time: {result['total_duration']:.2f}s")
+        else:
+            logger.error(f"❌ Animation pipeline failed")
+            logger.error(f"Errors: {result['errors']}")
+
+        return result
+
+    except Exception as e:
+        logger.error(f"Pipeline execution failed: {e}", exc_info=True)
+        return {
+            "success": False,
+            "error": str(e),
+            "work_dir": str(work_dir),
+            "output_dir": str(output_dir),
+        }
+
+    finally:
+        # Note: We don't clean up work_dir here so users can inspect artifacts
+        logger.info(f"Work directory preserved at: {work_dir}")

orchestrator.py

@@ -0,0 +1,785 @@
+"""
+NeuroAnim Orchestrator
+
+This script coordinates the entire STEM animation generation pipeline:
+1. Concept Planning
+2. Code Generation
+3. Rendering
+4. Vision-based Analysis
+5. Audio Generation
+6. Final Merging
+
+It uses the MCP servers (renderer and creative) to accomplish these tasks.
+"""
+
+import ast
+import asyncio
+import json
+import logging
+import os
+import tempfile
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import aiofiles
+from dotenv import load_dotenv
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+from utils.tts import TTSGenerator
+
+load_dotenv()
+# Set up logging
+logging.basicConfig(
+    level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+)
+logger = logging.getLogger(__name__)
+
+
+class NeuroAnimOrchestrator:
+    """Main orchestrator for NeuroAnim pipeline."""
+
+    def __init__(
+        self, hf_api_key: Optional[str] = None, elevenlabs_api_key: Optional[str] = None
+    ):
+        self.hf_api_key = hf_api_key or os.getenv("HUGGINGFACE_API_KEY")
+        self.elevenlabs_api_key = elevenlabs_api_key or os.getenv("ELEVENLABS_API_KEY")
+        self.renderer_session: Optional[ClientSession] = None
+        self.creative_session: Optional[ClientSession] = None
+
+        # Initialize TTS generator
+        self.tts_generator = TTSGenerator(
+            elevenlabs_api_key=self.elevenlabs_api_key,
+            hf_api_key=self.hf_api_key,
+            fallback_enabled=True,
+        )
+
+        # Context managers for MCP client connections
+        self._renderer_cm = None
+        self._creative_cm = None
+        self._renderer_streams = None
+        self._creative_streams = None
+
+        # Working directories
+        self.work_dir: Optional[Path] = None
+        self.output_dir: Optional[Path] = None
+
+    async def initialize(self):
+        """Initialize MCP server connections."""
+        # Set up working directories
+        self.work_dir = Path(tempfile.mkdtemp(prefix="neuroanim_work_"))
+        self.output_dir = Path("outputs")
+        self.output_dir.mkdir(exist_ok=True)
+
+        logger.info(f"Working directory: {self.work_dir}")
+        logger.info(f"Output directory: {self.output_dir}")
+
+        # Initialize renderer server
+        # stdio_client is an async context manager, must use async with
+        renderer_params = StdioServerParameters(
+            command="python", args=["mcp_servers/renderer.py"]
+        )
+
+        self._renderer_cm = stdio_client(renderer_params)
+        self._renderer_streams = await self._renderer_cm.__aenter__()
+        read_stream, write_stream = self._renderer_streams
+        self.renderer_session = ClientSession(read_stream, write_stream)
+        # Start background receive loop for the client session
+        await self.renderer_session.__aenter__()
+        await self.renderer_session.initialize()
+        logger.info("Renderer MCP server connected")
+
+        # Initialize creative server
+        creative_params = StdioServerParameters(
+            command="python",
+            args=["mcp_servers/creative.py"],
+            env={"HUGGINGFACE_API_KEY": self.hf_api_key} if self.hf_api_key else None,
+        )
+
+        self._creative_cm = stdio_client(creative_params)
+        self._creative_streams = await self._creative_cm.__aenter__()
+        read_stream, write_stream = self._creative_streams
+        self.creative_session = ClientSession(read_stream, write_stream)
+        # Start background receive loop for the client session
+        await self.creative_session.__aenter__()
+        await self.creative_session.initialize()
+        logger.info("Creative MCP server connected")
+
+    async def cleanup(self):
+        """Clean up resources."""
+        import shutil
+
+        # Close sessions first
+        if self.renderer_session:
+            try:
+                await self.renderer_session.__aexit__(None, None, None)
+            except (Exception, asyncio.CancelledError) as e:
+                logger.debug(f"Error closing renderer session: {e}")
+
+        if self.creative_session:
+            try:
+                await self.creative_session.__aexit__(None, None, None)
+            except (Exception, asyncio.CancelledError) as e:
+                logger.debug(f"Error closing creative session: {e}")
+
+        # Then close the stdio_client context managers with timeout
+        if self._renderer_cm:
+            try:
+                async with asyncio.timeout(2):  # 2 second timeout
+                    await self._renderer_cm.__aexit__(None, None, None)
+            except (Exception, asyncio.CancelledError, TimeoutError) as e:
+                logger.debug(f"Error closing renderer context manager: {e}")
+
+        if self._creative_cm:
+            try:
+                async with asyncio.timeout(2):  # 2 second timeout
+                    await self._creative_cm.__aexit__(None, None, None)
+            except (Exception, asyncio.CancelledError, TimeoutError) as e:
+                logger.debug(f"Error closing creative context manager: {e}")
+
+        # Clean up working directory
+        if self.work_dir and self.work_dir.exists():
+            try:
+                shutil.rmtree(self.work_dir)
+                logger.info(f"Cleaned up working directory: {self.work_dir}")
+            except Exception as e:
+                logger.warning(f"Failed to clean up working directory: {e}")
+
+    async def call_tool(
+        self, session: ClientSession, tool_name: str, arguments: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Call a tool on an MCP server."""
+        result = await session.call_tool(tool_name, arguments)
+
+        if hasattr(result, "content") and result.content:
+            content = result.content[0]
+            if hasattr(content, "text"):
+                return {
+                    "text": content.text,
+                    "isError": getattr(result, "isError", False),
+                }
+
+        return {"text": str(result), "isError": False}
+
+    async def generate_animation(
+        self,
+        topic: str,
+        target_audience: str = "general",
+        animation_length_minutes: float = 2.0,
+        output_filename: str = "animation.mp4",
+        quality: str = "medium",
+        progress_callback: Optional[callable] = None,
+    ) -> Dict[str, Any]:
+        """Complete animation generation pipeline."""
+
+        try:
+            logger.info(f"Starting animation generation for: {topic}")
+
+            # Step 1: Concept Planning
+            logger.info("Step 1: Planning concept...")
+            if progress_callback:
+                progress_callback("Planning concept", 0.1)
+            concept_result = await self.call_tool(
+                self.creative_session,
+                "plan_concept",
+                {
+                    "topic": topic,
+                    "target_audience": target_audience,
+                    "animation_length_minutes": animation_length_minutes,
+                },
+            )
+
+            if concept_result["isError"]:
+                raise Exception(f"Concept planning failed: {concept_result['text']}")
+
+            concept_plan = concept_result["text"]
+            logger.info("Concept planning completed")
+
+            # Step 2: Generate Narration
+            logger.info("Step 2: Generating narration...")
+            if progress_callback:
+                progress_callback("Generating narration script", 0.25)
+            narration_result = await self.call_tool(
+                self.creative_session,
+                "generate_narration",
+                {
+                    "concept": topic,
+                    "scene_description": concept_plan,
+                    "target_audience": target_audience,
+                    "duration_seconds": int(animation_length_minutes * 60),
+                },
+            )
+
+            if narration_result["isError"]:
+                raise Exception(
+                    f"Narration generation failed: {narration_result['text']}"
+                )
+
+            # Clean narration text - remove title/prefix before TTS
+            narration_text = self._clean_narration_text(narration_result["text"])
+            logger.info("Narration generation completed")
+            logger.info(f"Narration preview: {narration_text[:100]}...")
+
+            # Step 3: Generate Manim Code with retry logic
+            logger.info("Step 3: Generating Manim code...")
+            if progress_callback:
+                progress_callback("Creating Manim animation code", 0.40)
+            target_duration_seconds = int(animation_length_minutes * 60)
+            manim_code = await self._generate_and_validate_code(
+                topic=topic,
+                concept_plan=concept_plan,
+                duration_seconds=target_duration_seconds,
+                max_retries=3,
+            )
+            logger.info("Manim code generation completed and validated")
+
+            # Step 4: Write Manim File
+            logger.info("Step 4: Writing Manim file...")
+            manim_file = self.work_dir / "animation.py"
+            write_result = await self.call_tool(
+                self.renderer_session,
+                "write_manim_file",
+                {"filepath": str(manim_file), "code": manim_code},
+            )
+
+            if write_result["isError"]:
+                raise Exception(f"File writing failed: {write_result['text']}")
+
+            # Extract scene name from code
+            scene_name = self._extract_scene_name(manim_code)
+            logger.info(f"Scene name detected: {scene_name}")
+
+            # Step 5: Render Animation with retry on runtime errors
+            logger.info("Step 5: Rendering animation...")
+            if progress_callback:
+                progress_callback("Rendering animation video", 0.55)
+            max_render_retries = 5
+            video_file = None
+            
+            for render_attempt in range(max_render_retries):
+                render_result = await self.call_tool(
+                    self.renderer_session,
+                    "render_manim_animation",
+                    {
+                        "scene_name": scene_name,
+                        "file_path": str(manim_file),
+                        "output_dir": str(self.work_dir),
+                        "quality": quality,  # Use the quality parameter
+                        "format": "mp4",
+                        "frame_rate": 30,
+                    },
+                )
+
+                if not render_result["isError"]:
+                    # Success! Find the rendered file
+                    video_file = self._find_output_file(self.work_dir, scene_name, "mp4")
+                    if video_file:
+                        # Check video duration
+                        try:
+                            actual_duration = self._get_video_duration(video_file)
+                            logger.info(f"Rendered video duration: {actual_duration:.2f}s (Target: {target_duration_seconds}s)")
+                            
+                            if actual_duration < target_duration_seconds * 0.5:
+                                logger.warning(f"Video is too short ({actual_duration:.2f}s < {target_duration_seconds * 0.5}s). Forcing retry...")
+                                error_text = (
+                                    f"The generated animation was TOO SHORT ({actual_duration:.1f}s). "
+                                    f"The target duration is {target_duration_seconds}s. "
+                                    "You MUST make the animation longer by adding more `self.wait()` calls "
+                                    "and ensuring animations play slower (use run_time parameter)."
+                                )
+                                # Fall through to error handling logic below
+                            else:
+                                break
+                        except Exception as e:
+                            logger.warning(f"Could not verify video duration: {e}")
+                            break
+                    else:
+                        logger.warning("Render succeeded but could not find output file")
+                        if render_attempt < max_render_retries - 1:
+                            continue
+                
+                # Rendering failed - check if it's a runtime error we can fix
+                error_text = render_result["text"]
+                logger.warning(f"Render attempt {render_attempt + 1} failed: {error_text[:200]}...")
+                
+                # Check if this is a Manim runtime error (not a "no scene" error)
+                if render_attempt < max_render_retries - 1 and (
+                    "TypeError" in error_text 
+                    or "AttributeError" in error_text 
+                    or "ValueError" in error_text
+                    or "KeyError" in error_text
+                ):
+                    logger.info(f"Detected runtime error in Manim code. Regenerating code (attempt {render_attempt + 2}/{max_render_retries})...")
+                    
+                    # Regenerate code with error feedback
+                    runtime_error_msg = f"Runtime Error during Manim rendering:\n{error_text}\n\nPlease fix the code to be compatible with Manim version 0.19.0."
+                    manim_code = await self._generate_and_validate_code(
+                        topic=topic,
+                        concept_plan=concept_plan,
+                        duration_seconds=target_duration_seconds,
+                        max_retries=3,  # Allow retries for syntax errors during fix
+                        previous_error=runtime_error_msg,
+                        previous_code=manim_code,
+                    )
+                    
+                    # Write the new code
+                    write_result = await self.call_tool(
+                        self.renderer_session,
+                        "write_manim_file",
+                        {"filepath": str(manim_file), "code": manim_code},
+                    )
+                    
+                    if write_result["isError"]:
+                        raise Exception(f"File writing failed: {write_result['text']}")
+                    
+                    # Extract scene name from new code
+                    scene_name = self._extract_scene_name(manim_code)
+                    logger.info(f"Regenerated code with scene: {scene_name}")
+                    
+                    # Loop will retry rendering with new code
+                    continue
+                else:
+                    # Not a runtime error or out of retries
+                    raise Exception(f"Rendering failed: {error_text}")
+            
+            if not video_file:
+                raise Exception("Could not find rendered video file after all attempts")
+
+            logger.info(f"Animation rendered: {video_file}")
+
+            # Step 6: Generate Speech Audio
+            logger.info("Step 6: Generating speech audio...")
+            if progress_callback:
+                progress_callback("Generating audio narration", 0.75)
+            audio_file = self.work_dir / "narration.mp3"
+
+            # Use TTS generator with automatic fallback
+            try:
+                tts_result = await self.tts_generator.generate_speech(
+                    text=narration_text, output_path=audio_file, voice="rachel"
+                )
+                logger.info(
+                    f"Audio generated with {tts_result['provider']}: {audio_file}"
+                )
+
+                # Validate audio file
+                validation = self.tts_generator.validate_audio_file(audio_file)
+                if not validation["valid"]:
+                    logger.warning(
+                        f"Audio validation warning: {validation.get('error', 'Unknown issue')}"
+                    )
+                    logger.info("Audio file may have issues but continuing...")
+                else:
+                    logger.info(
+                        f"Audio validated: {validation.get('duration', 'N/A')}s, {validation.get('size', 0)} bytes"
+                    )
+
+            except Exception as e:
+                logger.error(f"TTS generation failed: {e}")
+                raise Exception(f"Speech generation failed: {str(e)}")
+
+            # Step 7: Merge Video and Audio
+            logger.info("Step 7: Merging video and audio...")
+            if progress_callback:
+                progress_callback("Merging video and audio", 0.90)
+            final_output = self.output_dir / output_filename
+            merge_result = await self.call_tool(
+                self.renderer_session,
+                "merge_video_audio",
+                {
+                    "video_file": str(video_file),
+                    "audio_file": str(audio_file),
+                    "output_file": str(final_output),
+                },
+            )
+
+            if merge_result["isError"]:
+                raise Exception(f"Merging failed: {merge_result['text']}")
+
+            # Step 8: Generate Quiz
+            logger.info("Step 8: Generating quiz...")
+            if progress_callback:
+                progress_callback("Creating quiz questions", 0.95)
+            quiz_result = await self.call_tool(
+                self.creative_session,
+                "generate_quiz",
+                {
+                    "concept": topic,
+                    "difficulty": "medium",
+                    "num_questions": 3,
+                    "question_types": ["multiple_choice"],
+                },
+            )
+
+            quiz_content = (
+                quiz_result["text"]
+                if not quiz_result["isError"]
+                else "Quiz generation failed"
+            )
+
+            # Return results
+            results = {
+                "success": True,
+                "topic": topic,
+                "target_audience": target_audience,
+                "concept_plan": concept_plan,
+                "narration": narration_text,
+                "manim_code": manim_code,
+                "output_file": str(final_output),
+                "quiz": quiz_content,
+                "work_dir": str(self.work_dir),
+            }
+
+            logger.info(f"Animation generation completed successfully: {final_output}")
+            return results
+
+        except Exception as e:
+            logger.error(f"Animation generation failed: {str(e)}")
+            return {
+                "success": False,
+                "error": str(e),
+                "work_dir": str(self.work_dir) if self.work_dir else None,
+            }
+
+    def _clean_narration_text(self, text: str) -> str:
+        """
+        Clean narration text by removing title prefixes and formatting artifacts.
+
+        The creative server returns text with prefixes like "Narration Script:\n\n"
+        which should not be sent to TTS.
+        """
+        # Remove common prefixes
+        prefixes_to_remove = [
+            "Narration Script:",
+            "Script:",
+            "Narration:",
+            "Text:",
+        ]
+
+        cleaned = text.strip()
+
+        # Remove any of the prefixes (case-insensitive)
+        for prefix in prefixes_to_remove:
+            if cleaned.lower().startswith(prefix.lower()):
+                cleaned = cleaned[len(prefix) :].strip()
+                break
+
+        # Remove leading newlines and whitespace
+        cleaned = cleaned.lstrip("\n").strip()
+
+        # Remove any markdown code block markers
+        if cleaned.startswith("```"):
+            lines = cleaned.split("\n")
+            # Remove first line (opening ```)
+            if len(lines) > 1:
+                lines = lines[1:]
+            # Remove last line if it's closing ```
+            if lines and lines[-1].strip() == "```":
+                lines = lines[:-1]
+            cleaned = "\n".join(lines).strip()
+
+        return cleaned
+
+    def _extract_python_code(self, text: str) -> str:
+        """Extract Python code from markdown response."""
+        # Look for code blocks
+        if "```python" in text:
+            start = text.find("```python") + 9
+            end = text.find("```", start)
+            if end == -1:
+                end = len(text)
+            return text[start:end].strip()
+        elif "```" in text:
+            start = text.find("```") + 3
+            end = text.find("```", start)
+            if end == -1:
+                end = len(text)
+            return text[start:end].strip()
+        else:
+            return text.strip()
+
+    async def _generate_and_validate_code(
+        self,
+        topic: str,
+        concept_plan: str,
+        duration_seconds: int = 60,
+        max_retries: int = 3,
+        previous_error: Optional[str] = None,
+        previous_code: Optional[str] = None,
+    ) -> str:
+        """Generate Manim code with retry logic for syntax errors."""
+        for attempt in range(max_retries):
+            try:
+                logger.info(f"Code generation attempt {attempt + 1}/{max_retries}")
+
+                # Build arguments for code generation
+                arguments = {
+                    "concept": topic,
+                    "scene_description": concept_plan,
+                    "visual_elements": ["text", "shapes", "animations"],
+                    "duration_seconds": duration_seconds,
+                }
+
+                # If this is a retry, include error feedback
+                if previous_error:
+                    if previous_code:
+                        arguments["previous_code"] = previous_code
+                    arguments["error_message"] = previous_error
+                    logger.info(
+                        f"Retrying with error feedback: {previous_error[:100]}..."
+                    )
+
+                # Generate code
+                code_result = await self.call_tool(
+                    self.creative_session, "generate_manim_code", arguments
+                )
+
+                if code_result["isError"]:
+                    if attempt < max_retries - 1:
+                        logger.warning(
+                            f"Code generation failed, retrying: {code_result['text']}"
+                        )
+                        previous_error = code_result["text"]
+                        # Keep previous_code if we had it, for better context in retry
+                        continue
+                    else:
+                        raise Exception(
+                            f"Code generation failed: {code_result['text']}"
+                        )
+
+                # Extract Python code from response
+                manim_code = self._extract_python_code(code_result["text"])
+
+                # Validate Python syntax
+                syntax_errors = self._validate_python_syntax(manim_code)
+                if syntax_errors:
+                    if attempt < max_retries - 1:
+                        logger.warning(
+                            f"Syntax error detected, retrying: {syntax_errors}"
+                        )
+                        previous_error = f"Syntax Error:\n{syntax_errors}"
+                        previous_code = manim_code
+                        continue
+                    else:
+                        raise Exception(
+                            f"Generated code has syntax errors after {max_retries} attempts:\n{syntax_errors}"
+                        )
+
+                # Validate that code contains a Scene class
+                has_scene = self._validate_has_scene_class(manim_code)
+                if not has_scene:
+                    if attempt < max_retries - 1:
+                        logger.warning(
+                            "No Scene class found in generated code, retrying..."
+                        )
+                        previous_error = (
+                            "Error: The generated code does not contain any Scene class. "
+                            "Please ensure you create a class that inherits from manim.Scene, "
+                            "manim.MovingCameraScene, or manim.ThreeDScene."
+                        )
+                        previous_code = manim_code
+                        continue
+                    else:
+                        raise Exception(
+                            f"Generated code does not contain a Scene class after {max_retries} attempts"
+                        )
+
+                # Success!
+                logger.info(f"Valid code generated on attempt {attempt + 1}")
+                return manim_code
+
+            except Exception as e:
+                if attempt < max_retries - 1:
+                    logger.warning(f"Attempt {attempt + 1} failed: {str(e)}")
+                    previous_error = str(e)
+                    continue
+                else:
+                    raise
+
+        raise Exception("Failed to generate valid code after all retries")
+
+    def _validate_python_syntax(self, code: str) -> Optional[str]:
+        """Validate Python code syntax. Returns error message if invalid, None if valid."""
+        try:
+            ast.parse(code)
+            return None
+        except SyntaxError as e:
+            # Build detailed error message with context
+            error_msg = f"Line {e.lineno}: {e.msg}"
+
+            # Show surrounding context (3 lines before and after)
+            if e.lineno is not None:
+                code_lines = code.split("\n")
+                start_line = max(0, e.lineno - 4)  # 3 lines before
+                end_line = min(len(code_lines), e.lineno + 2)  # 2 lines after
+
+                error_msg += "\n\nContext:"
+                for i in range(start_line, end_line):
+                    line_num = i + 1
+                    prefix = ">>> " if line_num == e.lineno else "    "
+                    error_msg += f"\n{prefix}{line_num:3d} | {code_lines[i]}"
+
+                    # Add pointer for error line
+                    if line_num == e.lineno and e.offset:
+                        error_msg += f"\n    {' ' * 4}{' ' * (e.offset - 1)}^"
+
+            return error_msg
+        except Exception as e:
+            return f"Unexpected error during syntax validation: {str(e)}"
+
+    def _validate_has_scene_class(self, code: str) -> bool:
+        """Check if code contains at least one Scene class."""
+        import re
+        
+        # Check for Scene class inheritance
+        scene_patterns = [
+            r"class\s+\w+\s*\(\s*Scene\s*\)",
+            r"class\s+\w+\s*\(\s*MovingCameraScene\s*\)",
+            r"class\s+\w+\s*\(\s*ThreeDScene\s*\)",
+            r"class\s+\w+\s*\(\s*\w*Scene\s*\)",
+        ]
+        
+        for pattern in scene_patterns:
+            if re.search(pattern, code):
+                return True
+        
+        # Also check using AST parsing as a backup
+        try:
+            tree = ast.parse(code)
+            for node in ast.walk(tree):
+                if isinstance(node, ast.ClassDef):
+                    # Check if any base class contains "Scene"
+                    for base in node.bases:
+                        if isinstance(base, ast.Name) and "Scene" in base.id:
+                            return True
+        except Exception:
+            pass
+        
+        return False
+
+    def _extract_scene_name(self, code: str) -> str:
+        """Extract scene class name from Manim code."""
+        import re
+
+        # Try multiple patterns to find Scene class
+        patterns = [
+            r"class\s+(\w+)\s*\(\s*Scene\s*\)",  # class Name(Scene)
+            r"class\s+(\w+)\s*\(\s*MovingCameraScene\s*\)",  # class Name(MovingCameraScene)
+            r"class\s+(\w+)\s*\(\s*ThreeDScene\s*\)",  # class Name(ThreeDScene)
+            r"class\s+(\w+)\s*\(\s*\w*Scene\s*\)",  # class Name(AnyScene)
+        ]
+        
+        for pattern in patterns:
+            match = re.search(pattern, code)
+            if match:
+                scene_name = match.group(1)
+                logger.info(f"Found scene class: {scene_name}")
+                return scene_name
+        
+        # If no scene found, look for any class definition and warn
+        any_class = re.search(r"class\s+(\w+)\s*\(", code)
+        if any_class:
+            class_name = any_class.group(1)
+            logger.warning(
+                f"Could not find Scene class, using first class found: {class_name}"
+            )
+            return class_name
+        
+        # Last resort - parse the AST to find classes
+        try:
+            tree = ast.parse(code)
+            for node in ast.walk(tree):
+                if isinstance(node, ast.ClassDef):
+                    logger.warning(
+                        f"Using first class from AST parsing: {node.name}"
+                    )
+                    return node.name
+        except Exception as e:
+            logger.error(f"Failed to parse code AST: {e}")
+        
+        # Absolute fallback
+        logger.error("No scene class found in code! This will likely cause rendering to fail.")
+        return "Scene"  # fallback
+
+    def _find_output_file(
+        self, directory: Path, scene_name: str, extension: str
+    ) -> Optional[Path]:
+        """Find output file with given scene name and extension."""
+        for file in directory.glob(f"{scene_name}*.{extension}"):
+            return file
+        return None
+
+
+async def main():
+    """Main function for running the orchestrator."""
+    import argparse
+
+    parser = argparse.ArgumentParser(description="NeuroAnim STEM Animation Generator")
+    parser.add_argument("topic", help="STEM topic for the animation")
+    parser.add_argument(
+        "--audience",
+        choices=["elementary", "middle_school", "high_school", "college", "general"],
+        default="general",
+        help="Target audience",
+    )
+    parser.add_argument(
+        "--duration", type=float, default=2.0, help="Animation duration in minutes"
+    )
+    parser.add_argument("--output", default="animation.mp4", help="Output filename")
+    parser.add_argument(
+        "--api-key", help="Hugging Face API key (or set HUGGINGFACE_API_KEY env var)"
+    )
+    parser.add_argument(
+        "--elevenlabs-key",
+        help="ElevenLabs API key (or set ELEVENLABS_API_KEY env var)",
+    )
+
+    args = parser.parse_args()
+
+    # Initialize and run orchestrator
+    orchestrator = NeuroAnimOrchestrator(
+        hf_api_key=args.api_key, elevenlabs_api_key=args.elevenlabs_key
+    )
+
+    try:
+        await orchestrator.initialize()
+
+        results = await orchestrator.generate_animation(
+            topic=args.topic,
+            target_audience=args.audience,
+            animation_length_minutes=args.duration,
+            output_filename=args.output,
+        )
+
+        if results["success"]:
+            print("\n🎉 Animation Generated Successfully!")
+            print(f"📹 Output file: {results['output_file']}")
+            print(f"🎯 Topic: {results['topic']}")
+            print(f"👥 Audience: {results['target_audience']}")
+            print(f"\n📝 Concept Plan:")
+            print(
+                results["concept_plan"][:500] + "..."
+                if len(results["concept_plan"]) > 500
+                else results["concept_plan"]
+            )
+            print(f"\n🎭 Narration:")
+            print(
+                results["narration"][:300] + "..."
+                if len(results["narration"]) > 300
+                else results["narration"]
+            )
+            print(f"\n📚 Quiz Questions:")
+            print(results["quiz"])
+        else:
+            print(f"\n❌ Animation Generation Failed: {results['error']}")
+
+    except KeyboardInterrupt:
+        print("\n⚠️  Process interrupted by user")
+    except Exception as e:
+        print(f"\n💥 Unexpected error: {str(e)}")
+    finally:
+        await orchestrator.cleanup()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "neuroanim"
+version = "0.1.0"
+description = "Modular STEM animation generator using MCP and Hugging Face"
+requires-python = ">=3.12"
+dependencies = [
+    "mcp>=1.0.0",
+    "langgraph>=0.0.26",
+    "langchain-core>=0.1.0",
+    "huggingface_hub>=0.25.0",
+    "manim>=0.18.1",
+    "pydantic>=2.0.0",
+    "aiohttp>=3.8.0",
+    "httpx>=0.24.0",
+    "numpy>=1.24.0",
+    "Pillow>=10.0.0",
+    "gtts>=2.3.0",
+    "pydub>=0.25.0",
+    "python-dotenv>=1.0.0",
+    "elevenlabs>=0.2.0",
+    "blaxel>=0.1.0",
+    "gradio>=4.0.0",
+    "textstat>=0.7.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.black]
+line-length = 88
+target-version = ['py312']
+
+[tool.isort]
+profile = "black"

requirements.txt

@@ -0,0 +1,33 @@
+# Core dependencies for Hugging Face Spaces
+gradio>=6.0.0
+python-dotenv>=1.0.0
+
+# AI and LLM
+mcp>=1.0.0
+langgraph>=0.0.26
+langchain-core>=0.1.0
+huggingface-hub>=0.25.0
+
+# Animation and rendering
+manim>=0.18.1
+Pillow>=10.0.0
+numpy>=1.24.0
+
+# Audio processing
+gtts>=2.3.0
+pydub>=0.25.0
+elevenlabs>=0.2.0
+
+# Cloud rendering
+blaxel>=0.1.0
+
+# Utilities
+pydantic>=2.0.0
+aiohttp>=3.8.0
+httpx>=0.24.0
+textstat>=0.7.0
+requests>=2.32.0
+
+# Additional dependencies
+beautifulsoup4>=4.14.0
+tqdm>=4.67.0

utils/__init__.py

@@ -0,0 +1,9 @@
+"""
+Utilities for NeuroAnim.
+
+This package contains utility modules for the NeuroAnim project.
+"""
+
+from .hf_wrapper import HFInferenceWrapper, ModelConfig, get_hf_wrapper
+
+__all__ = ["HFInferenceWrapper", "ModelConfig", "get_hf_wrapper"]

utils/hf_wrapper.py

@@ -0,0 +1,369 @@
+"""
+Hugging Face Inference API Wrapper
+
+This module provides a robust wrapper around the Hugging Face Inference API
+with rate limiting, error handling, and support for various model types.
+"""
+
+import asyncio
+import base64
+import io
+import logging
+import time
+from typing import Any, BinaryIO, Dict, List, Optional, Union
+
+import aiohttp
+from huggingface_hub import AsyncInferenceClient, InferenceClient
+from pydantic import BaseModel, Field
+
+logger = logging.getLogger(__name__)
+
+
+class RateLimiter:
+    """Simple rate limiter for API calls."""
+
+    def __init__(self, max_calls: int = 60, time_window: int = 60):
+        self.max_calls = max_calls
+        self.time_window = time_window
+        self.calls = []
+
+    async def acquire(self):
+        """Wait if rate limit would be exceeded."""
+        now = time.time()
+        # Remove calls outside the time window
+        self.calls = [
+            call_time for call_time in self.calls if now - call_time < self.time_window
+        ]
+
+        if len(self.calls) >= self.max_calls:
+            # Calculate wait time
+            oldest_call = min(self.calls)
+            wait_time = self.time_window - (now - oldest_call)
+            if wait_time > 0:
+                logger.info(f"Rate limit reached, waiting {wait_time:.2f} seconds")
+                await asyncio.sleep(wait_time)
+
+        self.calls.append(now)
+
+
+class HFInferenceWrapper:
+    """
+    Wrapper for Hugging Face Inference API with rate limiting and error handling.
+    """
+
+    def __init__(self, api_key: Optional[str] = None, max_calls_per_minute: int = 60):
+        self.client = AsyncInferenceClient(token=api_key)
+        self.rate_limiter = RateLimiter(max_calls=max_calls_per_minute, time_window=60)
+
+    async def text_generation(
+        self,
+        model: str,
+        prompt: str,
+        max_new_tokens: int = 512,
+        temperature: float = 0.7,
+        **kwargs,
+    ) -> str:
+        """Generate text using a language model.
+
+        Notes:
+        - Uses AsyncInferenceClient by default.
+        - Works around a known issue where `AsyncInferenceClient.text_generation`
+          may raise `StopIteration` ("coroutine raised StopIteration") by
+          falling back to the synchronous `InferenceClient` inside a thread.
+        - Automatically detects if a model supports conversational tasks and
+          uses chat_completion instead of text_generation.
+        - Always normalizes the result to a plain string, extracting
+          `generated_text` when the client returns a `TextGenerationOutput`
+          object.
+        """
+        await self.rate_limiter.acquire()
+
+        try:
+            # Check if this is a conversational model that doesn't support text_generation
+            if self._is_conversational_model(model):
+                logger.info(f"Using chat_completion for conversational model: {model}")
+                return await self._chat_completion_fallback(
+                    model, prompt, max_new_tokens, temperature, **kwargs
+                )
+
+            # Primary path: async client with text_generation
+            response = await self.client.text_generation(
+                prompt=prompt,
+                model=model,
+                max_new_tokens=max_new_tokens,
+                temperature=temperature,
+                **kwargs,
+            )
+        except Exception as e:
+            # Check if this is a model capability issue
+            if "not supported for task text-generation" in str(e):
+                logger.info(f"Falling back to chat_completion for model: {model}")
+                return await self._chat_completion_fallback(
+                    model, prompt, max_new_tokens, temperature, **kwargs
+                )
+
+            # Newer versions of `huggingface_hub` sometimes surface a
+            # `RuntimeError` with message "coroutine raised StopIteration" from
+            # the async client. Detect that pattern (or a raw StopIteration)
+            # and fall back to the sync client in a background thread.
+            is_stop_iteration_like = isinstance(
+                e, StopIteration
+            ) or "StopIteration" in str(e)
+
+            if is_stop_iteration_like:  # pragma: no cover - defensive against HF bug
+                logger.warning(
+                    "Async text_generation raised/contained StopIteration for "
+                    "model %s; falling back to sync InferenceClient: %s",
+                    model,
+                    e,
+                )
+
+                def _call_sync() -> str:
+                    """Synchronous text-generation call for asyncio.to_thread."""
+                    sync_client = InferenceClient(token=self.client.token)
+                    # Check if this is a conversational model
+                    if self._is_conversational_model(model):
+                        messages = [{"role": "user", "content": prompt}]
+                        chat_response = sync_client.chat.completions.create(
+                            model=model,
+                            messages=messages,
+                            max_tokens=max_new_tokens,
+                            temperature=temperature,
+                            **kwargs,
+                        )
+                        return chat_response.choices[0].message.content
+                    else:
+                        return sync_client.text_generation(
+                            prompt=prompt,
+                            model=model,
+                            max_new_tokens=max_new_tokens,
+                            temperature=temperature,
+                            **kwargs,
+                        )
+
+                response = await asyncio.to_thread(_call_sync)
+            else:
+                logger.error(f"Text generation failed with model {model}: {e}")
+                raise
+
+        # Normalize various possible return types to a plain string
+        try:
+            from huggingface_hub.inference._generated.types.text_generation import (
+                TextGenerationOutput,
+            )
+        except Exception:  # pragma: no cover - type import fallback
+            TextGenerationOutput = None  # type: ignore
+
+        if TextGenerationOutput is not None and isinstance(
+            response, TextGenerationOutput
+        ):
+            return response.generated_text
+
+        if isinstance(response, str):
+            return response
+
+        # Fallback: best-effort stringification
+        return str(response)
+
+    def _is_conversational_model(self, model: str) -> bool:
+        """Check if a model is primarily conversational (doesn't support text_generation)."""
+        conversational_models = [
+            "zai-org/GLM-4.6",
+            # Add other known conversational-only models here
+        ]
+        return model in conversational_models
+
+    async def _chat_completion_fallback(
+        self,
+        model: str,
+        prompt: str,
+        max_new_tokens: int = 512,
+        temperature: float = 0.7,
+        **kwargs,
+    ) -> str:
+        """Fallback method using chat.completions for conversational models."""
+        messages = [{"role": "user", "content": prompt}]
+
+        try:
+            # Try async first
+            response = await self.client.chat.completions.create(
+                model=model,
+                messages=messages,
+                max_tokens=max_new_tokens,
+                temperature=temperature,
+                **kwargs,
+            )
+            return response.choices[0].message.content
+        except Exception as e:
+            logger.warning(f"Async chat_completion failed, falling back to sync: {e}")
+
+            # Fall back to sync if async fails
+            def _sync_chat_completion():
+                sync_client = InferenceClient(token=self.client.token)
+                response = sync_client.chat.completions.create(
+                    model=model,
+                    messages=messages,
+                    max_tokens=max_new_tokens,
+                    temperature=temperature,
+                    **kwargs,
+                )
+                return response.choices[0].message.content
+
+            return await asyncio.to_thread(_sync_chat_completion)
+
+    async def conversation(
+        self,
+        model: str,
+        messages: List[Dict[str, str]],
+        max_tokens: int = 512,
+        temperature: float = 0.7,
+        **kwargs,
+    ) -> str:
+        """Generate response in a conversation format."""
+        await self.rate_limiter.acquire()
+
+        try:
+            response = await self.client.chat.completions.create(
+                model=model,
+                messages=messages,
+                max_tokens=max_tokens,
+                temperature=temperature,
+                **kwargs,
+            )
+            return response.choices[0].message.content
+        except Exception as e:
+            logger.error(f"Conversation failed with model {model}: {e}")
+            raise
+
+    async def image_generation(
+        self,
+        model: str,
+        prompt: str,
+        negative_prompt: Optional[str] = None,
+        width: int = 1024,
+        height: int = 1024,
+        **kwargs,
+    ) -> bytes:
+        """Generate an image and return as bytes."""
+        await self.rate_limiter.acquire()
+
+        try:
+            image_bytes = await self.client.text_to_image(
+                model=model,
+                prompt=prompt,
+                negative_prompt=negative_prompt,
+                width=width,
+                height=height,
+                **kwargs,
+            )
+            return image_bytes
+        except Exception as e:
+            logger.error(f"Image generation failed with model {model}: {e}")
+            raise
+
+    async def text_to_speech(
+        self, model: str, text: str, voice: Optional[str] = None, **kwargs
+    ) -> bytes:
+        """Convert text to speech and return audio bytes.
+
+        Note: The voice parameter is kept for backwards compatibility but is not used
+        as the HuggingFace API doesn't support it.
+        """
+        await self.rate_limiter.acquire()
+
+        try:
+            # HuggingFace text_to_speech API: text as first arg, model as kwarg
+            audio_bytes = await self.client.text_to_speech(text, model=model)
+            return audio_bytes
+        except Exception as e:
+            logger.error(f"TTS failed with model {model}: {e}")
+            raise
+
+    async def vision_analysis(
+        self, model: str, image: Union[bytes, BinaryIO], text: str, **kwargs
+    ) -> str:
+        """Analyze an image with a vision model."""
+        await self.rate_limiter.acquire()
+
+        try:
+            response = await self.client.image_to_text(
+                model=model, image=image, text=text, **kwargs
+            )
+            return response
+        except Exception as e:
+            logger.error(f"Vision analysis failed with model {model}: {e}")
+            raise
+
+    async def save_audio_to_file(self, audio_bytes: bytes, output_path: str) -> bool:
+        """Save audio bytes to a file."""
+        try:
+            with open(output_path, "wb") as f:
+                f.write(audio_bytes)
+            logger.info(f"Audio saved to {output_path}")
+            return True
+        except Exception as e:
+            logger.error(f"Failed to save audio to {output_path}: {e}")
+            return False
+
+    def audio_bytes_to_base64(self, audio_bytes: bytes) -> str:
+        """Convert audio bytes to base64 string for transmission."""
+        return base64.b64encode(audio_bytes).decode("utf-8")
+
+    def base64_to_audio_bytes(self, base64_str: str) -> bytes:
+        """Convert base64 string back to audio bytes."""
+        return base64.b64decode(base64_str.encode("utf-8"))
+
+
+class ModelConfig(BaseModel):
+    """Configuration for different model types."""
+
+    text_models: List[str] = Field(
+        default_factory=lambda: [
+            # Primary general/text models
+            "zai-org/GLM-4.6",
+            "mistralai/Mistral-Nemo-Instruct-2407",
+            "Qwen/Qwen2.5-7B-Instruct",
+            "meta-llama/Llama-3.1-8B-Instruct",
+        ]
+    )
+
+    code_models: List[str] = Field(
+        default_factory=lambda: [
+            # Primary code-capable models
+            "zai-org/GLM-4.6",
+            "deepseek-ai/DeepSeek-Coder-V2-Lite-Instruct",
+            "meta-llama/CodeLlama-70b-Instruct-hf",
+            # Kept last because it has caused auth issues in practice
+            "ZhipuAI/glm-4-9b-chat",
+        ]
+    )
+
+    vision_models: List[str] = Field(
+        default_factory=lambda: [
+            "llava-hf/llava-v1.6-mistral-7b-hf",
+            "Salesforce/blip2-flan-t5-xxl",
+            "google/paligemma-3b-mix-448",
+        ]
+    )
+
+    tts_models: List[str] = Field(
+        default_factory=lambda: [
+            "ResembleAI/chatterbox",
+            "suno/bark",
+            "facebook/mms-tts-all",
+        ]
+    )
+
+    image_models: List[str] = Field(
+        default_factory=lambda: [
+            "stabilityai/stable-diffusion-3-medium",
+            "black-forest-labs/FLUX.1-dev",
+            "prompthero/openjourney",
+        ]
+    )
+
+
+# Global instance factory
+def get_hf_wrapper(api_key: Optional[str] = None) -> HFInferenceWrapper:
+    """Get a configured HFInferenceWrapper instance."""
+    return HFInferenceWrapper(api_key=api_key)

utils/tts.py

@@ -0,0 +1,440 @@
+"""
+Text-to-Speech (TTS) Utility Module
+
+Supports multiple TTS providers:
+- ElevenLabs (primary, high quality)
+- Hugging Face (fallback)
+- Google TTS (optional fallback)
+"""
+
+import asyncio
+import logging
+import os
+from enum import Enum
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+import httpx
+from dotenv import load_dotenv
+
+# Try to import ElevenLabs SDK
+try:
+    from elevenlabs.client import ElevenLabs
+
+    ELEVENLABS_SDK_AVAILABLE = True
+except ImportError:
+    ELEVENLABS_SDK_AVAILABLE = False
+    ElevenLabs = None
+
+load_dotenv()
+
+logger = logging.getLogger(__name__)
+
+
+class TTSProvider(Enum):
+    """Available TTS providers."""
+
+    ELEVENLABS = "elevenlabs"
+    HUGGINGFACE = "huggingface"
+    GTTS = "gtts"
+
+
+class TTSConfig:
+    """Configuration for TTS generation."""
+
+    # ElevenLabs voices
+    ELEVENLABS_VOICES = {
+        "rachel": "21m00Tcm4TlvDq8ikWAM",  # Clear, neutral female
+        "adam": "pNInz6obpgDQGcFmaJgB",  # Deep, confident male
+        "antoni": "ErXwobaYiN019PkySvjV",  # Well-rounded male
+        "arnold": "VR6AewLTigWG4xSOukaG",  # Crisp, articulate male
+        "bella": "EXAVITQu4vr4xnSDxMaL",  # Soft, gentle female
+        "domi": "AZnzlk1XvdvUeBnXmlld",  # Strong female
+        "elli": "MF3mGyEYCl7XYWbV9V6O",  # Emotional, expressive female
+        "josh": "TxGEqnHWrfWFTfGW9XjX",  # Young, energetic male
+        "sam": "yoZ06aMxZJJ28mfd3POQ",  # Raspy male
+    }
+
+    # Default settings
+    ELEVENLABS_MODEL = "eleven_turbo_v2_5"
+    ELEVENLABS_STABILITY = 0.5
+    ELEVENLABS_SIMILARITY_BOOST = 0.75
+    ELEVENLABS_STYLE = 0.0
+    ELEVENLABS_USE_SPEAKER_BOOST = True
+
+    # Hugging Face models
+    HF_TTS_MODELS = [
+        "facebook/mms-tts-eng",
+        "microsoft/speecht5_tts",
+        "suno/bark",
+    ]
+
+    # Timeouts
+    ELEVENLABS_TIMEOUT = 60.0
+    HF_TIMEOUT = 120.0
+
+
+class TTSGenerator:
+    """Main TTS generation class with multi-provider support."""
+
+    def __init__(
+        self,
+        elevenlabs_api_key: Optional[str] = None,
+        hf_api_key: Optional[str] = None,
+        default_voice: str = "rachel",
+        fallback_enabled: bool = True,
+    ):
+        """
+        Initialize TTS generator.
+
+        Args:
+            elevenlabs_api_key: ElevenLabs API key
+            hf_api_key: Hugging Face API key
+            default_voice: Default voice to use
+            fallback_enabled: Whether to fall back to other providers on failure
+        """
+        self.elevenlabs_api_key = elevenlabs_api_key or os.getenv("ELEVENLABS_API_KEY")
+        self.hf_api_key = hf_api_key or os.getenv("HUGGINGFACE_API_KEY")
+        self.default_voice = default_voice
+        self.fallback_enabled = fallback_enabled
+
+    async def generate_speech(
+        self,
+        text: str,
+        output_path: Path,
+        voice: Optional[str] = None,
+        provider: Optional[TTSProvider] = None,
+        **kwargs,
+    ) -> Dict[str, Any]:
+        """
+        Generate speech from text and save to file.
+
+        Args:
+            text: Text to convert to speech
+            output_path: Path to save audio file
+            voice: Voice ID or name
+            provider: Specific provider to use (if None, auto-select)
+            **kwargs: Provider-specific options
+
+        Returns:
+            Dict with generation info (provider, duration, etc.)
+        """
+        voice = voice or self.default_voice
+
+        # Auto-select provider if not specified
+        if provider is None:
+            if self.elevenlabs_api_key:
+                provider = TTSProvider.ELEVENLABS
+            elif self.hf_api_key:
+                provider = TTSProvider.HUGGINGFACE
+            else:
+                provider = TTSProvider.GTTS
+
+        # Try primary provider
+        try:
+            logger.info(f"Generating speech with {provider.value}...")
+
+            if provider == TTSProvider.ELEVENLABS:
+                result = await self._generate_elevenlabs(
+                    text, output_path, voice, **kwargs
+                )
+            elif provider == TTSProvider.HUGGINGFACE:
+                result = await self._generate_huggingface(text, output_path, **kwargs)
+            else:
+                result = await self._generate_gtts(text, output_path, **kwargs)
+
+            logger.info(f"Successfully generated speech with {provider.value}")
+            return result
+
+        except Exception as e:
+            logger.error(f"{provider.value} TTS failed: {e}")
+
+            # Try fallback if enabled
+            if self.fallback_enabled:
+                return await self._fallback_generation(
+                    text, output_path, provider, voice, **kwargs
+                )
+            else:
+                raise
+
+    async def _fallback_generation(
+        self,
+        text: str,
+        output_path: Path,
+        failed_provider: TTSProvider,
+        voice: str,
+        **kwargs,
+    ) -> Dict[str, Any]:
+        """Try alternative providers as fallback."""
+        logger.warning(f"Attempting fallback from {failed_provider.value}...")
+
+        # Define fallback order
+        if failed_provider == TTSProvider.ELEVENLABS:
+            fallback_order = [TTSProvider.HUGGINGFACE, TTSProvider.GTTS]
+        elif failed_provider == TTSProvider.HUGGINGFACE:
+            fallback_order = [TTSProvider.GTTS]
+        else:
+            raise Exception("All TTS providers failed")
+
+        for provider in fallback_order:
+            try:
+                logger.info(f"Trying fallback provider: {provider.value}")
+
+                if provider == TTSProvider.HUGGINGFACE and self.hf_api_key:
+                    return await self._generate_huggingface(text, output_path, **kwargs)
+                elif provider == TTSProvider.GTTS:
+                    return await self._generate_gtts(text, output_path, **kwargs)
+
+            except Exception as e:
+                logger.error(f"Fallback {provider.value} failed: {e}")
+                continue
+
+        raise Exception("All TTS providers failed")
+
+    async def _generate_elevenlabs(
+        self, text: str, output_path: Path, voice: str, **kwargs
+    ) -> Dict[str, Any]:
+        """Generate speech using ElevenLabs API."""
+        if not self.elevenlabs_api_key:
+            raise ValueError("ElevenLabs API key not provided")
+
+        if not ELEVENLABS_SDK_AVAILABLE:
+            raise ImportError(
+                "elevenlabs SDK not installed. Run: pip install elevenlabs"
+            )
+
+        # Get voice ID
+        voice_id = TTSConfig.ELEVENLABS_VOICES.get(voice.lower(), voice)
+
+        # Create client
+        client = ElevenLabs(api_key=self.elevenlabs_api_key)
+
+        # Generate audio using new SDK
+        def _generate():
+            return client.text_to_speech.convert(
+                text=text,
+                voice_id=voice_id,
+                model_id=kwargs.get("model_id", TTSConfig.ELEVENLABS_MODEL),
+                output_format="mp3_44100_128",
+            )
+
+        # Run in thread pool since SDK is synchronous
+        loop = asyncio.get_event_loop()
+        audio_generator = await loop.run_in_executor(None, _generate)
+
+        # Save audio
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        audio_bytes = b"".join(audio_generator)
+
+        with open(output_path, "wb") as f:
+            f.write(audio_bytes)
+
+        # Get audio info
+        file_size = len(audio_bytes)
+
+        return {
+            "provider": "elevenlabs",
+            "voice": voice,
+            "voice_id": voice_id,
+            "output_path": str(output_path),
+            "file_size_bytes": file_size,
+            "text_length": len(text),
+        }
+
+    async def _generate_huggingface(
+        self, text: str, output_path: Path, **kwargs
+    ) -> Dict[str, Any]:
+        """Generate speech using Hugging Face API."""
+        if not self.hf_api_key:
+            raise ValueError("Hugging Face API key not provided")
+
+        # Import HF wrapper
+        from utils.hf_wrapper import HuggingFaceWrapper
+
+        wrapper = HuggingFaceWrapper(api_key=self.hf_api_key)
+        model = kwargs.get("model", TTSConfig.HF_TTS_MODELS[0])
+
+        # Generate speech
+        result = await wrapper.text_to_speech(
+            text=text, model=model, output_path=str(output_path)
+        )
+
+        return {
+            "provider": "huggingface",
+            "model": model,
+            "output_path": str(output_path),
+            "text_length": len(text),
+        }
+
+    async def _generate_gtts(
+        self, text: str, output_path: Path, **kwargs
+    ) -> Dict[str, Any]:
+        """Generate speech using gTTS (Google Text-to-Speech) as last resort."""
+        try:
+            from gtts import gTTS
+        except ImportError:
+            raise ImportError("gTTS not installed. Run: pip install gtts")
+
+        # Generate speech
+        tts = gTTS(
+            text=text, lang=kwargs.get("lang", "en"), slow=kwargs.get("slow", False)
+        )
+
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        tts.save(str(output_path))
+
+        return {
+            "provider": "gtts",
+            "output_path": str(output_path),
+            "text_length": len(text),
+        }
+
+    async def get_available_voices(
+        self, provider: TTSProvider = TTSProvider.ELEVENLABS
+    ) -> Dict[str, str]:
+        """
+        Get list of available voices for a provider.
+
+        Args:
+            provider: TTS provider
+
+        Returns:
+            Dict mapping voice names to IDs
+        """
+        if provider == TTSProvider.ELEVENLABS:
+            if not self.elevenlabs_api_key:
+                return TTSConfig.ELEVENLABS_VOICES
+
+            # Fetch from API for custom voices
+            try:
+                async with httpx.AsyncClient(timeout=10.0) as client:
+                    response = await client.get(
+                        "https://api.elevenlabs.io/v1/voices",
+                        headers={"xi-api-key": self.elevenlabs_api_key},
+                    )
+                    response.raise_for_status()
+                    voices_data = response.json()
+
+                    voices = {}
+                    for voice in voices_data.get("voices", []):
+                        voices[voice["name"].lower()] = voice["voice_id"]
+
+                    return voices
+            except Exception as e:
+                logger.warning(f"Failed to fetch ElevenLabs voices: {e}")
+                return TTSConfig.ELEVENLABS_VOICES
+
+        return {}
+
+    def validate_audio_file(self, audio_path: Path) -> Dict[str, Any]:
+        """
+        Validate that audio file was generated correctly.
+
+        Args:
+            audio_path: Path to audio file
+
+        Returns:
+            Dict with validation results
+        """
+        if not audio_path.exists():
+            return {"valid": False, "error": "File does not exist"}
+
+        file_size = audio_path.stat().st_size
+
+        if file_size == 0:
+            return {"valid": False, "error": "File is empty"}
+
+        if file_size < 1000:  # Less than 1KB is suspicious
+            return {
+                "valid": False,
+                "error": "File suspiciously small",
+                "size": file_size,
+            }
+
+        # Try to check if it's valid audio (optional, requires pydub)
+        try:
+            from pydub import AudioSegment
+
+            audio = AudioSegment.from_file(str(audio_path))
+            duration = len(audio) / 1000.0  # Convert to seconds
+
+            if duration < 0.1:
+                return {
+                    "valid": False,
+                    "error": "Audio duration too short",
+                    "duration": duration,
+                }
+
+            return {
+                "valid": True,
+                "size": file_size,
+                "duration": duration,
+                "format": audio_path.suffix,
+            }
+        except ImportError:
+            # pydub not available, just check size
+            return {"valid": True, "size": file_size, "format": audio_path.suffix}
+        except Exception as e:
+            return {"valid": False, "error": f"Audio validation failed: {e}"}
+
+
+# Convenience functions
+async def generate_speech_elevenlabs(
+    text: str,
+    output_path: Path,
+    api_key: Optional[str] = None,
+    voice: str = "rachel",
+    **kwargs,
+) -> Dict[str, Any]:
+    """
+    Quick function to generate speech with ElevenLabs.
+
+    Args:
+        text: Text to convert
+        output_path: Output file path
+        api_key: ElevenLabs API key
+        voice: Voice name or ID
+        **kwargs: Additional options
+
+    Returns:
+        Generation info dict
+    """
+    generator = TTSGenerator(elevenlabs_api_key=api_key, fallback_enabled=False)
+    return await generator.generate_speech(
+        text=text,
+        output_path=output_path,
+        voice=voice,
+        provider=TTSProvider.ELEVENLABS,
+        **kwargs,
+    )
+
+
+async def generate_speech_auto(
+    text: str,
+    output_path: Path,
+    elevenlabs_key: Optional[str] = None,
+    hf_key: Optional[str] = None,
+    voice: str = "rachel",
+    **kwargs,
+) -> Dict[str, Any]:
+    """
+    Auto-select best available TTS provider.
+
+    Args:
+        text: Text to convert
+        output_path: Output file path
+        elevenlabs_key: ElevenLabs API key
+        hf_key: Hugging Face API key
+        voice: Voice name
+        **kwargs: Additional options
+
+    Returns:
+        Generation info dict
+    """
+    generator = TTSGenerator(
+        elevenlabs_api_key=elevenlabs_key,
+        hf_api_key=hf_key,
+        default_voice=voice,
+        fallback_enabled=True,
+    )
+    return await generator.generate_speech(text=text, output_path=output_path, **kwargs)