Explainer Engine

Three examples to watch

Citation gate · 76 seconds / Evidence budget · 62 seconds / Earlier example: Harness-Field · 57 seconds

What the verified badge actually promises · 76 seconds

The gate’s own code shows what it takes to earn a verified badge—plain tokens that match whole words, evidence on the first and last cited lines and, when the script pins a commit, a matching HEAD on a clean tree unless explicitly allowed—and what the badge does not promise. Read its script.

Public 9a59b3f example; script and cited source available. Its verified badge names no commit (the script does not pin one). English narration, English and Chinese captions. Open video (MP4)

At 52 seconds: verifier.py lines 328–342. If the checked-out commit doesn’t start with the claimed one, the gate records “commit_mismatch”; unless dirty files are allowed, uncommitted changes record “dirty_tree”. Tags read simplified and verified. — Still at 52 seconds · Open full size

How much evidence does a citation need? · 62 seconds

A graph and code show how many evidence tokens the planner lets a citation carry, and why it drops a citation with too little evidence.

Public c345e66 example; script and cited source available. Its verified badge names no commit (the script does not pin one). English narration, English and Chinese captions. Open video (MP4)

At 12 seconds: a two-tokens-per-line graph above TOKENS_PER_LINE = 2 and its evidence.py:56 citation. — Still at 12 seconds · Open full size

Earlier example: Harness-Field · 57 seconds

Made with an earlier local snapshot of the engine. Five influences on an AI agent’s actions become forces and paths—an attempt to make an abstract relationship easier to follow.

Earlier local example; its historical verification result is not independently checkable. English narration, English and Chinese captions. Open video (MP4)

This page can show captions below the picture to keep code clear. Fullscreen playback and browsers without JavaScript use native captions. Text embedded in the videos has not been remade and remains small on phones; use fullscreen or the scripts for detail.

From script to screen

The input is a YAML A declarative script for a video: an ordered list of beats — plots, cited code callouts, concept diagrams — each with narration text. It is the engine's only input; nothing it doesn't specify appears on screen. specifying scenes, narration and source citations—not arbitrary code uploaded for an automatically reliable explanation. This is an excerpt from the second video’s per-line beat; the frame comes from 12 seconds into the existing video.

Input: an actual YAML excerpt

code_callout:
  display: "TOKENS_PER_LINE = 2"
  language: python
  cite: "explainer/plan/evidence.py:56"
  evidence: ["TOKENS_PER_LINE", "2"]

The excerpt specifies the displayed code, the cited source line and the evidence to find; the same beat defines its curve as 2 * x. The on-screen code is a teaching view marked simplified, not a verbatim source listing. Read the full script.

Check citationsThe citation gate checks whether the cited lines contain the evidence declared in the script: plain tokens as whole words, with evidence on the first and last cited lines. If any citation fails, rendering stops before scene code is generated.
Generate the scene by fixed rulesThe script compiles into A programmatic animation library for mathematical and technical video. Scenes are code, not timeline edits — which is what lets a generator emit them deterministically. scene code; no language model writes that code.
Render and narrateManim renders the visuals, and a text-to-speech service synthesizes the narration. These examples also provide English and Chinese caption tracks.

Separately, the optional explainer plan uses a language model to draft a script from a selected source range. It is a preparation step: the draft must still pass the same citation gate, which checks its citations, not its narration. The model does not generate scenes during rendering.

What you can check

Both public scripts verify on v0.2.0. Checking them needs only the light install, which has no manim and no system libraries:

pip install -e ".[verify]"
explainer verify examples/evidence-budget.story.yaml

This command checks citations; it does not re-render the video. It does not establish that the explanation is semantically correct or educationally effective. After the gate, verify also checks that the code generator accepts the script; it reads files only, with no rendering, narration or network. The same command works for examples/citation-gate.story.yaml.

Rendering needs the full install, pip install -e ".[explainer]", plus the cairo/pango, ffmpeg and LaTeX packages listed in the repository’s README, and network access for narration. The desktop GUI installs separately with pip install ".[gui]".

explainer verify and explainer render exit with:

0: OK.
2: the script fails to load or validate, or the code generator rejects it.
3: the citation gate failed.
4: the render failed. Without manim installed, render stops at this point before writing anything and prints the install command.

The evidence-budget video was rendered from public commit c345e66; its script and the cited source there:

The planner’s budget allows two token slots per cited line, with a floor of five and a cap of twenty-four, and the planner drops citations with fewer than two tokens or no strong token. The citation gate itself does not apply that budget; it checks the declared evidence against the cited lines. This site states that the evidence-budget clip was rendered from c345e66 and the citation-gate clip from 9a59b3f; the pictures alone do not establish that provenance. Since then, source edits moved some cited lines, and the scripts on v0.2.0 cite the new line numbers with the same evidence, so cite labels in the videos can differ from the current scripts. Both scripts cite their own repository without pinning a commit, so their badges read verified without a commit.

About the earlier Harness-Field example

The Harness-Field video is actual engine output from the earlier local diagram-canvas snapshot. Its five forces come from a research wiki. The simplified label and verified @ commit badge identify the teaching view and the source line and commit cited for “memory force.” The citation gate passed before that render, but the historical result lacks public run evidence and is not independently checkable. Its storyboard is not public. The video shows the artifact and those markers; it cannot replace that run evidence.

Decisions and trade-offs

Animation can make a relationship easier to see, but it can also make a wrong explanation look more convincing. The checks here constrain citations; they do not replace judgment about the explanation itself.

Stop rendering when a citation does not check out. The gate checks for declared evidence in source, as whole words and on the first and last cited lines, so a range that has shifted usually fails instead of keeping its badge; when the script pins a commit, it also checks that the repository’s HEAD matches and rejects a dirty tree without explicit opt-in. Cost: Script authors must maintain resolvable citations and may need to revise them when source changes. Scripts that passed on v0.1.0 can fail on v0.2.0.

Keep provenance on the teaching view. The simplified label and verified badge show the gate's verdict, not a guarantee that the explanation is correct. Cost: Labels and citations take space away from the diagram and code.

Use a model to draft, fixed rules to generate code. The same script produces the same scene code through deterministic codegen; the actual video still depends on the render environment, fonts and narration resources. Cost: A new beat type requires engine changes, not just a new prompt; the planner cannot bypass the gate.

Share the render core with the desktop tool. The same Qt-free core also serves the batch-render GUI, which has its own install extra. Cost: Core changes must serve both consumers, without blocking the GUI for the convenience of the CLI.

Implementation note: sharing code is not the same decision as sharing a package

Where it stands

The source is public and the project is pre-release. The current tag is v0.2.0. Its citation gate is stricter than in the first public tag, v0.1.0 (tagged 2026-10-15, UTC), and the repository’s Changelog lists the changes. No teaching outcomes have been validated. Nothing is committed to a milestone. The open question remains which relationships benefit from animation, and how to make explanations easier to understand and citations easier to check.

Role: Personal project
Status: Public source, pre-release
Tag: v0.2.0
Key outcome: Three actual videos; citation checks do not establish semantic correctness or teaching effectiveness.
Stack: PythonManimCited codegen
Links: Source

Limits

Not an arbitrary-code-to-reliable-explanation tool: the input remains an explicit script.
Not video improvised by an LLM during rendering: the AI planner only provides optional script drafting.
The diagram canvas animates relationships, but learning benefits have not been validated.
On-screen code is a cited teaching view, not a verbatim source viewer.
Citation checks do not establish semantic correctness. The badge gives a verdict; to check a particular claim, readers still need source links and evidence.
The Harness-Field video’s storyboard is not public, so its historical verification result is not independently checkable.

← All work

Make code and technical concepts easier to see.