Problem
A student stuck on a concept (gravity, derivatives, pH, bubble sort) only finds text or videos that don’t answer their exact question. Generating an animation on demand with a language model is possible, but what the model writes is rarely reliable: code that runs can still draw a wrong or confusing figure, and waiting several minutes for a video loses the student. Two constraints guided the project: the demo must not be able to fail, and a wrong explanation is worse than none.
Solution
The model writes a JSON document (plan, parameters, calculation model, scenes) validated by a Zod schema, which the repository’s own primitives interpret in a Remotion player. A judge model reviews the plan, then every scene goes through six deterministic rules and a conformity check: a scene that doesn’t pass is fixed or dropped, never shown. Scenes are streamed, the first one playing while the next are prepared, and a degraded mode offers 24 reference explanations with no network or database.
My role
- Product, design, full-stack development and deployment, solo, from 12 to 24 October 2026 (153 commits)
- Generation pipeline: schema-constrained model output, plan reviewed by a judge, six validation rules per scene, four model roles that can each target a different provider
- Expression interpreter written for the project (no eval), so sliders recalculate the figure and the result on every frame, within a 16 ms frame budget checked by a script
- Isolated execution of the generated Manim code: no-network container, read-only root, no Linux capabilities, 150 s cut-off, static analysis only as a pre-filter
- Synthesised voice with fallback between Azure Speech, Kokoro and Pocket TTS; with no voice reachable, the explanation plays with subtitles only
- “Planche” design system (Paper and Board themes), accessibility, French and English from day one
- Spec Kit method: an eight-principle constitution, a specification, a plan, 98 tasks and contracts; built with Claude Code and coding agents delegated per task
Impact
- First token in 0.7 to 1.0 s (deepseek-flash without reasoning); first scene without voice in under 15 s across four concepts, with a real provider
- An explanation already generated (same concept, level and language) is served from cache in about 1 s
- Judge role tuned after measurement: over 20 s with reasoning, 2 s without, so reasoning is switched off for that role
- A 30 s Manim scene rendered in 20 s (2 CPU, 2 GB); an outbound connection and a write outside the exchange volume do fail
- ≈ 85,000 lines of TypeScript, 118 test files, 10 Playwright journeys, 50 Python files; 91 of 98 tasks done
- Limits: the 24 reference explanations were produced with the model and have not yet been reviewed by a person; no test with students has taken place, so there is no real user feedback to quote
- Limits: the 40-question benchmark has not yet been run on the deployed version, and the Manim sandbox isolation is verified locally, not yet under Dokploy
Key features
- Free-form question: a sentence to complete, the level (middle school, high school, higher education), the language (French, English) and the theme (Paper or Board); the first scene plays while the next ones are prepared
- Sliders on the concept’s quantities (masses, distance, voltage…): the figure, the values and the highlighted result are recalculated on every frame
- “I still don’t get it”: another analogy, a simpler version, a zoom on one step or a free follow-up question, with the session’s versions listed
- A short quiz: a wrong answer sends the student back to the scene to review
- Colophon “How this explanation was built”: teaching plan, chosen analogy and verification verdict for each scene
- Voice synced to the real duration of the audio files, subtitles, keyboard shortcuts and reduced motion respected
- Public share link and MP4 export prepared in the background; deeper Manim version rendered in an isolated container
- 24 reference explanations (12 concepts × 2 languages, six subjects) playable with no network or database, and a health endpoint exposing the state of each service
