hao-ai-lab-FastVideo/fastvideo/AGENTS.md

fastvideo/ — Core Package

Generated: 2026-05-02

Inference + training framework for video DiTs. Public API entry: from fastvideo import VideoGenerator, PipelineConfig, SamplingParam.

Public Surface (__init__.py)

VideoGenerator   # entrypoints/video_generator.py — high-level inference handle
PipelineConfig   # configs/pipelines/base.py — pipeline wiring dataclass
SamplingParam    # api/sampling_param.py — runtime sampling knobs

CLI entry: fastvideo script → entrypoints/cli/main.py (subcommands: generate, serve, bench).

Layout

fastvideo/
├── api/             # Schema + presets for the OpenAI-compatible serving layer
├── attention/       # Backends + selector (FlashAttn / SageAttn / SDPA / VSA / VMoBA / SLA)
├── configs/         # Per-model arch configs + per-pipeline configs (registry-driven)
├── dataset/         # Dataloaders (pre-commit excluded — minimal lint surface)
├── distributed/     # SP/TP groups, device communicators, init helpers
├── entrypoints/     # cli/, openai/, streaming/, video_generator.py
├── hooks/           # Runtime hook system for pipelines
├── layers/          # Tensor-parallel linears + attention wrappers (port targets)
├── models/          # DiT / VAE / encoder / scheduler / loader (pre-commit excluded)
├── pipelines/       # basic/<model>/, preprocess/, stages/, training/
├── platforms/       # CUDA/ROCm capability + AttentionBackendEnum
├── third_party/     # Vendored externals (lint excluded; do not reformat)
├── train/           # NEW modular trainer — methods × models × callbacks
├── training/        # LEGACY monolithic *_training/distillation_pipeline.py
├── worker/          # Multi-process / Ray executors
├── workflow/        # Preprocessing workflow base class
├── registry.py      # Pipeline-config + model-class lookup (canonical)
├── envs.py          # Env-var declarations
├── fastvideo_args.py# Runtime arg dataclass passed through pipelines
└── utils.py         # FlexibleArgumentParser, qualname resolver, etc.

Where to Look

Task	Location
Add a new pipeline class	pipelines/basic/<model>/ + configs/pipelines/<model>.py + register in registry.py
Add a new model component	models/<role>/<model>.py + configs/models/<role>/<model>.py
Wire an existing model into a new pipeline	pipelines/basic/<model>/presets.py + reuse stages from pipelines/stages/
Add a converter	scripts/checkpoint_conversion/<model>_to_*.py (separate dir, separate AGENTS.md)
Add an attention backend	attention/backends/<name>.py + register in selector
Add a runtime CLI flag	fastvideo_args.py (avoid argparse ad-hoc inside stages)

Conventions Specific Here

• PipelineStage subclasses (pipelines/stages/) own one verb each (encode, schedule, denoise, decode). Compose, don't fork.
• Every pipeline reads from a PipelineConfig subclass and a SamplingParam. Never read raw env vars inside a stage — go through fastvideo.envs.
• Logger setup: from fastvideo.logger import init_logger; logger = init_logger(__name__). Do not call logging.getLogger directly.
• Imports between train/ and training/ are forbidden — they are independent stacks.

Pre-Commit Exclusions (do not assume linted)

These dirs are listed in .pre-commit-config.yaml exclude:

• fastvideo/third_party/, fastvideo/dataset/, fastvideo/models/

Editing files there will NOT trigger yapf/ruff/mypy/codespell. Format manually if a sibling file shows clear style; do not introduce new violations.