Project Overview
Math‑To‑Manim is an open‑source Python project hosted on GitHub. The project's core goal is to address common issues in AI‑generated animations: vague prompts that lead to LaTeX errors, conceptual jumps, or visually incoherent output. Driven by a multi‑agent system and large models such as Claude Sonnet 4.5, it can produce detailed prompts exceeding 2000 tokens, generate Manim‑compatible Python code, and render MP4 videos. The project is MIT‑licensed and suited for education, research, and content creation, covering topics from high‑school to graduate level. A Kimi K2 implementation was added on 2025‑11‑06 to improve tool invocation and API compatibility. As of 2025‑11‑14 the repository has surpassed 1,000 stars and maintains an active community.
Core Innovation: Reverse Knowledge Tree
The standout feature of Math‑To‑Manim is the "Reverse Knowledge Tree" algorithm. This is a recursive prerequisite‑discovery mechanism that avoids the limitations of one‑size‑fits‑all prompts. Traditional pipelines such as "simple prompt → pattern match → random output" are error‑prone and struggle with novel concepts. The Reverse Knowledge Tree proceeds in reverse:
- Input: a user prompt, e.g. "explain cosmology."
- Process: recursively ask "what must be understood before X?" For instance, cosmology traces back to general relativity, then special relativity, Lorentz transformations, down to high‑school physics basics.
- Output: construct a concept dependency graph that layers LaTeX formulas, visual metaphors, and a narrative arc from fundamentals upward.
This method does not require a training dataset; relying on Claude Sonnet 4.5's reasoning ability it can generate coherent animation paths. Future plans include integrating the Nomic Atlas semantic knowledge graph to enable 10x‑accelerated prerequisite caching and a community‑shared database (see docs/NOMIC_ATLAS_INTEGRATION.md). This bottom‑up construction ensures pedagogical clarity and avoids the common pitfall of "teaching the advanced material first and backfilling basics."
System Architecture: Multi‑Agent Pipeline
The project uses a six‑agent system (a seventh VideoReview agent is in development), built on the Claude Agent SDK, supporting automatic context management and tool integration (file ops, code execution, etc.). The pipeline is as follows:
- ConceptAnalyzer: parses the prompt and identifies core concepts, domain, and difficulty level (e.g., high‑school vs. graduate quantum mechanics).
- PrerequisiteExplorer: the core agent that recursively builds the knowledge tree and generates the dependency graph.
- MathematicalEnricher: adds LaTeX formulas to each node to ensure mathematical rigor (example formula: \mathcal{L}_{\text{QED}} = \bar{\psi}(i \gamma^{\mu} D_{\mu} ‑ m)\psi ‑ \tfrac{1}{4}F_{\mu\nu}F^{\mu\nu}).
- VisualDesigner: designs visual elements such as camera moves, color schemes (electric field in red, magnetic field in blue), and transitions.
- NarrativeComposer: weaves the narrative from fundamentals to the target, producing detailed prompts exceeding 2000 tokens.
- CodeGenerator: translates the plan into Manim Python code with LaTeX rendering support.
A new Kimi K2 pipeline (KimiK2Thinking/ folder) uses an OpenAI‑compatible API and tool calls to provide structured data extraction, focusing on LaTeX rather than Manim class implementations. The full pipeline typically runs in 1–2 minutes; render times depend on quality (low quality 10–30s, high quality 1–5 minutes).
Installation
Installation is straightforward and supports Windows, Linux, and macOS. Requirements: Python 3.10+, FFmpeg (for video rendering), and Manim v0.19.0. Minimum 8GB RAM, 16GB recommended; GPU optional for accelerated rendering.
1. Clone the repository:
git clone https://github.com/HarleyCoops/Math-To-Manim\ncd Math-To-Manim\n
2. Install dependencies:
pip install -r requirements.txt\n
(Includes Manim, the Claude SDK, etc.; additional packages may be needed if offline.)
3. Configure API keys:
- Claude:
echo "ANTHROPIC_API_KEY=your_key_here" > .env(obtain from Anthropic). - Kimi K2:
echo "MOONSHOT_API_KEY=your_key_here" >> .env(Moonshot AI).
4. Install FFmpeg:
- Windows:
choco install ffmpeg(requires Chocolatey). - Linux:
sudo apt-get install ffmpeg. - macOS:
brew install ffmpeg.
Verify the setup by running manim --version and ensuring v0.19.0. See requirements.txt for full details.
Usage
The project provides three interfaces: a Gradio UI, a CLI, and example runner scripts. Beginners are recommended to use the UI.
1. Gradio UI (recommended for newcomers):
python src/app_claude.py\n
- Open a browser at
localhost:7860. - Enter a prompt such as "visualize the Pythagorean theorem" or "explain optimal transport theory."
- Agents will automatically build the tree, generate code, and render video. Kimi mode is supported.
2. Kimi K2 pipeline (CLI):
# test integration\npython KimiK2Thinking/examples/test_kimi_integration.py\n# run full pipeline (requires tree.json)\npython KimiK2Thinking/examples/run_enrichment_pipeline.py tree.json\n
See KimiK2Thinking/README.md for details; suitable for batch processing.
3. Run example animations: The examples/ folder is organized by topic. Use the Manim CLI:
# quantum mechanics example\nmanim -pql examples/physics/quantum/QED.py QEDJourney\n# geometry example\nmanim -pql examples/mathematics/geometry/pythagorean.py PythagoreanScene\n# cosmology\nmanim -pql examples/cosmology/Claude37Cosmic.py CosmicScene\n
Flag explanations:
- ‑p: preview after rendering.
- ‑q: quality (l low, m medium, h high, k 4K).
- ‑l: low‑resolution fast test.
4. Generate study notes: send Manim code back to an LLM with the prompt "generate LaTeX study notes" to produce a PDF‑ready document.
Prompting tips: enrich descriptions with LaTeX, e.g. "display the Minkowski spacetime metric ds^2 = ‑c^2 dt^2 + dx^2 + dy^2 + dz^2 and highlight the time component."
Examples and Applications
The repository contains 55+ examples detailed in docs/EXAMPLES.md. By difficulty:
- Basic (high‑school):
geometry/pythagorean.py– a proof of the Pythagorean theorem showing triangle decomposition and area animations. - Intermediate (undergraduate):
mathematics/analysis/optimal_transport.py– optimal transport theory, visualizing the Wasserstein distance and particle flows. - Advanced (graduate):
physics/quantum/QED.py– a QED journey including Feynman diagrams, the Lagrangian density, and renormalization flow. - Frontier (research):
computer_science/machine_learning/GRPO.py– Group Relative Policy Optimization, showing reward shaping and gradient flow in RL. - Creative:
misc/recursive_rhombicosidodecahedron.py– a recursive rhombicosidodecahedron fractal with 3D self‑similar transforms.
Practical uses: educators create animated lecture materials; researchers visualize models such as ProLIP (probabilistic visual‑language models) for contrastive learning. Examples can be generated directly from a single prompt without manual edits.
Supported Models
The project is cross‑model compatible; examples use multiple LLMs to capture diverse perspectives:
- Claude Sonnet 4.5: the primary agent system, strong in recursive reasoning and context management (Claude SDK).
- Kimi K2: Moonshot AI, new pipeline with tool calling and chain‑of‑thought mode, cost‑effective and API‑friendly.
- DeepSeek R1: used for quantum‑physics examples, excels at precise formulas.
- Gemini 2.5 Pro: alternative for QED visualization.
- Grok 3: quantum mechanics paths (xAI model).
- Qwen Max: mathematical analysis.
- Mistral Large: gravitational‑wave examples.
To switch models, edit the .env file or the agent scripts. Claude is the default; Kimi is suited to OpenAI ecosystems.
FAQ and Troubleshooting
- LaTeX errors: agents validate formulas and, on error, return diagnostics to the LLM for correction.
- Slow rendering: use ‑ql for testing; split renders in low‑RAM scenarios.
- No GPU: CPU‑only rendering is supported by Manim.
- Commercial use: MIT license permits commercial use; attribution is recommended.
- Accuracy: LaTeX enforces precision and the knowledge tree ensures logical consistency; community testing covers edge cases.
Roadmap
Short term (1–2 months): complete the VideoReview agent, test suite, and knowledge‑tree visualization UI. Medium term (3–6 months): Nomic Atlas integration for a semantic graph and 10x acceleration. Long term (6–12 months): community platform, animation library, and RL fine‑tuning. Current status: refactored to the Claude SDK with full examples (November 2025).