Role

Personal project

Status

Private/local

Snapshot

local tag explainer-plan

Key outcome

Every on-screen claim is verified against the source repo at a pinned commit before a frame is drawn.

Stack

Python/Manim/Cited codegen

What it is

The Explainer Engine compiles 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. into a A programmatic animation library for mathematical and technical video. Scenes are code, not timeline edits — which is what lets a generator emit them deterministically. narrated scene. Each beat is a plot, a cited code callout, or an animated concept diagram: labeled nodes placed at named anchors, force edges, one path, and a node moving along it. The render path is one pass, with no model in it: storyboard → citation gate → deterministic codegen → Manim render with synthesized narration. An optional explainer plan step can draft that storyboard from a focused slice of real source — evidence-stamped from the files it read — but the draft still has to pass the same citation gate before a frame is drawn. It is a private, local tool; the snapshot it describes is named under Evidence below.

fig. 3.1 — the engine's own output, end to end (English narration; English and Chinese caption tracks). The amber tag marks the view simplified; the badge cites the source commit the "memory force" claim was verified against.

The problem

Explanations drift from the code they describe, and a rendered explanation drifts silently: the video still plays, the diagram still looks right, and nothing tells you the claim on screen stopped matching the source two refactors ago. A paraphrase is easy to get subtly wrong, and production polish makes it worse — a well-produced claim reads as more authoritative than an unchecked one has any right to. The question the engine is built around isn't how to render an explanation — it's what it takes for a rendered explanation to refuse to drift.

Constraints & key decisions

Refuse to draw a claim that can't be cited. Before render, a citation gate reads the cited lines from the source repo at a pinned commit and checks that the stated evidence is actually present; a commit-honesty check fails the build if the badge's commit does not match the repo's HEAD, or the tree is dirty without an explicit opt-in. Cost: authoring slows down — every claim needs a cite that resolves, and a storyboard that outruns its sources doesn't render at all.

Mark the teaching view; never pass it off as source. On-screen content is always marked simplified — a reshaped teaching view is never presented as verbatim code. The amber tag and the verified @ commit badge are not decoration; they are the gate's verdict, rendered into the frame. Cost: every frame carries permanent disclosure furniture — pixels spent on provenance instead of polish.

Deterministic codegen, no model in the render loop. The same storyboard always emits the same scene, so a render is reproducible and a diff in the output traces to a diff in the input. The diagram canvas turns relationships into motion without hand-built scene code, which is what lets a concept — not just a code listing — be explained and still be checkable. Cost: nothing the storyboard doesn't specify exists, and a new beat type is engine work, not prompt work. A planner can draft YAML; it cannot bypass the gate or invent a beat type the engine does not have.

One render core, two consumers. The engine sits on a shared, Qt-free render core — the same core a desktop batch-render GUI drives — so the rendering path is one tested surface rather than a one-off script. Cost: every core change has two consumers to keep working, and the engine can't take shortcuts that would wedge the GUI. The trigger that would change that split is written down in Sharing code is not the same decision as sharing a package.

Evidence

A private local snapshot at local tag explainer-plan — there is no public source to inspect. What backs the render claims is the artifact itself: the clip above is the engine's output, not a mock-up. It was rendered under the earlier diagram-canvas snapshot, through the same citation-gated pipeline this pin still describes. Its five forces are drawn from a research wiki; the on-screen badge cites the exact source line and commit the "memory force" claim was verified against, and the citation gate passed before the render ran. The disclosure markers — the simplified tag and the verified @ commit badge — are visible in every frame. The video itself can verify the rendered artifact and those visible markers. The cited private source line and the gate result are not independently checkable today. If the source is later published, the cited line could be checked externally; the historical gate result would still require public run evidence. This later snapshot adds the optional explainer plan authoring step; it does not change how a verified storyboard becomes a frame.

Next

Nothing is committed to a milestone. The open question the diagram canvas half-answers sets the direction: how much of a concept can be explained in motion while staying checkable against source. A public source link follows if and when the repository becomes reachable.

What it isn't

• Not an LLM video generator — a planner can draft the storyboard; codegen stays deterministic and reproducible.
• Not a slideshow — the diagram canvas animates relationships, not bullet points.
• Not a verbatim source viewer — on-screen code is a marked simplification, with the real lines cited.
• Not a warrant-transfer medium — the badge shows the gate's verdict, not the evidence; readers who need to check a claim need links, not narration.
• Private/local — not a public-source project today.

← All work