[docs]: replace config generator with native cookbook

Address review: flip ignoreBuildErrors true->false. The code type-checks clean (verified with next build).

.agents/skills/add-model-01-prep/scripts/clone_reference_repo.py

@@ -10,7 +10,9 @@ from pathlib import Path
 
 
 def parse_args() -> argparse.Namespace:
-    parser = argparse.ArgumentParser(description="Clone a reference repo for FastVideo parity tests.")
+    parser = argparse.ArgumentParser(
+        description="Clone a reference repo for FastVideo parity tests."
+    )
     parser.add_argument("repo_url", help="Official reference repository URL")
     parser.add_argument("target_dir", help="Directory to clone into")
     parser.add_argument("--branch", help="Branch or tag to clone")
@@ -60,7 +62,9 @@ def gitignore_entry_for(target: Path) -> str:
     try:
         relative = resolved.relative_to(root)
     except ValueError as exc:
-        raise ValueError("--update-gitignore requires target_dir to be under the current directory") from exc
+        raise ValueError(
+            "--update-gitignore requires target_dir to be under the current directory"
+        ) from exc
 
     text = relative.as_posix().rstrip("/")
     return "/" + text + "/"

.agents/skills/add-model-01-prep/scripts/download_hf_weights.py

@@ -8,12 +8,14 @@ import os
 import sys
 from pathlib import Path
 
+
 HF_TOKEN_ENV_KEYS = ("HF_TOKEN", "HUGGINGFACE_HUB_TOKEN", "HF_API_KEY")
 
 
 def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(
-        description="Download a HF model snapshot or selected files into a local directory.")
+        description="Download a HF model snapshot or selected files into a local directory."
+    )
     parser.add_argument("repo_id", help="HF repo id, for example Org/Model")
     parser.add_argument("local_dir", help="Destination directory")
     parser.add_argument("--repo-type", default="model", help="HF repo type (default: model)")

.agents/skills/add-model-01-prep/scripts/inspect_hf_layout.py

@@ -10,6 +10,7 @@ import sys
 from pathlib import Path
 from typing import Any
 
+
 HF_TOKEN_ENV_KEYS = ("HF_TOKEN", "HUGGINGFACE_HUB_TOKEN", "HF_API_KEY")
 RAW_WEIGHT_SUFFIXES = (".safetensors", ".pt", ".pth", ".ckpt", ".bin")
 KNOWN_COMPONENTS = {
@@ -33,7 +34,8 @@ KNOWN_COMPONENTS = {
 
 def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(
-        description="Classify a HF repo or local directory as Diffusers, raw, custom, or unknown.")
+        description="Classify a HF repo or local directory as Diffusers, raw, custom, or unknown."
+    )
     parser.add_argument("source", help="HF repo id or local weights directory")
     parser.add_argument("--repo-type", default="model", help="HF repo type (default: model)")
     parser.add_argument("--revision", help="HF revision to inspect")
@@ -92,12 +94,14 @@ def load_remote_files(
 ) -> list[str]:
     from huggingface_hub import list_repo_files
 
-    return sorted(list_repo_files(
-        repo_id,
-        repo_type=repo_type,
-        revision=revision,
-        token=token,
-    ))
+    return sorted(
+        list_repo_files(
+            repo_id,
+            repo_type=repo_type,
+            revision=revision,
+            token=token,
+        )
+    )
 
 
 def load_remote_model_index(
@@ -211,24 +215,24 @@ def build_result(args: argparse.Namespace) -> dict[str, Any]:
         "components_seen": components,
         "file_count": len(files),
         "file_scan_truncated": truncated,
-        "files_sample": files[:args.sample_limit],
+        "files_sample": files[: args.sample_limit],
     }
 
 
 def print_human(result: dict[str, Any]) -> None:
     for key in (
-            "source",
-            "source_kind",
-            "repo_type",
-            "revision",
-            "token_env",
-            "source_layout",
-            "needs_conversion",
-            "model_index_class",
-            "model_index_diffusers_version",
-            "model_index_error",
-            "file_count",
-            "file_scan_truncated",
+        "source",
+        "source_kind",
+        "repo_type",
+        "revision",
+        "token_env",
+        "source_layout",
+        "needs_conversion",
+        "model_index_class",
+        "model_index_diffusers_version",
+        "model_index_error",
+        "file_count",
+        "file_scan_truncated",
     ):
         value = result.get(key)
         if value is not None:

.agents/skills/add-model-02-parity/templates/component_parity_test.py

@@ -18,6 +18,7 @@ import pytest
 import torch
 from torch.testing import assert_close
 
+
 os.environ.setdefault("MASTER_ADDR", "localhost")
 os.environ.setdefault("MASTER_PORT", "29519")
 os.environ.setdefault("DISABLE_SP", "1")
@@ -34,10 +35,15 @@ FASTVIDEO_CONFIG_CLASS = "<FastVideoConfig>"  # TODO.
 FASTVIDEO_MODEL_MODULE = "fastvideo.models.<bucket>.<module>"  # TODO.
 FASTVIDEO_MODEL_CLASS = "<FastVideoModel>"  # TODO.
 
-OFFICIAL_REF_DIR = Path(os.getenv("<FAMILY_UPPER>_OFFICIAL_REF_DIR", REPO_ROOT / "<ReferenceDir>"))
-LOCAL_WEIGHTS_DIR = Path(os.getenv("<FAMILY_UPPER>_LOCAL_WEIGHTS_DIR", REPO_ROOT / "official_weights" / FAMILY))
-CONVERTED_WEIGHTS_DIR = Path(os.getenv("<FAMILY_UPPER>_CONVERTED_WEIGHTS_DIR",
-                                       REPO_ROOT / "converted_weights" / FAMILY))
+OFFICIAL_REF_DIR = Path(
+    os.getenv("<FAMILY_UPPER>_OFFICIAL_REF_DIR", REPO_ROOT / "<ReferenceDir>")
+)
+LOCAL_WEIGHTS_DIR = Path(
+    os.getenv("<FAMILY_UPPER>_LOCAL_WEIGHTS_DIR", REPO_ROOT / "official_weights" / FAMILY)
+)
+CONVERTED_WEIGHTS_DIR = Path(
+    os.getenv("<FAMILY_UPPER>_CONVERTED_WEIGHTS_DIR", REPO_ROOT / "converted_weights" / FAMILY)
+)
 
 
 def _resolve_hf_token() -> str | None:
@@ -93,14 +99,18 @@ def _load_official_model(device: torch.device, dtype: torch.dtype) -> torch.nn.M
     model = OfficialClass()  # TODO: pass official config kwargs.
     state_dict = {}  # TODO: load official state dict from LOCAL_WEIGHTS_DIR.
     missing, unexpected = model.load_state_dict(state_dict, strict=True)
-    assert not missing and not unexpected, (f"official load mismatch missing={missing[:5]} unexpected={unexpected[:5]}")
+    assert not missing and not unexpected, (
+        f"official load mismatch missing={missing[:5]} unexpected={unexpected[:5]}"
+    )
     return model.to(device=device, dtype=dtype).eval()
 
 
 def _load_fastvideo_model(device: torch.device, dtype: torch.dtype) -> torch.nn.Module:
     """Load the FastVideo component with the same tensor content."""
     if not CONVERTED_WEIGHTS_DIR.exists() and not LOCAL_WEIGHTS_DIR.exists():
-        pytest.skip(f"No FastVideo loadable weights: {CONVERTED_WEIGHTS_DIR} or {LOCAL_WEIGHTS_DIR}")
+        pytest.skip(
+            f"No FastVideo loadable weights: {CONVERTED_WEIGHTS_DIR} or {LOCAL_WEIGHTS_DIR}"
+        )
 
     # TODO: replace with the bucket-specific FastVideo config/class/loader.
     # DiT examples:
@@ -117,7 +127,8 @@ def _load_fastvideo_model(device: torch.device, dtype: torch.dtype) -> torch.nn.
     state_dict = {}  # TODO: load converted or directly mapped state dict.
     missing, unexpected = model.load_state_dict(state_dict, strict=True)
     assert not missing and not unexpected, (
-        f"FastVideo load mismatch missing={missing[:5]} unexpected={unexpected[:5]}")
+        f"FastVideo load mismatch missing={missing[:5]} unexpected={unexpected[:5]}"
+    )
     return model.to(device=device, dtype=dtype).eval()
 
 
@@ -176,9 +187,11 @@ def test_component_parity():
 
     assert official_out.shape == fastvideo_out.shape
     diff = (official_out - fastvideo_out).abs()
-    print(f"official abs_mean={official_out.abs().mean().item():.6f} "
-          f"fastvideo abs_mean={fastvideo_out.abs().mean().item():.6f} "
-          f"diff_max={diff.max().item():.6f} diff_mean={diff.mean().item():.6f}")
+    print(
+        f"official abs_mean={official_out.abs().mean().item():.6f} "
+        f"fastvideo abs_mean={fastvideo_out.abs().mean().item():.6f} "
+        f"diff_max={diff.max().item():.6f} diff_mean={diff.mean().item():.6f}"
+    )
 
     # TODO: pick tolerance by scope:
     # - single block / same kernel: 1e-4

.agents/skills/add-model-07-conversion/templates/family_to_diffusers.py

@@ -27,6 +27,7 @@ try:
 except ImportError:  # pragma: no cover - optional local conversion dependency
     snapshot_download = None
 
+
 # TODO: fill with authoritative component prefixes for monolithic checkpoints.
 # Example: {"model.model.": "transformer", "pretransform.model.": "vae"}
 COMPONENT_PREFIXES: dict[str, str] = {}
@@ -46,7 +47,10 @@ SKIP_PATTERNS: tuple[str, ...] = ()
 
 
 def _hf_token() -> str | None:
-    return (os.environ.get("HF_TOKEN") or os.environ.get("HUGGINGFACE_HUB_TOKEN") or os.environ.get("HF_API_KEY"))
+    return (
+        os.environ.get("HF_TOKEN") or os.environ.get("HUGGINGFACE_HUB_TOKEN")
+        or os.environ.get("HF_API_KEY")
+    )
 
 
 def resolve_src(src: str, revision: str | None) -> Path:
@@ -91,10 +95,11 @@ def apply_mapping(key: str) -> str | None:
     return key
 
 
-def split_monolithic(state: dict[str, torch.Tensor], ) -> dict[str, OrderedDict[str, torch.Tensor]]:
+def split_monolithic(
+    state: dict[str, torch.Tensor],
+) -> dict[str, OrderedDict[str, torch.Tensor]]:
     components: dict[str, OrderedDict[str, torch.Tensor]] = {
-        name: OrderedDict()
-        for name in set(COMPONENT_PREFIXES.values())
+        name: OrderedDict() for name in set(COMPONENT_PREFIXES.values())
     }
     intentionally_skipped: list[str] = []
     unowned: list[str] = []
@@ -112,8 +117,10 @@ def split_monolithic(state: dict[str, torch.Tensor], ) -> dict[str, OrderedDict[
             unowned.append(key)
     if unowned:
         sample = ", ".join(unowned[:10])
-        raise ValueError(f"Unowned monolithic keys: {len(unowned)}. "
-                         f"Add COMPONENT_PREFIXES or SKIP_PATTERNS entries. Sample: {sample}")
+        raise ValueError(
+            f"Unowned monolithic keys: {len(unowned)}. "
+            f"Add COMPONENT_PREFIXES or SKIP_PATTERNS entries. Sample: {sample}"
+        )
     if intentionally_skipped:
         print(f"Intentionally skipped {len(intentionally_skipped)} keys")
     return {name: weights for name, weights in components.items() if weights}
@@ -136,12 +143,8 @@ def build_component_configs(_src_dir: Path) -> dict[str, dict[str, Any]]:
     # TODO: emit config content accepted by FastVideo loaders. Most components use
     # config.json; schedulers use scheduler_config.json.
     return {
-        "transformer": {
-            "_class_name": "<FastVideoTransformerClass>"
-        },
-        "vae": {
-            "_class_name": "<FastVideoVAEClass>"
-        },
+        "transformer": {"_class_name": "<FastVideoTransformerClass>"},
+        "vae": {"_class_name": "<FastVideoVAEClass>"},
     }
 
 
@@ -174,13 +177,19 @@ def build_model_index(
     }
     if revision:
         index["_fastvideo_converted_revision"] = revision
-    return {key: value for key, value in index.items() if key.startswith("_") or key in available_components}
+    return {
+        key: value
+        for key, value in index.items()
+        if key.startswith("_") or key in available_components
+    }
 
 
 def validate_component_configs(configs: dict[str, dict[str, Any]]) -> None:
     # TODO: instantiate each FastVideo config and call update_model_arch(...) or
     # update_model_config(...) with this JSON so unknown emitted keys fail here.
-    placeholder_configs = [name for name, config in configs.items() if "<" in json.dumps(config)]
+    placeholder_configs = [
+        name for name, config in configs.items() if "<" in json.dumps(config)
+    ]
     if placeholder_configs:
         raise ValueError(f"Replace config placeholders for: {placeholder_configs}")
 
@@ -192,7 +201,9 @@ def verify_conversion(
     del dst_dir, components
     # TODO: load each emitted stateful component through its production loader and
     # assert strict load, or document exact allowed missing/unexpected keys.
-    raise NotImplementedError("Implement production config validation and strict-load checks")
+    raise NotImplementedError(
+        "Implement production config validation and strict-load checks"
+    )
 
 
 def write_component(
@@ -205,7 +216,9 @@ def write_component(
     if component_dir.exists() and any(component_dir.iterdir()):
         shutil.rmtree(component_dir)
     component_dir.mkdir(parents=True, exist_ok=True)
-    save_file(dict(state), str(component_dir / "diffusion_pytorch_model.safetensors"))
+    save_file(
+        dict(state), str(component_dir / "diffusion_pytorch_model.safetensors")
+    )
     if config is not None:
         config_path = component_dir / config_filename(name)
         with config_path.open("w", encoding="utf-8") as f:
@@ -248,7 +261,9 @@ def convert(
 
     if layout in {"monolithic", "raw_official"}:
         # TODO: replace model.safetensors with the official monolithic file name.
-        components = split_monolithic(load_checkpoint(default_monolithic_checkpoint(src_path)))
+        components = split_monolithic(
+            load_checkpoint(default_monolithic_checkpoint(src_path))
+        )
     elif layout in {"separate_components", "mixed"}:
         if not src_path.is_dir():
             raise ValueError(f"{layout} layout requires a source directory: {src_path}")
@@ -256,7 +271,9 @@ def convert(
     else:
         raise ValueError(f"Unsupported template layout: {layout}")
 
-    copied = (copy_passthrough(src_path, dst_dir) if src_path.is_dir() else [])
+    copied = (
+        copy_passthrough(src_path, dst_dir) if src_path.is_dir() else []
+    )
     configs = build_component_configs(src_path if src_path.is_dir() else src_path.parent)
     validate_component_configs(configs)
     for name, state in components.items():
@@ -272,7 +289,9 @@ def convert(
 
 def main() -> None:
     parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("--src", required=True, help="HF repo id, local dir, or checkpoint path")
+    parser.add_argument(
+        "--src", required=True, help="HF repo id, local dir, or checkpoint path"
+    )
     parser.add_argument("--revision", help="HF branch, tag, or commit for repo sources")
     parser.add_argument(
         "--dst",

.agents/skills/add-model-08-trace/templates/block_trace_debug.py

@@ -24,8 +24,8 @@ from typing import Any
 
 import torch
 
-FAMILY: str = "<family>"  # e.g. "magi_human", "ltx2", "wan"
-COMPONENT: str = "<component>"  # e.g. "dit", "vae", "encoder"
+FAMILY: str = "<family>"       # e.g. "magi_human", "ltx2", "wan"
+COMPONENT: str = "<component>" # e.g. "dit", "vae", "encoder"
 DRILL_LAYER_ENV: str = "<FAMILY>_DEBUG_DRILL_LAYER"
 HYPOTHESIS_ENV: str = "<FAMILY>_DEBUG_PATCH_<HYPOTHESIS>"
 REL_THRESHOLD: float = 0.005  # 0.5% abs_mean drift flags a block as divergent
@@ -94,7 +94,6 @@ def _attach_block_hooks(
     handles: list[Any] = []
 
     def _hook(name: str):
-
         def fn(_module, _inputs, outputs):
             t = outputs[0] if isinstance(outputs, tuple) else outputs
             if not torch.is_tensor(t):
@@ -102,7 +101,6 @@ def _attach_block_hooks(
             log.append({"side": label, **_stat(name, t)})
             if tensors is not None:
                 tensors[name] = t.detach().float().cpu()
-
         return fn
 
     def _pre_hook(name: str):
@@ -116,7 +114,6 @@ def _attach_block_hooks(
             log.append({"side": label, **_stat(key, t)})
             if tensors is not None:
                 tensors[key] = t.detach().float().cpu()
-
         return fn
 
     # TODO: adapt attribute paths to your model. Remove adapter block if absent.
@@ -134,21 +131,43 @@ def _attach_block_hooks(
             # magi-human uses: attention, mlp.pre_norm, mlp.up_gate_proj,
             # mlp.down_proj (pre+post), mlp, attn_post_norm, mlp_post_norm.
             if hasattr(layer, "attention"):
-                handles.append(layer.attention.register_forward_hook(_hook(f"{tag}.attention")))
+                handles.append(
+                    layer.attention.register_forward_hook(_hook(f"{tag}.attention"))
+                )
             if hasattr(layer, "mlp"):
                 mlp = layer.mlp
                 if hasattr(mlp, "pre_norm"):
-                    handles.append(mlp.pre_norm.register_forward_hook(_hook(f"{tag}.mlp.pre_norm")))
+                    handles.append(
+                        mlp.pre_norm.register_forward_hook(_hook(f"{tag}.mlp.pre_norm"))
+                    )
                 if hasattr(mlp, "up_gate_proj"):
-                    handles.append(mlp.up_gate_proj.register_forward_hook(_hook(f"{tag}.mlp.up_gate_proj")))
+                    handles.append(
+                        mlp.up_gate_proj.register_forward_hook(
+                            _hook(f"{tag}.mlp.up_gate_proj")
+                        )
+                    )
                 if hasattr(mlp, "down_proj"):
-                    handles.append(mlp.down_proj.register_forward_pre_hook(_pre_hook(f"{tag}.mlp.down_proj")))
-                    handles.append(mlp.down_proj.register_forward_hook(_hook(f"{tag}.mlp.down_proj")))
+                    handles.append(
+                        mlp.down_proj.register_forward_pre_hook(
+                            _pre_hook(f"{tag}.mlp.down_proj")
+                        )
+                    )
+                    handles.append(
+                        mlp.down_proj.register_forward_hook(_hook(f"{tag}.mlp.down_proj"))
+                    )
                 handles.append(mlp.register_forward_hook(_hook(f"{tag}.mlp")))
             if hasattr(layer, "attn_post_norm"):
-                handles.append(layer.attn_post_norm.register_forward_hook(_hook(f"{tag}.attn_post_norm")))
+                handles.append(
+                    layer.attn_post_norm.register_forward_hook(
+                        _hook(f"{tag}.attn_post_norm")
+                    )
+                )
             if hasattr(layer, "mlp_post_norm"):
-                handles.append(layer.mlp_post_norm.register_forward_hook(_hook(f"{tag}.mlp_post_norm")))
+                handles.append(
+                    layer.mlp_post_norm.register_forward_hook(
+                        _hook(f"{tag}.mlp_post_norm")
+                    )
+                )
     return handles
 
 
@@ -174,9 +193,11 @@ def _write_log(entries: list[dict], path: Path) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
     with open(path, "w") as f:
         for e in entries:
-            f.write(f"{e['name']} {e['shape']} "
-                    f"{e['abs_mean']:.8f} {e['sum']:.4f} "
-                    f"{e['min']:.6f} {e['max']:.6f}\n")
+            f.write(
+                f"{e['name']} {e['shape']} "
+                f"{e['abs_mean']:.8f} {e['sum']:.4f} "
+                f"{e['min']:.6f} {e['max']:.6f}\n"
+            )
 
 
 def _sort_key(name: str, drill_layer: int) -> tuple:
@@ -184,14 +205,9 @@ def _sort_key(name: str, drill_layer: int) -> tuple:
         return (0, "")
     if name.startswith(f"L{drill_layer:02d}."):
         sub_order = {
-            "attention": 0,
-            "attn_post_norm": 1,
-            "mlp.pre_norm": 2,
-            "mlp.up_gate_proj": 3,
-            "mlp.down_proj<in>": 4,
-            "mlp.down_proj": 5,
-            "mlp": 6,
-            "mlp_post_norm": 7,
+            "attention": 0, "attn_post_norm": 1, "mlp.pre_norm": 2,
+            "mlp.up_gate_proj": 3, "mlp.down_proj<in>": 4,
+            "mlp.down_proj": 5, "mlp": 6, "mlp_post_norm": 7,
         }.get(name.split(".", 1)[1], 9)
         return (1, f"block[{drill_layer:02d}]", sub_order)
     if name.startswith("block["):
@@ -200,8 +216,10 @@ def _sort_key(name: str, drill_layer: int) -> tuple:
 
 
 def _print_table(by_name: dict[str, dict], drill_layer: int) -> int | None:
-    hdr = (f"{'name':<18} {'up_shape':<22} {'up_absmean':>12} {'fv_absmean':>12} "
-           f"{'absmean_diff':>14} {'rel%':>8} {'up_sum':>14} {'fv_sum':>14} {'sum_diff':>12}")
+    hdr = (
+        f"{'name':<18} {'up_shape':<22} {'up_absmean':>12} {'fv_absmean':>12} "
+        f"{'absmean_diff':>14} {'rel%':>8} {'up_sum':>14} {'fv_sum':>14} {'sum_diff':>12}"
+    )
     print(f"\n{hdr}\n{'-' * len(hdr)}")
     first_div: int | None = None
     for name in sorted(by_name.keys(), key=lambda n: _sort_key(n, drill_layer)):
@@ -217,9 +235,11 @@ def _print_table(by_name: dict[str, dict], drill_layer: int) -> int | None:
             flag = " <<< DIVERGE"
             if first_div is None:
                 first_div = int(name[len("block["):-1])
-        print(f"{name:<18} {str(up['shape']):<22} {up['abs_mean']:>12.6f} "
-              f"{fv['abs_mean']:>12.6f} {am_diff:>14.6f} {am_rel * 100:>7.3f}% "
-              f"{up['sum']:>14.4f} {fv['sum']:>14.4f} {sum_diff:>12.4f}{flag}")
+        print(
+            f"{name:<18} {str(up['shape']):<22} {up['abs_mean']:>12.6f} "
+            f"{fv['abs_mean']:>12.6f} {am_diff:>14.6f} {am_rel * 100:>7.3f}% "
+            f"{up['sum']:>14.4f} {fv['sum']:>14.4f} {sum_diff:>12.4f}{flag}"
+        )
     return first_div
 
 
@@ -235,8 +255,10 @@ def _print_elementwise(up_t: dict[str, torch.Tensor], fv_t: dict[str, torch.Tens
             continue
         diff = (a - b).abs()
         rel = (diff.mean().item() / max(a.abs().mean().item(), 1e-9)) * 100
-        print(f"{name:<30} {str(tuple(a.shape)):<22} "
-              f"{diff.max().item():>12.6f} {diff.mean().item():>12.6f} {rel:>9.4f}%")
+        print(
+            f"{name:<30} {str(tuple(a.shape)):<22} "
+            f"{diff.max().item():>12.6f} {diff.mean().item():>12.6f} {rel:>9.4f}%"
+        )
 
 
 def main() -> None:

.agents/skills/add-model-09-pipeline/templates/pipeline_parity_test.py

@@ -43,10 +43,12 @@ def _add_official_to_path() -> Path:
 
 def _log_tensor_stats(label: str, tensor: torch.Tensor) -> None:
     value = tensor.detach().float()
-    print(f"[{_MODEL_FAMILY} PIPELINE] {label}: shape={tuple(tensor.shape)} "
-          f"dtype={tensor.dtype} device={tensor.device} "
-          f"min={value.min().item():.6f} max={value.max().item():.6f} "
-          f"mean={value.mean().item():.6f} std={value.std().item():.6f}")
+    print(
+        f"[{_MODEL_FAMILY} PIPELINE] {label}: shape={tuple(tensor.shape)} "
+        f"dtype={tensor.dtype} device={tensor.device} "
+        f"min={value.min().item():.6f} max={value.max().item():.6f} "
+        f"mean={value.mean().item():.6f} std={value.std().item():.6f}"
+    )
 
 
 def _extract_tensor(output: Any, key: str) -> torch.Tensor:
@@ -71,8 +73,10 @@ def _run_official_pipeline(
     device: torch.device,
 ) -> Any:
     del official_path, params, device
-    pytest.skip("TODO: import the official pipeline/factory, load official weights, "
-                "run with params, and return the comparison target.")
+    pytest.skip(
+        "TODO: import the official pipeline/factory, load official weights, "
+        "run with params, and return the comparison target."
+    )
 
 
 def _run_fastvideo_pipeline(model_path: Path, params: dict[str, Any]) -> Any:
@@ -142,6 +146,8 @@ def test_todo_model_family_pipeline_official_parity() -> None:
     assert official_tensor.shape == fastvideo_tensor.shape
 
     diff = (official_tensor - fastvideo_tensor).abs()
-    print(f"diff max={diff.max().item():.6f} "
-          f"mean={diff.mean().item():.6f} median={diff.median().item():.6f}")
+    print(
+        f"diff max={diff.max().item():.6f} "
+        f"mean={diff.mean().item():.6f} median={diff.median().item():.6f}"
+    )
     assert_close(fastvideo_tensor, official_tensor, atol=1e-2, rtol=1e-2)

.github/workflows/infra-docs.yml

@@ -6,6 +6,7 @@ on:
     paths:
       - 'docs/**'
       - 'examples/**'
+      - 'scripts/inference/**'
       - 'mkdocs.yml'
       - 'requirements-mkdocs.in'
       - 'requirements-mkdocs.txt'
@@ -16,6 +17,7 @@ on:
     paths:
       - 'docs/**'
       - 'examples/**'
+      - 'scripts/inference/**'
       - 'mkdocs.yml'
       - 'requirements-mkdocs.in'
       - 'requirements-mkdocs.txt'

.gitignore

@@ -23,7 +23,6 @@ Miniconda3-latest-Linux-x86_64.sh
 *validation/
 data/
 outputs/
-outputs_audio/
 outputs_video
 checkpoints/
 sbatch.sh

.pre-commit-config.yaml

@@ -22,7 +22,6 @@ repos:
   hooks:
   - id: yapf
     args: [--in-place, --verbose]
-    language_version: python3.12
     additional_dependencies: [toml] # TODO: Remove when yapf is upgraded
 - repo: https://github.com/astral-sh/ruff-pre-commit
   rev: v0.11.12

apps/dreamverse/dreamverse/tests/conftest.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import sys
 from pathlib import Path
 
+
 TESTS_DIR = Path(__file__).resolve().parent
 DREAMVERSE_PACKAGE_DIR = TESTS_DIR.parent
 DREAMVERSE_APP_DIR = DREAMVERSE_PACKAGE_DIR.parent

apps/dreamverse/dreamverse/tests/test_config.py

@@ -5,6 +5,7 @@ from pathlib import Path
 
 import pytest
 
+
 SERVER_DIR = Path(__file__).resolve().parents[1]
 
 
@@ -52,7 +53,9 @@ def test_config_defaults_to_cerebras_with_parallel_groq_fallback_stage(monkeypat
     module = _load_config_module()
 
     assert module.PROMPT_PROVIDER == "cerebras"
-    assert module.PROMPT_PROVIDER_RUNTIME_STAGES == (("cerebras", "groq"), )
+    assert module.PROMPT_PROVIDER_RUNTIME_STAGES == (
+        ("cerebras", "groq"),
+    )
     assert module.PROMPT_PROVIDER_PRIORITY == (
         "cerebras",
         "groq",
@@ -83,7 +86,9 @@ def test_config_ignores_legacy_groq_primary_override(monkeypatch):
     module = _load_config_module()
 
     assert module.PROMPT_PROVIDER == "cerebras"
-    assert module.PROMPT_PROVIDER_RUNTIME_STAGES == (("cerebras", "groq"), )
+    assert module.PROMPT_PROVIDER_RUNTIME_STAGES == (
+        ("cerebras", "groq"),
+    )
     assert module.PROMPT_PROVIDER_PRIORITY == (
         "cerebras",
         "groq",
@@ -101,17 +106,24 @@ def test_config_uses_local_overlay_paths_when_devtools_enabled(monkeypatch, tmp_
 
     assert module.DEVTOOLS_ENABLED is True
     assert module.FRONTEND_ROOT.as_posix().endswith("apps/dreamverse/web")
-    assert module.PROMPT_ENHANCE_SYSTEM_PROMPT_PATH.endswith("dreamverse/prompts.local/next_segment_system_prompt.md")
+    assert module.PROMPT_ENHANCE_SYSTEM_PROMPT_PATH.endswith(
+        "dreamverse/prompts.local/next_segment_system_prompt.md"
+    )
     assert module.PROMPT_ENHANCE_SYSTEM_PROMPT_FALLBACK_PATH.endswith(
-        "dreamverse/prompts/next_segment_system_prompt.md")
+        "dreamverse/prompts/next_segment_system_prompt.md"
+    )
     assert module.PROMPT_REWRITE_USER_SYSTEM_PROMPT_PATH.endswith(
-        "dreamverse/prompts.local/rewrite_user_system_prompt.md")
+        "dreamverse/prompts.local/rewrite_user_system_prompt.md"
+    )
     assert module.PROMPT_REWRITE_USER_SYSTEM_PROMPT_FALLBACK_PATH.endswith(
-        "dreamverse/prompts/rewrite_user_system_prompt.md")
+        "dreamverse/prompts/rewrite_user_system_prompt.md"
+    )
     assert module.CURATED_PRESETS_FILE_PATH.endswith(
-        "apps/dreamverse/web/prompts.local/selected_ltx2_continuation_story_presets.json")
+        "apps/dreamverse/web/prompts.local/selected_ltx2_continuation_story_presets.json"
+    )
     assert module.CURATED_PRESETS_FALLBACK_FILE_PATH.endswith(
-        "apps/dreamverse/web/prompts/selected_ltx2_continuation_story_presets.json")
+        "apps/dreamverse/web/prompts/selected_ltx2_continuation_story_presets.json"
+    )
     assert module.FRONTEND_STATIC_DIR_CANDIDATES[:2] == (
         str(module.FRONTEND_ROOT / "out"),
         str(module.FRONTEND_ROOT / "dist"),

apps/dreamverse/dreamverse/tests/test_entrypoints.py

@@ -9,7 +9,6 @@ from fastapi.testclient import TestClient
 import fastvideo.entrypoints.streaming as streaming_entrypoints
 import pytest
 
-
 def _install_stack03_import_stubs(monkeypatch):
     """Keep entrypoint tests focused while later-stack runtime modules are absent."""
     if not hasattr(streaming_entrypoints, "build_health_router"):
@@ -18,7 +17,6 @@ def _install_stack03_import_stubs(monkeypatch):
     gpu_pool_stub = types.ModuleType("dreamverse.gpu_pool")
 
     class GPUPool:
-
         def __init__(self, _gpu_ids):
             pass
 
@@ -51,7 +49,6 @@ def _install_stack03_import_stubs(monkeypatch):
     controller_stub = types.ModuleType("dreamverse.session.controller")
 
     class SessionController:
-
         def __init__(self, **_kwargs):
             pass
 
@@ -79,11 +76,13 @@ def _run_cli(module, monkeypatch, argv: list[str]) -> list[dict[str, object]]:
     uvicorn_stub = types.ModuleType("uvicorn")
 
     def run(app, host: str, port: int) -> None:
-        calls.append({
-            "app": app,
-            "host": host,
-            "port": port,
-        })
+        calls.append(
+            {
+                "app": app,
+                "host": host,
+                "port": port,
+            }
+        )
 
     uvicorn_stub.run = run
     monkeypatch.setitem(sys.modules, "uvicorn", uvicorn_stub)
@@ -100,11 +99,13 @@ def test_server_cli_defaults_to_local_web_port(monkeypatch):
     server_main = _import_server_main(monkeypatch)
     calls = _run_cli(server_main, monkeypatch, ["dreamverse-server"])
 
-    assert calls == [{
-        "app": server_main.app,
-        "host": "0.0.0.0",
-        "port": 8009,
-    }]
+    assert calls == [
+        {
+            "app": server_main.app,
+            "host": "0.0.0.0",
+            "port": 8009,
+        }
+    ]
 
 
 def test_server_cli_allows_explicit_host_and_port(monkeypatch):
@@ -115,11 +116,13 @@ def test_server_cli_allows_explicit_host_and_port(monkeypatch):
         ["dreamverse-server", "--host", "127.0.0.1", "--port", "8123"],
     )
 
-    assert calls == [{
-        "app": server_main.app,
-        "host": "127.0.0.1",
-        "port": 8123,
-    }]
+    assert calls == [
+        {
+            "app": server_main.app,
+            "host": "127.0.0.1",
+            "port": 8123,
+        }
+    ]
 
 
 def test_server_does_not_expose_backend_source_as_static_assets(monkeypatch):
@@ -139,11 +142,13 @@ def test_mock_server_cli_defaults_to_local_web_port(monkeypatch):
         ["dreamverse-mock-server"],
     )
 
-    assert calls == [{
-        "app": mock_server.app,
-        "host": "0.0.0.0",
-        "port": 8009,
-    }]
+    assert calls == [
+        {
+            "app": mock_server.app,
+            "host": "0.0.0.0",
+            "port": 8009,
+        }
+    ]
 
 
 def test_mock_server_cli_updates_latency(monkeypatch):
@@ -156,11 +161,13 @@ def test_mock_server_cli_updates_latency(monkeypatch):
             ["dreamverse-mock-server", "--latency", "321", "--port", "8111"],
         )
 
-        assert calls == [{
-            "app": mock_server.app,
-            "host": "0.0.0.0",
-            "port": 8111,
-        }]
+        assert calls == [
+            {
+                "app": mock_server.app,
+                "host": "0.0.0.0",
+                "port": 8111,
+            }
+        ]
         assert mock_server.LATENCY_MS == 321
     finally:
         mock_server.LATENCY_MS = old_latency_ms

apps/dreamverse/dreamverse/tests/test_gpu_pool.py

@@ -7,6 +7,7 @@ from types import SimpleNamespace
 
 import pytest
 
+
 import dreamverse.gpu_pool as gpu_pool
 
 
@@ -84,7 +85,9 @@ def test_send_command_raises_on_worker_death():
     cmd_q = ctx.Queue()
     resp_q = ctx.Queue()
 
-    proc = ctx.Process(target=_child_consume_and_exit, args=(cmd_q, resp_q))
+    proc = ctx.Process(
+        target=_child_consume_and_exit, args=(cmd_q, resp_q)
+    )
     proc.start()
 
     # Wait for the spawn child to fully boot.  Allow generous time —

apps/dreamverse/dreamverse/tests/test_import_contract.py

@@ -7,7 +7,7 @@ ALLOWED_PREFIXES = (
     "fastvideo.entrypoints.video_generator",
     "fastvideo.configs",
 )
-ALLOWED_EXACT = ("fastvideo", )
+ALLOWED_EXACT = ("fastvideo",)
 FORBIDDEN_PREFIXES = (
     "fastvideo.pipelines",
     "fastvideo.models",
@@ -38,13 +38,19 @@ def test_dreamverse_server_imports_only_public_fastvideo_surfaces() -> None:
         except SyntaxError as task_exc:
             raise AssertionError(f"Failed to parse {path}") from task_exc
         for node in ast.walk(tree):
-            names = ([a.name for a in node.names] if isinstance(node, ast.Import) else
-                     [node.module] if isinstance(node, ast.ImportFrom) and node.module else [])
+            names = (
+                [a.name for a in node.names] if isinstance(node, ast.Import)
+                else [node.module] if isinstance(node, ast.ImportFrom) and node.module
+                else []
+            )
             for name in names:
                 if not name:
                     continue
                 rel_path = str(path.relative_to(root))
-                if (name.startswith(FORBIDDEN_PREFIXES) and (rel_path, name) not in ALLOWED_INTERNAL_IMPORTS):
+                if (
+                    name.startswith(FORBIDDEN_PREFIXES)
+                    and (rel_path, name) not in ALLOWED_INTERNAL_IMPORTS
+                ):
                     bad.append((str(path.relative_to(root)), getattr(node, "lineno", 0), name))
 
     assert bad == [], f"Forbidden internal imports: {bad}"

apps/dreamverse/dreamverse/tests/test_mock_server.py

@@ -6,6 +6,7 @@ import os
 
 from fastapi import WebSocketDisconnect
 
+
 os.environ.setdefault("CEREBRAS_API_KEY", "dummy")
 os.environ.setdefault("GROQ_API_KEY", "dummy")
 
@@ -13,7 +14,6 @@ import dreamverse.mock_server as mock_server
 
 
 class _FakeWebSocket:
-
     def __init__(self, messages: list[tuple[float, dict[str, object]]]):
         self._messages = messages
         self._index = 0
@@ -49,34 +49,34 @@ def test_mock_server_matches_current_single5s_protocol():
         mock_server.MOCK_SEGMENT_BYTES = b"mock-fmp4-bytes"
         mock_server.LATENCY_MS = 1
 
-        ws = _FakeWebSocket([
-            (
-                0.0,
-                {
-                    "type": "session_init_v2",
-                    "preset_id": "simple_prompt_1",
-                    "curated_prompts": ["selected prompt"],
-                    "single_clip_mode": True,
-                    "enhancement_enabled": False,
-                    "auto_extension_enabled": False,
-                    "loop_generation_enabled": False,
-                },
-            ),
-            (
-                0.01,
-                {
-                    "type": "simple_generate",
-                    "preset_id": "simple_custom_prompt",
-                    "prompt_id": "simple_custom_prompt",
-                    "prompt": "custom prompt",
-                    "enhancement_enabled": True,
-                    "initial_image": None,
-                },
-            ),
-            (0.20, {
-                "type": "leave"
-            }),
-        ])
+        ws = _FakeWebSocket(
+            [
+                (
+                    0.0,
+                    {
+                        "type": "session_init_v2",
+                        "preset_id": "simple_prompt_1",
+                        "curated_prompts": ["selected prompt"],
+                        "single_clip_mode": True,
+                        "enhancement_enabled": False,
+                        "auto_extension_enabled": False,
+                        "loop_generation_enabled": False,
+                    },
+                ),
+                (
+                    0.01,
+                    {
+                        "type": "simple_generate",
+                        "preset_id": "simple_custom_prompt",
+                        "prompt_id": "simple_custom_prompt",
+                        "prompt": "custom prompt",
+                        "enhancement_enabled": True,
+                        "initial_image": None,
+                    },
+                ),
+                (0.20, {"type": "leave"}),
+            ]
+        )
 
         asyncio.run(mock_server.websocket_endpoint(ws))
 
@@ -92,14 +92,24 @@ def test_mock_server_matches_current_single5s_protocol():
         assert message_types.count("ltx2_stream_complete") == 2
         assert "prompt_sources_blocked" not in message_types
 
-        segment_start_events = [payload for payload in ws.sent_json if payload["type"] == "ltx2_segment_start"]
-        gpu_assigned_event = next(payload for payload in ws.sent_json if payload["type"] == "gpu_assigned")
+        segment_start_events = [
+            payload
+            for payload in ws.sent_json
+            if payload["type"] == "ltx2_segment_start"
+        ]
+        gpu_assigned_event = next(
+            payload for payload in ws.sent_json if payload["type"] == "gpu_assigned"
+        )
         assert gpu_assigned_event["session_timeout"] == mock_server.SESSION_TIMEOUT_SECONDS
         assert [payload["segment_idx"] for payload in segment_start_events] == [1, 1]
         assert segment_start_events[0]["prompt"] == "selected prompt"
         assert segment_start_events[1]["prompt"] == "custom prompt"
 
-        step_complete_events = [payload for payload in ws.sent_json if payload["type"] == "step_complete"]
+        step_complete_events = [
+            payload
+            for payload in ws.sent_json
+            if payload["type"] == "step_complete"
+        ]
         assert len(step_complete_events) == 2
         assert step_complete_events[0]["latency_ms"] == {
             "total": 121.0,
@@ -124,29 +134,29 @@ def test_mock_server_regular_cap_waits_for_rewrite_rollout():
         mock_server.LATENCY_MS = 1
         mock_server.GENERATION_SEGMENT_CAP = 1
 
-        ws = _FakeWebSocket([
-            (
-                0.0,
-                {
-                    "type": "session_init_v2",
-                    "preset_id": "test_preset",
-                    "curated_prompts": ["segment one"],
-                    "enhancement_enabled": True,
-                    "auto_extension_enabled": False,
-                    "loop_generation_enabled": False,
-                },
-            ),
-            (
-                0.02,
-                {
-                    "type": "rewrite_seed_prompts",
-                    "rewrite_instruction": "start a new rollout",
-                },
-            ),
-            (0.20, {
-                "type": "leave"
-            }),
-        ])
+        ws = _FakeWebSocket(
+            [
+                (
+                    0.0,
+                    {
+                        "type": "session_init_v2",
+                        "preset_id": "test_preset",
+                        "curated_prompts": ["segment one"],
+                        "enhancement_enabled": True,
+                        "auto_extension_enabled": False,
+                        "loop_generation_enabled": False,
+                    },
+                ),
+                (
+                    0.02,
+                    {
+                        "type": "rewrite_seed_prompts",
+                        "rewrite_instruction": "start a new rollout",
+                    },
+                ),
+                (0.20, {"type": "leave"}),
+            ]
+        )
 
         asyncio.run(mock_server.websocket_endpoint(ws))
 
@@ -156,7 +166,11 @@ def test_mock_server_regular_cap_waits_for_rewrite_rollout():
         assert "generation_cap_reached" not in message_types
         assert "prompt_sources_blocked" not in message_types
 
-        segment_start_events = [payload for payload in ws.sent_json if payload["type"] == "ltx2_segment_start"]
+        segment_start_events = [
+            payload
+            for payload in ws.sent_json
+            if payload["type"] == "ltx2_segment_start"
+        ]
         assert [payload["segment_idx"] for payload in segment_start_events] == [1, 1]
         assert segment_start_events[0]["prompt"] == "segment one"
         assert segment_start_events[1]["prompt"] == "segment one [start a new rollout]"
@@ -173,40 +187,54 @@ def test_mock_server_rewrite_during_active_segment_restarts_from_first_rewritten
         mock_server.MOCK_SEGMENT_BYTES = b"mock-fmp4-bytes"
         mock_server.LATENCY_MS = 100
 
-        ws = _FakeWebSocket([
-            (
-                0.0,
-                {
-                    "type": "session_init_v2",
-                    "preset_id": "test_preset",
-                    "curated_prompts": ["segment one", "segment two"],
-                    "enhancement_enabled": True,
-                    "auto_extension_enabled": False,
-                    "loop_generation_enabled": False,
-                },
-            ),
-            (
-                0.02,
-                {
-                    "type": "rewrite_seed_prompts",
-                    "rewrite_instruction": "restart from rewrite",
-                },
-            ),
-            (0.40, {
-                "type": "leave"
-            }),
-        ])
+        ws = _FakeWebSocket(
+            [
+                (
+                    0.0,
+                    {
+                        "type": "session_init_v2",
+                        "preset_id": "test_preset",
+                        "curated_prompts": ["segment one", "segment two"],
+                        "enhancement_enabled": True,
+                        "auto_extension_enabled": False,
+                        "loop_generation_enabled": False,
+                    },
+                ),
+                (
+                    0.02,
+                    {
+                        "type": "rewrite_seed_prompts",
+                        "rewrite_instruction": "restart from rewrite",
+                    },
+                ),
+                (0.40, {"type": "leave"}),
+            ]
+        )
 
         asyncio.run(mock_server.websocket_endpoint(ws))
 
-        segment_start_events = [payload for payload in ws.sent_json if payload["type"] == "ltx2_segment_start"]
+        segment_start_events = [
+            payload
+            for payload in ws.sent_json
+            if payload["type"] == "ltx2_segment_start"
+        ]
         assert [payload["prompt"] for payload in segment_start_events[:2]] == [
             "segment one",
             "segment one [restart from rewrite]",
         ]
-        assert all(payload["prompt"] != "segment two" for payload in segment_start_events[1:])
-        reset_events = [payload for payload in ws.sent_json if payload.get("type") == "seed_prompts_reset_applied"]
-        assert any(payload.get("reason") == "rewrite_during_generation" for payload in reset_events)
+        assert all(
+            payload["prompt"] != "segment two"
+            for payload in segment_start_events[1:]
+        )
+        reset_events = [
+            payload
+            for payload in ws.sent_json
+            if payload.get("type") == "seed_prompts_reset_applied"
+        ]
+        assert any(
+            payload.get("reason") == "rewrite_during_generation"
+            for payload in reset_events
+        )
     finally:
         mock_server.MOCK_SEGMENT_BYTES = old_segment_bytes
         mock_server.LATENCY_MS = old_latency_ms
@@ -219,24 +247,24 @@ def test_mock_server_supports_initial_custom_rollout_prompt():
         mock_server.MOCK_SEGMENT_BYTES = b"mock-fmp4-bytes"
         mock_server.LATENCY_MS = 1
 
-        ws = _FakeWebSocket([
-            (
-                0.0,
-                {
-                    "type": "session_init_v2",
-                    "preset_id": "custom_editable",
-                    "preset_label": "Custom rollout",
-                    "curated_prompts": [],
-                    "initial_rollout_prompt": "A moonbase corridor thriller with flooding",
-                    "enhancement_enabled": True,
-                    "auto_extension_enabled": False,
-                    "loop_generation_enabled": False,
-                },
-            ),
-            (0.20, {
-                "type": "leave"
-            }),
-        ])
+        ws = _FakeWebSocket(
+            [
+                (
+                    0.0,
+                    {
+                        "type": "session_init_v2",
+                        "preset_id": "custom_editable",
+                        "preset_label": "Custom rollout",
+                        "curated_prompts": [],
+                        "initial_rollout_prompt": "A moonbase corridor thriller with flooding",
+                        "enhancement_enabled": True,
+                        "auto_extension_enabled": False,
+                        "loop_generation_enabled": False,
+                    },
+                ),
+                (0.20, {"type": "leave"}),
+            ]
+        )
 
         asyncio.run(mock_server.websocket_endpoint(ws))
 
@@ -248,9 +276,15 @@ def test_mock_server_supports_initial_custom_rollout_prompt():
         assert "ltx2_stream_start" in message_types
         assert "prompt_sources_blocked" not in message_types
 
-        segment_start_events = [payload for payload in ws.sent_json if payload["type"] == "ltx2_segment_start"]
+        segment_start_events = [
+            payload
+            for payload in ws.sent_json
+            if payload["type"] == "ltx2_segment_start"
+        ]
         assert segment_start_events
-        assert segment_start_events[0]["prompt"] == ("A moonbase corridor thriller with flooding [segment 1]")
+        assert segment_start_events[0]["prompt"] == (
+            "A moonbase corridor thriller with flooding [segment 1]"
+        )
     finally:
         mock_server.MOCK_SEGMENT_BYTES = old_segment_bytes
         mock_server.LATENCY_MS = old_latency_ms
@@ -263,37 +297,35 @@ def test_mock_server_can_start_new_project_without_reconnecting():
         mock_server.MOCK_SEGMENT_BYTES = b"mock-fmp4-bytes"
         mock_server.LATENCY_MS = 40
 
-        ws = _FakeWebSocket([
-            (
-                0.0,
-                {
-                    "type": "session_init_v2",
-                    "preset_id": "test_preset",
-                    "curated_prompts": ["segment one"],
-                    "enhancement_enabled": True,
-                    "auto_extension_enabled": False,
-                    "loop_generation_enabled": False,
-                },
-            ),
-            (0.02, {
-                "type": "end_project_keep_session"
-            }),
-            (
-                0.20,
-                {
-                    "type": "project_init_v1",
-                    "preset_id": "test_preset_2",
-                    "preset_label": "Test Preset 2",
-                    "curated_prompts": ["segment two"],
-                    "enhancement_enabled": True,
-                    "auto_extension_enabled": False,
-                    "loop_generation_enabled": False,
-                },
-            ),
-            (0.40, {
-                "type": "leave"
-            }),
-        ])
+        ws = _FakeWebSocket(
+            [
+                (
+                    0.0,
+                    {
+                        "type": "session_init_v2",
+                        "preset_id": "test_preset",
+                        "curated_prompts": ["segment one"],
+                        "enhancement_enabled": True,
+                        "auto_extension_enabled": False,
+                        "loop_generation_enabled": False,
+                    },
+                ),
+                (0.02, {"type": "end_project_keep_session"}),
+                (
+                    0.20,
+                    {
+                        "type": "project_init_v1",
+                        "preset_id": "test_preset_2",
+                        "preset_label": "Test Preset 2",
+                        "curated_prompts": ["segment two"],
+                        "enhancement_enabled": True,
+                        "auto_extension_enabled": False,
+                        "loop_generation_enabled": False,
+                    },
+                ),
+                (0.40, {"type": "leave"}),
+            ]
+        )
 
         asyncio.run(mock_server.websocket_endpoint(ws))
 
@@ -304,11 +336,16 @@ def test_mock_server_can_start_new_project_without_reconnecting():
 
         project_idle_index = message_types.index("project_idle")
         stream_start_indexes = [
-            index for index, message_type in enumerate(message_types) if message_type == "ltx2_stream_start"
+            index for index, message_type in enumerate(message_types)
+            if message_type == "ltx2_stream_start"
         ]
         assert stream_start_indexes[0] < project_idle_index < stream_start_indexes[1]
 
-        segment_start_events = [payload for payload in ws.sent_json if payload["type"] == "ltx2_segment_start"]
+        segment_start_events = [
+            payload
+            for payload in ws.sent_json
+            if payload["type"] == "ltx2_segment_start"
+        ]
         assert [payload["prompt"] for payload in segment_start_events[:2]] == [
             "segment one",
             "segment two",

apps/dreamverse/dreamverse/tests/test_prompt_enhancer.py

@@ -6,6 +6,7 @@ import os
 import re
 import time
 
+
 os.environ.setdefault("CEREBRAS_API_KEY", "dummy")
 os.environ.setdefault("GROQ_API_KEY", "dummy")
 
@@ -21,7 +22,6 @@ from dreamverse.prompt_enhancer import (
 
 
 class _FakeResponse:
-
     def __init__(self, payload: dict):
         self._payload = payload
 
@@ -30,7 +30,6 @@ class _FakeResponse:
 
 
 class _FakeSyncCompletions:
-
     def __init__(self, payload: dict):
         self._payload = payload
 
@@ -39,7 +38,6 @@ class _FakeSyncCompletions:
 
 
 class _FakeSyncClient:
-
     def __init__(self, payload: dict):
         self.chat = type(
             "_FakeChat",
@@ -49,7 +47,6 @@ class _FakeSyncClient:
 
 
 class _DelayedSyncCompletions:
-
     def __init__(self, payload: dict, delay_s: float = 0.0, exc: Exception | None = None):
         self._payload = payload
         self._delay_s = delay_s
@@ -64,26 +61,29 @@ class _DelayedSyncCompletions:
 
 
 class _DelayedSyncClient:
-
     def __init__(self, payload: dict, delay_s: float = 0.0, exc: Exception | None = None):
         self.chat = type(
             "_FakeChat",
             (),
-            {"completions": _DelayedSyncCompletions(
-                payload,
-                delay_s=delay_s,
-                exc=exc,
-            )},
+            {
+                "completions": _DelayedSyncCompletions(
+                    payload,
+                    delay_s=delay_s,
+                    exc=exc,
+                )
+            },
         )()
 
 
 def _chat_payload_with_content(content: str) -> dict:
     return {
-        "choices": [{
-            "message": {
-                "content": content,
+        "choices": [
+            {
+                "message": {
+                    "content": content,
+                }
             }
-        }]
+        ]
     }
 
 
@@ -172,7 +172,6 @@ def _build_staged_enhancer(
 
 
 class _FakeOpenAIClient:
-
     def __init__(self, **kwargs):
         self.kwargs = kwargs
         self.chat = type(
@@ -183,7 +182,6 @@ class _FakeOpenAIClient:
 
 
 class _FakeCerebrasClient:
-
     def __init__(self, **kwargs):
         self.kwargs = kwargs
         self.chat = type(
@@ -194,12 +192,16 @@ class _FakeCerebrasClient:
 
 
 def test_parse_json_response_accepts_fenced_json_with_prose():
-    parsed = _parse_json_response("Here is the rewrite:\n```json\n{\"segment_prompts\":[\"A\",\"B\"]}\n```\nThanks.")
+    parsed = _parse_json_response(
+        "Here is the rewrite:\n```json\n{\"segment_prompts\":[\"A\",\"B\"]}\n```\nThanks."
+    )
     assert parsed == {"segment_prompts": ["A", "B"]}
 
 
 def test_parse_json_response_extracts_first_embedded_object():
-    parsed = _parse_json_response("Model output:\n{\"segment_prompts\":[\"A\",\"B\"]}\n(complete)")
+    parsed = _parse_json_response(
+        "Model output:\n{\"segment_prompts\":[\"A\",\"B\"]}\n(complete)"
+    )
     assert parsed == {"segment_prompts": ["A", "B"]}
 
 
@@ -266,12 +268,16 @@ def test_build_client_supports_groq_provider(monkeypatch):
 
 def test_rewrite_prompt_sequence_accepts_segment_prompts_output():
     enhancer = _build_test_enhancer(
-        _chat_payload_with_content('{"id":"preset_a","label":"Preset A","segment_prompts":["A","B"]}'))
+        _chat_payload_with_content(
+            '{"id":"preset_a","label":"Preset A","segment_prompts":["A","B"]}'
+        )
+    )
     result = asyncio.run(
         enhancer.rewrite_prompt_sequence(
             ["prompt one", "prompt two"],
             rewrite_instruction="make it cinematic",
-        ))
+        )
+    )
     assert result.fallback_used is False
     assert result.error is None
     assert result.rollout_id == "preset_a"
@@ -280,12 +286,15 @@ def test_rewrite_prompt_sequence_accepts_segment_prompts_output():
 
 
 def test_rewrite_prompt_sequence_accepts_legacy_rewritten_prompts_output():
-    enhancer = _build_test_enhancer(_chat_payload_with_content('{"rewritten_prompts":["A","B"]}'))
+    enhancer = _build_test_enhancer(
+        _chat_payload_with_content('{"rewritten_prompts":["A","B"]}')
+    )
     result = asyncio.run(
         enhancer.rewrite_prompt_sequence(
             ["prompt one", "prompt two"],
             rewrite_instruction="make it cinematic",
-        ))
+        )
+    )
     assert result.fallback_used is False
     assert result.error is None
     assert result.rollout_id == "current_rollout"
@@ -294,14 +303,19 @@ def test_rewrite_prompt_sequence_accepts_legacy_rewritten_prompts_output():
 
 
 def test_rewrite_prompt_sequence_accepts_segment_dicts_without_top_level_rollout_metadata():
-    enhancer = _build_test_enhancer(_chat_payload_with_content('{"segments":[{"prompt":"A"},{"text":"B"}]}'))
+    enhancer = _build_test_enhancer(
+        _chat_payload_with_content(
+            '{"segments":[{"prompt":"A"},{"text":"B"}]}'
+        )
+    )
     result = asyncio.run(
         enhancer.rewrite_prompt_sequence(
             ["prompt one", "prompt two"],
             preset_id="preset_a",
             preset_label="Preset A",
             rewrite_instruction="make it cinematic",
-        ))
+        )
+    )
     assert result.fallback_used is False
     assert result.error is None
     assert result.rollout_id == "preset_a"
@@ -315,12 +329,14 @@ def test_rewrite_prompt_sequence_accepts_numbered_prose_output():
             "The user is asking for a cinematic rewrite.\n\n"
             "1. A dog bounds across the moon's dusty surface, kicking up silver regolith as it chases a rabbit beneath the black sky.\n"
             "2. The rabbit darts around a crater rim while the dog lunges after it, Earth glowing blue in the distance.\n"
-        ))
+        )
+    )
     result = asyncio.run(
         enhancer.rewrite_prompt_sequence(
             ["prompt one", "prompt two"],
             rewrite_instruction="make it cinematic",
-        ))
+        )
+    )
     assert result.fallback_used is False
     assert result.error is None
     assert result.rollout_id == "current_rollout"
@@ -339,10 +355,12 @@ def test_enhance_prompt_prefers_cerebras_before_groq_fallback():
         groq_delay_s=0.01,
     )
 
-    result = asyncio.run(enhancer.enhance_prompt(
-        "A rainy alley at night",
-        mode="single_clip",
-    ))
+    result = asyncio.run(
+        enhancer.enhance_prompt(
+            "A rainy alley at night",
+            mode="single_clip",
+        )
+    )
 
     assert result.fallback_used is False
     assert result.error is None
@@ -363,10 +381,12 @@ def test_enhance_prompt_uses_groq_when_cerebras_fails():
         groq_delay_s=0.01,
     )
 
-    result = asyncio.run(enhancer.enhance_prompt(
-        "A rainy alley at night",
-        mode="single_clip",
-    ))
+    result = asyncio.run(
+        enhancer.enhance_prompt(
+            "A rainy alley at night",
+            mode="single_clip",
+        )
+    )
 
     assert result.fallback_used is False
     assert result.error is None
@@ -388,11 +408,13 @@ def test_enhance_prompt_can_use_groq_when_cerebras_times_out():
     enhancer.http_timeout_ms = 50
     enhancer.default_timeout_ms = 50
 
-    result = asyncio.run(enhancer.enhance_prompt(
-        "A rainy alley at night",
-        mode="single_clip",
-        timeout_ms=50,
-    ))
+    result = asyncio.run(
+        enhancer.enhance_prompt(
+            "A rainy alley at night",
+            mode="single_clip",
+            timeout_ms=50,
+        )
+    )
 
     assert result.fallback_used is False
     assert result.error is None
@@ -412,10 +434,12 @@ def test_enhance_prompt_can_use_cerebras_when_it_returns_first():
         groq_delay_s=0.08,
     )
 
-    result = asyncio.run(enhancer.enhance_prompt(
-        "A rainy alley at night",
-        mode="single_clip",
-    ))
+    result = asyncio.run(
+        enhancer.enhance_prompt(
+            "A rainy alley at night",
+            mode="single_clip",
+        )
+    )
 
     assert result.fallback_used is False
     assert result.error is None
@@ -429,12 +453,15 @@ def test_enhance_prompt_can_use_cerebras_when_it_returns_first():
 
 
 def test_rewrite_prompt_sequence_keeps_raw_output_on_parse_error():
-    enhancer = _build_test_enhancer(_chat_payload_with_content("I cannot comply with JSON right now."))
+    enhancer = _build_test_enhancer(
+        _chat_payload_with_content("I cannot comply with JSON right now.")
+    )
     result = asyncio.run(
         enhancer.rewrite_prompt_sequence(
             ["prompt one", "prompt two"],
             rewrite_instruction="make it cinematic",
-        ))
+        )
+    )
     assert result.fallback_used is True
     assert "No JSON object found in assistant response." in (result.error or "")
     assert result.raw_response_text == "I cannot comply with JSON right now."
@@ -446,7 +473,9 @@ def test_rewrite_prompt_sequence_keeps_raw_output_on_parse_error():
 def test_rewrite_prompt_sequence_uses_current_rollout_payload_shape():
     enhancer = _build_test_enhancer(
         _chat_payload_with_content(
-            '{"id":"rewritten_rollout","label":"Rewritten Rollout","segment_prompts":["A","B"]}'))
+            '{"id":"rewritten_rollout","label":"Rewritten Rollout","segment_prompts":["A","B"]}'
+        )
+    )
     captured = {
         "body": None,
         "timeout_seconds": None,
@@ -457,7 +486,8 @@ def test_rewrite_prompt_sequence_uses_current_rollout_payload_shape():
         captured["timeout_seconds"] = timeout_seconds
         return (
             _chat_payload_with_content(
-                '{"id":"rewritten_rollout","label":"Rewritten Rollout","segment_prompts":["A","B"]}'),
+                '{"id":"rewritten_rollout","label":"Rewritten Rollout","segment_prompts":["A","B"]}'
+            ),
             '{"id":"rewritten_rollout","label":"Rewritten Rollout","segment_prompts":["A","B"]}',
         )
 
@@ -472,7 +502,8 @@ def test_rewrite_prompt_sequence_uses_current_rollout_payload_shape():
             rewrite_model="gpt-test",
             rewrite_temperature=0.2,
             timeout_ms=800,
-        ))
+        )
+    )
 
     assert result.fallback_used is False
     assert captured["body"]["messages"][0] == {
@@ -481,12 +512,12 @@ def test_rewrite_prompt_sequence_uses_current_rollout_payload_shape():
     }
     assert captured["body"]["messages"][1]["role"] == "user"
     assert prompt_enhancer_module.json.loads(captured["body"]["messages"][1]["content"]) == {
-        "mode":
-        "edit_existing_rollout",
-        "request": ("Rewrite all segment prompts with improved continuity and cinematic detail. "
-                    "Keep count and ordering identical."),
-        "user_instruction":
-        "make it cinematic",
+        "mode": "edit_existing_rollout",
+        "request": (
+            "Rewrite all segment prompts with improved continuity and cinematic detail. "
+            "Keep count and ordering identical."
+        ),
+        "user_instruction": "make it cinematic",
         "current_rollout": {
             "id": "preset_a",
             "label": "Preset A",
@@ -497,8 +528,11 @@ def test_rewrite_prompt_sequence_uses_current_rollout_payload_shape():
 
 def test_rewrite_prompt_sequence_supports_new_rollout_mode():
     enhancer = _build_test_enhancer(
-        _chat_payload_with_content('{"id":"custom_editable","label":"Custom rollout","segment_prompts":['
-                                   '"A","B","C","D","E","F"]}'))
+        _chat_payload_with_content(
+            '{"id":"custom_editable","label":"Custom rollout","segment_prompts":['
+            '"A","B","C","D","E","F"]}'
+        )
+    )
     captured = {
         "body": None,
     }
@@ -507,8 +541,10 @@ def test_rewrite_prompt_sequence_supports_new_rollout_mode():
         del timeout_seconds
         captured["body"] = body
         return (
-            _chat_payload_with_content('{"id":"custom_editable","label":"Custom rollout","segment_prompts":['
-                                       '"A","B","C","D","E","F"]}'),
+            _chat_payload_with_content(
+                '{"id":"custom_editable","label":"Custom rollout","segment_prompts":['
+                '"A","B","C","D","E","F"]}'
+            ),
             '{"id":"custom_editable","label":"Custom rollout","segment_prompts":['
             '"A","B","C","D","E","F"]}',
         )
@@ -524,29 +560,30 @@ def test_rewrite_prompt_sequence_supports_new_rollout_mode():
             rewrite_model="gpt-test",
             rewrite_temperature=0.2,
             timeout_ms=800,
-        ))
+        )
+    )
 
     assert result.fallback_used is False
     assert result.prompts == ["A", "B", "C", "D", "E", "F"]
     assert prompt_enhancer_module.json.loads(captured["body"]["messages"][1]["content"]) == {
-        "mode":
-        "new_rollout",
-        "request": ("Rewrite all segment prompts with improved continuity and cinematic detail. "
-                    "Keep count and ordering identical."),
-        "user_instruction":
-        "A moonbase corridor thriller with flooding and red alarms",
-        "desired_segment_count":
-        6,
-        "rollout_id_hint":
-        "custom_editable",
-        "rollout_label_hint":
-        "Custom rollout",
+        "mode": "new_rollout",
+        "request": (
+            "Rewrite all segment prompts with improved continuity and cinematic detail. "
+            "Keep count and ordering identical."
+        ),
+        "user_instruction": "A moonbase corridor thriller with flooding and red alarms",
+        "desired_segment_count": 6,
+        "rollout_id_hint": "custom_editable",
+        "rollout_label_hint": "Custom rollout",
     }
 
 
 def test_rewrite_prompt_sequence_uses_session_override_system_prompt():
     enhancer = _build_test_enhancer(
-        _chat_payload_with_content('{"id":"preset_a","label":"Preset A","segment_prompts":["A","B"]}'))
+        _chat_payload_with_content(
+            '{"id":"preset_a","label":"Preset A","segment_prompts":["A","B"]}'
+        )
+    )
     enhancer.rewrite_all_system_prompt = "shared system prompt"
     captured = {
         "body": None,
@@ -556,7 +593,9 @@ def test_rewrite_prompt_sequence_uses_session_override_system_prompt():
         del timeout_seconds
         captured["body"] = body
         return (
-            _chat_payload_with_content('{"id":"preset_a","label":"Preset A","segment_prompts":["A","B"]}'),
+            _chat_payload_with_content(
+                '{"id":"preset_a","label":"Preset A","segment_prompts":["A","B"]}'
+            ),
             '{"id":"preset_a","label":"Preset A","segment_prompts":["A","B"]}',
         )
 
@@ -570,7 +609,8 @@ def test_rewrite_prompt_sequence_uses_session_override_system_prompt():
             rewrite_instruction="make it cinematic",
             rewrite_model="gpt-test",
             system_prompt_override="session specific system prompt",
-        ))
+        )
+    )
 
     assert result.fallback_used is False
     assert captured["body"]["messages"][0] == {
@@ -581,7 +621,10 @@ def test_rewrite_prompt_sequence_uses_session_override_system_prompt():
 
 def test_resolve_rewrite_new_rollout_system_prompt_uses_dedicated_prompt():
     enhancer = _build_test_enhancer(
-        _chat_payload_with_content('{"id":"preset_a","label":"Preset A","segment_prompts":["A","B"]}'))
+        _chat_payload_with_content(
+            '{"id":"preset_a","label":"Preset A","segment_prompts":["A","B"]}'
+        )
+    )
     enhancer.rewrite_all_system_prompt = "shared rewrite system prompt"
     enhancer.rewrite_user_system_prompt = "new rollout rewrite system prompt"
 
@@ -592,17 +635,24 @@ def test_resolve_rewrite_new_rollout_system_prompt_uses_dedicated_prompt():
 
 def test_resolve_rewrite_new_rollout_system_prompt_prefers_override():
     enhancer = _build_test_enhancer(
-        _chat_payload_with_content('{"id":"preset_a","label":"Preset A","segment_prompts":["A","B"]}'))
+        _chat_payload_with_content(
+            '{"id":"preset_a","label":"Preset A","segment_prompts":["A","B"]}'
+        )
+    )
     enhancer.rewrite_all_system_prompt = "shared rewrite system prompt"
     enhancer.rewrite_user_system_prompt = "new rollout rewrite system prompt"
 
-    resolved = enhancer.resolve_rewrite_new_rollout_system_prompt("session specific system prompt")
+    resolved = enhancer.resolve_rewrite_new_rollout_system_prompt(
+        "session specific system prompt"
+    )
 
     assert resolved == "session specific system prompt"
 
 
 def test_generate_auto_prompt_uses_selected_model():
-    enhancer = _build_test_enhancer(_chat_payload_with_content('{"next_prompt":"Auto next"}'))
+    enhancer = _build_test_enhancer(
+        _chat_payload_with_content('{"next_prompt":"Auto next"}')
+    )
     enhancer.auto_system_prompt = "auto system prompt"
     enhancer.rewrite_model_options = ["gpt-test", "gpt-alt"]
     enhancer.rewrite_default_model = "gpt-test"
@@ -630,7 +680,8 @@ def test_generate_auto_prompt_uses_selected_model():
             next_segment_idx=2,
             model="gpt-alt",
             timeout_ms=800,
-        ))
+        )
+    )
     assert result.fallback_used is False
     assert result.error is None
     assert result.prompt == "Auto next"
@@ -639,7 +690,9 @@ def test_generate_auto_prompt_uses_selected_model():
 
 
 def test_enhance_prompt_uses_selected_model():
-    enhancer = _build_test_enhancer(_chat_payload_with_content('{"next_prompt":"Enhanced next"}'))
+    enhancer = _build_test_enhancer(
+        _chat_payload_with_content('{"next_prompt":"Enhanced next"}')
+    )
     enhancer.enhance_system_prompt = "enhance system prompt"
     enhancer.auto_system_prompt = "auto system prompt"
     enhancer.rewrite_model_options = ["gpt-test", "gpt-alt"]
@@ -669,7 +722,8 @@ def test_enhance_prompt_uses_selected_model():
             next_segment_idx=2,
             model="gpt-alt",
             timeout_ms=800,
-        ))
+        )
+    )
     assert result.fallback_used is False
     assert result.error is None
     assert result.prompt == "Enhanced next"
@@ -678,7 +732,9 @@ def test_enhance_prompt_uses_selected_model():
 
 
 def test_enhance_prompt_single_clip_uses_auto_extension_prompt_and_prompt_field():
-    enhancer = _build_test_enhancer(_chat_payload_with_content('{"prompt":"Extended single clip"}'))
+    enhancer = _build_test_enhancer(
+        _chat_payload_with_content('{"prompt":"Extended single clip"}')
+    )
     enhancer.enhance_system_prompt = "enhance system prompt"
     enhancer.auto_system_prompt = "auto system prompt"
     enhancer.rewrite_model_options = ["gpt-test", "gpt-alt"]
@@ -708,12 +764,14 @@ def test_enhance_prompt_single_clip_uses_auto_extension_prompt_and_prompt_field(
 
     enhancer._request_content = _fake_request_content  # type: ignore[attr-defined]
 
-    result = asyncio.run(enhancer.enhance_prompt(
-        "short 5s idea",
-        mode="single_clip",
-        model="gpt-alt",
-        timeout_ms=800,
-    ))
+    result = asyncio.run(
+        enhancer.enhance_prompt(
+            "short 5s idea",
+            mode="single_clip",
+            model="gpt-alt",
+            timeout_ms=800,
+        )
+    )
     assert result.fallback_used is False
     assert result.error is None
     assert result.prompt == "Extended single clip"
@@ -726,15 +784,17 @@ def test_enhance_prompt_single_clip_uses_auto_extension_prompt_and_prompt_field(
             "single 5-second LTX-2.3 video clip. Respond with "
             'valid JSON only as {"prompt": "..."}.'  # noqa: E501
         ),
-        "user_prompt":
-        "short 5s idea",
+        "user_prompt": "short 5s idea",
     }
 
 
 def test_enhance_prompt_single_clip_rejects_plain_text_response():
     enhancer = _build_test_enhancer(
-        _chat_payload_with_content("Medium shot of a woman by a rainy cafe window as she lifts her "
-                                   "phone, exhales softly, and the camera makes a slow push in."))
+        _chat_payload_with_content(
+            "Medium shot of a woman by a rainy cafe window as she lifts her "
+            "phone, exhales softly, and the camera makes a slow push in."
+        )
+    )
     enhancer.auto_system_prompt = "auto system prompt"
 
     result = asyncio.run(
@@ -743,14 +803,17 @@ def test_enhance_prompt_single_clip_rejects_plain_text_response():
             mode="single_clip",
             model="gpt-test",
             timeout_ms=800,
-        ))
+        )
+    )
     assert result.fallback_used is True
     assert "No JSON object found in assistant response." in result.error
     assert result.prompt == ""
 
 
 def test_enhance_prompt_single_clip_rejects_segment_prompts_json():
-    enhancer = _build_test_enhancer(_chat_payload_with_content('{"segment_prompts":["A","B"]}'))
+    enhancer = _build_test_enhancer(
+        _chat_payload_with_content('{"segment_prompts":["A","B"]}')
+    )
     enhancer.auto_system_prompt = "auto system prompt"
     enhancer.rewrite_model_options = ["gpt-test"]
     enhancer.rewrite_default_model = "gpt-test"
@@ -761,14 +824,17 @@ def test_enhance_prompt_single_clip_rejects_segment_prompts_json():
             mode="single_clip",
             model="gpt-test",
             timeout_ms=800,
-        ))
+        )
+    )
     assert result.fallback_used is True
     assert result.prompt == ""
     assert "Missing prompt string." in (result.error or "")
 
 
 def test_enhance_prompt_requires_json_and_does_not_fallback_to_raw_text():
-    enhancer = _build_test_enhancer(_chat_payload_with_content("A cinematic continuation with slow dolly movement."))
+    enhancer = _build_test_enhancer(
+        _chat_payload_with_content("A cinematic continuation with slow dolly movement.")
+    )
     enhancer.enhance_system_prompt = "enhance system prompt"
     enhancer.rewrite_model_options = ["gpt-test"]
     enhancer.rewrite_default_model = "gpt-test"
@@ -780,14 +846,17 @@ def test_enhance_prompt_requires_json_and_does_not_fallback_to_raw_text():
             next_segment_idx=2,
             model="gpt-test",
             timeout_ms=800,
-        ))
+        )
+    )
     assert result.fallback_used is True
     assert result.prompt == ""
     assert "No JSON object found in assistant response." in (result.error or "")
 
 
 def test_generate_auto_prompt_requires_json_and_does_not_fallback_to_raw_text():
-    enhancer = _build_test_enhancer(_chat_payload_with_content("A calm, grounded continuation with subtle motion."))
+    enhancer = _build_test_enhancer(
+        _chat_payload_with_content("A calm, grounded continuation with subtle motion.")
+    )
     enhancer.auto_system_prompt = "auto system prompt"
     enhancer.rewrite_model_options = ["gpt-test"]
     enhancer.rewrite_default_model = "gpt-test"
@@ -798,30 +867,34 @@ def test_generate_auto_prompt_requires_json_and_does_not_fallback_to_raw_text():
             next_segment_idx=2,
             model="gpt-test",
             timeout_ms=800,
-        ))
+        )
+    )
     assert result.fallback_used is True
     assert result.prompt == ""
     assert "No JSON object found in assistant response." in (result.error or "")
 
 
 def test_rewrite_prompt_sequence_includes_raw_json_when_content_empty():
-    enhancer = _build_test_enhancer({
-        "choices": [{
-            "finish_reason": "length",
-            "message": {
-                "content": [],
-                "refusal": None,
-            },
-        }],
-        "usage": {
-            "completion_tokens": 0
-        },
-    })
+    enhancer = _build_test_enhancer(
+        {
+            "choices": [
+                {
+                    "finish_reason": "length",
+                    "message": {
+                        "content": [],
+                        "refusal": None,
+                    },
+                }
+            ],
+            "usage": {"completion_tokens": 0},
+        }
+    )
     result = asyncio.run(
         enhancer.rewrite_prompt_sequence(
             ["prompt one", "prompt two"],
             rewrite_instruction="make it cinematic",
-        ))
+        )
+    )
     assert result.fallback_used is True
     assert "No rewrite segment prompts found in assistant response." in (result.error or "")
     assert isinstance(result.raw_response_text, str)
@@ -830,7 +903,10 @@ def test_rewrite_prompt_sequence_includes_raw_json_when_content_empty():
 
 def test_get_rewrite_model_config_returns_fixed_defaults():
     enhancer = _build_test_enhancer(
-        _chat_payload_with_content('{"id":"preset_a","label":"Preset A","segment_prompts":["A","B"]}'))
+        _chat_payload_with_content(
+            '{"id":"preset_a","label":"Preset A","segment_prompts":["A","B"]}'
+        )
+    )
     enhancer.rewrite_default_model = "gpt-oss-120b"
     enhancer.rewrite_model_options = ["gpt-oss-120b"]
 
@@ -842,7 +918,10 @@ def test_get_rewrite_model_config_returns_fixed_defaults():
 
 def test_get_prompt_config_includes_auto_extension_prompt():
     enhancer = _build_test_enhancer(
-        _chat_payload_with_content('{"id":"preset_a","label":"Preset A","segment_prompts":["A","B"]}'))
+        _chat_payload_with_content(
+            '{"id":"preset_a","label":"Preset A","segment_prompts":["A","B"]}'
+        )
+    )
     enhancer.enhance_system_prompt_path = "/tmp/next.md"
     enhancer.auto_system_prompt_path = "/tmp/auto.md"
     enhancer.rewrite_all_system_prompt_path = "/tmp/rewrite.md"
@@ -869,14 +948,19 @@ def test_get_prompt_config_includes_auto_extension_prompt():
 
 def test_get_prompt_config_reports_loaded_fallback_prompt_path(tmp_path):
     enhancer = _build_test_enhancer(
-        _chat_payload_with_content('{"id":"preset_a","label":"Preset A","segment_prompts":["A","B"]}'))
+        _chat_payload_with_content(
+            '{"id":"preset_a","label":"Preset A","segment_prompts":["A","B"]}'
+        )
+    )
     rewrite_fallback_path = tmp_path / "rewrite_window_system_prompt.md"
     rewrite_fallback_path.write_text("rewrite prompt\n", encoding="utf-8")
     next_path = tmp_path / "next.md"
     next_path.write_text("next prompt\n", encoding="utf-8")
     auto_path = tmp_path / "auto.md"
     auto_path.write_text("auto prompt\n", encoding="utf-8")
-    enhancer.rewrite_all_system_prompt_path = str(tmp_path / "prompts.local" / "rewrite_window_system_prompt.md")
+    enhancer.rewrite_all_system_prompt_path = str(
+        tmp_path / "prompts.local" / "rewrite_window_system_prompt.md"
+    )
     enhancer.rewrite_all_system_prompt_fallback_path = str(rewrite_fallback_path)
     enhancer.enhance_system_prompt_path = str(next_path)
     enhancer.auto_system_prompt_path = str(auto_path)
@@ -889,9 +973,14 @@ def test_get_prompt_config_reports_loaded_fallback_prompt_path(tmp_path):
     assert config["rewrite_window_system_prompt_path"] == str(rewrite_fallback_path)
 
 
-def test_reload_system_prompts_falls_back_to_rewrite_window_when_user_prompt_empty(tmp_path, ):
+def test_reload_system_prompts_falls_back_to_rewrite_window_when_user_prompt_empty(
+    tmp_path,
+):
     enhancer = _build_test_enhancer(
-        _chat_payload_with_content('{"id":"preset_a","label":"Preset A","segment_prompts":["A","B"]}'))
+        _chat_payload_with_content(
+            '{"id":"preset_a","label":"Preset A","segment_prompts":["A","B"]}'
+        )
+    )
     next_path = tmp_path / "next.md"
     auto_path = tmp_path / "auto.md"
     rewrite_path = tmp_path / "rewrite_window_system_prompt.md"
@@ -918,7 +1007,10 @@ def test_reload_system_prompts_falls_back_to_rewrite_window_when_user_prompt_emp
 
 def test_save_prompt_config_updates_auto_extension_prompt(tmp_path):
     enhancer = _build_test_enhancer(
-        _chat_payload_with_content('{"id":"preset_a","label":"Preset A","segment_prompts":["A","B"]}'))
+        _chat_payload_with_content(
+            '{"id":"preset_a","label":"Preset A","segment_prompts":["A","B"]}'
+        )
+    )
     next_path = tmp_path / "next.md"
     auto_path = tmp_path / "auto.md"
     rewrite_path = tmp_path / "rewrite.md"
@@ -929,7 +1021,9 @@ def test_save_prompt_config_updates_auto_extension_prompt(tmp_path):
     enhancer.auto_system_prompt_path = str(auto_path)
     enhancer.rewrite_all_system_prompt_path = str(rewrite_path)
 
-    config = enhancer.save_prompt_config(auto_extension_system_prompt="auto updated", )
+    config = enhancer.save_prompt_config(
+        auto_extension_system_prompt="auto updated",
+    )
 
     assert auto_path.read_text(encoding="utf-8").strip() == "auto updated"
     assert config["auto_extension_system_prompt"] == "auto updated"
@@ -937,7 +1031,10 @@ def test_save_prompt_config_updates_auto_extension_prompt(tmp_path):
 
 def test_save_prompt_config_updates_rewrite_user_prompt(tmp_path):
     enhancer = _build_test_enhancer(
-        _chat_payload_with_content('{"id":"preset_a","label":"Preset A","segment_prompts":["A","B"]}'))
+        _chat_payload_with_content(
+            '{"id":"preset_a","label":"Preset A","segment_prompts":["A","B"]}'
+        )
+    )
     next_path = tmp_path / "next.md"
     auto_path = tmp_path / "auto.md"
     rewrite_path = tmp_path / "rewrite.md"
@@ -955,7 +1052,9 @@ def test_save_prompt_config_updates_rewrite_user_prompt(tmp_path):
     enhancer.rewrite_all_system_prompt_fallback_path = None
     enhancer.rewrite_user_system_prompt_fallback_path = None
 
-    config = enhancer.save_prompt_config(rewrite_user_system_prompt="rewrite user updated", )
+    config = enhancer.save_prompt_config(
+        rewrite_user_system_prompt="rewrite user updated",
+    )
 
     assert rewrite_user_path.read_text(encoding="utf-8").strip() == "rewrite user updated"
     assert config["rewrite_user_system_prompt"] == "rewrite user updated"
@@ -963,7 +1062,10 @@ def test_save_prompt_config_updates_rewrite_user_prompt(tmp_path):
 
 def test_save_prompt_config_updates_rewrite_model(tmp_path):
     enhancer = _build_test_enhancer(
-        _chat_payload_with_content('{"id":"preset_a","label":"Preset A","segment_prompts":["A","B"]}'))
+        _chat_payload_with_content(
+            '{"id":"preset_a","label":"Preset A","segment_prompts":["A","B"]}'
+        )
+    )
     next_path = tmp_path / "next.md"
     auto_path = tmp_path / "auto.md"
     rewrite_path = tmp_path / "rewrite.md"
@@ -979,7 +1081,9 @@ def test_save_prompt_config_updates_rewrite_model(tmp_path):
     enhancer.rewrite_default_model = "gpt-test"
     enhancer.rewrite_model_options = ["gpt-test", "gpt-alt"]
 
-    config = enhancer.save_prompt_config(rewrite_model="gpt-alt", )
+    config = enhancer.save_prompt_config(
+        rewrite_model="gpt-alt",
+    )
 
     assert enhancer.rewrite_default_model == "gpt-alt"
     assert config["rewrite_model"] == "gpt-alt"
@@ -988,7 +1092,10 @@ def test_save_prompt_config_updates_rewrite_model(tmp_path):
 
 def test_save_prompt_config_updates_rewrite_temperature(tmp_path):
     enhancer = _build_test_enhancer(
-        _chat_payload_with_content('{"id":"preset_a","label":"Preset A","segment_prompts":["A","B"]}'))
+        _chat_payload_with_content(
+            '{"id":"preset_a","label":"Preset A","segment_prompts":["A","B"]}'
+        )
+    )
     next_path = tmp_path / "next.md"
     auto_path = tmp_path / "auto.md"
     rewrite_path = tmp_path / "rewrite.md"
@@ -1002,7 +1109,9 @@ def test_save_prompt_config_updates_rewrite_temperature(tmp_path):
     enhancer.auto_system_prompt_fallback_path = None
     enhancer.rewrite_all_system_prompt_fallback_path = None
 
-    config = enhancer.save_prompt_config(rewrite_temperature=1.3, )
+    config = enhancer.save_prompt_config(
+        rewrite_temperature=1.3,
+    )
 
     assert enhancer.rewrite_default_temperature == 1.3
     assert config["rewrite_temperature"] == 1.3
@@ -1010,7 +1119,10 @@ def test_save_prompt_config_updates_rewrite_temperature(tmp_path):
 
 def test_save_prompt_config_creates_versioned_backup_for_existing_prompt(tmp_path):
     enhancer = _build_test_enhancer(
-        _chat_payload_with_content('{"id":"preset_a","label":"Preset A","segment_prompts":["A","B"]}'))
+        _chat_payload_with_content(
+            '{"id":"preset_a","label":"Preset A","segment_prompts":["A","B"]}'
+        )
+    )
     next_path = tmp_path / "next.md"
     auto_path = tmp_path / "auto.md"
     rewrite_path = tmp_path / "rewrite_window_system_prompt.md"
@@ -1024,9 +1136,13 @@ def test_save_prompt_config_creates_versioned_backup_for_existing_prompt(tmp_pat
     enhancer.auto_system_prompt_fallback_path = None
     enhancer.rewrite_all_system_prompt_fallback_path = None
 
-    enhancer.save_prompt_config(rewrite_window_system_prompt="rewrite updated", )
+    enhancer.save_prompt_config(
+        rewrite_window_system_prompt="rewrite updated",
+    )
 
-    backup_paths = sorted(tmp_path.glob("rewrite_window_system_prompt.*.bak.md"))
+    backup_paths = sorted(
+        tmp_path.glob("rewrite_window_system_prompt.*.bak.md")
+    )
 
     assert rewrite_path.read_text(encoding="utf-8").strip() == "rewrite updated"
     assert len(backup_paths) == 1

apps/dreamverse/dreamverse/tests/test_realtime_stress.py

@@ -27,8 +27,13 @@ try:
 except ModuleNotFoundError:
     websockets = None  # type: ignore[assignment]
 
-DEFAULT_PRESET_FILE = (Path(__file__).resolve().parents[2] / "web" / "prompts" /
-                       "selected_ltx2_continuation_story_presets.json")
+
+DEFAULT_PRESET_FILE = (
+    Path(__file__).resolve().parents[2]
+    / "web"
+    / "prompts"
+    / "selected_ltx2_continuation_story_presets.json"
+)
 
 
 def utc_now_iso() -> str:
@@ -60,7 +65,10 @@ def safe_percentile(values: list[float], percentile: float) -> float | None:
     if lower == upper:
         return sorted_values[lower]
     fraction = rank - lower
-    return (sorted_values[lower] + (sorted_values[upper] - sorted_values[lower]) * fraction)
+    return (
+        sorted_values[lower]
+        + (sorted_values[upper] - sorted_values[lower]) * fraction
+    )
 
 
 def summarize_series(values: list[float]) -> dict[str, float | int | None]:
@@ -137,16 +145,24 @@ def load_curated_prompts(
     selected_id = str(selected.get("id", "")).strip() or "unknown_preset"
     raw_prompts = selected.get("segment_prompts", [])
     if not isinstance(raw_prompts, list):
-        raise ValueError(f"Preset {selected_id} has invalid segment_prompts (must be list).")
+        raise ValueError(
+            f"Preset {selected_id} has invalid segment_prompts (must be list)."
+        )
 
-    prompts = [str(prompt).strip() for prompt in raw_prompts if isinstance(prompt, str) and str(prompt).strip()]
+    prompts = [
+        str(prompt).strip()
+        for prompt in raw_prompts
+        if isinstance(prompt, str) and str(prompt).strip()
+    ]
     if not prompts:
         raise ValueError(f"Preset {selected_id} has no non-empty prompts.")
 
     limited = prompts[:curated_limit]
     if not limited:
-        raise ValueError(f"curated_limit={curated_limit} produced no prompts for preset "
-                         f"{selected_id}.")
+        raise ValueError(
+            f"curated_limit={curated_limit} produced no prompts for preset "
+            f"{selected_id}."
+        )
     return selected_id, limited, len(prompts)
 
 
@@ -208,11 +224,11 @@ async def run_single_session(
 
     try:
         async with websockets.connect(
-                url,
-                max_size=None,
-                ping_interval=None,
-                open_timeout=connect_timeout_s,
-                close_timeout=2.0,
+            url,
+            max_size=None,
+            ping_interval=None,
+            open_timeout=connect_timeout_s,
+            close_timeout=2.0,
         ) as ws:
             connect_finish_monotonic = time.monotonic()
             session_data["connect_finish_ts_utc"] = utc_now_iso()
@@ -233,7 +249,9 @@ async def run_single_session(
                 timeout_remaining = session_timeout_s - elapsed_s
                 if timeout_remaining <= 0:
                     session_data["status"] = "timeout"
-                    session_data["error"] = (f"Session timed out after {session_timeout_s:.1f}s.")
+                    session_data["error"] = (
+                        f"Session timed out after {session_timeout_s:.1f}s."
+                    )
                     break
 
                 recv_start_epoch = time.time()
@@ -247,7 +265,9 @@ async def run_single_session(
                     )
                 except asyncio.TimeoutError:
                     session_data["status"] = "timeout"
-                    session_data["error"] = ("Timed out waiting for websocket message.")
+                    session_data["error"] = (
+                        "Timed out waiting for websocket message."
+                    )
                     break
                 except Exception as exc:
                     session_data["status"] = "failed"
@@ -268,16 +288,20 @@ async def run_single_session(
 
                     chunk_gap_ms: float | None = None
                     if last_chunk_finish_monotonic is not None:
-                        chunk_gap_ms = (recv_finish_monotonic - last_chunk_finish_monotonic) * 1000.0
+                        chunk_gap_ms = (
+                            recv_finish_monotonic - last_chunk_finish_monotonic
+                        ) * 1000.0
 
-                    session_data["chunks"].append({
-                        "segment_idx": current_segment_idx,
-                        "chunk_idx": session_data["total_chunks"],
-                        "size_bytes": len(message),
-                        "chunk_start_ts_utc": recv_start_iso,
-                        "chunk_finish_ts_utc": recv_finish_iso,
-                        "chunk_gap_ms": chunk_gap_ms,
-                    })
+                    session_data["chunks"].append(
+                        {
+                            "segment_idx": current_segment_idx,
+                            "chunk_idx": session_data["total_chunks"],
+                            "size_bytes": len(message),
+                            "chunk_start_ts_utc": recv_start_iso,
+                            "chunk_finish_ts_utc": recv_finish_iso,
+                            "chunk_gap_ms": chunk_gap_ms,
+                        }
+                    )
                     last_chunk_finish_monotonic = recv_finish_monotonic
                     last_chunk_finish_epoch = recv_finish_epoch
                     session_data["last_chunk_finish_ts_utc"] = recv_finish_iso
@@ -297,7 +321,9 @@ async def run_single_session(
                 if msg_type == "gpu_assigned":
                     session_data["gpu_assigned_ts_utc"] = recv_finish_iso
                     if connect_finish_monotonic is not None:
-                        session_data["queue_wait_ms"] = (recv_finish_monotonic - connect_finish_monotonic) * 1000.0
+                        session_data["queue_wait_ms"] = (
+                            recv_finish_monotonic - connect_finish_monotonic
+                        ) * 1000.0
                 elif msg_type == "ltx2_stream_start":
                     if initial_total_segments is None:
                         parsed_total = parse_int(data.get("total_segments"))
@@ -312,13 +338,20 @@ async def run_single_session(
                     session_data["media_segments_completed"] += 1
                     if first_media_segment_complete_epoch is None:
                         first_media_segment_complete_epoch = recv_finish_epoch
-                        session_data["first_media_segment_complete_ts_utc"] = recv_finish_iso
+                        session_data[
+                            "first_media_segment_complete_ts_utc"
+                        ] = recv_finish_iso
                 elif msg_type == "ltx2_segment_complete":
                     session_data["segments_completed"] += 1
                     seg_idx = parse_int(data.get("segment_idx"))
-                    if (initial_total_segments is not None and seg_idx is not None
-                            and seg_idx >= initial_total_segments):
-                        session_data["target_segment_complete_ts_utc"] = recv_finish_iso
+                    if (
+                        initial_total_segments is not None
+                        and seg_idx is not None
+                        and seg_idx >= initial_total_segments
+                    ):
+                        session_data[
+                            "target_segment_complete_ts_utc"
+                        ] = recv_finish_iso
                         await asyncio.sleep(post_complete_wait_s)
                         session_data["leave_sent_ts_utc"] = utc_now_iso()
                         try:
@@ -329,11 +362,15 @@ async def run_single_session(
                         break
                 elif msg_type == "session_timeout":
                     session_data["status"] = "timeout"
-                    session_data["error"] = str(data.get("message") or "Backend session timeout")
+                    session_data["error"] = str(
+                        data.get("message") or "Backend session timeout"
+                    )
                     break
                 elif msg_type == "error":
                     session_data["status"] = "failed"
-                    session_data["error"] = str(data.get("message") or "Backend error message")
+                    session_data["error"] = str(
+                        data.get("message") or "Backend error message"
+                    )
                     break
 
             if session_data["status"] == "failed" and session_data["error"] is None:
@@ -342,18 +379,29 @@ async def run_single_session(
         session_data["status"] = "failed"
         session_data["error"] = f"WebSocket connect/run failed: {exc}"
 
-    if (first_chunk_finish_epoch is not None and last_chunk_finish_epoch is not None
-            and session_data["total_chunk_bytes"] > 0):
+    if (
+        first_chunk_finish_epoch is not None
+        and last_chunk_finish_epoch is not None
+        and session_data["total_chunk_bytes"] > 0
+    ):
         duration_s = last_chunk_finish_epoch - first_chunk_finish_epoch
         if duration_s > 0:
-            session_data["session_goodput_mbps"] = (session_data["total_chunk_bytes"] * 8.0 / duration_s / 1_000_000.0)
+            session_data["session_goodput_mbps"] = (
+                session_data["total_chunk_bytes"] * 8.0 / duration_s / 1_000_000.0
+            )
 
-    if (first_chunk_finish_epoch is not None and first_media_segment_complete_epoch is not None):
-        session_data["first_chunk_before_first_media_complete"] = (first_chunk_finish_epoch
-                                                                   < first_media_segment_complete_epoch)
+    if (
+        first_chunk_finish_epoch is not None
+        and first_media_segment_complete_epoch is not None
+    ):
+        session_data["first_chunk_before_first_media_complete"] = (
+            first_chunk_finish_epoch < first_media_segment_complete_epoch
+        )
 
     session_data["close_ts_utc"] = utc_now_iso()
-    session_data["duration_ms"] = (time.monotonic() - session_start_monotonic) * 1000.0
+    session_data["duration_ms"] = (
+        time.monotonic() - session_start_monotonic
+    ) * 1000.0
     return session_data
 
 
@@ -364,11 +412,14 @@ async def run_worker_sessions(
     config: dict[str, Any],
 ) -> list[dict[str, Any]]:
     tasks = [
-        asyncio.create_task(run_single_session(
-            worker_id=worker_id,
-            worker_session_idx=idx,
-            config=config,
-        )) for idx in range(session_count)
+        asyncio.create_task(
+            run_single_session(
+                worker_id=worker_id,
+                worker_session_idx=idx,
+                config=config,
+            )
+        )
+        for idx in range(session_count)
     ]
     if not tasks:
         return []
@@ -386,23 +437,29 @@ def worker_entry(
     try:
         ready_queue.put({"worker_id": worker_id, "status": "ready"})
         start_event.wait()
-        sessions = asyncio.run(run_worker_sessions(
-            worker_id=worker_id,
-            session_count=session_count,
-            config=config,
-        ))
-        result_queue.put({
-            "worker_id": worker_id,
-            "status": "ok",
-            "sessions": sessions,
-        })
+        sessions = asyncio.run(
+            run_worker_sessions(
+                worker_id=worker_id,
+                session_count=session_count,
+                config=config,
+            )
+        )
+        result_queue.put(
+            {
+                "worker_id": worker_id,
+                "status": "ok",
+                "sessions": sessions,
+            }
+        )
     except Exception as exc:
-        result_queue.put({
-            "worker_id": worker_id,
-            "status": "error",
-            "error": str(exc),
-            "traceback": traceback.format_exc(),
-        })
+        result_queue.put(
+            {
+                "worker_id": worker_id,
+                "status": "error",
+                "error": str(exc),
+                "traceback": traceback.format_exc(),
+            }
+        )
 
 
 def build_summary(
@@ -460,22 +517,33 @@ def build_summary(
     if len(all_chunk_finish_epochs) >= 2 and total_chunk_bytes > 0:
         duration_s = max(all_chunk_finish_epochs) - min(all_chunk_finish_epochs)
         if duration_s > 0:
-            global_goodput_mbps = (total_chunk_bytes * 8.0 / duration_s / 1_000_000.0)
+            global_goodput_mbps = (
+                total_chunk_bytes * 8.0 / duration_s / 1_000_000.0
+            )
 
-    bucket_throughputs_mbps = [(bytes_count * 8.0) / 1_000_000.0 for _, bytes_count in sorted(bucket_bytes.items())]
+    bucket_throughputs_mbps = [
+        (bytes_count * 8.0) / 1_000_000.0
+        for _, bytes_count in sorted(bucket_bytes.items())
+    ]
     bucket_stats = summarize_series(bucket_throughputs_mbps)
 
-    chunk_gap_threshold_breaches = [value for value in chunk_gaps if value >= chunk_gap_threshold_ms]
+    chunk_gap_threshold_breaches = [
+        value for value in chunk_gaps if value >= chunk_gap_threshold_ms
+    ]
     non_success = len(sessions) - status_counts.get("success", 0)
 
     fail_reasons: list[str] = []
     if non_success > 0:
-        fail_reasons.append(f"{non_success} session(s) did not complete successfully.")
+        fail_reasons.append(
+            f"{non_success} session(s) did not complete successfully."
+        )
     if not chunk_gaps:
         fail_reasons.append("No chunk gap data collected.")
     if chunk_gap_threshold_breaches:
-        fail_reasons.append(f"{len(chunk_gap_threshold_breaches)} chunk gap(s) were >= "
-                            f"{chunk_gap_threshold_ms:.0f}ms.")
+        fail_reasons.append(
+            f"{len(chunk_gap_threshold_breaches)} chunk gap(s) were >= "
+            f"{chunk_gap_threshold_ms:.0f}ms."
+        )
 
     passed = len(fail_reasons) == 0
     progressive_ratio = None
@@ -486,18 +554,20 @@ def build_summary(
         "passed": passed,
         "fail_reasons": fail_reasons,
         "sessions": {
-            "total":
-            len(sessions),
-            "success":
-            status_counts.get("success", 0),
-            "failed":
-            status_counts.get("failed", 0),
-            "timeout":
-            status_counts.get("timeout", 0),
-            "protocol_error":
-            status_counts.get("protocol_error", 0),
-            "other": (len(sessions) - (status_counts.get("success", 0) + status_counts.get("failed", 0) +
-                                       status_counts.get("timeout", 0) + status_counts.get("protocol_error", 0))),
+            "total": len(sessions),
+            "success": status_counts.get("success", 0),
+            "failed": status_counts.get("failed", 0),
+            "timeout": status_counts.get("timeout", 0),
+            "protocol_error": status_counts.get("protocol_error", 0),
+            "other": (
+                len(sessions)
+                - (
+                    status_counts.get("success", 0)
+                    + status_counts.get("failed", 0)
+                    + status_counts.get("timeout", 0)
+                    + status_counts.get("protocol_error", 0)
+                )
+            ),
         },
         "chunk_gap_ms": {
             **chunk_gap_stats,
@@ -536,39 +606,51 @@ def print_summary(
     bucket_bw = bandwidth["bucketed_1s"]
 
     print("=== LTX2 Realtime Stress Test Summary ===")
-    print("Run: "
-          f"url={run_info['url']} clients={run_info['clients']} "
-          f"processes={run_info['processes']} "
-          f"preset={run_info['preset_id']} "
-          f"curated_limit={run_info['curated_limit']}")
-    print("Sessions: "
-          f"total={sessions['total']} success={sessions['success']} "
-          f"failed={sessions['failed']} timeout={sessions['timeout']} "
-          f"protocol_error={sessions['protocol_error']}")
-    print("Chunk gap ms: "
-          f"min={format_num(chunk_gap['min'])} "
-          f"p50={format_num(chunk_gap['p50'])} "
-          f"p95={format_num(chunk_gap['p95'])} "
-          f"p99={format_num(chunk_gap['p99'])} "
-          f"max={format_num(chunk_gap['max'])} "
-          f"threshold={format_num(chunk_gap['threshold_ms'])} "
-          f"breaches={chunk_gap['breach_count']}")
-    print("Queue wait ms: "
-          f"min={format_num(queue_wait['min'])} "
-          f"p50={format_num(queue_wait['p50'])} "
-          f"p95={format_num(queue_wait['p95'])} "
-          f"max={format_num(queue_wait['max'])}")
+    print(
+        "Run: "
+        f"url={run_info['url']} clients={run_info['clients']} "
+        f"processes={run_info['processes']} "
+        f"preset={run_info['preset_id']} "
+        f"curated_limit={run_info['curated_limit']}"
+    )
+    print(
+        "Sessions: "
+        f"total={sessions['total']} success={sessions['success']} "
+        f"failed={sessions['failed']} timeout={sessions['timeout']} "
+        f"protocol_error={sessions['protocol_error']}"
+    )
+    print(
+        "Chunk gap ms: "
+        f"min={format_num(chunk_gap['min'])} "
+        f"p50={format_num(chunk_gap['p50'])} "
+        f"p95={format_num(chunk_gap['p95'])} "
+        f"p99={format_num(chunk_gap['p99'])} "
+        f"max={format_num(chunk_gap['max'])} "
+        f"threshold={format_num(chunk_gap['threshold_ms'])} "
+        f"breaches={chunk_gap['breach_count']}"
+    )
+    print(
+        "Queue wait ms: "
+        f"min={format_num(queue_wait['min'])} "
+        f"p50={format_num(queue_wait['p50'])} "
+        f"p95={format_num(queue_wait['p95'])} "
+        f"max={format_num(queue_wait['max'])}"
+    )
     ratio = progressive["ratio"]
     ratio_text = "n/a" if ratio is None else f"{ratio * 100:.2f}%"
-    print("Progressive streaming: "
-          f"{progressive['success_sessions']}/"
-          f"{progressive['eligible_sessions']} ({ratio_text})")
-    print("Bandwidth Mbps: "
-          f"per_session_avg={format_num(per_session_bw['avg'])} "
-          f"per_session_p95={format_num(per_session_bw['p95'])} "
-          f"global={format_num(bandwidth['global_goodput_mbps'])} "
-          f"bucket_avg={format_num(bucket_bw['avg_mbps'])} "
-          f"bucket_peak={format_num(bucket_bw['peak_mbps'])}")
+    print(
+        "Progressive streaming: "
+        f"{progressive['success_sessions']}/"
+        f"{progressive['eligible_sessions']} ({ratio_text})"
+    )
+    print(
+        "Bandwidth Mbps: "
+        f"per_session_avg={format_num(per_session_bw['avg'])} "
+        f"per_session_p95={format_num(per_session_bw['p95'])} "
+        f"global={format_num(bandwidth['global_goodput_mbps'])} "
+        f"bucket_avg={format_num(bucket_bw['avg_mbps'])} "
+        f"bucket_peak={format_num(bucket_bw['peak_mbps'])}"
+    )
     print(f"VERDICT: {'PASS' if summary['passed'] else 'FAIL'}")
     if summary["fail_reasons"]:
         print("Fail reasons:")
@@ -588,8 +670,10 @@ def distribute_sessions(total_clients: int, process_count: int) -> list[int]:
 
 def run_stress(args: argparse.Namespace) -> tuple[dict[str, Any], int]:
     if websockets is None:
-        raise RuntimeError("Missing dependency: websockets. Install it before running this "
-                           "stress test.")
+        raise RuntimeError(
+            "Missing dependency: websockets. Install it before running this "
+            "stress test."
+        )
 
     preset_file = Path(args.preset_file).expanduser().resolve()
     selected_preset_id, curated_prompts, total_prompt_count = load_curated_prompts(
@@ -651,8 +735,13 @@ def run_stress(args: argparse.Namespace) -> tuple[dict[str, Any], int]:
 
         start_event.set()
 
-        result_deadline = (time.monotonic() + args.connect_timeout_s + args.session_timeout_s +
-                           args.post_complete_wait_s + 180.0)
+        result_deadline = (
+            time.monotonic()
+            + args.connect_timeout_s
+            + args.session_timeout_s
+            + args.post_complete_wait_s
+            + 180.0
+        )
         worker_results: list[dict[str, Any]] = []
         while len(worker_results) < len(processes):
             timeout_s = max(0.1, result_deadline - time.monotonic())
@@ -676,20 +765,24 @@ def run_stress(args: argparse.Namespace) -> tuple[dict[str, Any], int]:
             if result.get("status") == "ok":
                 sessions.extend(result.get("sessions", []))
             else:
-                worker_errors.append({
-                    "worker_id": result.get("worker_id"),
-                    "error": result.get("error"),
-                    "traceback": result.get("traceback"),
-                })
+                worker_errors.append(
+                    {
+                        "worker_id": result.get("worker_id"),
+                        "error": result.get("error"),
+                        "traceback": result.get("traceback"),
+                    }
+                )
 
         received_workers = {result.get("worker_id") for result in worker_results}
         expected_workers = set(range(len(processes)))
         missing_workers = sorted(expected_workers - received_workers)
         for worker_id in missing_workers:
-            worker_errors.append({
-                "worker_id": worker_id,
-                "error": "No worker result received.",
-            })
+            worker_errors.append(
+                {
+                    "worker_id": worker_id,
+                    "error": "No worker result received.",
+                }
+            )
 
         run_end_epoch = time.time()
         run_end_iso = iso_from_epoch(run_end_epoch)
@@ -702,8 +795,9 @@ def run_stress(args: argparse.Namespace) -> tuple[dict[str, Any], int]:
 
         if worker_errors:
             summary["passed"] = False
-            summary["fail_reasons"] = list(
-                summary["fail_reasons"]) + [f"{len(worker_errors)} worker error(s) occurred."]
+            summary["fail_reasons"] = list(summary["fail_reasons"]) + [
+                f"{len(worker_errors)} worker error(s) occurred."
+            ]
 
         output_payload = {
             "run_info": {
@@ -739,7 +833,9 @@ def run_stress(args: argparse.Namespace) -> tuple[dict[str, Any], int]:
 
 
 def parse_args() -> argparse.Namespace:
-    parser = argparse.ArgumentParser(description="Multiprocess realtime stress test for LTX2 streaming.", )
+    parser = argparse.ArgumentParser(
+        description="Multiprocess realtime stress test for LTX2 streaming.",
+    )
     parser.add_argument(
         "-u",
         "--url",

apps/dreamverse/dreamverse/tests/test_session_init_image.py

@@ -47,11 +47,13 @@ def test_persist_session_init_image_returns_none_when_missing_data():
 
 def test_persist_session_init_image_rejects_unsupported_mime():
     with pytest.raises(ValueError, match="PNG, JPEG, or WebP"):
-        persist_session_init_image({
-            "name": "frame.gif",
-            "mime_type": "image/gif",
-            "data_url": "data:image/gif;base64,R0lGODlhAQABAAAAACw=",
-        })
+        persist_session_init_image(
+            {
+                "name": "frame.gif",
+                "mime_type": "image/gif",
+                "data_url": "data:image/gif;base64,R0lGODlhAQABAAAAACw=",
+            }
+        )
 
 
 def test_persist_session_init_image_rejects_large_payload(monkeypatch):
@@ -64,8 +66,10 @@ def test_persist_session_init_image_rejects_large_payload(monkeypatch):
     monkeypatch.setattr(base64, "b64decode", fake_b64decode)
 
     with pytest.raises(ValueError, match="15 MB or smaller"):
-        persist_session_init_image({
-            "name": "frame.png",
-            "mime_type": "image/png",
-            "data_url": data_url,
-        })
+        persist_session_init_image(
+            {
+                "name": "frame.png",
+                "mime_type": "image/png",
+                "data_url": data_url,
+            }
+        )

apps/dreamverse/scripts/modal/modal_app.py

@@ -8,10 +8,12 @@ import modal
 
 IMAGE = os.environ.get("DREAMVERSE_IMAGE")
 if not IMAGE:
-    raise RuntimeError("DREAMVERSE_IMAGE is required. Set it to a published SHA-specific Dreamverse image, "
-                       "for example a dreamverse-backend-cuda13.0.0-sha-* tag or a "
-                       "dreamverse-ui-cuda13.0.0-sha-* tag if serving the static UI. "
-                       "CUDA 12 / cu126 images use the corresponding cuda12.6.3 tag.")
+    raise RuntimeError(
+        "DREAMVERSE_IMAGE is required. Set it to a published SHA-specific Dreamverse image, "
+        "for example a dreamverse-backend-cuda13.0.0-sha-* tag or a "
+        "dreamverse-ui-cuda13.0.0-sha-* tag if serving the static UI. "
+        "CUDA 12 / cu126 images use the corresponding cuda12.6.3 tag."
+    )
 
 # ``@modal.web_server`` invokes ``serve()`` directly and bypasses the image
 # ENTRYPOINT (``docker/docker_entrypoint.sh``).  That entrypoint normally
@@ -63,10 +65,14 @@ def serve():
     # ``or ""`` collapses ``None`` (unset) into an empty string, ``.strip()``
     # collapses whitespace-only values (e.g. ``"   "``) — both should be
     # treated as missing.
-    missing = [k for k in _REQUIRED_SECRET_KEYS if not (os.environ.get(k) or "").strip()]
+    missing = [
+        k for k in _REQUIRED_SECRET_KEYS
+        if not (os.environ.get(k) or "").strip()
+    ]
     if missing:
-        raise RuntimeError("dreamverse-api-keys secret is missing required entries: "
-                           f"{', '.join(missing)}. Add them with `modal secret create "
-                           "dreamverse-api-keys ... --force` and redeploy "
-                           "(see apps/dreamverse/scripts/modal/README.md).")
+        raise RuntimeError(
+            "dreamverse-api-keys secret is missing required entries: "
+            f"{', '.join(missing)}. Add them with `modal secret create "
+            "dreamverse-api-keys ... --force` and redeploy "
+            "(see apps/dreamverse/scripts/modal/README.md).")
     subprocess.Popen(["dreamverse-server", "--host", "0.0.0.0", "--port", "8009"])

apps/fastvideo_studio/tests/test_gpu.py

@@ -74,8 +74,10 @@ def test_snapshot_shapes_devices(monkeypatch: pytest.MonkeyPatch) -> None:
     }
 
 
-def test_snapshot_tolerates_missing_sensors(monkeypatch: pytest.MonkeyPatch) -> None:
-    monkeypatch.setitem(sys.modules, "pynvml", _make_fake_pynvml(broken_sensors=True))
+def test_snapshot_tolerates_missing_sensors(
+        monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setitem(sys.modules, "pynvml",
+                        _make_fake_pynvml(broken_sensors=True))
     snap = gpu_mod.get_gpu_snapshot()
     assert snap["available"] is True
     g = snap["gpus"][0]
@@ -84,7 +86,8 @@ def test_snapshot_tolerates_missing_sensors(monkeypatch: pytest.MonkeyPatch) ->
     assert g["power_limit_watts"] is None
 
 
-def test_snapshot_reports_nvml_failure(monkeypatch: pytest.MonkeyPatch) -> None:
+def test_snapshot_reports_nvml_failure(
+        monkeypatch: pytest.MonkeyPatch) -> None:
     fake = _make_fake_pynvml()
     fake.nvmlInit = lambda: (_ for _ in ()).throw(_NVMLError("driver gone"))
     monkeypatch.setitem(sys.modules, "pynvml", fake)

apps/fastvideo_studio/tests/test_training_config.py

@@ -130,7 +130,8 @@ def test_dmd_builds_three_role_models_and_method_knobs() -> None:
 
 
 def test_dmd_vsa_maps_to_training_vsa_sparsity() -> None:
-    config = build_training_config(_job("dmd_t2v", dmd_use_vsa=True, dmd_vsa_sparsity=0.9), "out")
+    config = build_training_config(
+        _job("dmd_t2v", dmd_use_vsa=True, dmd_vsa_sparsity=0.9), "out")
     assert config["training"]["vsa"]["sparsity"] == 0.9
 
 
@@ -160,27 +161,31 @@ def test_validation_callback_only_when_file_given() -> None:
     without = build_training_config(_job("full_t2v"), "out")
     assert "validation" not in without["callbacks"]
 
-    with_file = build_training_config(_job("full_t2v", validation_dataset_file="val.json"), "out")
+    with_file = build_training_config(
+        _job("full_t2v", validation_dataset_file="val.json"), "out")
     validation = with_file["callbacks"]["validation"]
     assert validation["dataset_file"] == "val.json"
     assert validation["pipeline_target"].endswith(".WanPipeline")
     assert validation["sampling_steps"] == [50]
 
-    dmd = build_training_config(_job("dmd_t2v", validation_dataset_file="val.json"), "out")
+    dmd = build_training_config(
+        _job("dmd_t2v", validation_dataset_file="val.json"), "out")
     validation = dmd["callbacks"]["validation"]
     assert validation["pipeline_target"].endswith(".WanDMDPipeline")
     assert validation["sampling_steps"] == [3]
     assert validation["sampling_timesteps"] == [1000, 757, 522]
 
     # KD/ODE-init has no sampling-based validation pipeline.
-    ode = build_training_config(_job("ode_init", validation_dataset_file="val.json"), "out")
+    ode = build_training_config(
+        _job("ode_init", validation_dataset_file="val.json"), "out")
     assert "validation" not in ode["callbacks"]
 
 
 def test_ltx2_models_are_rejected() -> None:
     assert is_ltx2_model("Lightricks/LTX-2-19B")
     with pytest.raises(ValueError, match="LTX-2 training is not supported"):
-        build_training_config(_job("full_t2v", model_id="Lightricks/LTX-2-19B"), "out")
+        build_training_config(
+            _job("full_t2v", model_id="Lightricks/LTX-2-19B"), "out")
 
 
 def test_unknown_workload_is_rejected() -> None:
@@ -190,7 +195,8 @@ def test_unknown_workload_is_rejected() -> None:
 
 def test_invalid_denoising_steps_are_rejected() -> None:
     with pytest.raises(ValueError, match="Invalid DMD denoising steps"):
-        build_training_config(_job("dmd_t2v", dmd_denoising_steps="1000,abc"), "out")
+        build_training_config(
+            _job("dmd_t2v", dmd_denoising_steps="1000,abc"), "out")
 
 
 def test_training_env_has_no_backend_override() -> None:
@@ -205,7 +211,8 @@ def test_workloads_match_frontend_job_config() -> None:
     (src/lib/jobConfig.ts) — drift means creatable-but-unrunnable jobs."""
     import re
 
-    job_config = (Path(__file__).resolve().parents[1] / "src" / "lib" / "jobConfig.ts").read_text(encoding="utf-8")
+    job_config = (Path(__file__).resolve().parents[1] / "src" / "lib" /
+                  "jobConfig.ts").read_text(encoding="utf-8")
     all_types = set(re.findall(r'type:\s*"([^"]+)"', job_config))
     inference_types = {"t2v", "i2v", "t2i"}
     assert inference_types <= all_types, "jobConfig.ts parse failed"

docs/assets/cookbook-recipes.json

@@ -0,0 +1,52 @@
+{
+  "recipes": [
+    {
+      "id": "fastwan21-t2v",
+      "task": "Text to video",
+      "label": "FastWan2.1 1.3B (distilled + VSA)",
+      "model": "FastVideo/FastWan2.1-T2V-1.3B-Diffusers",
+      "source": "scripts/inference/inference_wan_VSA_DMD_1_3B.yaml",
+      "command": "FASTVIDEO_ATTENTION_BACKEND=VIDEO_SPARSE_ATTN fastvideo generate --config scripts/inference/inference_wan_VSA_DMD_1_3B.yaml"
+    },
+    {
+      "id": "wan22-t2v",
+      "task": "Text to video",
+      "label": "Wan2.2 A14B",
+      "model": "Wan-AI/Wan2.2-T2V-A14B-Diffusers",
+      "source": "examples/inference/basic/basic_wan2_2.py",
+      "command": "python examples/inference/basic/basic_wan2_2.py"
+    },
+    {
+      "id": "wan21-i2v",
+      "task": "Image to video",
+      "label": "Wan2.1 14B 480P",
+      "model": "Wan-AI/Wan2.1-I2V-14B-480P-Diffusers",
+      "source": "scripts/inference/inference_wan_i2v.yaml",
+      "command": "fastvideo generate --config scripts/inference/inference_wan_i2v.yaml"
+    },
+    {
+      "id": "turbowan22-i2v",
+      "task": "Image to video",
+      "label": "TurboWan2.2 A14B",
+      "model": "loayrashid/TurboWan2.2-I2V-A14B-Diffusers",
+      "source": "examples/inference/basic/basic_turbodiffusion_i2v.py",
+      "command": "python examples/inference/basic/basic_turbodiffusion_i2v.py"
+    },
+    {
+      "id": "wan22-ti2v",
+      "task": "Text or image to video",
+      "label": "Wan2.2 TI2V 5B",
+      "model": "Wan-AI/Wan2.2-TI2V-5B-Diffusers",
+      "source": "examples/inference/basic/basic_wan2_2_ti2v.py",
+      "command": "python examples/inference/basic/basic_wan2_2_ti2v.py"
+    },
+    {
+      "id": "matrix-game-2",
+      "task": "Interactive world",
+      "label": "Matrix Game 2.0",
+      "model": "FastVideo/Matrix-Game-2.0-Base-Distilled-Diffusers",
+      "source": "examples/inference/basic/basic_matrixgame2.py",
+      "command": "python examples/inference/basic/basic_matrixgame2.py"
+    }
+  ]
+}

docs/assets/cookbook.js

@@ -0,0 +1,60 @@
+(() => {
+  let recipesPromise;
+
+  const loadRecipes = (url) => {
+    recipesPromise ||= fetch(url).then((response) => {
+      if (!response.ok) throw new Error(`HTTP ${response.status}`);
+      return response.json();
+    });
+    return recipesPromise;
+  };
+
+  const init = () => {
+    document.querySelectorAll("[data-cookbook]").forEach(async (root) => {
+      if (root.dataset.initialized) return;
+      root.dataset.initialized = "true";
+
+      const select = root.querySelector("[data-cookbook-recipe]");
+      const model = root.querySelector("[data-cookbook-model]");
+      const source = root.querySelector("[data-cookbook-source]");
+      const command = root.querySelector("[data-cookbook-command]");
+      const status = root.querySelector("[data-cookbook-status]");
+
+      try {
+        const { recipes } = await loadRecipes(root.dataset.recipes);
+        const byId = new Map(recipes.map((recipe) => [recipe.id, recipe]));
+        const groups = new Map();
+
+        select.replaceChildren();
+        recipes.forEach((recipe) => {
+          if (!groups.has(recipe.task)) {
+            const group = document.createElement("optgroup");
+            group.label = recipe.task;
+            groups.set(recipe.task, group);
+            select.append(group);
+          }
+          groups.get(recipe.task).append(new Option(recipe.label, recipe.id));
+        });
+
+        const render = () => {
+          const recipe = byId.get(select.value);
+          model.textContent = recipe.model;
+          source.textContent = recipe.source;
+          source.href = `https://github.com/hao-ai-lab/FastVideo/blob/main/${recipe.source}`;
+          command.textContent = recipe.command;
+          status.textContent = `${recipe.label} selected.`;
+        };
+
+        select.addEventListener("change", render);
+        select.disabled = false;
+        render();
+      } catch (error) {
+        status.textContent = "Recipes could not be loaded. Use the examples link below.";
+        console.error("Failed to load FastVideo cookbook recipes", error);
+      }
+    });
+  };
+
+  if (window.document$) window.document$.subscribe(init);
+  else document.addEventListener("DOMContentLoaded", init);
+})();

docs/assets/custom.css

@@ -42,6 +42,46 @@ img {
     margin: 0 auto;
 }
 
+.cookbook-picker {
+    padding: 1rem;
+    border: 0.05rem solid var(--md-default-fg-color--lightest);
+    border-radius: 0.2rem;
+}
+
+.cookbook-picker select {
+    width: 100%;
+    padding: 0.6rem;
+    color: var(--md-default-fg-color);
+    background: var(--md-default-bg-color);
+    border: 0.05rem solid var(--md-default-fg-color--lighter);
+    border-radius: 0.2rem;
+}
+
+.cookbook-picker dl {
+    display: grid;
+    grid-template-columns: max-content 1fr;
+    gap: 0.25rem 1rem;
+}
+
+.cookbook-picker dt {
+    font-weight: 700;
+}
+
+.cookbook-picker dd {
+    margin: 0;
+    min-width: 0;
+    overflow-wrap: anywhere;
+}
+
+.cookbook-picker__status {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+}
+
 .md-typeset .copy-page-button.md-button {
     float: right;
     margin: 0 0 1rem 1rem;

docs/cookbook/index.md

@@ -0,0 +1,44 @@
+# Inference Cookbook
+
+Choose a complete recipe maintained in the FastVideo repository. Each command
+runs its checked-in source directly, so coupled model, GPU, offload, and
+attention settings do not drift into unsupported combinations.
+
+The commands expect a local clone:
+
+```bash
+git clone https://github.com/hao-ai-lab/FastVideo.git
+cd FastVideo
+```
+
+<div class="cookbook-picker" data-cookbook data-recipes="../assets/cookbook-recipes.json">
+  <label for="cookbook-recipe"><strong>Recipe</strong></label>
+  <select id="cookbook-recipe" data-cookbook-recipe disabled>
+    <option>Loading recipes…</option>
+  </select>
+  <dl>
+    <dt>Model</dt>
+    <dd data-cookbook-model>Loading…</dd>
+    <dt>Source</dt>
+    <dd><a data-cookbook-source href="../inference/examples/basic/">Browse maintained examples</a></dd>
+  </dl>
+  <pre><code class="language-bash" data-cookbook-command>Loading…</code></pre>
+  <p class="cookbook-picker__status" role="status" aria-live="polite" data-cookbook-status></p>
+  <noscript>
+    JavaScript is needed for the recipe picker. Browse the
+    <a href="../inference/examples/examples_inference_index/">inference examples</a>
+    instead.
+  </noscript>
+</div>
+
+## Customize a recipe
+
+Start from the checked-in source, then change only the settings your model
+supports:
+
+- [Configuration](../inference/configuration.md) covers the Python and CLI
+  config surfaces.
+- [Optimizations](../inference/optimizations.md) covers attention backends,
+  compilation, and memory tradeoffs.
+- [Support matrix](../inference/support_matrix.md) lists supported models and
+  optimizations.

docs/generate_examples.py

@@ -2,6 +2,7 @@
 # adapted from vllm: https://github.com/vllm-project/vllm/blob/v0.7.3/docs/source/generate_examples.py
 
 import itertools
+import json
 import os
 import re
 from dataclasses import dataclass, field
@@ -19,6 +20,40 @@ GENERATED_DOC_PREFIXES = (
     "training/examples/",
     "distillation/examples/",
 )
+COOKBOOK_DATA = ROOT_DIR / "docs/assets/cookbook-recipes.json"
+COOKBOOK_SOURCE_ROOTS = (
+    ROOT_DIR / "examples/inference",
+    ROOT_DIR / "scripts/inference",
+)
+
+
+def validate_cookbook() -> None:
+    """Keep cookbook entries tied to checked-in runnable sources."""
+    recipes = json.loads(COOKBOOK_DATA.read_text(encoding="utf-8")).get("recipes")
+    if not isinstance(recipes, list) or not recipes:
+        raise ValueError(f"{COOKBOOK_DATA}: recipes must be a non-empty list")
+
+    seen: set[str] = set()
+    for recipe in recipes:
+        required = ("id", "task", "label", "model", "source", "command")
+        missing = {key for key in required if not recipe.get(key)}
+        if missing:
+            raise ValueError(f"Cookbook recipe is missing: {', '.join(sorted(missing))}")
+        if recipe["id"] in seen:
+            raise ValueError(f"Duplicate cookbook recipe id: {recipe['id']}")
+        seen.add(recipe["id"])
+
+        source = (ROOT_DIR / recipe["source"]).resolve()
+        if not any(source.is_relative_to(root.resolve()) for root in COOKBOOK_SOURCE_ROOTS):
+            raise ValueError(f"Cookbook source is outside an approved directory: {recipe['source']}")
+        if not source.is_file():
+            raise ValueError(f"Cookbook source does not exist: {recipe['source']}")
+
+        source_text = source.read_text(encoding="utf-8")
+        if recipe["model"] not in source_text:
+            raise ValueError(f"Cookbook model is not present in {recipe['source']}: {recipe['model']}")
+        if recipe["source"] not in recipe["command"]:
+            raise ValueError(f"Cookbook command does not invoke its source: {recipe['id']}")
 
 
 def fix_case(text: str) -> str:
@@ -536,6 +571,7 @@ def on_pre_build(config, **kwargs):
     MkDocs hook to generate examples before building the documentation.
     This function is called automatically by MkDocs' native hook system.
     """
+    validate_cookbook()
     print("Generating example documentation...")
     generate_examples(generate_main_index=True)
     print("Example documentation generated successfully!")
@@ -549,6 +585,7 @@ def on_page_context(context, page, **kwargs):
 
 
 if __name__ == "__main__":
+    validate_cookbook()
     print("Generating example documentation...")
     generate_examples(generate_main_index=True)
     print("Example documentation generated successfully!")

docs/getting_started/installation.md

@@ -65,6 +65,7 @@ uv pip install flash-attn --no-build-isolation -v
 
 ## Next Steps
 
-- [Quick Start Guide](quick_start.md) - Get started with your first video generation
+- [Quick Start](quick_start.md) - Generate your first video
+- [Inference Cookbook](../cookbook/index.md) - Choose a maintained recipe
 - [Configuration](../inference/configuration.md) - Learn about configuration options
-- [Examples](../inference/examples/examples_inference_index.md) - Explore example scripts and notebooks
+- [Examples](../inference/examples/examples_inference_index.md) - Explore scripts and notebooks

docs/getting_started/quick_start.md

@@ -23,61 +23,21 @@ Also optionally install flash-attn:
 uv pip install flash-attn --no-build-isolation -v
 ```
 
-## Basic Usage
+## Choose a maintained recipe
 
-### Text-to-Video Generation
+The cookbook selects complete, checked-in recipes instead of mixing model,
+parallelism, offload, and attention settings independently.
 
-```python
-from fastvideo import VideoGenerator
+[Open the inference cookbook](../cookbook/index.md){ .md-button .md-button--primary }
 
-def main():
-    # Create a video generator with a pre-trained model
-    generator = VideoGenerator.from_pretrained(
-        "Wan-AI/Wan2.1-T2V-1.3B-Diffusers",
-        num_gpus=1,  # Adjust based on your hardware
-    )
-
-    # Define a prompt for your video
-    prompt = "A curious raccoon peers through a vibrant field of yellow sunflowers, its eyes wide with interest."
-
-    # Generate the video
-    video = generator.generate_video(
-        prompt,
-        output_path="my_videos/",  # Controls where videos are saved
-        save_video=True
-    )
-
-if __name__ == '__main__':
-    main()
-```
-
-### Image-to-Video Generation
-
-```python
-from fastvideo import VideoGenerator, SamplingParam
-
-def main():
-    # Create the generator
-    model_name = "Wan-AI/Wan2.1-I2V-14B-480P-Diffusers"
-    generator = VideoGenerator.from_pretrained(model_name, num_gpus=1)
-
-    # Set up parameters with an initial image
-    sampling_param = SamplingParam.from_pretrained(model_name)
-    sampling_param.image_path = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg"
-    sampling_param.num_frames = 107
-
-    # Generate video based on the image
-    prompt = "A photograph coming to life with gentle movement"
-    generator.generate_video(prompt, sampling_param=sampling_param,
-                             output_path="my_videos/",
-                             save_video=True)
-
-if __name__ == '__main__':
-    main()
-```
+!!! tip "Need more control?"
+    Start from a maintained recipe, then use the
+    [configuration](../inference/configuration.md) and
+    [optimization](../inference/optimizations.md) guides for supported changes.
 
 ## Next Steps
 
+- [Inference Cookbook](../cookbook/index.md) - Choose a maintained recipe
 - [Installation Guide](installation.md) - Detailed installation instructions
 - [Configuration](../inference/configuration.md) - Learn about configuration options
 - [Examples](../inference/examples/examples_inference_index.md) - Explore more

docs/inference/support_matrix.md

@@ -64,7 +64,6 @@ column links a runnable script in `examples/inference/basic/` where one exists.
 | ltx2 | `FastVideo/LTX2-Distilled-Diffusers`<br>`FastVideo/LTX2.3-Distilled-Diffusers`<br>`FastVideo/LTX-2.3-Distilled-Diffusers` | T2V | [basic_ltx2_distilled.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_ltx2_distilled.py) |
 | ltx2 | `Lightricks/LTX-2.3`<br>`FastVideo/LTX2.3-base`<br>`FastVideo/LTX2.3-Diffusers` | T2V | [basic_ltx2.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_ltx2.py) |
 | ltx2 | `Lightricks/LTX-2`<br>`FastVideo/LTX2-base`<br>`FastVideo/LTX2-Diffusers` | T2V | [basic_ltx2.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_ltx2.py) |
-| mmaudio | `FastVideo/MMAudio-large-44k-v2-Diffusers` | V2A, T2A | [basic_mmaudio.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_mmaudio.py) |
 | matrixgame | `FastVideo/Matrix-Game-2.0-Base-Distilled-Diffusers`<br>`FastVideo/Matrix-Game-2.0-GTA-Distilled-Diffusers`<br>`FastVideo/Matrix-Game-2.0-TempleRun-Distilled-Diffusers`<br>`FastVideo/Matrix-Game-2.0-Base-Diffusers`<br>`FastVideo/Matrix-Game-2.0-GTA-Diffusers`<br>`FastVideo/Matrix-Game-2.0-TempleRun-Diffusers`<br>`mignonjia/mg_longtuning_distilled_zelda`<br>`mignonjia/mg_sf_distilled_zelda_1k_steps`<br>`mignonjia/mg_sf_distilled_zelda`<br>`mignonjia/mg_causal_zelda`<br>`mignonjia/mg_bidirectional_zelda` | I2V | [basic_matrixgame2.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_matrixgame2.py) |
 | matrixgame | `FastVideo/Matrix-Game-3.0-Base-Distilled-Diffusers` | I2V | [basic_matrixgame3.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_matrixgame3.py) |
 | minimax_h3 | `MiniMaxAI/MiniMax-H3` | T2V, I2V | [T2VA](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_minimax_h3_t2v.py)<br>[FL2VA](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_minimax_h3_fl2va.py)<br>[Ref2VA](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_minimax_h3_ref2va.py) |
@@ -95,10 +94,6 @@ column links a runnable script in `examples/inference/basic/` where one exists.
 (`StableAudioT2AConfig` / `StableAudioOpenSmallConfig`); they are registered
 under the generic T2V workload option in the registry.
 
-**Note (MMAudio)**: the registered Hugging Face model ID is reserved but not
-yet public. Follow the [MMAudio inference guide](https://github.com/hao-ai-lab/FastVideo/blob/main/fastvideo/pipelines/basic/mmaudio/README.md)
-to convert the official weights locally and set `MMAUDIO_MODEL_PATH`.
-
 **Note (MiniMax H3)**: T2VA, FL2VA, and Ref2VA all generate video with stereo
 audio. Use the Ref2VA example when passing ordered image, video, or audio
 references.

examples/inference/basic/README.md

@@ -33,35 +33,6 @@ For the typed config/request path added during the inference API refactor:
 python examples/inference/basic/basic_dmd_new_api.py
 ```
 
-## LTX-2.5 single-file bundles
-
-These examples load LTX-2.5 from a single-file bundle: one `.safetensors`
-file carrying every component (transformer, video VAE, audio VAE, vocoder,
-text projection). (The Hugging Face release ships as a split pack — one
-file per component — which loads through the standard repo path instead.)
-Pass the bundle FILE path directly:
-
-```bash
-python examples/inference/basic/basic_ltx2_5_distilled.py \
-    --model-path /path/to/bundle.safetensors \
-    --gemma-root /path/to/gemma_root
-```
-
-| bundle variant | preset | sampling defaults |
-|---|---|---|
-| distilled | `ltx2_distilled` | one stage, 8 steps, CFG 1.0 (no CFG/STG, no spatial upscaler) |
-| sft / base | `ltx2_base` | 40 steps, CFG 3.0 with STG |
-
-- The variant is read from the bundle header when declared; otherwise the
-  `distilled` token in the file name decides.
-- The Gemma text encoder is NOT in the bundle. Declare its root with
-  `--gemma-root` (or `FASTVIDEO_LTX_ENCODER_ROOT`), and use the root shipped
-  with the same transformer variant — the roots differ in prompt templating.
-- Decoder caveat: bundles that declare a diffusion VAE decoder
-  (`CausalDiffusionVAE`) are not supported yet; loading them currently
-  fails at VAE build time. Bundles with the classic `CausalVideoAutoencoder`
-  run end to end.
-
 ## Basic Walkthrough
 
 All you need to generate videos using multi-gpus from state-of-the-art diffusion pipelines is the following few lines!

examples/inference/basic/basic.py

@@ -3,8 +3,6 @@ from fastvideo import VideoGenerator
 # from fastvideo.api.sampling_param import SamplingParam
 
 OUTPUT_PATH = "video_samples"
-
-
 def main():
     # FastVideo will automatically use the optimal default arguments for the
     # model.
@@ -14,11 +12,11 @@ def main():
         "Wan-AI/Wan2.1-T2V-1.3B-Diffusers",
         # FastVideo will automatically handle distributed setup
         num_gpus=1,
-        use_fsdp_inference=False,  # set to True if GPU is out of memory
+        use_fsdp_inference=False, # set to True if GPU is out of memory
         dit_cpu_offload=False,
         vae_cpu_offload=False,
         text_encoder_cpu_offload=True,
-        pin_cpu_memory=True,  # set to false if low CPU RAM or hit obscure "CUDA error: Invalid argument"
+        pin_cpu_memory=True, # set to false if low CPU RAM or hit obscure "CUDA error: Invalid argument"
         # image_encoder_cpu_offload=False,
     )
 
@@ -26,19 +24,22 @@ def main():
     # sampling_param.num_frames = 45
     # sampling_param.image_path = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg"
     # Generate videos with the same simple API, regardless of GPU count
-    prompt = ("A curious raccoon peers through a vibrant field of yellow sunflowers, its eyes "
-              "wide with interest. The playful yet serene atmosphere is complemented by soft "
-              "natural light filtering through the petals. Mid-shot, warm and cheerful tones.")
+    prompt = (
+        "A curious raccoon peers through a vibrant field of yellow sunflowers, its eyes "
+        "wide with interest. The playful yet serene atmosphere is complemented by soft "
+        "natural light filtering through the petals. Mid-shot, warm and cheerful tones."
+    )
     video = generator.generate_video(prompt, output_path=OUTPUT_PATH, save_video=True)
     # video = generator.generate_video(prompt, sampling_param=sampling_param, output_path="wan_t2v_videos/")
 
     # Generate another video with a different prompt, without reloading the
     # model!
-    prompt2 = ("A majestic lion strides across the golden savanna, its powerful frame "
-               "glistening under the warm afternoon sun. The tall grass ripples gently in "
-               "the breeze, enhancing the lion's commanding presence. The tone is vibrant, "
-               "embodying the raw energy of the wild. Low angle, steady tracking shot, "
-               "cinematic.")
+    prompt2 = (
+        "A majestic lion strides across the golden savanna, its powerful frame "
+        "glistening under the warm afternoon sun. The tall grass ripples gently in "
+        "the breeze, enhancing the lion's commanding presence. The tone is vibrant, "
+        "embodying the raw energy of the wild. Low angle, steady tracking shot, "
+        "cinematic.")
     video2 = generator.generate_video(prompt2, output_path=OUTPUT_PATH, save_video=True)
 
 

examples/inference/basic/basic_cosmos2_5_i2w.py

@@ -30,7 +30,8 @@ def main():
         "and casting reflections onto adjacent vehicles. "
         "The motion creates space in the lineup, signaling activity within the otherwise quiet station. "
         "It then comes to a smooth stop, resuming its position in line. "
-        "Overhead signage in Chinese characters remains illuminated, enhancing the vibrant, urban night scene.")
+        "Overhead signage in Chinese characters remains illuminated, enhancing the vibrant, urban night scene."
+    )
 
     generator.generate_video(
         prompt,
@@ -46,3 +47,4 @@ def main():
 
 if __name__ == "__main__":
     main()
+

examples/inference/basic/basic_cosmos2_5_t2w.py

@@ -31,7 +31,8 @@ def main():
         "The welding torch consistently emits sparks and light, and the smoke continues to rise, diffusing slightly as it moves upward. "
         "The metal surface beneath the torch shows ongoing signs of heating and melting. "
         "The scene retains its industrial ambiance, with the welding sparks and smoke dominating the visual field, "
-        "underscoring the ongoing nature of the welding operation.")
+        "underscoring the ongoing nature of the welding operation."
+    )
 
     generator.generate_video(
         prompt,
@@ -45,3 +46,6 @@ def main():
 
 if __name__ == "__main__":
     main()
+
+
+

examples/inference/basic/basic_cosmos2_5_v2w.py

@@ -50,3 +50,4 @@ def main():
 
 if __name__ == "__main__":
     main()
+

examples/inference/basic/basic_dmd.py

@@ -5,8 +5,6 @@ from fastvideo import VideoGenerator
 from fastvideo.api.sampling_param import SamplingParam
 
 OUTPUT_PATH = "video_samples_dmd2"
-
-
 def main():
     os.environ["FASTVIDEO_ATTENTION_BACKEND"] = "VIDEO_SPARSE_ATTN"
 
@@ -16,10 +14,10 @@ def main():
         model_name,
         # FastVideo will automatically handle distributed setup
         num_gpus=1,
-        use_fsdp_inference=False,  # set to True if GPU is out of memory
+        use_fsdp_inference=False, # set to True if GPU is out of memory
         # Adjust these offload parameters if you have < 32GB of VRAM
         text_encoder_cpu_offload=True,
-        pin_cpu_memory=True,  # set to false if low CPU RAM or hit obscure "CUDA error: Invalid argument"
+        pin_cpu_memory=True, # set to false if low CPU RAM or hit obscure "CUDA error: Invalid argument"
         dit_cpu_offload=False,
         vae_cpu_offload=False,
         VSA_sparsity=0.8,
@@ -27,6 +25,7 @@ def main():
     load_end_time = time.perf_counter()
     load_time = load_end_time - load_start_time
 
+
     sampling_param = SamplingParam.from_pretrained(model_name)
     sampling_param.num_frames = 81
 
@@ -40,16 +39,18 @@ def main():
 
     # Generate another video with a different prompt, without reloading the
     # model!
-    prompt2 = ("A majestic lion strides across the golden savanna, its powerful frame "
-               "glistening under the warm afternoon sun. The tall grass ripples gently in "
-               "the breeze, enhancing the lion's commanding presence. The tone is vibrant, "
-               "embodying the raw energy of the wild. Low angle, steady tracking shot, "
-               "cinematic.")
+    prompt2 = (
+        "A majestic lion strides across the golden savanna, its powerful frame "
+        "glistening under the warm afternoon sun. The tall grass ripples gently in "
+        "the breeze, enhancing the lion's commanding presence. The tone is vibrant, "
+        "embodying the raw energy of the wild. Low angle, steady tracking shot, "
+        "cinematic.")
     start_time = time.perf_counter()
     video2 = generator.generate_video(prompt2, output_path=OUTPUT_PATH, save_video=True, num_frames=81)
     end_time = time.perf_counter()
     gen_time2 = end_time - start_time
 
+
     print(f"Time taken to load model: {load_time} seconds")
     print(f"Time taken to generate video: {gen_time} seconds")
     print(f"Time taken to generate video2: {gen_time2} seconds")

examples/inference/basic/basic_dmd_new_api.py

@@ -32,9 +32,11 @@ def main():
         ),
         # PR 2 still routes a few advanced inference knobs through the
         # compatibility bridge until they get first-class typed fields.
-        pipeline=PipelineSelection(experimental={
-            "VSA_sparsity": 0.8,
-        }, ),
+        pipeline=PipelineSelection(
+            experimental={
+                "VSA_sparsity": 0.8,
+            },
+        ),
     )
 
     load_start_time = time.perf_counter()
@@ -42,12 +44,14 @@ def main():
     load_end_time = time.perf_counter()
     load_time = load_end_time - load_start_time
 
-    prompt = ("A neon-lit alley in futuristic Tokyo during a heavy rainstorm at night. "
-              "The puddles reflect glowing signs in kanji, advertising ramen, karaoke, "
-              "and VR arcades. A woman in a translucent raincoat walks briskly with an "
-              "LED umbrella. Steam rises from a street food cart, and a cat darts "
-              "across the screen. Raindrops are visible on the camera lens, creating "
-              "a cinematic bokeh effect.")
+    prompt = (
+        "A neon-lit alley in futuristic Tokyo during a heavy rainstorm at night. "
+        "The puddles reflect glowing signs in kanji, advertising ramen, karaoke, "
+        "and VR arcades. A woman in a translucent raincoat walks briskly with an "
+        "LED umbrella. Steam rises from a street food cart, and a cat darts "
+        "across the screen. Raindrops are visible on the camera lens, creating "
+        "a cinematic bokeh effect."
+    )
     request = GenerationRequest(
         prompt=prompt,
         output=OutputConfig(
@@ -62,11 +66,13 @@ def main():
     end_time = time.perf_counter()
     gen_time = end_time - start_time
 
-    prompt2 = ("A majestic lion strides across the golden savanna, its powerful frame "
-               "glistening under the warm afternoon sun. The tall grass ripples gently "
-               "in the breeze, enhancing the lion's commanding presence. The tone is "
-               "vibrant, embodying the raw energy of the wild. Low angle, steady "
-               "tracking shot, cinematic.")
+    prompt2 = (
+        "A majestic lion strides across the golden savanna, its powerful frame "
+        "glistening under the warm afternoon sun. The tall grass ripples gently "
+        "in the breeze, enhancing the lion's commanding presence. The tone is "
+        "vibrant, embodying the raw energy of the wild. Low angle, steady "
+        "tracking shot, cinematic."
+    )
     request2 = GenerationRequest(
         prompt=prompt2,
         output=OutputConfig(

examples/inference/basic/basic_dreamx_world.py

@@ -2,6 +2,7 @@ import os
 
 from fastvideo import VideoGenerator
 
+
 OUTPUT_PATH = os.getenv("DREAMX_WORLD_OUTPUT_PATH", "video_samples_dreamx_world")
 
 
@@ -45,8 +46,10 @@ def main():
         "num_inference_steps": _env_int("DREAMX_WORLD_STEPS", 30),
         "guidance_scale": _env_float("DREAMX_WORLD_GUIDANCE", 5.0),
         "action_list": os.getenv("DREAMX_WORLD_ACTIONS", "w,d,w").split(","),
-        "action_speed_list":
-        [float(value) for value in os.getenv("DREAMX_WORLD_ACTION_SPEEDS", "4.0,2.0,4.0").split(",")],
+        "action_speed_list": [
+            float(value)
+            for value in os.getenv("DREAMX_WORLD_ACTION_SPEEDS", "4.0,2.0,4.0").split(",")
+        ],
     }
     if image_path:
         kwargs["image_path"] = image_path

examples/inference/basic/basic_flux2.py

@@ -64,8 +64,12 @@ def main() -> None:
 
     output = Path(args.output)
     output.parent.mkdir(parents=True, exist_ok=True)
-    tp_size = args.tp_size if args.tp_size is not None else (args.num_gpus if args.num_gpus > 1 else 1)
-    sp_size = args.sp_size if args.sp_size is not None else (1 if args.num_gpus > 1 else args.num_gpus)
+    tp_size = args.tp_size if args.tp_size is not None else (
+        args.num_gpus if args.num_gpus > 1 else 1
+    )
+    sp_size = args.sp_size if args.sp_size is not None else (
+        1 if args.num_gpus > 1 else args.num_gpus
+    )
 
     generator_config = GeneratorConfig(
         model_path=args.model_path,

examples/inference/basic/basic_flux2_klein.py

@@ -21,6 +21,7 @@ from fastvideo.api import (
     SamplingConfig,
 )
 
+
 DEFAULT_PROMPT = "a brushed steel espresso machine on a marble counter, morning window light"
 
 

examples/inference/basic/basic_flux_dev.py

@@ -9,9 +9,11 @@ import re
 
 DEFAULT_PROMPTS = [
     "a photo of a cat",
-    ("a cinematic photo of a red panda wearing a tiny backpack, standing on a "
-     "rainy neon-lit street at night, shallow depth of field, sharp focus, "
-     "35mm, bokeh"),
+    (
+        "a cinematic photo of a red panda wearing a tiny backpack, standing on a "
+        "rainy neon-lit street at night, shallow depth of field, sharp focus, "
+        "35mm, bokeh"
+    ),
 ]
 
 
@@ -40,7 +42,9 @@ def _remove_existing_outputs(out_dir: str, filename_base: str) -> None:
 
 
 def parse_args() -> argparse.Namespace:
-    p = argparse.ArgumentParser(description="Run FLUX.1-dev text-to-image with FastVideo VideoGenerator.", )
+    p = argparse.ArgumentParser(
+        description="Run FLUX.1-dev text-to-image with FastVideo VideoGenerator.",
+    )
     p.add_argument(
         "--model-path",
         default="official_weights/FLUX.1-dev",
@@ -104,7 +108,9 @@ def main() -> None:
     try:
         for i, prompt in enumerate(prompts):
             seed = args.seed + i
-            filename_base = (f"flux_dev_{i:02d}_seed{seed}_{_safe_filename(prompt, max_len=80)}")
+            filename_base = (
+                f"flux_dev_{i:02d}_seed{seed}_{_safe_filename(prompt, max_len=80)}"
+            )
             _remove_existing_outputs(args.out_dir, filename_base)
             output_path = os.path.join(args.out_dir, f"{filename_base}.png")
             print(f"[flux] prompt_idx={i} seed={seed} output_path={output_path}")

examples/inference/basic/basic_gamecraft.py

@@ -33,20 +33,21 @@ MODEL_PATH = os.environ.get("GAMECRAFT_MODEL_PATH", "FastVideo/HunyuanGameCraft-
 
 # Default prompts for demo
 DEFAULT_PROMPTS = {
-    "village":
-    "A charming medieval village with cobblestone streets, thatched-roof houses, and vibrant flower gardens under a bright blue sky.",
-    "temple":
-    "A majestic ancient temple stands under a clear blue sky, its grandeur highlighted by towering Doric columns and intricate architectural details.",
-    "forest":
-    "A lush green forest with tall trees, dappled sunlight filtering through the leaves, and a winding dirt path.",
+    "village": "A charming medieval village with cobblestone streets, thatched-roof houses, and vibrant flower gardens under a bright blue sky.",
+    "temple": "A majestic ancient temple stands under a clear blue sky, its grandeur highlighted by towering Doric columns and intricate architectural details.",
+    "forest": "A lush green forest with tall trees, dappled sunlight filtering through the leaves, and a winding dirt path.",
     "beach": "A tropical beach with crystal clear turquoise water, white sand, and palm trees swaying in the breeze.",
 }
 
 # I2V: default reference image (URL). Can override with a local path.
-DEFAULT_I2V_IMAGE_URL = ("https://huggingface.co/datasets/huggingface/documentation-images/"
-                         "resolve/main/diffusers/astronaut.jpg")
-DEFAULT_I2V_PROMPT = ("An astronaut hatching from an egg, on the surface of the moon, "
-                      "the darkness and depth of space realised in the background.")
+DEFAULT_I2V_IMAGE_URL = (
+    "https://huggingface.co/datasets/huggingface/documentation-images/"
+    "resolve/main/diffusers/astronaut.jpg"
+)
+DEFAULT_I2V_PROMPT = (
+    "An astronaut hatching from an egg, on the surface of the moon, "
+    "the darkness and depth of space realised in the background."
+)
 
 OUTPUT_PATH = "video_samples_gamecraft"
 

examples/inference/basic/basic_gen3c.py

@@ -26,35 +26,51 @@ from fastvideo import VideoGenerator
 
 def main():
     parser = argparse.ArgumentParser(description="GEN3C video generation")
-    parser.add_argument("--model_path", type=str, default="converted_weights/GEN3C-Cosmos-7B")
-    parser.add_argument("--image_path", type=str, default=None, help="Input image for 3D cache conditioning")
-    parser.add_argument("--prompt", type=str, default="A slow camera pan over a sunlit landscape.")
+    parser.add_argument("--model_path",
+                        type=str,
+                        default="converted_weights/GEN3C-Cosmos-7B")
+    parser.add_argument("--image_path",
+                        type=str,
+                        default=None,
+                        help="Input image for 3D cache conditioning")
+    parser.add_argument("--prompt",
+                        type=str,
+                        default="A slow camera pan over a sunlit landscape.")
     parser.add_argument(
         "--negative_prompt",
         type=str,
-        default=("The video captures a series of frames showing ugly scenes, static with no motion, motion blur, "
-                 "over-saturation, shaky footage, low resolution, grainy texture, pixelated images, poorly lit areas, "
-                 "underexposed and overexposed scenes, poor color balance, washed out colors, choppy sequences, "
-                 "jerky movements, low frame rate, artifacting, color banding, unnatural transitions, outdated special "
-                 "effects, fake elements, unconvincing visuals, poorly edited content, jump cuts, visual noise, and "
-                 "flickering. Overall, the video is of poor quality."),
+        default=(
+            "The video captures a series of frames showing ugly scenes, static with no motion, motion blur, "
+            "over-saturation, shaky footage, low resolution, grainy texture, pixelated images, poorly lit areas, "
+            "underexposed and overexposed scenes, poor color balance, washed out colors, choppy sequences, "
+            "jerky movements, low frame rate, artifacting, color banding, unnatural transitions, outdated special "
+            "effects, fake elements, unconvincing visuals, poorly edited content, jump cuts, visual noise, and "
+            "flickering. Overall, the video is of poor quality."
+        ),
     )
-    parser.add_argument(
-        "--trajectory",
-        type=str,
-        default="left",
-        choices=["left", "right", "up", "down", "zoom_in", "zoom_out", "clockwise", "counterclockwise", "none"])
+    parser.add_argument("--trajectory",
+                        type=str,
+                        default="left",
+                        choices=[
+                            "left", "right", "up", "down", "zoom_in",
+                            "zoom_out", "clockwise", "counterclockwise", "none"
+                        ])
     parser.add_argument("--movement_distance", type=float, default=0.3)
     parser.add_argument("--camera_rotation",
                         type=str,
                         default="center_facing",
-                        choices=["center_facing", "no_rotation", "trajectory_aligned"])
+                        choices=[
+                            "center_facing", "no_rotation",
+                            "trajectory_aligned"
+                        ])
     parser.add_argument("--height", type=int, default=704)
     parser.add_argument("--width", type=int, default=1280)
     parser.add_argument("--num_frames", type=int, default=121)
     parser.add_argument("--num_inference_steps", type=int, default=35)
     parser.add_argument("--guidance_scale", type=float, default=1.0)
-    parser.add_argument("--output_path", type=str, default="outputs_video/gen3c.mp4")
+    parser.add_argument("--output_path",
+                        type=str,
+                        default="outputs_video/gen3c.mp4")
     parser.add_argument("--seed", type=int, default=42)
     args = parser.parse_args()
 

examples/inference/basic/basic_hy15.py

@@ -3,8 +3,6 @@ import json
 # from fastvideo.api.sampling_param import SamplingParam
 
 OUTPUT_PATH = "video_samples_hy15"
-
-
 def main():
     # FastVideo will automatically use the optimal default arguments for the
     # model.
@@ -14,38 +12,31 @@ def main():
         "hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v",
         # FastVideo will automatically handle distributed setup
         num_gpus=1,
-        use_fsdp_inference=False,  # set to True if GPU is out of memory
+        use_fsdp_inference=False, # set to True if GPU is out of memory
         dit_cpu_offload=True,
         vae_cpu_offload=True,
         text_encoder_cpu_offload=True,
-        pin_cpu_memory=True,  # set to false if low CPU RAM or hit obscure "CUDA error: Invalid argument"
+        pin_cpu_memory=True, # set to false if low CPU RAM or hit obscure "CUDA error: Invalid argument"
         # image_encoder_cpu_offload=False,
     )
 
-    prompt = ("A curious raccoon peers through a vibrant field of yellow sunflowers, its eyes "
-              "wide with interest. The playful yet serene atmosphere is complemented by soft "
-              "natural light filtering through the petals. Mid-shot, warm and cheerful tones.")
+    prompt = (
+        "A curious raccoon peers through a vibrant field of yellow sunflowers, its eyes "
+        "wide with interest. The playful yet serene atmosphere is complemented by soft "
+        "natural light filtering through the petals. Mid-shot, warm and cheerful tones."
+    )
 
-    video = generator.generate_video(prompt,
-                                     output_path=OUTPUT_PATH,
-                                     save_video=True,
-                                     negative_prompt="",
-                                     num_frames=81,
-                                     fps=16)
+    video = generator.generate_video(prompt, output_path=OUTPUT_PATH, save_video=True, negative_prompt="", num_frames=81, fps=16)
 
-    prompt2 = ("A majestic lion strides across the golden savanna, its powerful frame "
-               "glistening under the warm afternoon sun. The tall grass ripples gently in "
-               "the breeze, enhancing the lion's commanding presence. The tone is vibrant, "
-               "embodying the raw energy of the wild. Low angle, steady tracking shot, "
-               "cinematic.")
+    prompt2 = (
+        "A majestic lion strides across the golden savanna, its powerful frame "
+        "glistening under the warm afternoon sun. The tall grass ripples gently in "
+        "the breeze, enhancing the lion's commanding presence. The tone is vibrant, "
+        "embodying the raw energy of the wild. Low angle, steady tracking shot, "
+        "cinematic.")
 
-    video2 = generator.generate_video(prompt2,
-                                      output_path=OUTPUT_PATH,
-                                      save_video=True,
-                                      negative_prompt="",
-                                      num_frames=81,
-                                      fps=16)
+    video2 = generator.generate_video(prompt2, output_path=OUTPUT_PATH, save_video=True, negative_prompt="", num_frames=81, fps=16)
 
 
 if __name__ == "__main__":
-    main()
+    main()

examples/inference/basic/basic_hy15_1080p.py

@@ -3,37 +3,38 @@ import json
 # from fastvideo.api.sampling_param import SamplingParam
 
 OUTPUT_PATH = "video_samples_hy15_1080p"
-
-
 def main():
     # FastVideo will automatically use the optimal default arguments for the
     # model.
     # If a local path is provided, FastVideo will make a best effort
     # attempt to identify the optimal arguments.
     generator = VideoGenerator.from_pretrained(
-        "weizhou03/HunyuanVideo-1.5-Diffusers-1080p-2SR",  # 480p -> 720p -> 1080p
+        "weizhou03/HunyuanVideo-1.5-Diffusers-1080p-2SR", # 480p -> 720p -> 1080p
         # or "weizhou03/HunyuanVideo-1.5-Diffusers-1080p" # 720p -> 1080p
         # FastVideo will automatically handle distributed setup
         num_gpus=1,
-        use_fsdp_inference=False,  # set to True if GPU is out of memory
+        use_fsdp_inference=False, # set to True if GPU is out of memory
         dit_cpu_offload=True,
         vae_cpu_offload=True,
         text_encoder_cpu_offload=True,
-        pin_cpu_memory=True,  # set to false if low CPU RAM or hit obscure "CUDA error: Invalid argument"
+        pin_cpu_memory=True, # set to false if low CPU RAM or hit obscure "CUDA error: Invalid argument"
         # image_encoder_cpu_offload=False,
     )
 
-    prompt = ("A curious raccoon peers through a vibrant field of yellow sunflowers, its eyes "
-              "wide with interest. The playful yet serene atmosphere is complemented by soft "
-              "natural light filtering through the petals. Mid-shot, warm and cheerful tones.")
+    prompt = (
+        "A curious raccoon peers through a vibrant field of yellow sunflowers, its eyes "
+        "wide with interest. The playful yet serene atmosphere is complemented by soft "
+        "natural light filtering through the petals. Mid-shot, warm and cheerful tones."
+    )
 
     video = generator.generate_video(prompt, output_path=OUTPUT_PATH, save_video=True, negative_prompt="")
 
-    prompt2 = ("A majestic lion strides across the golden savanna, its powerful frame "
-               "glistening under the warm afternoon sun. The tall grass ripples gently in "
-               "the breeze, enhancing the lion's commanding presence. The tone is vibrant, "
-               "embodying the raw energy of the wild. Low angle, steady tracking shot, "
-               "cinematic.")
+    prompt2 = (
+        "A majestic lion strides across the golden savanna, its powerful frame "
+        "glistening under the warm afternoon sun. The tall grass ripples gently in "
+        "the breeze, enhancing the lion's commanding presence. The tone is vibrant, "
+        "embodying the raw energy of the wild. Low angle, steady tracking shot, "
+        "cinematic.")
 
     video2 = generator.generate_video(prompt2, output_path=OUTPUT_PATH, save_video=True, negative_prompt="")
 

examples/inference/basic/basic_hyworld.py

@@ -6,8 +6,6 @@ DEFAULT_PROMPT = 'A paved pathway leads towards a stone arch bridge spanning a c
 DEFAULT_IMAGE = 'https://raw.githubusercontent.com/Tencent-Hunyuan/HY-WorldPlay/main/assets/img/test.png'
 
 OUTPUT_PATH = "video_samples_hyworld"
-
-
 def main():
     import argparse
 

examples/inference/basic/basic_kandinsky5_i2v.py

@@ -7,7 +7,7 @@ IMAGE_PATH = "assets/girl.png"
 
 def main():
     generator = VideoGenerator.from_pretrained(
-        "kandinskylab/Kandinsky-5.0-I2V-Pro-distilled-5s-Diffusers",
+        "kandinskylab/Kandinsky-5.0-I2V-Pro-distilled-5s-Diffusers", 
         # "kandinskylab/Kandinsky-5.0-I2V-Pro-sft-5s-Diffusers"
         # "kandinskylab/Kandinsky-5.0-I2V-Lite-5s-Diffusers"
         num_gpus=1,
@@ -19,7 +19,9 @@ def main():
         # image_encoder_cpu_offload=False,
     )
 
-    prompt = ("A woman stands up and walks away")
+    prompt = (
+        "A woman stands up and walks away"
+    )
     _ = generator.generate_video(
         prompt,
         image_path=IMAGE_PATH,

examples/inference/basic/basic_kandinsky5_t2v.py

@@ -2,7 +2,6 @@ from fastvideo import VideoGenerator
 
 OUTPUT_PATH = "video_samples_kandinsky5_t2v"
 
-
 def main():
     generator = VideoGenerator.from_pretrained(
         "kandinskylab/Kandinsky-5.0-T2V-Lite-sft-5s-Diffusers",
@@ -18,28 +17,21 @@ def main():
         # image_encoder_cpu_offload=False,
     )
 
-    prompt = ("A curious raccoon peers through a vibrant field of yellow sunflowers, its eyes "
-              "wide with interest. The playful yet serene atmosphere is complemented by soft "
-              "natural light filtering through the petals. Mid-shot, warm and cheerful tones.")
-    _ = generator.generate_video(prompt,
-                                 output_path=OUTPUT_PATH,
-                                 save_video=True,
-                                 height=512,
-                                 width=768,
-                                 num_frames=121)
+    prompt = (
+        "A curious raccoon peers through a vibrant field of yellow sunflowers, its eyes "
+        "wide with interest. The playful yet serene atmosphere is complemented by soft "
+        "natural light filtering through the petals. Mid-shot, warm and cheerful tones."
+    )
+    _ = generator.generate_video(prompt, output_path=OUTPUT_PATH, save_video=True,height=512, width=768, num_frames=121)
 
-    prompt2 = ("A majestic lion strides across the golden savanna, its powerful frame "
-               "glistening under the warm afternoon sun. The tall grass ripples gently in "
-               "the breeze, enhancing the lion's commanding presence. The tone is vibrant, "
-               "embodying the raw energy of the wild. Low angle, steady tracking shot, "
-               "cinematic.")
-    _ = generator.generate_video(prompt2,
-                                 output_path=OUTPUT_PATH,
-                                 save_video=True,
-                                 height=512,
-                                 width=768,
-                                 num_frames=121)
+    prompt2 = (
+        "A majestic lion strides across the golden savanna, its powerful frame "
+        "glistening under the warm afternoon sun. The tall grass ripples gently in "
+        "the breeze, enhancing the lion's commanding presence. The tone is vibrant, "
+        "embodying the raw energy of the wild. Low angle, steady tracking shot, "
+        "cinematic.")
+    _ = generator.generate_video(prompt2, output_path=OUTPUT_PATH, save_video=True, height=512, width=768, num_frames=121)
 
 
 if __name__ == "__main__":
-    main()
+    main()

examples/inference/basic/basic_lingbotworld2_causal_fast.py

@@ -6,6 +6,7 @@ from pathlib import Path
 
 from fastvideo import VideoGenerator
 
+
 REPO_ROOT = Path(__file__).resolve().parents[3]
 DATASET_DIR = REPO_ROOT / "examples" / "dataset" / "lingbotworld2"
 OUTPUT_PATH = REPO_ROOT / "outputs" / "lingbotworld2_causal_fast.mp4"

examples/inference/basic/basic_lingbotworld_base_cam.py

@@ -3,19 +3,17 @@ from fastvideo.models.dits.lingbotworld.cam_utils import prepare_camera_embeddin
 
 # from fastvideo.api.sampling_param import SamplingParam
 OUTPUT_PATH = "video_samples_lingbotworld"
-
-
 def main():
     # FastVideo will automatically use the optimal default arguments for the
     # model.
     # If a local path is provided, FastVideo will make a best effort
     # attempt to identify the optimal arguments.
     generator = VideoGenerator.from_pretrained(
-        "FastVideo/LingBot-World-Base-Cam-Diffusers",
+         "FastVideo/LingBot-World-Base-Cam-Diffusers",
         # FastVideo will automatically handle distributed setup
         num_gpus=1,
-        use_fsdp_inference=False,  # set to True if GPU is out of memory
-        dit_cpu_offload=True,  # DiT need to be offloaded for MoE
+        use_fsdp_inference=False, # set to True if GPU is out of memory
+        dit_cpu_offload=True, # DiT need to be offloaded for MoE
         vae_cpu_offload=False,
         text_encoder_cpu_offload=True,
         # Set pin_cpu_memory to false if CPU RAM is limited and there're no frequent CPU-GPU transfer

examples/inference/basic/basic_longcat_i2v.py

@@ -21,16 +21,20 @@ import os
 from fastvideo import VideoGenerator
 
 # Common prompts and settings matching the shell script examples
-PROMPT = ("A woman sits at a wooden table by the window in a cozy café. She reaches out "
-          "with her right hand, picks up the white coffee cup from the saucer, and gently "
-          "brings it to her lips to take a sip. After drinking, she places the cup back on "
-          "the table and looks out the window, enjoying the peaceful atmosphere.")
+PROMPT = (
+    "A woman sits at a wooden table by the window in a cozy café. She reaches out "
+    "with her right hand, picks up the white coffee cup from the saucer, and gently "
+    "brings it to her lips to take a sip. After drinking, she places the cup back on "
+    "the table and looks out the window, enjoying the peaceful atmosphere."
+)
 
-NEGATIVE_PROMPT = ("Bright tones, overexposed, static, blurred details, subtitles, style, works, "
-                   "paintings, images, static, overall gray, worst quality, low quality, JPEG compression "
-                   "residue, ugly, incomplete, extra fingers, poorly drawn hands, poorly drawn faces, "
-                   "deformed, disfigured, misshapen limbs, fused fingers, still picture, messy background, "
-                   "three legs, many people in the background, walking backwards")
+NEGATIVE_PROMPT = (
+    "Bright tones, overexposed, static, blurred details, subtitles, style, works, "
+    "paintings, images, static, overall gray, worst quality, low quality, JPEG compression "
+    "residue, ugly, incomplete, extra fingers, poorly drawn hands, poorly drawn faces, "
+    "deformed, disfigured, misshapen limbs, fused fingers, still picture, messy background, "
+    "three legs, many people in the background, walking backwards"
+)
 
 # Input image path
 IMAGE_PATH = "assets/girl.png"
@@ -47,20 +51,20 @@ def basic_generation():
     print("=" * 60)
     print("LongCat I2V: Basic Generation (50 steps, 480p)")
     print("=" * 60)
-
+    
     generator = VideoGenerator.from_pretrained(
         "FastVideo/LongCat-Video-I2V-Diffusers",
         num_gpus=1,
-        use_fsdp_inference=False,  # set to True if GPU is out of memory
+        use_fsdp_inference=False, # set to True if GPU is out of memory
         dit_cpu_offload=False,
         vae_cpu_offload=True,
         text_encoder_cpu_offload=True,
         pin_cpu_memory=False,
         enable_bsa=False,
     )
-
+    
     output_path = "outputs_video/longcat_i2v_basic"
-
+    
     generator.generate_video(
         prompt=PROMPT,
         negative_prompt=NEGATIVE_PROMPT,
@@ -75,7 +79,7 @@ def basic_generation():
         guidance_scale=4.0,
         seed=SEED,
     )
-
+    
     print(f"\nBasic generation complete! Video saved to: {output_path}")
     generator.shutdown()
 
@@ -90,11 +94,11 @@ def distill_refine_generation():
     print("\n" + "=" * 60)
     print("LongCat I2V: Distill + Refine Pipeline")
     print("=" * 60)
-
+    
     # Stage 1: Distilled generation (16 steps at 480p)
     print("\n[Stage 1] Distilled generation (16 steps, 480p)")
     print("-" * 40)
-
+    
     generator = VideoGenerator.from_pretrained(
         "FastVideo/LongCat-Video-I2V-Diffusers",
         num_gpus=1,
@@ -107,9 +111,9 @@ def distill_refine_generation():
         lora_path="FastVideo/LongCat-Video-T2V-Distilled-LoRA",
         lora_nickname="distilled",
     )
-
+    
     distill_output_path = "outputs_video/longcat_i2v_distill"
-
+    
     generator.generate_video(
         prompt=PROMPT,
         negative_prompt=NEGATIVE_PROMPT,
@@ -124,14 +128,14 @@ def distill_refine_generation():
         guidance_scale=1.0,
         seed=SEED,
     )
-
+    
     print(f"Distilled generation complete! Video saved to: {distill_output_path}")
     generator.shutdown()
-
+    
     # Stage 2: Refinement (480p -> 768p)
     print("\n[Stage 2] Refinement (480p -> 768p with BSA)")
     print("-" * 40)
-
+    
     # Find the actual saved video file from stage 1
     video_files = glob.glob(os.path.join(distill_output_path, "*.mp4"))
     if not video_files:
@@ -139,7 +143,7 @@ def distill_refine_generation():
     # Use the most recently created video file
     distill_video_path = max(video_files, key=os.path.getmtime)
     print(f"Using stage 1 video: {distill_video_path}")
-
+    
     # Create a new generator with refinement LoRA and BSA enabled
     # Note: Refinement uses the T2V model (not I2V) since it's upscaling the generated video
     # For BSA [4, 4, 8]: latent must be divisible by 8
@@ -159,9 +163,9 @@ def distill_refine_generation():
         lora_path="FastVideo/LongCat-Video-T2V-Refinement-LoRA",
         lora_nickname="refinement",
     )
-
+    
     refine_output_path = "outputs_video/longcat_i2v_refine_720p"
-
+    
     refine_generator.generate_video(
         prompt=PROMPT,
         negative_prompt=NEGATIVE_PROMPT,
@@ -178,7 +182,7 @@ def distill_refine_generation():
         guidance_scale=1.0,
         seed=SEED,
     )
-
+    
     print(f"Refinement complete! Video saved to: {refine_output_path}")
     refine_generator.shutdown()
 
@@ -188,13 +192,13 @@ def main():
     print("\n" + "=" * 60)
     print("LongCat Image-to-Video Example")
     print("=" * 60 + "\n")
-
+    
     # Run basic generation
     basic_generation()
-
+    
     # Run distill+refine pipeline
     distill_refine_generation()
-
+    
     print("\n" + "=" * 60)
     print("All generations complete!")
     print("=" * 60)
@@ -202,3 +206,5 @@ def main():
 
 if __name__ == "__main__":
     main()
+
+

examples/inference/basic/basic_longcat_t2v.py

@@ -15,18 +15,22 @@ import os
 from fastvideo import VideoGenerator
 
 # Common prompts and settings matching the shell script examples
-PROMPT = ("In a realistic photography style, a white boy around seven or eight years old "
-          "sits on a park bench, wearing a light blue T-shirt, denim shorts, and white sneakers. "
-          "He holds an ice cream cone with vanilla and chocolate flavors, and beside him is a "
-          "medium-sized golden Labrador. Smiling, the boy offers the ice cream to the dog, "
-          "who eagerly licks it with its tongue. The sun is shining brightly, and the background "
-          "features a green lawn and several tall trees, creating a warm and loving scene.")
+PROMPT = (
+    "In a realistic photography style, a white boy around seven or eight years old "
+    "sits on a park bench, wearing a light blue T-shirt, denim shorts, and white sneakers. "
+    "He holds an ice cream cone with vanilla and chocolate flavors, and beside him is a "
+    "medium-sized golden Labrador. Smiling, the boy offers the ice cream to the dog, "
+    "who eagerly licks it with its tongue. The sun is shining brightly, and the background "
+    "features a green lawn and several tall trees, creating a warm and loving scene."
+)
 
-NEGATIVE_PROMPT = ("Bright tones, overexposed, static, blurred details, subtitles, style, works, "
-                   "paintings, images, static, overall gray, worst quality, low quality, JPEG compression "
-                   "residue, ugly, incomplete, extra fingers, poorly drawn hands, poorly drawn faces, "
-                   "deformed, disfigured, misshapen limbs, fused fingers, still picture, messy background, "
-                   "three legs, many people in the background, walking backwards")
+NEGATIVE_PROMPT = (
+    "Bright tones, overexposed, static, blurred details, subtitles, style, works, "
+    "paintings, images, static, overall gray, worst quality, low quality, JPEG compression "
+    "residue, ugly, incomplete, extra fingers, poorly drawn hands, poorly drawn faces, "
+    "deformed, disfigured, misshapen limbs, fused fingers, still picture, messy background, "
+    "three legs, many people in the background, walking backwards"
+)
 
 SEED = 42
 
@@ -40,20 +44,20 @@ def basic_generation():
     print("=" * 60)
     print("LongCat T2V: Basic Generation (50 steps, 480p)")
     print("=" * 60)
-
+    
     generator = VideoGenerator.from_pretrained(
         "FastVideo/LongCat-Video-T2V-Diffusers",
         num_gpus=1,
-        use_fsdp_inference=False,  # set to True if GPU is out of memory
+        use_fsdp_inference=False, # set to True if GPU is out of memory
         dit_cpu_offload=False,
         vae_cpu_offload=True,
         text_encoder_cpu_offload=True,
         pin_cpu_memory=False,
         enable_bsa=False,
     )
-
+    
     output_path = "outputs_video/longcat_t2v_basic"
-
+    
     generator.generate_video(
         prompt=PROMPT,
         negative_prompt=NEGATIVE_PROMPT,
@@ -67,7 +71,7 @@ def basic_generation():
         guidance_scale=4.0,
         seed=SEED,
     )
-
+    
     print(f"\nBasic generation complete! Video saved to: {output_path}")
     generator.shutdown()
 
@@ -82,11 +86,11 @@ def distill_refine_generation():
     print("\n" + "=" * 60)
     print("LongCat T2V: Distill + Refine Pipeline")
     print("=" * 60)
-
+    
     # Stage 1: Distilled generation (16 steps at 480p)
     print("\n[Stage 1] Distilled generation (16 steps, 480p)")
     print("-" * 40)
-
+    
     generator = VideoGenerator.from_pretrained(
         "FastVideo/LongCat-Video-T2V-Diffusers",
         num_gpus=1,
@@ -99,9 +103,9 @@ def distill_refine_generation():
         lora_path="FastVideo/LongCat-Video-T2V-Distilled-LoRA",
         lora_nickname="distilled",
     )
-
+    
     distill_output_path = "outputs_video/longcat_t2v_distill"
-
+    
     generator.generate_video(
         prompt=PROMPT,
         negative_prompt=NEGATIVE_PROMPT,
@@ -115,14 +119,14 @@ def distill_refine_generation():
         guidance_scale=1.0,
         seed=SEED,
     )
-
+    
     print(f"Distilled generation complete! Video saved to: {distill_output_path}")
     generator.shutdown()
-
+    
     # Stage 2: Refinement (480p -> 720p)
     print("\n[Stage 2] Refinement (480p -> 720p with BSA)")
     print("-" * 40)
-
+    
     # Find the actual saved video file from stage 1
     video_files = glob.glob(os.path.join(distill_output_path, "*.mp4"))
     if not video_files:
@@ -130,7 +134,7 @@ def distill_refine_generation():
     # Use the most recently created video file
     distill_video_path = max(video_files, key=os.path.getmtime)
     print(f"Using stage 1 video: {distill_video_path}")
-
+    
     # Create a new generator with refinement LoRA and BSA enabled
     refine_generator = VideoGenerator.from_pretrained(
         "FastVideo/LongCat-Video-T2V-Diffusers",
@@ -147,9 +151,9 @@ def distill_refine_generation():
         lora_path="FastVideo/LongCat-Video-T2V-Refinement-LoRA",
         lora_nickname="refinement",
     )
-
+    
     refine_output_path = "outputs_video/longcat_t2v_refine_720p"
-
+    
     refine_generator.generate_video(
         prompt=PROMPT,
         negative_prompt=NEGATIVE_PROMPT,
@@ -166,7 +170,7 @@ def distill_refine_generation():
         guidance_scale=1.0,
         seed=SEED,
     )
-
+    
     print(f"Refinement complete! Video saved to: {refine_output_path}")
     refine_generator.shutdown()
 
@@ -176,13 +180,13 @@ def main():
     print("\n" + "=" * 60)
     print("LongCat Text-to-Video Example")
     print("=" * 60 + "\n")
-
+    
     # Run basic generation
     basic_generation()
-
+    
     # Run distill+refine pipeline
     distill_refine_generation()
-
+    
     print("\n" + "=" * 60)
     print("All generations complete!")
     print("=" * 60)
@@ -190,3 +194,5 @@ def main():
 
 if __name__ == "__main__":
     main()
+
+

examples/inference/basic/basic_longcat_vc.py

@@ -21,17 +21,21 @@ import os
 from fastvideo import VideoGenerator
 
 # Common prompts and settings matching the shell script examples
-PROMPT = ("A person rides a motorcycle along a long, straight road that stretches between "
-          "a body of water and a forested hillside. The rider steadily accelerates, keeping "
-          "the motorcycle centered between the guardrails, while the scenery passes by on "
-          "both sides. The video captures the journey from the rider's perspective, emphasizing "
-          "the sense of motion and adventure.")
+PROMPT = (
+    "A person rides a motorcycle along a long, straight road that stretches between "
+    "a body of water and a forested hillside. The rider steadily accelerates, keeping "
+    "the motorcycle centered between the guardrails, while the scenery passes by on "
+    "both sides. The video captures the journey from the rider's perspective, emphasizing "
+    "the sense of motion and adventure."
+)
 
-NEGATIVE_PROMPT = ("Bright tones, overexposed, static, blurred details, subtitles, style, works, "
-                   "paintings, images, static, overall gray, worst quality, low quality, JPEG compression "
-                   "residue, ugly, incomplete, extra fingers, poorly drawn hands, poorly drawn faces, "
-                   "deformed, disfigured, misshapen limbs, fused fingers, still picture, messy background, "
-                   "three legs, many people in the background, walking backwards")
+NEGATIVE_PROMPT = (
+    "Bright tones, overexposed, static, blurred details, subtitles, style, works, "
+    "paintings, images, static, overall gray, worst quality, low quality, JPEG compression "
+    "residue, ugly, incomplete, extra fingers, poorly drawn hands, poorly drawn faces, "
+    "deformed, disfigured, misshapen limbs, fused fingers, still picture, messy background, "
+    "three legs, many people in the background, walking backwards"
+)
 
 # Input video path
 VIDEO_PATH = "assets/motorcycle.mp4"
@@ -51,25 +55,27 @@ def basic_generation():
     print("=" * 60)
     print("LongCat VC: Basic Generation (50 steps, 480p)")
     print("=" * 60)
-
+    
     # Check if video exists
     if not os.path.exists(VIDEO_PATH):
-        raise FileNotFoundError(f"Video not found at {VIDEO_PATH}. "
-                                "Please provide a valid video path.")
-
+        raise FileNotFoundError(
+            f"Video not found at {VIDEO_PATH}. "
+            "Please provide a valid video path."
+        )
+    
     generator = VideoGenerator.from_pretrained(
         "FastVideo/LongCat-Video-VC-Diffusers",
         num_gpus=1,
-        use_fsdp_inference=False,  # set to True if GPU is out of memory
+        use_fsdp_inference=False, # set to True if GPU is out of memory
         dit_cpu_offload=False,
         vae_cpu_offload=True,
         text_encoder_cpu_offload=True,
         pin_cpu_memory=False,
         enable_bsa=False,
     )
-
+    
     output_path = "outputs_video/longcat_vc_basic"
-
+    
     generator.generate_video(
         prompt=PROMPT,
         negative_prompt=NEGATIVE_PROMPT,
@@ -85,7 +91,7 @@ def basic_generation():
         guidance_scale=4.0,
         seed=SEED,
     )
-
+    
     print(f"\nBasic generation complete! Video saved to: {output_path}")
     generator.shutdown()
 
@@ -100,16 +106,18 @@ def distill_refine_generation():
     print("\n" + "=" * 60)
     print("LongCat VC: Distill + Refine Pipeline")
     print("=" * 60)
-
+    
     # Check if video exists
     if not os.path.exists(VIDEO_PATH):
-        raise FileNotFoundError(f"Video not found at {VIDEO_PATH}. "
-                                "Please provide a valid video path.")
-
+        raise FileNotFoundError(
+            f"Video not found at {VIDEO_PATH}. "
+            "Please provide a valid video path."
+        )
+    
     # Stage 1: Distilled generation (16 steps at 480p)
     print("\n[Stage 1] Distilled generation (16 steps, 480p)")
     print("-" * 40)
-
+    
     generator = VideoGenerator.from_pretrained(
         "FastVideo/LongCat-Video-VC-Diffusers",
         num_gpus=1,
@@ -122,9 +130,9 @@ def distill_refine_generation():
         lora_path="FastVideo/LongCat-Video-T2V-Distilled-LoRA",
         lora_nickname="distilled",
     )
-
+    
     distill_output_path = "outputs_video/longcat_vc_distill"
-
+    
     generator.generate_video(
         prompt=PROMPT,
         negative_prompt=NEGATIVE_PROMPT,
@@ -140,14 +148,14 @@ def distill_refine_generation():
         guidance_scale=1.0,
         seed=SEED,
     )
-
+    
     print(f"Distilled generation complete! Video saved to: {distill_output_path}")
     generator.shutdown()
-
+    
     # Stage 2: Refinement (480p -> 720p)
     print("\n[Stage 2] Refinement (480p -> 720p with BSA)")
     print("-" * 40)
-
+    
     # Find the actual saved video file from stage 1
     video_files = glob.glob(os.path.join(distill_output_path, "*.mp4"))
     if not video_files:
@@ -155,7 +163,7 @@ def distill_refine_generation():
     # Use the most recently created video file
     distill_video_path = max(video_files, key=os.path.getmtime)
     print(f"Using stage 1 video: {distill_video_path}")
-
+    
     # Create a new generator with refinement LoRA and BSA enabled
     # Note: Refinement uses the T2V model (not VC) since it's upscaling the generated video
     refine_generator = VideoGenerator.from_pretrained(
@@ -173,9 +181,9 @@ def distill_refine_generation():
         lora_path="FastVideo/LongCat-Video-T2V-Refinement-LoRA",
         lora_nickname="refinement",
     )
-
+    
     refine_output_path = "outputs_video/longcat_vc_refine_720p"
-
+    
     refine_generator.generate_video(
         prompt=PROMPT,
         negative_prompt=NEGATIVE_PROMPT,
@@ -192,7 +200,7 @@ def distill_refine_generation():
         guidance_scale=1.0,
         seed=SEED,
     )
-
+    
     print(f"Refinement complete! Video saved to: {refine_output_path}")
     refine_generator.shutdown()
 
@@ -202,13 +210,13 @@ def main():
     print("\n" + "=" * 60)
     print("LongCat Video Continuation Example")
     print("=" * 60 + "\n")
-
+    
     # Run basic generation
     basic_generation()
-
+    
     # Run distill+refine pipeline
     distill_refine_generation()
-
+    
     print("\n" + "=" * 60)
     print("All generations complete!")
     print("=" * 60)
@@ -216,3 +224,5 @@ def main():
 
 if __name__ == "__main__":
     main()
+
+

examples/inference/basic/basic_ltx2.py

@@ -1,16 +1,19 @@
 from fastvideo import VideoGenerator
 
-PROMPT = ("A warm sunny backyard. The camera starts in a tight cinematic close-up "
-          "of a woman and a man in their 30s, facing each other with serious "
-          "expressions. The woman, emotional and dramatic, says softly, \"That's "
-          "it... Dad's lost it. And we've lost Dad.\" The man exhales, slightly "
-          "annoyed: \"Stop being so dramatic, Jess.\" A beat. He glances aside, "
-          "then mutters defensively, \"He's just having fun.\" The camera slowly "
-          "pans right, revealing the grandfather in the garden wearing enormous "
-          "butterfly wings, waving his arms in the air like he's trying to take "
-          "off. He shouts, \"Wheeeew!\" as he flaps his wings with full commitment. "
-          "The woman covers her face, on the verge of tears. The tone is deadpan, "
-          "absurd, and quietly tragic.")
+
+PROMPT = (
+    "A warm sunny backyard. The camera starts in a tight cinematic close-up "
+    "of a woman and a man in their 30s, facing each other with serious "
+    "expressions. The woman, emotional and dramatic, says softly, \"That's "
+    "it... Dad's lost it. And we've lost Dad.\" The man exhales, slightly "
+    "annoyed: \"Stop being so dramatic, Jess.\" A beat. He glances aside, "
+    "then mutters defensively, \"He's just having fun.\" The camera slowly "
+    "pans right, revealing the grandfather in the garden wearing enormous "
+    "butterfly wings, waving his arms in the air like he's trying to take "
+    "off. He shouts, \"Wheeeew!\" as he flaps his wings with full commitment. "
+    "The woman covers her face, on the verge of tears. The tone is deadpan, "
+    "absurd, and quietly tragic."
+)
 
 
 def main() -> None:
@@ -33,4 +36,4 @@ def main() -> None:
 
 
 if __name__ == "__main__":
-    main()
+    main()

examples/inference/basic/basic_ltx2_3_distilled_i2v.py

@@ -67,19 +67,25 @@ _inductor.coordinate_descent_tuning = True
 _inductor.coordinate_descent_check_all_directions = True
 _inductor.epilogue_fusion = False
 
-MODEL_ID = os.path.expandvars(os.path.expanduser(os.getenv("LTX23_MODEL_PATH",
-                                                           "FastVideo/LTX-2.3-Distilled-Diffusers")))
-OUTPUT_DIR = Path(os.getenv("LTX23_OUTPUT_DIR", "outputs_video/ltx2_3_distilled_i2v"))
+MODEL_ID = os.path.expandvars(
+    os.path.expanduser(
+        os.getenv("LTX23_MODEL_PATH", "FastVideo/LTX-2.3-Distilled-Diffusers")
+    )
+)
+OUTPUT_DIR = Path(
+    os.getenv("LTX23_OUTPUT_DIR", "outputs_video/ltx2_3_distilled_i2v")
+)
 I2V_IMAGE = os.getenv("LTX23_I2V_IMAGE", "")
-DEFAULT_PROMPT = ("A fashion model takes a slow step forward and shifts her weight, "
-                  "the soft fabric of her clothing swaying and rippling with the "
-                  "motion, her hair shifting gently, soft even studio lighting on a "
-                  "clean light background, elegant slow-motion runway feel.")
+DEFAULT_PROMPT = (
+    "A fashion model takes a slow step forward and shifts her weight, "
+    "the soft fabric of her clothing swaying and rippling with the "
+    "motion, her hair shifting gently, soft even studio lighting on a "
+    "clean light background, elegant slow-motion runway feel."
+)
 PROMPT = os.getenv("LTX23_I2V_PROMPT", DEFAULT_PROMPT)
 
 # Per-stage timing helpers --------------------------------------------------
 
-
 def _print_stage_breakdown(result: dict, label: str) -> float | None:
     """Print stage execution times and return the sum, or None if missing."""
     logging_info = result.get("logging_info")
@@ -108,7 +114,9 @@ def _collect_stage_times(
         return
     for name, metrics in stages.items():
         stage_order.setdefault(name, None)
-        stage_times.setdefault(name, []).append(float(metrics.get("execution_time", 0.0)))
+        stage_times.setdefault(name, []).append(
+            float(metrics.get("execution_time", 0.0))
+        )
 
 
 def _resolve_refine_upsampler(model_root: str) -> Path:
@@ -117,18 +125,21 @@ def _resolve_refine_upsampler(model_root: str) -> Path:
         cand = Path(model_root) / name
         if (cand / "config.json").is_file():
             return cand
-    raise FileNotFoundError(f"No refine upsampler directory under {model_root}. "
-                            f"Expected `{model_root}/spatial_upscaler/config.json`.")
+    raise FileNotFoundError(
+        f"No refine upsampler directory under {model_root}. "
+        f"Expected `{model_root}/spatial_upscaler/config.json`."
+    )
 
 
 # Main ---------------------------------------------------------------------
 
-
 def main() -> None:
     if not I2V_IMAGE:
-        raise SystemExit("LTX23_I2V_IMAGE is required for i2v. Example:\n"
-                         "  export LTX23_I2V_IMAGE=/path/to/portrait_or_product.jpg\n"
-                         "  python examples/inference/basic/basic_ltx2_3_distilled_i2v.py")
+        raise SystemExit(
+            "LTX23_I2V_IMAGE is required for i2v. Example:\n"
+            "  export LTX23_I2V_IMAGE=/path/to/portrait_or_product.jpg\n"
+            "  python examples/inference/basic/basic_ltx2_3_distilled_i2v.py"
+        )
     if not Path(I2V_IMAGE).is_file():
         raise SystemExit(f"LTX23_I2V_IMAGE not found: {I2V_IMAGE}")
 
@@ -190,13 +201,11 @@ def main() -> None:
 
     common_kwargs = dict(
         prompt=PROMPT,
-        negative_prompt="",  # distilled is CFG-free; no negative needed
-        guidance_scale=1.0,  # CFG=1 for distilled
-        height=1280,
-        width=832,  # portrait runway aspect
-        num_frames=121,
-        fps=24,  # ~5s clip
-        num_inference_steps=8,  # distilled denoise steps
+        negative_prompt="",         # distilled is CFG-free; no negative needed
+        guidance_scale=1.0,         # CFG=1 for distilled
+        height=1280, width=832,     # portrait runway aspect
+        num_frames=121, fps=24,     # ~5s clip
+        num_inference_steps=8,      # distilled denoise steps
         # i2v: anchor the input image at frame 0 with full strength.
         # `ltx2_image_crf=0.0` skips an extra JPEG re-encode of an already
         # JPEG conditioning image.
@@ -242,7 +251,10 @@ def main() -> None:
                 **common_kwargs,
             )
             wall = time.perf_counter() - t0
-            e2e = (result.get("e2e_latency") if isinstance(result, dict) else None) or wall
+            e2e = (
+                result.get("e2e_latency")
+                if isinstance(result, dict) else None
+            ) or wall
             measured_secs.append(e2e)
             print(f"[measured {m + 1}/{measured_runs}] e2e={e2e:.2f}s wall={wall:.2f}s")
             if isinstance(result, dict):
@@ -254,8 +266,10 @@ def main() -> None:
         print(f"warmup wall-times:      {[round(x, 1) for x in warmup_secs]}")
         if measured_secs:
             avg = sum(measured_secs) / len(measured_secs)
-            print(f"measured e2e (n={len(measured_secs)}): "
-                  f"{[round(x, 2) for x in measured_secs]} -> avg {avg:.2f}s")
+            print(
+                f"measured e2e (n={len(measured_secs)}): "
+                f"{[round(x, 2) for x in measured_secs]} -> avg {avg:.2f}s"
+            )
         if stage_times:
             print(f"average stage times over {measured_runs} measured runs:")
             avg_total = 0.0

examples/inference/basic/basic_ltx2_3_distilled_i2v_typed.py

@@ -100,14 +100,23 @@ _inductor.coordinate_descent_tuning = True
 _inductor.coordinate_descent_check_all_directions = True
 _inductor.epilogue_fusion = False
 
-MODEL_ID = os.path.expandvars(os.path.expanduser(os.getenv("LTX23_MODEL_PATH",
-                                                           "FastVideo/LTX-2.3-Distilled-Diffusers")))
-OUTPUT_DIR = Path(os.getenv("LTX23_OUTPUT_DIR", "outputs_video/ltx2_3_distilled_i2v_typed"))
+MODEL_ID = os.path.expandvars(
+    os.path.expanduser(
+        os.getenv("LTX23_MODEL_PATH", "FastVideo/LTX-2.3-Distilled-Diffusers")
+    )
+)
+OUTPUT_DIR = Path(
+    os.getenv(
+        "LTX23_OUTPUT_DIR", "outputs_video/ltx2_3_distilled_i2v_typed"
+    )
+)
 I2V_IMAGE = os.getenv("LTX23_I2V_IMAGE", "")
-DEFAULT_PROMPT = ("A fashion model takes a slow step forward and shifts her weight, "
-                  "the soft fabric of her clothing swaying and rippling with the "
-                  "motion, her hair shifting gently, soft even studio lighting on a "
-                  "clean light background, elegant slow-motion runway feel.")
+DEFAULT_PROMPT = (
+    "A fashion model takes a slow step forward and shifts her weight, "
+    "the soft fabric of her clothing swaying and rippling with the "
+    "motion, her hair shifting gently, soft even studio lighting on a "
+    "clean light background, elegant slow-motion runway feel."
+)
 PROMPT = os.getenv("LTX23_I2V_PROMPT", DEFAULT_PROMPT)
 
 
@@ -138,7 +147,9 @@ def _collect_stage_times(
         return
     for name, metrics in stages.items():
         stage_order.setdefault(name, None)
-        stage_times.setdefault(name, []).append(float(metrics.get("execution_time", 0.0)))
+        stage_times.setdefault(name, []).append(
+            float(metrics.get("execution_time", 0.0))
+        )
 
 
 def _resolve_refine_upsampler(model_root: str) -> Path:
@@ -146,16 +157,20 @@ def _resolve_refine_upsampler(model_root: str) -> Path:
         cand = Path(model_root) / name
         if (cand / "config.json").is_file():
             return cand
-    raise FileNotFoundError(f"No refine upsampler directory under {model_root}. "
-                            f"Expected `{model_root}/spatial_upscaler/config.json`.")
+    raise FileNotFoundError(
+        f"No refine upsampler directory under {model_root}. "
+        f"Expected `{model_root}/spatial_upscaler/config.json`."
+    )
 
 
 def main() -> None:
     if not I2V_IMAGE:
-        raise SystemExit("LTX23_I2V_IMAGE is required for i2v. Example:\n"
-                         "  export LTX23_I2V_IMAGE=/path/to/portrait_or_product.jpg\n"
-                         "  python examples/inference/basic/"
-                         "basic_ltx2_3_distilled_i2v_typed.py")
+        raise SystemExit(
+            "LTX23_I2V_IMAGE is required for i2v. Example:\n"
+            "  export LTX23_I2V_IMAGE=/path/to/portrait_or_product.jpg\n"
+            "  python examples/inference/basic/"
+            "basic_ltx2_3_distilled_i2v_typed.py"
+        )
     if not Path(I2V_IMAGE).is_file():
         raise SystemExit(f"LTX23_I2V_IMAGE not found: {I2V_IMAGE}")
 
@@ -205,9 +220,10 @@ def main() -> None:
             # model-specific VAE precision / decoder defaults are picked up
             # the same way the legacy example's
             # ``PipelineConfig.from_pretrained(model_root)`` did them.
-            components=ComponentConfig(upsampler_weights=str(refine_upsampler_path),
-                                       # Distilled has no refine LoRA — omit ``lora_path``.
-                                       ),
+            components=ComponentConfig(
+                upsampler_weights=str(refine_upsampler_path),
+                # Distilled has no refine LoRA — omit ``lora_path``.
+            ),
             vae_tiling=False,
             preset_overrides={
                 "refine": {
@@ -262,7 +278,11 @@ def main() -> None:
         for w in range(warmup_runs):
             print(f"\n[warmup {w + 1}/{warmup_runs}] compiling + generating…")
             t0 = time.perf_counter()
-            generator.generate(build_request(OUTPUT_DIR / f"_warmup_{w + 1}.mp4", seed=7))
+            generator.generate(
+                build_request(
+                    OUTPUT_DIR / f"_warmup_{w + 1}.mp4", seed=7
+                )
+            )
             dt = time.perf_counter() - t0
             warmup_secs.append(dt)
             print(f"[warmup {w + 1}/{warmup_runs}] wall={dt:.1f}s")
@@ -271,30 +291,46 @@ def main() -> None:
             (OUTPUT_DIR / f"_warmup_{w + 1}.mp4").unlink(missing_ok=True)
 
         for m in range(measured_runs):
-            out_path = (OUTPUT_DIR / f"output_ltx2_3_distilled_i2v_typed_run_{m + 1}.mp4")
-            print(f"\n[measured {m + 1}/{measured_runs}] generating: {out_path}")
+            out_path = (
+                OUTPUT_DIR
+                / f"output_ltx2_3_distilled_i2v_typed_run_{m + 1}.mp4"
+            )
+            print(
+                f"\n[measured {m + 1}/{measured_runs}] generating: {out_path}"
+            )
             t0 = time.perf_counter()
-            result = generator.generate(build_request(out_path, seed=2002 + m))
+            result = generator.generate(
+                build_request(out_path, seed=2002 + m)
+            )
             wall = time.perf_counter() - t0
             # ``e2e_latency`` is currently surfaced via ``result.extra``;
             # ``GenerationResult`` exposes ``generation_time`` as a
             # first-class field but the LTX-2 pipeline only fills the
             # legacy ``e2e_latency`` key. Prefer the explicit one, fall
             # back to wall-clock.
-            e2e = (result.extra.get("e2e_latency") if hasattr(result, "extra") else None) or wall
+            e2e = (
+                result.extra.get("e2e_latency")
+                if hasattr(result, "extra") else None
+            ) or wall
             measured_secs.append(e2e)
-            print(f"[measured {m + 1}/{measured_runs}] "
-                  f"e2e={e2e:.2f}s wall={wall:.2f}s")
+            print(
+                f"[measured {m + 1}/{measured_runs}] "
+                f"e2e={e2e:.2f}s wall={wall:.2f}s"
+            )
             _print_stage_breakdown(result, f"measured {m + 1}")
             _collect_stage_times(result, stage_times, stage_order)
 
         print("\n=== summary ===")
-        print(f"warmup wall-times:      "
-              f"{[round(x, 1) for x in warmup_secs]}")
+        print(
+            f"warmup wall-times:      "
+            f"{[round(x, 1) for x in warmup_secs]}"
+        )
         if measured_secs:
             avg = sum(measured_secs) / len(measured_secs)
-            print(f"measured e2e (n={len(measured_secs)}): "
-                  f"{[round(x, 2) for x in measured_secs]} -> avg {avg:.2f}s")
+            print(
+                f"measured e2e (n={len(measured_secs)}): "
+                f"{[round(x, 2) for x in measured_secs]} -> avg {avg:.2f}s"
+            )
         if stage_times:
             print(f"average stage times over {measured_runs} measured runs:")
             avg_total = 0.0

examples/inference/basic/basic_ltx2_5.py

@@ -1,103 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-"""LTX-2.5 (sft/base) text-to-video from a single-file bundle.
-
-Loads LTX-2.5 from a single-file bundle: ONE ``.safetensors`` file carrying
-every component (transformer, video VAE, audio VAE, vocoder, text
-projection), so ``--model-path`` takes the bundle FILE, not a repo
-directory. (The split-pack Hugging Face release loads through the standard
-repo path instead.)
-
-The Gemma text encoder is NOT in the bundle: pass its root directory with
-``--gemma-root`` (or set ``FASTVIDEO_LTX_ENCODER_ROOT``). Use the encoder
-root shipped WITH this transformer variant -- the published roots share
-weights but differ in prompt templating, so a mismatched root silently
-changes prompting.
-
-A non-distilled bundle resolves to the standard ``ltx2_base`` preset
-(40 steps, CFG 3.0 with STG); run without sampling flags to use it as-is.
-For the 8-step distilled recipe, see ``basic_ltx2_5_distilled.py``.
-
-Audio: the bundle carries an audio VAE + vocoder, so generated videos get
-an audio track. A bundle that declares no audio decoder skips audio
-decoding and still produces video.
-
-Decoder caveat: bundles that declare a *diffusion* VAE decoder
-(``CausalDiffusionVAE``) are not implemented yet -- loading such a bundle
-currently fails at VAE build time with an unsupported-architecture error
-(no classic-decoder fallback is wired). Bundles with the classic
-``CausalVideoAutoencoder`` decode end to end.
-"""
-import argparse
-import os
-
-from fastvideo import VideoGenerator
-
-PROMPT = ("A warm sunny backyard. The camera starts in a tight cinematic close-up "
-          "of a woman and a man in their 30s, facing each other with serious "
-          "expressions. The woman, emotional and dramatic, says softly, \"That's "
-          "it... Dad's lost it. And we've lost Dad.\" The man exhales, slightly "
-          "annoyed: \"Stop being so dramatic, Jess.\" A beat. He glances aside, "
-          "then mutters defensively, \"He's just having fun.\" The camera slowly "
-          "pans right, revealing the grandfather in the garden wearing enormous "
-          "butterfly wings, waving his arms in the air like he's trying to take "
-          "off. He shouts, \"Wheeeew!\" as he flaps his wings with full commitment. "
-          "The woman covers her face, on the verge of tears. The tone is deadpan, "
-          "absurd, and quietly tragic.")
-
-# Sampling flags default to None: unset flags are NOT passed to
-# `generate_video`, so the bundle's preset supplies them via
-# `SamplingParam.from_pretrained` (ltx2_base: 40 steps, cfg 3.0, 512x768,
-# 121 frames).
-_SAMPLING_FLAGS = ("height", "width", "num_frames", "num_inference_steps", "guidance_scale", "seed")
-
-
-def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
-    parser = argparse.ArgumentParser(description="LTX-2.5 (sft/base) inference from a single-file bundle.")
-    parser.add_argument(
-        "--model-path",
-        required=True,
-        help="Path to the LTX-2.5 bundle (.safetensors FILE).",
-    )
-    parser.add_argument(
-        "--gemma-root",
-        default=None,
-        help="Gemma text-encoder root directory. Must be the root paired with "
-        "this transformer variant; the roots differ in prompt templating.",
-    )
-    parser.add_argument("--prompt", default=PROMPT)
-    parser.add_argument("--output-path", default="outputs_video/ltx2_5/output_ltx2_5_t2v.mp4")
-    parser.add_argument("--num-gpus", type=int, default=1)
-    parser.add_argument("--height", type=int, default=None)
-    parser.add_argument("--width", type=int, default=None)
-    parser.add_argument("--num-frames", type=int, default=None)
-    parser.add_argument("--num-inference-steps", type=int, default=None)
-    parser.add_argument("--guidance-scale", type=float, default=None)
-    parser.add_argument("--seed", type=int, default=None)
-    return parser.parse_args(argv)
-
-
-def sampling_overrides(args: argparse.Namespace) -> dict:
-    """Only sampling flags the user actually passed; the preset supplies the rest."""
-    return {name: getattr(args, name) for name in _SAMPLING_FLAGS if getattr(args, name) is not None}
-
-
-def main(argv: list[str] | None = None) -> None:
-    args = parse_args(argv)
-    if args.gemma_root:
-        os.environ["FASTVIDEO_LTX_ENCODER_ROOT"] = args.gemma_root
-
-    generator = VideoGenerator.from_pretrained(
-        args.model_path,
-        num_gpus=args.num_gpus,
-    )
-    generator.generate_video(
-        prompt=args.prompt,
-        output_path=args.output_path,
-        save_video=True,
-        **sampling_overrides(args),
-    )
-    generator.shutdown()
-
-
-if __name__ == "__main__":
-    main()

examples/inference/basic/basic_ltx2_5_distilled.py

@@ -1,104 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-"""LTX-2.5 distilled text-to-video from a single-file bundle.
-
-Loads LTX-2.5 from a single-file bundle: ONE ``.safetensors`` file carrying
-every component (transformer, video VAE, audio VAE, vocoder, text
-projection), so ``--model-path`` takes the bundle FILE, not a repo
-directory. (The split-pack Hugging Face release loads through the standard
-repo path instead.)
-
-The Gemma text encoder is NOT in the bundle: pass its root directory with
-``--gemma-root`` (or set ``FASTVIDEO_LTX_ENCODER_ROOT``). Use the encoder
-root shipped WITH this transformer variant -- the published roots share
-weights but differ in prompt templating, so a mismatched root silently
-changes prompting.
-
-Distilled recipe: ONE stage -- 8 steps on the distilled sigma schedule,
-CFG 1.0, no CFG/STG, and no spatial upscaler needed. All of it comes from
-the ``ltx2_distilled`` preset the bundle resolves to; run without sampling
-flags to use it as-is.
-
-Audio: the bundle carries an audio VAE + vocoder, so generated videos get
-an audio track. A bundle that declares no audio decoder skips audio
-decoding and still produces video.
-
-Decoder caveat: bundles that declare a *diffusion* VAE decoder
-(``CausalDiffusionVAE``) are not implemented yet -- loading such a bundle
-currently fails at VAE build time with an unsupported-architecture error
-(no classic-decoder fallback is wired). Bundles with the classic
-``CausalVideoAutoencoder`` decode end to end.
-"""
-import argparse
-import os
-
-from fastvideo import VideoGenerator
-
-PROMPT = ("A warm sunny backyard. The camera starts in a tight cinematic close-up "
-          "of a woman and a man in their 30s, facing each other with serious "
-          "expressions. The woman, emotional and dramatic, says softly, \"That's "
-          "it... Dad's lost it. And we've lost Dad.\" The man exhales, slightly "
-          "annoyed: \"Stop being so dramatic, Jess.\" A beat. He glances aside, "
-          "then mutters defensively, \"He's just having fun.\" The camera slowly "
-          "pans right, revealing the grandfather in the garden wearing enormous "
-          "butterfly wings, waving his arms in the air like he's trying to take "
-          "off. He shouts, \"Wheeeew!\" as he flaps his wings with full commitment. "
-          "The woman covers her face, on the verge of tears. The tone is deadpan, "
-          "absurd, and quietly tragic.")
-
-# Sampling flags default to None: unset flags are NOT passed to
-# `generate_video`, so the bundle's preset supplies them via
-# `SamplingParam.from_pretrained` (ltx2_distilled: 8 steps, cfg 1.0,
-# 1024x1536, 121 frames).
-_SAMPLING_FLAGS = ("height", "width", "num_frames", "num_inference_steps", "guidance_scale", "seed")
-
-
-def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
-    parser = argparse.ArgumentParser(description="LTX-2.5 distilled inference from a single-file bundle.")
-    parser.add_argument(
-        "--model-path",
-        required=True,
-        help="Path to the LTX-2.5 distilled bundle (.safetensors FILE).",
-    )
-    parser.add_argument(
-        "--gemma-root",
-        default=None,
-        help="Gemma text-encoder root directory. Must be the root paired with "
-        "this transformer variant; the roots differ in prompt templating.",
-    )
-    parser.add_argument("--prompt", default=PROMPT)
-    parser.add_argument("--output-path", default="outputs_video/ltx2_5/output_ltx2_5_distilled_t2v.mp4")
-    parser.add_argument("--num-gpus", type=int, default=1)
-    parser.add_argument("--height", type=int, default=None)
-    parser.add_argument("--width", type=int, default=None)
-    parser.add_argument("--num-frames", type=int, default=None)
-    parser.add_argument("--num-inference-steps", type=int, default=None)
-    parser.add_argument("--guidance-scale", type=float, default=None)
-    parser.add_argument("--seed", type=int, default=None)
-    return parser.parse_args(argv)
-
-
-def sampling_overrides(args: argparse.Namespace) -> dict:
-    """Only sampling flags the user actually passed; the preset supplies the rest."""
-    return {name: getattr(args, name) for name in _SAMPLING_FLAGS if getattr(args, name) is not None}
-
-
-def main(argv: list[str] | None = None) -> None:
-    args = parse_args(argv)
-    if args.gemma_root:
-        os.environ["FASTVIDEO_LTX_ENCODER_ROOT"] = args.gemma_root
-
-    generator = VideoGenerator.from_pretrained(
-        args.model_path,
-        num_gpus=args.num_gpus,
-    )
-    generator.generate_video(
-        prompt=args.prompt,
-        output_path=args.output_path,
-        save_video=True,
-        **sampling_overrides(args),
-    )
-    generator.shutdown()
-
-
-if __name__ == "__main__":
-    main()

examples/inference/basic/basic_ltx2_distilled.py

@@ -1,21 +1,21 @@
 from fastvideo import VideoGenerator
 
-PROMPT = ("A warm sunny backyard. The camera starts in a tight cinematic close-up "
-          "of a woman and a man in their 30s, facing each other with serious "
-          "expressions. The woman, emotional and dramatic, says softly, \"That's "
-          "it... Dad's lost it. And we've lost Dad.\" The man exhales, slightly "
-          "annoyed: \"Stop being so dramatic, Jess.\" A beat. He glances aside, "
-          "then mutters defensively, \"He's just having fun.\" The camera slowly "
-          "pans right, revealing the grandfather in the garden wearing enormous "
-          "butterfly wings, waving his arms in the air like he's trying to take "
-          "off. He shouts, \"Wheeeew!\" as he flaps his wings with full commitment. "
-          "The woman covers her face, on the verge of tears. The tone is deadpan, "
-          "absurd, and quietly tragic.")
+PROMPT = (
+    "A warm sunny backyard. The camera starts in a tight cinematic close-up "
+    "of a woman and a man in their 30s, facing each other with serious "
+    "expressions. The woman, emotional and dramatic, says softly, \"That's "
+    "it... Dad's lost it. And we've lost Dad.\" The man exhales, slightly "
+    "annoyed: \"Stop being so dramatic, Jess.\" A beat. He glances aside, "
+    "then mutters defensively, \"He's just having fun.\" The camera slowly "
+    "pans right, revealing the grandfather in the garden wearing enormous "
+    "butterfly wings, waving his arms in the air like he's trying to take "
+    "off. He shouts, \"Wheeeew!\" as he flaps his wings with full commitment. "
+    "The woman covers her face, on the verge of tears. The tone is deadpan, "
+    "absurd, and quietly tragic."
+)
 import os
-
 os.environ["FASTVIDEO_ATTENTION_BACKEND"] = "FLASH_ATTN"
 
-
 def main() -> None:
     generator = VideoGenerator.from_pretrained(
         "FastVideo/LTX2-Distilled-Diffusers",

examples/inference/basic/basic_ltx2_distilled_fast_profile.py

@@ -12,11 +12,15 @@ from fastvideo.configs.pipelines.base import PipelineConfig
 from fastvideo.layers.quantization.nvfp4_config import NVFP4Config
 from fastvideo.utils import maybe_download_model
 
-VALIDATION_JSON = (Path(__file__).resolve().parents[2] / "training" / "finetune" / "ltx2" / "validation.json")
+VALIDATION_JSON = (
+    Path(__file__).resolve().parents[2] / "training" / "finetune" / "ltx2" / "validation.json"
+)
 
 # Override with a local snapshot or converted directory when needed, e.g.
 #   export LTX2_MODEL_PATH=/raid/$USER/hf/FastVideo/LTX2-Distilled-Diffusers
-MODEL_ID = os.path.expandvars(os.path.expanduser(os.getenv("LTX2_MODEL_PATH", "FastVideo/LTX2-Distilled-Diffusers")))
+MODEL_ID = os.path.expandvars(
+    os.path.expanduser(os.getenv("LTX2_MODEL_PATH", "FastVideo/LTX2-Distilled-Diffusers"))
+)
 OUTPUT_DIR = Path("outputs_video/ltx2_distilled_fast_profile")
 
 os.environ["FASTVIDEO_ATTENTION_BACKEND"] = "FLASH_ATTN"
@@ -65,7 +69,9 @@ def print_stage_breakdown(
     return total
 
 
-def extract_sr_forward_latency(result: dict, ) -> tuple[float | None, list[tuple[str, float]], list[str]]:
+def extract_sr_forward_latency(
+    result: dict,
+) -> tuple[float | None, list[tuple[str, float]], list[str]]:
     logging_info = result.get("logging_info")
     if logging_info is None:
         return None, [], []
@@ -83,8 +89,12 @@ def extract_sr_forward_latency(result: dict, ) -> tuple[float | None, list[tuple
         if sr_match_substr:
             is_sr_stage = sr_match_substr in stage_name_l
         else:
-            is_sr_stage = ("srdenoisingstage" in stage_name_l or "sr_denoising" in stage_name_l
-                           or "upsample" in stage_name_l or ("refine" in stage_name_l and "denois" in stage_name_l))
+            is_sr_stage = (
+                "srdenoisingstage" in stage_name_l
+                or "sr_denoising" in stage_name_l
+                or "upsample" in stage_name_l
+                or ("refine" in stage_name_l and "denois" in stage_name_l)
+            )
         if not is_sr_stage:
             continue
         exec_time = float(stage_metrics.get("execution_time", 0.0))
@@ -151,9 +161,11 @@ def resolve_refine_upsampler_path(model_root: str) -> Path:
             return candidate
 
     checked = "\n".join(f"  - {candidate}" for candidate in candidates)
-    raise FileNotFoundError("Could not find an LTX2 refine upsampler directory.\n"
-                            "Checked:\n"
-                            f"{checked}")
+    raise FileNotFoundError(
+        "Could not find an LTX2 refine upsampler directory.\n"
+        "Checked:\n"
+        f"{checked}"
+    )
 
 
 def main() -> None:
@@ -302,15 +314,19 @@ def main() -> None:
 
         measured_times = run_times[measured_start_idx:]
         avg_time = sum(measured_times) / len(measured_times)
-        print(f"Average video generation time over {len(measured_times)} runs "
-              f"(runs {measured_start_idx + 1}-{len(run_times)}, skipping first {warmup_runs} warmup runs): "
-              f"{avg_time:.2f}s")
+        print(
+            f"Average video generation time over {len(measured_times)} runs "
+            f"(runs {measured_start_idx + 1}-{len(run_times)}, skipping first {warmup_runs} warmup runs): "
+            f"{avg_time:.2f}s"
+        )
 
         measured_e2e_times = e2e_times[measured_start_idx:]
         avg_e2e_time = sum(measured_e2e_times) / len(measured_e2e_times)
-        print(f"Average end-to-end latency over {len(measured_e2e_times)} runs "
-              f"(runs {measured_start_idx + 1}-{len(e2e_times)}, skipping first {warmup_runs} warmup runs): "
-              f"{avg_e2e_time:.2f}s")
+        print(
+            f"Average end-to-end latency over {len(measured_e2e_times)} runs "
+            f"(runs {measured_start_idx + 1}-{len(e2e_times)}, skipping first {warmup_runs} warmup runs): "
+            f"{avg_e2e_time:.2f}s"
+        )
 
         if sr_forward_times:
             avg_sr_forward = sum(sr_forward_times) / len(sr_forward_times)
@@ -322,8 +338,10 @@ def main() -> None:
 
         if non_stage_overhead_times:
             avg_non_stage_overhead = sum(non_stage_overhead_times) / len(non_stage_overhead_times)
-            print("Average non-stage overhead over "
-                  f"{len(non_stage_overhead_times)} measured runs: {avg_non_stage_overhead:.3f}s")
+            print(
+                "Average non-stage overhead over "
+                f"{len(non_stage_overhead_times)} measured runs: {avg_non_stage_overhead:.3f}s"
+            )
         else:
             print("Average non-stage overhead unavailable (no stage timings).")
     finally:

examples/inference/basic/basic_matrixgame2.py

@@ -13,34 +13,24 @@ MODEL_VARIANT = "base_distilled_model"
 # Variant-specific settings
 VARIANT_CONFIG = {
     "base_distilled_model": {
-        "model_path":
-        "FastVideo/Matrix-Game-2.0-Base-Distilled-Diffusers",
-        "keyboard_dim":
-        4,
-        "image_url":
-        "https://raw.githubusercontent.com/SkyworkAI/Matrix-Game/main/Matrix-Game-2/demo_images/universal/0000.png",
+        "model_path": "FastVideo/Matrix-Game-2.0-Base-Distilled-Diffusers",
+        "keyboard_dim": 4,
+        "image_url": "https://raw.githubusercontent.com/SkyworkAI/Matrix-Game/main/Matrix-Game-2/demo_images/universal/0000.png",
     },
     "gta_distilled_model": {
-        "model_path":
-        "FastVideo/Matrix-Game-2.0-GTA-Distilled-Diffusers",
-        "keyboard_dim":
-        2,
-        "image_url":
-        "https://raw.githubusercontent.com/SkyworkAI/Matrix-Game/main/Matrix-Game-2/demo_images/gta_drive/0000.png",
+        "model_path": "FastVideo/Matrix-Game-2.0-GTA-Distilled-Diffusers",
+        "keyboard_dim": 2,
+        "image_url": "https://raw.githubusercontent.com/SkyworkAI/Matrix-Game/main/Matrix-Game-2/demo_images/gta_drive/0000.png",
     },
     "templerun_distilled_model": {
-        "model_path":
-        "FastVideo/Matrix-Game-2.0-TempleRun-Distilled-Diffusers",
-        "keyboard_dim":
-        7,
-        "image_url":
-        "https://raw.githubusercontent.com/SkyworkAI/Matrix-Game/main/Matrix-Game-2/demo_images/temple_run/0000.png",
+        "model_path": "FastVideo/Matrix-Game-2.0-TempleRun-Distilled-Diffusers",
+        "keyboard_dim": 7,
+        "image_url": "https://raw.githubusercontent.com/SkyworkAI/Matrix-Game/main/Matrix-Game-2/demo_images/temple_run/0000.png",
     },
 }
 
+
 OUTPUT_PATH = "video_samples_matrixgame2"
-
-
 def main():
     # FastVideo will automatically use the optimal default arguments for the
     # model.
@@ -52,8 +42,8 @@ def main():
         config["model_path"],
         # FastVideo will automatically handle distributed setup
         num_gpus=1,
-        use_fsdp_inference=False,  # set to True if GPU is out of memory
-        dit_cpu_offload=True,  # DiT need to be offloaded for MoE
+        use_fsdp_inference=False, # set to True if GPU is out of memory
+        dit_cpu_offload=True, # DiT need to be offloaded for MoE
         vae_cpu_offload=False,
         text_encoder_cpu_offload=True,
         # Set pin_cpu_memory to false if CPU RAM is limited and there're no frequent CPU-GPU transfer

examples/inference/basic/basic_matrixgame2_streaming.py

@@ -14,40 +14,27 @@ MODEL_VARIANT = "base_distilled_model"
 # Variant-specific settings
 VARIANT_CONFIG = {
     "base_distilled_model": {
-        "model_path":
-        "FastVideo/Matrix-Game-2.0-Base-Distilled-Diffusers",
-        "keyboard_dim":
-        4,
-        "mode":
-        "universal",
-        "image_url":
-        "https://raw.githubusercontent.com/SkyworkAI/Matrix-Game/main/Matrix-Game-2/demo_images/universal/0000.png",
+        "model_path": "FastVideo/Matrix-Game-2.0-Base-Distilled-Diffusers",
+        "keyboard_dim": 4,
+        "mode": "universal",
+        "image_url": "https://raw.githubusercontent.com/SkyworkAI/Matrix-Game/main/Matrix-Game-2/demo_images/universal/0000.png",
     },
     "gta_distilled_model": {
-        "model_path":
-        "FastVideo/Matrix-Game-2.0-GTA-Distilled-Diffusers",
-        "keyboard_dim":
-        2,
-        "mode":
-        "gta_drive",
-        "image_url":
-        "https://raw.githubusercontent.com/SkyworkAI/Matrix-Game/main/Matrix-Game-2/demo_images/gta_drive/0000.png",
+        "model_path": "FastVideo/Matrix-Game-2.0-GTA-Distilled-Diffusers",
+        "keyboard_dim": 2,
+        "mode": "gta_drive",
+        "image_url": "https://raw.githubusercontent.com/SkyworkAI/Matrix-Game/main/Matrix-Game-2/demo_images/gta_drive/0000.png",
     },
     "templerun_distilled_model": {
-        "model_path":
-        "FastVideo/Matrix-Game-2.0-TempleRun-Distilled-Diffusers",
-        "keyboard_dim":
-        7,
-        "mode":
-        "templerun",
-        "image_url":
-        "https://raw.githubusercontent.com/SkyworkAI/Matrix-Game/main/Matrix-Game-2/demo_images/temple_run/0000.png",
+        "model_path": "FastVideo/Matrix-Game-2.0-TempleRun-Distilled-Diffusers",
+        "keyboard_dim": 7,
+        "mode": "templerun",
+        "image_url": "https://raw.githubusercontent.com/SkyworkAI/Matrix-Game/main/Matrix-Game-2/demo_images/temple_run/0000.png",
     },
 }
 
+
 OUTPUT_PATH = "video_samples_matrixgame2"
-
-
 async def main():
     # FastVideo will automatically use the optimal default arguments for the
     # model.
@@ -59,8 +46,8 @@ async def main():
         config["model_path"],
         # FastVideo will automatically handle distributed setup
         num_gpus=1,
-        use_fsdp_inference=False,  # set to True if GPU is out of memory
-        dit_cpu_offload=True,  # DiT need to be offloaded for MoE
+        use_fsdp_inference=False, # set to True if GPU is out of memory
+        dit_cpu_offload=True, # DiT need to be offloaded for MoE
         vae_cpu_offload=False,
         text_encoder_cpu_offload=True,
         # Set pin_cpu_memory to false if CPU RAM is limited and there're no frequent CPU-GPU transfer
@@ -69,8 +56,11 @@ async def main():
     )
 
     max_blocks = 50
-    num_frames = 597
-    actions = {"keyboard": torch.zeros((num_frames, config["keyboard_dim"])), "mouse": torch.zeros((num_frames, 2))}
+    num_frames = 597    
+    actions = {
+        "keyboard": torch.zeros((num_frames, config["keyboard_dim"])),
+        "mouse": torch.zeros((num_frames, 2))
+    }
     grid_sizes = torch.tensor([150, 44, 80])
     mode = config["mode"]
 
@@ -91,11 +81,11 @@ async def main():
 
     for block_id in range(max_blocks):
         print(f"\n=== Block {block_id + 1}/{max_blocks} ===")
-
+        
         action = await get_current_action_async(mode)
         keyboard_cond, mouse_cond = expand_action_to_frames(action, 12)
         await generator.step_async(keyboard_cond, mouse_cond)
-
+        
         if (await asyncio.to_thread(input, "\nContinue? (y/n): ")).lower() == 'n':
             break
 

examples/inference/basic/basic_minimax_h3_fl2va.py

@@ -25,12 +25,6 @@ from fastvideo.pipelines.basic.minimax_h3.packing import resolve_canvas_size
 def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--model-path", default="MiniMaxAI/MiniMax-H3")
-    # Rank-reduced AdaLN checkpoint (-39% params, -23 GiB VRAM): pass
-    #   --model-path noctuashap/MiniMax-H3-pruned-r16
-    # (or a local dir converted with tools/minimax_h3/fit_adaln_basis.py).
-    # adaln_rank is read from the checkpoint config; no other flags needed.
-    # Rank-reduced checkpoints are inference-only: training needs the
-    # full-rank release.
     parser.add_argument("--image", required=True, help="First-frame image path.")
     parser.add_argument("--last-image", help="Optional last-frame image path.")
     parser.add_argument("--output", default="outputs/minimax_h3_fl2va")

examples/inference/basic/basic_minimax_h3_ref2va.py

@@ -25,12 +25,6 @@ from fastvideo.pipelines.basic.minimax_h3 import MiniMaxH3Reference
 def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--model-path", default="MiniMaxAI/MiniMax-H3")
-    # Rank-reduced AdaLN checkpoint (-39% params, -23 GiB VRAM): pass
-    #   --model-path noctuashap/MiniMax-H3-pruned-r16
-    # (or a local dir converted with tools/minimax_h3/fit_adaln_basis.py).
-    # adaln_rank is read from the checkpoint config; no other flags needed.
-    # Rank-reduced checkpoints are inference-only: training needs the
-    # full-rank release.
     parser.add_argument("--reference-video", required=True)
     parser.add_argument("--reference-audio", help="Optional additional audio reference.")
     parser.add_argument("--output", default="outputs/minimax_h3_ref2va")

examples/inference/basic/basic_minimax_h3_t2v.py

@@ -22,12 +22,6 @@ from fastvideo.api import (
 def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--model-path", default="MiniMaxAI/MiniMax-H3")
-    # Rank-reduced AdaLN checkpoint (-39% params, -23 GiB VRAM): pass
-    #   --model-path noctuashap/MiniMax-H3-pruned-r16
-    # (or a local dir converted with tools/minimax_h3/fit_adaln_basis.py).
-    # adaln_rank is read from the checkpoint config; no other flags needed.
-    # Rank-reduced checkpoints are inference-only: training needs the
-    # full-rank release.
     parser.add_argument("--prompt", required=True)
     parser.add_argument("--output", default="outputs/minimax_h3_t2v")
     parser.add_argument("--height", type=int, default=768)
@@ -36,15 +30,13 @@ def parse_args() -> argparse.Namespace:
     parser.add_argument("--steps", type=int, default=50)
     parser.add_argument("--seed", type=int, default=0)
     parser.add_argument("--num-gpus", type=int, default=4)
-    parser.add_argument("--torch-compile", action="store_true", help="torch.compile the DiT transformer path")
-    parser.add_argument("--compile-mode",
-                        default=None,
+    parser.add_argument("--torch-compile", action="store_true",
+                        help="torch.compile the DiT transformer path")
+    parser.add_argument("--compile-mode", default=None,
                         help='torch.compile mode, e.g. "reduce-overhead" for CUDA graphs')
-    parser.add_argument("--repeats",
-                        type=int,
-                        default=1,
+    parser.add_argument("--repeats", type=int, default=1,
                         help="generate N times; with --torch-compile the first run pays "
-                        "compilation, so steady-state is the last repeat")
+                             "compilation, so steady-state is the last repeat")
     return parser.parse_args()
 
 
@@ -75,24 +67,24 @@ def main() -> None:
         ))
     try:
         request = GenerationRequest(
-            prompt=args.prompt,
-            negative_prompt="",
-            sampling=SamplingConfig(
-                height=args.height,
-                width=args.width,
-                num_frames=args.num_frames,
-                fps=24,
-                num_inference_steps=args.steps,
-                guidance_scale=1.0,
-                batch_cfg=False,
-                seed=args.seed,
-            ),
-            output=OutputConfig(
-                output_path=str(output_dir / "minimax_h3_t2v.mp4"),
-                save_video=True,
-                return_frames=False,
-            ),
-        )
+                prompt=args.prompt,
+                negative_prompt="",
+                sampling=SamplingConfig(
+                    height=args.height,
+                    width=args.width,
+                    num_frames=args.num_frames,
+                    fps=24,
+                    num_inference_steps=args.steps,
+                    guidance_scale=1.0,
+                    batch_cfg=False,
+                    seed=args.seed,
+                ),
+                output=OutputConfig(
+                    output_path=str(output_dir / "minimax_h3_t2v.mp4"),
+                    save_video=True,
+                    return_frames=False,
+                ),
+            )
         result = generator.generate(request)
         print(f"Output written to: {result.video_path}")
         if result.generation_time is not None:

examples/inference/basic/basic_mmaudio.py

@@ -1,44 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-"""MMAudio large-44k-v2 video-to-audio example."""
-
-import argparse
-import os
-
-from fastvideo import VideoGenerator
-
-
-def parse_args() -> argparse.Namespace:
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("--video-path", required=True)
-    parser.add_argument("--output-path", default="outputs_audio/mmaudio.wav")
-    parser.add_argument("--duration-seconds", type=float, default=8.0)
-    parser.add_argument("--prompt", default="")
-    parser.add_argument("--negative-prompt", default="music")
-    return parser.parse_args()
-
-
-def main() -> None:
-    args = parse_args()
-    generator = VideoGenerator.from_pretrained(
-        os.environ.get(
-            "MMAUDIO_MODEL_PATH",
-            "converted_weights/mmaudio/large_44k_v2",
-        ),
-        workload_type="v2a",
-        num_gpus=1,
-    )
-    result = generator.generate_video(
-        prompt=args.prompt,
-        negative_prompt=args.negative_prompt,
-        video_path=args.video_path,
-        audio_end_in_s=args.duration_seconds,
-        output_path=args.output_path,
-        save_video=True,
-        return_frames=False,
-    )
-    print(result["video_path"])
-    generator.shutdown()
-
-
-if __name__ == "__main__":
-    main()

examples/inference/basic/basic_mps.py

@@ -1,20 +1,19 @@
 from fastvideo import VideoGenerator, PipelineConfig
 from fastvideo.api.sampling_param import SamplingParam
 
-
 def main():
     config = PipelineConfig.from_pretrained("Wan-AI/Wan2.1-T2V-1.3B-Diffusers")
     config.text_encoder_precisions = ["fp16"]
-
+    
     generator = VideoGenerator.from_pretrained(
         "Wan-AI/Wan2.1-T2V-1.3B-Diffusers",
         pipeline_config=config,
-        use_fsdp_inference=False,  # Disable FSDP for MPS
-        dit_cpu_offload=True,
-        text_encoder_cpu_offload=True,
-        pin_cpu_memory=True,
-        disable_autocast=False,
-        num_gpus=1,
+        use_fsdp_inference=False,      # Disable FSDP for MPS
+        dit_cpu_offload=True,          
+        text_encoder_cpu_offload=True,    
+        pin_cpu_memory=True,           
+        disable_autocast=False,        
+        num_gpus=1,      
     )
 
     # Create sampling parameters with reduced number of frames
@@ -24,19 +23,18 @@ def main():
     sampling_param.width = 256
 
     prompt = ("A curious raccoon peers through a vibrant field of yellow sunflowers, its eyes "
-              "wide with interest. The playful yet serene atmosphere is complemented by soft "
-              "natural light filtering through the petals. Mid-shot, warm and cheerful tones.")
-
+             "wide with interest. The playful yet serene atmosphere is complemented by soft "
+             "natural light filtering through the petals. Mid-shot, warm and cheerful tones.")
+    
     video = generator.generate_video(prompt, sampling_param=sampling_param)
 
     prompt2 = ("A majestic lion strides across the golden savanna, its powerful frame "
-               "glistening under the warm afternoon sun. The tall grass ripples gently in "
-               "the breeze, enhancing the lion's commanding presence. The tone is vibrant, "
-               "embodying the raw energy of the wild. Low angle, steady tracking shot, "
-               "cinematic.")
-
+        "glistening under the warm afternoon sun. The tall grass ripples gently in "
+        "the breeze, enhancing the lion's commanding presence. The tone is vibrant, "
+        "embodying the raw energy of the wild. Low angle, steady tracking shot, "
+        "cinematic.")
+    
     video2 = generator.generate_video(prompt2, sampling_param=sampling_param)
 
-
 if __name__ == "__main__":
     main()

examples/inference/basic/basic_ray.py

@@ -3,8 +3,6 @@ from fastvideo import VideoGenerator
 # from fastvideo.api.sampling_param import SamplingParam
 
 OUTPUT_PATH = "video_samples"
-
-
 def main():
     # FastVideo will automatically use the optimal default arguments for the
     # model.
@@ -18,24 +16,27 @@ def main():
         dit_cpu_offload=False,
         vae_cpu_offload=False,
         text_encoder_cpu_offload=True,
-        pin_cpu_memory=True,  # set to false if low CPU RAM or hit obscure "CUDA error: Invalid argument"
+        pin_cpu_memory=True, # set to false if low CPU RAM or hit obscure "CUDA error: Invalid argument"
         distributed_executor_backend="ray",
         # image_encoder_cpu_offload=False,
     )
 
     # Generate videos with the same simple API, regardless of GPU count
-    prompt = ("A curious raccoon peers through a vibrant field of yellow sunflowers, its eyes "
-              "wide with interest. The playful yet serene atmosphere is complemented by soft "
-              "natural light filtering through the petals. Mid-shot, warm and cheerful tones.")
+    prompt = (
+        "A curious raccoon peers through a vibrant field of yellow sunflowers, its eyes "
+        "wide with interest. The playful yet serene atmosphere is complemented by soft "
+        "natural light filtering through the petals. Mid-shot, warm and cheerful tones."
+    )
     video = generator.generate_video(prompt, output_path=OUTPUT_PATH, save_video=True)
 
     # Generate another video with a different prompt, without reloading the
     # model!
-    prompt2 = ("A majestic lion strides across the golden savanna, its powerful frame "
-               "glistening under the warm afternoon sun. The tall grass ripples gently in "
-               "the breeze, enhancing the lion's commanding presence. The tone is vibrant, "
-               "embodying the raw energy of the wild. Low angle, steady tracking shot, "
-               "cinematic.")
+    prompt2 = (
+        "A majestic lion strides across the golden savanna, its powerful frame "
+        "glistening under the warm afternoon sun. The tall grass ripples gently in "
+        "the breeze, enhancing the lion's commanding presence. The tone is vibrant, "
+        "embodying the raw energy of the wild. Low angle, steady tracking shot, "
+        "cinematic.")
     video2 = generator.generate_video(prompt2, output_path=OUTPUT_PATH, save_video=True)
 
 

examples/inference/basic/basic_sd35_t2i.py

@@ -7,6 +7,7 @@ import os
 import re
 from typing import List
 
+
 DEFAULT_PROMPTS = [
     "a photo of a cat",
     "a cinematic photo of a red panda wearing a tiny backpack, standing on a rainy neon-lit street at night, shallow depth of field, sharp focus, 35mm, bokeh",
@@ -48,9 +49,7 @@ def _remove_existing_outputs(out_dir: str, filename_base: str) -> None:
 
 def parse_args() -> argparse.Namespace:
     p = argparse.ArgumentParser(description="Run SD3.5 Medium text-to-image with FastVideo VideoGenerator.")
-    p.add_argument("--model-path",
-                   default="stabilityai/stable-diffusion-3.5-medium",
-                   help="Path to local diffusers-format SD3.5 weights directory.")
+    p.add_argument("--model-path", default="stabilityai/stable-diffusion-3.5-medium", help="Path to local diffusers-format SD3.5 weights directory.")
     p.add_argument(
         "--out-dir",
         "--outdir",

examples/inference/basic/basic_self_forcing_causal.py

@@ -3,8 +3,6 @@ import time
 from fastvideo import VideoGenerator, SamplingParam
 
 OUTPUT_PATH = "video_samples_causal"
-
-
 def main():
     # FastVideo will automatically use the optimal default arguments for the
     # model.
@@ -15,18 +13,19 @@ def main():
         model_name,
         # FastVideo will automatically handle distributed setup
         num_gpus=1,
-        use_fsdp_inference=False,  # set to True if GPU is out of memory
+        use_fsdp_inference=False, # set to True if GPU is out of memory
         text_encoder_cpu_offload=False,
         dit_cpu_offload=False,
     )
 
     sampling_param = SamplingParam.from_pretrained(model_name)
 
-    prompt = ("A curious raccoon peers through a vibrant field of yellow sunflowers, its eyes "
-              "wide with interest. The playful yet serene atmosphere is complemented by soft "
-              "natural light filtering through the petals. Mid-shot, warm and cheerful tones.")
+    prompt = (
+        "A curious raccoon peers through a vibrant field of yellow sunflowers, its eyes "
+        "wide with interest. The playful yet serene atmosphere is complemented by soft "
+        "natural light filtering through the petals. Mid-shot, warm and cheerful tones."
+    )
     video = generator.generate_video(prompt, output_path=OUTPUT_PATH, save_video=True, sampling_param=sampling_param)
 
-
 if __name__ == "__main__":
     main()

examples/inference/basic/basic_self_forcing_causal_wan2_2_i2v.py

@@ -5,8 +5,6 @@ import json
 # from fastvideo.api.sampling_param import SamplingParam
 
 OUTPUT_PATH = "video_samples_self_forcing_causal_wan2_2_14B_i2v"
-
-
 def main():
     # FastVideo will automatically use the optimal default arguments for the
     # model.
@@ -16,8 +14,8 @@ def main():
         "FastVideo/SFWan2.2-I2V-A14B-Preview-Diffusers",
         # FastVideo will automatically handle distributed setup
         num_gpus=1,
-        use_fsdp_inference=False,  # set to True if GPU is out of memory
-        dit_cpu_offload=True,  # DiT need to be offloaded for MoE
+        use_fsdp_inference=False, # set to True if GPU is out of memory
+        dit_cpu_offload=True, # DiT need to be offloaded for MoE
         dit_precision="fp32",
         vae_cpu_offload=False,
         text_encoder_cpu_offload=True,
@@ -39,11 +37,7 @@ def main():
     for prompt_image_pair in prompt_image_pairs:
         prompt = prompt_image_pair["prompt"]
         image_path = prompt_image_pair["image_path"]
-        _ = generator.generate_video(prompt,
-                                     image_path=image_path,
-                                     output_path=OUTPUT_PATH,
-                                     save_video=True,
-                                     sampling_param=sampling_param)
+        _ = generator.generate_video(prompt, image_path=image_path, output_path=OUTPUT_PATH, save_video=True, sampling_param=sampling_param)
 
 
 if __name__ == "__main__":

examples/inference/basic/basic_self_forcing_causal_wan2_2_t2v.py

@@ -5,8 +5,6 @@ from fastvideo import VideoGenerator
 # from fastvideo.api.sampling_param import SamplingParam
 
 OUTPUT_PATH = "video_samples_self_forcing_causal_wan2_2_14B_t2v"
-
-
 def main():
     # FastVideo will automatically use the optimal default arguments for the
     # model.
@@ -16,17 +14,15 @@ def main():
         "rand0nmr/SFWan2.2-T2V-A14B-Diffusers",
         # FastVideo will automatically handle distributed setup
         num_gpus=1,
-        use_fsdp_inference=False,  # set to True if GPU is out of memory
-        dit_cpu_offload=True,  # DiT need to be offloaded for MoE
+        use_fsdp_inference=False, # set to True if GPU is out of memory
+        dit_cpu_offload=True, # DiT need to be offloaded for MoE
         vae_cpu_offload=False,
         text_encoder_cpu_offload=True,
         dmd_denoising_steps=[1000, 850, 700, 550, 350, 275, 200, 125],
         # Set pin_cpu_memory to false if CPU RAM is limited and there're no frequent CPU-GPU transfer
         pin_cpu_memory=True,
-        init_weights_from_safetensors=
-        "/mnt/sharefs/users/hao.zhang/wei/SFwan2.2_distill_self_forcing_release_cfg2/checkpoint-246_weight_only/generator_inference_transformer/",
-        init_weights_from_safetensors_2=
-        "/mnt/sharefs/users/hao.zhang/wei/SFwan2.2_distill_self_forcing_release_cfg2/checkpoint-246_weight_only/generator_2_inference_transformer/",
+        init_weights_from_safetensors="/mnt/sharefs/users/hao.zhang/wei/SFwan2.2_distill_self_forcing_release_cfg2/checkpoint-246_weight_only/generator_inference_transformer/",
+        init_weights_from_safetensors_2="/mnt/sharefs/users/hao.zhang/wei/SFwan2.2_distill_self_forcing_release_cfg2/checkpoint-246_weight_only/generator_2_inference_transformer/",
         num_frame_per_block=7,
         # image_encoder_cpu_offload=False,
     )
@@ -35,11 +31,13 @@ def main():
     # sampling_param.num_frames = 45
     # sampling_param.image_path = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg"
     # Generate videos with the same simple API, regardless of GPU count
-    prompt = ("A curious raccoon peers through a vibrant field of yellow sunflowers, its eyes "
-              "wide with interest. The playful yet serene atmosphere is complemented by soft "
-              "natural light filtering through the petals. Mid-shot, warm and cheerful tones.")
+    prompt = (
+        "A curious raccoon peers through a vibrant field of yellow sunflowers, its eyes "
+        "wide with interest. The playful yet serene atmosphere is complemented by soft "
+        "natural light filtering through the petals. Mid-shot, warm and cheerful tones."
+    )
     _ = generator.generate_video(prompt, output_path=OUTPUT_PATH, save_video=True, num_frames=81)
 
 
 if __name__ == "__main__":
-    main()
+    main()

examples/inference/basic/basic_stable_audio_inpaint.py

@@ -54,15 +54,16 @@ PROMPT = "Steady lo-fi hip hop drum loop with vinyl crackle."
 # ...) 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
+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.")
+        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,

examples/inference/basic/basic_turbodiffusion.py

@@ -15,17 +15,19 @@ def main() -> None:
         "loayrashid/TurboWan2.1-T2V-1.3B-Diffusers",
         # FastVideo will automatically handle distributed setup
         num_gpus=1,
-        use_fsdp_inference=False,  # set to True if GPU is out of memory
+        use_fsdp_inference=False, # set to True if GPU is out of memory
 
-        # set to false if using RTX 4090
+        # set to false if using RTX 4090 
         # pin_cpu_memory=False,
     )
 
     # Generate videos with the same simple API, regardless of GPU count
     # TurboDiffusion defaults: guidance_scale=1.0 and num_inference_steps=4 (from config)
-    prompt = ("A curious raccoon peers through a vibrant field of yellow sunflowers, its eyes "
-              "wide with interest. The playful yet serene atmosphere is complemented by soft "
-              "natural light filtering through the petals. Mid-shot, warm and cheerful tones.")
+    prompt = (
+        "A curious raccoon peers through a vibrant field of yellow sunflowers, its eyes "
+        "wide with interest. The playful yet serene atmosphere is complemented by soft "
+        "natural light filtering through the petals. Mid-shot, warm and cheerful tones."
+    )
     video = generator.generate_video(
         prompt,
         output_path=OUTPUT_PATH,
@@ -34,11 +36,13 @@ def main() -> None:
     )
 
     # Generate another video with a different prompt, without reloading the model!
-    prompt2 = ("A majestic lion strides across the golden savanna, its powerful frame "
-               "glistening under the warm afternoon sun. The tall grass ripples gently in "
-               "the breeze, enhancing the lion's commanding presence. The tone is vibrant, "
-               "embodying the raw energy of the wild. Low angle, steady tracking shot, "
-               "cinematic.")
+    prompt2 = (
+        "A majestic lion strides across the golden savanna, its powerful frame "
+        "glistening under the warm afternoon sun. The tall grass ripples gently in "
+        "the breeze, enhancing the lion's commanding presence. The tone is vibrant, "
+        "embodying the raw energy of the wild. Low angle, steady tracking shot, "
+        "cinematic."
+    )
     video2 = generator.generate_video(
         prompt2,
         output_path=OUTPUT_PATH,

examples/inference/basic/basic_turbodiffusion_14b.py

@@ -17,9 +17,11 @@ def main() -> None:
         num_gpus=2,
     )
 
-    prompt = ("A curious raccoon peers through a vibrant field of yellow sunflowers, its eyes "
-              "wide with interest. The playful yet serene atmosphere is complemented by soft "
-              "natural light filtering through the petals. Mid-shot, warm and cheerful tones.")
+    prompt = (
+        "A curious raccoon peers through a vibrant field of yellow sunflowers, its eyes "
+        "wide with interest. The playful yet serene atmosphere is complemented by soft "
+        "natural light filtering through the petals. Mid-shot, warm and cheerful tones."
+    )
     video = generator.generate_video(
         prompt,
         output_path=OUTPUT_PATH,
@@ -28,11 +30,13 @@ def main() -> None:
     )
 
     # Generate another video with a different prompt, without reloading the model!
-    prompt2 = ("A majestic lion strides across the golden savanna, its powerful frame "
-               "glistening under the warm afternoon sun. The tall grass ripples gently in "
-               "the breeze, enhancing the lion's commanding presence. The tone is vibrant, "
-               "embodying the raw energy of the wild. Low angle, steady tracking shot, "
-               "cinematic.")
+    prompt2 = (
+        "A majestic lion strides across the golden savanna, its powerful frame "
+        "glistening under the warm afternoon sun. The tall grass ripples gently in "
+        "the breeze, enhancing the lion's commanding presence. The tone is vibrant, "
+        "embodying the raw energy of the wild. Low angle, steady tracking shot, "
+        "cinematic."
+    )
     video2 = generator.generate_video(
         prompt2,
         output_path=OUTPUT_PATH,

examples/inference/basic/basic_turbodiffusion_i2v.py

@@ -18,13 +18,12 @@ def main() -> None:
     )
 
     # Example prompt and image for I2V
-    prompt = (
-        "Summer beach vacation style, a white cat wearing sunglasses sits on a surfboard. The fluffy-furred feline gazes directly at the camera with a relaxed expression. Blurred beach scenery forms the background featuring crystal-clear waters, distant green hills, and a blue sky dotted with white clouds. The cat assumes a naturally relaxed posture, as if savoring the sea breeze and warm sunlight. A close-up shot highlights the feline's intricate details and the refreshing atmosphere of the seaside."
-    )
+    prompt = ("Summer beach vacation style, a white cat wearing sunglasses sits on a surfboard. The fluffy-furred feline gazes directly at the camera with a relaxed expression. Blurred beach scenery forms the background featuring crystal-clear waters, distant green hills, and a blue sky dotted with white clouds. The cat assumes a naturally relaxed posture, as if savoring the sea breeze and warm sunlight. A close-up shot highlights the feline's intricate details and the refreshing atmosphere of the seaside.")
 
     # Use an example image path
     image_path = "https://huggingface.co/datasets/YiYiXu/testing-images/resolve/main/wan_i2v_input.JPG"
 
+
     video = generator.generate_video(
         prompt,
         image_path=image_path,

examples/inference/basic/basic_wan2_2.py

@@ -3,8 +3,6 @@ from fastvideo import VideoGenerator
 # from fastvideo.api.sampling_param import SamplingParam
 
 OUTPUT_PATH = "video_samples_wan2_2_14B_t2v"
-
-
 def main():
     # FastVideo will automatically use the optimal default arguments for the
     # model.
@@ -14,8 +12,8 @@ def main():
         "Wan-AI/Wan2.2-T2V-A14B-Diffusers",
         # FastVideo will automatically handle distributed setup
         num_gpus=2,
-        use_fsdp_inference=False,  # set to True if GPU is out of memory 
-        dit_cpu_offload=True,  # DiT need to be offloaded for MoE
+        use_fsdp_inference=False, # set to True if GPU is out of memory 
+        dit_cpu_offload=True, # DiT need to be offloaded for MoE
         vae_cpu_offload=False,
         text_encoder_cpu_offload=True,
         # Set pin_cpu_memory to false if CPU RAM is limited and there're no frequent CPU-GPU transfer
@@ -27,31 +25,24 @@ def main():
     # sampling_param.num_frames = 45
     # sampling_param.image_path = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg"
     # Generate videos with the same simple API, regardless of GPU count
-    prompt = ("A curious raccoon peers through a vibrant field of yellow sunflowers, its eyes "
-              "wide with interest. The playful yet serene atmosphere is complemented by soft "
-              "natural light filtering through the petals. Mid-shot, warm and cheerful tones.")
-    _ = generator.generate_video(prompt,
-                                 output_path=OUTPUT_PATH,
-                                 save_video=True,
-                                 height=720,
-                                 width=1280,
-                                 num_frames=81)
+    prompt = (
+        "A curious raccoon peers through a vibrant field of yellow sunflowers, its eyes "
+        "wide with interest. The playful yet serene atmosphere is complemented by soft "
+        "natural light filtering through the petals. Mid-shot, warm and cheerful tones."
+    )
+    _ = generator.generate_video(prompt, output_path=OUTPUT_PATH, save_video=True, height=720, width=1280, num_frames=81)
     # video = generator.generate_video(prompt, sampling_param=sampling_param, output_path="wan_t2v_videos/")
 
     # Generate another video with a different prompt, without reloading the
     # model!
-    prompt2 = ("A majestic lion strides across the golden savanna, its powerful frame "
-               "glistening under the warm afternoon sun. The tall grass ripples gently in "
-               "the breeze, enhancing the lion's commanding presence. The tone is vibrant, "
-               "embodying the raw energy of the wild. Low angle, steady tracking shot, "
-               "cinematic.")
-    _ = generator.generate_video(prompt2,
-                                 output_path=OUTPUT_PATH,
-                                 save_video=True,
-                                 height=720,
-                                 width=1280,
-                                 num_frames=81)
+    prompt2 = (
+        "A majestic lion strides across the golden savanna, its powerful frame "
+        "glistening under the warm afternoon sun. The tall grass ripples gently in "
+        "the breeze, enhancing the lion's commanding presence. The tone is vibrant, "
+        "embodying the raw energy of the wild. Low angle, steady tracking shot, "
+        "cinematic.")
+    _ = generator.generate_video(prompt2, output_path=OUTPUT_PATH, save_video=True, height=720, width=1280, num_frames=81)
 
 
 if __name__ == "__main__":
-    main()
+    main()

examples/inference/basic/basic_wan2_2_Fun.py

@@ -4,8 +4,6 @@ from fastvideo import VideoGenerator
 
 OUTPUT_PATH = "video_samples_wan2_1_Fun"
 OUTPUT_NAME = "wan2.1_test"
-
-
 def main():
     # FastVideo will automatically use the optimal default arguments for the
     # model.
@@ -16,8 +14,8 @@ def main():
         # "alibaba-pai/Wan2.2-Fun-A14B-Control",
         # FastVideo will automatically handle distributed setup
         num_gpus=1,
-        use_fsdp_inference=False,  # set to True if GPU is out of memory
-        dit_cpu_offload=True,  # DiT need to be offloaded for MoE
+        use_fsdp_inference=False, # set to True if GPU is out of memory
+        dit_cpu_offload=True, # DiT need to be offloaded for MoE
         vae_cpu_offload=False,
         text_encoder_cpu_offload=True,
         # Set pin_cpu_memory to false if CPU RAM is limited and there're no frequent CPU-GPU transfer
@@ -32,14 +30,7 @@ def main():
     image_path = "https://pai-aigc-photog.oss-cn-hangzhou.aliyuncs.com/wan_fun/asset_Wan2_2/v1.0/8.png"
     control_video_path = "https://pai-aigc-photog.oss-cn-hangzhou.aliyuncs.com/wan_fun/asset_Wan2_2/v1.0/pose.mp4"
 
-    video = generator.generate_video(prompt,
-                                     negative_prompt=negative_prompt,
-                                     image_path=image_path,
-                                     video_path=control_video_path,
-                                     output_path=OUTPUT_PATH,
-                                     output_video_name=OUTPUT_NAME,
-                                     save_video=True)
-
+    video = generator.generate_video(prompt, negative_prompt=negative_prompt, image_path=image_path, video_path=control_video_path, output_path=OUTPUT_PATH, output_video_name=OUTPUT_NAME, save_video=True)
 
 if __name__ == "__main__":
-    main()
+    main()

examples/inference/basic/basic_wan2_2_i2v.py

@@ -3,8 +3,6 @@ from fastvideo import VideoGenerator
 # from fastvideo.api.sampling_param import SamplingParam
 
 OUTPUT_PATH = "video_samples_wan2_2_14B_i2v"
-
-
 def main():
     # FastVideo will automatically use the optimal default arguments for the
     # model.
@@ -14,8 +12,8 @@ def main():
         "Wan-AI/Wan2.2-I2V-A14B-Diffusers",
         # FastVideo will automatically handle distributed setup
         num_gpus=1,
-        use_fsdp_inference=False,  # set to True if GPU is out of memory
-        dit_cpu_offload=True,  # DiT need to be offloaded for MoE
+        use_fsdp_inference=False, # set to True if GPU is out of memory
+        dit_cpu_offload=True, # DiT need to be offloaded for MoE
         vae_cpu_offload=False,
         text_encoder_cpu_offload=True,
         # Set pin_cpu_memory to false if CPU RAM is limited and there're no frequent CPU-GPU transfer
@@ -26,14 +24,7 @@ def main():
     prompt = "Summer beach vacation style, a white cat wearing sunglasses sits on a surfboard. The fluffy-furred feline gazes directly at the camera with a relaxed expression. Blurred beach scenery forms the background featuring crystal-clear waters, distant green hills, and a blue sky dotted with white clouds. The cat assumes a naturally relaxed posture, as if savoring the sea breeze and warm sunlight. A close-up shot highlights the feline's intricate details and the refreshing atmosphere of the seaside."
     image_path = "https://huggingface.co/datasets/YiYiXu/testing-images/resolve/main/wan_i2v_input.JPG"
 
-    video = generator.generate_video(prompt,
-                                     image_path=image_path,
-                                     output_path=OUTPUT_PATH,
-                                     save_video=True,
-                                     height=832,
-                                     width=480,
-                                     num_frames=81)
-
+    video = generator.generate_video(prompt, image_path=image_path, output_path=OUTPUT_PATH, save_video=True, height=832, width=480, num_frames=81)
 
 if __name__ == "__main__":
-    main()
+    main()

examples/inference/basic/basic_wan2_2_ti2v.py

@@ -1,8 +1,6 @@
 from fastvideo import VideoGenerator
 
 OUTPUT_PATH = "video_samples_wan2_2_5B_ti2v"
-
-
 def main():
     # FastVideo will automatically use the optimal default arguments for the
     # model.
@@ -13,11 +11,11 @@ def main():
         model_name,
         # FastVideo will automatically handle distributed setup
         num_gpus=1,
-        use_fsdp_inference=False,  # set to True if GPU is out of memory
+        use_fsdp_inference=False, # set to True if GPU is out of memory
         dit_cpu_offload=True,
         vae_cpu_offload=False,
         text_encoder_cpu_offload=True,
-        pin_cpu_memory=True,  # set to false if low CPU RAM or hit obscure "CUDA error: Invalid argument"
+        pin_cpu_memory=True, # set to false if low CPU RAM or hit obscure "CUDA error: Invalid argument"
         # image_encoder_cpu_offload=False,
     )
 
@@ -30,13 +28,14 @@ def main():
     # model!
 
     # T2V mode
-    prompt2 = ("A majestic lion strides across the golden savanna, its powerful frame "
-               "glistening under the warm afternoon sun. The tall grass ripples gently in "
-               "the breeze, enhancing the lion's commanding presence. The tone is vibrant, "
-               "embodying the raw energy of the wild. Low angle, steady tracking shot, "
-               "cinematic.")
+    prompt2 = (
+        "A majestic lion strides across the golden savanna, its powerful frame "
+        "glistening under the warm afternoon sun. The tall grass ripples gently in "
+        "the breeze, enhancing the lion's commanding presence. The tone is vibrant, "
+        "embodying the raw energy of the wild. Low angle, steady tracking shot, "
+        "cinematic.")
     video2 = generator.generate_video(prompt2, output_path=OUTPUT_PATH, save_video=True)
 
 
 if __name__ == "__main__":
-    main()
+    main()

examples/inference/basic/basic_zimage.py

@@ -20,11 +20,13 @@ from fastvideo.api import (
     SamplingConfig,
 )
 
+
 DEFAULT_PROMPT = (
     "Young Chinese woman in red Hanfu, intricate embroidery. Impeccable makeup, red floral forehead pattern. "
     "Elaborate high bun, golden phoenix headdress, red flowers, beads. Holds round folding fan with lady, trees, bird. "
     "Neon lightning-bolt lamp (⚡️), bright yellow glow, above extended left palm. Soft-lit outdoor night background, "
-    "silhouetted tiered pagoda (西安大雁塔), blurred colorful distant lights.")
+    "silhouetted tiered pagoda (西安大雁塔), blurred colorful distant lights."
+)
 DEFAULT_REVISION = "f332072aa78be7aecdf3ee76d5c247082da564a6"
 
 

examples/inference/eval/all_metrics_demo.py

@@ -35,11 +35,13 @@ import torch
 # Generation — make one LTX2 video to evaluate.
 # ---------------------------------------------------------------------
 
-PROMPT = ("A warm sunny backyard. The camera starts in a tight cinematic close-up "
-          "of a woman and a man in their 30s, facing each other with serious "
-          "expressions. The woman, emotional and dramatic, says softly, \"That's "
-          "it... Dad's lost it. And we've lost Dad.\" The man exhales, slightly "
-          "annoyed: \"Stop being so dramatic, Jess.\"")
+PROMPT = (
+    "A warm sunny backyard. The camera starts in a tight cinematic close-up "
+    "of a woman and a man in their 30s, facing each other with serious "
+    "expressions. The woman, emotional and dramatic, says softly, \"That's "
+    "it... Dad's lost it. And we've lost Dad.\" The man exhales, slightly "
+    "annoyed: \"Stop being so dramatic, Jess.\""
+)
 
 OUTPUT_PATH = "fastvideo/tests/eval/asset/ltx2.mp4"
 N_DUP = 4  # how many times to duplicate the video for the gen/ref corpora
@@ -75,7 +77,6 @@ def generate_one_ltx2_video() -> str:
 # Eval — the point of the script.  4 lines from "two paths" to results.
 # ---------------------------------------------------------------------
 
-
 def _all_registered_metrics() -> list[str]:
     """Every metric in the registry, sorted.  Combined with
     ``skip_missing_deps=True`` this is the "run everything that works in
@@ -102,7 +103,8 @@ def score_all_metrics(video_path: str) -> None:
     torch.cuda.empty_cache()
     torch.cuda.reset_peak_memory_stats()
     t_init0 = time.perf_counter()
-    ev = create_evaluator(metrics=_all_registered_metrics(), device="cuda:0", num_gpus=1, skip_missing_deps=True)
+    ev = create_evaluator(metrics=_all_registered_metrics(),
+                          device="cuda:0", num_gpus=1, skip_missing_deps=True)
     t_init1 = time.perf_counter()
     samples = samples_from(video=gen_dir, reference=ref_dir, text_prompt=PROMPT, fps=24.0,
                            extract_audio=True)  # auto-extract audio track from videos

examples/inference/eval/basic_ltx2_audio_eval.py

@@ -23,12 +23,14 @@ import torch
 from fastvideo import VideoGenerator
 from fastvideo.eval import create_evaluator
 
-PROMPT = ("A warm sunny backyard. The camera starts in a tight cinematic close-up "
-          "of a woman and a man in their 30s, facing each other with serious "
-          "expressions. The woman, emotional and dramatic, says softly, \"That's "
-          "it... Dad's lost it. And we've lost Dad.\" The man exhales, slightly "
-          "annoyed: \"Stop being so dramatic, Jess.\" A beat. He glances aside, "
-          "then mutters defensively, \"He's just having fun.\"")
+PROMPT = (
+    "A warm sunny backyard. The camera starts in a tight cinematic close-up "
+    "of a woman and a man in their 30s, facing each other with serious "
+    "expressions. The woman, emotional and dramatic, says softly, \"That's "
+    "it... Dad's lost it. And we've lost Dad.\" The man exhales, slightly "
+    "annoyed: \"Stop being so dramatic, Jess.\" A beat. He glances aside, "
+    "then mutters defensively, \"He's just having fun.\""
+)
 
 METRICS = [
     "audio.clap_score",

examples/inference/eval/basic_ltx2_eval.py

@@ -25,17 +25,19 @@ from fastvideo import VideoGenerator
 from fastvideo.eval import Evaluator
 from fastvideo.eval.io import build_eval_kwargs
 
-PROMPT = ("A warm sunny backyard. The camera starts in a tight cinematic close-up "
-          "of a woman and a man in their 30s, facing each other with serious "
-          "expressions. The woman, emotional and dramatic, says softly, \"That's "
-          "it... Dad's lost it. And we've lost Dad.\" The man exhales, slightly "
-          "annoyed: \"Stop being so dramatic, Jess.\" A beat. He glances aside, "
-          "then mutters defensively, \"He's just having fun.\" The camera slowly "
-          "pans right, revealing the grandfather in the garden wearing enormous "
-          "butterfly wings, waving his arms in the air like he's trying to take "
-          "off. He shouts, \"Wheeeew!\" as he flaps his wings with full commitment. "
-          "The woman covers her face, on the verge of tears. The tone is deadpan, "
-          "absurd, and quietly tragic.")
+PROMPT = (
+    "A warm sunny backyard. The camera starts in a tight cinematic close-up "
+    "of a woman and a man in their 30s, facing each other with serious "
+    "expressions. The woman, emotional and dramatic, says softly, \"That's "
+    "it... Dad's lost it. And we've lost Dad.\" The man exhales, slightly "
+    "annoyed: \"Stop being so dramatic, Jess.\" A beat. He glances aside, "
+    "then mutters defensively, \"He's just having fun.\" The camera slowly "
+    "pans right, revealing the grandfather in the garden wearing enormous "
+    "butterfly wings, waving his arms in the air like he's trying to take "
+    "off. He shouts, \"Wheeeew!\" as he flaps his wings with full commitment. "
+    "The woman covers her face, on the verge of tears. The tone is deadpan, "
+    "absurd, and quietly tragic."
+)
 
 # VBench sub-metrics meaningful for an arbitrary text→video sample
 # (just the generated frames, optionally fps + the source prompt).
@@ -43,14 +45,14 @@ PROMPT = ("A warm sunny backyard. The camera starts in a tight cinematic close-u
 # vbench.scene, ...) are excluded — they need prompts built to a
 # specific schema.
 METRICS = [
-    "vbench.aesthetic_quality",  # CLIP + LAION aesthetic head
-    "vbench.subject_consistency",  # DINO frame-to-first cosine
+    "vbench.aesthetic_quality",       # CLIP + LAION aesthetic head
+    "vbench.subject_consistency",     # DINO frame-to-first cosine
     "vbench.background_consistency",  # DINO on background patches
-    "vbench.imaging_quality",  # pyiqa MUSIQ
-    "vbench.temporal_flickering",  # pixel-wise frame deltas
-    "vbench.motion_smoothness",  # AMT frame interpolator residual
-    "vbench.dynamic_degree",  # RAFT optical-flow magnitude (needs fps)
-    "vbench.overall_consistency",  # ViCLIP video↔prompt similarity
+    "vbench.imaging_quality",         # pyiqa MUSIQ
+    "vbench.temporal_flickering",     # pixel-wise frame deltas
+    "vbench.motion_smoothness",       # AMT frame interpolator residual
+    "vbench.dynamic_degree",          # RAFT optical-flow magnitude (needs fps)
+    "vbench.overall_consistency",     # ViCLIP video↔prompt similarity
 ]
 
 

examples/inference/eval/bench_physics_iq.py

@@ -41,8 +41,9 @@ def _expected_filename(row: dict) -> str:
     return row["auxiliary_info"]["expected_gen_filename"]
 
 
-def _generate_videos(rows: list[dict], videos_dir: Path, model: str, num_gpus: int, num_frames: int, height: int,
-                     width: int) -> None:
+def _generate_videos(rows: list[dict], videos_dir: Path,
+                     model: str, num_gpus: int,
+                     num_frames: int, height: int, width: int) -> None:
     from fastvideo import VideoGenerator
 
     videos_dir.mkdir(parents=True, exist_ok=True)
@@ -58,43 +59,36 @@ def _generate_videos(rows: list[dict], videos_dir: Path, model: str, num_gpus: i
     try:
         for row, out_path in todo:
             gen.generate_video(
-                prompt=row["prompt"],
-                output_path=str(out_path),
-                save_video=True,
-                num_frames=num_frames,
-                height=height,
-                width=width,
+                prompt=row["prompt"], output_path=str(out_path), save_video=True,
+                num_frames=num_frames, height=height, width=width,
             )
     finally:
         gen.shutdown()
 
 
 def main() -> None:
-    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
-    p.add_argument("--dataset-root",
-                   type=Path,
-                   default=None,
+    p = argparse.ArgumentParser(description=__doc__,
+                                formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("--dataset-root", type=Path, default=None,
                    help="Path to a pre-downloaded Physics-IQ release. "
-                   "Defaults to ${FASTVIDEO_EVAL_CACHE}/datasets/physics_iq, "
-                   "auto-fetching missing assets from the public bucket.")
-    p.add_argument("--videos-dir",
-                   type=Path,
+                        "Defaults to ${FASTVIDEO_EVAL_CACHE}/datasets/physics_iq, "
+                        "auto-fetching missing assets from the public bucket.")
+    p.add_argument("--videos-dir", type=Path,
                    default=Path("outputs_video/bench_physics_iq"),
                    help="Where to read/write generated videos.")
-    p.add_argument("--limit", type=int, default=None, help="Truncate to first N scenarios for smoke runs.")
+    p.add_argument("--limit", type=int, default=None,
+                   help="Truncate to first N scenarios for smoke runs.")
     p.add_argument("--num-gpus", type=int, default=1)
-    p.add_argument("--model",
-                   default="Davids048/LTX2-Base-Diffusers",
+    p.add_argument("--model", default="Davids048/LTX2-Base-Diffusers",
                    help="HF repo id of the text→video generator to use.")
     p.add_argument("--num-frames", type=int, default=121)
     p.add_argument("--height", type=int, default=1088)
     p.add_argument("--width", type=int, default=1920)
-    p.add_argument("--skip-generation", action="store_true", help="Re-score existing videos under --videos-dir.")
-    p.add_argument("--scores-out",
-                   type=Path,
-                   default=None,
+    p.add_argument("--skip-generation", action="store_true",
+                   help="Re-score existing videos under --videos-dir.")
+    p.add_argument("--scores-out", type=Path, default=None,
                    help="Where to write per-scenario scores (JSON). "
-                   "Defaults to <videos-dir>/scores.json.")
+                        "Defaults to <videos-dir>/scores.json.")
     args = p.parse_args()
 
     # 1. Walk the Physics-IQ corpus. Pass --limit to the dataset
@@ -106,13 +100,8 @@ def main() -> None:
     # 2. Generate (or reuse) one mp4 per scenario.
     if not args.skip_generation:
         _generate_videos(
-            rows,
-            args.videos_dir,
-            args.model,
-            args.num_gpus,
-            args.num_frames,
-            args.height,
-            args.width,
+            rows, args.videos_dir, args.model, args.num_gpus,
+            args.num_frames, args.height, args.width,
         )
 
     # 3. Score each scenario. The metric reads file paths directly out
@@ -137,26 +126,28 @@ def main() -> None:
 
     # 4. Aggregate per the upstream scoring recipe.
     metric = get_metric("physics_iq")
-    components = metric.aggregate_components([r["physics_iq"] for r in all_results])
+    components = metric.aggregate_components(
+        [r["physics_iq"] for r in all_results]
+    )
 
     print()
     print("=== Physics-IQ aggregate ===")
     for name, value in components.items():
         print(f"  {name:24s}  {value:.4f}")
 
-    detailed = [{
-        "scenario": row["auxiliary_info"]["scenario_id"],
-        "view": row["view"],
-        "scenario_name": row["auxiliary_info"]["scenario_name"],
-        "score": results["physics_iq"].score,
-    } for row, results in zip(matched, all_results)]
+    detailed = [
+        {
+            "scenario": row["auxiliary_info"]["scenario_id"],
+            "view": row["view"],
+            "scenario_name": row["auxiliary_info"]["scenario_name"],
+            "score": results["physics_iq"].score,
+        }
+        for row, results in zip(matched, all_results)
+    ]
     out = args.scores_out or (args.videos_dir / "scores.json")
     out.parent.mkdir(parents=True, exist_ok=True)
     out.write_text(json.dumps(
-        {
-            "aggregate": components,
-            "per_scenario": detailed
-        },
+        {"aggregate": components, "per_scenario": detailed},
         indent=2,
     ))
     print(f"\n[done] per-scenario scores → {out}")

examples/inference/eval/bench_vbench.py

@@ -39,8 +39,9 @@ def _slugify(prompt: str, max_len: int = 100) -> str:
     return re.sub(r"\s+", " ", s) or "output"
 
 
-def _generate_videos(prompts: list[str], videos_dir: Path, model: str, num_gpus: int, num_frames: int, height: int,
-                     width: int) -> None:
+def _generate_videos(prompts: list[str], videos_dir: Path,
+                     model: str, num_gpus: int,
+                     num_frames: int, height: int, width: int) -> None:
     from fastvideo import VideoGenerator
 
     videos_dir.mkdir(parents=True, exist_ok=True)
@@ -56,60 +57,53 @@ def _generate_videos(prompts: list[str], videos_dir: Path, model: str, num_gpus:
     try:
         for prompt, out_path in todo:
             gen.generate_video(
-                prompt=prompt,
-                output_path=str(out_path),
-                save_video=True,
-                num_frames=num_frames,
-                height=height,
-                width=width,
+                prompt=prompt, output_path=str(out_path), save_video=True,
+                num_frames=num_frames, height=height, width=width,
             )
     finally:
         gen.shutdown()
 
 
 def main() -> None:
-    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
-    p.add_argument("--dimensions",
-                   default="aesthetic_quality,subject_consistency",
+    p = argparse.ArgumentParser(description=__doc__,
+                                formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("--dimensions", default="aesthetic_quality,subject_consistency",
                    help="Comma-separated VBench dimensions (or 'all').")
-    p.add_argument("--limit", type=int, default=None, help="Truncate to first N prompts for smoke runs.")
-    p.add_argument("--videos-dir", type=Path, default=Path("outputs_video/bench_vbench"))
+    p.add_argument("--limit", type=int, default=None,
+                   help="Truncate to first N prompts for smoke runs.")
+    p.add_argument("--videos-dir", type=Path,
+                   default=Path("outputs_video/bench_vbench"))
     p.add_argument("--num-gpus", type=int, default=1)
-    p.add_argument("--model",
-                   default="Davids048/LTX2-Base-Diffusers",
+    p.add_argument("--model", default="Davids048/LTX2-Base-Diffusers",
                    help="HF repo id of the text→video generator to use.")
     p.add_argument("--num-frames", type=int, default=121)
     p.add_argument("--height", type=int, default=1088)
     p.add_argument("--width", type=int, default=1920)
-    p.add_argument("--fps", type=float, default=24.0, help="Frame-rate annotation passed to fps-aware metrics.")
-    p.add_argument("--skip-generation",
-                   action="store_true",
+    p.add_argument("--fps", type=float, default=24.0,
+                   help="Frame-rate annotation passed to fps-aware metrics.")
+    p.add_argument("--skip-generation", action="store_true",
                    help="Re-score existing videos under --videos-dir without "
-                   "regenerating.")
-    p.add_argument("--scores-out",
-                   type=Path,
-                   default=None,
+                        "regenerating.")
+    p.add_argument("--scores-out", type=Path, default=None,
                    help="Where to dump per-prompt scores as JSON. "
-                   "Defaults to <videos-dir>/scores.json.")
+                        "Defaults to <videos-dir>/scores.json.")
     args = p.parse_args()
 
     # 1. Pull prompts from VBench.
-    dims_arg: list[str] | str = (args.dimensions if args.dimensions == "all" else
-                                 [d.strip() for d in args.dimensions.split(",") if d.strip()])
+    dims_arg: list[str] | str = (
+        args.dimensions if args.dimensions == "all"
+        else [d.strip() for d in args.dimensions.split(",") if d.strip()]
+    )
     ds = get_dataset("vbench", dimensions=dims_arg)
-    rows = list(ds)[:args.limit]
+    rows = list(ds)[: args.limit]
     print(f"[load] VBench: {len(rows)} prompts across {ds.dimensions}")
 
     # 2. Generate (or reuse) one mp4 per prompt.
     if not args.skip_generation:
         _generate_videos(
             [row["prompt"] for row in rows],
-            args.videos_dir,
-            args.model,
-            args.num_gpus,
-            args.num_frames,
-            args.height,
-            args.width,
+            args.videos_dir, args.model, args.num_gpus,
+            args.num_frames, args.height, args.width,
         )
 
     # 3. Score each video against the requested vbench sub-metrics.
@@ -128,7 +122,7 @@ def main() -> None:
         samples.append({
             "video": str(video_path),
             "fps": args.fps,
-            **row,  # prompt / aux / dims
+            **row,                                       # prompt / aux / dims
         })
         matched_rows.append(row)
 

examples/inference/eval/eval_fvd.py

@@ -35,29 +35,20 @@ from fastvideo.eval import create_evaluator, samples_from
 
 
 def main() -> None:
-    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
-    p.add_argument("--gen-dir",
-                   type=Path,
-                   required=True,
+    p = argparse.ArgumentParser(description=__doc__,
+                                formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("--gen-dir", type=Path, required=True,
                    help="Directory of generated videos (.mp4, .avi, .mov, .mkv, .gif).")
-    p.add_argument("--reference-dir",
-                   type=Path,
-                   default=None,
+    p.add_argument("--reference-dir", type=Path, default=None,
                    help="Directory of reference videos. Omit to score against the cached "
-                   "reference features (built on a previous run).")
+                        "reference features (built on a previous run).")
     p.add_argument("--device", default="cuda:0" if torch.cuda.is_available() else "cpu")
-    p.add_argument("--num-gpus",
-                   type=int,
-                   default=1,
+    p.add_argument("--num-gpus", type=int, default=1,
                    help="Number of GPU replicas. >1 fans extraction out across devices.")
-    p.add_argument("--cache-path",
-                   type=Path,
-                   default=None,
+    p.add_argument("--cache-path", type=Path, default=None,
                    help="Override the reference-feature cache path. "
-                   "Defaults to ${FASTVIDEO_EVAL_CACHE}/fvd/real_features_i3d.pt.")
-    p.add_argument("--output",
-                   type=Path,
-                   default=None,
+                        "Defaults to ${FASTVIDEO_EVAL_CACHE}/fvd/real_features_i3d.pt.")
+    p.add_argument("--output", type=Path, default=None,
                    help="Write the result as JSON to this path (default: stdout only).")
     args = p.parse_args()
 

examples/inference/eval/eval_ltx2_vbench.py

@@ -36,55 +36,57 @@ from fastvideo import VideoGenerator
 from fastvideo.eval import create_evaluator
 from fastvideo.eval.io import load_video
 
-PROMPT = ("A warm sunny backyard. The camera starts in a tight cinematic close-up "
-          "of a woman and a man in their 30s, facing each other with serious "
-          "expressions. The woman, emotional and dramatic, says softly, \"That's "
-          "it... Dad's lost it. And we've lost Dad.\" The man exhales, slightly "
-          "annoyed: \"Stop being so dramatic, Jess.\" A beat. He glances aside, "
-          "then mutters defensively, \"He's just having fun.\" The camera slowly "
-          "pans right, revealing the grandfather in the garden wearing enormous "
-          "butterfly wings, waving his arms in the air like he's trying to take "
-          "off. He shouts, \"Wheeeew!\" as he flaps his wings with full commitment. "
-          "The woman covers her face, on the verge of tears. The tone is deadpan, "
-          "absurd, and quietly tragic.")
+
+PROMPT = (
+    "A warm sunny backyard. The camera starts in a tight cinematic close-up "
+    "of a woman and a man in their 30s, facing each other with serious "
+    "expressions. The woman, emotional and dramatic, says softly, \"That's "
+    "it... Dad's lost it. And we've lost Dad.\" The man exhales, slightly "
+    "annoyed: \"Stop being so dramatic, Jess.\" A beat. He glances aside, "
+    "then mutters defensively, \"He's just having fun.\" The camera slowly "
+    "pans right, revealing the grandfather in the garden wearing enormous "
+    "butterfly wings, waving his arms in the air like he's trying to take "
+    "off. He shouts, \"Wheeeew!\" as he flaps his wings with full commitment. "
+    "The woman covers her face, on the verge of tears. The tone is deadpan, "
+    "absurd, and quietly tragic."
+)
 
 DEFAULT_METRICS = [
     # No-input metrics: just need the generated frames.
-    "vbench.aesthetic_quality",  # CLIP + LAION aesthetic head
-    "vbench.subject_consistency",  # DINO frame-to-first cosine
+    "vbench.aesthetic_quality",       # CLIP + LAION aesthetic head
+    "vbench.subject_consistency",     # DINO frame-to-first cosine
     "vbench.background_consistency",  # DINO on background patches
-    "vbench.imaging_quality",  # pyiqa MUSIQ
-    "vbench.temporal_flickering",  # pixel-wise frame deltas
-    "vbench.motion_smoothness",  # AMT frame interpolator residual
+    "vbench.imaging_quality",         # pyiqa MUSIQ
+    "vbench.temporal_flickering",     # pixel-wise frame deltas
+    "vbench.motion_smoothness",       # AMT frame interpolator residual
     # Need fps annotation:
-    "vbench.dynamic_degree",  # RAFT optical-flow magnitude
+    "vbench.dynamic_degree",          # RAFT optical-flow magnitude
     # Need the source prompt:
-    "vbench.overall_consistency",  # ViCLIP video↔prompt similarity
+    "vbench.overall_consistency",     # ViCLIP video↔prompt similarity
 ]
 
 
 def parse_args() -> argparse.Namespace:
-    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
-    p.add_argument("--model", default="Davids048/LTX2-Base-Diffusers", help="HF repo id of the LTX2 checkpoint.")
+    p = argparse.ArgumentParser(description=__doc__,
+                                formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("--model", default="Davids048/LTX2-Base-Diffusers",
+                   help="HF repo id of the LTX2 checkpoint.")
     p.add_argument("--num-gpus", type=int, default=1)
-    p.add_argument("--output", default="outputs_video/ltx2_eval/clip.mp4", help="Where to save the generated mp4.")
+    p.add_argument("--output", default="outputs_video/ltx2_eval/clip.mp4",
+                   help="Where to save the generated mp4.")
     p.add_argument("--num-frames", type=int, default=121)
     p.add_argument("--height", type=int, default=1088)
     p.add_argument("--width", type=int, default=1920)
     p.add_argument("--prompt", default=PROMPT)
-    p.add_argument("--fps",
-                   type=float,
-                   default=24.0,
+    p.add_argument("--fps", type=float, default=24.0,
                    help="Frame-rate annotation passed to fps-aware metrics "
-                   "(e.g. vbench.dynamic_degree). LTX2 outputs at 24 fps "
-                   "by default.")
-    p.add_argument("--metrics",
-                   default=",".join(DEFAULT_METRICS),
+                        "(e.g. vbench.dynamic_degree). LTX2 outputs at 24 fps "
+                        "by default.")
+    p.add_argument("--metrics", default=",".join(DEFAULT_METRICS),
                    help="Comma-separated metric names. Pass 'all' for every "
-                   "registered metric, or e.g. 'vbench' for the whole group.")
+                        "registered metric, or e.g. 'vbench' for the whole group.")
     p.add_argument("--scores-out", default="outputs_video/ltx2_eval/scores.json")
-    p.add_argument("--skip-generation",
-                   action="store_true",
+    p.add_argument("--skip-generation", action="store_true",
                    help="Reuse an existing --output video instead of regenerating.")
     return p.parse_args()
 
@@ -113,10 +115,11 @@ def generate(args: argparse.Namespace) -> Path:
     return out
 
 
-def evaluate_video(video_path: Path, prompt: str, fps: float, metric_names) -> dict:
+def evaluate_video(video_path: Path, prompt: str, fps: float,
+                   metric_names) -> dict:
     print(f"[eval] loading video from {video_path}...")
-    video = load_video(str(video_path))  # (T, C, H, W) in [0, 1]
-    video = video.unsqueeze(0)  # → (1, T, C, H, W)
+    video = load_video(str(video_path))                  # (T, C, H, W) in [0, 1]
+    video = video.unsqueeze(0)                            # → (1, T, C, H, W)
 
     print(f"[eval] building evaluator: {metric_names}")
     evaluator = create_evaluator(metrics=metric_names, device="cuda")
@@ -129,9 +132,12 @@ def evaluate_video(video_path: Path, prompt: str, fps: float, metric_names) -> d
     )
 
     if isinstance(results, list):
-        results = results[0]  # batch of 1
+        results = results[0]                              # batch of 1
 
-    return {name: {"score": r.score, "details": r.details} for name, r in results.items()}
+    return {
+        name: {"score": r.score, "details": r.details}
+        for name, r in results.items()
+    }
 
 
 def main() -> None:
@@ -151,11 +157,7 @@ def main() -> None:
     out = Path(args.scores_out)
     out.parent.mkdir(parents=True, exist_ok=True)
     out.write_text(json.dumps(
-        {
-            "video": str(video_path),
-            "prompt": args.prompt,
-            "scores": scores
-        },
+        {"video": str(video_path), "prompt": args.prompt, "scores": scores},
         indent=2,
     ))
     print(f"[done] scores written to {out}")

examples/inference/eval/eval_third_person_separation.py

@@ -23,25 +23,19 @@ def _by_stem(directory: Path, exts: set[str]) -> dict[str, Path]:
 
 
 def main() -> None:
-    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
-    p.add_argument("--candidate-dir", type=Path, default=None, help="Directory of candidate clips (directory mode).")
-    p.add_argument("--reference",
-                   action="append",
-                   default=[],
-                   metavar="NAME=DIR",
+    p = argparse.ArgumentParser(description=__doc__,
+                                formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("--candidate-dir", type=Path, default=None,
+                   help="Directory of candidate clips (directory mode).")
+    p.add_argument("--reference", action="append", default=[], metavar="NAME=DIR",
                    help="Baseline directory, repeatable: 'name=dir' or bare 'dir'.")
-    p.add_argument("--image-dir",
-                   type=Path,
-                   default=None,
+    p.add_argument("--image-dir", type=Path, default=None,
                    help="Optional first-frame images, matched to clips by stem.")
-    p.add_argument("--prompts-json", type=Path, default=None, help="Optional {stem: control-signal text} JSON.")
-    p.add_argument("--actions-json",
-                   type=Path,
-                   default=None,
+    p.add_argument("--prompts-json", type=Path, default=None,
+                   help="Optional {stem: control-signal text} JSON.")
+    p.add_argument("--actions-json", type=Path, default=None,
                    help="Optional {stem: action-label} JSON for the per-action breakdown.")
-    p.add_argument("--manifest",
-                   type=Path,
-                   default=None,
+    p.add_argument("--manifest", type=Path, default=None,
                    help="JSON list of {baseline, video_path, reference_path, ...} rows.")
     p.add_argument("--output", type=Path, default=None)
     args = p.parse_args()
@@ -50,7 +44,8 @@ def main() -> None:
     by_baseline: dict[str, list[dict]] = defaultdict(list)
     if args.manifest is not None:
         for row in json.loads(args.manifest.read_text()):
-            by_baseline[row.get("baseline", "baseline")].append({k: v for k, v in row.items() if k != "baseline"})
+            by_baseline[row.get("baseline", "baseline")].append(
+                {k: v for k, v in row.items() if k != "baseline"})
     elif args.candidate_dir is not None and args.reference:
         cands = _by_stem(args.candidate_dir, VIDEO_EXTS)
         images = _by_stem(args.image_dir, IMAGE_EXTS) if args.image_dir else {}

examples/inference/eval/score_folder.py

@@ -34,15 +34,16 @@ def _list_videos(directory: Path) -> list[Path]:
 
 
 def main() -> None:
-    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
-    p.add_argument("--videos", type=Path, required=True, help="Directory of generated videos.")
-    p.add_argument("--reference-dir",
-                   type=Path,
-                   default=None,
+    p = argparse.ArgumentParser(description=__doc__,
+                                formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("--videos", type=Path, required=True,
+                   help="Directory of generated videos.")
+    p.add_argument("--reference-dir", type=Path, default=None,
                    help="Directory of reference videos with matching stems.")
     p.add_argument("--metrics", default="vbench.aesthetic_quality")
     p.add_argument("--num-gpus", type=int, default=1)
-    p.add_argument("--fps", type=float, default=None, help="Frame-rate annotation for fps-aware metrics.")
+    p.add_argument("--fps", type=float, default=None,
+                   help="Frame-rate annotation for fps-aware metrics.")
     p.add_argument("--output", type=Path, default=Path("scores.json"))
     args = p.parse_args()
 
@@ -51,8 +52,10 @@ def main() -> None:
         raise SystemExit(f"No videos under {args.videos}")
     print(f"Found {len(video_paths)} videos in {args.videos}")
 
-    metrics: list[str] | str = (args.metrics
-                                if args.metrics == "all" else [m.strip() for m in args.metrics.split(",") if m.strip()])
+    metrics: list[str] | str = (
+        args.metrics if args.metrics == "all"
+        else [m.strip() for m in args.metrics.split(",") if m.strip()]
+    )
     evaluator = create_evaluator(metrics=metrics, num_gpus=args.num_gpus)
 
     # Build per-video sample dicts holding *paths*, not pre-loaded
@@ -76,13 +79,13 @@ def main() -> None:
     all_results = evaluator.evaluate(samples=samples)
     evaluator.shutdown()
 
-    payload = [{
-        "video": str(vp),
-        "scores": {
-            name: r.score
-            for name, r in results.items()
-        },
-    } for vp, results in zip(video_paths, all_results)]
+    payload = [
+        {
+            "video": str(vp),
+            "scores": {name: r.score for name, r in results.items()},
+        }
+        for vp, results in zip(video_paths, all_results)
+    ]
     args.output.parent.mkdir(parents=True, exist_ok=True)
     args.output.write_text(json.dumps(payload, indent=2))
     print(f"Wrote {args.output}")

examples/inference/eval/score_video.py

@@ -25,26 +25,26 @@ from fastvideo.eval.io import load_video
 
 
 def main() -> None:
-    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    p = argparse.ArgumentParser(description=__doc__,
+                                formatter_class=argparse.RawDescriptionHelpFormatter)
     p.add_argument("--video", required=True, help="Path to the generated mp4.")
-    p.add_argument("--reference", default=None, help="Optional path to a reference mp4 (for paired metrics).")
-    p.add_argument("--metrics",
-                   default="common.psnr,common.ssim",
+    p.add_argument("--reference", default=None,
+                   help="Optional path to a reference mp4 (for paired metrics).")
+    p.add_argument("--metrics", default="common.psnr,common.ssim",
                    help="Comma-separated metric names, or a group name like 'vbench'.")
     p.add_argument("--device", default="cuda:0")
-    p.add_argument("--text-prompt",
-                   default=None,
+    p.add_argument("--text-prompt", default=None,
                    help="Text prompt for prompt-aware metrics "
-                   "(vbench.overall_consistency, etc.).")
-    p.add_argument("--fps",
-                   type=float,
-                   default=None,
+                        "(vbench.overall_consistency, etc.).")
+    p.add_argument("--fps", type=float, default=None,
                    help="Frame-rate annotation for fps-aware metrics "
-                   "(vbench.dynamic_degree, etc.).")
+                        "(vbench.dynamic_degree, etc.).")
     args = p.parse_args()
 
-    metrics: list[str] | str = (args.metrics if args.metrics in ("all", ) else
-                                [m.strip() for m in args.metrics.split(",") if m.strip()])
+    metrics: list[str] | str = (
+        args.metrics if args.metrics in ("all",)
+        else [m.strip() for m in args.metrics.split(",") if m.strip()]
+    )
     evaluator = create_evaluator(metrics=metrics, device=args.device)
 
     sample: dict = {"video": load_video(args.video)}
@@ -59,10 +59,7 @@ def main() -> None:
     evaluator.shutdown()
 
     print(json.dumps(
-        {
-            name: r.score
-            for name, r in results.items()
-        },
+        {name: r.score for name, r in results.items()},
         indent=2,
     ))
 

examples/inference/gradio/local/gradio_local_demo.py

@@ -8,15 +8,15 @@ from fastvideo.entrypoints.video_generator import VideoGenerator
 from fastvideo.api.sampling_param import SamplingParam
 from copy import deepcopy
 
+
 MODEL_PATH_MAPPING = {
     "FastWan2.1-T2V-1.3B": "FastVideo/FastWan2.1-T2V-1.3B-Diffusers",
     # "FastWan2.2-TI2V-5B-FullAttn": "FastVideo/FastWan2.2-TI2V-5B-FullAttn-Diffusers",
 }
 
-
 def create_timing_display(inference_time, total_time, stage_execution_times, num_frames):
     dit_denoising_time = f"{stage_execution_times[5]:.2f}s" if len(stage_execution_times) > 5 else "N/A"
-
+    
     timing_html = f"""
     <div style="margin: 10px 0;">
         <h3 style="text-align: center; margin-bottom: 10px;">⏱️ Timing Breakdown</h3>
@@ -47,7 +47,7 @@ def create_timing_display(inference_time, total_time, stage_execution_times, num
                 <div style="font-size: 18px; color: #0277bd;">{total_time:.2f}s</div>
             </div>
         </div>"""
-
+    
     if inference_time > 0:
         fps = num_frames / inference_time
         timing_html += f"""
@@ -55,10 +55,8 @@ def create_timing_display(inference_time, total_time, stage_execution_times, num
             <span style="font-weight: bold;">Generation Speed: </span>
             <span style="font-size: 18px; color: #6366f1; font-weight: bold;">{fps:.1f} frames/second</span>
         </div>"""
-
+    
     return timing_html + "</div>"
-
-
 def setup_model_environment(model_path: str) -> None:
     if "fullattn" in model_path.lower():
         os.environ["FASTVIDEO_ATTENTION_BACKEND"] = "FLASH_ATTN"
@@ -66,12 +64,10 @@ def setup_model_environment(model_path: str) -> None:
         os.environ["FASTVIDEO_ATTENTION_BACKEND"] = "VIDEO_SPARSE_ATTN"
     os.environ["FASTVIDEO_STAGE_LOGGING"] = "1"
 
-
 def load_example_prompts():
-
     def contains_chinese(text):
         return any('\u4e00' <= char <= '\u9fff' for char in text)
-
+    
     def load_from_file(filepath):
         prompts, labels = [], []
         try:
@@ -85,28 +81,27 @@ def load_example_prompts():
         except Exception as e:
             print(f"Warning: Could not read {filepath}: {e}")
         return prompts, labels
-
+    
     examples, example_labels = load_from_file("examples/inference/gradio/local/prompts_final.txt")
-
+    
     if not examples:
-        examples = [
-            "A crowded rooftop bar buzzes with energy, the city skyline twinkling like a field of stars in the background."
-        ]
+        examples = ["A crowded rooftop bar buzzes with energy, the city skyline twinkling like a field of stars in the background."]
         example_labels = ["Crowded rooftop bar at night"]
-
+    
     return examples, example_labels
 
 
 def create_gradio_interface(default_params: dict[str, SamplingParam], generators: dict[str, VideoGenerator]):
-
-    def generate_video(prompt, negative_prompt, use_negative_prompt, seed, guidance_scale, num_frames, height, width,
-                       randomize_seed, model_selection, progress):
+    def generate_video(
+        prompt, negative_prompt, use_negative_prompt, seed, guidance_scale,
+        num_frames, height, width, randomize_seed, model_selection, progress
+    ):
         model_path = MODEL_PATH_MAPPING.get(model_selection, "FastVideo/FastWan2.1-T2V-1.3B-Diffusers")
         setup_model_environment(model_path)
         try:
             if progress:
                 progress(0.1, desc="Loading model for local inference...")
-
+            
             generator = generators[model_path]
             params = deepcopy(default_params[model_path])
             total_start_time = time.time()
@@ -134,25 +129,20 @@ def create_gradio_interface(default_params: dict[str, SamplingParam], generators
             output_dir = "outputs/"
             os.makedirs(output_dir, exist_ok=True)
             start_time = time.time()
-            result = generator.generate_video(prompt=prompt,
-                                              sampling_param=params,
-                                              save_video=True,
-                                              return_frames=False)
+            result = generator.generate_video(prompt=prompt, sampling_param=params, save_video=True, return_frames=False)
             inference_time = time.time() - start_time
             logging_info = result.get("logging_info", None)
             if logging_info:
                 stage_names = logging_info.get_execution_order()
                 stage_execution_times = [
-                    logging_info.get_stage_info(stage_name).get("execution_time", 0.0) for stage_name in stage_names
+                    logging_info.get_stage_info(stage_name).get("execution_time", 0.0) 
+                    for stage_name in stage_names
                 ]
             else:
                 stage_names = []
                 stage_execution_times = []
             total_time = time.time() - total_start_time
-            timing_details = create_timing_display(inference_time=inference_time,
-                                                   total_time=total_time,
-                                                   stage_execution_times=stage_execution_times,
-                                                   num_frames=params.num_frames)
+            timing_details=create_timing_display(inference_time=inference_time, total_time=total_time, stage_execution_times=stage_execution_times, num_frames=params.num_frames)
             safe_prompt = params.prompt[:100].replace(' ', '_').replace('/', '_').replace('\\', '_')
             video_filename = f"{params.prompt[:100]}.mp4"
             output_path = os.path.join(output_dir, video_filename)
@@ -167,7 +157,7 @@ def create_gradio_interface(default_params: dict[str, SamplingParam], generators
             return None, f"Generation failed: {str(e)}", ""
 
     examples, example_labels = load_example_prompts()
-
+    
     theme = gr.themes.Base().set(
         button_primary_background_fill="#2563eb",
         button_primary_background_fill_hover="#1d4ed8",
@@ -175,7 +165,7 @@ def create_gradio_interface(default_params: dict[str, SamplingParam], generators
         slider_color="#2563eb",
         checkbox_background_color_selected="#2563eb",
     )
-
+    
     def get_default_values(model_name):
         model_path = MODEL_PATH_MAPPING.get(model_name)
         if model_path and model_path in default_params:
@@ -187,7 +177,7 @@ def create_gradio_interface(default_params: dict[str, SamplingParam], generators
                 'guidance_scale': params.guidance_scale,
                 'seed': params.seed,
             }
-
+        
         return {
             'height': 448,
             'width': 832,
@@ -195,9 +185,9 @@ def create_gradio_interface(default_params: dict[str, SamplingParam], generators
             'guidance_scale': 3.0,
             'seed': 1024,
         }
-
+    
     initial_values = get_default_values("FastWan2.1-T2V-1.3B")
-
+    
     with gr.Blocks(title="FastWan", theme=theme) as demo:
         gr.Image("assets/full.svg", show_label=False, container=False, height=80)
 
@@ -207,7 +197,7 @@ def create_gradio_interface(default_params: dict[str, SamplingParam], generators
             <p style="font-size: 18px;"> <a href="https://github.com/hao-ai-lab/FastVideo/tree/main" target="_blank">Code</a> | <a href="https://hao-ai-lab.github.io/blogs/fastvideo_post_training/" target="_blank">Blog</a> | <a href="https://hao-ai-lab.github.io/FastVideo/" target="_blank">Docs</a>  </p>
         </div>
         """)
-
+        
         with gr.Accordion("🎥 What Is FastVideo?", open=False):
             gr.HTML("""
             <div style="padding: 20px; line-height: 1.6;">
@@ -216,20 +206,24 @@ def create_gradio_interface(default_params: dict[str, SamplingParam], generators
                 </p>
             </div>
             """)
+        
+        with gr.Row():
+            model_selection = gr.Dropdown(
+                choices=list(MODEL_PATH_MAPPING.keys()),
+                value="FastWan2.1-T2V-1.3B",
+                label="Select Model",
+                interactive=True
+            )
 
         with gr.Row():
-            model_selection = gr.Dropdown(choices=list(MODEL_PATH_MAPPING.keys()),
-                                          value="FastWan2.1-T2V-1.3B",
-                                          label="Select Model",
-                                          interactive=True)
-
-        with gr.Row():
-            example_dropdown = gr.Dropdown(choices=example_labels,
-                                           label="Example Prompts",
-                                           value=None,
-                                           interactive=True,
-                                           allow_custom_value=False)
-
+            example_dropdown = gr.Dropdown(
+                choices=example_labels,
+                label="Example Prompts",
+                value=None,
+                interactive=True,
+                allow_custom_value=False
+            )
+        
         with gr.Row():
             with gr.Column(scale=6):
                 prompt = gr.Text(
@@ -243,7 +237,7 @@ def create_gradio_interface(default_params: dict[str, SamplingParam], generators
                 )
             with gr.Column(scale=1, min_width=120, elem_classes="center-button"):
                 run_button = gr.Button("Run", variant="primary", size="lg")
-
+        
         with gr.Row():
             with gr.Column():
                 error_output = gr.Text(label="Error", visible=False)
@@ -252,32 +246,38 @@ def create_gradio_interface(default_params: dict[str, SamplingParam], generators
         with gr.Row(equal_height=True, elem_classes="main-content-row"):
             with gr.Column(scale=1, elem_classes="advanced-options-column"):
                 with gr.Group():
-                    gr.HTML(
-                        "<div style='margin: 0 0 15px 0; text-align: center; font-size: 16px;'>Advanced Options</div>")
+                    gr.HTML("<div style='margin: 0 0 15px 0; text-align: center; font-size: 16px;'>Advanced Options</div>")
                     with gr.Row():
-                        height = gr.Number(label="Height",
-                                           value=initial_values['height'],
-                                           interactive=False,
-                                           container=True)
-                        width = gr.Number(label="Width",
-                                          value=initial_values['width'],
-                                          interactive=False,
-                                          container=True)
-
+                        height = gr.Number(
+                            label="Height",
+                            value=initial_values['height'],
+                            interactive=False,
+                            container=True
+                        )
+                        width = gr.Number(
+                            label="Width",
+                            value=initial_values['width'],
+                            interactive=False,
+                            container=True
+                        )
+                    
                     with gr.Row():
-                        num_frames = gr.Number(label="Number of Frames",
-                                               value=initial_values['num_frames'],
-                                               interactive=False,
-                                               container=True)
+                        num_frames = gr.Number(
+                            label="Number of Frames",
+                            value=initial_values['num_frames'],
+                            interactive=False,
+                            container=True
+                        )
                         guidance_scale = gr.Slider(
                             label="Guidance Scale",
                             minimum=1,
                             maximum=12,
                             value=initial_values['guidance_scale'],
                         )
-
+                    
                     with gr.Row():
-                        use_negative_prompt = gr.Checkbox(label="Use negative prompt", value=False)
+                        use_negative_prompt = gr.Checkbox(
+                            label="Use negative prompt", value=False)
                         negative_prompt = gr.Text(
                             label="Negative prompt",
                             max_lines=3,
@@ -295,15 +295,17 @@ def create_gradio_interface(default_params: dict[str, SamplingParam], generators
                     )
                     randomize_seed = gr.Checkbox(label="Randomize seed", value=False)
                     seed_output = gr.Number(label="Used Seed")
-
+        
             with gr.Column(scale=1, elem_classes="video-column"):
-                result = gr.Video(label="Generated Video",
-                                  show_label=True,
-                                  height=466,
-                                  width=600,
-                                  container=True,
-                                  elem_classes="video-component")
-
+                result = gr.Video(
+                    label="Generated Video", 
+                    show_label=True,
+                    height=466,
+                    width=600,
+                    container=True,
+                    elem_classes="video-component"
+                )
+        
         gr.HTML("""
         <style>
         .center-button {
@@ -434,37 +436,37 @@ def create_gradio_interface(default_params: dict[str, SamplingParam], generators
         }
         </style>
         """)
-
+        
         def on_example_select(example_label):
             if example_label and example_label in example_labels:
                 index = example_labels.index(example_label)
                 return examples[index]
             return ""
-
+        
         example_dropdown.change(
             fn=on_example_select,
             inputs=example_dropdown,
             outputs=prompt,
         )
-
+        
         gr.HTML("""
         <div style="text-align: center; margin-top: 10px; margin-bottom: 15px;">
             <p style="font-size: 16px; margin: 0;">Note that this demo is meant to showcase FastWan's quality and that under a large number of requests, generation speed may be affected.</p>
         </div>
         """)
-
+        
         use_negative_prompt.change(
             fn=lambda x: gr.update(visible=x),
             inputs=use_negative_prompt,
             outputs=negative_prompt,
         )
-
+        
         def on_model_selection_change(selected_model):
             if not selected_model:
                 selected_model = "FastWan2.1-T2V-1.3B"
-
+            
             model_path = MODEL_PATH_MAPPING.get(selected_model)
-
+            
             if model_path and model_path in default_params:
                 params = default_params[model_path]
                 return (
@@ -474,7 +476,7 @@ def create_gradio_interface(default_params: dict[str, SamplingParam], generators
                     gr.update(value=params.guidance_scale),
                     gr.update(value=params.seed),
                 )
-
+            
             return (
                 gr.update(value=448),
                 gr.update(value=832),
@@ -482,34 +484,35 @@ def create_gradio_interface(default_params: dict[str, SamplingParam], generators
                 gr.update(value=3.0),
                 gr.update(value=1024),
             )
-
+        
         model_selection.change(
             fn=on_model_selection_change,
             inputs=model_selection,
             outputs=[height, width, num_frames, guidance_scale, seed],
         )
-
+        
         def handle_generation(*args, progress=None, request: gr.Request = None):
             model_selection, prompt, negative_prompt, use_negative_prompt, seed, guidance_scale, num_frames, height, width, randomize_seed = args
-
-            result_path, seed_or_error, timing_details = generate_video(prompt, negative_prompt, use_negative_prompt,
-                                                                        seed, guidance_scale, num_frames, height, width,
-                                                                        randomize_seed, model_selection, progress)
+            
+            result_path, seed_or_error, timing_details = generate_video(
+                prompt, negative_prompt, use_negative_prompt, seed, guidance_scale, 
+                num_frames, height, width, randomize_seed, model_selection, progress
+            )
             if result_path and os.path.exists(result_path):
                 return (
-                    result_path,
-                    seed_or_error,
+                    result_path, 
+                    seed_or_error, 
                     gr.update(visible=False),
                     gr.update(visible=True, value=timing_details),
                 )
             else:
                 return (
-                    None,
-                    seed_or_error,
+                    None, 
+                    seed_or_error, 
                     gr.update(visible=True, value=seed_or_error),
                     gr.update(visible=False),
                 )
-
+        
         run_button.click(
             fn=handle_generation,
             inputs=[
@@ -527,18 +530,19 @@ def create_gradio_interface(default_params: dict[str, SamplingParam], generators
             outputs=[result, seed_output, error_output, timing_display],
             concurrency_limit=20,
         )
-
+    
     return demo
 
 
 def main():
     parser = argparse.ArgumentParser(description="FastVideo Gradio Local Demo")
-    parser.add_argument("--t2v_model_paths",
-                        type=str,
+    parser.add_argument("--t2v_model_paths", type=str,
                         default="FastVideo/FastWan2.1-T2V-1.3B-Diffusers",
                         help="Comma separated list of paths to the T2V model(s)")
-    parser.add_argument("--host", type=str, default="0.0.0.0", help="Host to bind to")
-    parser.add_argument("--port", type=int, default=7860, help="Port to bind to")
+    parser.add_argument("--host", type=str, default="0.0.0.0",
+                        help="Host to bind to")
+    parser.add_argument("--port", type=int, default=7860,
+                        help="Port to bind to")
     args = parser.parse_args()
     generators = {}
     default_params = {}
@@ -551,36 +555,40 @@ def main():
     demo = create_gradio_interface(default_params, generators)
     print(f"Starting Gradio frontend at http://{args.host}:{args.port}")
     print(f"T2V Models: {args.t2v_model_paths}")
-
+    
     from fastapi import FastAPI, Request, HTTPException
     from fastapi.responses import HTMLResponse, FileResponse
     import uvicorn
-
+    
     app = FastAPI()
-
+    
     @app.get("/logo.png")
     def get_logo():
-        return FileResponse("assets/full.svg",
-                            media_type="image/svg+xml",
-                            headers={
-                                "Cache-Control": "public, max-age=3600",
-                                "Access-Control-Allow-Origin": "*"
-                            })
-
+        return FileResponse(
+            "assets/full.svg",
+            media_type="image/svg+xml",
+            headers={
+                "Cache-Control": "public, max-age=3600",
+                "Access-Control-Allow-Origin": "*"
+            }
+        )
+    
     @app.get("/favicon.ico")
     def get_favicon():
         favicon_path = "assets/icon-simple.svg"
-
+        
         if os.path.exists(favicon_path):
-            return FileResponse(favicon_path,
-                                media_type="image/svg+xml",
-                                headers={
-                                    "Cache-Control": "public, max-age=3600",
-                                    "Access-Control-Allow-Origin": "*"
-                                })
+            return FileResponse(
+                favicon_path, 
+                media_type="image/svg+xml",
+                headers={
+                    "Cache-Control": "public, max-age=3600",
+                    "Access-Control-Allow-Origin": "*"
+                }
+            )
         else:
             raise HTTPException(status_code=404, detail="Favicon not found")
-
+    
     @app.get("/", response_class=HTMLResponse)
     def index(request: Request):
         base_url = str(request.base_url).rstrip('/')
@@ -632,16 +640,17 @@ def main():
         </body>
         </html>
         """
-
-    app = gr.mount_gradio_app(app,
-                              demo,
-                              path="/gradio",
-                              allowed_paths=[os.path.abspath("outputs"),
-                                             os.path.abspath("fastvideo-logos")])
-
+    
+    app = gr.mount_gradio_app(
+        app, 
+        demo, 
+        path="/gradio",
+        allowed_paths=[os.path.abspath("outputs"), os.path.abspath("fastvideo-logos")]
+    )
+    
     uvicorn.run(app, host=args.host, port=args.port)
 
 
 if __name__ == "__main__":
-
-    main()
+    
+    main() 

examples/inference/gradio/local/gradio_local_demo_ltx2_3/app.py

@@ -20,15 +20,15 @@ from .config import (
 )
 from .ui import create_gradio_interface
 
-
 def main():
     parser = argparse.ArgumentParser(description="FastVideo Gradio Local Demo")
-    parser.add_argument("--t2v_model_paths",
-                        type=str,
+    parser.add_argument("--t2v_model_paths", type=str,
                         default=MODEL_ID,
                         help="Comma separated list of paths to the T2V model(s)")
-    parser.add_argument("--host", type=str, default="0.0.0.0", help="Host to bind to")
-    parser.add_argument("--port", type=int, default=7860, help="Port to bind to")
+    parser.add_argument("--host", type=str, default="0.0.0.0",
+                        help="Host to bind to")
+    parser.add_argument("--port", type=int, default=7860,
+                        help="Port to bind to")
     args = parser.parse_args()
     gradio_temp_dir = os.path.abspath("outputs/gradio_tmp")
     os.makedirs(gradio_temp_dir, exist_ok=True)
@@ -71,46 +71,54 @@ def main():
             text_encoder_cpu_offload=False,
             ltx2_vae_tiling=False,
         )
-        default_params[model_path] = apply_ltx2_defaults(SamplingParam.from_pretrained(str(resolved_model_path)))
+        default_params[model_path] = apply_ltx2_defaults(
+            SamplingParam.from_pretrained(str(resolved_model_path))
+        )
     demo = create_gradio_interface(default_params, generators)
     print(f"Starting Gradio frontend at http://{args.host}:{args.port}")
     print(f"T2V Models: {args.t2v_model_paths}")
-
+    
     from fastapi import FastAPI, Request, HTTPException
     from fastapi.responses import HTMLResponse, FileResponse
     import uvicorn
-
+    
     app = FastAPI()
-
+    
     @app.get("/logo.png")
     def get_logo():
-        return FileResponse("assets/full.svg",
-                            media_type="image/svg+xml",
-                            headers={
-                                "Cache-Control": "public, max-age=3600",
-                                "Access-Control-Allow-Origin": "*"
-                            })
+        return FileResponse(
+            "assets/full.svg",
+            media_type="image/svg+xml",
+            headers={
+                "Cache-Control": "public, max-age=3600",
+                "Access-Control-Allow-Origin": "*"
+            }
+        )
 
     @app.get("/nvidia.png")
     def get_nvidia_logo():
-        return FileResponse("assets/nv.png",
-                            media_type="image/png",
-                            headers={
-                                "Cache-Control": "public, max-age=3600",
-                                "Access-Control-Allow-Origin": "*"
-                            })
-
+        return FileResponse(
+            "assets/nv.png",
+            media_type="image/png",
+            headers={
+                "Cache-Control": "public, max-age=3600",
+                "Access-Control-Allow-Origin": "*"
+            }
+        )
+    
     @app.get("/favicon.ico")
     def get_favicon():
         favicon_path = "assets/icon-simple.svg"
-
+        
         if os.path.exists(favicon_path):
-            return FileResponse(favicon_path,
-                                media_type="image/svg+xml",
-                                headers={
-                                    "Cache-Control": "public, max-age=3600",
-                                    "Access-Control-Allow-Origin": "*"
-                                })
+            return FileResponse(
+                favicon_path, 
+                media_type="image/svg+xml",
+                headers={
+                    "Cache-Control": "public, max-age=3600",
+                    "Access-Control-Allow-Origin": "*"
+                }
+            )
         else:
             raise HTTPException(status_code=404, detail="Favicon not found")
 
@@ -130,7 +138,7 @@ def main():
                 "Access-Control-Allow-Origin": "*",
             },
         )
-
+    
     @app.get("/", response_class=HTMLResponse)
     def index(request: Request):
         base_url = str(request.base_url).rstrip('/')
@@ -202,14 +210,16 @@ def main():
         </body>
         </html>
         """
-
-    app = gr.mount_gradio_app(app,
-                              demo,
-                              path="/gradio",
-                              allowed_paths=[
-                                  os.path.abspath("outputs"),
-                                  os.path.abspath("outputs_video"),
-                                  os.path.abspath("fastvideo-logos"),
-                              ])
-
+    
+    app = gr.mount_gradio_app(
+        app, 
+        demo, 
+        path="/gradio",
+        allowed_paths=[
+            os.path.abspath("outputs"),
+            os.path.abspath("outputs_video"),
+            os.path.abspath("fastvideo-logos"),
+        ]
+    )
+    
     uvicorn.run(app, host=args.host, port=args.port)

examples/inference/gradio/local/gradio_local_demo_ltx2_3/config.py

@@ -7,10 +7,19 @@ import torch._inductor.config
 from fastvideo import SamplingParam
 
 LOCAL_DEMO_DIR = Path(__file__).resolve().parent
-CLASSIFIER_DIR = Path(os.path.expandvars(os.path.expanduser(os.getenv("LTX2_CLASSIFIER_DIR", str(LOCAL_DEMO_DIR)))))
+CLASSIFIER_DIR = Path(
+    os.path.expandvars(
+        os.path.expanduser(
+            os.getenv("LTX2_CLASSIFIER_DIR", str(LOCAL_DEMO_DIR))
+        )
+    )
+)
 
 MODEL_ID = os.path.expandvars(
-    os.path.expanduser(os.getenv("LTX2_3_MODEL_PATH", "FastVideo/LTX-2.3-Distilled-Diffusers")))
+    os.path.expanduser(
+        os.getenv("LTX2_3_MODEL_PATH", "FastVideo/LTX-2.3-Distilled-Diffusers")
+    )
+)
 MODEL_PATH_MAPPING = {
     "FastLTX-2.3": MODEL_ID,
 }
@@ -35,7 +44,6 @@ config.coordinate_descent_tuning = True
 config.coordinate_descent_check_all_directions = True
 config.epilogue_fusion = False
 
-
 def apply_ltx2_defaults(params: SamplingParam) -> SamplingParam:
     params.height = DEFAULT_HEIGHT
     params.width = DEFAULT_WIDTH
@@ -47,11 +55,9 @@ def apply_ltx2_defaults(params: SamplingParam) -> SamplingParam:
     params.negative_prompt = DEFAULT_NEGATIVE_PROMPT
     return params
 
-
 def resolve_model_path(model_path: str) -> Path:
     return Path(os.path.expandvars(os.path.expanduser(model_path)))
 
-
 def resolve_refine_upsampler_path(model_path: Path) -> Path:
     candidates = [
         model_path / "spatial_upscaler",
@@ -62,18 +68,21 @@ def resolve_refine_upsampler_path(model_path: Path) -> Path:
 
     env_path = os.getenv("LTX2_REFINE_UPSAMPLER_PATH")
     if env_path:
-        candidates.insert(0, Path(os.path.expandvars(os.path.expanduser(env_path))))
+        candidates.insert(
+            0, Path(os.path.expandvars(os.path.expanduser(env_path)))
+        )
 
     for candidate in candidates:
         if (candidate / "config.json").is_file():
             return candidate
 
     checked = "\n".join(f"  - {candidate}" for candidate in candidates)
-    raise FileNotFoundError("Could not find an LTX2 refine upsampler directory.\n"
-                            "Checked:\n"
-                            f"{checked}\n"
-                            "Set LTX2_REFINE_UPSAMPLER_PATH or update REFINE_UPSAMPLER_PATH.")
-
+    raise FileNotFoundError(
+        "Could not find an LTX2 refine upsampler directory.\n"
+        "Checked:\n"
+        f"{checked}\n"
+        "Set LTX2_REFINE_UPSAMPLER_PATH or update REFINE_UPSAMPLER_PATH."
+    )
 
 def setup_model_environment(model_path: str) -> None:
     _ = model_path

examples/inference/gradio/local/gradio_local_demo_ltx2_3/download_fasttext_classifiers.py

@@ -21,16 +21,14 @@ class ClassifierSpec:
 
 
 CLASSIFIERS = {
-    "nsfw":
-    ClassifierSpec(
+    "nsfw": ClassifierSpec(
         name="nsfw",
         repo_id="allenai/dolma-jigsaw-fasttext-bigrams-nsfw",
         source_filename="model.bin",
         target_filename="jigsaw_fasttext_bigrams_nsfw_final.bin",
         env_var="LTX2_NSFW_CLASSIFIER_PATH",
     ),
-    "hatespeech":
-    ClassifierSpec(
+    "hatespeech": ClassifierSpec(
         name="hatespeech",
         repo_id="allenai/dolma-jigsaw-fasttext-bigrams-hatespeech",
         source_filename="model.bin",
@@ -50,14 +48,20 @@ def default_output_dir() -> Path:
 
 
 def parse_args() -> argparse.Namespace:
-    parser = argparse.ArgumentParser(description=("Download the fastText safety classifiers used by "
-                                                  "gradio_local_demo_ltx2_3.py."))
+    parser = argparse.ArgumentParser(
+        description=(
+            "Download the fastText safety classifiers used by "
+            "gradio_local_demo_ltx2_3.py."
+        )
+    )
     parser.add_argument(
         "--output-dir",
         type=Path,
         default=default_output_dir(),
-        help=("Directory where the demo looks for classifiers. Defaults to "
-              "LTX2_CLASSIFIER_DIR or the local Gradio demo directory."),
+        help=(
+            "Directory where the demo looks for classifiers. Defaults to "
+            "LTX2_CLASSIFIER_DIR or the local Gradio demo directory."
+        ),
     )
     parser.add_argument(
         "--classifier",
@@ -104,8 +108,10 @@ def download_classifier(
         print(f"[skip] {spec.name}: {destination}")
         return destination
 
-    print(f"[download] {spec.name}: "
-          f"{spec.repo_id}/{spec.source_filename}")
+    print(
+        f"[download] {spec.name}: "
+        f"{spec.repo_id}/{spec.source_filename}"
+    )
     cached_path = Path(
         hf_hub_download(
             repo_id=spec.repo_id,
@@ -113,7 +119,8 @@ def download_classifier(
             cache_dir=cache_dir,
             force_download=force,
             token=token,
-        ))
+        )
+    )
     materialize_download(cached_path, destination)
     print(f"[ready] {spec.name}: {destination}")
     return destination
@@ -131,7 +138,9 @@ def print_summary(
     print("\nThese filenames are auto-discovered by gradio_local_demo_ltx2_3.py.")
 
     if output_dir != default_output_dir():
-        print("\nBecause you used a custom output directory, point the demo to it:")
+        print(
+            "\nBecause you used a custom output directory, point the demo to it:"
+        )
         print(f'  export LTX2_CLASSIFIER_DIR="{output_dir}"')
 
     for spec, path in zip(selected_specs, downloaded_paths, strict=True):
@@ -155,7 +164,8 @@ def main() -> None:
             cache_dir=cache_dir,
             force=args.force,
             token=args.token,
-        ) for spec in selected_specs
+        )
+        for spec in selected_specs
     ]
     print_summary(selected_specs, output_dir, downloaded_paths)
 

examples/inference/gradio/local/gradio_local_demo_ltx2_3/examples.py

@@ -1,7 +1,6 @@
 import json
 import os
 
-
 def load_example_prompts():
     examples: list[str] = []
     example_labels: list[str] = []
@@ -24,7 +23,9 @@ def load_example_prompts():
                 if not prompt:
                     continue
                 examples.append(prompt)
-                example_labels.append(prompt[:100] + "..." if len(prompt) > 100 else prompt)
+                example_labels.append(
+                    prompt[:100] + "..." if len(prompt) > 100 else prompt
+                )
     except Exception as e:
         print(f"Warning: Could not read {prompts_path}: {e}")
 
@@ -51,7 +52,9 @@ def load_example_prompts():
                 if not caption:
                     continue
                 examples.append(caption)
-                example_labels.append(caption[:100] + "..." if len(caption) > 100 else caption)
+                example_labels.append(
+                    caption[:100] + "..." if len(caption) > 100 else caption
+                )
         except Exception as e:
             print(f"Warning: Could not read {validation_path}: {e}")
 

examples/inference/gradio/local/gradio_local_demo_ltx2_3/prompt_enhancer.py

@@ -14,7 +14,9 @@ except ImportError:  # pragma: no cover - optional dependency
     Cerebras = None  # type: ignore[assignment]
 
 LOCAL_DEMO_DIR = Path(__file__).resolve().parent
-DEFAULT_SYSTEM_PROMPT_PATH = (LOCAL_DEMO_DIR / "prompts" / "prompt_extension_system_prompt.md")
+DEFAULT_SYSTEM_PROMPT_PATH = (
+    LOCAL_DEMO_DIR / "prompts" / "prompt_extension_system_prompt.md"
+)
 DEFAULT_PROVIDER = "cerebras"
 DEFAULT_MODEL = "gpt-oss-120b"
 DEFAULT_TEMPERATURE = 1.0
@@ -81,13 +83,19 @@ def _load_prompt_required(path: str, prompt_name: str) -> str:
         try:
             text = candidate.read_text(encoding="utf-8").strip()
         except OSError as exc:
-            raise RuntimeError(f"Failed to read {prompt_name} system prompt: {candidate}") from exc
+            raise RuntimeError(
+                f"Failed to read {prompt_name} system prompt: {candidate}"
+            ) from exc
         if not text:
-            raise RuntimeError(f"{prompt_name} system prompt file is empty: {candidate}")
+            raise RuntimeError(
+                f"{prompt_name} system prompt file is empty: {candidate}"
+            )
         return text
 
     tried = ", ".join(str(candidate) for candidate in candidate_paths)
-    raise RuntimeError(f"{prompt_name} system prompt file not found. Tried: {tried}")
+    raise RuntimeError(
+        f"{prompt_name} system prompt file not found. Tried: {tried}"
+    )
 
 
 def _extract_assistant_content(response_json: dict[str, Any]) -> str:
@@ -121,8 +129,10 @@ def _extract_assistant_content(response_json: dict[str, Any]) -> str:
 
     finish_reason = choices[0].get("finish_reason")
     refusal = message.get("refusal")
-    raise ValueError("Missing assistant content in chat completion response. "
-                     f"finish_reason={finish_reason!r}, refusal={refusal!r}")
+    raise ValueError(
+        "Missing assistant content in chat completion response. "
+        f"finish_reason={finish_reason!r}, refusal={refusal!r}"
+    )
 
 
 def _dump_response_json(response: Any) -> dict[str, Any]:
@@ -133,11 +143,15 @@ def _dump_response_json(response: Any) -> dict[str, Any]:
     elif hasattr(response, "dict"):
         payload = response.dict()
     else:
-        raise TypeError("Unsupported chat completion response type. "
-                        f"type={type(response)!r}")
+        raise TypeError(
+            "Unsupported chat completion response type. "
+            f"type={type(response)!r}"
+        )
 
     if not isinstance(payload, dict):
-        raise TypeError("Chat completion response did not serialize to a JSON object.")
+        raise TypeError(
+            "Chat completion response did not serialize to a JSON object."
+        )
     return payload
 
 
@@ -189,7 +203,6 @@ def _normalize_prompt(value: Any) -> str:
 
 
 class PromptEnhancer:
-
     def __init__(self) -> None:
         self.provider = DEFAULT_PROVIDER
         self.provider_label = DEFAULT_PROVIDER
@@ -202,8 +215,9 @@ class PromptEnhancer:
             "LTX2_PROMPT_TEMPERATURE",
             DEFAULT_TEMPERATURE,
         )
-        self.system_prompt_path = _env_value("LTX2_PROMPT_EXTENSION_SYSTEM_PROMPT_PATH") or str(
-            DEFAULT_SYSTEM_PROMPT_PATH)
+        self.system_prompt_path = _env_value(
+            "LTX2_PROMPT_EXTENSION_SYSTEM_PROMPT_PATH"
+        ) or str(DEFAULT_SYSTEM_PROMPT_PATH)
         self.client: Any | None = None
         self.system_prompt: str | None = None
         self.unavailable_reason: str | None = None
@@ -223,10 +237,14 @@ class PromptEnhancer:
 
     def _build_client(self) -> Any:
         if Cerebras is None:
-            raise RuntimeError("Cerebras SDK is not installed. Install "
-                               "'cerebras-cloud-sdk' to use prompt enhancement.")
+            raise RuntimeError(
+                "Cerebras SDK is not installed. Install "
+                "'cerebras-cloud-sdk' to use prompt enhancement."
+            )
         if not self.api_key:
-            raise RuntimeError("Missing FASTVIDEO_PROMPT_API_KEY or CEREBRAS_API_KEY.")
+            raise RuntimeError(
+                "Missing FASTVIDEO_PROMPT_API_KEY or CEREBRAS_API_KEY."
+            )
         return Cerebras(api_key=self.api_key)
 
     def _build_body(
@@ -242,14 +260,11 @@ class PromptEnhancer:
                 "single 5-second LTX-2.3 video. Respond with valid JSON "
                 'only as {"prompt": "..."}.'  # noqa: E501
             ),
-            "user_prompt":
-            user_prompt,
+            "user_prompt": user_prompt,
         }
         return {
-            "model":
-            model or self.model,
-            "temperature":
-            self.temperature,
+            "model": model or self.model,
+            "temperature": self.temperature,
             "messages": [
                 {
                     "role": "system",
@@ -270,7 +285,10 @@ class PromptEnhancer:
         model: str | None = None,
     ) -> tuple[dict[str, Any], str]:
         if self.client is None:
-            raise RuntimeError(self.unavailable_reason or "Prompt enhancement client is not initialized.")
+            raise RuntimeError(
+                self.unavailable_reason
+                or "Prompt enhancement client is not initialized."
+            )
 
         body = self._build_body(
             system_prompt=system_prompt,
@@ -314,7 +332,10 @@ class PromptEnhancer:
             return EnhanceResult(
                 prompt="",
                 fallback_used=True,
-                error=(self.unavailable_reason or "Prompt enhancement system prompt is unavailable."),
+                error=(
+                    self.unavailable_reason
+                    or "Prompt enhancement system prompt is unavailable."
+                ),
                 provider=self.provider_label,
                 model=self.model,
                 latency_ms=0.0,
@@ -342,8 +363,10 @@ class PromptEnhancer:
         except Exception as exc:
             error_detail = str(exc)
             if isinstance(response_content, str) and response_content.strip():
-                error_detail = (f"{error_detail} | assistant_response="
-                                f"{_preview_text(response_content, limit=240)}")
+                error_detail = (
+                    f"{error_detail} | assistant_response="
+                    f"{_preview_text(response_content, limit=240)}"
+                )
             latency_ms = (time.perf_counter() - t0) * 1000.0
             return EnhanceResult(
                 prompt="",

examples/inference/gradio/local/gradio_local_demo_ltx2_3/prompt_rewrite.py

@@ -2,12 +2,10 @@ from functools import lru_cache
 
 from .prompt_enhancer import PromptEnhancer
 
-
 @lru_cache(maxsize=1)
 def get_prompt_enhancer() -> PromptEnhancer:
     return PromptEnhancer()
 
-
 def maybe_enhance_prompt(
     prompt: str,
     curated_prompts: set[str],
@@ -17,20 +15,28 @@ def maybe_enhance_prompt(
         return normalized_prompt
 
     if normalized_prompt in curated_prompts:
-        print("[ENHANCE][INFO] Skipping prompt enhancement for curated prompt.")
+        print(
+            "[ENHANCE][INFO] Skipping prompt enhancement for curated prompt."
+        )
         return normalized_prompt
 
     enhancer = get_prompt_enhancer()
     if not enhancer.api_key:
-        raise RuntimeError("Prompt enhancement is enabled for custom prompts, but "
-                           "FASTVIDEO_PROMPT_API_KEY or CEREBRAS_API_KEY is not set.")
+        raise RuntimeError(
+            "Prompt enhancement is enabled for custom prompts, but "
+            "FASTVIDEO_PROMPT_API_KEY or CEREBRAS_API_KEY is not set."
+        )
 
     result = enhancer.enhance_prompt(normalized_prompt)
     if result.fallback_used or not result.prompt.strip():
-        print("[ENHANCE][WARN] Falling back to raw prompt "
-              f"error={result.error}")
+        print(
+            "[ENHANCE][WARN] Falling back to raw prompt "
+            f"error={result.error}"
+        )
         return normalized_prompt
 
-    print("[ENHANCE][INFO] Prompt enhanced "
-          f"latency={result.latency_ms:.2f}ms model={result.model}")
+    print(
+        "[ENHANCE][INFO] Prompt enhanced "
+        f"latency={result.latency_ms:.2f}ms model={result.model}"
+    )
     return result.prompt.strip()

examples/inference/gradio/local/gradio_local_demo_ltx2_3/rendering.py

@@ -3,7 +3,6 @@ from pathlib import Path
 
 from .config import DEFAULT_FPS, GENERATED_CLIP_ROOT, MAX_SESSION_CLIPS
 
-
 def create_timing_display(inference_time, total_time, stage_execution_times, num_frames):
     timing_html = f"""
     <div class="timing-shell">
@@ -19,7 +18,7 @@ def create_timing_display(inference_time, total_time, stage_execution_times, num
                 <div style="font-size: 18px; color: #0277bd;">{total_time:.1f}s</div>
             </div>
         </div>"""
-
+    
     if inference_time > 0:
         fps = num_frames / inference_time
         timing_html += f"""
@@ -27,10 +26,9 @@ def create_timing_display(inference_time, total_time, stage_execution_times, num
             <span style="font-weight: bold;">Generation Speed: </span>
             <span style="font-size: 18px; color: #6366f1; font-weight: bold;">{fps:.1f} frames/second</span>
         </div>"""
-
+    
     return timing_html + "</div>"
 
-
 def create_timing_placeholder() -> str:
     return """
     <div class="timing-shell">
@@ -51,23 +49,19 @@ def create_timing_placeholder() -> str:
     </div>
     """
 
-
 def _truncate_text(value: str, max_chars: int) -> str:
     if len(value) <= max_chars:
         return value
-    return value[:max_chars - 1].rstrip() + "..."
-
+    return value[: max_chars - 1].rstrip() + "..."
 
 def _clip_duration_seconds(num_frames: int, fps: int) -> int:
     return max(1, round(num_frames / max(fps, 1)))
 
-
 def _make_clip_public_path(output_path: str) -> str:
     resolved_path = Path(output_path).resolve()
     relative_path = resolved_path.relative_to(GENERATED_CLIP_ROOT.resolve())
     return f"/generated-clips/{relative_path.as_posix()}"
 
-
 def _record_session_clip(
     session_clips: list[dict[str, str | int | float]],
     *,
@@ -92,7 +86,6 @@ def _record_session_clip(
         updated_clips = updated_clips[-MAX_SESSION_CLIPS:]
     return updated_clips
 
-
 def render_completed_clips(clips: list[dict[str, str | int | float]]) -> str:
     if not clips:
         return """
@@ -111,7 +104,8 @@ def render_completed_clips(clips: list[dict[str, str | int | float]]) -> str:
         prompt_preview = html.escape(str(clip["prompt_preview"]))
         model_name = html.escape(str(clip["model_name"]))
         duration_label = html.escape(str(clip["duration_label"]))
-        cards.append(f"""
+        cards.append(
+            f"""
             <article class="completed-clip-card">
                 <div class="completed-clip-video-shell">
                     <video class="completed-clip-video" src="{video_url}" controls preload="metadata" playsinline></video>
@@ -128,7 +122,8 @@ def render_completed_clips(clips: list[dict[str, str | int | float]]) -> str:
                     </details>
                 </div>
             </article>
-            """)
+            """
+        )
 
     return f"""
     <div class="completed-clips-grid">
@@ -136,7 +131,6 @@ def render_completed_clips(clips: list[dict[str, str | int | float]]) -> str:
     </div>
     """
 
-
 def render_error_message(message: str) -> str:
     return f"""
     <div class="stage-error-card">
@@ -145,16 +139,17 @@ def render_error_message(message: str) -> str:
     </div>
     """
 
-
 def render_prompt_blocked_message(
     message: str,
     category: str | None = None,
 ) -> str:
     details = ""
     if category:
-        details = ('<div class="stage-error-copy">'
-                   f"Policy: {html.escape(category)}"
-                   "</div>")
+        details = (
+            '<div class="stage-error-copy">'
+            f"Policy: {html.escape(category)}"
+            "</div>"
+        )
     return f"""
     <div class="stage-error-card">
         <div class="stage-error-title">Prompt Blocked</div>
@@ -163,12 +158,13 @@ def render_prompt_blocked_message(
     </div>
     """
 
-
 def render_input_image_status(input_image: str | None) -> str:
     if not input_image:
         return ""
 
     image_name = html.escape(Path(str(input_image)).name)
-    return ("<div class='image-upload-status'>"
-            f"Image ready: {image_name}"
-            "</div>")
+    return (
+        "<div class='image-upload-status'>"
+        f"Image ready: {image_name}"
+        "</div>"
+    )