GitHub - HarleyCoops/Math-To-Manim: Create Epic Math and Physics Animations & Study Notes From Text and Images.

Ask a question -> get a reasoned movie

Motion showcase · Architecture · Prime RL · Roadmap · Agent guide

Math-To-Manim turns serious math and physics prompts into Manim explainer videos and the reusable artifacts that produced them: intent, prerequisite graphs, lesson plans, math packets, storyboards, scene specs, generated code, validation reports, render evidence, review notes, and stage traces. Browse the local GIF gallery →

Code-grounded workflow: every run stays inspectable from prompt to artifacts to render.

What this is Math-To-Manim started on the morning of Donald Trump's second inauguration. Around 4:30 a.m. my time on January 20, 2025, DeepSeek, a Chinese AI lab, released R1 on Hugging Face. I read the timing as deliberate: a Sputnik-style signal that open reasoning models were now a geopolitical fact. My first move was to clone R1 and point it at math reasoning. The interesting part was not just that a reasoning model could solve math; it was that the path to a good explanation could be made visible. A topic could become prerequisites, then a teaching order, then equations, then screen beats, then Manim code, then a movie. M2M2 is the pipeline that grew out of that experiment. A teacher, tutor, parent, student, researcher, or agent can bring a short question, a lesson idea, or a dense technical note and get back an inspectable explanation: the concept, the missing prerequisites, the order of ideas, the screen beats, the generated Manim code, and optionally the rendered video. The render can be a strong first pass at a four-to-five-minute explainer, with real mathematical and physical notation in LaTeX instead of decorative pseudo-math. The product is not only the MP4. Each run bundle preserves the reasoning artifacts and math that led to the scene, which makes the output useful for debugging, agent handoff, and reinforcement-learning work such as the Prime Intellect repair environment.

The next direction is recursive editing. Inspired by Recursive Language Models, the goal is to treat a finished movie and its run bundle as an environment an agent can inspect and revise. A request like, "rerender this, but tilt the camera so the equations are easier to read," should route back through the scene plan and Manim code, recompute the right change, validate it, render again, and leave a new trace that can train the next policy. This repo is the build log for that loop: agents learning to reason through complex topics, preserve their work, and turn the reasoning into visual explanations.

Christian

Today, that means a durable agent pipeline with:

audience-aware request artifacts, from grade-school intuition to advanced notation; a prerequisite-story pipeline inspired by the original reverse knowledge tree; typed Pydantic artifacts between every stage; OpenAI Agents SDK-compatible adapters for planning and generation; optional Codex CLI-backed codegen for subscription-authenticated iteration; a reproducible runs/<run_id>/ bundle for every generation; static validation, render metadata, review artifacts, and manifests that are easy to inspect in CI or by another agent.

The design principle is simple: story before symbols, geometry before algebra, artifacts before side effects.

Reverse reasoning pipeline A normal text-to-code demo jumps from request to Python. Math-To-Manim takes the long way on purpose: it reasons backward from the final concept to the prerequisites, then walks forward through a teachable visual sequence. The code path is explicit in math_to_manim/pipeline/runner.py. AnimationPipeline.generate() runs a fixed stage chain: IntentAgent, PrerequisiteGraphAgent, CurriculumAgent, MathAgent, StoryboardAgent, SceneSpecAgent, ManimCodeAgent, StaticReviewAgent, RenderAgent, VideoReviewAgent, and PublisherAgent.

Stage Why it exists Artifact

Intent Clarify what the learner is really asking. intent.json

Reverse prerequisites Build the knowledge graph needed before the target idea. knowledge_graph.json

Curriculum Turn the graph into a teachable order. curriculum.json

Math packet Select definitions, equations, assumptions, and examples. math_packet.json

Storyboard Decide the screen beats before code exists. storyboard.json

Scene spec Compile the visual plan into Manim objects, animations, timing, and camera notes.

scene_spec.json

Code, validation, render, review Generate runnable Manim, gate it with static checks, render when allowed, and package the evidence. generated_scene.py, reports, manifest

That gives every run a memory: JSON contracts, generated code, render results, review notes, and a manifest. The output is not just a video; it is an inspectable path from question to understanding to animation. For current editable-video status and the planned prompt/spec/code edit loop, see the roadmap.

Prime Intellect RL repair loop Math-To-Manim is also becoming a Prime Intellect reinforcement-learning environment. The first RL target is not "make the whole video in one shot." It is the repair move that matters most when generated animation code fails: take the typed scene plan, the broken generated_scene.py, and validation/render evidence, then return corrected Manim Python that is safe, sparse, and more likely to render.

The current hub environment is harleycooper/math-to-manim. A repair task carries the original prompt, typed scene_spec, generated Manim Python, static-validation report, and render/recovery evidence when available. The model must return one strict GeneratedCode JSON block. The Verifiers reward checks whether the proposed code parses, defines the expected Manim scene, avoids unsafe imports and calls, preserves expected math terms, and reduces obvious text/layout crowding hazards. generated_scene.py + scene_spec + validation/render evidence -> Prime Intellect Verifiers environment -> model proposes corrected GeneratedCode JSON -> static reward checks parseability, scene shape, safety, terms, layout -> hosted RL updates the repair policy -> corrected, renderable Manim Python flows back into M2M2 recovery

That keeps the fast RL loop text-and-AST based while the slower Manim renderer remains the audit gate. The intended result is a model that learns the house style of this repo: cinematic but readable scenes, sparse formulas, staged captions, safe Manim code, and scripts that are much more likely to render on the first recovery attempt.

Current hosted-training status: the environment action passes on Prime, the hub package is published as harleycooper/math-to-manim@0.1.1, a 1-step smoke completed, and a 25-step W&B-enabled pilot has been launched on Qwen/Qwen3.5-35B-A3B. See the full integration notes in docs/PRIME_INTELLECT_RL.md.

Clone and run 1. Clone Windows PowerShell: git clone https://github.com/HarleyCoops/Math-To-Manim.git cd Math-To-Manim python -m venv .venv .\.venv\Scripts\Activate.ps1 python -m pip install -U pip python -m pip install -e ".[dev]" python -m pytest macOS / Linux / WSL: git clone https://github.com/HarleyCoops/Math-To-Manim.git cd Math-To-Manim python3 -m venv .venv source .venv/bin/activate python -m pip install -U pip python -m pip install -e ".[dev]" python -m pytest 2. Run a no-API smoke test This proves the CLI, artifact contracts, and validators are wired before you spend model or render time: math-to-manim generate "Explain why derivatives are slopes" --deterministic --no-render Equivalent module form: python -m math_to_manim.cli generate "Explain why derivatives are slopes" --deterministic --no-render 3. Generate with model calls Set an OpenAI key and choose a model if desired: export OPENAI_API_KEY="sk-..." export OPENAI_MODEL="gpt-4.1" math-to-manim generate "Explain Fourier epicycles as rotating vectors" --no-render PowerShell: $env:OPENAI_API_KEY = "sk-..." $env:OPENAI_MODEL = "gpt-4.1" math-to-manim generate "Explain Fourier epicycles as rotating vectors" --no-render 4.

Install render extras when you want MP4 output Python render dependency: python -m pip install -e ".[dev,render]" System render dependencies are also needed for real Manim output, especially FFmpeg and LaTeX for MathTex. On Debian/Ubuntu/WSL: ./scripts/bootstrap-render.sh The package list lives in requirements-system.txt.

Codex CLI codegen path Math-To-Manim can keep the typed planning pipeline while sending the Manim codegen and repair loop through a locally authenticated Codex CLI session. Check Codex first: codex --version codex exec "Say ready from inside this repo" Then route codegen through Codex: math-to-manim generate "Explain derivatives as slopes with a cinematic tangent-line reveal" \ --codegen-provider codex-cli \ --codex-full-auto \ --style cinematic \ --quality l Earlier planning stages remain on the typed adapters; only the generated-code and repair stages move first. That makes the migration incremental instead of all-or-nothing.

What lands on disk A generation writes a self-contained run bundle: runs/<run_id>/ request.json intent.json knowledge_graph.json curriculum.json math_packet.json storyboard.json scene_spec.json generated_code.json generated_scene.py validation_report.json render_result.json review_report.json trace.jsonl # stage-boundary events when tracing is enabled recovery_manifest.json # after recover-render draft_review/ draft_review.md contact_sheet.png frames/ animation_package.json manifest.json

After editing generated_scene.py inside a run bundle, rerun the recovery path: math-to-manim recover-render runs/<run_id> --quality l That command refreshes validation, render, review, draft-review assets, and recovery_manifest.json without regenerating upstream planning artifacts.

Package layout: math_to_manim/ agents/ # stage adapters schemas/ # versioned artifact contracts tools/ # graph, validation, rendering, video, artifact helpers pipeline/ # orchestration, tracing, repair loop rendering/ # Manim and FFmpeg wrappers review/ # static and visual review scoring

Hermes Agent Hermes is the contributor/operator agent around this repository. It is not imported by Math-To-Manim and is not a runtime dependency; it uses the repo the way a developer would: read files, search code, patch docs and code, run terminal checks, inspect generated artifacts, review frames or GIFs, track todos, delegate larger work, and preserve stable context through skills. That makes Hermes useful for maintaining the reverse-reasoning pipeline without becoming part of it. A Hermes session can inspect AGENTS.md, pyproject.toml, schemas, tests, and runs/<run_id>/ bundles; run pytest, CLI smoke commands, Manim, FFmpeg, and git checks; then verify that docs, code, and showcase media still match the artifact contracts. Repo-local Hermes skills live under hermes/skills/. The old Claude ./skill path is historical; current contributor guidance is in AGENTS.md, with launch notes in docs/HERMES_LEARNS_MANIM.md.

Motion showcase Sixteen curated GIFs are tracked under docs/showcase/assets/ as the art direction target for Math-To-Manim's visual explanations.

See the full gallery with descriptions: docs/showcase/README.md. Make a README-sized GIF from a render MP4="media/videos/your_scene/480p15/YourScene.mp4"

ffmpeg -y -ss 95 -t 24 -i "$MP4" \ -vf "fps=12,scale=720:-1:flags=lanczos,split[s0][s1];[s0]palettegen=max_colors=96[p];[s1][p]paletteuse=dither=bayer:bayer_scale=5" \ docs/showcase/assets/your-clip.gif Adjust -ss and -t to capture the teaching beat you want.

License MIT.