Math to Manim

Ask a question -> reverse reasoning -> Manim movie

Motion showcase · Architecture · Roadmap · Agent guide

Math-To-Manim turns short prompts into reverse-reasoned lesson plans, typed pipeline artifacts, generated Manim code, and reusable visual explanations.

Browse the local GIF gallery →

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

---

What this is

Math to Manim is for the moment when a learner asks, “Can you show me why?” A teacher, tutor, parent, or guardian can type a question and get back a visual explanation plan: the concept, the missing prerequisites, the order of ideas, the screen beats, the generated Manim code, and optionally the rendered video.

The input can be short, but the product is the explanation: what the learner needs to understand, what should appear first, where the aha moment lives, and which visual metaphor makes the idea feel inevitable.

Math-To-Manim proves that calculus, topology, chaos, spacetime, stochastic finance, and ML concepts can become useful mathematical motion when agents plan the explanation before they write code.

This repo turns that idea into a durable agent pipeline:

• 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.

---

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
  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.

Geometry as spectacle	Topology as choreography	Chaos as intuition

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.