video-promo/AGENTS.md

AGENTS.md — AstrAI Promo

Project

Manim-driven technical animation project for AstrAI promo videos (1B param, zh/en bilingual LLM).
Python 3.12, Manim (renders MP4 output).

Setup

Requires a conda environment named manim.

conda run -n manim python -m pip install manim

The user verbally referred to it as "animin" — the actual name is manim. No system Python is available; always use conda run -n manim.

Commands

Action	Command
Render all (parallel)	conda run -n manim python render_all.py
Render all (draft 480p)	conda run -n manim python render_all.py -ql
Render all (4K)	conda run -n manim python render_all.py -4k
Single scene (1080p)	conda run -n manim python -m manim <file.py> <SceneClass> -qh
Single scene (draft)	conda run -n manim python -m manim <file.py> <SceneClass> -ql

Output goes to output/videos/.

File layout (flat — no subdirectory)

Files are at the repo root, not under promo/ despite what README.md and PROMO_GUIDE.md reference in some spots.

hook.py                 # Scene: Hook
architecture.py          # Scene: Architecture
continuous_batching.py  # Scene: ContinuousBatching
cta.py                  # Scene: CTA
paged_cache.py          # Scene: PrefixCache
transformer.py          # Scene: Transformer
render_all.py           # Parallel batch renderer
PROMO_GUIDE.md          # Full production guide (storyboard, narration, recording)
README.md               # Quick-start docs (may reference stale promo/ paths)

Scenes

File	Class	Content	Est. duration
hook.py	Hook	Terminal demo + GPU comparison + logo reveal	~18s
transformer.py	Transformer	GQA attention (Q/K/V → RoPE → Attention → O) + spec card	~35s
continuous_batching.py	ContinuousBatching	4-stage pipeline + throughput comparison (1.0x vs 3.4x)	~30s
paged_cache.py	PrefixCache	Paged KV cache: page table, on-demand growth, O(1) free	~30s
architecture.py	Architecture	Full-stack: HTTP API → Engine → Paged Cache → Transformer	~25s
cta.py	CTA	End card: "AstrAI — Single GPU, Open Source, 1B params"	~3s

Render quirks

• render_all.py runs all 5 scenes in parallel via ThreadPoolExecutor. Script blocks until all finish. No -qh flag in render_all.py means check the default at the top of the file.
• The output/ directory must exist (script creates it via Manim's --media_dir).

Chinese text in Manim

Text.set_default(font="Microsoft YaHei")

This must be set before creating any Text objects, otherwise CJK characters render as boxes.

No tests / lint / typecheck

This is a render-only project. No pytest, ruff, mypy, or similar config exists.

.gitignore oddity (from parent AstrAI project)

The repo uses deny-by-default .gitignore (* then !*.py, !*.sh, etc.).
New file types at root need an explicit ! entry — check .gitignore before adding assets.