update

docs(seed-ssim-skill): fix modal volume get path + force flag
Post-first-run corrections to the seed-ssim-references skill: - modal volume get needs --force when the local parent directory already exists, otherwise it errors with [Errno 21] Is a directory. - The downloaded tree has an extra generated_videos/ level (from the volume layout in _sync_generated_videos_to_volume), so copy-local's --generated-dir must include it.
2026-04-21 10:26:57 -07:00 · 2026-04-21 10:22:36 -07:00 · 2026-04-21 10:06:07 -07:00 · 2026-04-21 09:58:19 -07:00 · 2026-04-21 09:44:00 -07:00 · 2026-04-21 08:32:19 -07:00
288 changed files with 1015 additions and 28422 deletions
@@ -119,7 +119,7 @@ FastVideo-WorldModel/
 ## Build & Test Commands

 ```bash
-uv pip install -e ".[dev]"                        # Editable install
+uv pip install -e .[dev]                          # Editable install
 pre-commit run --all-files                        # Lint/format/spell
 pytest tests/                                     # Top-level tests
 pytest fastvideo/tests/ -v                        # Package tests
@@ -6,5 +6,3 @@
 {"name": "index-related-work", "description": "Ingest a paper or repository into the related work index", "path": "index-related-work/SKILL.md", "status": "draft", "trust": "low"}
 {"name": "search-related-work", "description": "Query the related work index for relevant papers, repos, or comparisons", "path": "search-related-work/SKILL.md", "status": "draft", "trust": "low"}
 {"name": "seed-ssim-references", "description": "Run a new or updated fastvideo/tests/ssim/ test on Modal, pull generated videos, and upload them to FastVideo/ssim-reference-videos so the test has a regression baseline", "path": "seed-ssim-references/SKILL.md", "status": "draft", "trust": "low"}
-{"name": "reseed-ssim-references", "description": "Re-seed (overwrite) HF reference videos for an existing fastvideo/tests/ssim/ test and a single model id on Modal L40S. Always backs up current refs first, regenerates on Modal, pauses for the user to eyeball before-vs-after, then uploads with --force scoped to --model-id. Sister skill to seed-ssim-references; use when intentional code change has invalidated existing refs", "path": "reseed-ssim-references/SKILL.md", "status": "draft", "trust": "low"}
-{"name": "add-model", "description": "Add a new model (or variant) to FastVideo: DiT + configs + pipeline + presets + registry + tests. Walks through FastVideo's single stage-based pipeline architecture with exact file paths and registration hooks.", "path": "add-model/SKILL.md", "status": "draft", "trust": "low"}
@@ -12,7 +12,7 @@ automates the boilerplate of setting environment variables, picking the right
 entrypoint, and applying defaults from the closest example script.

 ## Prerequisites
- The repo is cloned and `fastvideo` is installed (`uv pip install -e ".[dev]"`).
+- The repo is cloned and `fastvideo` is installed (`uv pip install -e .[dev]`).
 - Dataset is preprocessed (see `docs/training/data_preprocess.md`).
 - `WANDB_API_KEY` is set in the environment (or `WANDB_MODE=offline` for local).
 - GPU resources are available (multi-GPU requires NCCL).
@@ -1,343 +0,0 @@
---
-name: reseed-ssim-references
-description: Re-seed HF reference videos for a single existing SSIM test on Modal L40S. Always backs up current refs locally first, regenerates on Modal, pauses for the user to eyeball before-vs-after quality, then overwrites the targeted `<model_id>` subtree on `FastVideo/ssim-reference-videos` with `--force`. Use when an intentional code change (model port fix, attention backend swap, kernel upgrade, hyperparameter change) has invalidated existing refs and they need to be regenerated. Pairs with `seed-ssim-references`, which is for first-time seeding only.
---
-
-# Re-seed SSIM Reference Videos
-
-## Purpose
-
-Replace the existing SSIM reference videos for a single `(test_file, model_id)`
-pair on the HF dataset (`FastVideo/ssim-reference-videos`). This is **destructive**
-on HF — the old refs are overwritten — so the skill always:
-
-1. Confirms intent with a one-liner the user has to type.
-2. Downloads the existing refs as a local, timestamped backup.
-3. Regenerates on Modal L40S (same code path that CI uses).
-4. Pauses for a side-by-side eyeball of backup vs new mp4s.
-5. Uploads with `--force`, scoped to the single `--model-id`.
-6. Reminds the user to keep the backup until the PR lands.
-
-Pairs with `seed-ssim-references`, which is the inverse (first-time seeding
-only, refuses to overwrite). Re-seeding is intentionally a separate, more
-ceremonial operation because mistakenly clobbering production refs is much
-harder to recover from than failing closed.
-
-## When to use
-
- An intentional code change (model port fix, kernel upgrade, attention
-  backend swap, hyperparameter change in the test itself) has shifted the
-  expected SSIM output and the existing refs no longer represent the new
-  ground truth.
- A test is failing in CI **for the right reason** (the new code is correct,
-  the old refs are stale).
-
-## When not to use
-
- A test is failing for the **wrong** reason (the port is buggy, not the
-  refs). Fix the port; re-seeding hides the bug.
- A brand-new test that has no refs on HF yet. Use `seed-ssim-references`.
- "Just to clean up drift" without a concrete code change to point at. The
-  PR description has to justify *why* refs changed; without a concrete
-  change, there's nothing to write.
-
-## Inputs
-
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `test_file` | Yes | Path to the SSIM test, e.g. `fastvideo/tests/ssim/test_matrixgame_similarity.py`. Validated against `fastvideo/tests/ssim/test_*_similarity.py`. |
-| `model_id` | Yes | Single model id from the test's `*_MODEL_TO_PARAMS`, e.g. `Matrix-Game-2.0-Diffusers-Base`. Re-seed runs are **per model**. For multi-model tests, invoke the skill once per model. |
-| `intent_rationale` | Yes | One-line explanation of *why* refs are being regenerated (e.g. "Relax FA-2 head_size whitelist to include 80 — matrix_game now uses FLASH_ATTN instead of TORCH_SDPA"). Recorded in the backup directory and reused in the PR description. |
-
-Hardcoded:
-
- Modal GPU: **L40S** (matches CI; re-seeding from another SKU produces refs
-  that L40S CI cannot match).
- Quality tier: **`default`**. `full_quality` is a separate, deliberate
-  operation.
- HF repo: `FastVideo/ssim-reference-videos` (override via
-  `FASTVIDEO_SSIM_REFERENCE_HF_REPO`).
- Device folder: `L40S_reference_videos`.
-
-## Prerequisites
-
-The user has confirmed:
-
- `modal` CLI authenticated.
- `hf` CLI authenticated, **and** `HF_API_KEY` (or `HUGGINGFACE_HUB_TOKEN` /
-  `HF_TOKEN`) exported with **write** access to
-  `FastVideo/ssim-reference-videos`.
- The current branch's code is the change that motivated the re-seed (i.e.
-  `git rev-parse HEAD` is the commit that intentionally invalidated refs).
-
-Fail fast if any of these are missing.
-
-## Steps
-
-### 1. Validate inputs and confirm intent
-
- Verify `test_file` exists and matches `fastvideo/tests/ssim/test_*_similarity.py`.
- Grep the file for `*_MODEL_TO_PARAMS` and assert `model_id` is one of its
-  keys. If the file has only a single hardcoded model, accept that model id
-  as the only valid value.
- Print the rationale and ask the user to type **`confirm reseed`** (not just
-  `y` — make it deliberate):
-
-  > About to RE-SEED references for model `<model_id>` from test `<test_file>`.
-  > This will OVERWRITE existing refs on
-  > `FastVideo/ssim-reference-videos/reference_videos/default/L40S_reference_videos/<model_id>/`
-  > after backup + Modal regen + eyeball.
-  >
-  > Reason: `<intent_rationale>`
-  > HEAD: `<git rev-parse --short=12 HEAD>`
-  >
-  > Reply `confirm reseed` to proceed, anything else to abort.
-
-  Stop until the user types exactly `confirm reseed`. Anything else aborts
-  with no side effects.
-
-### 2. Back up existing refs
-
-Always required. The backup is the only graceful path back if anything goes
-wrong later.
-
-```bash
-SHORT_COMMIT=$(git rev-parse --short=12 HEAD)
-TIMESTAMP=$(date -u +%Y%m%d_%H%M%S)
-MODEL_SAFE=$(echo "<model_id>" | tr '/' '_')
-BACKUP_DIR="ssim_reseed_backup/${TIMESTAMP}_${SHORT_COMMIT}_${MODEL_SAFE}"
-mkdir -p "$BACKUP_DIR"
-
-hf download \
-    --repo-type dataset FastVideo/ssim-reference-videos \
-    --include "reference_videos/default/L40S_reference_videos/<model_id>/**" \
-    --local-dir "$BACKUP_DIR"
-
-mp4_count=$(find "$BACKUP_DIR" -name "*.mp4" | wc -l)
-echo "Backup mp4 count: $mp4_count"
-[ "$mp4_count" -gt 0 ] || {
-    echo "ERROR: backup is empty for <model_id>. Either the model id is wrong"
-    echo "or there are no existing refs (use seed-ssim-references instead)."
-    exit 1
-}
-
-# Provenance — used in the PR description
-cat > "$BACKUP_DIR/PROVENANCE.txt" <<EOF
-test_file: <test_file>
-model_id: <model_id>
-head_commit: $(git rev-parse HEAD)
-timestamp_utc: $(date -u +%FT%TZ)
-reason: <intent_rationale>
-EOF
-```
-
-If the `hf download` produces zero mp4s, abort — the user has either picked a
-non-existent `model_id` or there are no refs yet (in which case
-`seed-ssim-references` is the right tool).
-
-### 3. Regenerate on Modal L40S
-
-Mirror CI's exact env recipe so the regenerated refs are byte-comparable to
-what CI will produce on the same commit. Two differences from CI:
-
-1. **Pass the same env prefix CI uses** (`IMAGE_VERSION`, `BUILDKITE_*`) — see
-   `.buildkite/pipeline.yml:1-3` and `.buildkite/scripts/pr_test.sh:62-83`.
-   Without this, `ssim_test.py:17-18` resolves a different GHCR image tag
-   (default is `latest`, CI is `py3.12-latest`), and `ssim_test.py:38-46`
-   bakes different values into the image's frozen env block. **Mismatched
-   image or env is the most common source of SSIM drift between reseed and
-   CI runs.**
-2. **Do not pass `--skip-reference-download`**. Letting the test fetch the
-   existing refs and run the full SSIM compare gives "before" SSIM numbers
-   for the PR description, and the test still produces the new mp4s
-   regardless of whether the comparison passes or fails.
-
-```bash
-SUBDIR="${TIMESTAMP}_${SHORT_COMMIT}"
-
-IMAGE_VERSION="py3.12-latest" \
-BUILDKITE_REPO="$(git config --get remote.origin.url)" \
-BUILDKITE_COMMIT="$(git rev-parse HEAD)" \
-BUILDKITE_PULL_REQUEST="${BUILDKITE_PULL_REQUEST:-false}" \
-modal run fastvideo/tests/modal/ssim_test.py \
-    --git-repo="$(git config --get remote.origin.url)" \
-    --git-commit="$(git rev-parse HEAD)" \
-    --hf-api-key="$HF_API_KEY" \
-    --test-files="<test_file>" \
-    --sync-generated-to-volume \
-    --generated-volume-subdir="$SUBDIR" \
-    --no-fail-fast
-```
-
-Capture the printed `modal volume get ...` hint — its `<SUBDIR>` matches
-`$SUBDIR` and is needed for step 4. Capture the SSIM numbers from the test
-output (or from the JSON next to the generated mp4) for the PR description.
-
-### 4. Download generated videos
-
-```bash
-modal volume get --force hf-model-weights \
-    ssim_generated_videos/default/"$SUBDIR"/generated_videos \
-    ./generated_videos_modal/default
-```
-
-After this, the new mp4s live at:
-
-```
-./generated_videos_modal/default/generated_videos/L40S_reference_videos/<model_id>/<backend>/<prompt>.mp4
-```
-
-`--force` is required when `./generated_videos_modal/default` already exists
-from a prior run; safe on the first run too.
-
-### 5. PAUSE — user reviews quality side-by-side
-
-Print the diff and the comparison:
-
-```bash
-echo "=== File list diff (backup vs new) ==="
-diff -u \
-    <(find "$BACKUP_DIR/reference_videos/default/L40S_reference_videos/<model_id>" -name "*.mp4" \
-        | sed "s|$BACKUP_DIR/reference_videos/default/L40S_reference_videos/||" | sort) \
-    <(find ./generated_videos_modal/default/generated_videos/L40S_reference_videos/<model_id> -name "*.mp4" \
-        | sed "s|./generated_videos_modal/default/generated_videos/L40S_reference_videos/||" | sort) \
-    || true
-
-echo
-echo "=== SSIM numbers from this run (paste into PR) ==="
-find ./generated_videos_modal/default/generated_videos/L40S_reference_videos/<model_id> -name "*_ssim.json" -exec cat {} \;
-```
-
-Then stop and tell the user:
-
-> Old refs backed up to `$BACKUP_DIR`.
-> New videos in `./generated_videos_modal/default/generated_videos/L40S_reference_videos/<model_id>/`.
->
-> Open both in a video player. Confirm the new videos:
->   1. Look correct (no obvious artifacts, no black/static frames).
->   2. Are *intentionally* different from the backup in the way described
->      in `<intent_rationale>` (e.g. slight numerical drift only, not a
->      different scene / different motion / corrupted output).
->
-> Reply **`upload`** to overwrite HF, anything else to abort.
-> Aborting leaves the backup and new videos on disk for inspection — nothing
-> on HF changes.
-
-Do not proceed until the user types exactly `upload`. If they abort, leave
-everything on disk and stop here.
-
-### 6. Copy into the local reference layout
-
-Same as `seed-ssim-references` step 5:
-
-```bash
-python fastvideo/tests/ssim/reference_videos_cli.py copy-local \
-    --quality-tier default \
-    --device-folder L40S_reference_videos \
-    --generated-dir ./generated_videos_modal/default/generated_videos/L40S_reference_videos
-```
-
-Result: `fastvideo/tests/ssim/reference_videos/default/L40S_reference_videos/<model_id>/<backend>/<prompt>.mp4`.
-
-### 7. Upload with `--force`, scoped to `--model-id`
-
-The `--force` flag is what makes this skill different from `seed-ssim-references`.
-Always pair it with `--model-id` so a typo cannot accidentally overwrite a
-neighboring model's refs.
-
-```bash
-python fastvideo/tests/ssim/reference_videos_cli.py upload \
-    --quality-tier default \
-    --device-folder L40S_reference_videos \
-    --model-id "<model_id>" \
-    --force
-```
-
-The CLI's overwrite guard refuses without `--force`; with `--force` it
-overwrites only files under
-`reference_videos/default/L40S_reference_videos/<model_id>/`.
-
-### 8. Report success and retention guidance
-
-Print:
-
- The HF path that was overwritten (`<repo>/reference_videos/default/L40S_reference_videos/<model_id>/`).
- The local backup directory path.
- The new SSIM numbers from step 5.
- This restore command, in case the PR review surfaces a problem after
-  upload:
-
-  ```bash
-  python fastvideo/tests/ssim/reference_videos_cli.py upload \
-      --quality-tier default \
-      --device-folder L40S_reference_videos \
-      --model-id "<model_id>" \
-      --reference-dir "$BACKUP_DIR/reference_videos/default/L40S_reference_videos" \
-      --force
-  ```
-
- This PR-description checklist (see `fastvideo/tests/ssim/AGENTS.md` →
-  *Updating Reference Videos*):
-  1. Source commit that produced the new refs (HEAD at re-seed time).
-  2. Test command and GPU SKU (`L40S`).
-  3. Before/after SSIM numbers.
-  4. The `<intent_rationale>` from step 1.
-  5. A note that the backup lives at `$BACKUP_DIR` and should be retained
-     until CI on the PR is green.
-
-Do **not** auto-rerun the SSIM test — the user does that as part of the PR.
-
-## Failure modes and how to handle them
-
- **`HF_API_KEY` unset.** Stop before step 2.
- **Backup is empty (zero mp4s).** Stop before step 3 — the model id is
-  wrong or the refs don't exist yet (use `seed-ssim-references`).
- **Modal run fails before generation.** No mp4s on the volume. Don't
-  upload. Investigate the failure (test crash, OOM, partition exhaustion),
-  fix, then retry from step 3. Backup is still intact.
- **Quality regressed (visual or metric).** User aborts at step 5. Backup
-  retained. New videos retained on disk for inspection. Nothing on HF
-  changed. Either fix the underlying code change or abandon the re-seed.
- **User confirmed `upload` but later realized the new refs are wrong.**
-  Run the restore command from step 8 with the backup `--reference-dir`.
-  This is exactly why the backup exists.
- **Multi-model test, only one model is being re-seeded.** Run the skill
-  once per model id. The `--model-id` scope on upload guarantees the others
-  are untouched.
-
-## Design notes (for future skill maintainers)
-
- Per-`model_id` scope is mandatory. The dataset houses many model subtrees;
-  re-seeding the wrong one is hard to undo without backup.
- `default` tier only; `full_quality` is a separate, deliberate operation
-  with different params and ~doubled runtime, and isn't what CI gates on.
- The skill deliberately does **not** pass `--skip-reference-download` to
-  Modal so we get pre-reseed SSIM numbers for the PR. The `seed`-skill
-  passes it because no refs exist yet; for re-seed, refs do exist and
-  exposing the comparison is informative.
- The two-token confirm (`confirm reseed`, then `upload`) is intentional.
-  Re-seeding is high-blast-radius and should not be one-keystroke.
- The backup directory is plain mp4s + `PROVENANCE.txt`. No HF metadata is
-  preserved; the restore path uses `reference_videos_cli.py upload
-  --reference-dir` which doesn't need it.
-
-## References
-
- `.agents/skills/seed-ssim-references/SKILL.md` — the first-time seed
-  skill this one parallels. Read it for the Modal flag rationale shared
-  between the two flows.
- `fastvideo/tests/ssim/AGENTS.md` — directory rules, including the PR
-  expectations for any reference-video change (rationale, before/after
-  SSIM, source commit/model/backend).
- `fastvideo/tests/ssim/reference_videos_cli.py` — `copy-local`, `upload`
-  (with `--model-id`, `--force`), `download`. The overwrite guard at
-  `upload_reference_videos` is the safety net this skill leans on.
- `fastvideo/tests/modal/ssim_test.py` — Modal orchestrator;
-  `--sync-generated-to-volume`, `--generated-volume-subdir`,
-  `--skip-reference-download`, `--no-fail-fast`.
-
-## Changelog
-
-| Date | Change |
-|------|--------|
-| 2026-05-02 | Initial version. Sister skill to `seed-ssim-references`, scoped to single `(test_file, model_id)` re-seeds, with mandatory backup and two-token confirm. |
@@ -1,41 +1,26 @@
 ---
 name: seed-ssim-references
-description: Seed HF reference artefacts for a single newly-added SSIM test (pixel `.mp4` for `run_text_to_video_similarity_test`-style tests, or latent `.pt` for `run_text_to_latent_similarity_test`-style tests). Runs the test on Modal L40S, downloads the generated artefacts via `modal volume get`, pauses for the user to verify (visual eyeball for mp4, numerics dump for pt), then uploads only that test's files to `FastVideo/ssim-reference-videos`. Use when a new `fastvideo/tests/ssim/test_*_similarity.py` has just been added and has no references on HF yet.
+description: Seed HF reference videos for a single newly-added SSIM test. Runs the test on Modal L40S, downloads the generated mp4s via `modal volume get`, pauses for the user to eyeball quality, then uploads only that test's files to `FastVideo/ssim-reference-videos`. Use when a new `fastvideo/tests/ssim/test_*_similarity.py` has just been added and has no references on HF yet.
 ---

-# Seed SSIM Reference Artefacts (mp4 or pt)
+# Seed SSIM Reference Videos

 ## Purpose

 A brand-new SSIM test in `fastvideo/tests/ssim/` fails forever until its
-reference artefacts exist on the HF dataset
-(`FastVideo/ssim-reference-videos`). The dataset hosts two kinds of artefacts
-side-by-side per `(model_id, backend, prompt)`:
-
- **`.mp4`** — pixel ground-truth for tests that call
-  `run_text_to_video_similarity_test` / `run_image_to_video_similarity_test`
-  in `inference_similarity_utils.py`. Compared via SSIM.
- **`.pt`** — pre-VAE latent bundle (fp16 full latent + fp32 slice +
-  metadata + `slice_spec` + `format_version`) for tests that call
-  `run_text_to_latent_similarity_test` in `latent_similarity_utils.py`.
-  Compared via cosine distance on the slice and the full tensor.
-
+reference videos exist on the HF dataset (`FastVideo/ssim-reference-videos`).
 This skill:

-1. Detects which artefact type the test produces (pixel vs latent).
-2. Runs the test on Modal's L40S pool to generate the artefacts.
-3. Downloads them to the local repo via `modal volume get`.
-4. Pauses so the user can verify quality:
-   - **mp4**: visual eyeball in a video player.
-   - **pt**: numerics dump (shape, slice stats, NaN/Inf check, metadata).
-5. Uploads only the new test's files to HF, with a guard that refuses to
+1. Runs the test on Modal's L40S pool to generate the videos.
+2. Downloads them to the local repo via `modal volume get`.
+3. Pauses so the user can eyeball the mp4s and confirm quality.
+4. Uploads only the new test's files to HF, with a guard that refuses to
   overwrite anything already present.

 The skill is run **manually**, once per new test. Before invoking it, the user
 has already sanity-tested the new test locally — it launches `VideoGenerator`
-and writes an artefact without crashing (the missing-reference assertion at
-the end is expected). The skill does not re-test locally; it goes straight
-to Modal L40S (which is what CI uses).
+and writes an mp4 without crashing. The skill does not re-test locally; it
+goes straight to Modal L40S (which is what CI uses).

 ## When to use

@@ -84,7 +69,7 @@ Fail fast if the token env var is missing.

 ## Steps

-### 1. Ask for the test file, then detect artefact type
+### 1. Ask for the test file

 If the user didn't name one, ask: *"Which SSIM test file do you want to seed
 references for? (e.g. `fastvideo/tests/ssim/test_ltx2_similarity.py`)"*.
@@ -95,22 +80,6 @@ Validate:
 - File defines a `*_MODEL_TO_PARAMS` dict — grep it to extract the set of
  model ids. Those ids drive step 5.

-Detect artefact type by inspecting the file's imports / helper call:
-
- **latent** (`.pt`) — file imports `run_text_to_latent_similarity_test`
-  from `fastvideo.tests.ssim.latent_similarity_utils` (or any other helper
-  that ends with `_latent_similarity_test`).
- **pixel** (`.mp4`) — file imports
-  `run_text_to_video_similarity_test` / `run_image_to_video_similarity_test`
-  from `fastvideo.tests.ssim.inference_similarity_utils`, OR uses the
-  legacy custom-inline helper pattern (see `test_gamecraft`,
-  `test_longcat`, etc.). Default to pixel when both heuristics fail.
-
-Record `ARTEFACT_TYPE ∈ {pixel, latent}` for use in step 4. Steps 2, 3, 5,
-and 6 are artefact-type-agnostic — `_iter_reference_files`,
-`copy_generated_to_reference`, and `upload_reference_videos` already walk
-both `.mp4` and `.pt` (see `reference_videos_cli.py`).
-
 If either check fails, stop and tell the user what's wrong.

 ### 2. Run the test on Modal L40S
@@ -123,19 +92,9 @@ TIMESTAMP=$(date -u +%Y%m%d_%H%M%S)
 SUBDIR="${TIMESTAMP}_${SHORT_COMMIT}"
 ```

-Then launch the Modal run. The `IMAGE_VERSION` and `BUILDKITE_*` env-prefix
-**must** match what CI exports in `.buildkite/scripts/pr_test.sh`, otherwise
-`fastvideo/tests/modal/ssim_test.py` resolves a different GHCR image tag
-(default is `latest`, CI is `py3.12-latest`) and bakes different values into
-the image's frozen env block (`ssim_test.py:17-18, 38-46`). Mismatched image
-or env produces SSIM drift that doesn't show up until the same commit runs
-in CI.
+Then launch the Modal run:

 ```bash
-IMAGE_VERSION="py3.12-latest" \
-BUILDKITE_REPO="$(git config --get remote.origin.url)" \
-BUILDKITE_COMMIT="$(git rev-parse HEAD)" \
-BUILDKITE_PULL_REQUEST="${BUILDKITE_PULL_REQUEST:-false}" \
 modal run fastvideo/tests/modal/ssim_test.py \
    --git-repo="$(git config --get remote.origin.url)" \
    --git-commit="$(git rev-parse HEAD)" \
@@ -147,19 +106,6 @@ modal run fastvideo/tests/modal/ssim_test.py \
    --no-fail-fast
 ```

-Env prefix rationale (parity with CI; see `.buildkite/pipeline.yml:1-3` and
-`.buildkite/scripts/pr_test.sh:62-83`):
- `IMAGE_VERSION=py3.12-latest`: pins the Modal image tag to the same one CI
-  uses. Without this, `ssim_test.py:17` falls back to `latest`, which on
-  GHCR is built from `Dockerfile.python3.10` — different Python, torch, and
-  flash-attn wheel than CI's `py3.12-latest` (`infra-build-image.yml:51-67`,
-  `_template-build-image.yml:65-101`).
- `BUILDKITE_REPO`/`BUILDKITE_COMMIT`/`BUILDKITE_PULL_REQUEST`: mirror what
-  Buildkite exports. `ssim_test.py:38-46` bakes these into the image's
-  `.env(...)` block; mismatched values can perturb in-container code paths
-  that branch on PR-vs-non-PR. `false` for `BUILDKITE_PULL_REQUEST` matches
-  Buildkite's "non-PR build" sentinel.
-
 Flag rationale:
 - `--skip-reference-download`: no refs exist yet, so conftest must not try to
  pull them.
@@ -197,59 +143,17 @@ get` preserves that trailing `generated_videos/` segment.

 ### 4. PAUSE — user reviews quality

-Type-aware verification.
-
-**For `ARTEFACT_TYPE = pixel`** — list the downloaded mp4s and ask the user to
-open them in a video player:
+Print the list of downloaded mp4s and their paths, then stop. Tell the user:

 > "Generated videos downloaded to `./generated_videos_modal/default/generated_videos/L40S_reference_videos/`. Please open them and confirm the quality looks correct. Reply **`upload`** to continue, or anything else to abort."

-**For `ARTEFACT_TYPE = latent`** — `.pt` files are not human-watchable. Print
-a numerics dump for each `.pt` so the user can sanity-check shape, distribution,
-and metadata:
-
-```python
-import torch
-from pathlib import Path
-ROOT = Path("./generated_videos_modal/default/generated_videos/L40S_reference_videos")
-for p in sorted(ROOT.rglob("*.pt")):
-    d = torch.load(p, map_location="cpu", weights_only=False)
-    s = d["expected_slice"]
-    L = d["latent"].float()
-    print(f"=== {p.relative_to(ROOT)} ===")
-    print(f"  format_version: {d['format_version']}")
-    print(f"  shape:          {d['shape']}")
-    print(f"  dtype_original: {d['dtype_original']}")
-    print(f"  slice_spec:     {d['slice_spec']}")
-    print(f"  slice  shape={tuple(s.shape)}  mean={s.mean():+.4f}  std={s.std():.4f}  min={s.min():+.4f}  max={s.max():+.4f}")
-    print(f"  latent shape={tuple(L.shape)}  mean={L.mean():+.4f}  std={L.std():.4f}  min={L.min():+.4f}  max={L.max():+.4f}")
-    print(f"  finite: latent NaN={torch.isnan(L).any().item()} Inf={torch.isinf(L).any().item()}; "
-          f"slice NaN={torch.isnan(s).any().item()} Inf={torch.isinf(s).any().item()}")
-    print(f"  metadata: {d['metadata']}\n")
-```
-
-Sanity criteria:
- `format_version == 1` (matches `LATENT_REFERENCE_FORMAT_VERSION`).
- `shape` matches what the model produces (e.g. LTX-2 distilled =
-  `[1, 128, T_lat, H_lat, W_lat]`; Stable Audio Open 1.0 = `[1, 64, 1024]`).
- `slice_spec.kind` matches a registered kind (`corner_3x3_first_frame`
-  for video, `audio_first_8_timesteps` for audio).
- No `NaN`/`Inf`. `mean ≈ 0`, `std ≈ 1` (denoised latents stay close to
-  the initial Gaussian distribution; very wide deviations suggest
-  numerical drift).
- `metadata.prompt` matches the test's prompt.
-
-Then ask:
-
-> "Numerics look right? Reply **`upload`** to continue, or anything else to abort."
-
 Do not proceed until the user explicitly says `upload`. If they abort, leave
 everything on disk so they can inspect further — no cleanup.

 ### 5. Copy into the local reference layout

-Scoped copy — only the new test's artefacts. Single command works for both
-artefact types because `_iter_reference_files` walks `.mp4` and `.pt`:
+Scoped copy — only the new test's mp4s. Loop over each `<model_id>` extracted
+in step 1:

 ```bash
 python fastvideo/tests/ssim/reference_videos_cli.py copy-local \
@@ -259,13 +163,12 @@ python fastvideo/tests/ssim/reference_videos_cli.py copy-local \
 ```

 (The `--generated-dir` points at the device-folder root inside the
-downloaded tree; `copy-local` walks all `<model>/<backend>/*.{mp4,pt}`
+downloaded tree; `copy-local` walks all `<model>/<backend>/*.mp4`
 underneath it. Since the Modal run was scoped to a single test file via
 `--test-files`, only that test's model(s) are present — so the copy is
 implicitly per-test.)

-Result for pixel: `fastvideo/tests/ssim/reference_videos/default/L40S_reference_videos/<model_id>/<backend>/<prompt>.mp4`.
-Result for latent: same path with `.pt` extension.
+Result: `fastvideo/tests/ssim/reference_videos/default/L40S_reference_videos/<model_id>/<backend>/<prompt>.mp4`.

 ### 6. Upload to HF — scoped per model_id, with overwrite guard

@@ -298,54 +201,33 @@ it will auto-download the refs they just uploaded.
 ## Failure modes and how to handle them

 - **`HF_API_KEY` unset.** Stop before step 2. The Modal run needs it (passed
-  via `--hf-api-key`), and step 6 needs it for upload. If the user
-  ran `hf auth login` instead of exporting an env var, read the cached
-  token via `huggingface_hub.get_token()` and forward it to Modal as
-  `--hf-api-key="$CACHED_TOKEN"`.
- **Modal run fails before generation.** No artefacts on the volume — nothing
-  to download. Fix the test locally (`pytest fastvideo/tests/ssim/<test_file>`)
+  via `--hf-api-key`), and step 6 needs it for upload.
+- **Modal run fails before generation.** No mp4s on the volume — nothing to
+  download. Fix the test locally (`pytest fastvideo/tests/ssim/<test_file>`)
  and retry from step 2.
 - **`./generated_videos_modal/default/L40S_reference_videos/` missing after
-  `modal volume get`.** The run didn't produce artefacts (most likely the
-  test crashed before writing, or `REQUIRED_GPUS` exceeded the partition
-  capacity — see Modal logs).
- **Latent test crashed with FSDP / inference_mode error
-  (`RuntimeError: Inference tensors do not track version counter`).** The
-  test must pass `init_kwargs_override={"use_fsdp_inference": False}` when
-  `sp_size == 1` — see `test_stable_audio_similarity.py` for the pattern.
-  Fix in the test, push, retry.
+  `modal volume get`.** The run didn't produce videos (most likely the test
+  crashed before writing, or `REQUIRED_GPUS` exceeded the partition capacity
+  — see Modal logs).
 - **Upload guard fires (files already exist).** The test name / model id
  collides with something already on HF. Verify the user actually wants to
  replace existing refs; if so, re-run the upload with `--force`. If not,
  rename the model id in `*_MODEL_TO_PARAMS` and re-seed.
- **Quality looks wrong in step 4.** Abort. The artefacts stay on disk for
+- **Quality looks wrong in step 4.** Abort. The mp4s stay on disk for
  inspection. The fix is usually in the test's params (resolution, steps,
  seed) — edit the test, then re-run the skill.
-  - For latent: also check `slice_spec.kind` matches the latent rank
-    (`corner_3x3_first_frame` requires 5-D, `audio_first_8_timesteps`
-    requires 3-D); a rank/kind mismatch raises in `_extract_expected_slice`.

 ## Design notes (for future skill maintainers)

 - The skill deliberately runs on Modal, **not** locally, because the CI
  runner is L40S. Seeding from a different GPU SKU produces refs that CI's
-  L40S runs can't match (pixel SSIM drifts across SKUs; latent cosine has
-  tighter cross-SKU bf16 drift but the configured tolerances assume
-  same-SKU seed → same-SKU verify).
+  L40S runs can't match (SSIM drifts across SKUs).
 - The skill is default-tier only. `full_quality` refs are seeded by a
  separate, deliberate operation — they double runtime and aren't what CI
  gates on.
 - The overwrite guard in `reference_videos_cli.py upload` is default-on
  specifically because this skill exists. Re-seeding is a distinct operation
  that requires explicit `--force`.
- Both artefact types share the same Modal flow: the orchestrator sets
-  `--skip-reference-download` + `--no-fail-fast`, runs pytest, the test's
-  helper writes the artefact (`.mp4` via `imageio` for pixel,
-  `save_latent_reference` → `torch.save` for latent) BEFORE the
-  missing-reference assertion raises. `_sync_generated_videos_to_volume` in
-  `ssim_test.py` does a `shutil.copytree` of the whole `generated_videos/`
-  tree, picking up `.mp4`, `.pt`, and the `*_ssim.json` / `*_latent.json`
-  metric files alongside.

 ## References

@@ -354,17 +236,10 @@ it will auto-download the refs they just uploaded.
  `--skip-reference-download`, `--no-fail-fast`.
 - `fastvideo/tests/ssim/reference_videos_cli.py` — `copy-local`, `upload`
  (with `--model-id`, `--force`), `download`, `ensure` subcommands.
-  Extension allowlist is `REFERENCE_EXTENSIONS = VIDEO_EXTENSIONS +
-  LATENT_EXTENSIONS` (`.pt`).
 - `fastvideo/tests/ssim/README.md` — reference layout, HF repo conventions.
- `fastvideo/tests/ssim/inference_similarity_utils.py` — pixel helpers
-  (`run_text_to_video_similarity_test`,
-  `run_image_to_video_similarity_test`, `build_init_kwargs`).
- `fastvideo/tests/ssim/latent_similarity_utils.py` — latent helper
-  (`run_text_to_latent_similarity_test`), slice spec dispatch
-  (`_extract_expected_slice`), reference schema
-  (`save_latent_reference` / `load_latent_reference`),
-  `LATENT_REFERENCE_FORMAT_VERSION`.
+- `fastvideo/tests/ssim/inference_similarity_utils.py` —
+  `run_text_to_video_similarity_test` + `_build_init_kwargs`: what each test
+  config passes to `VideoGenerator.from_pretrained`.

 ## Changelog

@@ -373,4 +248,3 @@ it will auto-download the refs they just uploaded.
 | 2026-04-17 | Initial version (Modal sync-to-volume flow). |
 | 2026-04-21 | Rewrite: single-test scope, explicit user-review pause, per-`model_id` upload, HF overwrite guard. Dropped `scripts/seed_ssim.sh`. |
 | 2026-04-21 | Post-first-run fixes: `modal volume get` needs `--force` when parent exists; download tree has an extra `generated_videos/` level so `--generated-dir` must reflect it. |
-| 2026-05-01 | Latent (`*.pt`) artefact support: artefact-type detection in step 1, type-aware verification (visual eyeball for mp4, numerics dump for pt) in step 4, FSDP+inference_mode failure-mode added, design notes for the unified Modal flow. Triggered by PR #1253 (LTX-2 latent migration + Stable Audio latent test). |
@@ -29,8 +29,8 @@
    "Will Smith casually eats noodles, his relaxed demeanor contrasting with the energetic background of a bustling street food market. The scene captures a mix of humor and authenticity. Mid-shot framing, vibrant lighting."
  ],
  "run_config": {
-    "num_warmup_runs": 2,
-    "num_measurement_runs": 5,
+    "num_warmup_runs": 1,
+    "num_measurement_runs": 3,
    "required_gpus": 2
  },
  "thresholds": {
@@ -15,21 +15,8 @@ log "Project root: $PROJECT_ROOT"
 # Install Modal if not available
 if ! python3 -m modal --version &> /dev/null; then
    log "Modal not found, installing..."
-    if ! command -v uv &> /dev/null; then
-        log "uv not found, bootstrapping..."
-        if ! curl -LsSf https://astral.sh/uv/install.sh | sh; then
-            log "Error: Failed to bootstrap uv via astral.sh installer."
-            exit 1
-        fi
-        export PATH="$HOME/.local/bin:$PATH"
-        if ! command -v uv &> /dev/null; then
-            log "Error: uv still not on PATH after bootstrap."
-            exit 1
-        fi
-    fi
-    # --break-system-packages preserves prior `pip install --user` semantics on PEP 668 agents.
-    uv pip install --system --break-system-packages modal
-
+    python3 -m pip install modal
+    
    # Verify installation
    if ! python3 -m modal --version &> /dev/null; then
        log "Error: Failed to install modal. Please install it manually."
@@ -76,72 +63,7 @@ EFFECTIVE_PR=${BUILDKITE_PULL_REQUEST:-false}
 if [ "$EFFECTIVE_PR" = "false" ] && [ -n "${PR_NUMBER:-}" ]; then
    EFFECTIVE_PR=$PR_NUMBER
 fi
-MODAL_ENV="BUILDKITE_REPO=$BUILDKITE_REPO BUILDKITE_COMMIT=$BUILDKITE_COMMIT BUILDKITE_PULL_REQUEST=$EFFECTIVE_PR BUILDKITE_BRANCH=${BUILDKITE_BRANCH:-} TEST_SCOPE=${TEST_SCOPE:-} IMAGE_VERSION=$IMAGE_VERSION"
-
-POST_RUN_HOOK=""
-
-upload_performance_artifacts() {
-    SHORT_SHA=${BUILDKITE_COMMIT:0:7}
-    LOCAL_DIR="downloaded_reports"
-
-    _download_reports() {
-        log "Downloading perf_reports/ from Modal Volume..."
-        mkdir -p "$LOCAL_DIR"
-        if ! modal volume get hf-model-weights "perf_reports/" "$LOCAL_DIR"; then
-            log "Error: Failed to download perf_reports/ from Modal Volume."
-            return 1
-        fi
-    }
-
-    _upload_dashboard() {
-        local target
-        target=$(find "$LOCAL_DIR" -name "dashboard_${SHORT_SHA}_*" | head -n 1)
-        log "TARGET dashboard: '$target'"
-
-        if [ -n "$target" ]; then
-            log "Found dashboard: $target. Uploading to Buildkite..."
-            buildkite-agent artifact upload "$target"
-            buildkite-agent annotate --style info --context "perf-dashboard" < "$target"
-        else
-            log "Warning: Could not find a dashboard file matching $SHORT_SHA"
-        fi
-    }
-
-    _upload_perf_summary() {
-        local target
-        target=$(find "$LOCAL_DIR" -name "perf_${SHORT_SHA}_*" | head -n 1)
-        log "TARGET perf summary: '$target'"
-
-        if [ -n "$target" ]; then
-            log "Found perf summary: $target. Uploading to Buildkite..."
-            buildkite-agent artifact upload "$target"
-            buildkite-agent annotate --style info --context "perf-summary" < "$target"
-        else
-            log "Warning: Could not find a perf summary file matching $SHORT_SHA"
-        fi
-    }
-
-    _cleanup_modal_volume() {
-        log "Cleaning up perf_reports/ from Modal Volume..."
-        if modal volume rm hf-model-weights "perf_reports/" --recursive; then
-            log "Successfully deleted perf_reports/ from Modal Volume."
-        else
-            log "Warning: Failed to delete perf_reports/ from Modal Volume. Manual cleanup may be required."
-        fi
-    }
-
-    _cleanup_local() {
-        log "Cleaning up local download directory..."
-        rm -rf "$LOCAL_DIR"
-    }
-
-    # --- Main flow ---
-    _download_reports || { _cleanup_local; return 1; }
-    _upload_dashboard
-    _upload_perf_summary
-    _cleanup_modal_volume
-    _cleanup_local
-}
+MODAL_ENV="BUILDKITE_REPO=$BUILDKITE_REPO BUILDKITE_COMMIT=$BUILDKITE_COMMIT BUILDKITE_PULL_REQUEST=$EFFECTIVE_PR IMAGE_VERSION=$IMAGE_VERSION"

 case "$TEST_TYPE" in
    "encoder")
@@ -202,9 +124,8 @@ case "$TEST_TYPE" in
        MODAL_COMMAND="$MODAL_ENV HF_API_KEY=$HF_API_KEY python3 -m modal run $MODAL_TEST_FILE::run_lora_extraction_tests"
        ;;
    "performance")
-        log "Running performance tests on Modal..."
+        log "Running performance tests..."
        MODAL_COMMAND="$MODAL_ENV HF_API_KEY=$HF_API_KEY python3 -m modal run $MODAL_TEST_FILE::run_performance_tests"
-        POST_RUN_HOOK="upload_performance_artifacts"
        ;;
    "api_server")
        log "Running API server integration tests..."
@@ -226,10 +147,5 @@ else
    log "Error: Modal test failed with exit code: $TEST_EXIT_CODE"
 fi

-if [ -n "$POST_RUN_HOOK" ]; then
-    log "Executing post-run hook: $POST_RUN_HOOK"
-    "$POST_RUN_HOOK"
-fi
-
 log "=== Test execution completed with exit code: $TEST_EXIT_CODE ==="
 exit $TEST_EXIT_CODE
@@ -13,21 +13,8 @@ log "Project root: $PROJECT_ROOT"

 if ! python3 -m pre_commit --version &> /dev/null; then
    log "pre-commit not found, installing..."
-    if ! command -v uv &> /dev/null; then
-        log "uv not found, bootstrapping..."
-        if ! curl -LsSf https://astral.sh/uv/install.sh | sh; then
-            log "Error: Failed to bootstrap uv via astral.sh installer."
-            exit 1
-        fi
-        export PATH="$HOME/.local/bin:$PATH"
-        if ! command -v uv &> /dev/null; then
-            log "Error: uv still not on PATH after bootstrap."
-            exit 1
-        fi
-    fi
-    # --break-system-packages preserves prior `pip install --user` semantics on PEP 668 agents.
-    uv pip install --system --break-system-packages pre-commit==4.0.1
-
+    python3 -m pip install --user pre-commit==4.0.1
+    
    if ! python3 -m pre_commit --version &> /dev/null; then
        log "Error: Failed to install pre-commit."
        exit 1
@@ -37,11 +37,10 @@ jobs:
        with:
          python-version: '3.12'

-      - name: Install uv
-        uses: astral-sh/setup-uv@v3
-
      - name: Install dependencies
-        run: uv pip install --system -r requirements-mkdocs.txt
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements-mkdocs.txt

      - name: Setup Pages
        uses: actions/configure-pages@v4
@@ -56,11 +56,10 @@ jobs:
        with:
          python-version: '3.10'

-      - name: Install uv
-        uses: astral-sh/setup-uv@v3
-
      - name: Install build dependencies
-        run: uv pip install --system build twine wheel
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine wheel

      - name: Build package
        run: |
@@ -131,13 +131,11 @@ jobs:
          clang-11 --version
          nvcc --version

-      - name: Install uv
-        uses: astral-sh/setup-uv@v3
-
      - name: Install PyTorch ${{ matrix.torch-cuda.torch-version }}+cu${{ matrix.torch-cuda.cuda-version }}
        run: |
-          uv pip install --system typing-extensions==4.12.2
-          uv pip install --system --no-cache-dir torch==${{ matrix.torch-cuda.torch-version }} --index-url https://download.pytorch.org/whl/${{matrix.torch-cuda.torch-cuda-short}}
+          pip install --upgrade pip
+          pip install typing-extensions==4.12.2
+          pip install --no-cache-dir torch==${{ matrix.torch-cuda.torch-version }} --index-url https://download.pytorch.org/whl/${{matrix.torch-cuda.torch-cuda-short}}
          nvcc --version
          python --version
          python -c "import torch; print('PyTorch:', torch.__version__)"
@@ -147,20 +145,20 @@ jobs:
      - name: Build wheel
        run: |
          export PYTHONPATH=$GITHUB_WORKSPACE:$PYTHONPATH
-
-          uv pip install --system setuptools ninja packaging wheel triton scikit-build-core cmake build
-
+          
+          pip install setuptools ninja packaging wheel triton scikit-build-core cmake build
+          
          cd fastvideo-kernel
          git submodule update --init --recursive  # Ensure ThunderKittens submodule is initialized
          # Release builds are produced on GPU-less runners, so force-enable TK and target Hopper.
          export TORCH_CUDA_ARCH_LIST="9.0a"
          export CMAKE_ARGS="${CMAKE_ARGS:-} -DFASTVIDEO_KERNEL_BUILD_TK=ON -DCMAKE_CUDA_ARCHITECTURES=90a"
-
+          
          # Build standard wheel (no local version suffix) for PyPI
          python -m build --wheel --outdir dist
-
+          
          # Fix the wheel to be manylinux compliant
-          uv pip install --system auditwheel
+          pip install auditwheel
          # Point auditwheel at torch libs, but do not vendor them into the wheel.
          TORCH_LIB_DIR=$(python - <<'PY'
          import os
@@ -213,13 +211,10 @@ jobs:
          pattern: 'fastvideo_kernel-py*'
          merge-multiple: true

-      - name: Install uv
-        uses: astral-sh/setup-uv@v3
-
      - name: Build source distribution
        run: |
-          uv pip install --system build scikit-build-core cmake ninja
-
+          pip install build scikit-build-core cmake ninja
+          
          cd fastvideo-kernel
          # We don't need full CUDA/Torch to just package the source (sdist)
          python -m build --sdist --outdir dist
@@ -92,11 +92,3 @@ preprocess_output_text/
 .sisyphus/
 openspec/
 fastvideo/tests/ssim/reference_videos/**
-
-# Local clones of upstream repos used only for parity testing.
-/stable-audio-tools/
-/daVinci-MagiHuman/
-
-# Converted model weights (produced by scripts/checkpoint_conversion/*).
-# Tens of GB; should live on HF, not in git.
-/converted_weights/
@@ -7,13 +7,20 @@ exclude: |
    fastvideo-kernel/.*|
    assets/.*|
    tests/.*|
+    demo/.*|
+    predict\.py|
    scripts/.*|
+    assets/prompts/.*|
+    fastvideo/data_preprocess/.*|
    fastvideo/dataset/.*|
    fastvideo/models/.*|
+    fastvideo/sample/.*|
+    fastvideo/train\.py|
+    fastvideo/utils/.*|
    examples/.*|
-    \.agents/.*|
    .github/workflows/publish-fastvideo.yml|
-    .github/workflows/_template-build-image.yml
+    .github/workflows/_template-build-image.yml|
+    docs/source/inference/support_matrix.md
  )
 repos:
 - repo: https://github.com/google/yapf
@@ -11,7 +11,7 @@
 - Static assets: `assets/` (including `assets/images/`, `assets/videos/`, and `assets/prompts/`) and `comfyui/assets/`.

 ## Build, Test, and Development Commands
- `uv pip install -e ".[dev]"`: editable install with lint/test extras.
+- `uv pip install -e .[dev]`: editable install with lint/test extras.
 - `pre-commit install --hook-type pre-commit --hook-type commit-msg`: enable local hooks.
 - `pre-commit run --all-files`: run formatter/lint/type/spelling checks.
 - `pytest tests/`: run top-level test suite.
@@ -23,8 +23,7 @@
 - Python 3.10+; 4-space indentation; keep code and imports readable and explicit.
 - Style tools are configured in `pyproject.toml` and `.pre-commit-config.yaml`:
  - `yapf` (format), `ruff` (lint, auto-fix), `mypy` (typing), `codespell`.
- Lint via `pre-commit run --files <changed paths>` (or `pre-commit run --all-files` for a full sweep) before committing. Do not shell out to `yapf`/`ruff`/`codespell`/`mypy` directly — pre-commit chains them with the project's config and respects the `.pre-commit-config.yaml` excludes (e.g. `fastvideo/tests/` is intentionally skipped). If pre-commit reports `(no files to check)` for your paths, that exclude is deliberate — don't bypass it.
- Target line length is 120 (configured in `pyproject.toml` for ruff, yapf, and isort).
+- Target line length is 80.
 - Naming: `snake_case` for functions/files, `PascalCase` for classes, `UPPER_SNAKE_CASE` for constants.

 ## Testing Guidelines
@@ -55,31 +54,3 @@ This repository is agent-friendly. Before doing any work, read:
 If you are exploring a new procedure that has no existing SOP, document your
 progress in `.agents/exploration/` and flag it for review at the end of your
 session.
-
-## Per-Directory AGENTS.md
-
-Local guidance lives next to the code. Read the in-scope file before editing:
-
-| Directory | What it covers |
-|-----------|----------------|
-| `fastvideo/AGENTS.md` | Core package map, public API, registry-driven model dispatch |
-| `fastvideo/configs/AGENTS.md` | Arch + pipeline config dataclasses, `param_names_mapping` |
-| `fastvideo/models/AGENTS.md` | DiT / VAE / encoder / scheduler / loader layout (pre-commit excluded) |
-| `fastvideo/layers/AGENTS.md` | Tensor-parallel linear/attention layer rules for ports |
-| `fastvideo/attention/AGENTS.md` | Backend registry + env-var override |
-| `fastvideo/pipelines/AGENTS.md` | Stage ABC, `basic/<model>/`, `preprocess/`, presets |
-| `fastvideo/training/AGENTS.md` | Legacy monolithic pipelines (frozen for existing models) |
-| `fastvideo/train/AGENTS.md` | New modular trainer (methods × models × callbacks, YAML) |
-| `fastvideo/tests/AGENTS.md` | Test taxonomy, conftest, pre-commit-excluded path |
-| `fastvideo/tests/ssim/AGENTS.md` | GPU SSIM regression authoring + reference video sync |
-| `scripts/checkpoint_conversion/AGENTS.md` | Adding a converter for a new HF/official checkpoint |
-
-## Critical: Two Training Stacks Coexist
-
- `fastvideo/training/` — legacy, monolithic per-model `*_training_pipeline.py` and
-  `*_distillation_pipeline.py`. Still authoritative for shipped models.
- `fastvideo/train/` — new modular framework (composable methods × models × callbacks
-  driven by YAML). Preferred for new training work.
-
-Pick the matching stack before editing. Do not migrate a pipeline between them
-without an explicit ask — the conventions and config surfaces differ.
@@ -128,7 +128,7 @@ class CLIPFeatureExtractor(BaseFeatureExtractor):

    def __init__(self, device: str = 'cuda', model_name: str = "openai/clip-vit-base-patch32"):
        if not TRANSFORMERS_AVAILABLE:
-            raise ImportError("Please install transformers: uv pip install transformers")
+            raise ImportError("Please install transformers: pip install transformers")
        super().__init__(device)
        self.processor = CLIPProcessor.from_pretrained(model_name)
        self.model = CLIPModel.from_pretrained(model_name).to(self.device)
@@ -171,7 +171,7 @@ class VideoMAEFeatureExtractor(BaseFeatureExtractor):

    def __init__(self, device: str = 'cuda', model_name: str = "MCG-NJU/videomae-base"):
        if not TRANSFORMERS_AVAILABLE:
-            raise ImportError("Please install transformers: uv pip install transformers")
+            raise ImportError("Please install transformers: pip install transformers")
        super().__init__(device)
        self.model = VideoMAEModel.from_pretrained(model_name).to(self.device)
        self.model.eval()
@@ -57,7 +57,7 @@ class I3DFeatureExtractor(nn.Module):
        except Exception as e:
            raise RuntimeError(f"Failed to load I3D model from Hugging Face Hub. Error: {e}\n"
                               f"Ensure you have internet connection and huggingface_hub installed:\n"
-                               f"uv pip install huggingface_hub") from e
+                               f"pip install huggingface_hub") from e

    def preprocess(self, videos: torch.Tensor) -> torch.Tensor:
        """
@@ -1,7 +1,7 @@
 #!/bin/bash

 # 1. Install missing dependency
-uv pip install -q opencv-python-headless transformers huggingface_hub
+pip install -q opencv-python-headless transformers huggingface_hub

 # 2. Run FVD script
 python benchmarks/fvd/run_fvd.py
@@ -1,4 +1,4 @@
 #!/bin/bash

 # 1. Install missing dependency
-uv pip install -q opencv-python-headless
+pip install -q opencv-python-headless
@@ -38,10 +38,10 @@ cp -r /path/to/FastVideo/comfyui /path/to/ComfyUI/custom_nodes/FastVideo

 #### Install dependencies:

-Currently, the only dependency is `fastvideo`, which can be installed with `uv`.
+Currently, the only dependency is `fastvideo`, which can be installed using pip.

 ```bash
-uv pip install fastvideo
+pip install fastvideo
 ```

 #### Install missing custom nodes:
@@ -42,15 +42,15 @@ RUN source $HOME/.local/bin/env && \
    uv venv --python 3.10 --seed /opt/venv && \
    source /opt/venv/bin/activate && \
    uv pip install --no-cache-dir --upgrade pip && \
-    uv pip install --no-cache-dir ".[dev]" && \
-    uv pip install --no-cache-dir https://github.com/mjun0812/flash-attention-prebuild-wheels/releases/download/v0.9.4/flash_attn-2.8.3+cu128torch2.11-cp310-cp310-linux_x86_64.whl
+    uv pip install --no-cache-dir .[dev] && \
+    uv pip install --no-cache-dir https://github.com/mjun0812/flash-attention-prebuild-wheels/releases/download/v0.7.16/flash_attn-2.8.3+cu128torch2.10-cp310-cp310-linux_x86_64.whl

 COPY . .

 # Install dependencies using uv and set up shell configuration
 RUN source $HOME/.local/bin/env && \
    source /opt/venv/bin/activate && \
-    uv pip install --no-cache-dir -e ".[dev]" && \
+    uv pip install --no-cache-dir -e .[dev] && \
    git config --unset-all http.https://github.com/.extraheader || true && \
    echo 'source /opt/venv/bin/activate' >> /root/.bashrc && \
    echo 'if [ -n "$ZSH_VERSION" ] && [ -f ~/.zshrc ]; then . ~/.zshrc; elif [ -f ~/.bashrc ]; then . ~/.bashrc; fi' > /root/.profile
@@ -42,15 +42,15 @@ RUN source $HOME/.local/bin/env && \
    uv venv --python 3.11 --seed /opt/venv && \
    source /opt/venv/bin/activate && \
    uv pip install --no-cache-dir --upgrade pip && \
-    uv pip install --no-cache-dir ".[dev]" && \
-    uv pip install --no-cache-dir https://github.com/mjun0812/flash-attention-prebuild-wheels/releases/download/v0.9.4/flash_attn-2.8.3+cu128torch2.11-cp311-cp311-linux_x86_64.whl
+    uv pip install --no-cache-dir .[dev] && \
+    uv pip install --no-cache-dir https://github.com/mjun0812/flash-attention-prebuild-wheels/releases/download/v0.7.16/flash_attn-2.8.3+cu128torch2.10-cp311-cp311-linux_x86_64.whl

 COPY . .

 # Install dependencies using uv and set up shell configuration
 RUN source $HOME/.local/bin/env && \
    source /opt/venv/bin/activate && \
-    uv pip install --no-cache-dir -e ".[dev]" && \
+    uv pip install --no-cache-dir -e .[dev] && \
    git config --unset-all http.https://github.com/.extraheader || true && \
    echo 'source /opt/venv/bin/activate' >> /root/.bashrc && \
    echo 'if [ -n "$ZSH_VERSION" ] && [ -f ~/.zshrc ]; then . ~/.zshrc; elif [ -f ~/.bashrc ]; then . ~/.bashrc; fi' > /root/.profile
@@ -42,15 +42,15 @@ RUN source $HOME/.local/bin/env && \
    uv venv --python 3.12 --seed /opt/venv && \
    source /opt/venv/bin/activate && \
    uv pip install --no-cache-dir --upgrade pip && \
-    uv pip install --no-cache-dir ".[dev]" && \
-    uv pip install --no-cache-dir https://github.com/mjun0812/flash-attention-prebuild-wheels/releases/download/v0.9.4/flash_attn-2.8.3+cu128torch2.11-cp312-cp312-linux_x86_64.whl
+    uv pip install --no-cache-dir .[dev] && \
+    uv pip install --no-cache-dir https://github.com/mjun0812/flash-attention-prebuild-wheels/releases/download/v0.7.16/flash_attn-2.8.3+cu128torch2.10-cp312-cp312-linux_x86_64.whl

 COPY . .

 # Install dependencies using uv and set up shell configuration
 RUN source $HOME/.local/bin/env && \
    source /opt/venv/bin/activate && \
-    uv pip install --no-cache-dir -e ".[dev]" && \
+    uv pip install --no-cache-dir -e .[dev] && \
    git config --unset-all http.https://github.com/.extraheader || true && \
    echo 'source /opt/venv/bin/activate' >> /root/.bashrc && \
    echo 'if [ -n "$ZSH_VERSION" ] && [ -f ~/.zshrc ]; then . ~/.zshrc; elif [ -f ~/.bashrc ]; then . ~/.bashrc; fi' > /root/.profile
@@ -42,7 +42,7 @@ RUN source $HOME/.local/bin/env && \
    uv venv --python 3.12 --seed /opt/venv && \
    source /opt/venv/bin/activate && \
    uv pip install --no-cache-dir --upgrade pip && \
-    uv pip install --no-cache-dir ".[dev]" && \
+    uv pip install --no-cache-dir .[dev] && \
    uv pip install --no-cache-dir flash-attn==2.8.3 --no-build-isolation

 COPY . .
@@ -50,7 +50,7 @@ COPY . .
 # Install dependencies using uv and set up shell configuration
 RUN source $HOME/.local/bin/env && \
    source /opt/venv/bin/activate && \
-    uv pip install --no-cache-dir -e ".[dev]" && \
+    uv pip install --no-cache-dir -e .[dev] && \
    git config --unset-all http.https://github.com/.extraheader || true && \
    echo 'source /opt/venv/bin/activate' >> /root/.bashrc && \
    echo 'if [ -n "$ZSH_VERSION" ] && [ -f ~/.zshrc ]; then . ~/.zshrc; elif [ -f ~/.bashrc ]; then . ~/.bashrc; fi' > /root/.profile
@@ -43,7 +43,7 @@ COPY . .
 # Install dependencies using uv and set up shell configuration
 RUN source $HOME/.local/bin/env && \
    source /opt/venv/bin/activate && \
-    uv pip install --no-cache-dir -e ".[rocm]" && \
+    uv pip install --no-cache-dir -e .[rocm] && \
    git config --unset-all http.https://github.com/.extraheader || true && \
    echo 'source /opt/venv/bin/activate' >> /root/.bashrc && \
    echo 'if [ -n "$ZSH_VERSION" ] && [ -f ~/.zshrc ]; then . ~/.zshrc; elif [ -f ~/.bashrc ]; then . ~/.bashrc; fi' > /root/.profile
@@ -6,7 +6,7 @@ This directory contains the FastVideo documentation built with MkDocs.

 ```bash
 # Install dependencies
-uv pip install -r requirements-mkdocs.txt
+pip install -r requirements-mkdocs.txt

 # Serve docs with live reload (recommended for development)
 mkdocs serve
@@ -1,210 +0,0 @@
-# Activation Trace Mode
-
-!!! note
-    This page covers Extension 0 (module forward hooks), which is the implemented
-    tracing mechanism. Extensions 1-3 are design sketches for future work and are
-    **not yet implemented**.
-
-## Overview
-
-Activation trace mode is a zero-overhead-when-off, env-gated mechanism for
-dumping per-layer activation statistics during FastVideo inference. Its primary
-use case is **parity debugging across model ports**: enable tracing on both
-FastVideo and the upstream reference implementation, then `diff` the resulting
-JSONL files to find the first divergent layer.
-
-The mechanism is intentionally narrow. It doesn't replace general logging,
-profiling, or function tracing. It answers one question: "at which layer do
-FastVideo and the reference model first produce different numbers?"
-
-## When to use
-
- Investigating numerical drift between FastVideo and an upstream reference.
- Debugging mid-pipeline divergence (e.g., one block produces wrong output while earlier blocks match).
- Validating that a refactor preserves bf16 noise-floor behavior across many layers.
-
-## When NOT to use
-
-| Goal | Use instead |
-|---|---|
-| General logging | `init_logger(__name__)` |
-| Per-stage timing | `FASTVIDEO_STAGE_LOGGING` |
-| Profiling kernel timings | `FASTVIDEO_TORCH_PROFILER_DIR` (see [Profiling](profiling.md)) |
-| Function-call tracing | `FASTVIDEO_TRACE_FUNCTION` (heavy) |
-
-## Quickstart
-
-```bash
-FASTVIDEO_TRACE_ACTIVATIONS=1 \
-FASTVIDEO_TRACE_LAYERS="^block\.layers\.[0-9]+$" \
-FASTVIDEO_TRACE_STATS="abs_mean,sum,max,shape" \
-FASTVIDEO_TRACE_OUTPUT="/tmp/fv_trace.jsonl" \
-python examples/inference/basic/basic_magi_human.py
-```
-
-Each line in `/tmp/fv_trace.jsonl` is a JSON record:
-
-```json
-{"module": "block.layers.0", "tensor": "out", "step": 0, "abs_mean": 1.234, "sum": -5.678, "max": 9.012, "shape": [1, 4096, 5120]}
-```
-
-## Configuration
-
-| Env var | Default | Description |
-|---|---|---|
-| `FASTVIDEO_TRACE_ACTIVATIONS` | `False` | Master toggle. When unset or false, **zero overhead** in the production hot path. |
-| `FASTVIDEO_TRACE_LAYERS` | `""` (all) | Python regex filter applied to `model.named_modules()` names. Empty string matches all modules. |
-| `FASTVIDEO_TRACE_STATS` | `"abs_mean,sum"` | Comma-separated stats to compute. Available: `abs_mean`, `sum`, `min`, `max`, `mean`, `std`, `shape`, `dtype`. |
-| `FASTVIDEO_TRACE_OUTPUT` | `"/tmp/fv_trace_<pid>.jsonl"` | Output file path. `<pid>` is replaced with the process ID at runtime. |
-| `FASTVIDEO_TRACE_STEPS` | `""` (all) | Comma-separated denoising step indices to capture. Empty string captures all steps. |
-
-## Workflow: parity-debug a model port
-
-1. Set up a tightly-controlled comparison: a parity test or a small standalone
-   script that loads both the FastVideo model and the upstream reference with
-   identical inputs and seeds.
-
-2. Run the FastVideo side with tracing on:
-
-   ```bash
-   FASTVIDEO_TRACE_ACTIVATIONS=1 \
-   FASTVIDEO_TRACE_LAYERS="<your regex>" \
-   FASTVIDEO_TRACE_OUTPUT="/tmp/fv_trace_fv.jsonl" \
-   python <fv_runner.py>
-   ```
-
-3. Run the upstream side. The upstream repo needs separate instrumentation. See
-   "Hooking the upstream side" below.
-
-4. Sort both files by `(module, step)` if needed, then diff:
-
-   ```bash
-   diff /tmp/fv_trace_fv.jsonl /tmp/fv_trace_upstream.jsonl
-   ```
-
-5. The first divergent line identifies the first layer where FastVideo and the
-   upstream produce different outputs. Start debugging there.
-
-## Architecture (Extension 0: module forward hooks)
-
-At pipeline initialization, `attach_activation_trace()` reads the env vars once.
-If `FASTVIDEO_TRACE_ACTIVATIONS` is unset or false, the function returns
-immediately and no hooks are registered. If tracing is on, it walks
-`model.named_modules()`, filters by the layer regex, and registers an
-`ActivationStatHook` on each matching module.
-
-During the forward pass, each hook fires after its module completes, computes
-the requested stats on the output tensor, and appends a JSON record to the
-output file.
-
-```
-ComposedPipelineBase
-  └─ attach_activation_trace()
-       ├─ reads env vars (once at startup)
-       ├─ if off: returns None immediately
-       └─ if on: walks named_modules()
-            └─ registers ActivationStatHook on matching modules
-                 └─ on each forward: compute stats → append JSONL
-```
-
-### Zero-overhead-when-off guarantee
-
- The env var check happens **once at startup** inside `attach_activation_trace()`.
- If the env var is unset or false, the function returns `None` immediately.
- No hooks are registered. No branches are added to the production forward path.
- The only cost when tracing is off is one env var lookup at pipeline
-  initialization, which takes under a microsecond.
-
-### Hooking the upstream side
-
-The upstream reference repo isn't part of FastVideo, so it can't read FastVideo
-env vars directly. Two options:
-
-**Option 1: Inline patch** in your local clone of the upstream repo. Add
-`register_forward_hook` calls in the same shape as `ActivationStatHook`. Clean
-up afterward with `git stash` or `git checkout HEAD -- <file>`.
-
-**Option 2: Wrapper script**. Write a small Python harness that imports the
-upstream model, walks its `named_modules()`, and attaches hooks externally.
-This is the same pattern used in
-`tests/local_tests/transformers/_debug_magi_human_block_parity.py`.
-
-The `add-model-trace` skill at `~/.config/opencode/skill/add-model-trace/`
-provides a script template for this purpose.
-
-## Future extensions (design only, not yet implemented)
-
-### Extension 1: FX/Dynamo backend graph rewrite
-
-**Granularity**: per-FX-node (every matmul, every add).
-
-**Mechanism**: a `torch.compile` backend that takes the captured `GraphModule`
-and inserts logger nodes after each op. Compiles into a separate artifact from
-the production graph.
-
-**Off semantics**: zero overhead. The production compile path is untouched.
-
-**When to add**: if you need to trace inside a `torch.compile`'d graph and
-Extension 0 is too coarse.
-
-**Build cost**: roughly 1-2 days. Reference:
-`torchao.quantization.pt2e._numeric_debugger`.
-
-### Extension 2: AST source injection at import time
-
-**Granularity**: per-line (between any two Python statements).
-
-**Mechanism**: an importlib loader hook rewrites Python source AST at module
-import time, inserting `if TRACE: dump(...)` statements. The decision is made
-once at import.
-
-**Off semantics**: zero overhead. If the env var is off at import time, source
-is loaded as-is.
-
-**When to add**: if you need per-line granularity that even FX-node-level can't
-provide. This is almost never the right choice.
-
-**Build cost**: roughly 1 week. Brittle and hard to debug.
-
-### Extension 3: `__torch_dispatch__` / `TorchDispatchMode`
-
-**Granularity**: per-op (every dispatcher call: matmul, add, view, etc.).
-
-**Mechanism**: a `TorchDispatchMode` context manager that intercepts all ops at
-the dispatcher level.
-
-**Off semantics**: zero overhead. PyTorch's dispatcher only invokes mode hooks
-when a mode is active.
-
-**When on**: significant overhead. Every op pays a Python callback cost. Triton
-kernels bypass it.
-
-**When to add**: useful for quantization or dtype debugging where module-level
-granularity isn't enough.
-
-**Build cost**: roughly 1 day. Reference:
-`torch.utils._python_dispatch.TorchDispatchMode`.
-
-## Comparison with similar tools
-
-| Tool | Pattern | FastVideo equivalent |
-|---|---|---|
-| SGLang `--debug-tensor-dump-output-folder` | env-gated forward hooks at startup | Extension 0 (this) |
-| TransformerEngine `DumpTensors` | config-driven selective dumps | Extension 0 (env-driven) |
-| HuggingFace `output_hidden_states=True` | source-level boolean gating | Not used; Extension 0 avoids model code edits |
-| torchao numeric debugger | FX pass + node-level loggers | Extension 1 (future) |
-| W&B `wandb.watch()` | runtime forward hooks (always on once registered) | Extension 0 has a similar mechanism, but gated off by default |
-
-## Implementation references
-
- Module: `fastvideo/hooks/activation_trace.py`
- Env vars: `fastvideo/envs.py` (`FASTVIDEO_TRACE_ACTIVATIONS` and friends)
- Pipeline integration: `fastvideo/pipelines/composed_pipeline_base.py`
- Tests: `fastvideo/tests/hooks/test_activation_trace.py`
- Companion skill (for ad-hoc port investigations): `~/.config/opencode/skill/add-model-trace/`
-
-## Changelog
-
-| Date | Change |
-|---|---|
-| 2026-05-01 | Initial Extension 0 (module forward hooks) implementation. Extensions 1-3 designed but not implemented. |
@@ -296,10 +296,8 @@ Action:

 - Add or reuse a numerical parity test that loads the official model and the
  FastVideo model and compares outputs.
- See examples in `tests/local_tests/` organized by model family
-  (e.g., `tests/local_tests/sd35/`, `tests/local_tests/ltx2/`,
-  `tests/local_tests/stable_audio/`) and the navigation index in
-  `tests/local_tests/README.md`.
+- See examples in `tests/local_tests/` (e.g., `tests/local_tests/upsamplers/`)
+  and the commands in `tests/local_tests/README.md`.
 - If there are discrepancies, add opt‑in logging to both models and compare
  activation summaries (layer output sums, per‑stage logs).
 - First align the loaded weights (validate `param_names_mapping`).
@@ -350,8 +348,7 @@ Purpose:

 Action:

- Add a pipeline parity test under `tests/local_tests/<family>/`
-  (e.g., `tests/local_tests/<family>/test_<family>_pipeline_parity.py`).
+- Add a pipeline parity test under `tests/local_tests/pipelines/`.
 - See the [Testing Guide](testing.md) for test conventions.

 ### 7) Add user‑facing examples
@@ -99,7 +99,7 @@ cd /FastVideo
 **Install the package**

 ```bash
-uv pip install -e ".[dev]"
+uv pip install -e .[dev]
 ```

 The Docker image already includes Flash Attention and most heavy dependencies, so this is fast.
@@ -49,7 +49,7 @@ git clone https://github.com/hao-ai-lab/FastVideo.git && cd FastVideo
 Install FastVideo in editable mode and set up hooks:

 ```bash
-uv pip install -e ".[dev]"
+uv pip install -e .[dev]

 # Optional: FlashAttention (builds native kernels)
 uv pip install flash-attn --no-build-isolation -v
@@ -306,30 +306,6 @@ surfaces:
        sources: [fastvideo.configs.pipelines.wan.MatrixGameI2V480PConfig]
      num_frames_per_block:
        sources: [fastvideo.configs.pipelines.wan.MatrixGameI2V480PConfig]
-      audio_channels:
-        sources:
-          - fastvideo.configs.pipelines.stable_audio.StableAudioT2AConfig
-          - fastvideo.configs.pipelines.stable_audio.StableAudioOpenSmallConfig
-      audio_end_in_s:
-        sources:
-          - fastvideo.configs.pipelines.stable_audio.StableAudioT2AConfig
-          - fastvideo.configs.pipelines.stable_audio.StableAudioOpenSmallConfig
-      audio_start_in_s:
-        sources:
-          - fastvideo.configs.pipelines.stable_audio.StableAudioT2AConfig
-          - fastvideo.configs.pipelines.stable_audio.StableAudioOpenSmallConfig
-      max_audio_duration_s:
-        sources:
-          - fastvideo.configs.pipelines.stable_audio.StableAudioT2AConfig
-          - fastvideo.configs.pipelines.stable_audio.StableAudioOpenSmallConfig
-      sample_size:
-        sources:
-          - fastvideo.configs.pipelines.stable_audio.StableAudioT2AConfig
-          - fastvideo.configs.pipelines.stable_audio.StableAudioOpenSmallConfig
-      sampling_rate:
-        sources:
-          - fastvideo.configs.pipelines.stable_audio.StableAudioT2AConfig
-          - fastvideo.configs.pipelines.stable_audio.StableAudioOpenSmallConfig
    compatibility_only:
      batch_size: "Gen3C inference-only tuning field pending typed batching design."
      gradient_checkpointing: "Gen3C inference-only compatibility field pending typed batching design."
@@ -378,8 +354,6 @@ surfaces:
      return_frames: request.output.return_frames
      return_trajectory_latents: request.runtime.return_trajectory_latents
      return_trajectory_decoded: request.runtime.return_trajectory_decoded
-      continuation_state: request.state
-      return_continuation_state: request.output.return_state
    preset_owned:
      t_thresh: request.stage_overrides.refine.t_thresh
      spatial_refine_only: request.stage_overrides.refine.spatial_refine_only
@@ -404,13 +378,6 @@ surfaces:
      ltx2_stg_scale_audio: request.extensions.ltx2.stg_scale_audio
      ltx2_stg_blocks_video: request.extensions.ltx2.stg_blocks_video
      ltx2_stg_blocks_audio: request.extensions.ltx2.stg_blocks_audio
-      audio_start_in_s: request.extensions.stable_audio.audio_start_in_s
-      audio_end_in_s: request.extensions.stable_audio.audio_end_in_s
-      init_audio: request.extensions.stable_audio.init_audio
-      init_audio_strength: request.extensions.stable_audio.init_audio_strength
-      init_noise_level: request.extensions.stable_audio.init_noise_level
-      inpaint_audio: request.extensions.stable_audio.inpaint_audio
-      inpaint_mask: request.extensions.stable_audio.inpaint_mask
    internal_only:
      data_type: "Derived from the request shape and not a public input."

@@ -1,177 +0,0 @@
-# Streaming WebSocket Server Contract
-
-The streaming server (`fastvideo/entrypoints/streaming/server.py`) speaks
-a JSON-over-WebSocket protocol with binary fMP4 chunks for media. This
-document is the authoritative spec for the message catalogue and the
-session state machine. Any change to either must update this document
-in the same PR that touches `protocol.py` or `session.py`.
-
-## Endpoint
-
-| Path | Protocol | Purpose |
-|---|---|---|
-| `WS /v1/stream` | WebSocket (JSON + binary) | Per-session realtime streaming |
-| `GET /health` | HTTP | Liveness probe (`status`, `stream_mode`, active `sessions`) |
-
-The server is launched by `fastvideo serve --config <serve.yaml>` when
-the config carries a `streaming:` block. Without that block the same CLI
-launches the OpenAI stateless HTTP server instead.
-
-## Connection lifecycle
-
-Every WebSocket connection holds exactly one `Session`. Sessions move
-through the states in `SessionState` (`fastvideo/entrypoints/streaming/session.py`).
-
-```
-                    ┌──────────────┐
-                    │ INITIALIZING │  ← WebSocket accepted, before init frame
-                    └──────┬───────┘
-                           │ session_init_v2 received
-            ┌──────────────┼──────────────┐
-            ▼              ▼              ▼
-         QUEUED      GPU_BINDING       REJECTED
-            │              │              ↑
-            │ slot ready   │              │ max-sessions hit
-            ▼              ▼              │ or invalid init
-                       ┌────────┐         │
-                       │ ACTIVE │ ────────┘
-                       └────┬───┘
-              segment loop  │
-                            │
-                ┌───────────┼───────────┐
-                ▼           ▼           ▼
-            COMPLETE      ERROR      TIMEOUT
-        (clean leave)  (any failure)  (idle / segment_cap reached)
-```
-
-Terminal states (`COMPLETE`, `ERROR`, `TIMEOUT`, `REJECTED`) are sinks —
-no transitions out. The transition matrix is enforced in
-`session.py::_VALID_TRANSITIONS`; bad transitions raise.
-
-`SessionManager` enforces the per-process budgets pulled from
-`StreamingConfig`:
-
- `session_timeout_seconds` — idle reaper drops sessions that haven't
-  advanced; non-terminal sessions transition to `TIMEOUT`.
- `generation_segment_cap` — a session that hits the cap transitions to
-  `COMPLETE` after the last segment ships.
-
-## Message catalogue
-
-Every JSON frame carries `{"type": <str>, ...}`. Pydantic models in
-`protocol.py` are the source of truth; this table is the human-readable
-view.
-
-### Client → server
-
-| `type` | Required fields | Purpose |
-|---|---|---|
-| `session_init_v2` | — | Opening frame. Carries preset, curated prompts, optional initial image, feature toggles, optional `continuation_state` to resume from a snapshot. |
-| `segment_prompt_source` | `prompt` | Request the next segment using the supplied prompt; optional sampling overrides (`seed`, `num_inference_steps`, `guidance_scale`, `negative_prompt`). |
-| `seed_prompts_updated` | `seed_prompts` | Replace the session's seed-prompt list; takes effect on the next segment. |
-| `enhancement_updated` | `enabled` | Toggle prompt enhancement for subsequent segments. |
-| `auto_extension_updated` | `enabled` | Toggle automatic per-segment prompt extension. |
-| `loop_generation_updated` | `enabled` | Toggle loop-generation mode. |
-| `generation_paused_updated` | `paused` | Pause/resume segment generation; queued requests defer. |
-| `snapshot_state` | — | Request the current `ContinuationState` for export; server replies with `continuation_state_snapshot`. |
-
-The opening frame must be `session_init_v2`. Any other first frame is
-rejected with an `error` (code `invalid_message`) and the WebSocket is
-closed.
-
-### Server → client
-
-| `type` | Carries | When emitted |
-|---|---|---|
-| `queue_status` | `position`, `queue_depth` | After `session_init_v2` accepted, before GPU binding. |
-| `gpu_assigned` | GPU id, model id | Once a generator slot is bound. |
-| `ltx2_stream_start` | session-level metadata | Once the session enters `ACTIVE`. |
-| `ltx2_segment_start` | `segment_idx`, `prompt`, prompt source | When a `segment_prompt_source` request begins generation. |
-| `step_complete` | `segment_idx`, denoise timings | After the segment's denoising loop finishes (before media emission). |
-| `media_init` | `segment_idx`, mime, stream id | First frame of fMP4 output for the segment. |
-| binary frame | fMP4 fragment bytes | Subsequent media chunks; the protocol enforces that `media_init` precedes any binary frames. |
-| `media_segment_complete` | `segment_idx`, chunk count, byte count | Last media chunk for the segment. |
-| `ltx2_segment_complete` | `segment_idx`, segment summary | Segment fully shipped; ready for the next `segment_prompt_source`. |
-| `ltx2_stream_complete` | session summary | Session reached `generation_segment_cap` or client requested clean shutdown. |
-| `session_timeout` | reason | Session hit `session_timeout_seconds`; immediately followed by close. |
-| `continuation_state_snapshot` | `kind`, `payload` | Reply to `snapshot_state`. The payload is the same shape produced by `LTX2ContinuationState.to_continuation_state(...)`. |
-| `error` | `code`, `message` | Any validation/runtime error. Non-fatal errors keep the connection open; fatal errors precede a `close`. |
-
-## Continuation state
-
-The session optionally accepts a `continuation_state` dict inside the
-opening `session_init_v2` frame. When present, the server hydrates it
-into a `ContinuationState(kind, payload)` envelope and feeds it as the
-`request.state` on the first segment's `GenerationRequest` — letting a
-client resume after a disconnect, migrate sessions across processes,
-or replay a prior session.
-
-After every segment, if the runtime returns a fresh state, the server
-persists it to the `SessionStore` so a `snapshot_state` request can
-export it. The store and serialization contracts live with the model
-family (e.g. `fastvideo/pipelines/basic/ltx2/continuation.py` for LTX-2).
-
-## Example flow
-
-```
-client                                                    server
-──────                                                    ──────
-WS /v1/stream  ─────── connect ─────────────────────────►
-               ◄────── (accept)
-
-{"type": "session_init_v2",
- "preset": "ltx2_two_stage",
- "curated_prompts": ["a fox in snow", "the fox jumps"],
- "initial_image": {...},
- "stream_mode": "av_fmp4"} ─────────────────────────────►
-
-                                                          (validate, queue, bind)
-               ◄──── {"type": "queue_status",
-                       "position": 0, "queue_depth": 0}
-               ◄──── {"type": "gpu_assigned",
-                       "gpu_id": 0, "model_id": "..."}
-               ◄──── {"type": "ltx2_stream_start", ...}
-
-{"type": "segment_prompt_source",
- "prompt": "a fox in snow",
- "source": "curated"} ───────────────────────────────────►
-                                                          (run pipeline)
-               ◄──── {"type": "ltx2_segment_start",
-                       "segment_idx": 1, ...}
-               ◄──── {"type": "step_complete",
-                       "segment_idx": 1, "timings": {...}}
-               ◄──── {"type": "media_init",
-                       "segment_idx": 1,
-                       "mime": "video/mp4", ...}
-               ◄──── <binary fMP4 init segment>
-               ◄──── <binary fMP4 fragment>
-               ◄──── <binary fMP4 fragment>
-               ◄──── {"type": "media_segment_complete",
-                       "segment_idx": 1, "chunks": 12}
-               ◄──── {"type": "ltx2_segment_complete",
-                       "segment_idx": 1, ...}
-
-{"type": "segment_prompt_source",
- "prompt": "the fox jumps"} ─────────────────────────────►
-                                                          (segment 2 …)
-
-{"type": "snapshot_state"} ──────────────────────────────►
-               ◄──── {"type": "continuation_state_snapshot",
-                       "kind": "ltx2.v1",
-                       "payload": {"schema_version": 1, ...}}
-
-(close) ──────────────────────────────────────────────────►
-                                                          (session → COMPLETE)
-```
-
-## Backward / forward compatibility
-
- Adding a new client message: append a Pydantic model to `protocol.py`
-  with a unique `type`; add the discriminator entry to `ClientMessage`;
-  add a row to the table above. Old clients that don't send the new
-  message remain compatible.
- Adding a new server message: emit only when a new feature flag is
-  enabled (or always emit, since clients ignore unknown types).
- Changing an existing message: bump the `type` (e.g. `session_init_v2`
-  → `session_init_v3`) and accept both for one release cycle. Never
-  silently change field semantics under the same `type`.
@@ -243,7 +243,7 @@ for step in range(start_step, max_steps):

 ```bash
 # Install
-uv pip install -e ".[dev]"
+uv pip install -e .[dev]

 # Run DMD2 distillation on Wan 2.1
 torchrun --nproc_per_node=8 -m fastvideo.train.entrypoint.train \
@@ -86,25 +86,3 @@ sbatch examples/distill/Wan2.2-TI2V-5B-Diffusers/Data-free/distill_dmd_t2v_5B.sh
 - Learning rate: 2e-5
 - Training steps: 3000 (~12 hours)
 - HSDP shard dim: 1
-
-## 🧭 Note on `real_score_guidance_scale`
-
-The teacher CFG used inside the DMD loss follows the DMD2 reference
-implementation and uses the parameterization
-
-```
-x = x_cond + w * (x_cond - x_uncond)
-```
-
-rather than the Ho & Salimans form `x_uncond + w * (x_cond - x_uncond)`. The
-two are mathematically equivalent up to a constant offset:
-
-| `real_score_guidance_scale` (`w`) | Equivalent standard CFG (`w + 1`) | Output                |
-|-----------------------------------|-----------------------------------|-----------------------|
-| `-1`                              | `0`                               | unconditional         |
-| `0`                               | `1`                               | conditional           |
-| `3.5` (default)                   | `4.5`                             | strong guidance       |
-
-So `real_score_guidance_scale` should be read as the **extra** guidance
-strength added on top of the conditional prediction. When porting values
-from a paper that uses the Ho & Salimans form, subtract 1.
@@ -27,7 +27,7 @@ uv pip install fastvideo
 conda create -n fastvideo python=3.12 -y
 conda activate fastvideo

-uv pip install fastvideo
+pip install fastvideo
 ```

 ### From source
@@ -41,11 +41,11 @@ uv pip install -e .
 uv pip install flash-attn --no-build-isolation -v
 ```

-Alternative with Conda environment (still drives installs through `uv`):
+Alternative with Conda environment:

 ```bash
-uv pip install -e .
-uv pip install flash-attn --no-build-isolation -v
+pip install -e .
+pip install flash-attn --no-build-isolation -v
 ```

 ## Hardware Requirements
@@ -58,16 +58,14 @@ uv pip install flash-attn --no-build-isolation -v

 #### With Conda environment (alternative)

-`uv` works inside an active conda env too, so prefer `uv pip` for the actual install:
-
 ```bash
-uv pip install fastvideo
+pip install fastvideo
 ```

 Also optionally install FlashAttention:

 ```bash
-uv pip install flash-attn --no-build-isolation -v
+pip install flash-attn --no-build-isolation -v
 ```

 ### Installation from Source
@@ -89,7 +87,7 @@ uv pip install -e .
 Alternative with Conda environment:

 ```bash
-uv pip install -e .
+pip install -e .
 ```

 ### Optional Dependencies
@@ -103,7 +101,7 @@ uv pip install flash-attn --no-build-isolation -v
 Alternative with Conda environment:

 ```bash
-uv pip install flash-attn --no-build-isolation -v
+pip install flash-attn --no-build-isolation -v
 ```

 ## Set up using Docker
@@ -57,10 +57,8 @@ uv pip install fastvideo

 #### With Conda environment (alternative)

-`uv` works inside an active conda env too, so prefer `uv pip` for the actual install:
-
 ```bash
-uv pip install fastvideo
+pip install fastvideo
 ```

 ### Installation from Source
@@ -82,7 +80,7 @@ uv pip install -e .
 Alternative with Conda environment:

 ```bash
-uv pip install -e .
+pip install -e .
 ```

 ## Development Environment Setup
@@ -19,7 +19,7 @@
 - Install MoGe:

 ```bash
-uv pip install git+https://github.com/microsoft/MoGe.git
+pip install git+https://github.com/microsoft/MoGe.git
 ```

 - If you hit `ImportError: libGL.so.1` (common on Ubuntu/headless nodes), you can try installing OpenCV runtime libs:
@@ -54,7 +54,7 @@ FASTVIDEO_ATTENTION_BACKEND=SAGE_ATTN python example.py
 We recommend always installing [Flash Attention 2](https://github.com/Dao-AILab/flash-attention):

 ```bash
-uv pip install flash-attn==2.7.4.post1 --no-build-isolation
+pip install flash-attn==2.7.4.post1 --no-build-isolation
 ```

 And if using a Hopper+ GPU (ie H100), installing [Flash Attention 3](https://github.com/Dao-AILab/flash-attention?tab=readme-ov-file#flashattention-3-beta-release) by compiling it from source (takes about 10 minutes for me):
@@ -63,7 +63,7 @@ And if using a Hopper+ GPU (ie H100), installing [Flash Attention 3](https://git
 git clone https://github.com/Dao-AILab/flash-attention.git && cd flash-attention

 cd hopper
-uv pip install ninja
+pip install ninja
 python setup.py install
 ```

@@ -98,7 +98,7 @@ To use [SageAttention](https://github.com/thu-ml/SageAttention) 2.1.1, please co
 ```bash
 git clone https://github.com/thu-ml/SageAttention.git
 cd sageattention
-python setup.py install  # or uv pip install -e .
+python setup.py install  # or pip install -e .
 ```

 ### Sage Attention 3
@@ -4,7 +4,7 @@ These are end-to-end example scripts for distilling Wan2.1 T2V 1.3B model using
 ### 0. Make sure you have installed VSA

 ```bash
-uv pip install vsa
+pip install vsa
 ```

 ### 1. Download dataset:
@@ -4,7 +4,7 @@ These are end-to-end example scripts for distilling Wan2.2 TI2V 5B model DMD+VSA
 ### 0. Make sure you have installed VSA

 ```bash
-uv pip install vsa
+pip install vsa
 ```

 ### Data-free Distillation
@@ -4,7 +4,7 @@ These are end-to-end example scripts for distilling Wan2.2 TI2V 5B model DMD+VSA
 ### 0. Make sure you have installed VSA

 ```bash
-uv pip install vsa
+pip install vsa
 ```

 ### 1. Download dataset:
@@ -7,7 +7,7 @@ and the GEN3C diffusion model.

 Requirements:
  1. Install MoGe:
-     uv pip install git+https://github.com/microsoft/MoGe.git
+     pip install git+https://github.com/microsoft/MoGe.git
     If you hit `ImportError: libGL.so.1`, install:
     sudo apt-get update && sudo apt-get install -y libgl1 libglib2.0-0 libsm6 libxext6 libxrender1
  2. Download and convert weights:
@@ -1,51 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-"""Minimal user-runnable example for the daVinci-MagiHuman base AV pipeline.
-
-Produces an mp4 with both video (Wan 2.2 TI2V-5B VAE) and audio (Stable
-Audio Open 1.0 VAE, first-class FastVideo port in
-`fastvideo/models/vaes/oobleck.py`) muxed together via PyAV.
-
-Prerequisites (one-off):
-
-  # Accept terms of use on the gated HF repos with your HF_TOKEN:
-  #   - https://huggingface.co/google/t5gemma-9b-9b-ul2
-  #   - https://huggingface.co/stabilityai/stable-audio-open-1.0
-  # All four cross-variant shared components (Wan 2.2 VAE, T5-Gemma
-  # encoder + tokenizer, Stable Audio VAE) are lazy-loaded from their
-  # canonical upstream HF repos on first build, so a single ~25 GB
-  # cache is shared across every MagiHuman variant.
-
-The umbrella HF repo `FastVideo/MagiHuman-Diffusers` holds all four
-variants (base / distill / sr_540p / sr_1080p) under sibling subfolders
-and FastVideo will download just the requested subfolder. Local
-conversion via `scripts/checkpoint_conversion/convert_magi_human_to_diffusers.py`
-is also supported.
-"""
-from fastvideo import VideoGenerator
-
-
-PROMPT = (
-    "A warm afternoon scene: a person sits on a park bench reading a book, "
-    "surrounded by softly swaying trees."
-)
-
-
-def main() -> None:
-    generator = VideoGenerator.from_pretrained(
-        "FastVideo/MagiHuman-Diffusers/base",
-        num_gpus=1,
-    )
-    output_path = "outputs_video/magi_human_basic/output_magi_human.mp4"
-    generator.generate_video(
-        prompt=PROMPT,
-        output_path=output_path,
-        save_video=True,
-        # Defaults pulled from the registered preset (magi_human_base):
-        # height=256, width=448, fps=25, num_inference_steps=32, seed=42.
-        # Override here only if you have a specific QA scenario.
-    )
-    generator.shutdown()
-
-
-if __name__ == "__main__":
-    main()
@@ -1,53 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-"""Minimal user-runnable example for the daVinci-MagiHuman DMD-2 distilled
-text-to-AV pipeline.
-
-Same arch as the base model (`basic_magi_human.py`) but with DMD-2 distilled
-weights: 8 denoising steps, no classifier-free guidance. ~4x faster than
-base at the same 256x480 resolution. Mirrors upstream
-`daVinci-MagiHuman/example/distill/run_T2V.sh`.
-
-Prerequisites (one-off):
-
-  # 1) Accept terms on the gated HF repos with your HF_TOKEN:
-  #    - https://huggingface.co/google/t5gemma-9b-9b-ul2
-  #    - https://huggingface.co/stabilityai/stable-audio-open-1.0
-  #    Cross-variant shared components (Wan 2.2 VAE + T5-Gemma + Stable
-  #    Audio VAE) are lazy-loaded from their canonical upstream HF repos
-  #    and shared with the base variant cache.
-  # 2) Convert the distill subfolder of GAIR/daVinci-MagiHuman:
-  python scripts/checkpoint_conversion/convert_magi_human_to_diffusers.py \\
-      --source GAIR/daVinci-MagiHuman \\
-      --subfolder distill \\
-      --output converted_weights/magi_human_distill \\
-      --cast-bf16
-  # `--cast-bf16` is recommended (61 GB fp32 -> 30 GB bf16); the FV pipeline
-  # loads bf16 anyway, and the conversion keeps norms / RoPE bands fp32.
-"""
-from fastvideo import VideoGenerator
-
-
-PROMPT = (
-    "A warm afternoon scene: a person sits on a park bench reading a book, "
-    "surrounded by softly swaying trees."
-)
-
-
-def main() -> None:
-    generator = VideoGenerator.from_pretrained(
-        "FastVideo/MagiHuman-Diffusers/distill",
-        num_gpus=1,
-    )
-    output_path = "outputs_video/magi_human_basic/output_magi_human_distill.mp4"
-    generator.generate_video(
-        prompt=PROMPT,
-        output_path=output_path,
-        save_video=True,
-        # Defaults pulled from the registered preset (magi_human_distill):
-        # height=256, width=480, fps=25, num_inference_steps=8, cfg=1, seed=42.
-    )
-    generator.shutdown()
-
-
-if __name__ == "__main__":
-    main()
@@ -1,34 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-"""Minimal daVinci-MagiHuman DMD-2 distilled text+image-to-AV example."""
-from fastvideo import VideoGenerator
-from fastvideo.pipelines.basic.magi_human.pipeline_configs import (
-    MagiHumanDistillI2VConfig,
-)
-
-
-PROMPT = (
-    "A cheerful saxophonist performs a short line with expressive facial "
-    "motion, natural head movement, and synchronized audio in a small jazz club."
-)
-IMAGE_PATH = "assets/images/saxophonist.jpg"
-
-
-def main() -> None:
-    generator = VideoGenerator.from_pretrained(
-        "FastVideo/MagiHuman-Diffusers/distill",
-        num_gpus=1,
-        workload_type="i2v",
-        override_pipeline_cls_name="MagiHumanI2VPipeline",
-        pipeline_config=MagiHumanDistillI2VConfig(),
-    )
-    generator.generate_video(
-        prompt=PROMPT,
-        image_path=IMAGE_PATH,
-        output_path="outputs_video/magi_human_distill_ti2v/output_magi_human_distill_ti2v.mp4",
-        save_video=True,
-    )
-    generator.shutdown()
-
-
-if __name__ == "__main__":
-    main()
@@ -1,45 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-"""Run daVinci-MagiHuman SR-1080p text-to-AV in FastVideo.
-
-Build the converted repo on large local storage, then symlink it into the
-workspace:
-
-    python scripts/checkpoint_conversion/convert_magi_human_to_diffusers.py \
-        --source GAIR/daVinci-MagiHuman \
-        --subfolder base \
-        --sr-source GAIR/daVinci-MagiHuman \
-        --sr-subfolder 1080p_sr \
-        --output /raid/william5lin_converted_weights/magi_human_sr_1080p \
-        --cast-bf16
-    ln -s /raid/william5lin_converted_weights/magi_human_sr_1080p \
-        converted_weights/magi_human_sr_1080p
-"""
-from fastvideo import VideoGenerator
-from fastvideo.pipelines.basic.magi_human.pipeline_configs import (
-    MagiHumanSR1080pConfig,
-)
-
-
-PROMPT = (
-    "A warm afternoon scene: a person sits on a park bench reading a book, "
-    "surrounded by softly swaying trees."
-)
-
-
-def main() -> None:
-    generator = VideoGenerator.from_pretrained(
-        "FastVideo/MagiHuman-Diffusers/sr_1080p",
-        num_gpus=1,
-        override_pipeline_cls_name="MagiHumanSR1080pPipeline",
-        pipeline_config=MagiHumanSR1080pConfig(),
-    )
-    generator.generate_video(
-        prompt=PROMPT,
-        output_path="outputs_video/magi_human_sr1080p/output_magi_human_sr1080p.mp4",
-        save_video=True,
-    )
-    generator.shutdown()
-
-
-if __name__ == "__main__":
-    main()
@@ -1,34 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-"""Run daVinci-MagiHuman SR-1080p text+image-to-AV in FastVideo."""
-from fastvideo import VideoGenerator
-from fastvideo.pipelines.basic.magi_human.pipeline_configs import (
-    MagiHumanSR1080pI2VConfig,
-)
-
-
-PROMPT = (
-    "A cheerful saxophonist performs a short line with expressive facial "
-    "motion, natural head movement, and synchronized audio in a small jazz club."
-)
-IMAGE_PATH = "assets/images/saxophonist.jpg"
-
-
-def main() -> None:
-    generator = VideoGenerator.from_pretrained(
-        "FastVideo/MagiHuman-Diffusers/sr_1080p",
-        num_gpus=1,
-        workload_type="i2v",
-        override_pipeline_cls_name="MagiHumanSR1080pI2VPipeline",
-        pipeline_config=MagiHumanSR1080pI2VConfig(),
-    )
-    generator.generate_video(
-        prompt=PROMPT,
-        image_path=IMAGE_PATH,
-        output_path="outputs_video/magi_human_sr1080p_ti2v/output_magi_human_sr1080p_ti2v.mp4",
-        save_video=True,
-    )
-    generator.shutdown()
-
-
-if __name__ == "__main__":
-    main()
@@ -1,37 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-"""Run daVinci-MagiHuman SR-540p text-to-AV in FastVideo.
-
-The converted repo must contain both ``transformer/`` (base DiT) and
-``sr_transformer/`` (540p SR DiT). Build it with:
-
-    python scripts/checkpoint_conversion/convert_magi_human_to_diffusers.py \
-        --source GAIR/daVinci-MagiHuman \
-        --subfolder base \
-        --sr-source GAIR/daVinci-MagiHuman \
-        --sr-subfolder 540p_sr \
-        --output converted_weights/magi_human_sr_540p
-"""
-from fastvideo import VideoGenerator
-
-
-PROMPT = (
-    "A warm afternoon scene: a person sits on a park bench reading a book, "
-    "surrounded by softly swaying trees."
-)
-
-
-def main() -> None:
-    generator = VideoGenerator.from_pretrained(
-        "FastVideo/MagiHuman-Diffusers/sr_540p",
-        num_gpus=1,
-    )
-    generator.generate_video(
-        prompt=PROMPT,
-        output_path="outputs_video/magi_human_sr540p/output_magi_human_sr540p.mp4",
-        save_video=True,
-    )
-    generator.shutdown()
-
-
-if __name__ == "__main__":
-    main()
@@ -1,34 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-"""Run daVinci-MagiHuman SR-540p text+image-to-AV in FastVideo."""
-from fastvideo import VideoGenerator
-from fastvideo.pipelines.basic.magi_human.pipeline_configs import (
-    MagiHumanSR540pI2VConfig,
-)
-
-
-PROMPT = (
-    "A cheerful saxophonist performs a short line with expressive facial "
-    "motion, natural head movement, and synchronized audio in a small jazz club."
-)
-IMAGE_PATH = "assets/images/saxophonist.jpg"
-
-
-def main() -> None:
-    generator = VideoGenerator.from_pretrained(
-        "FastVideo/MagiHuman-Diffusers/sr_540p",
-        num_gpus=1,
-        workload_type="i2v",
-        override_pipeline_cls_name="MagiHumanSRI2VPipeline",
-        pipeline_config=MagiHumanSR540pI2VConfig(),
-    )
-    generator.generate_video(
-        prompt=PROMPT,
-        image_path=IMAGE_PATH,
-        output_path="outputs_video/magi_human_sr540p_ti2v/output_magi_human_sr540p_ti2v.mp4",
-        save_video=True,
-    )
-    generator.shutdown()
-
-
-if __name__ == "__main__":
-    main()
@@ -1,34 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-"""Minimal daVinci-MagiHuman base text+image-to-AV example."""
-from fastvideo import VideoGenerator
-from fastvideo.pipelines.basic.magi_human.pipeline_configs import (
-    MagiHumanBaseI2VConfig,
-)
-
-
-PROMPT = (
-    "A cheerful saxophonist performs a short line with expressive facial "
-    "motion, natural head movement, and synchronized audio in a small jazz club."
-)
-IMAGE_PATH = "assets/images/saxophonist.jpg"
-
-
-def main() -> None:
-    generator = VideoGenerator.from_pretrained(
-        "FastVideo/MagiHuman-Diffusers/base",
-        num_gpus=1,
-        workload_type="i2v",
-        override_pipeline_cls_name="MagiHumanI2VPipeline",
-        pipeline_config=MagiHumanBaseI2VConfig(),
-    )
-    generator.generate_video(
-        prompt=PROMPT,
-        image_path=IMAGE_PATH,
-        output_path="outputs_video/magi_human_ti2v/output_magi_human_ti2v.mp4",
-        save_video=True,
-    )
-    generator.shutdown()
-
-
-if __name__ == "__main__":
-    main()
@@ -1,77 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-"""Stable Audio Open 1.0 — text-to-audio (baseline) example.
-
-User story (game-audio designer, prototyping):
-    "I'm prototyping a level and I need 6 seconds of background
-    ambience — gentle wind, distant thunder, a hint of birdsong. I
-    don't want to dig through a sound library; I want to type what I
-    hear in my head and get a wav back. If it's wrong I'll iterate
-    on the prompt. This is the first stop."
-
-User story (musician sketching ideas):
-    "I want to bounce a 30s lo-fi drum loop to use as a placeholder
-    bed while I build the rest of the track. Type prompt, get audio,
-    drop into the DAW. The actual production beat I'll record
-    myself, but I need *something* to write the chords against."
-
-User story (researcher exploring the model):
-    "First time touching Stable Audio Open — what does it sound
-    like at default settings? This is the smallest amount of code
-    that goes from prompt to mp4."
-
-How it works:
-    Pure text-to-audio (T2A). The pipeline runs:
-        T5 + NumberConditioner -> StableAudioDiT -> Oobleck VAE
-    via the `dpmpp-3m-sde` k-diffusion sampler. All components are
-    FastVideo-native — no diffusers / transformers model imports at
-    runtime (see REVIEW item 30). Mirrors upstream
-    `stable_audio_tools.inference.generation.generate_diffusion_cond`
-    bit-for-bit (~0.2% abs_mean drift on 25 steps).
-
-Tunable knobs (the "creative dials"):
-    audio_end_in_s
-        1–6   — quick ideation (sub-10s wall clock at 100 steps)
-        10–30 — full musical phrase / loop length (the README example
-                uses 30s)
-        47.5  — model maximum (full sample_size = 2097152 / 44100 Hz)
-    num_inference_steps
-        25  — fast preview, occasional artifacts
-        100 — preset default (matches the HF model card)
-        250 — diminishing returns past here
-    guidance_scale
-        3   — looser, more variation per seed
-        7   — preset default; matches README
-        12+ — sharper but can sound "fried"
-
-Prerequisites:
-  1. Accept the terms on https://huggingface.co/stabilityai/stable-audio-open-1.0
-     and export your HF token in the shell:
-         export HF_TOKEN=hf_...
-  2. Install optional inference deps (one-time):
-         uv pip install k_diffusion einops_exts alias_free_torch torchsde
-"""
-from fastvideo import VideoGenerator
-
-PROMPT = "Lo-fi hip hop instrumental with vinyl crackle and gentle piano."
-
-
-def main() -> None:
-    generator = VideoGenerator.from_pretrained(
-        "FastVideo/stable-audio-open-1.0-Diffusers",
-        num_gpus=1,
-    )
-    output_path = "outputs_audio/stable_audio_basic/output_stable_audio.wav"
-    generator.generate_video(
-        prompt=PROMPT,
-        output_path=output_path,
-        save_video=True,
-        # 6-second clip; the model max is ~47.5s.
-        audio_end_in_s=6.0,
-        # The registered preset gives 100 steps + CFG=7.0 by default;
-        # override num_inference_steps / guidance_scale here for QA.
-    )
-    generator.shutdown()
-
-
-if __name__ == "__main__":
-    main()
@@ -1,77 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-"""Stable Audio Open 1.0 — audio-to-audio variation example.
-
-User story (musician, late at night):
-    "I generated this 12-second lo-fi loop earlier and I love the chord
-    progression and overall vibe, but the snare hit at 0:08 sounds wrong
-    and the rhythm feels stiff. I don't want to start over from scratch
-    and lose what's working — I want the model to keep the harmony and
-    mood but reroll the percussion + groove."
-
-User story (sound designer, on a deadline):
-    "I have one good 'sword clang' SFX. The art director wants 8 sibling
-    variations that all feel like the same sword from different angles —
-    same metal, same weight, slightly different impact. I'd rather
-    refine my one good take than text-prompt my way through 50 misses."
-
-Pass `init_audio=path/to/clip` (any wav/mp3/mp4/m4a/flac the standard
-deps decode) and the model will use it as a starting point for the
-text prompt instead of pure noise.
-
-Picking `init_audio_strength` (0.0 to 1.0):
-
-    Higher = closer to the source clip. Lower = more transformation.
-    (Same convention as the "Input Audio Strength" slider in
-    Stability's commercial Stable Audio web UI, so values transfer
-    directly.)
-
-      | strength | what you get                                       |
-      |----------|----------------------------------------------------|
-      |   1.00   | Output ≈ reference. No transformation.             |
-      |   0.85   | Texture micro-variation only.                      |
-      |   0.70   | Light reroll, same instruments.                    |
-      |   0.60   | Default. Instrument identity is replaceable        |
-      |          | (cello can take over from piano on the same notes).|
-      |   0.50   | Heavy — only melody / chord progression survives.  |
-      |   0.30   | Reference acts as a loose mood prompt.             |
-      |   0.00   | Plain T2A — reference ignored.                     |
-
-    Rule of thumb by intent:
-      * "Fix one part of this clip"            -> 0.75 .. 0.85
-      * "Same notes, different instrument"     -> 0.55 .. 0.65
-      * "Same chord progression, new content"  -> 0.40 .. 0.55
-      * "Use this as a loose mood prompt"      -> 0.20 .. 0.35
-
-    If the reference timbre is bleeding through more than you want,
-    lower it; if the structure is gone, raise it.
-
-Prerequisites: same as `basic_stable_audio.py`.
-"""
-from fastvideo import VideoGenerator
-
-PROMPT = "Change the piano to a cello playing the same notes"
-# Path to any audio-bearing file (wav, mp3, mp4, m4a, flac, ...).
-# Set to `None` to skip A2A and run plain T2A.
-INIT_AUDIO_PATH: str | None = None
-# Reference fidelity in [0, 1] -- higher = closer to source.
-INIT_AUDIO_STRENGTH = 0.6
-
-
-def main() -> None:
-    generator = VideoGenerator.from_pretrained(
-        "FastVideo/stable-audio-open-1.0-Diffusers",
-        num_gpus=1,
-    )
-    generator.generate_video(
-        prompt=PROMPT,
-        output_path="outputs_audio/stable_audio_a2a/output_a2a.wav",
-        save_video=True,
-        audio_end_in_s=6.0,
-        init_audio=INIT_AUDIO_PATH,
-        init_audio_strength=INIT_AUDIO_STRENGTH,
-    )
-    generator.shutdown()
-
-
-if __name__ == "__main__":
-    main()
@@ -1,84 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-"""Stable Audio Open 1.0 — inpainting / outpainting (loop extension) example.
-
-User story (loop extension — the killer app):
-    "I have a 6-second drum loop my client likes. They want it as
-    background bed for a 30-second ad. I need it to loop seamlessly,
-    but a hard cut every 6s sounds bad. Let me extend it to 30s,
-    keeping the first 6s exactly as-is and letting the model continue
-    the groove for the remaining 24s."
-
-User story (audio repair):
-    "There's a microphone bump at 0:14 in this 30-second field
-    recording — really obvious in headphones. Mask out 0:13 to 0:15
-    and let the model regenerate plausible ambience that blends in.
-    Everything else stays exactly as I recorded it."
-
-User story (transition smoothing):
-    "I have two 10-second clips I want to crossfade. Mask out a 1s
-    overlap region in the middle and let the model invent a coherent
-    transition between the two."
-
-How it works (RePaint-style blending):
-    Stable Audio Open 1.0 wasn't trained as an inpainting model
-    (`model_type=diffusion_cond`, not `diffusion_cond_inpaint`), so we
-    can't use the upstream's mask-conditioned approach directly. We
-    use the RePaint trick instead, which works on any v-prediction
-    diffusion model:
-
-      1. Encode the reference clip into latent space.
-      2. At every denoising step `i`, replace the kept region of the
-         in-flight latent (where mask == 1) with the reference
-         re-noised to the next timestep's sigma. Only the unkept
-         region (mask == 0) is freely denoised.
-      3. After the loop, the kept region is exactly the reference;
-         the unkept region is freshly generated content.
-
-    This is approximate compared to a properly trained inpainting
-    checkpoint — the seam between kept/unkept can have slight EQ
-    discontinuity — but it works on the existing public model.
-
-Tunable: the mask is a 1-D tensor in {0, 1} at the model's sample
-rate. Conventions:
-    1.0 = keep this sample from the reference
-    0.0 = regenerate this sample
-
-Prerequisites: same as `basic_stable_audio.py`.
-"""
-import os
-
-from fastvideo import VideoGenerator
-
-PROMPT = "Steady lo-fi hip hop drum loop with vinyl crackle."
-# Required: path to the reference audio file (wav, mp3, mp4, m4a, flac,
-# ...) you want to extend or repair. The pipeline raises if a mask is
-# passed without a reference, so this must be a real path.
-REFERENCE_AUDIO_PATH = "path/to/your/loop.wav"
-KEEP_SECONDS = 6.0       # first KEEP_SECONDS preserved exactly
-TOTAL_SECONDS = 12.0     # extend the loop to this duration
-
-
-def main() -> None:
-    if not os.path.isfile(REFERENCE_AUDIO_PATH):
-        raise FileNotFoundError(
-            f"REFERENCE_AUDIO_PATH={REFERENCE_AUDIO_PATH!r} does not exist. "
-            "Edit this script to point at a real audio file (wav/mp3/mp4/"
-            "m4a/flac) before running.")
-    generator = VideoGenerator.from_pretrained(
-        "FastVideo/stable-audio-open-1.0-Diffusers",
-        num_gpus=1,
-    )
-    generator.generate_video(
-        prompt=PROMPT,
-        output_path="outputs_audio/stable_audio_inpaint/output_inpaint.wav",
-        save_video=True,
-        audio_end_in_s=TOTAL_SECONDS,
-        inpaint_audio=REFERENCE_AUDIO_PATH,
-        # Tuple form: keep first KEEP_SECONDS, regenerate the rest.
-        inpaint_mask=(KEEP_SECONDS, TOTAL_SECONDS),
-    )
-    generator.shutdown()
-
-
-if __name__ == "__main__":
-    main()
@@ -1,53 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-"""Stable Audio Open Small — fast / lightweight T2A example.
-
-User story (interactive UI builder):
-    "I'm building a sound-design UI where the user types a prompt and
-    we want sub-2-second feedback so the experience feels like
-    autocomplete, not a render queue. The full Stable Audio Open 1.0
-    takes ~8s on a single GPU; the small variant takes a fraction of
-    that — quality is lower but completely usable for real-time
-    iteration."
-
-User story (overnight batch jobs):
-    "I'm generating 10,000 short SFX variants for a procedural game.
-    Wall-clock matters more than per-clip polish — give me the small
-    model so I can fit the run in one night instead of a week."
-
-How it works:
-    The small variant is a separate Stability AI checkpoint
-    (`stabilityai/stable-audio-open-small`) that ships the same Oobleck
-    VAE as the 1.0 base model but a smaller / faster DiT (`embed_dim=1024`,
-    `depth=16`, `qk_norm="ln"`) and only one duration conditioner
-    (`seconds_total`, no `seconds_start`). FastVideo loads from the
-    converted Diffusers-format repo `FastVideo/stable-audio-open-small-Diffusers`
-    via the standard component loader; per-variant arch fields come
-    from `transformer/config.json` and `conditioner/config.json`.
-
-Prerequisites: same as `basic_stable_audio.py`. The converted repo is
-public so no gated-access flow is required.
-"""
-from fastvideo import VideoGenerator
-
-PROMPT = "Lo-fi hip hop instrumental with vinyl crackle and gentle piano."
-
-
-def main() -> None:
-    generator = VideoGenerator.from_pretrained(
-        "FastVideo/stable-audio-open-small-Diffusers",
-        num_gpus=1,
-    )
-    output_path = "outputs_audio/stable_audio_small/output_stable_audio_small.wav"
-    generator.generate_video(
-        prompt=PROMPT,
-        output_path=output_path,
-        save_video=True,
-        # Small variant trains on a ~11.9s window — keep `audio_end_in_s`
-        # at or below that.
-        audio_end_in_s=6.0,
-    )
-    generator.shutdown()
-
-
-if __name__ == "__main__":
-    main()
@@ -1,73 +0,0 @@
-# Cosmos Predict2 2B T2V finetune config.
-#
-# Data must be preprocessed with Cosmos VAE + T5 text encoder
-# into parquet format before training.
-
-models:
-  student:
-    _target_: fastvideo.train.models.cosmos.CosmosModel
-    init_from: nvidia/Cosmos-Predict2-2B-Video2World
-    trainable: true
-
-method:
-  _target_: fastvideo.train.methods.fine_tuning.finetune.FineTuneMethod
-
-training:
-  distributed:
-    num_gpus: 8
-    sp_size: 1
-    tp_size: 1
-    hsdp_replicate_dim: 8
-    hsdp_shard_dim: 1
-
-  data:
-    data_path: data/cosmos_preprocessed
-    dataloader_num_workers: 4
-    train_batch_size: 1
-    training_cfg_rate: 0.0
-    seed: 1000
-    # Cosmos VAE: 4x temporal, 8x spatial compression.
-    # 93 frames -> 24 latent frames, 480x832 -> 60x104
-    num_latent_t: 24
-    num_height: 480
-    num_width: 832
-    num_frames: 93
-
-  optimizer:
-    learning_rate: 1.0e-5
-    betas: [0.9, 0.999]
-    weight_decay: 0.01
-    lr_scheduler: constant
-    lr_warmup_steps: 0
-
-  loop:
-    max_train_steps: 5000
-    gradient_accumulation_steps: 1
-
-  checkpoint:
-    output_dir: outputs/cosmos_finetune
-    training_state_checkpointing_steps: 500
-    checkpoints_total_limit: 3
-    resume_from_checkpoint: latest
-
-  tracker:
-    project_name: fastvideo_cosmos
-    run_name: cosmos_finetune
-
-  model:
-    enable_gradient_checkpointing_type: full
-
-callbacks:
-  grad_clip:
-    _target_: fastvideo.train.callbacks.grad_clip.GradNormClipCallback
-    max_grad_norm: 1.0
-  validation:
-    _target_: fastvideo.train.callbacks.validation.ValidationCallback
-    pipeline_target: fastvideo.pipelines.basic.cosmos.cosmos_pipeline.Cosmos2VideoToWorldPipeline
-    dataset_file: data/cosmos_preprocessed/validation_prompts.json
-    every_steps: 100
-    sampling_steps: [50]
-    guidance_scale: 6.0
-
-pipeline:
-  flow_shift: 1.0
@@ -1,79 +0,0 @@
-# Cosmos-Predict2.5-2B Text-to-World overfitting test config.
-#
-# Overfits on a few short videos (480x832, 93 frames) to verify the
-# Cosmos 2.5 training plugin works end-to-end.
-#
-# Preprocess data first:
-#   CUDA_VISIBLE_DEVICES=0 python fastvideo/pipelines/preprocess/preprocess_cosmos25_overfit.py
-#
-# Run:
-#   bash examples/train/run.sh examples/train/configs/overfit_cosmos25_t2w.yaml
-
-models:
-  student:
-    _target_: fastvideo.train.models.cosmos.CosmosModel
-    init_from: KyleShao/Cosmos-Predict2.5-2B-Diffusers
-    trainable: true
-    enable_gradient_checkpointing_type: full
-    flow_shift: 1.0
-
-method:
-  _target_: fastvideo.train.methods.fine_tuning.finetune.FineTuneMethod
-
-training:
-  distributed:
-    num_gpus: 1
-    sp_size: 1
-    tp_size: 1
-    hsdp_replicate_dim: 1
-    hsdp_shard_dim: 1
-
-  data:
-    data_path: data/cosmos25_overfit_preprocessed
-    dataloader_num_workers: 0
-    train_batch_size: 1
-    training_cfg_rate: 0.0
-    seed: 42
-    num_latent_t: 24
-    num_height: 480
-    num_width: 832
-    num_frames: 93
-
-  optimizer:
-    learning_rate: 5.0e-5
-    betas: [0.9, 0.999]
-    weight_decay: 0.0
-    lr_scheduler: constant
-    lr_warmup_steps: 0
-
-  loop:
-    max_train_steps: 300
-    gradient_accumulation_steps: 1
-
-  checkpoint:
-    output_dir: outputs/cosmos25_overfit
-    training_state_checkpointing_steps: 50
-    checkpoints_total_limit: 2
-
-  tracker:
-    project_name: fastvideo_cosmos25
-    run_name: cosmos25_overfit
-
-  model:
-    precondition_outputs: false
-    enable_gradient_checkpointing_type: full
-
-callbacks:
-  grad_clip:
-    _target_: fastvideo.train.callbacks.grad_clip.GradNormClipCallback
-    max_grad_norm: 1.0
-  validation:
-    _target_: fastvideo.train.callbacks.validation.ValidationCallback
-    pipeline_target: fastvideo.pipelines.basic.cosmos.cosmos2_5_pipeline.Cosmos2_5Pipeline
-    dataset_file: data/cosmos25_overfit_preprocessed/validation_prompts.json
-    every_steps: 150
-    sampling_steps: [35]
-    guidance_scale: 7.0
-
-pipeline:
-  flow_shift: 1.0
@@ -1,7 +1,7 @@
 cmake_minimum_required(VERSION 3.26 FATAL_ERROR)
 project(fastvideo-kernel LANGUAGES CXX)

-# Prefer environment variable (used by CI or uv pip install git+repo_addr) if CMake var is not explicitly set.
+# Prefer environment variable (used by CI or pip install git+repo_addr) if CMake var is not explicitly set.
 if(NOT DEFINED GPU_BACKEND AND DEFINED ENV{GPU_BACKEND})
    set(GPU_BACKEND "$ENV{GPU_BACKEND}")
 endif()
@@ -5,11 +5,6 @@ from fastvideo_kernel.ops import (
    video_sparse_attn,
 )

-from fastvideo_kernel.block_sparse_attn import (
-    block_sparse_attn,
-    block_sparse_attn_from_indices,
-)
-
 from fastvideo_kernel.vmoba import (
    moba_attn_varlen,
    process_moba_input,
@@ -27,8 +22,6 @@ from fastvideo_kernel.turbodiffusion_ops import (
 __all__ = [
    "sliding_tile_attention",
    "video_sparse_attn",
-    "block_sparse_attn",
-    "block_sparse_attn_from_indices",
    "moba_attn_varlen",
    "process_moba_input",
    "process_moba_output",
@@ -1,5 +1,3 @@
-"""Autograd-enabled block-sparse attention. Index-native ops with a bool-mask compat shim."""
-
 from __future__ import annotations

 import os
@@ -8,11 +6,6 @@ from typing import Tuple
 import torch


-# ---------------------------------------------------------------------------
-# Backend selection helpers
-# ---------------------------------------------------------------------------
-
-
 def _get_sm90_ops():
    try:
        from fastvideo_kernel._C import fastvideo_kernel_ops  # type: ignore
@@ -32,66 +25,38 @@ def _is_sm90() -> bool:


 def _force_triton() -> bool:
+    # Force Triton even on SM90 and even if the compiled extension is available.
+    # Useful for CI / debugging / parity testing.
    return os.environ.get("FASTVIDEO_KERNEL_VSA_FORCE_TRITON", "0") == "1"


-# ---------------------------------------------------------------------------
-# Index helpers
-# ---------------------------------------------------------------------------
-
-
 def _map_to_index(block_map: torch.Tensor) -> Tuple[torch.Tensor, torch.Tensor]:
-    """Compact a bool block_map to (q2k_idx, q2k_num). Legacy path only."""
+    """
+    Preferred map->index conversion used by the wrapper.
+
+    This wrapper **requires** the Triton implementation.
+    If Triton (or the Triton map_to_index module) is not available, it raises.
+    """
    if block_map.dim() == 3:
        block_map = block_map.unsqueeze(0)
    if block_map.dim() != 4:
-        raise ValueError(
-            f"block_map must be [B,H,Q,KV] (or [H,Q,KV]), "
-            f"got shape={tuple(block_map.shape)}"
-        )
+        raise ValueError(f"block_map must be [B,H,Q,KV] (or [H,Q,KV]), got shape={tuple(block_map.shape)}")
    if block_map.dtype != torch.bool:
        block_map = block_map.to(torch.bool)
+
    if not block_map.is_cuda:
-        raise RuntimeError(
-            "block_map must be a CUDA tensor (Triton map_to_index required)."
-        )
+        raise RuntimeError("block_map must be a CUDA tensor (Triton map_to_index required).")

    try:
-        from fastvideo_kernel.triton_kernels.index import map_to_index as triton_map_to_index
-    except Exception as e:  # pragma: no cover - environment issue
+        from fastvideo_kernel.triton_kernels.index import map_to_index as triton_map_to_index  # local import
+    except Exception as e:
        raise ImportError(
            "Triton map_to_index is required but not available. "
-            "Ensure Triton is installed and "
-            "fastvideo_kernel.triton_kernels.index is importable."
+            "Ensure Triton is installed and fastvideo_kernel.triton_kernels.index is importable."
        ) from e
    return triton_map_to_index(block_map)


-def _invert_indices_for_backward(
-    q2k_idx: torch.Tensor,
-    q2k_num: torch.Tensor,
-    num_kv_blocks: int,
-) -> Tuple[torch.Tensor, torch.Tensor]:
-    from fastvideo_kernel.triton_kernels.index import invert_indices
-    return invert_indices(q2k_idx, q2k_num, num_kv_blocks=num_kv_blocks)
-
-
-def _as_int32_contig(t: torch.Tensor, name: str) -> torch.Tensor:
-    """Return `t` as a contiguous int32 tensor, raising a clear error on CPU input."""
-    if not t.is_cuda:
-        raise RuntimeError(f"{name} must be a CUDA tensor, got device={t.device}")
-    if t.dtype != torch.int32:
-        t = t.to(torch.int32)
-    if not t.is_contiguous():
-        t = t.contiguous()
-    return t
-
-
-# ---------------------------------------------------------------------------
-# Triton backend custom ops (index-native)
-# ---------------------------------------------------------------------------
-
-
@torch.library.custom_op(
    "fastvideo_kernel::block_sparse_attn_triton",
    mutates_args=(),
@@ -101,40 +66,34 @@ def block_sparse_attn_triton(
    q: torch.Tensor,
    k: torch.Tensor,
    v: torch.Tensor,
-    q2k_idx: torch.Tensor,
-    q2k_num: torch.Tensor,
+    block_map: torch.Tensor,
    variable_block_sizes: torch.Tensor,
 ) -> Tuple[torch.Tensor, torch.Tensor]:
-    from fastvideo_kernel.triton_kernels.block_sparse_attn_triton import (
+    q = q.contiguous()
+    k = k.contiguous()
+    v = v.contiguous()
+    block_map = block_map.to(torch.bool)
+    q2k_idx, q2k_num = _map_to_index(block_map)
+
+    from fastvideo_kernel.triton_kernels.block_sparse_attn_triton import (  # local import
        triton_block_sparse_attn_forward,
    )

-    o, M = triton_block_sparse_attn_forward(
-        q.contiguous(),
-        k.contiguous(),
-        v.contiguous(),
-        q2k_idx,
-        q2k_num,
-        variable_block_sizes,
-    )
+    o, M = triton_block_sparse_attn_forward(q, k, v, q2k_idx, q2k_num, variable_block_sizes)
    return o, M


+
@torch.library.register_fake("fastvideo_kernel::block_sparse_attn_triton")
 def _block_sparse_attn_triton_fake(
    q: torch.Tensor,
    k: torch.Tensor,
    v: torch.Tensor,
-    q2k_idx: torch.Tensor,
-    q2k_num: torch.Tensor,
+    block_map: torch.Tensor,
    variable_block_sizes: torch.Tensor,
 ) -> Tuple[torch.Tensor, torch.Tensor]:
    o = torch.empty_like(q)
-    M = torch.empty(
-        (q.shape[0], q.shape[1], q.shape[2]),
-        device=q.device,
-        dtype=torch.float32,
-    )
+    M = torch.empty((q.shape[0], q.shape[1], q.shape[2]), device=q.device, dtype=torch.float32)
    return o, M


@@ -150,32 +109,20 @@ def block_sparse_attn_backward_triton(
    v: torch.Tensor,
    o: torch.Tensor,
    M: torch.Tensor,
-    q2k_idx: torch.Tensor,
-    q2k_num: torch.Tensor,
+    block_map: torch.Tensor,
    variable_block_sizes: torch.Tensor,
 ) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
-    from fastvideo_kernel.triton_kernels.block_sparse_attn_triton import (
+    grad_output = grad_output.contiguous()
+    block_map = block_map.to(torch.bool)
+    q2k_idx, q2k_num = _map_to_index(block_map)
+    k2q_idx, k2q_num = _map_to_index(block_map.transpose(-1, -2).contiguous())
+
+    from fastvideo_kernel.triton_kernels.block_sparse_attn_triton import (  # local import
        triton_block_sparse_attn_backward,
    )

-    num_kv_blocks = int(variable_block_sizes.numel())
-    k2q_idx, k2q_num = _invert_indices_for_backward(
-        q2k_idx, q2k_num, num_kv_blocks
-    )
-    # q/k/v are saved from the user-facing inputs and may be non-contiguous;
-    # o/M are kernel outputs so are already contiguous.
    dq, dk, dv = triton_block_sparse_attn_backward(
-        grad_output.contiguous(),
-        q.contiguous(),
-        k.contiguous(),
-        v.contiguous(),
-        o,
-        M,
-        q2k_idx,
-        q2k_num,
-        k2q_idx,
-        k2q_num,
-        variable_block_sizes,
+        grad_output, q, k, v, o, M, q2k_idx, q2k_num, k2q_idx, k2q_num, variable_block_sizes
    )
    return dq, dk, dv

@@ -188,8 +135,7 @@ def _block_sparse_attn_backward_triton_fake(
    v: torch.Tensor,
    o: torch.Tensor,
    M: torch.Tensor,
-    q2k_idx: torch.Tensor,
-    q2k_num: torch.Tensor,
+    block_map: torch.Tensor,
    variable_block_sizes: torch.Tensor,
 ) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
    dq = torch.empty_like(q)
@@ -198,28 +144,19 @@ def _block_sparse_attn_backward_triton_fake(
    return dq, dk, dv


-def _setup_context_triton(ctx, inputs, output):
-    q, k, v, q2k_idx, q2k_num, variable_block_sizes = inputs
-    o, M = output
-    ctx.save_for_backward(q, k, v, o, M, q2k_idx, q2k_num, variable_block_sizes)
-
-
 def _backward_triton(ctx, grad_o, grad_M):
-    q, k, v, o, M, q2k_idx, q2k_num, variable_block_sizes = ctx.saved_tensors
-    dq, dk, dv = block_sparse_attn_backward_triton(
-        grad_o, q, k, v, o, M, q2k_idx, q2k_num, variable_block_sizes
-    )
-    return dq, dk, dv, None, None, None
+    q, k, v, o, M, block_map, variable_block_sizes = ctx.saved_tensors
+    dq, dk, dv = block_sparse_attn_backward_triton(grad_o, q, k, v, o, M, block_map, variable_block_sizes)
+    return dq, dk, dv, None, None


-block_sparse_attn_triton.register_autograd(
-    _backward_triton, setup_context=_setup_context_triton
-)
+def _setup_context_triton(ctx, inputs, output):
+    q, k, v, block_map, variable_block_sizes = inputs
+    o, M = output
+    ctx.save_for_backward(q, k, v, o, M, block_map, variable_block_sizes)


-# ---------------------------------------------------------------------------
-# SM90 backend custom ops (index-native)
-# ---------------------------------------------------------------------------
+block_sparse_attn_triton.register_autograd(_backward_triton, setup_context=_setup_context_triton)


@torch.library.custom_op(
@@ -231,21 +168,21 @@ def block_sparse_attn_sm90(
    q_padded: torch.Tensor,
    k_padded: torch.Tensor,
    v_padded: torch.Tensor,
-    q2k_idx: torch.Tensor,
-    q2k_num: torch.Tensor,
+    block_map: torch.Tensor,
    variable_block_sizes: torch.Tensor,
 ) -> Tuple[torch.Tensor, torch.Tensor]:
    block_sparse_fwd, _ = _get_sm90_ops()
    if block_sparse_fwd is None:
        raise ImportError("fastvideo_kernel_ops.block_sparse_fwd is not available")

+    q_padded = q_padded.contiguous()
+    k_padded = k_padded.contiguous()
+    v_padded = v_padded.contiguous()
+    block_map = block_map.to(torch.bool)
+    q2k_idx, q2k_num = _map_to_index(block_map)
+
    o_padded, lse_padded = block_sparse_fwd(
-        q_padded.contiguous(),
-        k_padded.contiguous(),
-        v_padded.contiguous(),
-        q2k_idx,
-        q2k_num,
-        variable_block_sizes,
+        q_padded, k_padded, v_padded, q2k_idx, q2k_num, variable_block_sizes.int()
    )
    return o_padded, lse_padded

@@ -255,16 +192,11 @@ def _block_sparse_attn_sm90_fake(
    q_padded: torch.Tensor,
    k_padded: torch.Tensor,
    v_padded: torch.Tensor,
-    q2k_idx: torch.Tensor,
-    q2k_num: torch.Tensor,
+    block_map: torch.Tensor,
    variable_block_sizes: torch.Tensor,
 ) -> Tuple[torch.Tensor, torch.Tensor]:
    o = torch.empty_like(q_padded)
-    lse = torch.empty(
-        (q_padded.shape[0], q_padded.shape[1], q_padded.shape[2], 1),
-        device=q_padded.device,
-        dtype=torch.float32,
-    )
+    lse = torch.empty((q_padded.shape[0], q_padded.shape[1], q_padded.shape[2], 1), device=q_padded.device, dtype=torch.float32)
    return o, lse


@@ -280,34 +212,30 @@ def block_sparse_attn_backward_sm90(
    v_padded: torch.Tensor,
    o_padded: torch.Tensor,
    lse_padded: torch.Tensor,
-    q2k_idx: torch.Tensor,
-    q2k_num: torch.Tensor,
+    block_map: torch.Tensor,
    variable_block_sizes: torch.Tensor,
 ) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
    _, block_sparse_bwd = _get_sm90_ops()
    if block_sparse_bwd is None:
        raise ImportError("fastvideo_kernel_ops.block_sparse_bwd is not available")

-    num_kv_blocks = int(variable_block_sizes.numel())
-    k2q_idx, k2q_num = _invert_indices_for_backward(
-        q2k_idx, q2k_num, num_kv_blocks
-    )
+    grad_output_padded = grad_output_padded.contiguous()
+    block_map = block_map.to(torch.bool)
+    k2q_idx, k2q_num = _map_to_index(block_map.transpose(-1, -2).contiguous())

-    # q/k/v are saved from user-facing inputs; o/lse are kernel outputs.
    dq, dk, dv = block_sparse_bwd(
-        q_padded.contiguous(),
-        k_padded.contiguous(),
-        v_padded.contiguous(),
+        q_padded,
+        k_padded,
+        v_padded,
        o_padded,
        lse_padded,
-        grad_output_padded.contiguous(),
+        grad_output_padded,
        k2q_idx,
        k2q_num,
-        variable_block_sizes,
+        variable_block_sizes.int(),
    )
-    # C++ kernel returns fp32 grads; cast back to the input dtype.
-    out_dtype = grad_output_padded.dtype
-    return dq.to(out_dtype), dk.to(out_dtype), dv.to(out_dtype)
+    # C++ kernel returns fp32 grads; cast back to match PyTorch convention if needed
+    return dq.to(grad_output_padded.dtype), dk.to(grad_output_padded.dtype), dv.to(grad_output_padded.dtype)


@torch.library.register_fake("fastvideo_kernel::block_sparse_attn_backward_sm90")
@@ -318,8 +246,7 @@ def _block_sparse_attn_backward_sm90_fake(
    v_padded: torch.Tensor,
    o_padded: torch.Tensor,
    lse_padded: torch.Tensor,
-    q2k_idx: torch.Tensor,
-    q2k_num: torch.Tensor,
+    block_map: torch.Tensor,
    variable_block_sizes: torch.Tensor,
 ) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
    dq = torch.empty_like(q_padded)
@@ -328,57 +255,21 @@ def _block_sparse_attn_backward_sm90_fake(
    return dq, dk, dv


-def _setup_context_sm90(ctx, inputs, output):
-    q, k, v, q2k_idx, q2k_num, variable_block_sizes = inputs
-    o, lse = output
-    ctx.save_for_backward(q, k, v, o, lse, q2k_idx, q2k_num, variable_block_sizes)
-
-
 def _backward_sm90(ctx, grad_o, grad_lse):
-    q, k, v, o, lse, q2k_idx, q2k_num, variable_block_sizes = ctx.saved_tensors
+    q, k, v, o, lse, block_map, variable_block_sizes = ctx.saved_tensors
    dq, dk, dv = block_sparse_attn_backward_sm90(
-        grad_o, q, k, v, o, lse, q2k_idx, q2k_num, variable_block_sizes
+        grad_o, q, k, v, o, lse, block_map, variable_block_sizes
    )
-    return dq, dk, dv, None, None, None
+    return dq, dk, dv, None, None


-block_sparse_attn_sm90.register_autograd(
-    _backward_sm90, setup_context=_setup_context_sm90
-)
+def _setup_context_sm90(ctx, inputs, output):
+    q, k, v, block_map, variable_block_sizes = inputs
+    o, lse = output
+    ctx.save_for_backward(q, k, v, o, lse, block_map, variable_block_sizes)


-# ---------------------------------------------------------------------------
-# Public API
-# ---------------------------------------------------------------------------
-
-
-def block_sparse_attn_from_indices(
-    q: torch.Tensor,
-    k: torch.Tensor,
-    v: torch.Tensor,
-    q2k_idx: torch.Tensor,
-    q2k_num: torch.Tensor,
-    variable_block_sizes: torch.Tensor,
-) -> Tuple[torch.Tensor, torch.Tensor]:
-    """Block-sparse attention with autograd, taking compact per-row KV indices."""
-    # Normalize index tensors once at the public boundary so the custom ops
-    # and their fakes can assume int32/contiguous. No-op on well-formed input.
-    q2k_idx = _as_int32_contig(q2k_idx, "q2k_idx")
-    q2k_num = _as_int32_contig(q2k_num, "q2k_num")
-    variable_block_sizes = _as_int32_contig(variable_block_sizes, "variable_block_sizes")
-
-    block_sparse_fwd, block_sparse_bwd = _get_sm90_ops()
-    use_sm90 = (
-        (not _force_triton())
-        and _is_sm90()
-        and block_sparse_fwd is not None
-        and block_sparse_bwd is not None
-    )
-    if use_sm90:
-        return block_sparse_attn_sm90(q, k, v, q2k_idx, q2k_num, variable_block_sizes)
-    # Triton path: supports q_seq_len != kv_seq_len as long as both are padded
-    # to a multiple of the block size (64 tokens).
-    return block_sparse_attn_triton(q, k, v, q2k_idx, q2k_num, variable_block_sizes)
+block_sparse_attn_sm90.register_autograd(_backward_sm90, setup_context=_setup_context_sm90)


 def block_sparse_attn(
@@ -388,8 +279,16 @@ def block_sparse_attn(
    block_map: torch.Tensor,
    variable_block_sizes: torch.Tensor,
 ) -> Tuple[torch.Tensor, torch.Tensor]:
-    """Bool-mask compat wrapper; prefer block_sparse_attn_from_indices."""
-    q2k_idx, q2k_num = _map_to_index(block_map)
-    return block_sparse_attn_from_indices(
-        q, k, v, q2k_idx, q2k_num, variable_block_sizes
-    )
+    """
+    Unified block-sparse attention op with autograd support.
+    - On SM90 with compiled extension present: uses fastvideo_kernel_ops.block_sparse_fwd/bwd.
+    - Otherwise: uses Triton implementation (requires q/k/v to have same padded length today).
+    """
+    block_sparse_fwd, block_sparse_bwd = _get_sm90_ops()
+    if (not _force_triton()) and _is_sm90() and (block_sparse_fwd is not None) and (block_sparse_bwd is not None):
+        return block_sparse_attn_sm90(q, k, v, block_map, variable_block_sizes)
+    # Triton path: supports q_seq_len != kv_seq_len as long as both are padded
+    # to a multiple of the block size (64 tokens).
+    return block_sparse_attn_triton(q, k, v, block_map, variable_block_sizes)
+
+
@@ -1,6 +1,6 @@
 import math
 import torch
-from .block_sparse_attn import block_sparse_attn, block_sparse_attn_from_indices
+from .block_sparse_attn import block_sparse_attn
 from .triton_kernels.st_attn_triton import sliding_tile_attention_triton

 # Try to load the C++ extension
@@ -125,18 +125,13 @@ def video_sparse_attn(
    out_c = out_c.repeat(1, 1, 1, block_elements,
                         1).view(batch, heads, q_seq_len, dim)

-    # Sparse branch: feed top-k indices directly, skipping the bool-mask round-trip.
+    # Sparse branch
    topk_idx = torch.topk(scores, topk, dim=-1).indices
-    q2k_idx = topk_idx.to(torch.int32).contiguous()
-    q2k_num = torch.full(
-        (batch, heads, q_num_blocks),
-        topk,
-        dtype=torch.int32,
-        device=q.device,
-    )
-    out_s = block_sparse_attn_from_indices(
-        q, k, v, q2k_idx, q2k_num, variable_block_sizes
-    )[0]
+    mask = torch.zeros_like(scores,
+                            dtype=torch.bool).scatter_(-1, topk_idx, True)
+
+    # out_s = block_sparse_attn(q, k, v, mask, variable_block_sizes)[0]
+    out_s = block_sparse_attn(q, k, v, mask, variable_block_sizes)[0]

    if compress_attn_weight is not None:
        return out_c * compress_attn_weight + out_s
@@ -1,10 +1,9 @@
 ## pytorch sdpa version of block sparse ##
-from typing import Tuple
-
 import triton
 import triton.language as tl
 import torch

+
@triton.jit
 def topk_index_to_map_kernel(
    map_ptr,
@@ -154,114 +153,3 @@ def map_to_index(block_map: torch.Tensor):
    )

    return index, index_num
-
-
-@triton.jit
-def _invert_indices_kernel(
-    q2k_idx_ptr,
-    q2k_num_ptr,
-    k2q_idx_ptr,
-    k2q_num_ptr,
-    q2k_idx_b, q2k_idx_h, q2k_idx_q, q2k_idx_k,
-    q2k_num_b, q2k_num_h, q2k_num_q,
-    k2q_idx_b, k2q_idx_h, k2q_idx_k, k2q_idx_q,
-    k2q_num_b, k2q_num_h, k2q_num_k,
-    MAX_KV_PER_Q: tl.constexpr,
-):
-    # One program per (b, h, q): reserve a slot in k2q via atomicAdd, write q.
-    pid_b = tl.program_id(0)
-    pid_h = tl.program_id(1)
-    pid_q = tl.program_id(2)
-
-    n = tl.load(
-        q2k_num_ptr
-        + pid_b * q2k_num_b
-        + pid_h * q2k_num_h
-        + pid_q * q2k_num_q
-    )
-
-    q2k_row = (
-        q2k_idx_ptr
-        + pid_b * q2k_idx_b
-        + pid_h * q2k_idx_h
-        + pid_q * q2k_idx_q
-    )
-
-    for i in tl.range(0, MAX_KV_PER_Q):
-        if i < n:
-            kv = tl.load(q2k_row + i * q2k_idx_k)
-            count_ptr = (
-                k2q_num_ptr
-                + pid_b * k2q_num_b
-                + pid_h * k2q_num_h
-                + kv * k2q_num_k
-            )
-            pos = tl.atomic_add(count_ptr, 1)
-            tl.store(
-                k2q_idx_ptr
-                + pid_b * k2q_idx_b
-                + pid_h * k2q_idx_h
-                + kv * k2q_idx_k
-                + pos * k2q_idx_q,
-                pid_q,
-            )
-
-
-def invert_indices(
-    q2k_idx: torch.Tensor,
-    q2k_num: torch.Tensor,
-    num_kv_blocks: int,
-) -> Tuple[torch.Tensor, torch.Tensor]:
-    """Transpose a Q->KV index list into a K->Q one via atomic compaction (GPU)."""
-    if q2k_idx.dim() != 4:
-        raise ValueError(
-            f"q2k_idx must be [B, H, Nq, Mk], got shape={tuple(q2k_idx.shape)}"
-        )
-    if q2k_num.dim() != 3:
-        raise ValueError(
-            f"q2k_num must be [B, H, Nq], got shape={tuple(q2k_num.shape)}"
-        )
-    if not q2k_idx.is_cuda or not q2k_num.is_cuda:
-        raise RuntimeError("invert_indices requires CUDA tensors.")
-
-    B, H, Nq, Mk = q2k_idx.shape
-    if q2k_num.shape != (B, H, Nq):
-        raise ValueError(
-            f"q2k_num shape {tuple(q2k_num.shape)} does not match q2k_idx "
-            f"[B, H, Nq] = {(B, H, Nq)}"
-        )
-
-    q2k_idx = q2k_idx.contiguous()
-    q2k_num = q2k_num.contiguous()
-    if q2k_idx.dtype != torch.int32:
-        q2k_idx = q2k_idx.to(torch.int32)
-    if q2k_num.dtype != torch.int32:
-        q2k_num = q2k_num.to(torch.int32)
-
-    # Any KV block is attended by at most Nq Q blocks (one per Q row), so
-    # `Nq` is a tight upper bound on the compacted K->Q slots.
-    k2q_idx = torch.empty(
-        (B, H, num_kv_blocks, Nq),
-        dtype=torch.int32,
-        device=q2k_idx.device,
-    )
-    k2q_num = torch.zeros(
-        (B, H, num_kv_blocks),
-        dtype=torch.int32,
-        device=q2k_idx.device,
-    )
-
-    grid = (B, H, Nq)
-    _invert_indices_kernel[grid](
-        q2k_idx,
-        q2k_num,
-        k2q_idx,
-        k2q_num,
-        q2k_idx.stride(0), q2k_idx.stride(1), q2k_idx.stride(2), q2k_idx.stride(3),
-        q2k_num.stride(0), q2k_num.stride(1), q2k_num.stride(2),
-        k2q_idx.stride(0), k2q_idx.stride(1), k2q_idx.stride(2), k2q_idx.stride(3),
-        k2q_num.stride(0), k2q_num.stride(1), k2q_num.stride(2),
-        MAX_KV_PER_Q=Mk,
-    )
-
-    return k2q_idx, k2q_num
@@ -11,7 +11,7 @@ except ImportError:

    def _unsupported(*args, **kwargs):
        raise ImportError(
-            "flash-attn is not installed. Please install it, e.g., `uv pip install flash-attn`."
+            "flash-attn is not installed. Please install it, e.g., `pip install flash-attn`."
        )

    _flash_attn_varlen_forward = _unsupported
@@ -1,67 +0,0 @@
-# `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`)
-
-```python
-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.
@@ -17,7 +17,6 @@ from fastvideo.api.request_metadata import (
 )
 from fastvideo.api.schema import (
    CompileConfig,
-    ContinuationState,
    GenerationRequest,
    GeneratorConfig,
    InputConfig,
@@ -27,10 +26,7 @@ from fastvideo.api.schema import (
 )
 from fastvideo.api.sampling_param import SamplingParam
 from fastvideo.fastvideo_args import FastVideoArgs
-from fastvideo.pipelines.basic.ltx2.stage_overrides import (
-    refine_preset_override_fields,
-    refine_stage_override_fields,
-)
+from fastvideo.pipelines.basic.ltx2.stage_overrides import REFINE_FLAT_KEYS
 from fastvideo.utils import shallow_asdict

 _INPUT_FIELD_NAMES = {field.name for field in fields(InputConfig)}
@@ -44,10 +40,7 @@ _LEGACY_REQUEST_ALIASES = {
 _REQUEST_PIPELINE_OVERRIDE_FIELDS = frozenset({
    "embedded_cfg_scale",
 })
-# torch.compile kwargs that map to first-class CompileConfig fields.
 _COMPILE_TYPED_KEYS = ("backend", "fullgraph", "mode", "dynamic")
-# LTX-2 refine flat kwargs (init + per-request) known to FastVideoArgs.
-_LTX2_REFINE_FLAT_KEYS = (refine_preset_override_fields() | refine_stage_override_fields())


 def normalize_generator_config(config: GeneratorConfig | Mapping[str, Any], ) -> GeneratorConfig:
@@ -118,10 +111,8 @@ def legacy_from_pretrained_to_config(
            offload["pin_cpu_memory"] = value
        elif key == "enable_torch_compile":
            compile_config["enabled"] = value
-        elif key == "enable_torch_compile_text_encoder":
-            compile_config["text_encoder_enabled"] = value
        elif key == "torch_compile_kwargs":
-            remaining: dict[str, Any] = (dict(deepcopy(value)) if isinstance(value, Mapping) else {})
+            remaining: dict[str, Any] = (dict(value) if isinstance(value, Mapping) else {})
            for first_class in _COMPILE_TYPED_KEYS:
                if first_class in remaining:
                    compile_config[first_class] = remaining.pop(first_class)
@@ -237,12 +228,6 @@ def generator_config_to_fastvideo_args(config: GeneratorConfig | Mapping[str, An
        kwargs["workload_type"] = normalized.pipeline.workload_type
    if normalized.pipeline.vae_tiling is not None:
        kwargs["ltx2_vae_tiling"] = normalized.pipeline.vae_tiling
-    if engine.compile.text_encoder_enabled is not None:
-        # ``FastVideoArgs.from_kwargs`` filters to declared fields, so
-        # this is a no-op on the current legacy path. Emit anyway so the
-        # realtime runtime (PR 7.6) — which reads from the kwargs dict
-        # before FastVideoArgs filtering — can pick it up once wired.
-        kwargs["enable_torch_compile_text_encoder"] = (engine.compile.text_encoder_enabled)

    quantization = engine.quantization
    if quantization is not None and quantization.text_encoder_quant is not None:
@@ -273,7 +258,7 @@ def generator_config_to_fastvideo_args(config: GeneratorConfig | Mapping[str, An
    preset_overrides = deepcopy(normalized.pipeline.preset_overrides)
    refine = preset_overrides.pop("refine", None)
    if isinstance(refine, Mapping):
-        for key in _LTX2_REFINE_FLAT_KEYS:
+        for key in REFINE_FLAT_KEYS:
            if key in refine:
                kwargs[f"ltx2_refine_{key}"] = refine[key]
    kwargs.update(preset_overrides)
@@ -326,13 +311,10 @@ def request_to_sampling_param(
 ) -> SamplingParam:
    if request.plan is not None:
        raise NotImplementedError("GenerationRequest.plan is not wired into VideoGenerator yet")
+    if request.state is not None:
+        raise NotImplementedError("GenerationRequest.state is not wired into VideoGenerator yet")

    sampling_param = SamplingParam.from_pretrained(model_path)
-    if request.state is not None:
-        _validate_continuation_state(request.state)
-        sampling_param.continuation_state = request.state
-    if request.output.return_state:
-        sampling_param.return_continuation_state = True
    updates = explicit_request_updates(request)

    for key, value in updates.items():
@@ -375,14 +357,9 @@ def _looks_like_run_or_serve_config(raw: Mapping[str, Any]) -> bool:


 def _compile_config_to_torch_kwargs(compile_config: CompileConfig, ) -> dict[str, Any]:
-    """Flatten typed ``CompileConfig`` back to a ``torch_compile_kwargs``
-    dict that the legacy ``FastVideoArgs`` path still expects.
-
-    Typed first-class fields (:attr:`backend`, :attr:`fullgraph`,
-    :attr:`mode`, :attr:`dynamic`) are only emitted when the user set
-    them explicitly (non-``None``). ``extras`` is merged on top for any
-    uncommon kwargs.
-    """
+    """Flatten typed ``CompileConfig`` back to the legacy
+    ``torch_compile_kwargs`` dict, emitting only explicitly-set typed
+    fields and merging ``extras`` on top."""
    out: dict[str, Any] = {}
    for key in _COMPILE_TYPED_KEYS:
        value = getattr(compile_config, key)
@@ -553,37 +530,6 @@ def _serialize_generation_request(request: GenerationRequest) -> dict[str, Any]:

 _SCHEMA_DEFAULT_UPDATES = _extract_request_updates(config_to_dict(GenerationRequest()))

-_KNOWN_CONTINUATION_KINDS: set[str] = set()
-
-
-def register_continuation_kind(kind: str) -> None:
-    """Register a :class:`ContinuationState.kind` as recognized.
-
-    PR 7 wires the envelope through; per-kind payload deserializers live
-    with each model family (e.g. ``fastvideo.pipelines.basic.ltx2.
-    continuation.LTX2ContinuationState``). The registry lets the
-    public-API compat layer validate the kind early, before the state
-    reaches the pipeline.
-    """
-    if not isinstance(kind, str) or not kind:
-        raise ValueError("ContinuationState kind must be a non-empty string")
-    _KNOWN_CONTINUATION_KINDS.add(kind)
-
-
-def _validate_continuation_state(state: ContinuationState) -> None:
-    if not isinstance(state.kind, str) or not state.kind:
-        raise ValueError("GenerationRequest.state.kind must be a non-empty string; got "
-                         f"{state.kind!r}")
-    if not isinstance(state.payload, Mapping):
-        raise ValueError(f"GenerationRequest.state.payload must be a mapping; got "
-                         f"{type(state.payload).__name__}")
-    if state.kind not in _KNOWN_CONTINUATION_KINDS:
-        known = sorted(_KNOWN_CONTINUATION_KINDS)
-        raise ValueError(f"Unknown ContinuationState kind {state.kind!r}; registered "
-                         f"kinds: {known}. Import the model family that owns this kind "
-                         "(e.g. `import fastvideo.pipelines.basic.ltx2.continuation`) "
-                         "to register it, or drop the state field.")
-

 def _fan_out_batched_input_value(
    source_request: GenerationRequest,
@@ -617,7 +563,6 @@ __all__ = [
    "load_generator_config_from_file",
    "normalize_generation_request",
    "normalize_generator_config",
-    "register_continuation_kind",
    "request_to_pipeline_overrides",
    "request_to_sampling_param",
 ]
@@ -15,7 +15,6 @@ class GenerationResult:
    samples: Any | None = None
    frames: Any | None = None
    audio: Any | None = None
-    audio_sample_rate: int | None = None
    size: tuple[int, int, int] | None = None
    generation_time: float | None = None
    logging_info: Any | None = None
@@ -45,7 +44,6 @@ class GenerationResult:
                "samples",
                "frames",
                "audio",
-                "audio_sample_rate",
                "size",
                "generation_time",
                "logging_info",
@@ -64,7 +62,6 @@ class GenerationResult:
            samples=result.get("samples"),
            frames=result.get("frames"),
            audio=result.get("audio"),
-            audio_sample_rate=result.get("audio_sample_rate"),
            size=result.get("size"),
            generation_time=result.get("generation_time"),
            logging_info=result.get("logging_info"),
@@ -83,7 +80,6 @@ class GenerationResult:
            "samples": self.samples,
            "frames": self.frames,
            "audio": self.audio,
-            "audio_sample_rate": self.audio_sample_rate,
            "size": self.size,
            "generation_time": self.generation_time,
            "logging_info": self.logging_info,
@@ -1,16 +1,11 @@
 # SPDX-License-Identifier: Apache-2.0
-from __future__ import annotations
-
 import copy
 from dataclasses import dataclass, field, fields
-from typing import TYPE_CHECKING, Any
+from typing import Any

 from fastvideo.logger import init_logger
 from fastvideo.utils import StoreBoolean

-if TYPE_CHECKING:
-    from fastvideo.api.schema import ContinuationState
-
 logger = init_logger(__name__)


@@ -97,13 +92,9 @@ class SamplingParam:
    movement_distance: float | None = None
    camera_rotation: str | None = None

-    # LTX-2 multi-modal CFG and STG.
-    # cfg_scale defaults are 1.0 (CFG off) so ``ForwardBatch.__post_init__``
-    # doesn't force ``do_classifier_free_guidance`` on non-LTX-2 models that
-    # never override these fields. LTX-2 presets that need text-CFG on set
-    # them in their ``defaults`` dict (e.g. ``ltx2_base``).
-    ltx2_cfg_scale_video: float = 1.0
-    ltx2_cfg_scale_audio: float = 1.0
+    # LTX2 multi-modal CFG and STG
+    ltx2_cfg_scale_video: float = 3.0
+    ltx2_cfg_scale_audio: float = 7.0
    ltx2_modality_scale_video: float = 3.0
    ltx2_modality_scale_audio: float = 3.0
    ltx2_rescale_scale: float = 0.7
@@ -112,39 +103,6 @@ class SamplingParam:
    ltx2_stg_blocks_video: list[int] = field(default_factory=lambda: [29])
    ltx2_stg_blocks_audio: list[int] = field(default_factory=lambda: [29])

-    # Stable Audio (T2A): clip start/end in seconds. Honored by
-    # `StableAudioConditioningStage` + `StableAudioDecodingStage`. Other
-    # families ignore them.
-    audio_start_in_s: float | None = None
-    audio_end_in_s: float | None = None
-
-    # Stable Audio audio-to-audio (variation):
-    #   `init_audio` -- a path or `[B, C, samples]` waveform at the model
-    #                   sample rate; the pipeline encodes it via the VAE
-    #                   and uses it as the starting latent.
-    #   `init_audio_strength` -- 0..1, higher = closer to the reference
-    #                            (matches the convention of Stability's
-    #                            commercial Stable Audio 2.0 UI). 1.0 ~=
-    #                            VAE round-trip, 0.0 ~= plain T2A.
-    #   `init_noise_level` -- legacy raw `sigma_max` override (0.3..500,
-    #                         higher = more freedom). Kept for callers
-    #                         that already use it; prefer `init_audio_strength`.
-    init_audio: Any = None
-    init_audio_strength: float | None = None
-    init_noise_level: float | None = None
-
-    # Stable Audio inpainting (RePaint-style): `inpaint_audio` is the
-    # reference clip, `inpaint_mask` is a [samples] tensor in {0, 1} where
-    # 1 means *keep the reference* and 0 means *regenerate*.
-    inpaint_audio: Any = None
-    inpaint_mask: Any = None
-
-    # Continuation state carried across streaming/multi-segment calls.
-    continuation_state: ContinuationState | None = None
-    # When True, the pipeline returns a ContinuationState on the result so
-    # the caller can resume from the generated segment.
-    return_continuation_state: bool = False
-
    # Misc
    save_video: bool = True
    return_frames: bool = True
@@ -169,7 +127,7 @@ class SamplingParam:
        self.__post_init__()

    @classmethod
-    def from_pretrained(cls, model_path: str) -> SamplingParam:
+    def from_pretrained(cls, model_path: str) -> "SamplingParam":
        sampling_param = cls._from_preset(model_path)
        if sampling_param is not None:
            return sampling_param
@@ -185,7 +143,7 @@ class SamplingParam:
    def _from_preset(
        cls,
        model_path: str,
-    ) -> SamplingParam | None:
+    ) -> "SamplingParam | None":
        """Build a SamplingParam from preset defaults.

        Returns ``None`` when no preset is configured for
@@ -41,12 +41,6 @@ class CompileConfig:
    """

    enabled: bool = False
-    text_encoder_enabled: bool | None = None
-    """Whether ``torch.compile`` is applied to the text encoder. ``None``
-    keeps the runtime default. The public ``FastVideoArgs`` adapter does
-    not yet consume this flag; reserved so the realtime runtime upstream
-    (PR 7.6) has a typed home for its ``enable_torch_compile_text_encoder``
-    kwarg without routing through ``pipeline.experimental``."""
    backend: str | None = None
    fullgraph: bool | None = None
    mode: str | None = None
@@ -1,58 +0,0 @@
-# `fastvideo/attention/` — Attention Backends
-
-**Generated:** 2026-05-02
-
-Backend registry + selector wrapping FlashAttn / SageAttn / SageAttn3 / SDPA / VSA / VMoBA / SLA / BSA.
-
-## Layout
-
-```
-attention/
-├── __init__.py            # Exports DistributedAttention, LocalAttention, get_attn_backend
-├── layer.py               # DistributedAttention, DistributedAttention_VSA, LocalAttention
-├── selector.py            # get_attn_backend (cached) + env-var override
-├── backends/
-│   ├── abstract.py        #   AttentionBackend / AttentionMetadata / AttentionMetadataBuilder
-│   ├── flash_attn.py      #   FA2/FA3
-│   ├── sage_attn.py       #   SageAttention v1
-│   ├── sage_attn3.py      #   SageAttention v3
-│   ├── sdpa.py            #   torch SDPA fallback
-│   ├── video_sparse_attn.py  # VSA (paper: Video Sparse Attention)
-│   ├── vmoba.py           #   Video-MoBA
-│   ├── sla.py             #   Sliding-window (STA)
-│   └── bsa_attn.py        #   Block-sparse
-└── utils/
-    ├── flash_attn_cute.py
-    └── flash_attn_no_pad.py
-```
-
-## Selection Order
-
-`get_attn_backend()` resolves via:
-
-1. Env-var override `FASTVIDEO_ATTENTION_BACKEND` (see `STR_BACKEND_ENV_VAR` in `fastvideo/utils.py`).
-2. Per-platform default from `fastvideo/platforms/`.
-3. Heuristic fallback to SDPA.
-
-The result is `@lru_cache`d. Tests that need a specific backend must use the
-`global_force_attn_backend(...)` context manager from `selector.py`, never set
-the env var mid-process.
-
-## Adding a Backend
-
-1. Subclass `AttentionBackend` in `backends/<name>.py`.
-2. Implement `AttentionMetadata` + `AttentionMetadataBuilder` for the new path.
-3. Register the enum value in `fastvideo/platforms/interface.py` (`AttentionBackendEnum`).
-4. Wire string → class resolution in `selector.py`.
-5. Verify the new backend works with `DistributedAttention` (sequence parallel)
-   and `LocalAttention` (single-rank). If it cannot support SP, document the
-   gap in the backend file's module docstring.
-
-## Anti-Patterns
-
- Calling `torch.nn.functional.scaled_dot_product_attention` directly inside a
-  model's forward — go through `DistributedAttention` / `LocalAttention`.
- Reading `os.environ[STR_BACKEND_ENV_VAR]` from arbitrary call sites. Use
-  `get_env_variable_attn_backend()`.
- Caching backend instances per-module. The selector cache is process-wide; do
-  not duplicate it.
@@ -2,6 +2,7 @@

 import torch
 import torch.nn.functional as F
+from flash_attn import flash_attn_func as flash_attn_2_func
 from dataclasses import dataclass

 try:
@@ -17,7 +18,6 @@ except ImportError:
        flash_attn_func = flash_attn_3_func
        fa_version = "3"
    except ImportError:
-        from flash_attn import flash_attn_func as flash_attn_2_func
        flash_attn_func = flash_attn_2_func
        fa_version = "2"

@@ -405,7 +405,7 @@ class SageSLAAttentionImpl(AttentionImpl, nn.Module):

        if not SAGESLA_ENABLED:
            raise ImportError("SageSLA requires spas_sage_attn. "
-                              "Install with: uv pip install git+https://github.com/thu-ml/SpargeAttn.git")
+                              "Install with: pip install git+https://github.com/thu-ml/SpargeAttn.git")

        assert head_size in [64, 128], f"SageSLA requires head_size in [64, 128], got {head_size}"

@@ -1,53 +0,0 @@
-# `fastvideo/configs/` — Config-Driven Model Registry
-
-**Generated:** 2026-05-02
-
-Two layers of dataclass configs feed every pipeline: **arch configs** (what the model is) and **pipeline configs** (how to run it).
-
-## Layout
-
-```
-configs/
-├── configs.py                  # Dataset / loader enums (DatasetType, VideoLoaderType)
-├── utils.py                    # update_config_from_args, shallow_asdict helpers
-├── backend/                    # Attention backend defaults
-├── models/
-│   ├── base.py                 # ModelConfig ABC
-│   ├── dits/                   # DiTConfig per model (wanvideo, ltx2, hunyuan, ...)
-│   ├── vaes/                   # VAEConfig per model
-│   ├── encoders/               # EncoderConfig (t5, clip, llama, qwen2_5, gemma, siglip, ...)
-│   ├── upsamplers/             # UpsamplerConfig (hunyuan15)
-│   └── audio/                  # Audio-model configs (ltx2_audio_vae, ...)
-├── pipelines/
-│   ├── base.py                 # PipelineConfig ABC + (de)serialization
-│   └── <model>.py              # Concrete configs (HunyuanConfig, WanT2V480PConfig, ...)
-└── *.json                      # Frozen reference configs for shipped models
-```
-
-## How Configs Hook Into the Registry
-
-`fastvideo/registry.py` imports every concrete `PipelineConfig` and exposes
-`get_pipeline_config_cls_from_name(...)`. Adding a new pipeline config requires:
-
-1. Subclass `PipelineConfig` in `pipelines/<model>.py`.
-2. Reference its component arch configs (DiT / VAE / encoder / upsampler).
-3. Add the import + name mapping in `fastvideo/registry.py`.
-
-Configs that do not appear in `registry.py` are unreachable from `VideoGenerator`.
-
-## Arch vs Pipeline — Where Does This Field Go?
-
-| Field type | Lives on |
-|-----------|----------|
-| Architecture constants (hidden dim, num heads, layer count) | `configs/models/<role>/<model>.py` |
-| Default sampling params (steps, cfg, shift, fps) | `configs/pipelines/<model>.py` |
-| Runtime overrides (precision, sp_size, tp_size, attention backend) | `configs/pipelines/base.py` defaults + CLI flags via `fastvideo_args.py` |
-| `param_names_mapping` for HF → FastVideo state-dict | Arch config (lives with the model definition) |
-
-If a knob is tunable per inference call → `SamplingParam`, not `PipelineConfig`.
-
-## Anti-Patterns
-
- Hard-coding architecture constants inside model classes — always read from the arch config.
- Using `argparse` directly here. Configs deserialize from dicts via `update_config_from_args`.
- Importing from `fastvideo.pipelines` here. Configs are the lower layer; the dependency is one-way.
@@ -48,6 +48,8 @@ class ModelConfig:
        for key, value in source_model_dict.items():
            if key in valid_fields:
                setattr(arch_config, key, value)
+            else:
+                raise AttributeError(f"{type(arch_config).__name__} has no field '{key}'")

        if hasattr(arch_config, "__post_init__"):
            arch_config.__post_init__()
@@ -5,14 +5,11 @@ from fastvideo.configs.models.dits.hunyuanvideo import HunyuanVideoConfig
 from fastvideo.configs.models.dits.hunyuanvideo15 import HunyuanVideo15Config
 from fastvideo.configs.models.dits.longcat import LongCatVideoConfig
 from fastvideo.configs.models.dits.ltx2 import LTX2VideoConfig
-from fastvideo.configs.models.dits.magi_human import MagiHumanVideoConfig
-from fastvideo.configs.models.dits.stable_audio import StableAudioConfig
 from fastvideo.configs.models.dits.wanvideo import WanVideoConfig
 from fastvideo.configs.models.dits.hyworld import HYWorldConfig
 from fastvideo.configs.models.dits.kandinsky5 import Kandinsky5VideoConfig

 __all__ = [
    "HunyuanVideoConfig", "HunyuanVideo15Config", "HunyuanGameCraftConfig", "WanVideoConfig", "CosmosVideoConfig",
-    "Cosmos25VideoConfig", "LongCatVideoConfig", "LTX2VideoConfig", "HYWorldConfig", "Kandinsky5VideoConfig",
-    "MagiHumanVideoConfig", "StableAudioConfig"
+    "Cosmos25VideoConfig", "LongCatVideoConfig", "LTX2VideoConfig", "HYWorldConfig", "Kandinsky5VideoConfig"
 ]
@@ -50,8 +50,7 @@ class CosmosArchConfig(DiTArchConfig):
        })

    # Cosmos-specific config parameters based on transformer_cosmos.py
-    # in_channels includes the condition_mask channel (16 latent + 1 cond = 17)
-    in_channels: int = 17
+    in_channels: int = 16
    out_channels: int = 16
    num_attention_heads: int = 16
    attention_head_dim: int = 128
@@ -1,110 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-"""Architecture / model config for the daVinci-MagiHuman DiT.
-
-The MagiHuman base DiT is a 15B-parameter single-stream transformer that
-jointly denoises video, audio, and text tokens in one flat sequence. Layout
-details verified against GAIR/daVinci-MagiHuman's base/ shards (2026-04-24).
-
-This file captures only configuration. The module implementation lives in
-fastvideo/models/dits/magi_human.py and the pipeline wiring in
-fastvideo/pipelines/basic/magi_human/.
-"""
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-
-from fastvideo.configs.models.dits.base import DiTArchConfig, DiTConfig
-
-
-def _is_block_layer(n: str, m) -> bool:
-    # Match "block.layers.<idx>" — the FSDP shard boundary for MagiHuman.
-    parts = n.split(".")
-    return (len(parts) >= 3 and parts[0] == "block" and parts[1] == "layers" and str.isdigit(parts[2]))
-
-
-@dataclass
-class MagiHumanArchConfig(DiTArchConfig):
-    """MagiHuman base DiT architecture constants.
-
-    **Scope contract:** fields here must match the `transformer/config.json`
-    emitted by `scripts/checkpoint_conversion/convert_magi_human_to_diffusers.py`
-    1:1, and both are sourced from the upstream Python reference
-    `inference/common/config.py::ModelConfig` (the HF root `config.json`
-    is empty so the Python source is canonical). Pipeline-level knobs
-    (VAE stride, fps, num_inference_steps, CFG scales, flow_shift,
-    t5_gemma_target_length) and data-proxy knobs (coords_style,
-    frame_receptive_field, ref_audio_offset, text_offset) live on
-    `MagiHumanBaseConfig`, NOT here.
-
-    `param_names_mapping` is intentionally empty: the FastVideo implementation
-    keeps the same module tree as the reference (`adapter.*`,
-    `block.layers.<i>.*`, `final_linear_{video,audio}.*`,
-    `final_norm_{video,audio}.*`), so converted weights load directly.
-    """
-
-    _fsdp_shard_conditions: list = field(default_factory=lambda: [_is_block_layer])
-
-    # No renames needed — the FastVideo module mirrors the reference names.
-    param_names_mapping: dict = field(default_factory=dict)
-    reverse_param_names_mapping: dict = field(default_factory=dict)
-    lora_param_names_mapping: dict = field(default_factory=dict)
-
-    # --- transformer shape ---
-    num_layers: int = 40
-    hidden_size: int = 5120
-    head_dim: int = 128
-    num_query_groups: int = 8  # num_heads_kv (GQA)
-
-    # --- modality channels ---
-    # video_in_channels = z_dim (48) * patch_size product (1*2*2=4), so the
-    # embedder receives 192 per token. text_in_channels is T5Gemma-9B's
-    # encoder hidden size.
-    video_in_channels: int = 192
-    audio_in_channels: int = 64
-    text_in_channels: int = 3584
-
-    # --- block-level architecture switches ---
-    # Sandwich MoE: first and last 4 layers have per-modality experts
-    # (video/audio/text), middle layers share a single set of weights.
-    mm_layers: tuple[int, ...] = (0, 1, 2, 3, 36, 37, 38, 39)
-    local_attn_layers: tuple[int, ...] = ()
-    gelu7_layers: tuple[int, ...] = (0, 1, 2, 3)
-    post_norm_layers: tuple[int, ...] = ()
-    enable_attn_gating: bool = True
-    activation_type: str = "swiglu7"
-
-    # --- DiT patching (upstream `ModelConfig`-equivalent; NOT the VAE
-    #     stride, which is pipeline-level). ---
-    patch_size: tuple[int, int, int] = (1, 2, 2)
-    spatial_rope_interpolation: str = "extra"
-
-    # --- TReAD (token routing + early drop). Flattened from the upstream
-    #     nested `tread_config` dict so it round-trips through
-    #     `update_model_arch` cleanly. ---
-    tread_selection_rate: float = 0.5
-    tread_start_layer_idx: int = 2
-    tread_end_layer_idx: int = 25
-
-    # --- derived fields (populated in __post_init__) ---
-    num_attention_heads: int = 0  # hidden_size / head_dim
-    num_heads_kv: int = 0  # == num_query_groups
-    in_channels: int = 0  # mirror of video_in_channels (FastVideo contract)
-    out_channels: int = 0  # mirror of video_in_channels
-
-    def __post_init__(self) -> None:
-        super().__post_init__()
-        self.num_attention_heads = self.hidden_size // self.head_dim
-        self.num_heads_kv = self.num_query_groups
-        self.in_channels = self.video_in_channels
-        self.out_channels = self.video_in_channels
-        # num_channels_latents is the VAE latent z_dim (48 for Wan 2.2 TI2V-5B).
-        # We don't declare z_dim on the arch config (it's a VAE property),
-        # but we still set num_channels_latents for the BaseDiT contract.
-        self.num_channels_latents = 48
-
-
-@dataclass
-class MagiHumanVideoConfig(DiTConfig):
-    arch_config: DiTArchConfig = field(default_factory=MagiHumanArchConfig)
-
-    prefix: str = "magi_human"
@@ -1,76 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-"""Config for the Stable Audio Open 1.0 DiT.
-
-Note: the SA pipeline bypasses the standard `ComposedPipelineBase`
-component loader because the published HF repo ships a single monolithic
-`model.safetensors` (no Diffusers-style `model_index.json` or
-per-subfolder layout). The arch fields and `param_names_mapping` here
-document the architecture and key remap so the same conventions used by
-the rest of the DiT family apply (FSDP shard conditions, supported
-attention backends, future loader integrations) — they are not currently
-consumed by `fastvideo/models/loader/fsdp_load.py` for SA.
-"""
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-
-from fastvideo.configs.models.dits.base import DiTArchConfig, DiTConfig
-from fastvideo.platforms import AttentionBackendEnum
-
-
-def _is_transformer_layer(n: str, m) -> bool:
-    # Matches `transformer.layers.{i}` in the SA DiT module tree.
-    parts = n.split(".")
-    return (len(parts) >= 3 and parts[-3] == "transformer" and parts[-2] == "layers" and parts[-1].isdigit())
-
-
-@dataclass
-class StableAudioArchConfig(DiTArchConfig):
-    _fsdp_shard_conditions: list = field(default_factory=lambda: [_is_transformer_layer])
-
-    # SA's checkpoint is `stable_audio_tools` raw format (not Diffusers),
-    # so the only remaps are: strip the `model.model.` host-pipeline
-    # prefix, and rename `nn.LayerNorm`'s `gamma`/`beta` to torch's
-    # canonical `weight`/`bias`. Linear / cross-attention naming already
-    # matches FastVideo's conventions, so no further remap is needed.
-    param_names_mapping: dict = field(
-        default_factory=lambda: {
-            r"^model\.model\.(.*?)\.gamma$": r"\1.weight",
-            r"^model\.model\.(.*?)\.beta$": r"\1.bias",
-            r"^model\.model\.(.*)$": r"\1",
-        })
-
-    # SA only supports backends compatible with single-GPU LocalAttention.
-    _supported_attention_backends: tuple[AttentionBackendEnum, ...] = (
-        AttentionBackendEnum.FLASH_ATTN,
-        AttentionBackendEnum.TORCH_SDPA,
-    )
-
-    # Architecture constants (from the published `model_config.json` for
-    # `stabilityai/stable-audio-open-1.0`).
-    io_channels: int = 64
-    embed_dim: int = 1536
-    depth: int = 24
-    num_attention_heads: int = 24
-    cond_token_dim: int = 768
-    global_cond_dim: int = 1536
-    project_cond_tokens: bool = False
-    project_global_cond: bool = True
-    # Set to "ln" to wrap attention Q/K in LayerNorm (used by
-    # `stable-audio-open-small`; absent in the 1.0 base).
-    qk_norm: str | None = None
-
-    def __post_init__(self) -> None:
-        super().__post_init__()
-        self.hidden_size = self.embed_dim
-        self.in_channels = self.io_channels
-        self.out_channels = self.io_channels
-        self.num_channels_latents = self.io_channels
-        self.attention_head_dim = self.embed_dim // self.num_attention_heads
-
-
-@dataclass
-class StableAudioConfig(DiTConfig):
-    arch_config: DiTArchConfig = field(default_factory=StableAudioArchConfig)
-
-    prefix: str = "StableAudio"
@@ -7,13 +7,9 @@ from fastvideo.configs.models.encoders.qwen2_5 import Qwen2_5_VLConfig
 from fastvideo.configs.models.encoders.siglip import SiglipVisionConfig
 from fastvideo.configs.models.encoders.reason1 import Reason1ArchConfig, Reason1Config
 from fastvideo.configs.models.encoders.gemma import LTX2GemmaConfig
-from fastvideo.configs.models.encoders.stable_audio_conditioner import (StableAudioConditionerArchConfig,
-                                                                        StableAudioConditionerConfig)
-from fastvideo.configs.models.encoders.t5gemma import T5GemmaEncoderConfig

 __all__ = [
    "EncoderConfig", "TextEncoderConfig", "ImageEncoderConfig", "BaseEncoderOutput", "CLIPTextConfig",
    "CLIPVisionConfig", "WAN2_1ControlCLIPVisionConfig", "LlamaConfig", "T5Config", "T5LargeConfig", "Qwen2_5_VLConfig",
-    "Reason1ArchConfig", "Reason1Config", "LTX2GemmaConfig", "SiglipVisionConfig", "StableAudioConditionerArchConfig",
-    "StableAudioConditionerConfig", "T5GemmaEncoderConfig"
+    "Reason1ArchConfig", "Reason1Config", "LTX2GemmaConfig", "SiglipVisionConfig"
 ]
@@ -1,80 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-"""Config for the Stable Audio Open 1.0 multi-conditioner.
-
-The conditioner bundles three sub-conditioners — a T5 text encoder
-(prompt) and two NumberConditioners (`seconds_start` / `seconds_total`)
-— into the (cross_attn_cond, cross_attn_mask, global_embed) triple the
-DiT consumes. The architecture is fully specified by the official
-`stable_audio_tools` `MultiConditioner` config; the constants here
-mirror that.
-"""
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-
-from fastvideo.configs.models.base import ArchConfig
-from fastvideo.configs.models.encoders.base import (EncoderArchConfig, EncoderConfig)
-
-
-def _default_configs() -> list[dict]:
-    """Default = `stable-audio-open-1.0`'s three sub-conditioners."""
-    return [
-        {
-            "id": "prompt",
-            "type": "t5",
-            "config": {
-                "t5_model_name": "t5-base",
-                "max_length": 128
-            }
-        },
-        {
-            "id": "seconds_start",
-            "type": "number",
-            "config": {
-                "min_val": 0,
-                "max_val": 512
-            }
-        },
-        {
-            "id": "seconds_total",
-            "type": "number",
-            "config": {
-                "min_val": 0,
-                "max_val": 512
-            }
-        },
-    ]
-
-
-@dataclass
-class StableAudioConditionerArchConfig(EncoderArchConfig):
-    architectures: list[str] = field(default_factory=lambda: ["StableAudioMultiConditioner"])
-
-    # Shared embedding width across all sub-conditioners (T5 last-hidden
-    # dim and NumberEmbedder feature dim both = `cond_dim`).
-    cond_dim: int = 768
-
-    # Sub-conditioner identifiers. Order in `cross_attention_cond_ids`
-    # is the concat order for the cross-attn token sequence; order in
-    # `global_cond_ids` is the concat order for the global FiLM-style
-    # embedding.
-    cross_attention_cond_ids: tuple[str, ...] = ("prompt", "seconds_start", "seconds_total")
-    global_cond_ids: tuple[str, ...] = ("seconds_start", "seconds_total")
-
-    # Per-sub-conditioner spec list (mirrors upstream
-    # `model_config.json.model.conditioning.configs`). Each entry is
-    # `{"id": ..., "type": "t5"|"number", "config": {...}}`. The default
-    # matches `stable-audio-open-1.0`; SA-small overrides via the
-    # `conditioner/config.json` shipped in the converted repo.
-    configs: list = field(default_factory=_default_configs)
-
-    # Match official `stable_audio_tools/models/conditioners.py:334`:
-    # T5 is loaded directly in fp16.
-    t5_dtype: str = "float16"
-
-
-@dataclass
-class StableAudioConditionerConfig(EncoderConfig):
-    arch_config: ArchConfig = field(default_factory=StableAudioConditionerArchConfig)
-
-    prefix: str = "stable_audio_conditioner"
@@ -41,14 +41,6 @@ class T5ArchConfig(TextEncoderArchConfig):
    text_len: int = 512
    dtype: str | None = None
    gradient_checkpointing: bool = False
-    # Extra fields present in upstream HF T5Config but unused by FastVideo's
-    # encoder. Declared here so `update_model_arch` doesn't reject them when
-    # loading repos like `stabilityai/stable-audio-open-1.0` that ship the
-    # full HF config.
-    n_positions: int = 512
-    decoder_start_token_id: int = 0
-    output_past: bool = True
-    task_specific_params: dict | None = None
    stacked_params_mapping: list[tuple[str, str, str]] = field(default_factory=lambda: [
        # (param_name, shard_name, shard_id)
        (".qkv_proj", ".q", "q"),
@@ -1,71 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-"""Config for the T5-Gemma encoder used by daVinci-MagiHuman.
-
-The reference pipeline uses `transformers.models.t5gemma.T5GemmaEncoderModel`
-on `google/t5gemma-9b-9b-ul2`. That is a gated Google repository, so the
-encoder weights are not bundled inside GAIR/daVinci-MagiHuman; they are
-loaded from the T5-Gemma HF repo directly.
-
-Encoder shape (verified from google/t5gemma-9b-9b-ul2/config.json):
-    layers=42, hidden=3584, heads=16, kv_heads=8, head_dim=256,
-    intermediate=14336, rope_theta=10000.0, max_pos=8192,
-    layer_types alternate sliding_attention / full_attention.
-"""
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-
-from fastvideo.configs.models.encoders.base import (
-    TextEncoderArchConfig,
-    TextEncoderConfig,
-)
-
-
-def _is_t5gemma_model(n: str, m) -> bool:
-    return n.endswith("t5gemma_model") or n.endswith("_t5gemma_model")
-
-
-@dataclass
-class T5GemmaEncoderArchConfig(TextEncoderArchConfig):
-    architectures: list[str] = field(default_factory=lambda: ["T5GemmaEncoderModel"])
-
-    hidden_size: int = 3584
-    num_hidden_layers: int = 42
-    num_attention_heads: int = 16
-    num_key_value_heads: int = 8
-    head_dim: int = 256
-    intermediate_size: int = 14336
-    max_position_embeddings: int = 8192
-    rope_theta: float = 10000.0
-    vocab_size: int = 256000
-
-    # MagiHuman fixes prompt embed length at 640 via pad_or_trim.
-    text_len: int = 640
-
-    pad_token_id: int = 0
-    eos_token_id: int = 1
-
-    # Path to the upstream gated repo. When set, the FastVideo loader will
-    # pull the encoder directly via `T5GemmaEncoderModel.from_pretrained`.
-    t5gemma_model_path: str = "google/t5gemma-9b-9b-ul2"
-    t5gemma_dtype: str = "bfloat16"
-
-    _fsdp_shard_conditions: list = field(default_factory=lambda: [_is_t5gemma_model])
-
-    def __post_init__(self) -> None:
-        super().__post_init__()
-        # WHY: upstream `t5_gemma_model.py:25` tokenizes without
-        # padding/max_length, then `prompt_process.py` pad_or_trim-s the
-        # encoded states. Keep only tensor return here so
-        # MagiHumanLatentPreparationStage can pad/trim post-encode while
-        # preserving the real original prompt length.
-        self.tokenizer_kwargs.pop("truncation", None)
-        self.tokenizer_kwargs.pop("max_length", None)
-        self.tokenizer_kwargs.pop("padding", None)
-
-
-@dataclass
-class T5GemmaEncoderConfig(TextEncoderConfig):
-    arch_config: TextEncoderArchConfig = field(default_factory=T5GemmaEncoderArchConfig)
-
-    prefix: str = "t5gemma"
@@ -5,7 +5,6 @@ from fastvideo.configs.models.vaes.gen3cvae import Gen3CVAEConfig
 from fastvideo.configs.models.vaes.hunyuanvae import HunyuanVAEConfig
 from fastvideo.configs.models.vaes.hunyuan15vae import Hunyuan15VAEConfig
 from fastvideo.configs.models.vaes.ltx2vae import LTX2VAEConfig
-from fastvideo.configs.models.vaes.oobleck import OobleckVAEArchConfig, OobleckVAEConfig
 from fastvideo.configs.models.vaes.wanvae import WanVAEConfig

 __all__ = [
@@ -17,6 +16,4 @@ __all__ = [
    "Gen3CVAEConfig",
    "Hunyuan15VAEConfig",
    "LTX2VAEConfig",
-    "OobleckVAEArchConfig",
-    "OobleckVAEConfig",
 ]
@@ -1,68 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-"""Config for the Stable Audio Open 1.0 "Oobleck" VAE.
-
-Mirrors the per-channel `vae/config.json` shipped in
-`stabilityai/stable-audio-open-1.0` 1:1 (see
-`fastvideo/models/vaes/oobleck.py::OobleckVAE.from_pretrained`, which
-constructs the VAE from these fields). Inherits the FastVideo VAEConfig
-base so the standard `load_encoder` / `load_decoder` flags + tiling
-knobs apply.
-
-Naming: the VAE architecture is officially "Oobleck" (per Stability
-AI's stable-audio-tools) — the surrounding model family is "Stable
-Audio Open 1.0". This config is named after the architecture
-(`OobleckVAEConfig`) since the same VAE is shared across Stable Audio
-checkpoints; downstream pipelines reference it by its arch name, not
-by a host-pipeline name.
-"""
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-
-from fastvideo.configs.models.vaes.base import VAEArchConfig, VAEConfig
-
-
-@dataclass
-class OobleckVAEArchConfig(VAEArchConfig):
-    """Stable Audio Open 1.0 VAE architecture constants."""
-
-    architectures: list[str] = field(default_factory=lambda: ["AutoencoderOobleck"])
-
-    # From stabilityai/stable-audio-open-1.0/vae/config.json.
-    encoder_hidden_size: int = 128
-    downsampling_ratios: list[int] = field(default_factory=lambda: [2, 4, 4, 8, 8])
-    channel_multiples: list[int] = field(default_factory=lambda: [1, 2, 4, 8, 16])
-    decoder_channels: int = 128
-    decoder_input_channels: int = 64
-    audio_channels: int = 2  # stereo
-    sampling_rate: int = 44100
-
-
-@dataclass
-class OobleckVAEConfig(VAEConfig):
-    """FastVideo VAE config wrapping the Oobleck arch.
-
-    Audio VAEs don't use the temporal/spatial tiling defaults that the
-    base VAEConfig is shaped for (those exist for video VAEs); they are
-    retained but irrelevant for audio.
-    """
-
-    arch_config: VAEArchConfig = field(default_factory=OobleckVAEArchConfig)
-
-    # Audio is 1-D, so the video-VAE tiling defaults are inert. Disable
-    # them so callers don't accidentally trip on tile-stride math built
-    # for spatial tensors.
-    use_tiling: bool = False
-    use_temporal_tiling: bool = False
-    use_parallel_tiling: bool = False
-
-    # Where the FastVideo loader / pipeline-glue wrapper should fetch
-    # weights from when no local path is supplied. Gated repo — caller's
-    # HF token must have accepted terms on
-    # https://huggingface.co/stabilityai/stable-audio-open-1.0.
-    pretrained_path: str = "stabilityai/stable-audio-open-1.0"
-    pretrained_subfolder: str = "vae"
-    # Match official `stable_audio_tools`: VAE runs in fp16 (the
-    # `pretransform.model_half` path in
-    # `stable_audio_tools/models/pretransforms.py`).
-    pretrained_dtype: str = "float16"
@@ -11,34 +11,10 @@ import torch
 from fastvideo.configs.models import DiTConfig, VAEConfig
 from fastvideo.configs.models.dits.base import DiTArchConfig
 from fastvideo.configs.models.encoders import BaseEncoderOutput, T5Config
-from fastvideo.configs.models.encoders.base import TextEncoderArchConfig
-from fastvideo.configs.models.encoders.t5 import T5ArchConfig
 from fastvideo.configs.models.vaes import WanVAEConfig
 from fastvideo.configs.pipelines.base import PipelineConfig


-@dataclass
-class LongCatT5ArchConfig(T5ArchConfig):
-    """T5 arch that pads tokenizer output to ``max_length``.
-
-    LongCat's denoising stage concatenates positive and negative
-    attention masks along the batch dimension for CFG, which requires
-    uniform seq length. The shared :class:`T5ArchConfig` dropped the
-    ``"padding": "max_length"`` tokenizer kwarg so other DiTs could run
-    with variable-length masks; LongCat still needs the uniform
-    contract.
-    """
-
-    def __post_init__(self) -> None:
-        super().__post_init__()
-        self.tokenizer_kwargs["padding"] = "max_length"
-
-
-@dataclass
-class LongCatT5Config(T5Config):
-    arch_config: TextEncoderArchConfig = field(default_factory=LongCatT5ArchConfig)
-
-
@dataclass
 class LongCatDiTArchConfig(DiTArchConfig):
    """Extended DiTArchConfig with LongCat-specific fields."""
@@ -127,9 +103,8 @@ class LongCatT2V480PConfig(PipelineConfig):
    vae_precision: str = "bf16"
    text_encoder_precisions: tuple[str, ...] = field(default_factory=lambda: ("bf16", ))

-    # UMT5 uses T5-like config; postprocess pads to 512. LongCatT5Config
-    # restores ``padding="max_length"`` for the CFG concat contract.
-    text_encoder_configs: tuple[T5Config, ...] = field(default_factory=lambda: (LongCatT5Config(), ))
+    # Text encoding (UMT5 uses T5-like config; postprocess to fixed 512)
+    text_encoder_configs: tuple[T5Config, ...] = field(default_factory=lambda: (T5Config(), ))
    preprocess_text_funcs: tuple[Callable[[str], str], ...] = field(default_factory=lambda: (longcat_preprocess_text, ))
    postprocess_text_funcs: tuple[Callable[[BaseEncoderOutput], torch.Tensor],
                                  ...] = field(default_factory=lambda: (umt5_postprocess_text, ))
@@ -1,67 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-"""`PipelineConfig` for Stable Audio Open 1.0."""
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-
-from fastvideo.configs.models import DiTConfig, VAEConfig
-from fastvideo.configs.models.dits import StableAudioConfig
-from fastvideo.configs.models.vaes import OobleckVAEConfig
-from fastvideo.configs.pipelines.base import PipelineConfig
-
-
-@dataclass
-class StableAudioT2AConfig(PipelineConfig):
-    """Stable Audio Open 1.0 pipeline config."""
-
-    dit_config: DiTConfig = field(default_factory=StableAudioConfig)
-    # Standard `TransformerLoader` reads `dit_precision`; default in
-    # `PipelineConfig` is bf16, but we want fp16 to match official.
-    dit_precision: str = "fp16"
-
-    vae_config: VAEConfig = field(default_factory=OobleckVAEConfig)
-    vae_tiling: bool = False
-    vae_sp: bool = False
-
-    # `StableAudioMultiConditioner` owns its own T5; zero out the
-    # parent's text-encoder slots so the length-equality validator passes.
-    text_encoder_configs: tuple = field(default_factory=tuple)
-    preprocess_text_funcs: tuple = field(default_factory=tuple)
-    postprocess_text_funcs: tuple = field(default_factory=tuple)
-
-    num_inference_steps: int = 100
-    guidance_scale: float = 7.0
-    audio_end_in_s: float = 10.0  # short-clip default
-    audio_start_in_s: float = 0.0
-    sampling_rate: int = 44100
-    audio_channels: int = 2
-    # Stable Audio Open 1.0 was trained at a fixed 2,097,152-sample
-    # window (= 2097152 / 44100 ≈ 47.55s). Anything past this is
-    # silently truncated by the post-decode slice — validate up-front.
-    sample_size: int = 2097152
-    max_audio_duration_s: float = 2097152 / 44100
-
-    # Match the official `stable_audio_tools` defaults (`model_half=True`
-    # in `run_gradio.py`), which loads the DiT, VAE, and T5 in fp16 and
-    # wraps T5 forward in `autocast(fp16)`. fp16 is also a hard
-    # requirement for FlashAttention-2 / FA-3.
-    precision: str = "fp16"
-    vae_precision: str = "fp16"
-    text_encoder_precisions: tuple[str, ...] = field(default_factory=tuple)
-
-    def __post_init__(self) -> None:
-        # A2A needs encode; load both halves for either path.
-        self.vae_config.load_encoder = True
-        self.vae_config.load_decoder = True
-
-
-@dataclass
-class StableAudioOpenSmallConfig(StableAudioT2AConfig):
-    """`stable-audio-open-small` overrides: shorter training window
-    (524288 samples ≈ 11.89s @ 44.1 kHz) and a faster default sampler
-    config carried by the small preset.
-    """
-
-    sample_size: int = 524288
-    max_audio_duration_s: float = 524288 / 44100
-    audio_end_in_s: float = 6.0  # short-clip default suitable for the small window
@@ -3,8 +3,6 @@
 from fastvideo.entrypoints.cli.cli_types import CLISubcommand
 from fastvideo.entrypoints.cli.generate import cmd_init as generate_cmd_init
 from fastvideo.utils import FlexibleArgumentParser
-from fastvideo.entrypoints.cli.router_serve import (
-    cmd_init as router_serve_cmd_init, )
 from fastvideo.entrypoints.cli.serve import cmd_init as serve_cmd_init
 from fastvideo.entrypoints.cli.bench import cmd_init as bench_cmd_init

@@ -14,7 +12,6 @@ def cmd_init() -> list[CLISubcommand]:
    commands = []
    commands.extend(generate_cmd_init())
    commands.extend(serve_cmd_init())
-    commands.extend(router_serve_cmd_init())
    commands.extend(bench_cmd_init())
    return commands

@@ -1,115 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-"""``fastvideo router-serve`` CLI subcommand.
-
-Launches the streaming router from a YAML config. Separate from
-``fastvideo serve`` because the router is an orthogonal process: it
-fronts one or more running servers rather than hosting a generator
-itself.
-"""
-from __future__ import annotations
-
-import argparse
-import os
-from typing import cast
-
-from fastvideo.api.parser import load_raw_config
-from fastvideo.entrypoints.cli.cli_types import CLISubcommand
-from fastvideo.entrypoints.streaming.router.config import (
-    ReplicaEndpoint,
-    RouterConfig,
-)
-from fastvideo.logger import init_logger
-from fastvideo.utils import FlexibleArgumentParser
-
-logger = init_logger(__name__)
-
-
-class RouterServeSubcommand(CLISubcommand):
-    """Start the multi-replica WebSocket router."""
-
-    def __init__(self) -> None:
-        self.name = "router-serve"
-        super().__init__()
-
-    def cmd(self, args: argparse.Namespace) -> None:
-        config = _load_router_config(args.config)
-        logger.info(
-            "router listening on %s:%d (%d replicas, %d primary)",
-            config.host,
-            config.port,
-            len(config.replicas),
-            sum(1 for r in config.replicas if r.primary),
-        )
-        from fastvideo.entrypoints.streaming.router.main import run_router
-
-        run_router(config)
-
-    def validate(self, args: argparse.Namespace) -> None:
-        if not args.config:
-            raise ValueError("fastvideo router-serve requires --config PATH")
-        if not os.path.exists(args.config):
-            raise ValueError(f"Router config file not found: {args.config}")
-
-    def subparser_init(
-        self,
-        subparsers: argparse._SubParsersAction,
-    ) -> FlexibleArgumentParser:
-        parser = subparsers.add_parser(
-            "router-serve",
-            help="Start the streaming router (multi-replica load balancer)",
-            usage="fastvideo router-serve --config ROUTER_CONFIG",
-        )
-        parser.add_argument(
-            "--config",
-            type=str,
-            default="",
-            required=False,
-            help="Path to a YAML/JSON router config. Required.",
-        )
-        return cast(FlexibleArgumentParser, parser)
-
-
-def _load_router_config(path: str) -> RouterConfig:
-    raw = load_raw_config(path)
-    router_raw = raw.get("router") if isinstance(raw, dict) else None
-    if not isinstance(router_raw, dict):
-        raise ValueError(f"Router config {path!r} must have a top-level `router:` block")
-
-    replicas_raw = router_raw.get("replicas", [])
-    if not isinstance(replicas_raw, list):
-        raise ValueError(f"router.replicas must be a list, got {type(replicas_raw).__name__}")
-    replicas = []
-    for i, r in enumerate(replicas_raw):
-        if not isinstance(r, dict):
-            raise ValueError(f"router.replicas[{i}] must be a mapping, got {type(r).__name__}")
-        url = r.get("url")
-        if not url:
-            raise ValueError(f"router.replicas[{i}] is missing required key 'url'")
-        replicas.append(
-            ReplicaEndpoint(
-                url=url,
-                name=r.get("name"),
-                primary=bool(r.get("primary", False)),
-                weight=float(r.get("weight", 1.0)),
-            ))
-    if not replicas:
-        raise ValueError("Router config must list at least one replica under `router.replicas`")
-
-    health_check = router_raw.get("health_check") or {}
-    return RouterConfig(
-        host=str(router_raw.get("host", "0.0.0.0")),
-        port=int(router_raw.get("port", 9000)),
-        replicas=replicas,
-        health_check_path=str(health_check.get("path", "/health")),
-        health_check_interval_seconds=float(health_check.get("interval_seconds", 5.0)),
-        health_check_timeout_seconds=float(health_check.get("timeout_seconds", 2.0)),
-        failure_threshold=int(health_check.get("failure_threshold", 3)),
-        recovery_threshold=int(health_check.get("recovery_threshold", 2)),
-    )
-
-
-def cmd_init() -> list[CLISubcommand]:
-    return [RouterServeSubcommand()]
-
-
-__all__ = ["RouterServeSubcommand", "cmd_init"]
@@ -1,65 +1,4 @@
 # SPDX-License-Identifier: Apache-2.0
-from fastvideo.entrypoints.streaming.server import build_app, run_server
-from fastvideo.entrypoints.streaming.session import (
-    Session,
-    SessionManager,
-    SessionState,
-)
-from fastvideo.entrypoints.streaming.session_store import (
-    BlobStore,
-    InMemoryBlobStore,
-    InMemorySessionStore,
-    SessionStore,
-)
-from fastvideo.entrypoints.streaming.gpu_pool import (
-    GpuPool,
-    InProcessGpuPool,
-    PoolAcquireTimeout,
-    SubprocessGpuPool,
-)
-from fastvideo.entrypoints.streaming.mock_server import (
-    MockGenerator,
-    build_mock_app,
-)
-from fastvideo.entrypoints.streaming.prompt import (
-    LLMProvider,
-    PromptEnhancer,
-)
-from fastvideo.entrypoints.streaming.prompt.safety import (
-    PromptSafetyFilter,
-    SafetyDecision,
-)
-from fastvideo.entrypoints.streaming.session_logger import (
-    SessionLogEvent,
-    SessionLogger,
-)
-from fastvideo.entrypoints.streaming.stream import (
-    FragmentedMP4Chunk,
-    FragmentedMP4Encoder,
-)
+from fastvideo.entrypoints.streaming.server import run_server

-__all__ = [
-    "BlobStore",
-    "FragmentedMP4Chunk",
-    "FragmentedMP4Encoder",
-    "GpuPool",
-    "InMemoryBlobStore",
-    "InMemorySessionStore",
-    "InProcessGpuPool",
-    "LLMProvider",
-    "MockGenerator",
-    "PoolAcquireTimeout",
-    "PromptEnhancer",
-    "PromptSafetyFilter",
-    "SafetyDecision",
-    "SessionLogEvent",
-    "SessionLogger",
-    "build_mock_app",
-    "Session",
-    "SessionManager",
-    "SessionState",
-    "SessionStore",
-    "SubprocessGpuPool",
-    "build_app",
-    "run_server",
-]
+__all__ = ["run_server"]
@@ -1,542 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-"""GPU pool manager for the streaming server.
-
-Replaces the single-generator path in PR 7.5 with a typed pool
-abstraction. Three implementations ship here:
-
-* :class:`InProcessGpuPool` — one in-process ``VideoGenerator``; used
-  by tests and single-GPU dev deployments.
-* :class:`SubprocessGpuPool` — one ``multiprocessing.Process`` per
-  GPU, each running :func:`worker_main` against a ``GeneratorConfig``.
-  Jobs are dispatched via ``multiprocessing.Queue``.
-* :class:`GpuPool` (abstract) — the interface both use.
-
-Session-to-GPU binding lives in the pool so continuation state stays
-on the GPU that generated the previous segment (matching the internal
-``gpu_pool.py``'s per-GPU cache behavior). Cross-GPU handoff is
-supported via :class:`SessionStore` snapshot + hydrate, which
-serializes the state before the migration and rehydrates it on the
-new worker.
-
-Typed config: workers start from a :class:`GeneratorConfig` (no flat
-LTX-2 kwargs), satisfying the PR 6 + PR 7 contracts that the public
-surface doesn't reintroduce the legacy kwarg bag.
-"""
-from __future__ import annotations
-
-import asyncio
-import multiprocessing as mp
-import queue
-import threading
-import time
-import uuid
-from abc import ABC, abstractmethod
-from concurrent.futures import Future
-from dataclasses import dataclass, field
-from typing import Any, Protocol
-
-from fastvideo.api.schema import (
-    GeneratorConfig,
-    GenerationRequest,
-    GpuPoolConfig,
-    WarmupConfig,
-)
-from fastvideo.entrypoints.streaming.session_store import (
-    InMemorySessionStore,
-    SessionStore,
-)
-from fastvideo.entrypoints.streaming.worker import worker_main
-from fastvideo.logger import init_logger
-
-logger = init_logger(__name__)
-
-# ---------------------------------------------------------------------------
-# Public interface
-# ---------------------------------------------------------------------------
-
-
-class _GeneratorLike(Protocol):
-    """Subset the pool calls on a worker-side generator."""
-
-    def generate(self, request: GenerationRequest) -> Any:
-        ...
-
-
-@dataclass
-class PoolAssignment:
-    """The worker a session is currently bound to."""
-
-    gpu_id: int
-    worker_id: str
-    pinned_at: float = field(default_factory=time.monotonic)
-
-
-class GpuPool(ABC):
-    """Abstract GPU pool.
-
-    ``acquire`` binds a session to a worker and holds that binding
-    across segments so continuation state can stay hot. ``run`` submits
-    a single ``GenerationRequest`` for a bound session.
-
-    Acquire / release are independent of run — a session can run many
-    segments on one acquired worker, and must release on disconnect.
-    """
-
-    @abstractmethod
-    async def acquire(
-        self,
-        session_id: str,
-        *,
-        timeout: float | None = None,
-    ) -> PoolAssignment:
-        ...
-
-    @abstractmethod
-    async def run(
-        self,
-        session_id: str,
-        request: GenerationRequest,
-    ) -> Any:
-        ...
-
-    @abstractmethod
-    async def release(self, session_id: str) -> None:
-        ...
-
-    @abstractmethod
-    async def shutdown(self) -> None:
-        ...
-
-    @abstractmethod
-    def health(self) -> PoolHealth:
-        ...
-
-
-@dataclass
-class PoolHealth:
-    total_workers: int
-    available_workers: int
-    active_sessions: int
-    queued_sessions: int = 0
-
-
-class PoolAcquireTimeout(RuntimeError):
-    """Raised when ``acquire`` times out waiting for a free worker."""
-
-
-# ---------------------------------------------------------------------------
-# In-process implementation (single-worker, test / dev)
-# ---------------------------------------------------------------------------
-
-
-class InProcessGpuPool(GpuPool):
-    """Single-process pool backed by one :class:`_GeneratorLike`.
-
-    This is what PR 7.5's server uses by default; PR 7.6 adds the real
-    ``SubprocessGpuPool`` alternative but keeps this one for tests and
-    small deployments.
-    """
-
-    def __init__(
-        self,
-        generator: _GeneratorLike,
-        *,
-        gpu_id: int = 0,
-        session_store: SessionStore | None = None,
-    ) -> None:
-        self._generator = generator
-        self._gpu_id = gpu_id
-        self._worker_id = f"inproc-{uuid.uuid4().hex[:6]}"
-        self._session_store = session_store or InMemorySessionStore()
-        self._active: dict[str, PoolAssignment] = {}
-        self._lock = asyncio.Lock()
-        self._gen_lock = asyncio.Lock()
-
-    async def acquire(
-        self,
-        session_id: str,
-        *,
-        timeout: float | None = None,
-    ) -> PoolAssignment:
-        async with self._lock:
-            existing = self._active.get(session_id)
-            if existing is not None:
-                return existing
-            assignment = PoolAssignment(gpu_id=self._gpu_id, worker_id=self._worker_id)
-            self._active[session_id] = assignment
-            return assignment
-
-    async def run(
-        self,
-        session_id: str,
-        request: GenerationRequest,
-    ) -> Any:
-        if session_id not in self._active:
-            raise RuntimeError(f"session {session_id!r} is not acquired on this pool")
-        # Serialize generator access so one GPU runs one request at a
-        # time, matching the internal gpu_pool's per-GPU lock.
-        async with self._gen_lock:
-            loop = asyncio.get_running_loop()
-            return await loop.run_in_executor(None, self._generator.generate, request)
-
-    async def release(self, session_id: str) -> None:
-        async with self._lock:
-            self._active.pop(session_id, None)
-
-    async def shutdown(self) -> None:
-        self._active.clear()
-
-    def health(self) -> PoolHealth:
-        return PoolHealth(
-            total_workers=1,
-            available_workers=1 if not self._active else 0,
-            active_sessions=len(self._active),
-        )
-
-
-# ---------------------------------------------------------------------------
-# Subprocess implementation (multi-worker, real deployment)
-# ---------------------------------------------------------------------------
-
-
-@dataclass
-class _WorkerHandle:
-    process: Any  # mp.Process or compatible handle with is_alive / join / kill
-    job_queue: mp.Queue
-    result_queue: mp.Queue
-    gpu_id: int
-    worker_id: str
-    ready: threading.Event
-    # ``ready`` flips on either successful boot or boot failure so the
-    # parent stops waiting; ``boot_ok`` is set only on a real ready
-    # acknowledgement and is what gates pool admission.
-    boot_ok: threading.Event
-    shutdown_event: Any  # mp.Event is a factory, not a type — Any keeps mypy sane
-
-
-@dataclass
-class _PendingJob:
-    job_id: str
-    future: Future
-    session_id: str
-    worker_id: str
-
-
-class SubprocessGpuPool(GpuPool):
-    """One ``multiprocessing.Process`` per GPU.
-
-    Each worker boots :class:`fastvideo.VideoGenerator` from a typed
-    :class:`GeneratorConfig` inside the child process (post-
-    ``CUDA_VISIBLE_DEVICES`` setup) and consumes jobs from an mp Queue.
-
-    This is the production shape: the parent process stays CPU-only, and
-    GPU state never crosses process boundaries. Continuation state is
-    serialized through :class:`SessionStore` for cross-GPU handoff.
-
-    PR 7.6 ships this as an opt-in; PR 7.5's in-process pool remains the
-    default until nightly runs validate the subprocess path.
-    """
-
-    def __init__(
-        self,
-        generator_config: GeneratorConfig,
-        *,
-        pool_config: GpuPoolConfig,
-        warmup_config: WarmupConfig | None = None,
-        session_store: SessionStore | None = None,
-        worker_factory: WorkerFactory | None = None,
-    ) -> None:
-        self._generator_config = generator_config
-        self._pool_config = pool_config
-        self._warmup_config = warmup_config or WarmupConfig()
-        self._session_store = session_store or InMemorySessionStore()
-        self._worker_factory = worker_factory or _default_worker_factory
-        self._workers: list[_WorkerHandle] = []
-        self._available: asyncio.Queue[int] = asyncio.Queue()
-        self._assignments: dict[str, PoolAssignment] = {}
-        self._worker_by_id: dict[str, _WorkerHandle] = {}
-        self._pending: dict[str, _PendingJob] = {}
-        self._lock = asyncio.Lock()
-        self._result_reader_tasks: list[asyncio.Task] = []
-
-    async def start(self) -> None:
-        """Spawn worker processes and wait for each to report ready."""
-        num_workers = self._pool_config.num_workers or 1
-        for gpu_id in range(num_workers):
-            handle = self._worker_factory(
-                gpu_id=gpu_id,
-                generator_config=self._generator_config,
-                warmup_config=self._warmup_config,
-            )
-            self._workers.append(handle)
-            self._worker_by_id[handle.worker_id] = handle
-
-        # Wait for each worker's ready event in a thread to avoid
-        # blocking the event loop.
-        loop = asyncio.get_running_loop()
-        await asyncio.gather(*[
-            loop.run_in_executor(None, handle.ready.wait, self._warmup_config.timeout_seconds)
-            for handle in self._workers
-        ])
-
-        # Start background result readers — one task per worker
-        # drains its result queue and resolves futures in _pending.
-        for handle in self._workers:
-            task = asyncio.create_task(self._drain_results(handle))
-            self._result_reader_tasks.append(task)
-
-        # Only admit workers that successfully booted. Anything that
-        # failed boot (timeout, crash, error sentinel) stays out of the
-        # available queue so we never assign a session to it.
-        for idx, handle in enumerate(self._workers):
-            if handle.boot_ok.is_set():
-                await self._available.put(idx)
-            else:
-                logger.error(
-                    "pool: worker %s failed to boot; skipping",
-                    handle.worker_id,
-                )
-
-    async def acquire(
-        self,
-        session_id: str,
-        *,
-        timeout: float | None = None,
-    ) -> PoolAssignment:
-        async with self._lock:
-            existing = self._assignments.get(session_id)
-            if existing is not None:
-                return existing
-        try:
-            idx = await asyncio.wait_for(self._available.get(), timeout=timeout)
-        except asyncio.TimeoutError as exc:
-            raise PoolAcquireTimeout(f"no worker available after {timeout}s") from exc
-        handle = self._workers[idx]
-        assignment = PoolAssignment(gpu_id=handle.gpu_id, worker_id=handle.worker_id)
-        async with self._lock:
-            self._assignments[session_id] = assignment
-        return assignment
-
-    async def run(
-        self,
-        session_id: str,
-        request: GenerationRequest,
-    ) -> Any:
-        assignment = self._assignments.get(session_id)
-        if assignment is None:
-            raise RuntimeError(f"session {session_id!r} not acquired on this pool")
-        handle = self._worker_by_id[assignment.worker_id]
-        job_id = uuid.uuid4().hex
-        future: Future = Future()
-        self._pending[job_id] = _PendingJob(
-            job_id=job_id,
-            future=future,
-            session_id=session_id,
-            worker_id=handle.worker_id,
-        )
-        # mp.Queue.put can block if the underlying pipe buffer is full;
-        # offload to a thread so the event loop keeps serving other
-        # sessions. If the put itself fails, drop the pending entry so
-        # _drain_results doesn't dangle a future forever.
-        loop = asyncio.get_running_loop()
-        try:
-            await loop.run_in_executor(
-                None,
-                handle.job_queue.put,
-                {
-                    "job_id": job_id,
-                    "request": request
-                },
-            )
-        except Exception:
-            self._pending.pop(job_id, None)
-            raise
-        return await asyncio.wrap_future(future)
-
-    async def release(self, session_id: str) -> None:
-        async with self._lock:
-            assignment = self._assignments.pop(session_id, None)
-        if assignment is None:
-            return
-        idx = next((i for i, h in enumerate(self._workers) if h.worker_id == assignment.worker_id), None)
-        if idx is None:
-            return
-        # Don't return a dead worker to the pool; otherwise the next
-        # acquire will hand a session to a process that can't run jobs.
-        if not self._workers[idx].process.is_alive():
-            logger.warning(
-                "pool: worker %s died; not returning to available queue",
-                self._workers[idx].worker_id,
-            )
-            return
-        await self._available.put(idx)
-
-    async def shutdown(self) -> None:
-        loop = asyncio.get_running_loop()
-
-        # Signal all workers in parallel; .put may block on a full pipe,
-        # so off-load it the same way run() does.
-        async def _signal(handle: _WorkerHandle) -> None:
-            try:
-                handle.shutdown_event.set()
-                await loop.run_in_executor(None, handle.job_queue.put, None)
-            except Exception:  # pragma: no cover - best-effort cleanup
-                pass
-
-        await asyncio.gather(*(_signal(h) for h in self._workers))
-        # Join in parallel so total shutdown is bounded by the slowest
-        # worker, not the sum of all timeouts.
-        await asyncio.gather(*(loop.run_in_executor(None, handle.process.join, 5.0) for handle in self._workers))
-        for handle in self._workers:
-            if handle.process.is_alive():
-                handle.process.kill()
-        for task in self._result_reader_tasks:
-            task.cancel()
-        self._result_reader_tasks.clear()
-        self._workers.clear()
-        self._worker_by_id.clear()
-
-    def health(self) -> PoolHealth:
-        return PoolHealth(
-            total_workers=len(self._workers),
-            available_workers=self._available.qsize(),
-            active_sessions=len(self._assignments),
-        )
-
-    async def _drain_results(self, handle: _WorkerHandle) -> None:
-        loop = asyncio.get_running_loop()
-        try:
-            while not handle.shutdown_event.is_set():
-                try:
-                    msg = await loop.run_in_executor(None, _safe_queue_get, handle.result_queue, 0.5)
-                except Exception:
-                    logger.exception("pool: worker %s result reader failed", handle.worker_id)
-                    return
-                if msg is None:
-                    continue
-                job_id = msg.get("job_id")
-                if job_id is None:
-                    continue
-                pending = self._pending.pop(job_id, None)
-                if pending is None:
-                    continue
-                if msg.get("kind") == "error":
-                    pending.future.set_exception(RuntimeError(msg["error"]))
-                else:
-                    pending.future.set_result(msg.get("result"))
-        finally:
-            # If we exit for any reason — shutdown, exception, cancel —
-            # surface that to any in-flight jobs on this worker so their
-            # await never hangs on a future no one will resolve.
-            for jid in [jid for jid, job in self._pending.items() if job.worker_id == handle.worker_id]:
-                pending = self._pending.pop(jid, None)
-                if pending is not None and not pending.future.done():
-                    pending.future.set_exception(
-                        RuntimeError(f"worker {handle.worker_id} result reader exited "
-                                     "with pending jobs"))
-
-
-def _safe_queue_get(q: mp.Queue, timeout: float) -> Any | None:
-    try:
-        return q.get(timeout=timeout)
-    except queue.Empty:
-        return None
-
-
-# ---------------------------------------------------------------------------
-# Worker process
-# ---------------------------------------------------------------------------
-
-
-class WorkerFactory(Protocol):
-
-    def __call__(
-        self,
-        *,
-        gpu_id: int,
-        generator_config: GeneratorConfig,
-        warmup_config: WarmupConfig,
-    ) -> _WorkerHandle:
-        ...
-
-
-def _default_worker_factory(
-    *,
-    gpu_id: int,
-    generator_config: GeneratorConfig,
-    warmup_config: WarmupConfig,
-) -> _WorkerHandle:
-    """Spawn a real multiprocessing worker.
-
-    The child process calls :func:`worker_main` which constructs a
-    :class:`VideoGenerator` from ``generator_config`` and runs a
-    blocking job loop. The ``ready`` event flips after the warmup
-    request completes.
-    """
-    ctx = mp.get_context("spawn")
-    job_queue: mp.Queue = ctx.Queue()
-    result_queue: mp.Queue = ctx.Queue()
-    ready = threading.Event()
-    boot_ok = threading.Event()
-    shutdown_event = ctx.Event()
-    worker_id = f"gpu{gpu_id}-{uuid.uuid4().hex[:6]}"
-    process = ctx.Process(
-        target=worker_main,
-        kwargs={
-            "gpu_id": gpu_id,
-            "worker_id": worker_id,
-            "generator_config": generator_config,
-            "warmup_config": warmup_config,
-            "job_queue": job_queue,
-            "result_queue": result_queue,
-            "shutdown_event": shutdown_event,
-        },
-        daemon=False,
-    )
-    process.start()
-
-    # Block the parent-side ``ready`` flag until the worker posts a
-    # ready acknowledgement on the result queue. We drain that single
-    # sentinel here; subsequent results belong to jobs. ``boot_ok``
-    # only flips on a real ready; on error we set ``ready`` to unblock
-    # the parent's wait but leave ``boot_ok`` clear so the pool keeps
-    # the worker out of the available queue.
-    def _await_ready() -> None:
-        while not shutdown_event.is_set():
-            try:
-                msg = result_queue.get(timeout=1.0)
-            except queue.Empty:
-                continue
-            if isinstance(msg, dict) and msg.get("kind") == "ready":
-                boot_ok.set()
-                ready.set()
-                return
-            if isinstance(msg, dict) and msg.get("kind") == "error":
-                logger.error("pool: worker %s failed to boot: %s", worker_id, msg.get("error"))
-                ready.set()
-                return
-
-    threading.Thread(target=_await_ready, daemon=True).start()
-
-    return _WorkerHandle(
-        process=process,
-        job_queue=job_queue,
-        result_queue=result_queue,
-        gpu_id=gpu_id,
-        worker_id=worker_id,
-        ready=ready,
-        boot_ok=boot_ok,
-        shutdown_event=shutdown_event,
-    )
-
-
-__all__ = [
-    "GpuPool",
-    "InProcessGpuPool",
-    "PoolAcquireTimeout",
-    "PoolAssignment",
-    "PoolHealth",
-    "SubprocessGpuPool",
-    "WorkerFactory",
-    "worker_main",
-]
@@ -1,122 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-"""Mock streaming server — a frontend dev aid.
-
-Boots the same FastAPI app the real streaming server uses, but backs
-it with :class:`InProcessGpuPool` wrapping a synthetic generator that
-emits pre-baked RGB frames. No GPU or model weights required.
-
-Use cases:
-
-* Frontend development without a real model loaded.
-* Integration tests that exercise the WS protocol end-to-end.
-* Reproducing protocol bugs locally.
-
-Launch: ``python -m fastvideo.entrypoints.streaming.mock_server``.
-"""
-from __future__ import annotations
-
-import argparse
-import time
-from dataclasses import dataclass
-from typing import Any
-
-import numpy as np
-
-from fastvideo.api.schema import (
-    ContinuationState,
-    GenerationRequest,
-    GeneratorConfig,
-    SamplingConfig,
-    ServeConfig,
-    StreamingConfig,
-)
-from fastvideo.entrypoints.streaming.server import build_app
-
-
-@dataclass
-class MockGenerator:
-    """Generator stand-in that returns synthetic gradient frames.
-
-    Each call produces one segment worth of frames whose pixels vary by
-    a constant derived from the request seed and segment index. Latency
-    is configurable via ``sleep_ms`` so the caller can exercise slow-
-    generate scenarios without spinning a GPU.
-    """
-
-    sleep_ms: float = 0.0
-
-    def generate(self, request: GenerationRequest) -> dict[str, Any]:
-        if self.sleep_ms:
-            time.sleep(self.sleep_ms / 1000.0)
-        width = max(16, request.sampling.width)
-        height = max(16, request.sampling.height)
-        num_frames = max(1, request.sampling.num_frames)
-        frames = [_gradient_frame(height, width, idx, seed=request.sampling.seed) for idx in range(num_frames)]
-        state = ContinuationState(
-            kind="ltx2.v1",
-            payload={
-                "schema_version": 1,
-                "segment_index": 0,
-                "source_prompt": request.prompt,
-            },
-        )
-        return {
-            "frames": frames,
-            "audio_sample_rate": 24000,
-            "state": state,
-        }
-
-
-def _gradient_frame(height: int, width: int, idx: int, *, seed: int) -> np.ndarray:
-    base = (idx * 17 + seed * 3) % 256
-    row = np.linspace(base, (base + 64) % 256, width, dtype=np.uint8)
-    frame = np.tile(row, (height, 1))
-    stacked = np.stack([frame, np.roll(frame, 8, axis=1), np.roll(frame, 16, axis=1)], axis=-1)
-    return stacked.astype(np.uint8)
-
-
-def build_mock_app(*, sleep_ms: float = 0.0):
-    """Build a FastAPI app backed by :class:`MockGenerator`."""
-    serve_config = ServeConfig(
-        generator=GeneratorConfig(model_path="/models/mock"),
-        streaming=StreamingConfig(
-            session_timeout_seconds=120,
-            generation_segment_cap=6,
-        ),
-    )
-    serve_config.default_request.sampling = SamplingConfig(
-        num_frames=24,
-        height=256,
-        width=256,
-        fps=24,
-        num_inference_steps=1,
-    )
-    return build_app(serve_config, MockGenerator(sleep_ms=sleep_ms))
-
-
-def main() -> None:  # pragma: no cover - CLI entry
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("--host", default="127.0.0.1")
-    parser.add_argument("--port", type=int, default=8000)
-    parser.add_argument(
-        "--sleep-ms",
-        type=float,
-        default=0.0,
-        help="Per-segment artificial latency for testing slow paths",
-    )
-    args = parser.parse_args()
-
-    import uvicorn
-
-    app = build_mock_app(sleep_ms=args.sleep_ms)
-    uvicorn.run(app, host=args.host, port=args.port)
-
-
-__all__ = [
-    "MockGenerator",
-    "build_mock_app",
-    "main",
-]
-
-if __name__ == "__main__":  # pragma: no cover - CLI entry
-    main()
@@ -1,36 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-"""Prompt pipeline for the streaming server.
-
-* :mod:`providers` — LLM backend abstraction + built-in adapters
-* :mod:`enhancer` — provider-agnostic enhance / auto-extend / rewrite
-  operations on top of the provider layer
-
-All of this is optional; the streaming server runs fine without it
-(PR 7.5's skeleton never invokes the enhancer). When the operator
-enables ``ServeConfig.streaming.prompt.enabled``, the server routes
-each ``session_init_v2`` curated prompt through ``enhance`` before the
-first segment.
-"""
-from fastvideo.entrypoints.streaming.prompt.enhancer import (
-    PromptEnhancer,
-    PromptOperation,
-)
-from fastvideo.entrypoints.streaming.prompt.providers.base import (
-    LLMMessage,
-    LLMProvider,
-    LLMProviderError,
-    LLMRequest,
-    LLMResponse,
-    LLMTimeoutError,
-)
-
-__all__ = [
-    "LLMMessage",
-    "LLMProvider",
-    "LLMProviderError",
-    "LLMRequest",
-    "LLMResponse",
-    "LLMTimeoutError",
-    "PromptEnhancer",
-    "PromptOperation",
-]
@@ -1,197 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-"""Provider-agnostic prompt orchestration for the streaming server.
-
-Three operations the streaming server needs:
-
-* ``enhance`` — polish a user prompt (add cinematic detail, fix syntax)
-* ``auto_extend`` — generate a follow-on prompt for loop generation
-* ``rewrite`` — rewrite a seed prompt for a user-directed rewrite flow
-
-All three share the same orchestration: pick a provider in priority
-order, submit an ``LLMRequest``, fall back to the next provider on
-retryable errors, and surface a structured :class:`LLMResponse` back
-to the caller.
-
-System prompts are loaded from ``system_prompt_dir`` on construction
-and can be hot-reloaded via :meth:`PromptEnhancer.reload_system_prompts`.
-The streaming server's management endpoint calls that method in
-response to a ``rewrite_seed_prompts_started`` frame.
-"""
-from __future__ import annotations
-
-import enum
-import os
-from collections.abc import Sequence
-from dataclasses import dataclass, replace
-
-from fastvideo.entrypoints.streaming.prompt.providers.base import (
-    LLMMessage,
-    LLMProvider,
-    LLMProviderError,
-    LLMRequest,
-    LLMResponse,
-)
-from fastvideo.logger import init_logger
-
-logger = init_logger(__name__)
-
-
-class PromptOperation(enum.Enum):
-    ENHANCE = "enhance"
-    AUTO_EXTEND = "auto_extend"
-    REWRITE = "rewrite"
-
-
-@dataclass
-class _SystemPrompts:
-    enhance: str
-    auto_extend: str
-    rewrite: str
-
-
-_DEFAULT_SYSTEM_PROMPTS = _SystemPrompts(
-    enhance=("You are a prompt enhancer for cinematic video generation. Given "
-             "a user prompt, produce an enhanced prompt that is more vivid, "
-             "specific, and concrete. Keep the subject intact; add lighting, "
-             "camera, and motion detail. Reply with just the enhanced prompt."),
-    auto_extend=("You are a video continuation assistant. Given the current "
-                 "sequence of prompts, produce one new prompt that naturally "
-                 "continues the sequence. Reply with just the next prompt."),
-    rewrite=("You are a creative prompt rewriter. Given a seed prompt, produce "
-             "a set of alternative prompts that explore different angles, "
-             "styles, and moods. Reply with one prompt per line."),
-)
-
-
-class PromptEnhancer:
-    """Orchestrates prompt operations across a priority-ordered provider
-    list with structured fallback + hot-reloadable system prompts.
-
-    Usage::
-
-        enhancer = PromptEnhancer(
-            providers=[CerebrasProvider(), GroqProvider()],
-            model="gpt-oss-120b",
-            system_prompt_dir="/etc/fastvideo/prompts",
-        )
-        response = await enhancer.enhance("a fox running through snow")
-    """
-
-    def __init__(
-        self,
-        *,
-        providers: Sequence[LLMProvider],
-        model: str,
-        timeout_ms: int = 20000,
-        temperature: float = 0.7,
-        max_tokens: int | None = 256,
-        system_prompt_dir: str | None = None,
-    ) -> None:
-        if not providers:
-            raise ValueError("PromptEnhancer requires at least one LLMProvider")
-        self._providers = list(providers)
-        self._model = model
-        self._timeout_ms = timeout_ms
-        self._temperature = temperature
-        self._max_tokens = max_tokens
-        self._system_prompt_dir = system_prompt_dir
-        self._system_prompts = self._load_system_prompts()
-
-    @property
-    def providers(self) -> list[LLMProvider]:
-        return list(self._providers)
-
-    def register_provider(self, provider: LLMProvider, *, priority: int = -1) -> None:
-        """Insert an additional provider. ``priority=0`` makes it primary;
-        ``priority=-1`` (default) appends as a fallback."""
-        if priority < 0:
-            self._providers.append(provider)
-        else:
-            self._providers.insert(priority, provider)
-
-    def reload_system_prompts(self) -> None:
-        """Re-read the system prompt files from ``system_prompt_dir``.
-
-        The streaming server exposes this via a management endpoint so
-        operators can iterate on prompt templates without restarting
-        workers.
-        """
-        self._system_prompts = self._load_system_prompts()
-        logger.info("prompt enhancer: reloaded system prompts from %s", self._system_prompt_dir or "defaults")
-
-    async def enhance(self, prompt: str) -> LLMResponse:
-        return await self._run(
-            PromptOperation.ENHANCE,
-            system=self._system_prompts.enhance,
-            user=prompt,
-        )
-
-    async def auto_extend(self, prior_prompts: Sequence[str]) -> LLMResponse:
-        user = "\n".join(prior_prompts)
-        return await self._run(
-            PromptOperation.AUTO_EXTEND,
-            system=self._system_prompts.auto_extend,
-            user=user,
-        )
-
-    async def rewrite(self, seed_prompt: str) -> LLMResponse:
-        return await self._run(
-            PromptOperation.REWRITE,
-            system=self._system_prompts.rewrite,
-            user=seed_prompt,
-        )
-
-    async def _run(
-        self,
-        operation: PromptOperation,
-        *,
-        system: str,
-        user: str,
-    ) -> LLMResponse:
-        request = LLMRequest(
-            messages=[
-                LLMMessage(role="system", content=system),
-                LLMMessage(role="user", content=user),
-            ],
-            model=self._model,
-            max_tokens=self._max_tokens,
-            temperature=self._temperature,
-            timeout_ms=self._timeout_ms,
-        )
-        last_error: LLMProviderError | None = None
-        for idx, provider in enumerate(self._providers):
-            try:
-                response = await provider.complete(request)
-                if idx > 0:
-                    # Mark the fallback flag without losing any other
-                    # response fields the provider populated.
-                    response = replace(response, fallback_used=True)
-                return response
-            except LLMProviderError as exc:
-                logger.warning("prompt %s: provider %s failed: %s; trying next", operation.value, provider.name, exc)
-                last_error = exc
-                if not exc.retryable:
-                    break
-        assert last_error is not None
-        raise last_error
-
-    def _load_system_prompts(self) -> _SystemPrompts:
-        if not self._system_prompt_dir:
-            return _DEFAULT_SYSTEM_PROMPTS
-        return _SystemPrompts(
-            enhance=_read_prompt(self._system_prompt_dir, "enhance.txt", _DEFAULT_SYSTEM_PROMPTS.enhance),
-            auto_extend=_read_prompt(self._system_prompt_dir, "auto_extend.txt", _DEFAULT_SYSTEM_PROMPTS.auto_extend),
-            rewrite=_read_prompt(self._system_prompt_dir, "rewrite.txt", _DEFAULT_SYSTEM_PROMPTS.rewrite),
-        )
-
-
-def _read_prompt(dirname: str, filename: str, default: str) -> str:
-    path = os.path.join(dirname, filename)
-    if not os.path.exists(path):
-        return default
-    with open(path, encoding="utf-8") as f:
-        content = f.read().strip()
-    return content or default
-
-
-__all__ = ["PromptEnhancer", "PromptOperation"]
@@ -1,24 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-"""LLM provider implementations used by the prompt enhancer."""
-from fastvideo.entrypoints.streaming.prompt.providers.base import (
-    LLMMessage,
-    LLMProvider,
-    LLMProviderError,
-    LLMRequest,
-    LLMResponse,
-    LLMTimeoutError,
-)
-from fastvideo.entrypoints.streaming.prompt.providers.cerebras import (
-    CerebrasProvider, )
-from fastvideo.entrypoints.streaming.prompt.providers.groq import GroqProvider
-
-__all__ = [
-    "CerebrasProvider",
-    "GroqProvider",
-    "LLMMessage",
-    "LLMProvider",
-    "LLMProviderError",
-    "LLMRequest",
-    "LLMResponse",
-    "LLMTimeoutError",
-]
@@ -1,101 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-"""Shared HTTP path for OpenAI-compatible ``/chat/completions`` providers.
-
-Cerebras and Groq both expose the OpenAI chat-completions schema, so
-the request shape, error mapping, and response decoding are identical
-between them. This module centralizes that logic; the per-provider
-modules stay thin (just defaults + env var wiring).
-"""
-from __future__ import annotations
-
-import time
-
-from fastvideo.entrypoints.streaming.prompt.providers.base import (
-    LLMProviderError,
-    LLMRequest,
-    LLMResponse,
-    LLMTimeoutError,
-)
-
-
-async def complete_openai_compatible(
-    *,
-    api_key: str | None,
-    api_key_hint: str,
-    base_url: str,
-    provider_name: str,
-    request: LLMRequest,
-) -> LLMResponse:
-    """Issue a chat-completions call and decode the OpenAI response."""
-    if not api_key:
-        raise LLMProviderError(
-            f"{provider_name} provider requires {api_key_hint} "
-            "(or explicit api_key=...)",
-            retryable=False,
-        )
-    try:
-        import httpx
-    except ImportError as exc:  # pragma: no cover - optional dep
-        raise LLMProviderError(
-            f"{provider_name} provider requires httpx; install httpx",
-            retryable=False,
-        ) from exc
-
-    timeout_s = (request.timeout_ms or 20000) / 1000.0
-    t0 = time.perf_counter()
-    try:
-        async with httpx.AsyncClient(timeout=timeout_s) as client:
-            response = await client.post(
-                f"{base_url}/chat/completions",
-                headers={
-                    "Authorization": f"Bearer {api_key}",
-                    "Content-Type": "application/json",
-                },
-                json={
-                    "model": request.model,
-                    "messages": [{
-                        "role": m.role,
-                        "content": m.content
-                    } for m in request.messages],
-                    "max_tokens": request.max_tokens,
-                    "temperature": request.temperature,
-                },
-            )
-    except httpx.TimeoutException as exc:
-        raise LLMTimeoutError(f"{provider_name} timed out after {timeout_s}s") from exc
-    except httpx.HTTPError as exc:
-        raise LLMProviderError(f"{provider_name} HTTP error: {exc}") from exc
-
-    if response.status_code >= 400:
-        # 5xx and 429 (rate-limit) are retryable: another provider may
-        # succeed. 4xx (auth, bad-request, etc.) are client errors —
-        # the enhancer should stop fallback traversal.
-        retryable = (response.status_code >= 500 or response.status_code == 429)
-        raise LLMProviderError(
-            f"{provider_name} returned {response.status_code}: "
-            f"{response.text[:200]}",
-            retryable=retryable,
-        )
-
-    try:
-        data = response.json()
-    except Exception as exc:
-        # Non-JSON body usually means a proxy / load-balancer error
-        # page; leave it retryable so a fallback provider can try.
-        raise LLMProviderError(f"{provider_name} returned non-JSON body: {exc}") from exc
-
-    choices = data.get("choices") or []
-    if not choices:
-        raise LLMProviderError(f"{provider_name} returned no choices")
-    content = choices[0].get("message", {}).get("content") or ""
-
-    latency_ms = (time.perf_counter() - t0) * 1000.0
-    return LLMResponse(
-        content=content.strip(),
-        provider=provider_name,
-        model=request.model,
-        latency_ms=latency_ms,
-    )
-
-
-__all__ = ["complete_openai_compatible"]
@@ -1,85 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-"""LLM provider protocol + DTOs used by the prompt enhancer.
-
-Third-party users add a new provider by implementing
-:class:`LLMProvider` and registering it with a prompt enhancer
-instance. The shipped providers live in sibling modules
-(``cerebras.py``, ``groq.py``) and each is ~100-200 LOC — the
-provider layer is intentionally thin so the enhancer stays
-provider-agnostic.
-"""
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import Literal, Protocol, runtime_checkable
-
-
-@dataclass
-class LLMMessage:
-    role: Literal["system", "user", "assistant"]
-    content: str
-
-
-@dataclass
-class LLMRequest:
-    messages: list[LLMMessage]
-    model: str
-    max_tokens: int | None = None
-    temperature: float | None = None
-    timeout_ms: int | None = None
-
-
-@dataclass
-class LLMResponse:
-    content: str
-    provider: str
-    model: str
-    latency_ms: float
-    fallback_used: bool = False
-
-
-class LLMProviderError(RuntimeError):
-    """Raised when an LLM provider fails a request.
-
-    ``retryable`` controls whether the enhancer falls back to the next
-    provider. It is settable per-instance so the same exception type
-    can describe retryable transport errors (5xx, 429) and
-    non-retryable client errors (4xx auth/bad-request) without forcing
-    a separate subclass for every status family.
-    """
-
-    def __init__(self, message: str, *, retryable: bool = True) -> None:
-        super().__init__(message)
-        self.retryable = retryable
-
-
-class LLMTimeoutError(LLMProviderError):
-    """Raised when an LLM provider times out — always retryable."""
-
-    def __init__(self, message: str) -> None:
-        super().__init__(message, retryable=True)
-
-
-@runtime_checkable
-class LLMProvider(Protocol):
-    """Provider interface every LLM adapter implements.
-
-    Providers are async-first because every built-in implementation
-    talks to an HTTP API. Synchronous providers can wrap their call in
-    ``asyncio.to_thread`` internally.
-    """
-
-    name: str
-
-    async def complete(self, request: LLMRequest) -> LLMResponse:
-        ...
-
-
-__all__ = [
-    "LLMMessage",
-    "LLMProvider",
-    "LLMProviderError",
-    "LLMRequest",
-    "LLMResponse",
-    "LLMTimeoutError",
-]
@@ -1,44 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-"""Cerebras LLM provider (OpenAI-compatible chat endpoint)."""
-from __future__ import annotations
-
-import os
-from dataclasses import dataclass
-
-from fastvideo.entrypoints.streaming.prompt.providers._openai_compat import (
-    complete_openai_compatible, )
-from fastvideo.entrypoints.streaming.prompt.providers.base import (
-    LLMRequest,
-    LLMResponse,
-)
-
-_DEFAULT_BASE_URL = "https://api.cerebras.ai/v1"
-_API_KEY_ENV = "CEREBRAS_API_KEY"
-
-
-@dataclass
-class CerebrasProvider:
-    """Cerebras inference adapter.
-
-    ``api_key`` falls back to ``CEREBRAS_API_KEY`` when unset.
-    """
-
-    api_key: str | None = None
-    base_url: str = _DEFAULT_BASE_URL
-    name: str = "cerebras"
-
-    def __post_init__(self) -> None:
-        if self.api_key is None:
-            self.api_key = os.environ.get(_API_KEY_ENV)
-
-    async def complete(self, request: LLMRequest) -> LLMResponse:
-        return await complete_openai_compatible(
-            api_key=self.api_key,
-            api_key_hint=_API_KEY_ENV,
-            base_url=self.base_url,
-            provider_name=self.name,
-            request=request,
-        )
-
-
-__all__ = ["CerebrasProvider"]
@@ -1,46 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-"""Groq LLM provider (OpenAI-compatible chat endpoint)."""
-from __future__ import annotations
-
-import os
-from dataclasses import dataclass
-
-from fastvideo.entrypoints.streaming.prompt.providers._openai_compat import (
-    complete_openai_compatible, )
-from fastvideo.entrypoints.streaming.prompt.providers.base import (
-    LLMRequest,
-    LLMResponse,
-)
-
-_DEFAULT_BASE_URL = "https://api.groq.com/openai/v1"
-_API_KEY_ENV = "GROQ_API_KEY"
-
-
-@dataclass
-class GroqProvider:
-    """Groq inference adapter.
-
-    Identical wire format to :class:`CerebrasProvider`; both go through
-    :func:`complete_openai_compatible`. The two providers differ only
-    in base URL, env var, and model id conventions.
-    """
-
-    api_key: str | None = None
-    base_url: str = _DEFAULT_BASE_URL
-    name: str = "groq"
-
-    def __post_init__(self) -> None:
-        if self.api_key is None:
-            self.api_key = os.environ.get(_API_KEY_ENV)
-
-    async def complete(self, request: LLMRequest) -> LLMResponse:
-        return await complete_openai_compatible(
-            api_key=self.api_key,
-            api_key_hint=_API_KEY_ENV,
-            base_url=self.base_url,
-            provider_name=self.name,
-            request=request,
-        )
-
-
-__all__ = ["GroqProvider"]
@@ -1,82 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-"""Rewrite payload builder.
-
-The UI's "rewrite seed prompts" flow asks the enhancer to produce a
-batch of alternative prompts given one seed. This module packages the
-seed + options into the payload the enhancer expects and unpacks the
-response back into a typed :class:`RewriteResult`.
-
-Separating this from :mod:`enhancer` keeps the enhancer provider-
-agnostic; anything UI-specific (how many alternatives to request, how
-to split the response, temperature) lives here.
-"""
-from __future__ import annotations
-
-import re
-from dataclasses import dataclass
-
-from fastvideo.entrypoints.streaming.prompt.enhancer import PromptEnhancer
-
-_LEADING_MARKER_RE = re.compile(r"^(?:[-*•]\s*|\d+\s*[.)]\s*)+")
-
-
-@dataclass
-class RewriteOptions:
-    count: int = 3
-    """Number of alternative prompts to request."""
-    temperature: float | None = None
-
-
-@dataclass
-class RewriteResult:
-    seed_prompt: str
-    alternatives: list[str]
-    provider: str
-    model: str
-    latency_ms: float
-    fallback_used: bool = False
-
-
-async def build_rewrite(
-    enhancer: PromptEnhancer,
-    seed_prompt: str,
-    *,
-    options: RewriteOptions | None = None,
-) -> RewriteResult:
-    """Run a rewrite op through the enhancer and return a typed result."""
-    if not seed_prompt.strip():
-        raise ValueError("rewrite seed prompt must be non-empty")
-    options = options or RewriteOptions()
-    response = await enhancer.rewrite(seed_prompt)
-    alternatives = _split_response(response.content, limit=options.count)
-    return RewriteResult(
-        seed_prompt=seed_prompt,
-        alternatives=alternatives,
-        provider=response.provider,
-        model=response.model,
-        latency_ms=response.latency_ms,
-        fallback_used=response.fallback_used,
-    )
-
-
-def _split_response(content: str, *, limit: int) -> list[str]:
-    """Split the LLM response into discrete prompt candidates.
-
-    The shipped system prompt instructs the model to emit one prompt
-    per line; this function is forgiving about numbered lists or
-    leading bullets so user-supplied system prompts don't break it.
-    """
-    lines = [line.strip() for line in content.splitlines() if line.strip()]
-    cleaned: list[str] = []
-    for line in lines:
-        stripped = _LEADING_MARKER_RE.sub("", line).strip()
-        if stripped:
-            cleaned.append(stripped)
-    return cleaned[:max(1, limit)]
-
-
-__all__ = [
-    "RewriteOptions",
-    "RewriteResult",
-    "build_rewrite",
-]
@@ -1,146 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-"""Optional prompt safety filter.
-
-Uses a fastText classifier to score prompts against a banned-content
-rubric. Only loaded when ``ServeConfig.streaming.safety.enabled`` is
-True and fastText is installed — users who don't need it see no
-runtime cost.
-
-Install: ``pip install fastvideo[prompt-safety]`` (ships fasttext as an
-optional extra) or install fasttext directly.
-"""
-from __future__ import annotations
-
-import enum
-import threading
-from dataclasses import dataclass
-from typing import Any
-
-from fastvideo.logger import init_logger
-
-logger = init_logger(__name__)
-
-
-class SafetyDecision(enum.Enum):
-    ALLOW = "allow"
-    BLOCK = "block"
-    UNAVAILABLE = "unavailable"
-    """Returned when the classifier can't run (not configured, fastText
-    missing). Safety is opt-in; the server treats ``UNAVAILABLE`` as
-    ``ALLOW`` but logs it so operators know the filter is off."""
-
-
-@dataclass
-class SafetyResult:
-    prompt: str
-    decision: SafetyDecision
-    score: float = 0.0
-    label: str | None = None
-    reason: str | None = None
-
-
-class PromptSafetyFilter:
-    """Minimal fastText-backed prompt safety filter.
-
-    Loads the classifier lazily on first use so the streaming server
-    can construct the filter eagerly at startup without paying the
-    model-load cost when safety is disabled.
-    """
-
-    def __init__(
-        self,
-        *,
-        classifier_path: str | None,
-        enabled: bool = True,
-        block_threshold: float = 0.5,
-    ) -> None:
-        self._classifier_path = classifier_path
-        self._enabled = enabled
-        self._block_threshold = block_threshold
-        self._model: Any | None = None
-        self._load_attempted = False
-        self._load_lock = threading.Lock()
-
-    @property
-    def enabled(self) -> bool:
-        return self._enabled and self._classifier_path is not None
-
-    def classify(self, prompt: str) -> SafetyResult:
-        if not self.enabled:
-            return SafetyResult(
-                prompt=prompt,
-                decision=SafetyDecision.UNAVAILABLE,
-                reason="safety filter not enabled",
-            )
-        model = self._ensure_loaded()
-        if model is None:
-            return SafetyResult(
-                prompt=prompt,
-                decision=SafetyDecision.UNAVAILABLE,
-                reason="fastText model unavailable",
-            )
-        try:
-            labels, probs = model.predict(prompt.replace("\n", " "), k=1)
-        except Exception as exc:  # pragma: no cover - defensive
-            logger.warning("safety: classifier failed: %s", exc)
-            return SafetyResult(
-                prompt=prompt,
-                decision=SafetyDecision.UNAVAILABLE,
-                reason=f"classifier error: {exc}",
-            )
-        label = labels[0].removeprefix("__label__") if labels else None
-        score = float(probs[0]) if len(probs) else 0.0
-        decision = (SafetyDecision.BLOCK if
-                    (label == "unsafe" and score >= self._block_threshold) else SafetyDecision.ALLOW)
-        return SafetyResult(
-            prompt=prompt,
-            decision=decision,
-            score=score,
-            label=label,
-        )
-
-    def _ensure_loaded(self) -> Any | None:
-        if self._model is not None:
-            return self._model
-        if self._load_attempted:
-            return None
-        with self._load_lock:
-            if self._model is not None:
-                return self._model
-            if self._load_attempted:
-                return None
-            self._load_attempted = True
-            if self._classifier_path is None:
-                return None
-            try:
-                import fasttext  # type: ignore[import-not-found]
-            except ImportError:
-                logger.warning("safety: fasttext not installed; safety filter disabled. "
-                               "Install fastvideo[prompt-safety] to enable.")
-                return None
-            try:
-                self._model = fasttext.load_model(self._classifier_path)
-            except Exception as exc:  # pragma: no cover - requires real model
-                logger.warning("safety: failed to load %s: %s", self._classifier_path, exc)
-                return None
-            return self._model
-
-
-def first_blocked(
-    filter_: PromptSafetyFilter,
-    prompts: list[str],
-) -> SafetyResult | None:
-    """Return the first prompt the filter blocks, or ``None``."""
-    for prompt in prompts:
-        result = filter_.classify(prompt)
-        if result.decision is SafetyDecision.BLOCK:
-            return result
-    return None
-
-
-__all__ = [
-    "PromptSafetyFilter",
-    "SafetyDecision",
-    "SafetyResult",
-    "first_blocked",
-]
@@ -1,252 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-"""JSON WebSocket protocol schemas for the streaming server.
-
-Every control message shares the envelope ``{"type": <str>, ...}``.
-Pydantic models live here so the server can parse / validate incoming
-frames and emit well-typed outgoing frames without hand-rolled dicts.
-
-The message catalogue matches the contract in
-``docs/design/server_contracts/streaming.md``; additions must land in
-both places in the same PR.
-"""
-from __future__ import annotations
-
-from typing import Annotated, Any, Literal, Union
-
-from pydantic import BaseModel, ConfigDict, Field
-
-# ---------------------------------------------------------------------------
-# Client → server
-# ---------------------------------------------------------------------------
-
-
-class SessionInitV2(BaseModel):
-    """Opening frame the client sends after the WebSocket handshake."""
-
-    model_config = ConfigDict(extra="allow")
-
-    type: Literal["session_init_v2"]
-    client_id: str | None = None
-    preset: str | None = None
-    preset_label: str | None = None
-    curated_prompts: list[str] = Field(default_factory=list)
-    initial_image: dict[str, Any] | None = None
-    enhancement_enabled: bool = False
-    auto_extension_enabled: bool = False
-    loop_generation_enabled: bool = False
-    single_clip_mode: bool = False
-    stream_mode: Literal["av_fmp4", "legacy_jpeg"] = "av_fmp4"
-    continuation_state: dict[str, Any] | None = None
-    """Optional ``{kind, payload}`` dict; hydrated into
-    :class:`fastvideo.api.ContinuationState` server-side."""
-
-
-class SegmentPromptSource(BaseModel):
-    """Request a new segment using a specific prompt."""
-
-    type: Literal["segment_prompt_source"]
-    prompt: str
-    negative_prompt: str | None = None
-    source: Literal["curated", "enhanced", "user", "auto_extension"] = "user"
-    seed: int | None = None
-    num_inference_steps: int | None = None
-    guidance_scale: float | None = None
-
-
-class SeedPromptsUpdated(BaseModel):
-    type: Literal["seed_prompts_updated"]
-    seed_prompts: list[str] = Field(default_factory=list)
-
-
-class EnhancementUpdated(BaseModel):
-    type: Literal["enhancement_updated"]
-    enabled: bool
-
-
-class AutoExtensionUpdated(BaseModel):
-    type: Literal["auto_extension_updated"]
-    enabled: bool
-
-
-class LoopGenerationUpdated(BaseModel):
-    type: Literal["loop_generation_updated"]
-    enabled: bool
-
-
-class GenerationPausedUpdated(BaseModel):
-    type: Literal["generation_paused_updated"]
-    paused: bool
-
-
-class SnapshotState(BaseModel):
-    """Request the current ``ContinuationState`` for export."""
-
-    type: Literal["snapshot_state"]
-
-
-ClientMessage = Annotated[
-    Union[  # noqa: UP007 - Annotated requires Union for discriminator
-        SessionInitV2,
-        SegmentPromptSource,
-        SeedPromptsUpdated,
-        EnhancementUpdated,
-        AutoExtensionUpdated,
-        LoopGenerationUpdated,
-        GenerationPausedUpdated,
-        SnapshotState,
-    ],
-    Field(discriminator="type"),
-]
-
-# ---------------------------------------------------------------------------
-# Server → client
-# ---------------------------------------------------------------------------
-
-
-class QueueStatus(BaseModel):
-    type: Literal["queue_status"] = "queue_status"
-    position: int
-    queue_depth: int
-
-
-class GpuAssigned(BaseModel):
-    type: Literal["gpu_assigned"] = "gpu_assigned"
-    gpu_id: int
-    session_timeout: int
-
-
-class Ltx2StreamStart(BaseModel):
-    type: Literal["ltx2_stream_start"] = "ltx2_stream_start"
-    preset: str | None = None
-    width: int
-    height: int
-    fps: int
-    num_frames: int
-
-
-class Ltx2SegmentStart(BaseModel):
-    type: Literal["ltx2_segment_start"] = "ltx2_segment_start"
-    segment_idx: int
-    prompt: str
-    total_steps: int
-
-
-class StepComplete(BaseModel):
-    type: Literal["step_complete"] = "step_complete"
-    segment_idx: int
-    step: int
-    total_steps: int
-    stage: str = "denoise"
-
-
-class MediaInit(BaseModel):
-    """Descriptor for the fMP4 initialization segment that follows."""
-
-    type: Literal["media_init"] = "media_init"
-    segment_idx: int
-    mime: str = "video/mp4; codecs=\"avc1.64001f, mp4a.40.2\""
-    stream_id: str
-    mode: Literal["av_fmp4"] = "av_fmp4"
-
-
-class MediaSegmentComplete(BaseModel):
-    type: Literal["media_segment_complete"] = "media_segment_complete"
-    segment_idx: int
-    stream_id: str
-    chunks: int
-    duration_ms: float | None = None
-    pts_base_ms: float | None = None
-
-
-class Ltx2SegmentComplete(BaseModel):
-    type: Literal["ltx2_segment_complete"] = "ltx2_segment_complete"
-    segment_idx: int
-    generation_time_ms: float
-    e2e_latency_ms: float | None = None
-
-
-class Ltx2StreamComplete(BaseModel):
-    type: Literal["ltx2_stream_complete"] = "ltx2_stream_complete"
-    reason: Literal["segment_cap", "stop_requested", "error"] = "stop_requested"
-
-
-class SessionTimeout(BaseModel):
-    type: Literal["session_timeout"] = "session_timeout"
-    timeout_seconds: int
-
-
-class ContinuationStateSnapshot(BaseModel):
-    type: Literal["continuation_state_snapshot"] = "continuation_state_snapshot"
-    state: dict[str, Any]
-    """``{kind, payload}`` dict matching
-    :class:`fastvideo.api.ContinuationState`."""
-
-
-class ErrorMessage(BaseModel):
-    type: Literal["error"] = "error"
-    code: Literal[
-        "session_rejected",
-        "invalid_message",
-        "preset_mismatch",
-        "gpu_unavailable",
-        "worker_failed",
-        "upstream_timeout",
-        "internal_error",
-    ] = "internal_error"
-    message: str
-    retryable: bool = False
-
-
-ServerMessage = Union[  # noqa: UP007 - pydantic Union handling
-    QueueStatus,
-    GpuAssigned,
-    Ltx2StreamStart,
-    Ltx2SegmentStart,
-    StepComplete,
-    MediaInit,
-    MediaSegmentComplete,
-    Ltx2SegmentComplete,
-    Ltx2StreamComplete,
-    SessionTimeout,
-    ContinuationStateSnapshot,
-    ErrorMessage,
-]
-
-
-def parse_client_message(raw: dict[str, Any]) -> ClientMessage:
-    """Parse an incoming WebSocket dict into a typed client message.
-
-    Unknown ``type`` values raise :class:`pydantic.ValidationError`; the
-    server handler turns that into an ``error`` frame with
-    ``code="invalid_message"``.
-    """
-    from pydantic import TypeAdapter
-
-    return TypeAdapter(ClientMessage).validate_python(raw)
-
-
-__all__ = [
-    "AutoExtensionUpdated",
-    "ClientMessage",
-    "ContinuationStateSnapshot",
-    "EnhancementUpdated",
-    "ErrorMessage",
-    "GenerationPausedUpdated",
-    "GpuAssigned",
-    "Ltx2SegmentComplete",
-    "Ltx2SegmentStart",
-    "Ltx2StreamComplete",
-    "Ltx2StreamStart",
-    "LoopGenerationUpdated",
-    "MediaInit",
-    "MediaSegmentComplete",
-    "QueueStatus",
-    "SeedPromptsUpdated",
-    "SegmentPromptSource",
-    "ServerMessage",
-    "SessionInitV2",
-    "SessionTimeout",
-    "SnapshotState",
-    "StepComplete",
-    "parse_client_message",
-]
@@ -1,27 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-"""Multi-replica load balancer + WebSocket proxy for the streaming server.
-
-Sits in front of one-or-more streaming-server replicas and forwards
-WebSocket sessions to a healthy primary, with failover to secondaries.
-Kept in-repo under ``fastvideo/entrypoints/streaming/router/`` per the
-PR plan's default; the alternative (separate package) is an open
-question deferred to review.
-"""
-from fastvideo.entrypoints.streaming.router.registry import (
-    Replica,
-    ReplicaHealth,
-    ReplicaRegistry,
-    ReplicaStatus,
-)
-from fastvideo.entrypoints.streaming.router.config import RouterConfig
-from fastvideo.entrypoints.streaming.router.main import build_router_app, run_router
-
-__all__ = [
-    "Replica",
-    "ReplicaHealth",
-    "ReplicaRegistry",
-    "ReplicaStatus",
-    "RouterConfig",
-    "build_router_app",
-    "run_router",
-]
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
SolitaryThinker	4a427692bf	update	2026-04-21 10:26:57 -07:00
SolitaryThinker	1214fb0f74	docs(seed-ssim-skill): fix modal volume get path + force flag Post-first-run corrections to the seed-ssim-references skill: - modal volume get needs --force when the local parent directory already exists, otherwise it errors with [Errno 21] Is a directory. - The downloaded tree has an extra generated_videos/ level (from the volume layout in _sync_generated_videos_to_volume), so copy-local's --generated-dir must include it.	2026-04-21 10:22:36 -07:00
SolitaryThinker	2dddbdf4c0	fix(kernel-build): detect CUDA arch via active venv python directly uv run --active --no-project can provision its own interpreter on some uv versions and misses packages installed into VIRTUAL_ENV, causing ModuleNotFoundError: torch right after uv pip install -e .[test] succeeded. Invoke $VIRTUAL_ENV/bin/python directly so detect_with_torch reliably sees the freshly-installed torch.	2026-04-21 10:06:07 -07:00
SolitaryThinker	4aa065b96c	fix(ssim-modal): install torch before fastvideo-kernel build fastvideo-kernel/build.sh needs torch to detect the host CUDA arch via detect_with_torch. The previous order built the kernel before uv pip install -e .[test], so torch wasn't present yet and detection failed with ModuleNotFoundError. Install the package (pulling torch) first, then build the kernel from source to shadow the PyPI wheel.	2026-04-21 09:58:19 -07:00
SolitaryThinker	7b1cd12059	update	2026-04-21 09:44:00 -07:00
SolitaryThinkerandClaude Opus 4.7	d041b038bf	[misc] [6/n] Improve API: tidy LTX-2 refine override helpers Promote the refine-override field accessors to module-level frozenset constants (``REFINE_PRESET_OVERRIDE_FIELDS``, ``REFINE_STAGE_OVERRIDE_FIELDS``, ``REFINE_FLAT_KEYS``) so callers reference a single source of truth instead of recomputing on each call. Drop the redundant ``dict(deepcopy(value))`` double-copy on the ``torch_compile_kwargs`` legacy path, compress the ``_compile_config_to_torch_kwargs`` docstring, and remove a handful of comments that just restated the code or named a future PR. Narrow the schema-parity ``walk_packages`` traversal to ``configs/pipelines/*`` and ``basic/<family>/pipeline_configs`` so the test no longer imports every heavy model module under ``basic/``. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-04-21 08:32:19 -07:00
SolitaryThinker	9a15721d28	[misc] [6/n] Simplify LTX-2 preset scaffolding Post-review cleanup (no behavior change): Correctness: * compat.py refine reverse-flatten now iterates _LTX2_REFINE_FLAT_KEYS, which unions the typed LTX2RefinePresetOverride and LTX2RefineStageOverride field sets. The previous hardcoded 4-tuple missed image_crf and video_position_offset_sec, so any init-time preset_overrides.refine.image_crf would silently drop on reverse. New regression test TestRefineFlattenCoversAllTypedFields pins the invariant. Simplification: * refine_preset_override_to_dict and refine_stage_override_to_dict were byte-identical; collapse to a single refine_override_to_dict. * Trim narrative / PR-migration prose from docstrings and re-export shims: stage_overrides.py module + field docstrings, schema.py CompileConfig + PipelineSelection.vae_tiling, presets.py LTX2_TWO_STAGE header, configs/pipelines/__init__.py and pipelines/stages/__init__.py and ltx2/stages/__init__.py.	2026-04-21 08:32:19 -07:00
SolitaryThinker	185d833d68	[test] [6/n] Improve API: gpu_pool-style LTX-2 kwarg round-trip Close out PR 6 with the compat mappings for every flat LTX-2 kwarg the FastVideo-internal ui/ltx2-streaming/server/gpu_pool.py passes to VideoGenerator.from_pretrained, plus an integration test that freezes the gpu_pool load_kwargs dict as a parity guard. Compat additions (fastvideo/api/compat.py): legacy_from_pretrained_to_config forward routing for: - config_model_path -> components.config_root - ltx2_refine_enabled -> preset_overrides.refine.enabled - ltx2_refine_upsampler_path -> components.upsampler_weights (empty string collapses to None) - ltx2_refine_lora_path -> components.lora_path (empty string collapses to None) - ltx2_refine_add_noise -> preset_overrides.refine.add_noise - ltx2_refine_num_inference_steps -> preset_overrides.refine.num_inference_steps - ltx2_refine_guidance_scale -> preset_overrides.refine.guidance_scale generator_config_to_fastvideo_args reverse routing: - components.config_root -> config_model_path - components.upsampler_weights -> ltx2_refine_upsampler_path (no longer raises NotImplementedError) - preset_overrides.refine.{...} now flattens back to ltx2_refine_{enabled, add_noise, num_inference_steps, guidance_scale} instead of leaking as a nested "refine" kwarg. PR 7.6 (gpu_pool upstream) and the Dynamo adapter can now build a typed GeneratorConfig from their CLI without knowing any legacy LTX-2 kwarg name — the hard gate called out in PR plan.md § "Why the gpu_pool.py typed-replacement scope matters". Tests (fastvideo/tests/api/test_ltx2_gpu_pool_translation.py): - GPU_POOL_LOAD_KWARGS fixture mirrors gpu_pool.py lines 233-260 (minus opaque objects: PipelineConfig instance, the text-encoder torch.compile flag not yet in the public FastVideoArgs). - TestGpuPoolForwardTranslation asserts each flat kwarg lands on the correct typed field and that pipeline.experimental stays empty (no silent fallthrough). - TestGpuPoolReverseTranslation asserts the same dict reproduces on the FastVideoArgs.from_kwargs call — including the four ltx2_refine_* fields, ltx2_vae_tiling, torch_compile_kwargs, and config_model_path. - TestCompileExtrasPreserved checks non-typed torch.compile kwargs (options, disable) ride through CompileConfig.extras in both directions. All 148 API tests pass locally (227 including entrypoints).	2026-04-21 08:32:19 -07:00
SolitaryThinker	5568c90591	[refactor] [6/n] Improve API: colocate LTX-2 pipeline config and stages Move the LTX-2 family's PipelineConfig and the four LTX-2-specific stage modules into fastvideo/pipelines/basic/ltx2/ so each model family directory is self-contained (pipeline implementation + presets + stage_overrides + pipeline_configs + stages in one place). See the "Pipeline Package Structure" section in PR plan.md and the per-model colocation plan in apirefactor.md Phase 8. File moves (git mv preserves history): fastvideo/configs/pipelines/ltx2.py -> fastvideo/pipelines/basic/ltx2/pipeline_configs.py fastvideo/pipelines/stages/ltx2_audio_decoding.py -> fastvideo/pipelines/basic/ltx2/stages/ltx2_audio_decoding.py fastvideo/pipelines/stages/ltx2_denoising.py -> fastvideo/pipelines/basic/ltx2/stages/ltx2_denoising.py fastvideo/pipelines/stages/ltx2_latent_preparation.py -> fastvideo/pipelines/basic/ltx2/stages/ltx2_latent_preparation.py fastvideo/pipelines/stages/ltx2_text_encoding.py -> fastvideo/pipelines/basic/ltx2/stages/ltx2_text_encoding.py Import/export updates: - fastvideo/registry.py and tests/local_tests/test_ltx2_registry.py now import LTX2T2VConfig from the new colocated path directly. - fastvideo/configs/pipelines/__init__.py keeps the legacy `fastvideo.configs.pipelines.LTX2T2VConfig` export by re-exporting from the new location — external users of the old path keep working. - fastvideo/pipelines/stages/__init__.py does the same for the four LTX-2 stage classes, re-exporting from the new pipelines/basic/ltx2/stages/ subpackage. - new fastvideo/pipelines/basic/ltx2/stages/__init__.py is the canonical home for the stage exports. Parity-inventory walker (fastvideo/tests/api/test_schema_parity_inventory.py): _get_extra_dataclass_fields now accepts a tuple of package roots and descends recursively via pkgutil.walk_packages, so it discovers PipelineConfig subclasses that have moved out of fastvideo.configs.pipelines into fastvideo.pipelines.basic.<family>. The pipeline_config_extensions classification test now walks both roots so the LTX-2 fields (vocoder_config, audio_decoder_config, vocoder_precision, audio_decoder_precision) stay accounted for. Nothing else changes: no behavior change; no test changes beyond the walker; all 210 API+entrypoints tests still pass.	2026-04-21 08:32:19 -07:00
SolitaryThinker	8031f27817	[feat] [6/n] Improve API: typed torch.compile kwargs + pipeline.vae_tiling Promote the four torch.compile kwargs the FastVideo-internal ltx2-streaming gpu_pool hard-codes in its torch_compile_kwargs dict into first-class typed fields on CompileConfig, and add a typed home for ltx2_vae_tiling on PipelineSelection so PR 7.6's public gpu_pool upstream has a typed boundary to hit. Schema changes (fastvideo/api/schema.py): CompileConfig: - rename kwargs -> extras (breaking; pre-stable API) - add backend: str \| None (e.g. "inductor") - add fullgraph: bool \| None - add mode: str \| None (e.g. "max-autotune-no-cudagraphs") - add dynamic: bool \| None extras still holds uncommon kwargs (e.g. options, disable). PipelineSelection: - add vae_tiling: bool \| None. Shared across model families that expose VAE tiling (LTX-2, Wan configs, etc.); None leaves the model default in place. Compat (fastvideo/api/compat.py): - legacy_from_pretrained_to_config splits incoming torch_compile_kwargs={backend, fullgraph, mode, dynamic, ...} across the four typed fields and drops the remainder into extras. - generator_config_to_fastvideo_args reconstructs the flat torch_compile_kwargs dict via _compile_config_to_torch_kwargs, emitting only user-set typed fields plus extras. - legacy ltx2_vae_tiling routes to pipeline.vae_tiling on the way in and back to ltx2_vae_tiling on the way out. Parity inventory (docs/design/inference_schema_parity_inventory.yaml): - torch_compile_kwargs now maps to the comma-separated leaf generator.engine.compile.backend,fullgraph,mode,dynamic,extras - ltx2_vae_tiling reclassified from preset_owned nested dict (.preset_overrides.ltx2.vae_tiling) to moved (.pipeline.vae_tiling) 11 new tests in fastvideo/tests/api/test_compat_translation.py cover typed-key promotion, extras merge, None suppression, round-trip back to FastVideoArgs, and the vae_tiling forward/reverse path. Parser round-trip fixture updated for the new schema fields.	2026-04-21 08:32:19 -07:00
SolitaryThinker	0b7e8b5d1d	[feat] [6/n] Improve API: typed LTX2 refine stage overrides Add typed public dataclasses that describe the LTX-2 refine override surfaces, and bind them to the ltx2_two_stage preset's stage schema so the validation-layer field set stays in lockstep with the dataclass: * LTX2RefinePresetOverride (init-time, for preset_overrides.refine): - enabled: bool \| None — toggle the refine stage topology - add_noise: bool \| None — controls LTX2UpsampleStage noise mixing * LTX2RefineStageOverride (per-request, for stage_overrides.refine): - num_inference_steps: int \| None — stage-2 denoise steps (2 or 3) - guidance_scale: float \| None — force_guidance_scale for stage-2 - image_crf: int \| None — image-encoding CRF hint - video_position_offset_sec: float \| None — RoPE shift for audio conditioning continuation Asset wiring (upsampler weights, refine LoRA) stays on ComponentConfig.upsampler_weights / .lora_path — no new typed home is added here because those already exist. The ltx2_two_stage refine stage schema's allowed_overrides now reads from refine_stage_override_fields() so the dataclass is the single source of truth. Serialisation helpers (refine_{preset,stage}_override_to_dict) drop None entries so only user-set fields flow through the preset/stage override dicts. The runtime still reads the refine knobs off FastVideoArgs at pipeline-construction time; wiring these typed objects through compat + runtime is the next slice. This commit ships only the public typed surface and the preset/dataclass invariant. 12 new tests in fastvideo/tests/api/test_ltx2_stage_overrides.py cover default None construction, explicit construction, to_dict() dropping None, fields() accessor, and an invariant test proving the preset's refine stage allowed_overrides exactly matches the dataclass fields.	2026-04-21 08:32:19 -07:00
SolitaryThinker	279e52ad8d	[feat] [6/n] Improve API: add ltx2_two_stage preset Land the ltx2_two_stage inference preset (PR 6 commit 1/5) that exposes the public LTX-2 two-stage distilled flow: half-resolution denoise followed by 2x spatial upsample + stage-2 refine denoise (3 steps with the official distilled sigma schedule, or 2 steps with the reduced variant). Schema: - new _REFINE_STAGE PresetStageSpec with kind="refinement" and allowed per-request overrides {num_inference_steps, guidance_scale, image_crf, video_position_offset_sec} - new LTX2_TWO_STAGE preset with stage_schemas=(denoise, refine) and stage_defaults.refine={num_inference_steps: 2, guidance_scale: 1.0} matching the load_kwargs the internal ltx2-streaming gpu_pool uses - LTX2_TWO_STAGE registered via ALL_PRESETS -> _register_presets() Init-time refine wiring (enabled, add_noise, upsampler/LoRA/transformer paths) flows through generator.pipeline.preset_overrides.refine.* and generator.pipeline.components.{upsampler_weights, lora_path} in a follow-up commit — the refine stage's internal implementation (fastvideo/pipelines/stages/ltx2_refine.py in FastVideo-internal) already treats those as FastVideoArgs fields; this commit only ships the public preset surface. 5 new tests under fastvideo/tests/api/test_presets.py::TestLtx2Presets: registration count (3 presets now), two-stage topology, stage defaults, valid per-request refine override keys, and unknown-override rejection.	2026-04-21 08:32:19 -07:00
SolitaryThinker	6b3c1223c6	[misc] add .agents/scripts/sync-skills.sh Claude Code only scans ~/.claude/skills/ and .claude/skills/ for user-invocable skills (no skillsPath / skillsDir config option exists — https://code.claude.com/docs/en/skills.md). Skills in this repo live under .agents/skills/ so they travel with the repo and stay under git. Add a one-shot idempotent sync script that symlinks each .agents/skills/<name>/ directory into .claude/skills/<name>. Run after cloning or after adding/removing a skill: .agents/scripts/sync-skills.sh Behavior: * relative symlinks (../../.agents/skills/<name>) so the link survives moving the clone * requires a SKILL.md inside each skill directory to be eligible * prunes stale symlinks whose source vanished from .agents/skills/ * refuses to clobber a pre-existing .claude/skills/<name>/ that isn't a symlink (lets the operator keep hand-written skills alongside managed ones) * prints a linked / unchanged / pruned / skipped summary Note: .claude/ is gitignored; the symlinks themselves are not committed. The script is the source of truth for reconstructing them.	2026-04-17 18:26:06 -07:00
SolitaryThinker	0c8687c919	[misc] add seed-ssim-references agent skill Wraps the existing fastvideo/tests/modal/ssim_test.py --sync-generated-to-volume path with a step-by-step SKILL.md and a thin seed_ssim.sh launcher so new SSIM tests can bootstrap their HF reference videos without manual Modal wrangling. Motivation: the new test_ltx2_similarity.py (committed earlier on this branch) has no HF reference video yet; the next operator needs a deterministic procedure for generating + uploading the first set. Generalises beyond LTX-2 — any new family test can reuse verbatim.	2026-04-17 17:59:21 -07:00
SolitaryThinker	ddbf41fa0e	[test] add LTX-2 distilled T2V SSIM regression test LTX-2 was the only model family in fastvideo/pipelines/basic/ without an SSIM coverage file. Add test_ltx2_similarity.py alongside the other per-family SSIM tests so the in-flight API refactor and future LTX-2-specific changes (two-stage refine, gpu_pool upstream, Dynamo backend) have a golden-quality regression guard. Parameters: Default (CI-friendly): model: FastVideo/LTX2-Distilled-Diffusers (8-step distilled) resolution: 512x768, num_frames=45, num_inference_steps=4 sp_size=2 on 2 GPUs, FLASH_ATTN backend ltx2_vae_tiling=True for peak-memory safety --ssim-full-quality: falls back to the ltx2_distilled preset defaults (1024x1536, 121 frames, 8 steps, guidance_scale=1.0) Uses the shared run_text_to_video_similarity_test helper (same pattern as Wan/TurboDiffusion), so _build_init_kwargs picks up ltx2_vae_tiling + related tile sizes automatically. REQUIRED_GPUS = 2 is declared at module scope so the Modal SSIM orchestrator (fastvideo/tests/modal/ssim_test.py) schedules it correctly on the L40S:8 runner. LTX2_DISTILLED_MODEL_TO_PARAMS is named so the orchestrator can split by model id (one subprocess per entry) for future multi-model LTX-2 coverage. Threshold min_acceptable_ssim=0.93 matches Wan T2V. Reference videos are not in the repo. After this lands on main, run the test once on an L40S and upload via `python fastvideo/tests/ssim/reference_videos_cli.py upload --quality-tier all` to seed FastVideo/ssim-reference-videos. Subsequent runs (including regression guards for in-flight refactor PRs) auto-download the references before the test executes.	2026-04-17 16:35:51 -07:00