An Agentic "Toy Theatre" Animation System
Papeterie is a metadata-driven 2D animation engine that uses Gemini to translate natural language creative prompts into physics-based animation parameters. It specializes in the "Paper Theatre" aesthetic—layered 2D assets with procedural oscillatory motion and environmental physics.
The engine follows a strict Compiler-Renderer separation:
- The Compiler (
src/compiler):- Consumes
.pngsprites and.prompttext files. - Uses Gemini 2.5-Flash to generate structured
JSONmetadata. - Validates physics constraints via Pydantic.
- Consumes
- The Fixup Loop:
- Automatically repairs malformed or unrealistic LLM outputs using Gemini 3 Pro.
- The Renderer (
src/renderer):- Procedurally animates layers using MoviePy 2.0+ and NumPy sine-wave functions.
/agent_env: Git Submodule containing agent-specific workflows, model checks, and validation tier logic./src: Modular Python package (Compiler, Renderer, Validator)./tests: Pytest suite for behavioral validation.
Check out docs/HOWTO_Develop.md for installation, environment setup, and development workflows.
This project was developed with an AI coding agent as a collaborative partner. The following blog posts document key phases of the architecture effort:
| Date | Post | Focus |
|---|---|---|
| 2026-01-09 | Component Map Architecture | Frontend-backend communication, Theatre.js engine, state synchronization |
| 2026-01-09 | Integration Pattern: Gemini API | LLM validation-fixup loop, two-stage analysis, async patterns |
| 2026-01-09 | The AI Partnership | Agent-in-the-loop debugging, mindset shift from coder to thought partner |
| 2026-01-09 | QA System & Workflows | Tiered validation, agentic workflows, QA reasoning loops |
| 2026-01-23 | Release v0.0.2 & AI Lessons | Test density vs hallucinations, agent-human partnership, v0.0.2 milestone |
These posts serve as both:
- Developer onboarding: Understand the architecture and design decisions
- Process documentation: How AI-assisted development shaped the codebase
This project uses an AGENTS.md file to maintain persistent context for LLM collaborators. When working with Gemini, ensure Agent Mode is active to allow full-repository awareness. See the "AI Agent Initialization" section in HOWTO_Develop.md for details.