Manim Project · Animation Agent Workbench

What it solves

A scientific animation cannot treat “ask a model to write Manim Python” as the source of scientific correctness: trajectories, fields, residuals, and data points need traceable computation, while visual expression needs a verifiable intermediate representation. Animation Agent V2 turns a one-sentence research goal and optional CSV into IntentSpec, calls allowlisted scientific tools to produce ToolRuns, builds AnimationIR 2.0, and uses deterministic compilation to produce a reviewable Preview. The original Teaching Prompt → ContentPlan → CodeVersion path remains available, and both paths share versioning, queues, sandboxes, and delivery.

Core capabilities

• Create an animation task from one research sentence and optional CSV
• Constrain model output to structured IntentSpec JSON
• Produce traceable ToolRuns through allowlisted scientific tools
• Compile AnimationIR 2.0 into Manim and Web JSON
• Run an expression critic and at most one IR repair
• Draft 2–8 scenes with Director, generate each, and compose a full video

How it works

1. Enter a research goal and optional assets
2. Resolve intent and run scientific tools
3. Build and inspect AnimationIR
4. Compile and render a Preview

The user enters a research goal in a local workbench that issues its own development session and optionally supplies CSV data. The system presents inferred domain, assumptions, and tools_needed for review. An unmatched closed catalog returns needs_confirmation; missing required data returns asset_required, so it neither invents equations nor fabricates data. Ready ToolRun outputs enter AnimationIR, the critic, and the compiler before the existing Runner renders a Preview inside the network-disabled Docker boundary.

In the closed P0 acceptance set, all six renderable vertical slices passed scientific assertions, deterministic compilation, and first Docker render; the paper-plus-CSV case outside the closed catalog paused for confirmation as intended. These are internal acceptance outcomes, not a general generation success rate.

The new workflow organizes a GlobalBrief into 2–8 independently versioned SceneBlocks. Director can draft scenes from a complete video goal; generation starts after the user applies that draft. Director does not emit Python, run scientific tools, or create render jobs in advance. Each scene selects a teaching or scientific path, can bind CSV data, and contributes to an ordered hard-cut MP4.

Project highlights

Let the model plan intent instead of writing free-form Scenes

On the research path, an enabled model can only fill IntentSpec JSON; it cannot emit Scene Python, lambdas, or arbitrary NumPy expressions. Without a model configuration, the same entry point falls back to a transparent keyword intent catalog. A deterministic compiler lowers constrained IR to Manim code, while unknown capabilities return structured errors and explicit fallbacks. Teaching is now constrained too: the model fills ContentPlan, then formula and function scenes pass through SceneStoryboard and deterministic compilation into CodeVersion. Unsupported expressions or geometry/3D requests without a storyboard fail explicitly rather than producing a text-only substitute video.

Keep scientific values and provenance inside ToolRun

Trajectories, fields, and time series come from registered NumPy/SciPy/pandas tools instead of ad hoc computation inside a Scene. ToolRun records parameter, input, and output hashes; AssetVersion preserves immutable asset provenance, and AnimationIR refers to artifact_ref. Paper-plus-CSV reproduction currently accepts only a closed Lotka–Volterra catalog with complete coefficients; other papers move to needs_confirmation.

The 76-case internal P1 gold set contains 58 ready cases. Expected, science, and provenance rates were 1.0, the expression-critic mean was 5.0, and mean IR repairs were 0. These figures describe closed-corpus gates, not external research findings.

Use one IR for two backends and a repair loop

AnimationIR 2.0 passes structural validation and a TIFA-style expression critic before at most one IR-level repair. The same IR lowers deterministically to Manim Python and Web JSON, so a second preview surface does not reinterpret the scientific goal. Manim output enters the existing network-disabled Render Sandbox; the Web backend is an inspectable JSON lowering, not a second video renderer.

In the 130-case internal P2 benchmark, 100 cases were ready; science, expected, and cross-backend rates were 1.0, and the unexpected FAILED rate was 0. The protocol explicitly records external_user_study=false.

Workflows reuse versioned scene clips above these generation paths: editing one scene regenerates that scene, while reordering only recomposes. Cache reuse rechecks ownership, hash, size, and decodability. Missing assets or render failures preserve successful clips but prevent delivery of an incomplete full video. Repository evidence covers real Docker composition and a production-build browser workflow. Repeatable black-box rendering uses deterministic teaching fixtures and does not establish quality for arbitrary model prompts.

System architecture

The Next.js workbench sends a research prompt through Intent Resolver and an allowlisted Compute Sandbox. ToolRuns and provenance hashes enter AnimationIR, the critic, and at most one repair before the deterministic compiler dispatches to Manim and Web JSON backends. Teaching ContentPlan / CodeVersion passes a separate security preflight and joins the same Runner. Only the Manim backend enters the network-disabled, non-root, resource-limited Render Sandbox; Preview / Final and QualityReport return to the shared workbench.

The diagram shows the single-scene generation core. The new orchestration layer is Director → user applies draft → GlobalBrief / SceneBlock → scene generation → Compose / Export. It reuses the existing generation and sandbox boundaries.

Project scope

This remains a local development and acceptance workbench: the research path covers a closed intent/tool catalog, while the teaching ContentPlan path remains available. P0/P1/P2 figures come from internal gold sets and a lab harness, not an external researcher study or production-deployment claim. Multi-scene composition supports linear ordering and hard cuts only, with no free-form DAGs, transitions, audio, or subtitles. Overlapping formulas remain a recorded visual issue in some teaching scenes.