# 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`.

```bash
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.

```
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 |
|------|-------|---------|---------------|
| `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

```python
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.