Math Video Creator (MVC)

An intelligent, AI-powered system for automated generation of high-quality educational mathematics videos using Manim.

Overview

Math Video Creator (MVC) is a sophisticated, production-grade system that leverages multi-agent AI architecture to automatically plan, generate, render, and review educational mathematics videos. Built on the powerful Manim animation engine, MVC transforms mathematical concepts into engaging visual content through an intelligent orchestration of specialized AI agents.

Key Capabilities

Automated Content Planning: AI-driven decomposition of complex mathematical topics into structured, pedagogically sound storyboards
Intelligent Code Generation: Automatic translation of conceptual descriptions into executable Manim animations with self-repair capabilities
Quality Assurance: Vision-based AI review of rendered content for layout optimization and visual clarity
Real-time Monitoring: Interactive dashboard providing live progress tracking and result visualization
Production-Ready: Enterprise-grade error handling, distributed tracing, and comprehensive test coverage

🏗️ Architecture

MVC implements a modular Orchestrator-Agent Pattern designed for scalability, maintainability, and extensibility:

System Components

API Layer (FastAPI)
- RESTful endpoints for video generation requests
- Asynchronous task management
- WebSocket support for real-time status updates
Orchestrator
- Central state machine coordinating the video production lifecycle
- Agent coordination and workflow management
- Error recovery and retry logic
Specialized AI Agents
- Planner Agent: Decomposes mathematical topics into structured JSON storyboards with scene-level visual cues and narration scripts
- Code Generator Agent: Translates scene descriptions into executable Manim code with automatic syntax error correction
- Reviewer Agent: Analyzes rendered frames using vision models to ensure layout quality, text legibility, and visual balance
Rendering Engine
- Sandboxed execution environment for Manim scripts
- Resource management and output file handling
- Frame extraction for quality review
Frontend Dashboard (React + Vite)
- Intuitive user interface for topic submission
- Real-time progress visualization
- Video preview and download capabilities

Architecture Diagram

graph TD
    User[User / React Frontend] -->|Topic Request| API[FastAPI Backend]
    API -->|Initialize Job| Orch[Orchestrator]
    
    subgraph Agentic Workflow
        Orch -->|1. Request Plan| Plan[Planner Agent]
        Plan -->|JSON Storyboard| Orch
        
        Orch -->|2. Generate Code| Gen[Generator Agent]
        Gen -->|Manim Python Code| Orch
        
        Orch -->|3. Execute Render| Render[Manim Renderer]
        Render -->|MP4 + Frames| Orch
        
        Orch -->|4. Quality Review| Review[Reviewer Agent]
        Review -->|Feedback & Metrics| Orch
        
        Orch -.->|5. Self-Repair| Gen
    end
    
    subgraph Core Utilities
        TS[TeachingScene Base Class]
        Render -->|Inherits| TS
    end

    Orch -->|Status Updates| API
    API -->|SSE/Polling| User

🧩 Core Components

Component	Location	Responsibility
Orchestrator	`backend/orchestrator.py`	Manages the complete video generation lifecycle, coordinates agent interactions, and maintains workflow state
Planner Agent	`backend/agents/planner.py`	Leverages LLMs to decompose mathematical topics into pedagogically structured scene-by-scene storyboards
Code Generator	`backend/agents/generator.py`	Transforms scene descriptions into production-ready Manim code using the TeachingScene framework
Visual Reviewer	`backend/agents/reviewer.py`	Employs vision-language models to analyze rendered frames for quality assurance
TeachingScene	`backend/utils/manim_base.py`	Provides a standardized 2-column layout system (Notes + Animation Grid) ensuring visual consistency
Renderer	`backend/utils/render.py`	Abstracts Manim CLI interactions, manages subprocess execution, and handles output artifacts
Frontend App	`frontend/src/App.tsx`	Delivers an interactive React-based interface for user interaction and real-time monitoring

🚀 Key Features

AI & Intelligence

Multi-Agent Collaboration: Specialized agents work in concert to handle distinct aspects of video production
Self-Healing Code: Automatic error detection and correction through iterative refinement loops
Vision-Based QA: Multimodal AI (GPT-4o/Claude-3.5) analyzes visual output for quality metrics
LLM-as-a-Judge: Automated evaluation framework for measuring content quality and educational value

Engineering Excellence

Type Safety: Comprehensive Pydantic models ensure data integrity across agent boundaries
Robust Error Handling: Graceful degradation with retry mechanisms and fallback strategies
Distributed Tracing: OpenTelemetry-compatible span-based observability exported to structured logs
Asynchronous Architecture: Non-blocking workflows handle long-running rendering tasks efficiently

User Experience

Real-Time Feedback: Live progress updates during video generation
TeachingScene Grid System: 10×10 coordinate system prevents visual clutter and element overlap
Flexible LLM Support: Compatible with OpenAI, Anthropic, and local model providers

🛠️ Technology Stack

Backend

Runtime: Python 3.10+
Web Framework: FastAPI with async/await support
AI/ML: OpenAI API, Anthropic Claude (via adapters)
Animation: Manim Community Edition
Validation: Pydantic v2
Testing: pytest with comprehensive fixtures

Frontend

Framework: React 19 with TypeScript
Build Tool: Vite
Styling: TailwindCSS v4
State Management: React Hooks

Infrastructure

Observability: Custom tracing with JSON export
Process Management: Subprocess isolation for rendering
API Design: RESTful with OpenAPI documentation

📋 Prerequisites

Before setting up MVC, ensure you have the following installed:

Python: Version 3.10 or higher
Node.js: Version 18 or higher
npm: Version 9 or higher
FFmpeg: Required by Manim for video rendering
LaTeX: Required by Manim for mathematical typesetting (e.g., TeX Live, MiKTeX)

System Dependencies

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install -y python3-pip python3-dev ffmpeg texlive texlive-latex-extra

macOS:

brew install python@3.10 ffmpeg
brew install --cask mactex

📦 Installation & Setup

1. Clone the Repository

git clone https://github.com/yourusername/MVC-Math-Video-Creator.git
cd MVC-Math-Video-Creator

2. Backend Setup

cd backend

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Configure environment variables
cp .env.example .env
# Edit .env and add your API keys

Required Environment Variables:

OPENAI_API_KEY=your_openai_api_key_here
# Optional: For Claude support
ANTHROPIC_API_KEY=your_anthropic_api_key_here

3. Frontend Setup

cd ../frontend

# Install dependencies
npm install

# Optional: Configure environment
cp .env.example .env

4. Start the Application

Terminal 1 - Backend:

cd backend
python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000

Terminal 2 - Frontend:

cd frontend
npm run dev

The application will be available at:

Frontend: http://localhost:5173
Backend API: http://localhost:8000
API Documentation: http://localhost:8000/docs

📖 Usage

Basic Workflow

Access the Dashboard: Navigate to http://localhost:5173 in your browser
Submit a Topic: Enter a mathematical concept (e.g., "The Fundamental Theorem of Calculus")
Monitor Progress: Watch real-time updates as agents plan, generate, and render your video
Review Output: Preview the generated video and download the final MP4

API Usage

For programmatic access, use the REST API:

curl -X POST "http://localhost:8000/api/generate" \
  -H "Content-Type: application/json" \
  -d '{"topic": "Pythagorean Theorem", "difficulty": "beginner"}'

Response:

{
  "job_id": "abc123",
  "status": "processing",
  "created_at": "2026-01-27T13:52:18Z"
}

Check status:

curl "http://localhost:8000/api/jobs/abc123"

🧪 Testing

MVC includes a comprehensive test suite covering unit, integration, and end-to-end scenarios.

Running Tests

cd backend

# Install development dependencies
pip install -r requirements-dev.txt

# Run all tests with verbose output
pytest tests/ -v

# Run with coverage report
pytest tests/ --cov=. --cov-report=html

# Run specific test modules
pytest tests/test_planner.py -v

Test Coverage

End-to-End Workflows: Complete video generation pipeline validation
Agent Behavior: Planner output structure, code generator syntax, reviewer analysis
Error Recovery: Retry logic, fallback mechanisms, self-repair loops
TeachingScene System: Grid coordinate validation, layout constraints
API Endpoints: Request validation, response schemas, error handling

Continuous Integration

Tests are automatically run on:

Pull requests to main branch
Commits to development branch
Scheduled nightly builds

📊 Evaluation & Benchmarking

MVC includes an automated evaluation framework for measuring agent performance.

Running Evaluations

cd backend
python -m evals.eval_planner

Evaluation Process

Test Suite: Evaluates the Planner agent on 10 diverse mathematical topics
LLM-as-a-Judge: Uses GPT-4 to score outputs on multiple dimensions
Report Generation: Produces detailed JSON reports in evals/results/

Metrics

Metric	Description	Target
Scene Count	Number of scenes per video	2-8 scenes
Visual Specificity	Clarity of visual cue descriptions	≥ 4.0/5.0
Narration Quality	Educational clarity and engagement	≥ 4.0/5.0
Logical Flow	Coherence of topic progression	≥ 4.5/5.0
Educational Value	Overall pedagogical effectiveness	≥ 4.0/5.0

🔍 Observability & Debugging

Distributed Tracing

All agent executions are automatically traced with structured logging:

# View trace for a specific job
cat traces/<trace_id>.jsonl | jq

# Filter by agent type
cat traces/<trace_id>.jsonl | jq 'select(.agent_type == "planner")'

Trace Span Structure

Each span includes:

Trace ID: Unique identifier for the entire workflow
Span ID: Unique identifier for the specific operation
Parent Span ID: Hierarchical relationship tracking
Duration: Execution time in milliseconds
Attributes: Agent-specific metadata (model, temperature, token usage)
Events: Key milestones during execution
Status: Success, error, or warning indicators

Logging

Structured logs are written to:

Console: Real-time output during development
Files: logs/app.log for persistent storage
Traces: traces/*.jsonl for detailed execution analysis

📁 Project Structure

MVC-Math-Video-Creator/
├── backend/
│   ├── agents/
│   │   ├── planner.py          # Topic decomposition agent
│   │   ├── generator.py        # Manim code generation agent
│   │   └── reviewer.py         # Visual quality assurance agent
│   ├── core/
│   │   ├── base_agent.py       # Abstract agent base class
│   │   └── models.py           # Pydantic data models
│   ├── utils/
│   │   ├── manim_base.py       # TeachingScene framework
│   │   ├── render.py           # Manim rendering wrapper
│   │   └── tracing.py          # Observability utilities
│   ├── evals/
│   │   ├── eval_planner.py     # Planner evaluation harness
│   │   └── results/            # Evaluation reports
│   ├── tests/
│   │   ├── test_planner.py
│   │   ├── test_generator.py
│   │   └── test_orchestrator.py
│   ├── orchestrator.py         # Main workflow coordinator
│   ├── main.py                 # FastAPI application
│   ├── requirements.txt        # Production dependencies
│   └── requirements-dev.txt    # Development dependencies
├── frontend/
│   ├── src/
│   │   ├── components/         # React components
│   │   ├── App.tsx             # Main application
│   │   └── main.tsx            # Entry point
│   ├── package.json
│   └── vite.config.ts
├── traces/                     # Execution traces
├── logs/                       # Application logs
├── outputs/                    # Generated videos
├── Makefile                    # Development automation
├── README.md
└── LICENSE

🤝 Contributing

We welcome contributions from the community! Please follow these guidelines:

Development Workflow

Fork the repository and create a feature branch
Install development dependencies: pip install -r requirements-dev.txt
Make your changes with appropriate tests
Run the test suite: pytest tests/ -v
Ensure code quality: black . && flake8 . && mypy .
Submit a pull request with a clear description

Code Standards

Style: Follow PEP 8 for Python, ESLint for TypeScript
Type Hints: Required for all Python functions
Documentation: Docstrings for public APIs, inline comments for complex logic
Testing: Minimum 80% code coverage for new features

Reporting Issues

Please use GitHub Issues and include:

Clear description of the problem
Steps to reproduce
Expected vs. actual behavior
Environment details (OS, Python version, etc.)

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
backend		backend
frontend		frontend
ARCHITECTURE.md		ARCHITECTURE.md
Makefile		Makefile
README.md		README.md

mo1998/MVC-Math-Video-Creator

Folders and files

Latest commit

History

Repository files navigation