Update to latest versions of all source files

app.py.new

@@ -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()

orchestrator.py

@@ -167,8 +167,6 @@ class NeuroAnimOrchestrator:
         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."""
 
@@ -177,8 +175,6 @@ class NeuroAnimOrchestrator:
 
             # 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",
@@ -197,8 +193,6 @@ class NeuroAnimOrchestrator:
 
             # 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",
@@ -215,21 +209,13 @@ class NeuroAnimOrchestrator:
                     f"Narration generation failed: {narration_result['text']}"
                 )
 
-            # Clean narration text - remove title/prefix before TTS
-            narration_text = self._clean_narration_text(narration_result["text"])
+            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,
+                topic=topic, concept_plan=concept_plan, max_retries=3
             )
             logger.info("Manim code generation completed and validated")
 
@@ -249,108 +235,33 @@ class NeuroAnimOrchestrator:
             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
+            # Step 5: Render Animation
             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,
-                    },
-                )
+            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": "medium",
+                    "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 render_result["isError"]:
+                raise Exception(f"Rendering failed: {render_result['text']}")
+
+            # Find rendered video file
+            video_file = self._find_output_file(self.work_dir, scene_name, "mp4")
             if not video_file:
-                raise Exception("Could not find rendered video file after all attempts")
+                raise Exception("Could not find rendered video file")
 
             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
@@ -380,8 +291,6 @@ class NeuroAnimOrchestrator:
 
             # 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,
@@ -398,8 +307,6 @@ class NeuroAnimOrchestrator:
 
             # 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",
@@ -441,68 +348,28 @@ class NeuroAnimOrchestrator:
                 "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:
+    def _extract_python_code(self, response_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 "```python" in response_text:
+            start = response_text.find("```python") + 9
+            end = response_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)
+                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(text)
-            return text[start:end].strip()
+                end = len(response_text)
+            return response_text[start:end].strip()
         else:
-            return text.strip()
+            return response_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,
@@ -517,13 +384,11 @@ class NeuroAnimOrchestrator:
                     "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
+                if previous_error and previous_code:
+                    arguments["previous_code"] = previous_code
                     arguments["error_message"] = previous_error
                     logger.info(
                         f"Retrying with error feedback: {previous_error[:100]}..."
@@ -540,7 +405,6 @@ class NeuroAnimOrchestrator:
                             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(
@@ -565,25 +429,6 @@ class NeuroAnimOrchestrator:
                             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
@@ -604,101 +449,23 @@ class NeuroAnimOrchestrator:
             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)}^"
-
+            if e.text:
+                error_msg += f"\n  {e.text.rstrip()}"
+                if e.offset:
+                    error_msg += f"\n  {' ' * (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.")
+        # Look for class definition that inherits from Scene, MovingCameraScene, etc.
+        match = re.search(r"class\s+(\w+)\s*\(\s*\w*Scene\s*\)", code)
+        if match:
+            return match.group(1)
         return "Scene"  # fallback
 
     def _find_output_file(

orchestrator.py.new

@@ -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())