[bugfix]: unset GenerationRequest fields inherit model presets

Directly-constructed GenerationRequests marked every schema default as
explicit (normalize_generation_request bound the full serialization when
_fastvideo_explicit_paths was absent), so request_to_sampling_param
overwrote model preset values with schema defaults: FastWan DMD ran
3->50 steps, TurboDiffusion 4->50, stable-audio 100 steps/CFG7 ->
50/CFG1, and 1.3B Wan examples rendered 720x1280x125f with CFG off.

Fix at the root: SamplingConfig fields now default to None = "inherit
the model preset". None leaves are never bound as explicit paths — for
directly-constructed requests (normalize_generation_request) and for
parsed YAML/JSON (parse_config treats explicit null as unset, so
widening the types cannot let nulls stomp presets either). Dicts
emptied by the pruning are dropped too, so None-valued extensions
cannot resurface via the live-attribute read in
explicit_request_updates. The _SCHEMA_DEFAULT_UPDATES tolerance hack is
deleted (an explicitly-set field unsupported by a model's SamplingParam
now always fails loudly), and return_state is skipped in the update
loop since it is already translated to return_continuation_state.

Consumers of raw (pre-resolution) sampling fields are guarded: the
streaming server validates operator-pinned default_request.sampling
before the multi-minute model boot (run_server) and in build_app; its
segment negative_prompt merge preserves an explicit "" clear; the mock
server supplies concrete fallbacks; generate_async resolves the preset
so its advertised total_steps matches the actual run; the ray-serve
gradio demo passes "" to keep its no-negative-prompt default. Stale
schema-default claims in video_api/ServeConfig/openai.md docs updated.

Tests: test_preset_inheritance.py locks the contract (bare request
inherits preset; partial override; explicit value equal to an old
schema default wins; negative_prompt None-inherits/""-clears; parsed
nulls inherit; None-valued extensions are dropped; unsupported explicit
field raises) plus a build_app pin-validation test.

.agents/exploration/mstar-v2-roadmap.md

@@ -1,207 +0,0 @@
-# v2 ← M\*: Architecture Gap-Analysis & Improvement Roadmap
-
-**Status:** exploration, flagged for review. **Date:** 2026-06-19.
-**Source paper:** *M\*: A Modular, Extensible, Serving System for Multimodal Models* (arXiv 2606.12688,
-Stanford/UW/CMU; Jha, Sagan, Kamahori, …, Kasikci, S. Wang). It is a universal serving runtime for composite
-multimodal models built on the **Walk Graph** abstraction (a model is a dataflow graph `G`; a request is a
-*Walk* — a labeled subgraph — and the runtime executes walks). It beats vLLM-Omni (~20% lower T2I latency on
-**BAGEL**, up to 2.64× on I2I), SGLang-Omni (2.7× TTS throughput on **Qwen3-Omni**), and native V-JEPA2
-rollout (12.5×). It explicitly names **FastVideo's own** sparse/sliding-tile attention, xDiT/PipeFusion/USP,
-Inferix, and FlashDrive as techniques integratable into the graph runtime.
-
-**Method:** a 28-agent workflow — 6 parallel v2-subsystem maps → 10 M\*-dimension analyses, each
-*adversarially verified against the actual v2 code* → synthesis + a completeness critic. The critic's
-corrections and three P0 claims were then **spot-verified by hand** (file:line below). This doc folds those
-corrections in; it is the corrected, authoritative synthesis.
-
----
-
-## 1. Executive summary
-
-v2 already implements the **harder half** of M\*'s thesis and in several axes **exceeds** it:
-
-- v2's `Program` *is* M\*'s graph `G` (typed `ComponentNode`/`ModelLoopNode` + edges).
-- v2's `shared_weight_components` *is* M\*'s cross-Walk node sharing — BAGEL/Cosmos3/LTX2 each bind two
-  `ModelLoopNode`s to **one resident transformer** (`instance.component()` returns the same live object). This
-  is the exact MoT serving property the omni cards in this repo already express.
-- v2 adds three things M\* (serving-only) has **no equivalent for**: a required+validated per-loop **cost
-  model**, a non-negotiable **interleave bit-parity gate**, and an **integrated training plane** (RL→distill
-  flywheel driving the *same* serving Loop).
-- The `extend/` plugin seam (interceptors/observers/registry with capability negotiation) is precisely the
-  hook M\*'s "extensible / integrate FastVideo-STA, xDiT, Inferix, FlashDrive" call-out asks for — **v2
-  already has the seam M\* only gestures at.**
-
-What v2 lacks is M\*'s **declarative authoring layer above the substrate**, and — the key insight — *much of
-that substrate is already authored but inert*: v2 has declared the metadata for "minimum components per
-request" (`required_for`/`optional_for` on every omni card) and "branch as a cache axis" (`guidance_sig`,
-`CacheKey`) but **never wired it to an executor**. The substrate is ~80% built and switched off.
-
-**Highest-leverage cluster:** three small, parity-safe wires that turn on inert substrate and unblock the
-BAGEL/Qwen-Omni/Cosmos3 latency wins M\* measured **on the exact models this repo already runs** — plus one
-P1 that aligns v2 with the paper's headline "extensible" claim using a seam v2 already has.
-
-### Verified P0 correctness findings (spot-checked by hand)
-1. **Runner divergence (real bug).** `v2/runtime/engine.py:88` → `nodes = self.program.nodes`;
-   `v2/runtime/disaggregated.py:96` → `nodes = self.program.active_nodes(self.request)`. The inline and
-   disaggregated runners execute *different node sets*. ✅ confirmed.
-2. **EOS is faked.** `v2/recipes/omni/ar_loop.py` docstring says "done on EOS/max_tokens"; `next()` (`:46-48`)
-   checks **only** `max_tokens`. M\*'s marquee `DynamicLoop` use case (EOS) is unimplemented in the loop that
-   serves the Qwen-Omni Thinker/Talker and Cosmos3 reasoner. ✅ confirmed.
-3. **`required_for`/`optional_for` have zero runtime consumers** (grep outside `specs.py`/recipes/tests is
-   empty). The min-components metadata is declared on every card and never read. ✅ confirmed.
-
----
-
-## 2. Dimension table (corrected)
-
-| # | Dimension | v2 status | Gap | Priority | Effort | Payoff | Action |
-|---|---|---|---|---|---|---|---|
-| 1 | Min-components per request (`required_for` + `when_task`) | substrate built, **inert** | real, cheap | **P0** | S | Consume `required_for` in `active_nodes`; unify `engine.py:88` onto `active_nodes`; deliver via registry/card builder so all ~40 cards inherit it |
-| 2 | Real EOS + declarative `DynamicLoop` | early-exit emergent; **EOS faked** | real | **P0** | S | `ARDecodeLoop` honors `eos_id` + `req.sampling.stop`; add `LoopSpec.dynamic_stop` + `register_loop_stop`. **Training-enabling** (world-model rollout horizon) |
-| 3 | CFG/branch as label over one paged KV pool | absent (`PagedKVCache` is a counter) | real | **P1** | L | `(namespace,label)` paged store w/ one budget; reuse `guidance_sig` for hash (NOT `partition_field`); by-ref via existing `InProcKVConnector`. AR path only (diffusion has no KV) |
-| 4 | `extend/` plugin seam → integrate FastVideo-STA / Inferix | **seam exists, unused for attn** | real (paper headline) | **P1** | M | Expose FastVideo sparse/sliding-tile attention + Inferix block-diffusion as `Interceptor`/`EngineKind` plugins — the paper's named integration targets, on this repo's own code |
-| 5 | `ParitySpec.output_determinism` (C3 distributional) | C3 rung defined, **0 users** | real, dormant | **P1** | S | Add field; `compare_outputs` consults it. **Training-enabling** (SDE/FlowGRPO stochastic rollouts) |
-| 6 | Registry-driven delivery of #1 | present, not leveraged | integration | **P1** | S | Express `when_task`/min-components through `WorkflowRegistry`/card builders, not 3 bespoke recipe patches |
-| 7 | Serving conductor + pluggable data plane | conductor exists (`serving/http.py`); **single-process transport** | real | **P2** | L | v2 already has the step-scheduled worker surface; gap is ZeroMQ/Mooncake + direct worker→worker tensor routing (today `InProcKVConnector` only) |
-| 8 | Fleet/Dynamo placement + replicas | **live** (`deploy/fleet.py`,`dynamo.py`) | partial | **P2** | M | Fleet-level placement/affinity/replica is real & ≥M\*; missing piece is only the intra-engine `(node,Walk)→rank` map decoupled from model code |
-| 9 | Per-node TP / SP + cross-rank transport | axis vocab **exists** (`sp` incl.); not wired to runtime | partial | **P2** | XL | Wire declarative degrees into runtime; Wan/LTX are **SP-native** (TP is a no-op there); populate `parallel_plan_hash` on the serving cache path |
-| 10 | Named Walks + per-model state machine | `Program`=G, sharing real; no Walk/SM | real | **P2** | M | Defer until a *re-entrant* phase graph (Thinker↔Talker, rollout) needs it; #1 captures the min-components win without it |
-| 11 | Declarative `Parallel/Sequential/Loop` IR | imperative loop classes | real (authoring) | **P2** | M | Thin Section IR lowering to flat `Program`; scope to one AR recipe |
-| 12 | Streaming `ChunkPolicy` + `StreamBuffer` | causal-chunk emit **already ships** (`wan_causal`); `EdgeKind.STREAM` inert | real | **P2** | L | Declarative `ChunkPolicy` vocab over the existing chunk mechanism; needs concurrent producer/consumer runner (= pipelined scheduling). Inferix integration point |
-| 13 | Speculative deferred-termination; loop-spanning CUDA graphs; N+1 prefetch; attn double-buffer | absent / per-step capture (14 cards) | real | **P3** | L | Gate behind a real GPU executor; unobservable on CPU-toy CI; loop-span needs an `allows_interleaving=False` carve-out |
-| — | Cost model + interleave/consistency parity | **exceeds M\*** | none | **guard** | — | Do not regress; keep `step_cost_model` mandatory + `bit_identical` default |
-| — | Integrated training plane (flywheel, weight-sync) | **exceeds M\*** | none | **guard** | — | Protect train==serve loop identity with a toy fixture |
-
----
-
-## 3. P0/P1 deep-dives (sequenced)
-
-```
-PR-1 (P0) min-components ──┐
-PR-2 (P0) real EOS        ─┼─► prereqs for honest "DynamicLoop" + min-component claims; both training-enabling
-PR-3 (P1) output_determinism (independent)
-PR-5 (P1) extend/ plugin: FastVideo-STA / Inferix as Interceptors (independent; highest paper-alignment)
-PR-4 (P1) CFG-as-label paged pool ──► depends on PR-2 (AR loop is the only KV consumer)
-```
-PR-1, PR-2, PR-3, PR-5 are mutually independent; PR-4 depends on PR-2.
-
-### PR-1 (P0) — Turn on the inert min-components substrate + fix runner divergence
-- **Change.** Extend `Program.active_nodes(request)` (`v2/program/specs.py`) to also drop any node whose bound
-  `ComponentSpec.required_for` (`v2/card/specs.py:144`) excludes `request.task` (and isn't in `optional_for`).
-  **Fix the bug:** change `v2/runtime/engine.py:88` to `nodes = self.program.active_nodes(self.request)` so the
-  inline `ProgramRunner` matches `DisaggregatedRunner` (`disaggregated.py:96`). Deliver the `when_task` gating
-  through the **registry/card builder** (`recipes/__init__.py`, `program/workflow.py:WorkflowRegistry`) so all
-  ~40 cards inherit it uniformly — not three bespoke `program.py` patches.
-- **Why (this repo's models).** BAGEL T2I currently steps the AR-text loop and Cosmos3 t2v materializes the
-  reasoner even though the cards declare `transformer required_for={'reason','t2i'}`, `vae required_for={'t2i'}`.
-  On the GPU backend that is wasted resident-weight load + wasted steps on every single-modality request —
-  exactly M\*'s "execute the MINIMUM components per request," delivered by consuming existing metadata.
-- **Risk/invariant.** Validate in `ModelCard.validate()` that every active node's `reads` are produced by an
-  active node for each declared `TaskType` (avoid dropping a producer). Pure node-id filtering ⇒ serial and
-  interleaved still walk the same filtered list ⇒ §9.3 interleave bit-parity holds by construction. CPU-toy clean.
-
-### PR-2 (P0) — Real EOS + declarative `dynamic_stop`  *(also training-enabling)*
-- **Change.** In `v2/recipes/omni/ar_loop.py`, `advance()` reads the emitted token; if it equals the model
-  `eos_id` (toy backend exposes `EOS=0`) or matches `req.sampling.stop` (`params.py:21`, currently dead),
-  register termination; `next()` returns `Done()` on stop OR `max_tokens`. Add `StopRegistry` to `LoopState` +
-  `register_loop_stop(name)` to the `LoopContext` protocol (`contracts.py:204`) and to
-  `DisaggregatedRunner`'s `RuntimeLoopContext`. Add `LoopSpec.dynamic_stop: bool=False`, opt the AR cards in.
-- **Why.** The docstring-vs-code lie sits in the loop serving Qwen-Omni Thinker/Talker and the Cosmos3 reasoner;
-  M\*'s second named `DynamicLoop` use case (world-model **rollout horizon**) is exactly what `self_forcing` RL
-  needs — so this is both a serving-credibility fix and a training enabler (raise its payoff accordingly).
-- **Risk/invariant.** `dynamic_stop=False` is byte-identical back-compat. Must pass **all three** parity gates:
-  serial==interleaved AND disaggregated==inline. **Not** in this PR: speculative deferred-termination (unobservable
-  on CPU-toy, fights the interleave invariant — P3, gated on GPU executor).
-
-### PR-3 (P1) — `ParitySpec.output_determinism` (close the dormant C3 hole)  *(training-enabling)*
-- **Change.** Add `output_determinism: str = "bit_identical"` to `ParitySpec` (`card/specs.py:88`); make
-  `compare_outputs` (`parity/interleave_gate.py:54`) consult it (`bit_identical` → today's exact check;
-  `distributional` → a moment/tolerance check — land a simple moment match first; a real KS test is new code).
-- **Why.** `ConsistencyLevel.C3` is defined and used by zero recipes; an SDE/FlowGRPO stochastic rollout cannot
-  honestly declare its parity contract and would falsely fail the bit-identical gate. Additive; default unchanged.
-
-### PR-5 (P1) — Expose FastVideo's own attention + Inferix as `extend/` plugins  *(highest paper-alignment)*
-- **Change.** Use the existing `extend/{interceptors,observers,registry}.py` seam (capability-negotiated, with
-  per-(request,branch) `plugin_state` that already passes the interleave gate) to register FastVideo's
-  sparse/sliding-tile attention and Inferix-style block-diffusion as `Interceptor`s / an `EngineKind` plugin.
-- **Why.** M\*'s title is "Modular, **Extensible**" and it explicitly lists FastVideo-STA, xDiT/PipeFusion/USP,
-  Inferix, FlashDrive as integratable. v2 already has the seam M\* only describes — this is where v2 most
-  directly answers the paper, using this repo's own attention code. Low risk (the seam + capability negotiation
-  already exist and are tested).
-
-### PR-4 (P1) — CFG/branch as a LABEL over one paged KV pool
-- **Change.** Rewrite `PagedKVCache` (`cache/classes.py:155-172`) from a block *counter* into a real
-  `(namespace,label)->[block-handle]` store with **one shared `total_blocks` budget** (M\*'s single-pool
-  property). Reuse the existing-but-unpopulated `CacheKey.guidance_sig` (`keys.py:53`) for the hash. Thread the
-  label through `ar_loop.py` (alloc/append/get per `(request_id, branch)`; prefill once per shared-prefix label;
-  combine via `CFGPolicy.combine`). Wire `ResourceRequest.cache_blocks` (`contracts.py:64`, zero consumers) into
-  admission per (class,label).
-- **Why.** The dossier-identified driver of M\*'s BAGEL win (3 CFG contexts as 3 labels over ONE pool vs dense
-  per-context). Targets AR_DECODE (BAGEL `generate_text`, omni Thinker); **correctly excludes diffusion**
-  (Wan/LTX are bidirectional, no KV — their CFG stays dense-but-batched).
-- **Corrections to bake in.** Do **NOT** add `branch_label` to `CacheKey.partition_field()` (CFG branches share
-  embeddings; partitioning by branch is a semantic bug). Do **NOT** add a new by-ref type — reuse
-  `InProcKVConnector` + `TransferManifest.cache_key`. Wiring `cache_blocks` admission is greenfield ⇒ effort **L**.
-  CPU version proves label/sharing semantics; the real latency win needs a FlashInfer paged kernel (out of scope)
-  — **merge** with a future "real KVCacheEngine" effort rather than landing isolated.
-
----
-
-## 4. What v2 already does ≥ M\* — do NOT regress
-1. **Required+validated cost model** on every `LoopSpec` (13-kind `WorkUnitKind`) — typed, pre-GPU-validated.
-2. **Interleave bit-parity as a hard gate** (`parity.interleave_required=True` on 40+ cards). M\* has no such
-   gate (its speculative scheduling deliberately wastes steps). Load-bearing invariant; every new primitive
-   must pass it.
-3. **C0–C4 consistency ladder** wired into RL methods, with first-divergence tap reporting. No M\* equivalent.
-4. **Integrated training plane** — DiffusionNFT/DMD2/self_forcing, RL→distill flywheel, `WeightSyncController`
-   hot weight-sync with drain-to-boundary + scoped cache invalidation, driving the **same** serving Loop.
-   M\* is serving-only. Protect with a toy fixture asserting `rollout_loop` drives the served Loop object.
-5. **CPU-toy parity for the whole stack** — loops/CFG/caches/parity/RL run in CI without a GPU. Every new
-   primitive must ship a toy exercise (this is what makes all PRs above testable without H100s).
-6. **Partition-not-flush cache invalidation** + four independent per-class pools.
-7. **`extend/` plugin seam** with capability negotiation (a 4-step distilled card *rejects* a residual-skip
-   interceptor) — M\* describes extensibility; v2 has the mechanism.
-8. **Dynamo citizenship** (`deploy/dynamo.py`: one `DeploymentCard`+cost model, two consumers) — beyond M\*'s
-   self-contained runtime.
-
----
-
-## 5. Dropped / merged / deferred (and why)
-- **DROP declarative `Parallel` as a CFG-execution win.** The runner walks nodes linearly (ignores
-  `Program.edges`), so `Parallel` lowers to sequential sugar and the CFG 3-pass braid is already one
-  co-scheduled `WorkPlan.run`; splitting it risks the interleave gate. Salvage only the no-op refactor
-  extracting `branch_forward` from `WanDenoiseLoop._velocity`. Reassign `Parallel` to the placement workstream.
-- **MERGE the full Walk/state-machine layer** into "defer until a re-entrant phase graph needs it" (PR-1 gets the
-  min-components win with ~20 lines, no new abstraction). If built: the validator must check a walk's node-id
-  order is a *subsequence* of `program.nodes` (not just membership) or the runner can reorder and break parity.
-- **MERGE `StreamBuffer`/`ChunkPolicy` into pipelined-scheduling.** Causal-chunk emit *already ships*
-  (`wan_causal/loop.py` per-chunk `StepResult.emit` + slab-KV); the gap is the declarative `ChunkPolicy` vocab
-  + a concurrent producer/consumer runner. If built: keep all policies pure (per-request `StreamBuffer` history,
-  not shared edge state) and restrict the bit-identical claim to the token-only handoff.
-- **MERGE CFG-fan-out exec + cross-rank transport + PD loop-splitting into a multi-GPU-runtime program.** These
-  need real collectives (`v2/distributed/` is a stub) and KV-by-reference (KV lives in `CacheManager`, not the
-  transferable `slots`). **Keep cheaply now:** the *declarative* halves — per-component degree, `(node,Walk)`
-  placement key with node-only fallback, `ReplicaSet` under `LocalFleet`, and populate `parallel_plan_hash` on
-  the **serving** cache path (it is already populated in `training/behavior.py:40` — the gap is serving-only).
-- **DEFER** speculative deferred-termination, loop-spanning CUDA graphs, N+1 prefetch, attention-plan
-  double-buffer — all gated on a real GPU executor; benefit unobservable on CPU-toy CI. Keep the cheap
-  `EngineKind` tag (`STATELESS|KV_CACHE|DIFFUSION`) now. Correct the stale `cudagraph.py:51-52` docstring
-  (per-step capture ships in 14 cards, not just wan21).
-- **RESCOPE per-node TP.** Wan/LTX use `ReplicatedLinear` + **sequence parallelism** (`sp`), not TP; the `sp`
-  axis already exists in `parallel/plan.py:AXIS_NAMES`. The work is wiring degrees into the runtime, not
-  inventing vocabulary; a `tp_size=2` "one-line activation" is a no-op for the shipped models.
-
----
-
-## 6. The first integration test, if/when multi-GPU placement work starts
-The **live Qwen-Omni 2-GPU bring-up** (Thinker on rank 0, Talker+Code2Wav on rank 1; see
-`v2_debug_videos/vlm.md` Session 4) is the natural first validation target for any `(node,Walk)→rank`
-placement work — it is the one place this repo already has real multi-rank composite-model execution.
-
----
-
-## Anchor files for P0/P1
-`v2/program/specs.py`, `v2/runtime/engine.py` (**line 88 fix**), `v2/runtime/disaggregated.py`,
-`v2/recipes/omni/ar_loop.py`, `v2/loop/contracts.py`, `v2/card/specs.py`, `v2/cache/{classes.py,keys.py}`,
-`v2/parity/interleave_gate.py`, `v2/extend/{interceptors,registry}.py`, `recipes/__init__.py` +
-`v2/program/workflow.py` (registry-driven delivery).

.agents/skills/reseed-performance-baseline/SKILL.md

@@ -69,7 +69,7 @@ approval, then upload reviewed accepted baseline records.
 | `model_id` | Yes | Benchmark id, e.g. `wan-t2v-1.3b-2gpu`. This maps to the HF subdirectory after `sanitize(model_id)`. |
 | `gpu_type` | Yes | Exact GPU device string from the performance record, e.g. the L40S device name emitted by CI. Baselines are GPU-specific. |
 | `source_results` | Yes | One or more local paths or Buildkite artifact URLs for accepted shifted performance JSONs. Prefer normalized `normalized_perf_*.json` artifacts emitted by `compare_baseline.py`. Accept `source_result` as an alias only for a single JSON. |
-| `max_intra_batch_regression` | No | Maximum allowed regression of any source JSON against the source batch median. Default: `PERF_MAX_REGRESSION` if set, otherwise `0.05` (5%). |
+| `max_intra_batch_regression` | No | Maximum allowed regression of any source JSON against the source batch median. Default: `0.05` (5%). |
 | `intent_rationale` | Yes | One-line explanation for why the baseline shift is legitimate. This is written into provenance and should be reused in the PR. |
 
 Hardcoded defaults:
@@ -148,8 +148,7 @@ For each metric with at least two non-null source values:
 4. Stop if any source record regresses against the batch median by more than
    `max_intra_batch_regression`.
 
-Default `max_intra_batch_regression` to `PERF_MAX_REGRESSION` when set,
-otherwise `0.05`. Print a table with per-source values, batch median, and
+Default `max_intra_batch_regression` to `0.05`. Print a table with per-source values, batch median, and
 worst intra-batch regression.
 
 This check prevents uploading a mixed batch where one JSON is materially
@@ -183,7 +182,7 @@ present, that run is not a valid source for baseline reseeding.
 
 ### 2. Sync and back up existing HF records under /tmp
 
-Use `fastvideo/tests/performance/hf_store.py` helpers directly. Do **not** use
+Use `fastvideo/performance/hf_store.py` helpers directly. Do **not** use
 `compare_baseline.py` as a sync shortcut; on full main runs it can persist
 records, while this step must only fetch and back up existing history.
 
@@ -192,7 +191,7 @@ The sync command pattern is:
 ```bash
 export PERFORMANCE_TRACKING_ROOT="${PERFORMANCE_TRACKING_ROOT:-/tmp/perf-tracking}"
 export HF_REPO_ID="${HF_REPO_ID:-FastVideo/performance-tracking}"
-PYTHONPATH=fastvideo/tests/performance python -c 'from hf_store import sync_from_hf; import os; sync_from_hf(os.environ["PERFORMANCE_TRACKING_ROOT"], strict=True)'
+python -c 'from fastvideo.performance.hf_store import sync_from_hf; import os; sync_from_hf(os.environ["PERFORMANCE_TRACKING_ROOT"], strict=True)'
 ```
 
 Then back up only the sanitized model directory under `/tmp`:
@@ -200,8 +199,8 @@ Then back up only the sanitized model directory under `/tmp`:
 ```bash
 SHORT_COMMIT=$(git rev-parse --short=12 HEAD)
 TIMESTAMP=$(date -u +%Y%m%d_%H%M%S)
-MODEL_SAFE=$(PYTHONPATH=fastvideo/tests/performance python - <<'PY'
-from hf_store import sanitize
+MODEL_SAFE=$(python - <<'PY'
+from fastvideo.performance.hf_store import sanitize
 print(sanitize("<model_id>"))
 PY
 )
@@ -235,7 +234,7 @@ first baseline seed. Continue, but report that baseline history was empty.
 Load the last 5 successful records for the target:
 
 ```python
-from hf_store import load_records_for_model
+from fastvideo.performance.hf_store import load_records_for_model
 
 records = load_records_for_model(
     "/tmp/perf-tracking",
@@ -372,7 +371,7 @@ prepared records plus backup on disk.
 Use the shared storage helper so the path and repo type match CI:
 
 ```python
-from hf_store import upload_record
+from fastvideo.performance.hf_store import upload_record
 
 upload_record("<local_record_path>", record, strict=True)
 ```
@@ -460,7 +459,7 @@ directories created for this reseed. Never remove unrelated `/tmp` contents.
   intentional baseline replacement.
 - `fastvideo/tests/performance/compare_baseline.py` — normalization, rolling
   median comparison, and persistence rules.
-- `fastvideo/tests/performance/hf_store.py` — HF sync, record loading,
+- `fastvideo/performance/hf_store.py` — HF sync, record loading,
   `sanitize()`, and `upload_record()`.
 - `fastvideo/tests/performance/test_inference_performance.py` — source result
   JSON schema.

.buildkite/performance-benchmarks/tests/wan-t2v-1.3b.json

@@ -1,5 +1,9 @@
 {
   "benchmark_id": "wan-t2v-1.3b-2gpu",
+  "config_schema_version": 2,
+  "workload_id": "wan-t2v",
+  "variant_id": "1.3b-sp2",
+  "benchmark_version": 2,
   "description": "Wan2.1 T2V 1.3B inference performance",
   "model": {
     "model_path": "Wan-AI/Wan2.1-T2V-1.3B-Diffusers",

.buildkite/pipeline.yml

@@ -114,6 +114,17 @@ steps:
             limit: 2
       agents:
         queue: "default"
+    - label: ":test_tube: LoRA Extraction Tests"
+      if: build.env("TEST_SCOPE") == "direct" && build.env("TEST_TYPE") == "lora_extraction"
+      command: "timeout 90m .buildkite/scripts/pr_test.sh"
+      retry:
+        automatic:
+          - exit_status: 128
+            limit: 3
+          - exit_status: -1
+            limit: 2
+      agents:
+        queue: "default"
     - label: ":test_tube: Training Tests"
       if: build.env("TEST_SCOPE") == "direct" && build.env("TEST_TYPE") == "training"
       command: "timeout 90m .buildkite/scripts/pr_test.sh"
@@ -371,6 +382,21 @@ steps:
                   - TEST_TYPE=inference_lora
                 agents:
                   queue: "default"
+            - path:
+                - "scripts/lora_extraction/**"
+                - "fastvideo/tests/lora_extraction/**"
+                - "fastvideo/models/loader/**"
+                - "fastvideo/training/training_utils.py"
+                - "fastvideo/layers/lora/**"
+                - "pyproject.toml"
+                - "docker/Dockerfile"
+              config:
+                command: "timeout 90m .buildkite/scripts/pr_test.sh"
+                label: ":test_tube: LoRA Extraction Tests"
+                env:
+                  - TEST_TYPE=lora_extraction
+                agents:
+                  queue: "default"
             - path:
                 - "fastvideo/**"
                 - "pyproject.toml"
@@ -455,6 +481,7 @@ steps:
                 - "fastvideo/layers/**"
                 - "fastvideo/worker/**"
                 - "fastvideo/entrypoints/**"
+                - "fastvideo/performance/**"
                 - "fastvideo/tests/performance/**"
                 - ".buildkite/performance-benchmarks/**"
                 - "pyproject.toml"

.buildkite/scripts/pr_test.sh

@@ -80,6 +80,23 @@ MODAL_ENV="BUILDKITE_REPO=$BUILDKITE_REPO BUILDKITE_COMMIT=$BUILDKITE_COMMIT BUI
 
 POST_RUN_HOOK=""
 
+is_truthy() {
+    case "${1:-}" in
+        1|true|TRUE|yes|YES|on|ON) return 0 ;;
+        *) return 1 ;;
+    esac
+}
+
+ssim_bootstrap_args() {
+    local title="${PR_TITLE:-}"
+    local message="${BUILDKITE_MESSAGE:-}"
+    if is_truthy "${FASTVIDEO_SSIM_BOOTSTRAP_MODE:-}" \
+        || [[ "$title" == *"[new-model]"* ]] \
+        || [[ "$message" == *"[new-model]"* ]]; then
+        printf ' --bootstrap-mode'
+    fi
+}
+
 upload_performance_artifacts() {
     SHORT_SHA=${BUILDKITE_COMMIT:0:7}
     LOCAL_DIR="downloaded_reports"
@@ -172,7 +189,12 @@ case "$TEST_TYPE" in
         ;;
     "ssim")
         log "Running SSIM tests..."
-        MODAL_COMMAND="$MODAL_ENV HF_API_KEY=$HF_API_KEY python3 -m modal run $MODAL_SSIM_TEST_FILE::run_ssim_tests"
+        SSIM_BOOTSTRAP_ARGS=$(ssim_bootstrap_args)
+        if [ -n "$SSIM_BOOTSTRAP_ARGS" ]; then
+            log "SSIM bootstrap mode enabled for new-model reference draft generation"
+        fi
+        MODAL_COMMAND="$MODAL_ENV HF_API_KEY=$HF_API_KEY python3 -m modal run "
+        MODAL_COMMAND+="$MODAL_SSIM_TEST_FILE::run_ssim_tests$SSIM_BOOTSTRAP_ARGS"
         ;;
     "training")
         log "Running training tests..."

.github/scripts/gate_full_suite.sh

@@ -0,0 +1,133 @@
+#!/usr/bin/env bash
+# Gate the expensive Buildkite full suite on the cheap GitHub checks.
+#
+# Polls the workflow runs for the PR head commit and only exits 0 once the
+# watched cheap workflows (pre-commit, docs build) have succeeded, so the
+# 'ready' label cannot burn ~20 GPU lanes on a head that a cheap check has
+# already doomed.
+#
+# Semantics:
+#   - watched run completed with a bad conclusion  -> exit 1 (fail CLOSED:
+#     no full suite; the next push re-arms via the 'synchronize' trigger)
+#   - watched run cancelled                         -> still pending: the docs
+#     workflow's repo-global 'pages' concurrency group cancels runs superseded
+#     by unrelated pushes, so 'cancelled' is not a verdict on this PR
+#   - watched runs pending                          -> poll until done
+#   - docs run absent                               -> not applicable after a
+#     short grace period ('Deploy Documentation' is path-filtered on PRs)
+#   - pre-commit run absent                         -> keep polling: pre-commit
+#     is never path-filtered, so its absence is always anomalous
+#   - 'ready' label removed while waiting           -> exit 1 (fail CLOSED:
+#     un-labeling is a deliberate maintainer action)
+#   - GitHub API unreachable or timeout             -> exit 0 (fail OPEN,
+#     loud warning: never brick CI on a GitHub outage)
+#
+# Required env: PR_SHA (PR head commit), PR_NUMBER, GITHUB_REPOSITORY, GH_TOKEN.
+set -euo pipefail
+
+: "${PR_SHA:?PR_SHA (PR head commit) is required}"
+: "${PR_NUMBER:?PR_NUMBER (pull request number) is required}"
+: "${GITHUB_REPOSITORY:?GITHUB_REPOSITORY is required}"
+
+# Workflow-level `name:` values that must be green before the full suite
+# may start. "Deploy Documentation" is path-filtered on PRs, so its run may
+# legitimately never exist; pre-commit always runs, so it must appear.
+WATCHED_NAMES='["pre-commit", "Deploy Documentation"]'
+WATCHED_REGEX='^(pre-commit|Deploy Documentation)$'
+POLL_SECS="${POLL_SECS:-20}"
+GRACE_SECS="${GRACE_SECS:-60}"
+MAX_WAIT_SECS="${MAX_WAIT_SECS:-1500}"
+
+# Bound each API call so a hung connection hits the 3-strike fail-open path
+# instead of pinning the loop until the job timeout (which would fail closed
+# on exactly the GitHub-outage case this script is meant to survive).
+if command -v timeout >/dev/null 2>&1; then
+  gh_api() { timeout 30 gh api "$@"; }
+else
+  gh_api() { gh api "$@"; }  # macOS dev boxes; CI always has coreutils timeout
+fi
+
+# The workflow checked the label before starting the gate, but the wait can
+# last ~25 min: re-check once before any exit 0 and fail closed if 'ready'
+# was removed in the meantime. An API error here proceeds (the label was
+# present when the gate started; never brick CI on an outage).
+recheck_ready_label() {
+  local pr_json
+  if pr_json=$(gh_api "repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}" 2>/dev/null); then
+    if ! jq -e '[.labels[]?.name] | index("ready")' <<<"$pr_json" >/dev/null 2>&1; then
+      echo "::error::PR #${PR_NUMBER} no longer has the 'ready' label —" \
+        "NOT triggering the Buildkite full suite. Re-add the label to re-arm."
+      exit 1
+    fi
+  else
+    echo "::warning::Could not re-check the 'ready' label on PR #${PR_NUMBER}; proceeding (it was present when the gate started)."
+  fi
+}
+
+start=$(date +%s)
+api_fails=0
+missing=""
+
+while true; do
+  elapsed=$(( $(date +%s) - start ))
+
+  if runs_json=$(gh_api "repos/${GITHUB_REPOSITORY}/actions/runs?head_sha=${PR_SHA}&per_page=100" 2>/dev/null) \
+     && state=$(jq --arg re "$WATCHED_REGEX" '
+          [.workflow_runs[]? | select(.name // "" | test($re))]
+          | group_by(.name) | map(max_by(.id))
+          | map({name, status, conclusion})' <<<"$runs_json" 2>/dev/null); then
+    api_fails=0
+    echo "t+${elapsed}s watched checks: $(jq -c . <<<"$state")"
+
+    failed=$(jq -r '[.[] | select(.status == "completed"
+          and (.conclusion | IN("success", "skipped", "neutral", "cancelled") | not))]
+        | map(.name) | join(", ")' <<<"$state")
+    if [ -n "$failed" ]; then
+      echo "::error::Cheap check(s) failed on ${PR_SHA}: ${failed}." \
+        "NOT triggering the Buildkite full suite. Push a fix (the 'ready'" \
+        "label re-arms on every push), or re-run the failed check and then" \
+        "re-run this workflow."
+      exit 1
+    fi
+
+    # 'cancelled' counts as pending: wait for a re-run to reach a real verdict
+    # (bounded by MAX_WAIT, then the fail-open below).
+    pending=$(jq '[.[] | select(.status != "completed" or .conclusion == "cancelled")] | length' <<<"$state")
+    missing=$(jq -r --argjson watched "$WATCHED_NAMES" '($watched - map(.name)) | join(", ")' <<<"$state")
+    if [ "$pending" -eq 0 ]; then
+      if [ -z "$missing" ]; then
+        recheck_ready_label
+        echo "All watched cheap checks are green — full suite may proceed."
+        exit 0
+      fi
+      case "$missing" in
+        *pre-commit*)
+          echo "pre-commit run not found for ${PR_SHA} yet; waiting (pre-commit is never path-filtered, so its absence is anomalous)."
+          ;;
+        *)
+          if [ "$elapsed" -ge "$GRACE_SECS" ]; then
+            recheck_ready_label
+            echo "::warning::Watched run(s) never appeared for ${PR_SHA}: ${missing} (path-filtered, likely not applicable). Proceeding on the checks that did run."
+            exit 0
+          fi
+          echo "Waiting up to ${GRACE_SECS}s grace for path-filtered run(s) to appear: ${missing}."
+          ;;
+      esac
+    fi
+  else
+    api_fails=$(( api_fails + 1 ))
+    echo "::warning::GitHub API error querying workflow runs for ${PR_SHA} (attempt ${api_fails}/3)."
+    if [ "$api_fails" -ge 3 ]; then
+      recheck_ready_label
+      echo "::warning::FAILING OPEN: cannot query GitHub check status — triggering the full suite WITHOUT the cheap-check gate."
+      exit 0
+    fi
+  fi
+
+  if [ "$elapsed" -ge "$MAX_WAIT_SECS" ]; then
+    recheck_ready_label
+    echo "::warning::FAILING OPEN: watched checks still pending after $(( MAX_WAIT_SECS / 60 )) min${missing:+ (never appeared: ${missing})} — triggering the full suite anyway."
+    exit 0
+  fi
+  sleep "$POLL_SECS"
+done

.github/scripts/test_gate_full_suite.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+# Self-test for gate_full_suite.sh using a mocked `gh`. No network, runs on
+# any dev box: bash .github/scripts/test_gate_full_suite.sh
+set -u
+here=$(cd "$(dirname "$0")" && pwd)
+tmp=$(mktemp -d)
+trap 'rm -rf "$tmp"' EXIT
+
+# Mock gh. Asserts the exact endpoint (including head_sha) it is called
+# with — an endpoint typo in the gate script fails the test rather than
+# silently serving canned data. On the runs endpoint it serves
+# $MOCK_DIR/response_<call#>.json, sticking on the highest existing file,
+# and exits 1 if none exist (simulates a GitHub API outage). On the pulls
+# endpoint it serves $MOCK_DIR/pr.json, defaulting to a 'ready'-labeled PR.
+cat > "$tmp/gh" <<'EOF'
+#!/usr/bin/env bash
+if [ "${1:-}" != "api" ]; then
+  echo "unexpected gh invocation: $*" >> "$MOCK_DIR/endpoint_error"
+  exit 2
+fi
+case "${2:-}" in
+  "repos/o/r/actions/runs?head_sha=deadbeef&per_page=100")
+    n=$(( $(cat "$MOCK_DIR/count" 2>/dev/null || echo 0) + 1 ))
+    echo "$n" > "$MOCK_DIR/count"
+    while [ "$n" -gt 0 ]; do
+      if [ -f "$MOCK_DIR/response_$n.json" ]; then
+        cat "$MOCK_DIR/response_$n.json"
+        exit 0
+      fi
+      n=$(( n - 1 ))
+    done
+    echo "api outage" >&2
+    exit 1
+    ;;
+  "repos/o/r/pulls/42")
+    if [ -f "$MOCK_DIR/pr.json" ]; then
+      cat "$MOCK_DIR/pr.json"
+    else
+      echo '{"labels": [{"name": "ready"}]}'
+    fi
+    ;;
+  *)
+    echo "unexpected gh endpoint: $2" >> "$MOCK_DIR/endpoint_error"
+    exit 2
+    ;;
+esac
+EOF
+chmod +x "$tmp/gh"
+
+PC_OK='{"name": "pre-commit", "id": 1, "status": "completed", "conclusion": "success"}'
+PC_BAD='{"name": "pre-commit", "id": 1, "status": "completed", "conclusion": "failure"}'
+PC_PENDING='{"name": "pre-commit", "id": 1, "status": "in_progress", "conclusion": null}'
+DOCS_OK='{"name": "Deploy Documentation", "id": 2, "status": "completed", "conclusion": "success"}'
+DOCS_BAD='{"name": "Deploy Documentation", "id": 2, "status": "completed", "conclusion": "failure"}'
+DOCS_CANCELLED='{"name": "Deploy Documentation", "id": 2, "status": "completed", "conclusion": "cancelled"}'
+OTHER='{"name": "Trigger Full Suite", "id": 3, "status": "in_progress", "conclusion": null}'
+NULL_NAME='{"name": null, "id": 4, "status": "completed", "conclusion": "failure"}'
+PC_OK_RERUN='{"name": "pre-commit", "id": 5, "status": "completed", "conclusion": "success"}'
+
+fails=0
+want_log=""  # optional: expect() also greps out.log for this regex, then resets
+pr_json=""   # optional: served for the pulls (label re-check) endpoint, then resets
+raw_body=""  # optional: serve responses verbatim instead of wrapping in workflow_runs
+expect() { # <name> <expected-exit> <response json>...
+  local name=$1 want=$2 dir i=1
+  shift 2
+  dir=$(mktemp -d "$tmp/test_XXXXXX")
+  for body in "$@"; do
+    if [ -n "$raw_body" ]; then
+      printf '%s' "$body" > "$dir/response_$i.json"
+    else
+      printf '{"workflow_runs": [%s]}' "$body" > "$dir/response_$i.json"
+    fi
+    i=$(( i + 1 ))
+  done
+  [ -n "$pr_json" ] && printf '%s' "$pr_json" > "$dir/pr.json"
+  ( export PATH="$tmp:$PATH" MOCK_DIR="$dir" PR_SHA=deadbeef PR_NUMBER=42 \
+      GITHUB_REPOSITORY=o/r POLL_SECS=0 GRACE_SECS=1 MAX_WAIT_SECS=3
+    bash "$here/gate_full_suite.sh" > "$dir/out.log" 2>&1 )
+  local rc=$?
+  if [ "$rc" -ne "$want" ]; then
+    echo "FAIL: $name (exit $rc, want $want)"
+    cat "$dir/out.log"
+    fails=1
+  elif [ -f "$dir/endpoint_error" ]; then
+    echo "FAIL: $name (mock gh got an unexpected call)"
+    cat "$dir/endpoint_error"
+    fails=1
+  elif [ -n "$want_log" ] && ! grep -Eq "$want_log" "$dir/out.log"; then
+    echo "FAIL: $name (log does not match: $want_log)"
+    cat "$dir/out.log"
+    fails=1
+  else
+    echo "ok: $name"
+  fi
+  want_log="" pr_json="" raw_body=""
+}
+
+expect "both green -> proceed" 0 "$PC_OK, $DOCS_OK, $OTHER, $NULL_NAME"
+expect "docs build failed -> blocked" 1 "$PC_OK, $DOCS_BAD"
+expect "pre-commit failed -> blocked" 1 "$PC_BAD"
+expect "pending then green -> proceed" 0 "$PC_PENDING" "$PC_OK, $DOCS_OK"
+want_log="never appeared.*Deploy Documentation"
+expect "docs run absent (path-filtered) -> proceed after grace" 0 "$PC_OK"
+expect "API outage -> fail open" 0
+want_log="FAILING OPEN"
+expect "pending past MAX_WAIT -> fail open" 0 "$PC_PENDING"
+want_log="FAILING OPEN"
+expect "unrelated runs only -> no grace, fail open at MAX_WAIT" 0 "$OTHER"
+expect "cancelled docs then green -> proceed" 0 \
+  "$PC_OK, $DOCS_CANCELLED" "$PC_OK, $DOCS_OK"
+want_log="FAILING OPEN"
+expect "cancelled docs forever -> fail open at MAX_WAIT" 0 "$PC_OK, $DOCS_CANCELLED"
+want_log="FAILING OPEN"
+expect "pre-commit absent -> no grace, fail open at MAX_WAIT" 0 "$DOCS_OK"
+expect "duplicate run names -> latest wins" 0 "$PC_BAD, $PC_OK_RERUN, $DOCS_OK"
+raw_body=1
+expect "garbage response body -> fail open" 0 "this is not json"
+pr_json='{"labels": [{"name": "other"}]}'
+expect "ready label removed mid-gate -> blocked" 1 "$PC_OK, $DOCS_OK"
+
+exit "$fails"

.github/workflows/ci-precommit.yml

@@ -1,7 +1,11 @@
 name: pre-commit
 
 on:
-  pull_request:
+  # pull_request_target instead of pull_request: the workflow definition and
+  # the hook config are always taken from the BASE branch, so fork /
+  # first-time-contributor PRs run immediately without a maintainer clicking
+  # "Approve and run". The PR head is checked out as data only.
+  pull_request_target:
     branches: [main]
   workflow_call:
     inputs:
@@ -15,12 +19,25 @@ permissions:
 
 jobs:
   pre-commit:
-    if: github.event_name == 'workflow_call' || github.event.pull_request.draft != true
+    if: github.event.pull_request.draft != true
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
       with:
         ref: ${{ inputs.ref || '' }}
+    # For PR events, lint the PR head — but keep the hook definitions from
+    # the base branch so an untrusted PR cannot alter what gets executed.
+    - name: Save trusted hook config
+      if: github.event_name == 'pull_request_target'
+      run: cp .pre-commit-config.yaml "$RUNNER_TEMP/trusted-pre-commit-config.yaml"
+    - uses: actions/checkout@v4
+      if: github.event_name == 'pull_request_target'
+      with:
+        ref: ${{ github.event.pull_request.head.sha }}
+        persist-credentials: false
+    - name: Restore trusted hook config
+      if: github.event_name == 'pull_request_target'
+      run: cp "$RUNNER_TEMP/trusted-pre-commit-config.yaml" .pre-commit-config.yaml
     - uses: actions/setup-python@v5
       with:
         python-version: "3.12"
@@ -30,3 +47,6 @@ jobs:
     - uses: pre-commit/action@v3.0.1
       with:
         extra_args: --all-files --hook-stage manual
+    # After pre-commit so a self-test failure cannot mask lint failures.
+    - name: Full-suite gate self-test
+      run: bash .github/scripts/test_gate_full_suite.sh

.github/workflows/ci-slash-commands.yml

@@ -52,6 +52,7 @@ jobs:
             core.setOutput('pr_sha', pr.head.sha);
             core.setOutput('pr_branch', pr.head.ref);
             core.setOutput('pr_number', String(prNumber));
+            core.setOutput('pr_title', pr.title);
 
       - name: Trigger Full Suite
         if: steps.perm.outputs.has_write == 'true'
@@ -60,6 +61,7 @@ jobs:
           PR_SHA: ${{ steps.label.outputs.pr_sha }}
           PR_BRANCH: ${{ steps.label.outputs.pr_branch }}
           PR_NUMBER: ${{ steps.label.outputs.pr_number }}
+          PR_TITLE: ${{ steps.label.outputs.pr_title }}
           BK_ORG: ${{ vars.BUILDKITE_ORG_SLUG }}
           BK_PIPELINE: ${{ vars.BUILDKITE_PIPELINE_SLUG }}
         run: |
@@ -71,6 +73,7 @@ jobs:
               --arg commit "$PR_SHA" \
               --arg branch "$PR_BRANCH" \
               --arg message "Full Suite for PR #${PR_NUMBER} (via /merge)" \
+              --arg pr_title "$PR_TITLE" \
               --argjson pr_id "$PR_NUMBER" \
               '{
                 commit: $commit,
@@ -80,11 +83,12 @@ jobs:
                 pull_request_id: $pr_id,
                 pull_request_base_branch: "main",
                 env: {
-                  TEST_SCOPE: "full",
-                  FULL_SUITE: "true",
-                  PR_NUMBER: ($pr_id | tostring)
-                }
-              }')"
+                    TEST_SCOPE: "full",
+                    FULL_SUITE: "true",
+                    PR_NUMBER: ($pr_id | tostring),
+                    PR_TITLE: $pr_title
+                  }
+                }')"
 
   parse-command:
     if: >-
@@ -125,7 +129,7 @@ jobs:
           set -euo pipefail
           TEST_NAME=$(echo "$COMMENT" | grep -oP '(?<=/test\s)\S+' | head -1 || true)
 
-          VALID="encoder vae transformer kernel unit dreamverse ssim training lora-inference lora-training distillation self-forcing vsa vmoba performance api train-framework eval full fastcheck pre-commit"
+          VALID="encoder vae transformer kernel unit dreamverse ssim training lora-inference lora-training lora-extraction distillation self-forcing vsa vmoba performance api train-framework eval full fastcheck pre-commit"
           if [ -z "$TEST_NAME" ] || ! echo "$VALID" | grep -qw "$TEST_NAME"; then
             echo "Unknown test: '$TEST_NAME'. Valid: $VALID"
             exit 1
@@ -136,6 +140,7 @@ jobs:
             [kernel]=kernel_tests [unit]=unit_test [dreamverse]=dreamverse_app
             [ssim]=ssim [training]=training
             [lora-inference]=inference_lora [lora-training]=training_lora
+            [lora-extraction]=lora_extraction
             [distillation]=distillation_dmd [self-forcing]=self_forcing
             [vsa]=training_vsa [vmoba]=inference_vmoba
             [performance]=performance [api]=api_server
@@ -240,6 +245,7 @@ jobs:
           TEST_SCOPE: ${{ needs.parse-command.outputs.test_scope }}
           FULL_SUITE: ${{ needs.parse-command.outputs.full_suite }}
           TEST_TYPE: ${{ needs.parse-command.outputs.test_type }}
+          PR_TITLE: ${{ github.event.issue.title }}
           BK_ORG: ${{ vars.BUILDKITE_ORG_SLUG }}
           BK_PIPELINE: ${{ vars.BUILDKITE_PIPELINE_SLUG }}
         run: |
@@ -256,6 +262,7 @@ jobs:
               --arg full_suite "$FULL_SUITE" \
               --arg test_type "$TEST_TYPE" \
               --arg pr_number "$PR_NUMBER" \
+              --arg pr_title "$PR_TITLE" \
               '{
                 commit: $commit,
                 branch: $branch,
@@ -265,8 +272,9 @@ jobs:
                 pull_request_base_branch: "main",
                 env: {
                   TEST_SCOPE: $test_scope,
-                  FULL_SUITE: $full_suite,
-                  TEST_TYPE: $test_type,
-                  PR_NUMBER: $pr_number
-                }
-              }')"
+                    FULL_SUITE: $full_suite,
+                    TEST_TYPE: $test_type,
+                    PR_NUMBER: $pr_number,
+                    PR_TITLE: $pr_title
+                  }
+                }')"

.github/workflows/ci-trigger-full-suite.yml

@@ -7,6 +7,7 @@ on:
 permissions:
   contents: read
   pull-requests: read
+  actions: read
 
 concurrency:
   group: full-suite-${{ github.event.pull_request.number }}
@@ -18,6 +19,8 @@ jobs:
       (github.event.action == 'labeled' && github.event.label.name == 'ready')
       || github.event.action == 'synchronize'
     runs-on: ubuntu-latest
+    # Gate below may wait for cheap checks (up to MAX_WAIT_SECS = 25 min).
+    timeout-minutes: 35
     steps:
       - name: Check ready label
         id: check
@@ -49,6 +52,20 @@ jobs:
               "https://api.buildkite.com/v2/organizations/${{ vars.BUILDKITE_ORG_SLUG }}/pipelines/${{ vars.BUILDKITE_PIPELINE_SLUG }}/builds/${build_num}/cancel"
           done
 
+      # Checks out the BASE branch (default for pull_request_target), so PR
+      # authors cannot tamper with the gate script.
+      - name: Checkout gate script
+        if: steps.check.outputs.has_ready == 'true'
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Wait for pre-commit and docs build
+        if: steps.check.outputs.has_ready == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR_SHA: ${{ github.event.pull_request.head.sha }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: bash .github/scripts/gate_full_suite.sh
+
       - name: Trigger Buildkite Full Suite
         if: steps.check.outputs.has_ready == 'true'
         env:
@@ -56,6 +73,7 @@ jobs:
           PR_SHA: ${{ github.event.pull_request.head.sha }}
           PR_BRANCH: ${{ github.event.pull_request.head.ref }}
           PR_NUMBER: ${{ github.event.pull_request.number }}
+          PR_TITLE: ${{ github.event.pull_request.title }}
           BK_ORG: ${{ vars.BUILDKITE_ORG_SLUG }}
           BK_PIPELINE: ${{ vars.BUILDKITE_PIPELINE_SLUG }}
         run: |
@@ -67,6 +85,7 @@ jobs:
               --arg commit "$PR_SHA" \
               --arg branch "$PR_BRANCH" \
               --arg message "Full Suite for PR #${PR_NUMBER}" \
+              --arg pr_title "$PR_TITLE" \
               --argjson pr_id "$PR_NUMBER" \
               '{
                 commit: $commit,
@@ -78,6 +97,7 @@ jobs:
                 env: {
                   TEST_SCOPE: "full",
                   FULL_SUITE: "true",
-                  PR_NUMBER: ($pr_id | tostring)
+                  PR_NUMBER: ($pr_id | tostring),
+                  PR_TITLE: $pr_title
                 }
               }')"

.github/workflows/infra-build-image.yml

@@ -13,12 +13,33 @@ on:
         required: false
         default: false
         type: boolean
+  # Auto-rebuild the CUDA images when their Dockerfile changes on main. The CUDA
+  # matrix is the only lane that builds from docker/Dockerfile, so a path-scoped
+  # push trigger is a sufficient change detector on its own -- no separate
+  # detect-changes/paths-filter job is needed now that there is a single
+  # in-scope Dockerfile. Dreamverse (apps/dreamverse/docker/Dockerfile) and the
+  # rocm Dockerfile stay manual-dispatch only.
+  push:
+    branches: [main]
+    paths:
+      - 'docker/Dockerfile'
 
 
 permissions:
   contents: read
   packages: write
 
+# One static group, no cancellation: every run of this workflow writes the same
+# mutable registry tags (latest, py3.12-latest, ...), so runs must serialize —
+# concurrent push/dispatch runs would race on those tags, and cancelling a run
+# mid-publish can strand the cu126/cu130 tag families at different commits. An
+# in-flight superseded build wastes its runner time, but its tags are then
+# overwritten by the newer queued run. GitHub keeps a single pending run per
+# group: the newest queued run replaces any older queued one.
+concurrency:
+  group: infra-build-image
+  cancel-in-progress: false
+
 jobs:
   # CUDA matrix: Python 3.12 x {12.6.3, 13.0.0} x {amd64, arm64}. Each architecture
   # builds natively and pushes only by digest; publish-cuda-manifests is the sole
@@ -28,7 +49,11 @@ jobs:
   # aliases; 13.0.0/cu130 is published under explicit versioned tags. Flash-attn
   # 2.8.3 comes from the architecture-specific prebuilt releases.
   build-cuda-images:
-    if: ${{ github.event.inputs.build_cuda_matrix == 'true' }}
+    # Runs on a manual dispatch when build_cuda_matrix is set, or automatically
+    # on a push that changed docker/Dockerfile (inputs are null on push). The
+    # repository guard keeps fork syncs from auto-building; manual dispatch
+    # still works in forks.
+    if: ${{ (github.event_name == 'push' && github.repository == 'hao-ai-lab/FastVideo') || github.event.inputs.build_cuda_matrix == 'true' }}
     strategy:
       fail-fast: false
       matrix:
@@ -75,10 +100,10 @@ jobs:
     secrets: inherit
 
   publish-cuda-manifests:
-    # !cancelled(): a failed sibling build leg must not skip the manifests for a
-    # CUDA lane whose own digests all exist; the digest-count check below fails
-    # the incomplete lane loudly instead.
-    if: ${{ !cancelled() && github.event.inputs.build_cuda_matrix == 'true' }}
+    # !cancelled(): publish lanes whose digests exist even if a sibling build
+    # leg failed (the digest-count check fails incomplete lanes); it also
+    # bypasses skipped-needs propagation, hence the explicit skipped check.
+    if: ${{ !cancelled() && needs.build-cuda-images.result != 'skipped' }}
     needs: build-cuda-images
     runs-on: ubuntu-latest
     permissions:

.pre-commit-config.yaml

@@ -10,8 +10,6 @@ exclude: |
     scripts/.*|
     fastvideo/dataset/.*|
     fastvideo/models/.*|
-    v2/(layers|attention|platforms|configs|distributed|models|logging_utils|third_party|hooks|api)/.*|
-    v2/(envs|logger|utils|version|forward_context|fastvideo_args)\.py|
     ^apps/dreamverse/web/.*|
     examples/.*|
     \.agents/.*|

apps/dreamverse/docker/Dockerfile

@@ -84,9 +84,12 @@ RUN source /opt/venv/bin/activate \
        FFMPEG_NATIVE_CXX=/usr/bin/g++ \
        bash /opt/FastVideo/apps/dreamverse/scripts/install_native_ffmpeg.sh
 
+# FASTVIDEO_FA4: FA4 (flash_attn.cute) is opt-in; this image installs it via
+# the dreamverse extra and is validated with it, so enable it here.
 ENV FASTVIDEO_DREAMVERSE_HOME=/var/lib/dreamverse \
     STREAM_MODE=av_fmp4 \
     FASTVIDEO_ENABLE_PROMPT_SAFETY=0 \
+    FASTVIDEO_FA4=1 \
     HF_HOME=/root/.cache/huggingface
 
 RUN mkdir -p /var/lib/dreamverse

apps/performance_dashboard/README.md

@@ -12,13 +12,17 @@ Defaults:
 
 - `HF_REPO_ID=FastVideo/performance-tracking`
 - `PERFORMANCE_TRACKING_ROOT=/tmp/fastvideo-perf-dashboard`
-- `PERF_MAX_REGRESSION=0.05`
 
-Records can include source metadata:
+Records can include source metadata and rolling-baseline policy context:
 
 - `run_source`: `pr`, `local`, `scheduled_main`, or `unknown`
 - `baseline_eligible`: only successful scheduled-main records should be true
 - Buildkite metadata such as branch, PR number, build URL, build ID, and job ID
+- `regression_thresholds`: per-metric rolling-baseline percent and absolute
+  floors used for recomputed status context
+
+Dashboard/API metric payloads expose `threshold_exceeded` for raw threshold
+crossings; `regressed` remains the gated CI-failure signal.
 
 Set one of `HF_API_KEY`, `HUGGINGFACE_HUB_TOKEN`, or `HF_TOKEN` if the
 configured dataset repo requires authenticated access:
@@ -89,7 +93,8 @@ Trend charts show metric-specific axes and exact point details on hover/focus:
 - PR number, branch, and Buildkite URL when present
 
 The latest status table uses the stored JSON `success` value. Recomputed
-baseline context is shown separately and does not override stored status.
+baseline context applies each metric's percent and absolute regression floors
+and does not override stored status.
 
 ## API
 

apps/performance_dashboard/frontend/src/App.tsx

@@ -1,6 +1,7 @@
 import { useEffect, useMemo, useState } from "react";
 
-import { fetchSummary, fetchTrends, refreshData, RunSource, SummaryResponse, TrendGroup, TrendPoint } from "./api";
+import { fetchSummary, fetchTrends, refreshData } from "./api";
+import type { CohortValue, RunSource, SummaryResponse, TrendGroup, TrendPoint } from "./api";
 
 const METRIC_KEYS = ["latency", "throughput", "memory", "text_encoder_time_s", "dit_time_s", "vae_decode_time_s"];
 const RUN_SOURCES: Array<{ value: "" | RunSource; label: string }> = [
@@ -109,6 +110,61 @@ function metricLabel(metricKey: string) {
   return METRIC_DEFINITIONS[metricKey]?.label ?? metricKey;
 }
 
+type CohortFields = {
+  model_id: string;
+  gpu_type: string;
+  workload_id: CohortValue;
+  variant_id: CohortValue;
+  benchmark_version: CohortValue;
+  recipe_fingerprint: CohortValue;
+  hardware_profile_id: CohortValue;
+  software_profile_id: CohortValue;
+};
+
+function cohortValue(value: CohortValue) {
+  if (value === null || value === undefined || value === "") {
+    return "legacy";
+  }
+  return String(value);
+}
+
+function shortCohortValue(value: CohortValue) {
+  const text = cohortValue(value);
+  if (text === "legacy" || text.length <= 14) {
+    return text;
+  }
+  return text.slice(0, 12);
+}
+
+function cohortKey(cohort: CohortFields) {
+  return [
+    cohort.model_id,
+    cohort.gpu_type,
+    cohortValue(cohort.workload_id),
+    cohortValue(cohort.variant_id),
+    cohortValue(cohort.benchmark_version),
+    cohortValue(cohort.recipe_fingerprint),
+    cohortValue(cohort.hardware_profile_id),
+    cohortValue(cohort.software_profile_id)
+  ].join("|");
+}
+
+function cohortTitle(cohort: CohortFields) {
+  const workload = cohortValue(cohort.workload_id);
+  const variant = cohortValue(cohort.variant_id);
+  const version = cohortValue(cohort.benchmark_version);
+  const versionLabel = version === "legacy" ? version : `v${version}`;
+  return `${workload} / ${variant} / ${versionLabel}`;
+}
+
+function cohortDetail(cohort: CohortFields) {
+  return [
+    `recipe ${shortCohortValue(cohort.recipe_fingerprint)}`,
+    shortCohortValue(cohort.hardware_profile_id),
+    shortCohortValue(cohort.software_profile_id)
+  ].join(" | ");
+}
+
 function formatMetricValue(metricKey: string, value: number | null | undefined, tooltip = false) {
   const definition = METRIC_DEFINITIONS[metricKey];
   if (!definition) {
@@ -171,7 +227,9 @@ function TrendChart({ group, metricKey }: { group: TrendGroup; metricKey: string
         top: `${(activePoint.y / height) * 100}%`
       }
     : undefined;
-  const ariaLabel = `${metricLabel(metricKey)} trend for ${group.model_id} on ${group.gpu_type}`;
+  const ariaLabel = `${metricLabel(metricKey)} trend for ${group.model_id} on ${group.gpu_type}, ${cohortTitle(
+    group
+  )}`;
 
   return (
     <div className="chart-shell">
@@ -419,7 +477,7 @@ export default function App() {
       <section className="panel">
         <div className="panel-header">
           <h2>Latest Status</h2>
-          <span>{latestRows.length} model/GPU groups</span>
+          <span>{latestRows.length} comparison cohorts</span>
         </div>
         {latestRows.length === 0 ? (
           <div className="empty">No records match the selected filters.</div>
@@ -432,6 +490,7 @@ export default function App() {
                   <th>Recomputed</th>
                   <th>Model</th>
                   <th>GPU</th>
+                  <th>Cohort</th>
                   <th>Commit</th>
                   <th>Source</th>
                   <th>Baseline</th>
@@ -440,11 +499,13 @@ export default function App() {
                   <th>Throughput</th>
                   <th>Memory</th>
                   <th>Worst</th>
+                  <th>Exceeded</th>
+                  <th>Failing</th>
                 </tr>
               </thead>
               <tbody>
                 {latestRows.map((row) => (
-                  <tr key={`${row.model_id}-${row.gpu_type}`}>
+                  <tr key={cohortKey(row)}>
                     <td>
                       <span className={`badge ${row.status}`}>{row.status}</span>
                     </td>
@@ -455,6 +516,12 @@ export default function App() {
                     </td>
                     <td>{row.model_id}</td>
                     <td>{row.gpu_type}</td>
+                    <td>
+                      <div className="cohort-cell">
+                        <strong>{cohortTitle(row)}</strong>
+                        <span>{cohortDetail(row)}</span>
+                      </div>
+                    </td>
                     <td>{shortSha(row.commit_sha)}</td>
                     <td>
                       <span className={`source-badge source-${row.run_source}`}>{runSourceLabel(row.run_source)}</span>
@@ -465,6 +532,12 @@ export default function App() {
                     <td>{formatNumber(row.metrics.throughput?.current, 3)}</td>
                     <td>{formatNumber(row.metrics.memory?.current, 1)}</td>
                     <td>{formatNumber(row.worst_regression_pct, 1)}%</td>
+                    <td>
+                      {row.threshold_exceeded_metrics.length
+                        ? row.threshold_exceeded_metrics.join(", ")
+                        : "none"}
+                    </td>
+                    <td>{row.failing_metrics.length ? row.failing_metrics.join(", ") : "none"}</td>
                   </tr>
                 ))}
               </tbody>
@@ -487,11 +560,13 @@ export default function App() {
           ) : (
             trends.map((group) =>
               METRIC_KEYS.map((metricKey) => (
-                <article className="trend-card" key={`${group.model_id}-${group.gpu_type}-${metricKey}`}>
+                <article className="trend-card" key={`${cohortKey(group)}-${metricKey}`}>
                   <div>
                     <h3>{metricLabel(metricKey)}</h3>
                     <p>
                       {group.model_id} | {group.gpu_type}
+                      <span>{cohortTitle(group)}</span>
+                      <span>{cohortDetail(group)}</span>
                     </p>
                   </div>
                   <TrendChart group={group} metricKey={metricKey} />

apps/performance_dashboard/frontend/src/api.ts

@@ -2,11 +2,28 @@ export type MetricValue = {
   current: number | null;
   baseline: number | null;
   regression_pct: number | null;
+  absolute_delta: number | null;
+  threshold_percent: number;
+  threshold_absolute: number;
+  gated: boolean;
+  threshold_exceeded: boolean;
+  regressed: boolean;
   label: string;
   lower_is_better: boolean;
   precision: number;
 };
 
+export type CohortValue = string | number | null;
+
+export type ComparisonCohort = {
+  workload_id: CohortValue;
+  variant_id: CohortValue;
+  benchmark_version: CohortValue;
+  recipe_fingerprint: CohortValue;
+  hardware_profile_id: CohortValue;
+  software_profile_id: CohortValue;
+};
+
 export type SummaryRow = {
   model_id: string;
   gpu_type: string;
@@ -15,7 +32,8 @@ export type SummaryRow = {
   success: boolean;
   baseline_n: number;
   worst_regression_pct: number | null;
-  regression_threshold_pct: number;
+  threshold_exceeded_metrics: string[];
+  failing_metrics: string[];
   computed_regression_status: "pass" | "fail";
   status: "pass" | "fail";
   run_source: RunSource;
@@ -27,7 +45,7 @@ export type SummaryRow = {
   build_id: string;
   job_id: string;
   metrics: Record<string, MetricValue>;
-};
+} & ComparisonCohort;
 
 export type RunSource = "pr" | "local" | "scheduled_main" | "unknown";
 
@@ -61,13 +79,13 @@ export type TrendPoint = {
   build_id: string;
   job_id: string;
   metrics: Record<string, number | null>;
-};
+} & ComparisonCohort;
 
 export type TrendGroup = {
   model_id: string;
   gpu_type: string;
   points: TrendPoint[];
-};
+} & ComparisonCohort;
 
 export type TrendsResponse = {
   groups: TrendGroup[];

apps/performance_dashboard/frontend/src/styles.css

@@ -149,6 +149,11 @@ h3 {
   font-size: 0.82rem;
 }
 
+.trend-card p {
+  display: grid;
+  gap: 2px;
+}
+
 .stat strong {
   display: block;
   margin-top: 8px;
@@ -186,7 +191,7 @@ h3 {
 
 table {
   width: 100%;
-  min-width: 1120px;
+  min-width: 1260px;
   border-collapse: collapse;
 }
 
@@ -209,6 +214,25 @@ td {
   font-size: 0.9rem;
 }
 
+.cohort-cell {
+  display: grid;
+  gap: 2px;
+}
+
+.cohort-cell strong,
+.trend-card p span {
+  color: #1b2836;
+  font-size: 0.78rem;
+  font-weight: 700;
+}
+
+.cohort-cell span,
+.trend-card p span + span {
+  color: #607080;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
+  font-size: 0.72rem;
+}
+
 .badge {
   display: inline-flex;
   align-items: center;

assets/eval/worldmodel_synthetic_flow_calibration.json

@@ -0,0 +1,22 @@
+{
+  "alpha_yaw": 0.08734091699186919,
+  "alpha_pitch": 0.08169667696275307,
+  "alpha_turn": 5.724587470723463e-17,
+  "beta_fwd": 0.02842768078408099,
+  "beta_strafe": 0.022531015077067108,
+  "focal_length": 457.0,
+  "frame_shape": [
+    352,
+    640
+  ],
+  "calibrated_from": [
+    "1_wasd_only",
+    "camera",
+    "camera4hold_alpha1",
+    "fully_random",
+    "wasdonly_alpha1",
+    "wasd4holdrandview_simple_1key1mouse1"
+  ],
+  "residual_rms": 15.890399609478676,
+  "n_equations": 4125232
+}

design_summary.md

@@ -1,56 +0,0 @@
-# FastVideo — Design Philosophy
-
-One page on *why* FastVideo is built the way it is. The full architecture, the as-built status, and the
-forward roadmap live in **[`v2/README.md`](v2/README.md)** — this is the philosophy beneath it.
-
----
-
-**A deployable model is a post-training artifact.** Unlike an LLM — where inference optimizes frozen weights
-after the fact — a *usable* video/omni model is *created* by training: step distillation for latency, QAT for
-precision, distillation + self-forcing for causal/world models. So every inference capability is a
-**(recipe, runtime) pair**: the weights and the loop that produced-and-assumes them are one versioned object.
-This is the source of the moat — whoever owns *both* sides of the pair owns the optimization frontier — and it
-is why training and serving cannot be two systems.
-
-**The work is loops, not `forward()`.** Denoise timesteps, AR decode, chunked rollout, VAE tiles, encoder
-chunks, audio tokens, reward batches, optimizer steps, media chunks — video and omni inference is iteration. A
-runtime that collapses everything to a single `forward` can't schedule, batch, cancel, stream, reserve memory
-for, or capture the behavior of what actually runs. So loops are first-class, and they are **driven**: the
-model describes the next step it needs, the runtime decides when and with whom it runs, the model folds the
-result back. The model keeps content-adaptive control flow; the runtime keeps admission, batching, streaming,
-and behavior capture. Per-request state lives in typed `LoopState`, never in module globals — so interleaving
-requests through one model instance cannot smear state, by construction.
-
-**The model is the center; everything else is a view over it.** A typed `ModelCard` owns components, loops,
-the recipe, and the parity contract. Programs compose a card's loops into a task; Workflows compose cards into
-pipelines; the scheduler runs the *steps* of all loops as `WorkUnit`s under one currency (predicted GPU-time,
-because a bidirectional denoise step and an AR token are ~1000× apart and incommensurable in counts);
-deployment places and routes; products stream artifacts. None of them define model semantics — they reference
-the Model Plane. One resident instance can run many loop types on shared weights, which is what makes omni/MoT
-native rather than a DAG that doubles weights.
-
-**Correctness is a typed contract, not a hope.** Caches are correct by *key* — if a field can change output
-semantics it is in the key, so reuse is partitioned, never blindly flushed. Parity between the train-forward
-and the serve-forward is *measured* on a declared ladder (component → loop → behavioral → distribution →
-artifact-quality), never assumed. And the non-negotiable gate is **interleave bit-parity**: N requests
-interleaved at step granularity must be bit-identical to running them serially — the test the whole
-loop-inversion bet lives or dies on.
-
-**One substrate for inference, training, and RL.** The rollout forward *is* the serve forward plus capture —
-same loop, same caches, same batcher, same numerics — so every serving optimization is automatically a rollout
-optimization, and there is one numerics surface the ladder measures rather than a correction layer papering
-over it. The engine doubles as the RL rollout engine under a strict rule: `training` consumes the engine; the
-**engine never imports `training`**.
-
-**Borrow aggressively; copy nothing as the core.** vLLM/SGLang scheduling, vLLM-Omni/SGLang-Omni omni serving,
-Dynamo fleet orchestration, diffusers components, xDiT parallelism, TorchTitan mesh discipline,
-verl-omni/miles RL lessons, ComfyUI workflows, Dreamverse/LiveKit sessions — each contributes a take, none is
-the center. Deployment orchestration (Dynamo) sits *above* the engine, never inside it. Extensions are
-versioned hook points, never monkeypatching. New frontier capabilities arrive as a card, a method, a loop, a
-workflow, or a controller — **not a rewrite**.
-
-> A model card is a (recipe, runtime) pair with a parity obligation. The model owns loop semantics; the runtime
-> owns loop lifecycle. One resident instance runs many loops; one scheduler runs their steps in one currency.
-> Caches are correct by key; parity is correct by test; the interleave gate is non-negotiable. Training records
-> behavior on the same loops it serves. Deployment places and routes; products stream artifacts; neither defines
-> the model.

docker/Dockerfile

@@ -68,7 +68,7 @@ ARG FLASH_ATTN_WHEEL_RELEASE_ARM64=https://github.com/mjun0812/flash-attention-p
 # cutlass-4.4 `cute.core.ThrMma` API, which crashes on the cutlass-dsl 4.5 that
 # flashinfer/quack pull in. After the wheel install we overlay this cutlass-4.5-safe
 # upstream cute (flash-attn-4) so the image runs FA4 instead of the FA2 fallback.
-ARG FA4_CUTE_REF=940cd9680f3315f2f06b43ab5bea2c2cf2d96806
+ARG FA4_CUTE_REF=82d6441eec5d4dfec120153db2c0145ae855a083
 
 # Provided automatically by BuildKit/buildx (e.g. "amd64" / "arm64") and used to
 # select the prebuilt flash-attn wheel. Empty under a plain `docker build` without
@@ -161,7 +161,7 @@ RUN --mount=type=cache,target=/opt/uv/cache \
         uv pip install flash-attn==${FLASH_ATTN_VERSION} --no-build-isolation; \
     fi
 
-# Overlay the cutlass-4.5-safe upstream FA4 cute (FA4_CUTE_REF) over the
+# Overlay the CuTe-DSL-4.6-compatible upstream FA4 cute (FA4_CUTE_REF) over the
 # wheel/source one so the image runs FA4, not the FA2 fallback. This pulls the FA4
 # runtime stack (cutlass-dsl, quack-kernels, apache-tvm-ffi, torch-c-dlpack-ext) --
 # the same deps the [dreamverse] extra already installs in CI; the installed torch
@@ -170,12 +170,14 @@ RUN --mount=type=cache,target=/opt/uv/cache \
 # rmtree clears the wheel's stale cute files first to avoid an install conflict.
 # Then verify both survive so a broken overlay fails the build instead of shipping
 # an FA2-less image. x86 only: the FA4 stack (quack-kernels etc.) is unvalidated on
-# arm64 / GB10 (sm_121), so there we skip the overlay and FA4 falls back to FA2.
+# arm64 / GB10 (sm_121), so there we skip the overlay; FA4 is opt-in
+# (FASTVIDEO_FA4=1) and errors if set without the overlay, so leave it unset on
+# arm64 and the image runs FA3/FA2 as usual.
 RUN --mount=type=cache,target=/opt/uv/cache \
     source $HOME/.local/bin/env && \
     source /opt/venv/bin/activate && \
     if [ "${TARGETARCH}" = "arm64" ]; then \
-        echo "Skipping FA4 cute overlay on arm64 (FA4 stack unvalidated there; FA4 falls back to FA2)"; \
+        echo "Skipping FA4 cute overlay on arm64 (FA4 stack unvalidated there; do not set FASTVIDEO_FA4)"; \
     else \
         python -c "import glob, shutil; [shutil.rmtree(d, ignore_errors=True) for d in glob.glob('/opt/venv/lib/python*/site-packages/flash_attn/cute')]" && \
         uv pip install "flash-attn-4 @ git+https://github.com/Dao-AILab/flash-attention.git@${FA4_CUTE_REF}#subdirectory=flash_attn/cute" && \

docs/contributing/ci_architecture.md

@@ -99,10 +99,18 @@ status.
 Full Suite is also path-filtered. It validates broader behavior before Mergify
 can merge a PR.
 
+A `ready`-labeled PR does not hit Buildkite immediately:
+`ci-trigger-full-suite.yml` first runs `.github/scripts/gate_full_suite.sh`,
+which waits for the cheap Tier-1 checks (pre-commit, docs build) on the PR
+head. A red cheap check blocks the suite (fail closed; the next push re-arms
+it), while a GitHub outage or a >25 min wait lets it run anyway (fail open).
+`/test full` bypasses the gate.
+
 | Buildkite label | `TEST_TYPE` | Main watched paths |
 |---|---|---|
 | SSIM Tests | `ssim` | `fastvideo/**/*.py`, `pyproject.toml`, `docker/Dockerfile` |
 | LoRA Inference Tests | `inference_lora` | LoRA tests, loader, transformer tests, pipelines, LoRA layers |
+| LoRA Extraction Tests | `lora_extraction` | LoRA extraction scripts/tests, loader, training utilities, LoRA layers |
 | Training Tests | `training` | `fastvideo/**`, `pyproject.toml`, `docker/Dockerfile` |
 | Distillation DMD Tests | `distillation_dmd` | `fastvideo/training/*distillation_pipeline.py` |
 | Self-Forcing Tests | `self_forcing` | self-forcing distillation pipeline and tests |
@@ -144,6 +152,7 @@ Valid direct test names:
 | `/test training` | `training` |
 | `/test lora-inference` | `inference_lora` |
 | `/test lora-training` | `training_lora` |
+| `/test lora-extraction` | `lora_extraction` |
 | `/test distillation` | `distillation_dmd` |
 | `/test self-forcing` | `self_forcing` |
 | `/test vsa` | `training_vsa` |

docs/contributing/performance_benchmarks.md

@@ -72,14 +72,18 @@ fastvideo/tests/performance/
     │           writes Markdown summary + (optionally) uploads new records
     ├── dashboard.py
     │       └── builds time-series Plotly HTML from HF history
-    └── hf_store.py               # shared HF I/O + DataFrame helpers
+
+fastvideo/performance/
+    ├── hf_store.py               # shared HF I/O + DataFrame helpers
+    └── metric_policy.py          # shared rolling-baseline threshold policy
 ```
 
 The HF dataset (`FastVideo/performance-tracking` by default) holds one
-normalized JSON per `(model_id, gpu_type, run)` tuple. The rolling baseline is
-the median of the last 5 successful, baseline-eligible records for that
-model+GPU. PR and local records are visible in the dashboard but are not
-baseline eligible.
+normalized JSON per run. For v2 records, the rolling baseline is the median of
+the last 5 successful, baseline-eligible records in the same comparison cohort:
+`model_id`, `gpu_type`, `workload_id`, `variant_id`, `benchmark_version`,
+`recipe_fingerprint`, `hardware_profile_id`, and `software_profile_id`. PR and
+local records are visible in the dashboard but are not baseline eligible.
 
 ## Planned Coverage
 
@@ -92,25 +96,28 @@ and recipe changes instead of treating all records for a model as equivalent.
 
 ## Metrics
 
-Each benchmark records six metrics:
+Each benchmark records six metrics. The rolling-baseline comparator also has a
+per-metric policy with direction, percent threshold, absolute threshold, and a
+`gated` flag.
 
-| Metric | Raw key | Normalized key | Direction |
-|---|---|---|---|
-| End-to-end generation latency | `avg_generation_time_s` | `latency` | Lower is better |
-| Video throughput | `throughput_fps` | `throughput` | Higher is better |
-| Peak GPU memory | `max_peak_memory_mb` | `memory` | Lower is better |
-| Text encoder time | `text_encoder_time_s` | `text_encoder_time_s` | Lower is better |
-| DiT denoising time | `dit_time_s` | `dit_time_s` | Lower is better |
-| VAE decode time | `vae_decode_time_s` | `vae_decode_time_s` | Lower is better |
+| Metric | Raw key | Normalized key | Direction | Default rolling policy |
+|---|---|---|---|---|
+| End-to-end generation latency | `avg_generation_time_s` | `latency` | Lower is better | 8% and 0.5 s |
+| Video throughput | `throughput_fps` | `throughput` | Higher is better | 8% and 0.05 FPS |
+| Peak GPU memory | `max_peak_memory_mb` | `memory` | Lower is better | 5% and 256 MB |
+| Text encoder time | `text_encoder_time_s` | `text_encoder_time_s` | Lower is better | 5% and 0.25 s |
+| DiT denoising time | `dit_time_s` | `dit_time_s` | Lower is better | 5% and 0.25 s |
+| VAE decode time | `vae_decode_time_s` | `vae_decode_time_s` | Lower is better | 5% and 0.25 s |
 
 `test_inference_performance.py` temporarily sets `FASTVIDEO_STAGE_LOGGING=1`
 while it runs so pipeline stage execution times are available in
 `generate_video(...).logging_info`. Stage logs use pipeline-unique keys such as
 `prompt_encoding_stage` so duplicate stage classes do not collide. For
-`PipelineStage` entries, the extractor maps the `stage_class` field:
-`TextEncodingStage` maps to `text_encoder_time_s`, `DenoisingStage` and
-`DmdDenoisingStage` map to `dit_time_s`, and `DecodingStage` maps to
-`vae_decode_time_s`, with a fallback for older logs that used the class name as
+`PipelineStage` entries, shared component stage bases emit a stable
+`component_metric`: text encoding stages map to `text_encoder_time_s`,
+denoising stages and subclasses map to `dit_time_s`, and decoding stages map to
+`vae_decode_time_s`. The extractor falls back to known `stage_class` names for
+older logs that do not include `component_metric` or that used the class name as
 the stage key. Generator-side timings such as `PostDecodeFrameProcessStage`,
 `VideoSaveStage`, and `AudioMuxStage` are intentionally ignored. If a pipeline
 does not report one of the mapped stages, that component metric is stored as
@@ -152,13 +159,29 @@ unrealistic memory growth, and optionally large component-specific slowdowns
 even when the rolling baseline is empty. They are hand-set with generous
 headroom and almost never need touching.
 
-### Rolling baseline (per `(model_id, gpu_type)`)
+### Rolling baseline (per comparison cohort)
 
 `compare_baseline.py` loads the last 5 successful, baseline-eligible records
-for the same `(model_id, gpu_type)` from the HF dataset, computes the median
-for each available metric, and fails if the current run regresses by more than
-`PERF_MAX_REGRESSION` (default 5%). For latency, memory, and component times,
-higher values are regressions. For throughput, lower values are regressions.
+for the same comparison cohort from the HF dataset, computes the median for
+each available metric, and evaluates the current run with the metric's
+rolling regression policy. For v2 records, that cohort is `model_id`,
+`gpu_type`, `workload_id`, `variant_id`, `benchmark_version`,
+`recipe_fingerprint`, `hardware_profile_id`, and `software_profile_id`. For
+latency, memory, and component times, higher values are regressions. For
+throughput, lower values are regressions.
+
+A metric exceeds its rolling threshold when both of these are true:
+
+```text
+percent_delta > threshold_percent
+absolute_delta > threshold_absolute
+```
+
+Gated metrics fail CI when that threshold crossing happens. Set `gated: false`
+for metrics that should remain visible in reports and the dashboard without
+failing CI. Dashboard/API payloads expose `threshold_exceeded` separately from
+`regressed`, where `regressed` means a gated CI failure. Missing or `null`
+metrics are skipped.
 
 This is the **drift detector** — it catches sub-threshold regressions that
 slowly add up. Only scheduled-main successful records are baseline eligible.
@@ -172,6 +195,51 @@ agent skill to advance the rolling median.
 
 ## Schemas
 
+### Benchmark config (`.buildkite/performance-benchmarks/tests/*.json`)
+
+Benchmark configs without `config_schema_version` are treated as legacy v1
+configs and remain loadable. New or migrated configs should use
+`config_schema_version: 2` and include explicit comparable identity fields:
+
+```jsonc
+{
+  "benchmark_id": "wan-t2v-1.3b-2gpu",
+  "config_schema_version": 2,
+  "workload_id": "wan-t2v",
+  "variant_id": "1.3b-sp2",
+  "benchmark_version": 2
+}
+```
+
+`benchmark_id` is still required in this phase because raw artifact names,
+generated-video directories, normalized record paths, and the current rolling
+baseline comparator still depend on it. The v2 identity fields are config
+metadata that make the measured workload explicit:
+
+| Field | Purpose |
+|---|---|
+| `workload_id` | Stable benchmark family, such as `wan-t2v`. |
+| `variant_id` | Intentional recipe family, including model size and parallelism config, such as `1.3b-sp2`. |
+| `benchmark_version` | Version of the measurement protocol and comparison policy. |
+
+If a config declares `config_schema_version: 2`, loading fails clearly when any
+required v2 identity field is missing. If v2 identity or metadata fields are
+added without `config_schema_version: 2`, loading also fails so partial
+migrations do not silently run as v1 configs. Optional v2 metadata fields
+reserved for follow-up work, such as `metric_threshold_policy` and
+`quality_metadata`, must be JSON objects when present. (`recipe` is emitted
+by the harness and is not config-declarable.)
+
+Recipe fingerprinting, hardware/software profile IDs, exact-identity
+comparison, and dashboard cohort grouping land with this change: v2 records
+compare only within their identity cohort, and a record that opens a NEW
+cohort is marked `baseline_status: "initialized_new_cohort"` (regression
+gating starts once that cohort accumulates history). Legacy v1 configs still
+run and are normalized for reporting, but their records skip rolling-baseline
+comparison entirely (`baseline_status: "skipped_missing_identity"`, never
+baseline eligible); only static thresholds gate them. Metric-specific
+threshold policies and promoted baselines remain separate follow-ups.
+
 ### Raw record (`results/perf_*.json`)
 
 Written by `test_inference_performance.py`. One file per benchmark run.
@@ -179,6 +247,10 @@ Written by `test_inference_performance.py`. One file per benchmark run.
 ```jsonc
 {
   "benchmark_id": "wan-t2v-1.3b-2gpu",
+  "result_schema_version": 2,
+  "workload_id": "wan-t2v",
+  "variant_id": "1.3b-sp2",
+  "benchmark_version": 2,
   "model_short_name": "Wan2.1-T2V-1.3B-Diffusers",
   "device": "NVIDIA L40S",
   "num_gpus": 2,
@@ -196,12 +268,62 @@ Written by `test_inference_performance.py`. One file per benchmark run.
     "max_dit_time_s": 10.0,
     "max_vae_decode_time_s": 10.0
   },
+  "regression_thresholds": {
+    "latency": {
+      "threshold_percent": 0.10,
+      "threshold_absolute": 1.0,
+      "gated": true
+    }
+  },
   "commit": "<full sha>",
+  "run_source": "pr",
+  "branch": "feature/perf-change",
   "pr_number": "1234",
+  "test_scope": "direct",
+  "build_url": "https://buildkite.example/build",
+  "build_id": "<buildkite-build-id>",
+  "job_id": "<buildkite-job-id>",
   "timestamp": "2026-05-08T22:00:00+00:00",
+  "quality_metadata": { "quality_status": "canonical" },
   "text_encoder_time_s": 2.141,
   "dit_time_s": 8.437,
-  "vae_decode_time_s": 3.208
+  "vae_decode_time_s": 3.208,
+  "recipe": {
+    "recipe_schema_version": 1,
+    "benchmark": {
+      "benchmark_id": "wan-t2v-1.3b-2gpu",
+      "workload_id": "wan-t2v",
+      "variant_id": "1.3b-sp2",
+      "benchmark_version": 2
+    },
+    "model": { "model_path": "Wan-AI/Wan2.1-T2V-1.3B-Diffusers" },
+    "init_kwargs": { "num_gpus": 2, "sp_size": 2, "tp_size": 1 },
+    "generation_kwargs": { "height": 480, "width": 832, "num_frames": 45 },
+    "inputs": { "prompt_count": 1, "prompt_sha256": ["<measured-prompt-sha256>"] },
+    "attention": { "requested_backend": "FLASH_ATTN", "resolved_backend": "FLASH_ATTN" }
+  },
+  "recipe_fingerprint": "<sha256>",
+  "hardware_profile": {
+    "device_type": "cuda",
+    "gpu_count": 2,
+    "gpus": [{ "name": "NVIDIA L40S", "memory_gb": 48, "compute_capability": "8.9" }],
+    "interconnect": "none_or_partial"
+  },
+  "hardware_profile_id": "hw-<sha256-prefix>",
+  "software_profile": {
+    "python": "3.12",
+    "pytorch": "2.12",
+    "cuda": "13.0",
+    "packages": {
+      "fastvideo_kernel": "0.3.2",
+      "flashinfer": "0.2.11",
+      "nvidia_cutlass_dsl": "4.5.0",
+      "triton": "3.4.1"
+    }
+  },
+  "software_profile_id": "sw-<sha256-prefix>",
+  "environment_metadata": { "env": { "IMAGE_VERSION": "py3.12-cuda13.0.0" } },
+  "environment_fingerprint": "env-<sha256-prefix>"
 }
 ```
 
@@ -213,6 +335,10 @@ result, used as the rolling-baseline source of truth.
 ```jsonc
 {
   "model_id": "wan-t2v-1.3b-2gpu",
+  "result_schema_version": 2,
+  "workload_id": "wan-t2v",
+  "variant_id": "1.3b-sp2",
+  "benchmark_version": 2,
   "timestamp": "2026-05-08T22:00:00+00:00",
   "commit_sha": "<full sha>",
   "gpu_type": "NVIDIA L40S",
@@ -222,34 +348,69 @@ result, used as the rolling-baseline source of truth.
   "text_encoder_time_s": 2.141,
   "dit_time_s": 8.437,
   "vae_decode_time_s": 3.208,
+  "regression_thresholds": {
+    "latency": {
+      "threshold_percent": 0.08,
+      "threshold_absolute": 0.5,
+      "gated": true
+    }
+  },
+  "recipe_fingerprint": "<sha256>",
+  "hardware_profile_id": "hw-<sha256-prefix>",
+  "software_profile_id": "sw-<sha256-prefix>",
+  "environment_fingerprint": "env-<sha256-prefix>",
+  "run_source": "pr",
+  "branch": "feature/perf-change",
+  "pr_number": "1234",
+  "test_scope": "direct",
+  "build_url": "https://buildkite.example/build",
+  "build_id": "<buildkite-build-id>",
+  "job_id": "<buildkite-job-id>",
+  "quality_metadata": { "quality_status": "canonical" },
   "success": true
 }
 ```
 
 ### Compatibility with legacy records
 
-Older records in the HF dataset may not have component timing fields. The
-comparator ignores missing or `null` metrics when computing a median, and the
-dashboard lists skipped plots for metric series that have no non-null values.
-Records missing both `run_source` and `baseline_eligible` are treated as legacy
-successful main/full-suite uploads and remain eligible for rolling baselines.
+Older records in the HF dataset may not have `result_schema_version`,
+component timing fields, or v2 identity/profile fields. Records without
+`result_schema_version` are treated as v1. The comparator ignores missing or
+`null` metrics when computing a median, and the dashboard lists skipped plots
+for metric series that have no non-null values. Records missing both
+`run_source` and `baseline_eligible` are treated as legacy successful
+main/full-suite uploads and remain eligible for rolling baselines.
+Current `perf_*.json` artifacts that lack the v2 comparison identity are
+normalized for reporting but skip rolling-baseline comparison and are not marked
+baseline eligible.
+
+New records compare only against the same `model_id`, `gpu_type`,
+`workload_id`, `variant_id`, `benchmark_version`, `recipe_fingerprint`,
+`hardware_profile_id`, and `software_profile_id` cohort.
+`environment_metadata` and `environment_fingerprint` are audit data and are not
+part of the comparison key.
+The recipe prompt digests describe the prompts actually measured by the
+benchmark run; extra configured prompts are ignored unless the benchmark runner
+executes them.
+Software profile package cohorts keep exact versions for relevant
+attention/kernel packages, including FastVideo kernels, FlashAttention,
+FlashInfer, Cutlass DSL, SageAttention, Triton, and xFormers when installed.
 
 ## Environment variable reference
 
 | Variable | Default | Used by | Purpose |
 |---|---|---|---|
-| `PERF_MAX_REGRESSION` | `0.05` | `compare_baseline.py` | Per-metric regression fraction that fails the build. |
 | `PERFORMANCE_TRACKING_ROOT` | `/tmp/perf-tracking` | `compare_baseline.py`, `dashboard.py` | Local directory the HF dataset is synced to. |
 | `PERF_REPORTS_DIR` | `/root/data/perf_reports` | `compare_baseline.py`, `dashboard.py` | Where the Markdown summary and Plotly HTML get written for Buildkite to pick up. |
-| `HF_REPO_ID` | `FastVideo/performance-tracking` | `hf_store.py` | HF dataset repo holding rolling-baseline records. |
-| `HF_API_KEY`, `HUGGINGFACE_HUB_TOKEN`, `HF_TOKEN` | unset | `hf_store.py` | Required for upload or private dataset reads. |
-| `PERF_RUN_SOURCE` | inferred | `compare_baseline.py` | Source metadata for uploaded records: `pr`, `local`, `scheduled_main`, or `unknown`. |
+| `HF_REPO_ID` | `FastVideo/performance-tracking` | `fastvideo/performance/hf_store.py` | HF dataset repo holding rolling-baseline records. |
+| `HF_API_KEY`, `HUGGINGFACE_HUB_TOKEN`, `HF_TOKEN` | unset | `fastvideo/performance/hf_store.py` | Required for upload or private dataset reads. |
+| `PERF_RUN_SOURCE` | inferred | `compare_baseline.py`, `test_inference_performance.py` | Source metadata for uploaded records: `pr`, `local`, `scheduled_main`, or `unknown`. |
 | `PERF_UPLOAD_POLICY` | `never` | `compare_baseline.py` | Upload policy: `never`, `pass`, or `always`. |
 | `PERF_PYTEST_RC` | unset | `compare_baseline.py` | Static-threshold pytest exit code, used so scheduled-main failures can be uploaded with `success=false`. |
 | `TEST_SCOPE` | unset | `compare_baseline.py` | CI context used to infer scheduled-main runs together with `BUILDKITE_BRANCH=main`. |
 | `BUILDKITE_BRANCH`, `BUILDKITE_COMMIT`, `BUILDKITE_PULL_REQUEST` | unset | `compare_baseline.py`, `test_inference_performance.py` | CI metadata stamped into records. |
 | `DASHBOARD_DAYS` | `30` | `dashboard.py` | Lookback window for the Plotly trend pages. |
-| `PERFORMANCE_TRACKING_SYNC_REUSE_TTL_SECONDS` | `3600` | `hf_store.py` | Freshness window for reusing an existing HF sync when requested by dashboard consumers. |
+| `PERFORMANCE_TRACKING_SYNC_REUSE_TTL_SECONDS` | `3600` | `fastvideo/performance/hf_store.py` | Freshness window for reusing an existing HF sync when requested by dashboard consumers. |
 | `FASTVIDEO_STAGE_LOGGING` | set by the pytest test | `test_inference_performance.py` | Enables pipeline stage timing capture for component metrics during benchmark runs. |
 
 ## CI integration
@@ -260,17 +421,22 @@ point is `fastvideo/tests/modal/pr_test.py:run_performance_tests` and the
 Buildkite artifact upload is in
 `.buildkite/scripts/pr_test.sh:upload_performance_artifacts`.
 
-Each performance build runs pytest first. If that fixed-threshold phase fails,
-`compare_baseline.py` is skipped, so Markdown summaries and normalized JSON
-artifacts are not emitted. The dashboard still runs best-effort for
-observability. When pytest passes, the rolling-baseline phase emits:
+Each performance build runs pytest first. PR and direct runs only continue to
+`compare_baseline.py` when that fixed-threshold phase passes; if pytest fails,
+Markdown summaries and normalized JSON artifacts are not emitted. Scheduled
+main runs set `PERF_UPLOAD_POLICY=always`, so they still run
+`compare_baseline.py` (with `PERF_PYTEST_RC` set) after a fixed-threshold
+failure. Those failed scheduled main runs emit summaries and normalized
+records, upload records with `success=false`, and are excluded from future
+rolling baselines. The dashboard still runs best-effort for observability.
+When the rolling-baseline phase runs, it emits:
 
 * **Markdown summary** — appended to `$GITHUB_STEP_SUMMARY` when that variable
   is set, and written as `perf_<sha>_<ts>.md` for Buildkite upload. Contains a
   per-benchmark row with current vs. baseline values for latency, throughput,
   memory, text encoder time, DiT time, and VAE decode time.
 * **Plotly dashboard** — `dashboard_<sha>_<ts>.html` showing time-series for
-  each metric grouped by `(model_id, gpu_type)`.
+  each metric grouped by comparison cohort.
 * **Normalized records** — `normalized_perf_*.json`, one per benchmark.
   Useful as input to the
   [`reseed-performance-baseline`](https://github.com/hao-ai-lab/FastVideo/blob/main/.agents/skills/reseed-performance-baseline/SKILL.md)
@@ -279,11 +445,16 @@ observability. When pytest passes, the rolling-baseline phase emits:
 ## Adding a new benchmark
 
 1. Drop a new JSON config into
-   `.buildkite/performance-benchmarks/tests/<name>.json`. Required keys:
+   `.buildkite/performance-benchmarks/tests/<name>.json`. New configs should
+   use v2 identity fields:
 
    ```json
    {
      "benchmark_id": "<unique-id>",
+     "config_schema_version": 2,
+     "workload_id": "<stable-workload-id>",
+     "variant_id": "<variant, e.g. 1.3b-sp2>",
+     "benchmark_version": 1,
      "model": { "model_path": "...", "model_short_name": "..." },
      "init_kwargs": { "num_gpus": 1, ... },
      "generation_kwargs": { "num_frames": 45, ... },
@@ -299,9 +470,19 @@ observability. When pytest passes, the rolling-baseline phase emits:
          "max_vae_decode_time_s": 10.0
        },
        "default": { "max_generation_time_s": 120.0, "max_peak_memory_mb": 30000.0 }
+     },
+     "regression_thresholds": {
+       "latency": { "threshold_percent": 0.10, "threshold_absolute": 1.0, "gated": true }
      }
-   }
-   ```
+  }
+
+  ```
+
+   Legacy v1 configs without `config_schema_version` still load, but should not
+   gain v2 identity or metadata fields until they are migrated to
+   `config_schema_version: 2`. For v2 configs, `workload_id`, `variant_id`,
+   and `benchmark_version` are part of the comparison key; benchmark runs
+   fail if any of these identity fields are missing.
 
 2. The pytest test auto-discovers all configs — no test code needed. CI
    picks it up on the next `/test performance` run.
@@ -320,10 +501,17 @@ observability. When pytest passes, the rolling-baseline phase emits:
    a useful fixed gate. The rolling baseline will still track component times
    when static component thresholds are omitted.
 
+6. Omit `regression_thresholds` to use the default rolling-baseline policy, or
+   include only benchmark-specific deviations. Tune these independently from
+   the fixed thresholds when a metric is noisy or should be informational. The
+   fixed `thresholds` block is an absolute pytest ceiling. The
+   `regression_thresholds` block controls rolling-baseline comparisons against
+   recent scheduled-main records.
+
 ## Troubleshooting
 
-**"No baseline for ... Initializing"** — first run for this `(model_id,
-gpu_type)`. Run will pass and (if persisting) seed the first record.
+**"No baseline for ... Initializing"** — first run for this comparison cohort.
+Run will pass and (if persisting) seed the first record.
 
 **Persistent failure right after a torch / kernel / image upgrade** —
 genuine regression *or* baseline drift. Compare the failing normalized record
@@ -336,5 +524,5 @@ pipelines that did not report a mapped component stage.
 
 **Component timing is `null`** — the generated result did not include a mapped
 stage in `logging_info.stages`. Check that the pipeline emits stage logging
-and that the stage name is listed in `STAGE_METRIC_MAP` in
-`test_inference_performance.py`.
+and that the stage emits `component_metric` or is covered by the legacy
+`STAGE_METRIC_MAP` fallback in `test_inference_performance.py`.

docs/contributing/testing.md

@@ -180,6 +180,30 @@ python fastvideo/tests/ssim/reference_videos_cli.py copy-local \
   --device-folder L40S_reference_videos
 ```
 
+### SSIM Bootstrap Mode
+
+Normal SSIM runs are strict: if a reference video or latent is missing, the
+test fails. For new-model PRs, CI can run SSIM in bootstrap mode so missing
+references are uploaded as draft artifacts for review instead of immediately
+blocking on a missing canonical reference.
+
+Buildkite enables SSIM bootstrap mode when either condition is true:
+
+- the PR title or Buildkite message contains `[new-model]`;
+- `FASTVIDEO_SSIM_BOOTSTRAP_MODE=1` is set for the Buildkite job.
+
+Bootstrap mode passes `--ssim-bootstrap-mode` to pytest. When a generated
+artifact is available, the test uploads it under the `drafts/...` namespace in
+the SSIM reference repo and marks that case as expected-failed. After reviewing
+the draft, promote it into the canonical reference layout:
+
+```bash
+python fastvideo/tests/ssim/reference_videos_cli.py promote-draft \
+  --quality-tier default \
+  --device-folder L40S_reference_videos \
+  --model-id <model_id>
+```
+
 ## CI Integration
 
 FastVideo CI tests are orchestrated by Buildkite and run on Modal GPU

docs/design/inference_schema_parity_inventory.yaml

@@ -191,6 +191,9 @@ surfaces:
         sources:
           - fastvideo.configs.pipelines.gen3c.Gen3CConfig
           - fastvideo.configs.pipelines.gen3c.Gen3CInferenceConfig
+      color_correction_strength:
+        sources:
+          - fastvideo.configs.pipelines.dreamx_world.DreamXWorld5BARPipelineConfig
       default_camera_rotation:
         sources:
           - fastvideo.configs.pipelines.gen3c.Gen3CConfig

docs/design/server_contracts/dynamo.md

@@ -330,7 +330,7 @@ at FastVideo's CI — before the Dynamo-side integration even knows.
   internal; presets identify them by name on
   `PipelineSelection.preset`).
 * `fastvideo.fastvideo_args.FastVideoArgs` (legacy compat type).
-* `fastvideo.api.compat.*` private helpers
+* `fastvideo.api.translation.*` private helpers
   (`_validate_continuation_state` etc.) — the public boundary is
   `VideoGenerator` + `fastvideo.api`.
 * Any flat legacy LTX-2 kwarg (`ltx2_refine_upsampler_path`,

docs/design/server_contracts/openai.md

@@ -48,15 +48,17 @@ highest first:
    `request.model_fields_set` (Pydantic v2). Unset fields do not count,
    even if the Pydantic model has a schema default for them.
 2. **`ServeConfig.default_request` (operator-explicit)** — projected via
-   [`explicit_request_updates()`](https://github.com/hao-ai-lab/FastVideo/blob/main/fastvideo/api/compat.py);
+   [`explicit_request_updates()`](https://github.com/hao-ai-lab/FastVideo/blob/main/fastvideo/api/translation.py);
    only fields the operator actually wrote into the YAML count as
-   defaults. Every other field inherits the schema default rather than
-   being pinned.
+   defaults (an explicit `null` counts as unset). Every other sampling
+   field stays `None` — "inherit the model preset" — and other sections
+   keep their schema defaults without being pinned.
 3. **Hardcoded fallback** — e.g. `fps = 24`.
 
-The gate matters: both surfaces carry schema defaults. Without
-`model_fields_set` / explicit-path tracking, schema defaults would
-masquerade as intent and silently shadow the other side.
+The gate matters: the Pydantic surface carries schema defaults and the
+dataclass surface carries non-None defaults outside `sampling`. Without
+`model_fields_set` / explicit-path tracking, defaults would masquerade
+as intent and silently shadow the other side.
 
 See [`video_api.py::_build_generation_kwargs`](https://github.com/hao-ai-lab/FastVideo/blob/main/fastvideo/entrypoints/openai/video_api.py)
 for the canonical implementation; the per-request assembly lives there,

docs/inference/optimizations.md

@@ -74,6 +74,23 @@ uv pip install ninja
 python setup.py install
 ```
 
+### Flash Attention 4 (opt-in)
+
+FastVideo never auto-selects FlashAttention-4 (`flash_attn.cute`) just because it
+is installed: its CuTeDSL kernels JIT-compile per shape family and can fail at
+runtime on some GPU/shape combinations. To use FA4, install the pinned
+`flash-attn-4` build (see the `flash-attn-4` source in `pyproject.toml`) and set:
+
+```bash
+export FASTVIDEO_FA4=1
+```
+
+On GPUs below sm90 a capability gate routes to FlashAttention-2 the calls FA4
+cannot serve there: grad-enabled (training) attention (FA4's backward requires
+sm90+) and GQA attention (FA4's `pack_gqa` fails to JIT-compile below sm90).
+On sm90+ both run on FA4. If FA4 is unusable while `FASTVIDEO_FA4=1` is set,
+FastVideo fails loudly instead of silently falling back.
+
 ### FP4 Flash Attention 4 (Blackwell only)
 
 **`FLASH_ATTN`** with **`--nvfp4_fa4`**

docs/inference/support_matrix.md

@@ -58,6 +58,8 @@ pipeline initialization and sampling.
 | FastWan2.1 T2V 1.3B | `FastVideo/FastWan2.1-T2V-1.3B-Diffusers` | 480P | ⭕ | ⭕ | ⭕ | ✅ | ⭕ |
 | FastWan2.2 TI2V 5B Full Attn* | `FastVideo/FastWan2.2-TI2V-5B-FullAttn-Diffusers` | 720P | ⭕ | ⭕ | ⭕ | ✅ | ⭕ |
 | Wan2.2 TI2V 5B | `Wan-AI/Wan2.2-TI2V-5B-Diffusers` | 720P | ⭕ | ⭕ | ✅ | ⭕ | ⭕ |
+| DreamX-World 5B Cam | `FastVideo/DreamX-World-5B-Cam-Diffusers` | 480P | ⭕ | ⭕ | ⭕ | ⭕ | ⭕ |
+| DreamX-World 5B AR | `FastVideo/DreamX-World-5B-Diffusers` | 704px1280p | ⭕ | ⭕ | ⭕ | ⭕ | ⭕ |
 | Lucy Edit Dev 5B*** | `decart-ai/Lucy-Edit-Dev` | 480P | ⭕ | ⭕ | ⭕ | ⭕ | ⭕ |
 | Wan2.2 T2V A14B | `Wan-AI/Wan2.2-T2V-A14B-Diffusers` | 480P<br>720P | ❌ | ❌ | ✅ | ⭕ | ⭕ |
 | Wan2.2 I2V A14B | `Wan-AI/Wan2.2-I2V-A14B-Diffusers` | 480P<br>720P | ❌ | ❌ | ✅ | ⭕ | ⭕ |

docs/training/trackers.md

@@ -0,0 +1,91 @@
+# Training Trackers
+
+FastVideo can send training metrics and validation media to Weights & Biases
+or SwanLab. Tracking runs only on global rank 0, and local tracker files are
+stored under `<output_dir>/tracker`.
+
+## Supported Trackers
+
+| Value | Backend | Installation |
+|-------|---------|--------------|
+| `wandb` | Weights & Biases | Included with FastVideo |
+| `swanlab` | SwanLab | Install the optional `swanlab` dependency |
+| `none` | Disable external tracking | No additional package |
+
+You can enable more than one backend, for example `trackers: [wandb, swanlab]`.
+Metrics and validation media are converted to the artifact type required by
+each backend.
+
+## Install SwanLab
+
+For a published FastVideo installation, install the SwanLab extra:
+
+```bash
+uv pip install "fastvideo[swanlab]"
+```
+
+For an editable source checkout, include the same extra during installation:
+
+```bash
+uv pip install -e ".[swanlab]"
+```
+
+If FastVideo is already installed, you can install the compatible SDK directly:
+
+```bash
+uv pip install "swanlab>=0.6.7"
+```
+
+Authenticate once before starting a training run:
+
+```bash
+swanlab login
+```
+
+See the [SwanLab login documentation](https://docs.swanlab.cn/en/api/cli-swanlab-login.html)
+for non-interactive and self-hosted setups.
+
+## Configure Tracking
+
+Select SwanLab in the YAML config used by the modular training framework:
+
+```yaml
+training:
+  checkpoint:
+    output_dir: outputs/my_run
+  tracker:
+    trackers: [swanlab]
+    project_name: my_project
+    run_name: my_run
+```
+
+To log to both supported services:
+
+```yaml
+training:
+  tracker:
+    trackers: [wandb, swanlab]
+    project_name: my_project
+    run_name: my_run
+```
+
+An empty or omitted `trackers` list selects W&B when `project_name` is set.
+Use an explicit `none` entry to disable external tracking:
+
+```yaml
+training:
+  tracker:
+    trackers: [none]
+```
+
+## Validation Videos
+
+SwanLab currently accepts GIF video artifacts. FastVideo converts validation
+MP4 files and in-memory video arrays to GIF automatically before logging them.
+For video files, FastVideo uses the sampling frame rate supplied by the caller,
+or the source file's frame rate when no value is supplied. In-memory arrays use
+the frame rate supplied by the caller. Both forms fall back to 16 FPS when no
+frame rate is available.
+
+For details about configuring validation callbacks, see
+[Training Infrastructure](train_infra.md#callbacks-pluggable-hooks).

docs/training/train_infra.md

@@ -161,6 +161,21 @@ training:
     decay_interval_steps: 0
 ```
 
+`training.data.data_path` can also mix multiple preprocessed datasets by using a mapping from dataset path to repeat count:
+
+```yaml
+training:
+  data:
+    data_path:
+      data/zeldam2-clean: 1
+      data/multi3d_games: 2
+```
+
+The repeat count duplicates that dataset's parquet file list before shuffling/sampling, so the example above trains with roughly twice as much `multi3d_games` exposure as `zeldam2-clean`. Paths are just suggested locations; use any local path that contains a FastVideo preprocessed parquet dataset.
+
+See [Training Trackers](trackers.md) to configure Weights & Biases or SwanLab,
+including SwanLab installation and authentication.
+
 ### `callbacks` — Pluggable hooks
 
 Callbacks run at specific points in the training loop (before/after optimizer
@@ -323,6 +338,40 @@ Self-Forcing inherits all DMD2 parameters, plus:
 | `enable_gradient_in_rollout` | `true` | Enable backprop through rollout |
 | `start_gradient_frame` | `0` | Frame index where gradients begin |
 
+### Streaming Long Tuning
+
+`StreamingLongTuningMethod` extends Self-Forcing for LongLive-style rollouts. It
+keeps a streaming state, generates overlapping chunks, and trains only the new
+frames while preserving context from earlier chunks.
+
+For the MatrixGame2/Zelda world-model example, self-forcing and long tuning are
+separate runs: first train or load the 1k-step self-forcing checkpoint using
+`examples/train/scenario/worldmodel/zelda/self_forcing_causal_i2v.yaml`,
+then run
+`examples/train/scenario/worldmodel/zelda/streaming_long_tuning_causal_i2v.yaml`
+from that checkpoint for the 3k-step streaming long-tuning stage.
+
+```yaml
+method:
+  _target_: fastvideo.train.methods.distribution_matching.streaming_long_tuning.StreamingLongTuningMethod
+  streaming_chunk_size: 9
+  streaming_max_length: 39
+  streaming_fixed_overlap_latents: 3
+  streaming_reencode_overlap_anchor: true
+  streaming_anchor_inject_k: 1
+  streaming_require_full_blocks: true
+  multi_phased_distill_schedule:
+    - stage: streaming_long
+      start_step: 0
+      end_step: 3000
+      num_latent_t: 39
+      streaming_training: true
+```
+
+See
+`examples/train/scenario/worldmodel/zelda/streaming_long_tuning_causal_i2v.yaml`
+for a complete MatrixGame2/Zelda configuration.
+
 ---
 
 ## Callbacks

examples/inference/basic/README.md

@@ -39,17 +39,20 @@ All you need to generate videos using multi-gpus from state-of-the-art diffusion
 
 ```python
 from fastvideo import VideoGenerator
+from fastvideo.api import EngineConfig, GenerationRequest, GeneratorConfig
 
 def main():
-    generator = VideoGenerator.from_pretrained(
-        "Wan-AI/Wan2.1-T2V-1.3B-Diffusers",
-        num_gpus=1,
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="Wan-AI/Wan2.1-T2V-1.3B-Diffusers",
+            engine=EngineConfig(num_gpus=1),
+        )
     )
 
     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)
+    result = generator.generate(GenerationRequest(prompt=prompt))
 
 if __name__ == "__main__":
     main()

examples/inference/basic/V2_PORTING_STATUS.md

@@ -1,94 +0,0 @@
-# v2 porting status — fastvideo models → the v2 (recipe, runtime) substrate
-
-Goal: every model in fastvideo's registry resolves through the **v2 `VideoGenerator`** / `Engine`
-(typed `fastvideo.api` configs + the real torch backend) to a recipe that can construct and run it.
-
-**Scope: ALL fastvideo models (achieved).** v2 now resolves **63/64** of fastvideo's registered HF ids
-by exact id (PRIMARY), plus the architecture fallback for local/unregistered checkpoints. The single
-remaining id — `FastVideo/Wan2.1-VSA-T2V-14B-720P-Diffusers` — is **environment-blocked**: its VSA
-(Sparse-Linear Attention) kernels require `nvcc` (not built in this bring-up). It arch-resolves to the
-base Wan card but needs the VSA kernel build to run faithfully.
-
-Dispatch is **architecture-driven** (`v2/registry.py`): exact HF id → short-name → architecture
-inference from the checkpoint (pipeline / transformer / VAE class names + `z_dim`, `transformer_2`,
-`spatial_upsampler`). Adding a model is one `_BUCKET_C` row (HF ids → builders + transformer class).
-
-## The porting mechanism — self-contained recipe packages
-Every net-new arch is a **self-contained recipe package** (`v2/recipes/<arch>/` = `card.py` `loop.py`
-`program.py` [+ `sampler.py`] + an optional `v2/platform/backends/torch_<arch>.py` adapter). The card
-declares its torch adapter via **`ComponentSpec.adapter="module:Class"`** (the `_explicit_adapter` seam in
-`torch_backend.py`) instead of editing the shared `_make_dit`/`_make_vae`/`_make_text_encoder` dispatch —
-so a port adds **only new files**, never touching shared code, and parallel ports never conflict. New
-samplers/loops live in-package. Registration is one row in `v2/registry.py:_BUCKET_C`.
-
-## Working today (GPU-verified, real video/audio) — committed on `v2`
-| Official example(s) | Model | v2 card |
-|---|---|---|
-| `basic.py`, `basic_mps.py`, `basic_ray.py` | `Wan-AI/Wan2.1-T2V-1.3B-Diffusers` | wan21 |
-| `basic_self_forcing_causal.py` | `wlsaidhi/SFWan2.1-T2V-1.3B-Diffusers` | wan_causal |
-| `basic_ltx2_distilled.py` | `FastVideo/LTX2-Distilled-Diffusers` (2-stage + spatial upsampler) | ltx2 |
-| `basic_wan2_2_ti2v.py` | `Wan-AI/Wan2.2-TI2V-5B-Diffusers` | wan2.2-ti2v |
-| `basic_wan2_2.py` | `Wan-AI/Wan2.2-T2V-A14B-Diffusers` (MoE + CPU expert offload) | wan2.2-a14b |
-| `basic_ltx2.py` | `Davids048/LTX2-Base-Diffusers` | ltx2 base |
-| `basic_ltx2_3_distilled.py` | `FastVideo/LTX-2.3-Distilled-Diffusers` (joint T2VS, video+audio) | ltx2.3-distilled |
-
-Plus the **Wan2.1 i2v cluster** (Fun-1.3B-InP GPU-verified; I2V-14B-480P/720P + Wan2.2-I2V-A14B MoE reuse
-the i2v card) — CLIP image-encoder + first-frame `[mask|cond]` → 36ch DiT.
-
-## GPU bring-up results (real weights on H100 NVL, single-GPU, TORCH_SDPA)
-**20 models generate real video/audio on GPU** — the 7 above + **13 of the newly-ported** archs, each run
-end-to-end through the real `VideoGenerator` (resolve → stamp → CUDA load → generate). The rest are blocked
-by a **fastvideo-shared-code / missing-kernel / HF-access** wall, NOT a v2 recipe bug (the v2 recipes are
-faithful — e.g. cosmos25's DiT+VAE produced finite output; only its Qwen2.5-VL encoder hit a library
-incompat). All ports also resolve + run end-to-end on the CPU toy backend (`test_bucket_c_ports.py`).
-
-| GPU status | Models |
-|---|---|
-| ✅ **Verified** (real GPU output) | stable_audio (audio), matrixgame2, matrixgame3, gen3c, wan_fun_control, lucy_edit, hunyuangamecraft, hunyuan_video, hunyuan_video15, longcat (13.58B), sfwan22 (2×14B MoE, expert offload), lingbotworld (2×14B, offload), fastwan (TI2V-5B-FullAttn DMD) |
-| 🚫 fastvideo/env-blocked | **cosmos25** (DiT+VAE ran; Qwen2.5-VL encoder → transformers 5.12.1 incompat in fastvideo); **kandinsky5** (fastvideo registry registers a bare `PipelineConfig`); **hyworld** (fastvideo DiT hardcodes `flash_attn`, not built); **turbowan** 1.3B/i2v + **fastwan** VSA-variants (SLA/VSA sparse-attn params + Triton kernels need nvcc) |
-| 🚫 access-blocked (HF-gated) | cosmos2, flux2, sd35 (no HF token in this env) |
-
-To unblock the env-blocked: build `fastvideo-kernel` (SLA/VSA Triton, needs nvcc); pin a fastvideo-compatible
-`transformers` for the Qwen2.5-VL encoder; add a Kandinsky5 `PipelineConfig` + an SDPA fallback in the
-hyworld DiT (all fastvideo-side / environment, not v2 recipe work).
-
-## Newly ported (recipe details)
-Each resolves through the registry AND runs end-to-end on the CPU toy backend via the public `Engine`
-path (the `v2/tests/test_bucket_c_ports.py` regression guard), emitting the correct modality artifact.
-
-**15 net-new architectures** (each a new `TorchComponent` adapter + recipe):
-- **cosmos2** (Cosmos-Predict2-2B-Video2World) — EDM-Karras denoiser; new `CosmosDenoiseLoop` +
-  `build_karras_sigmas` (the reference port). **cosmos25** (Cosmos-Predict2.5 2B/14B) — flow-match,
-  per-frame plain-sigma timestep, Reason1/Qwen2.5-VL encoder. **gen3c** (GEN3C) — EDM + 82ch pose-buffer.
-- **hunyuan_video** (+FastHunyuan) — reuses WanDenoiseLoop, dual LLaMA+CLIP encoders, Hunyuan VAE.
-  **hunyuan_video15** (480p/720p). **hunyuangamecraft**, **hyworld** — interactive (camera/action).
-- **longcat** (T2V/I2V/VC). **kandinsky5** (5.0 T2V Lite).
-- **sd35** (MMDiT, image, triple-encoder). **flux2** (dev/klein, MMDiT image). **stable_audio** (audio).
-- **lingbotworld** (camera/Plucker), **matrixgame2**, **matrixgame3** — interactive world models.
-
-**5 Wan-family variants** (reuse the Wan/Causal arch, new in-package sampler/loop/conditioning):
-- **turbowan** — rCM few-step (faithful RCMScheduler port), 1.3B/14B T2V + I2V-A14B MoE.
-- **lucy_edit** — v2v editor (video-VAE-encode node → 96ch DiT input). **wan_fun_control** — control input.
-- **sfwan22** — Self-Forcing Wan2.2-A14B causal + MoE (i2v + t2v). **fastwan** — DMD 3-step (TI2V-5B-FullAttn
-  loadable; VSA-trained variants + non-strict `to_gate_compress` load are BRINGUP).
-
-BRINGUP scope per port (documented in each package): GPU load/run; for interactive/world-model archs the
-action/camera/memory conditioning needs a request-API extension (the t2v/degenerate path is what
-CPU-verifies); video2world/i2v frame-replace conditioning is threaded but inert without conditioning inputs.
-
-## Environment
-v2 bring-up runs **single-GPU, resident, on the `TORCH_SDPA` backend** (no fastvideo-kernel / VSA / FP4).
-The box has been rescheduled across hosts/arches/python versions mid-session; rebuild the venv for the
-current arch when that happens: `uv venv --python 3.12 .venv`; comment out `fastvideo-kernel` in
-`pyproject.toml`; `uv pip install -e ".[dev]"`. Source `/home/scratch.willlin_ent/.bringup_env`
-(`HF_HOME=./.cache` on scratch, `FASTVIDEO_ATTENTION_BACKEND=TORCH_SDPA`). v2 CPU mini: 240 passed, 2 skipped.
-
-## How to add a model to the v2 substrate
-1. `v2/recipes/<arch>/` — card (declare adapters via `ComponentSpec.adapter`; per-model `SamplingDefaults`),
-   loop (reuse `WanDenoiseLoop`/`chunk_rollout` or a new in-package loop+sampler), program.
-2. `v2/platform/backends/torch_<arch>.py` — a `TorchComponent` subclass (only the forward semantics) if the
-   arch is genuinely new; reuse `WanDiT`/`LTX2DiT`/`WanVAE`/`T5Encoder` via `load_id` when it isn't.
-3. One row in `v2/registry.py:_BUCKET_C` (HF ids → builders; `transformer_cls` for the arch fallback, or
-   `""` for explicit-id-only capability variants of an existing arch).
-4. CPU-verify: it resolves + runs on the toy backend (auto-covered by `test_bucket_c_ports.py`). Then GPU
-   bring-up (`stamp_*_checkpoints` → real weights) per BRINGUP notes.

examples/inference/basic/basic.py

@@ -1,6 +1,7 @@
 from fastvideo import VideoGenerator
-
-# from fastvideo.api.sampling_param import SamplingParam
+from fastvideo.api import (
+    EngineConfig, GenerationRequest, GeneratorConfig, OffloadConfig, OutputConfig,
+)
 
 OUTPUT_PATH = "video_samples"
 def main():
@@ -8,29 +9,32 @@ def main():
     # model.
     # If a local path is provided, FastVideo will make a best effort
     # attempt to identify the optimal arguments.
-    generator = VideoGenerator.from_pretrained(
-        "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
-        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"
-        # image_encoder_cpu_offload=False,
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="Wan-AI/Wan2.1-T2V-1.3B-Diffusers",
+            # FastVideo will automatically handle distributed setup
+            engine=EngineConfig(
+                num_gpus=1,
+                use_fsdp_inference=False,  # set to True if GPU is out of memory
+                offload=OffloadConfig(
+                    dit=False,
+                    vae=False,
+                    text_encoder=True,
+                    pin_cpu_memory=True,  # set to false if low CPU RAM or hit obscure "CUDA error: Invalid argument"
+                    # image_encoder=False,
+                ),
+            ),
+        )
     )
 
-    # sampling_param = SamplingParam.from_pretrained("Wan-AI/Wan2.1-T2V-1.3B-Diffusers")
-    # 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."
     )
-    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/")
+    video = generator.generate(
+        GenerationRequest(prompt=prompt, output=OutputConfig(output_path=OUTPUT_PATH, save_video=True)))
 
     # Generate another video with a different prompt, without reloading the
     # model!
@@ -40,7 +44,8 @@ def main():
         "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)
+    video2 = generator.generate(
+        GenerationRequest(prompt=prompt2, output=OutputConfig(output_path=OUTPUT_PATH, save_video=True)))
 
 
 if __name__ == "__main__":

examples/inference/basic/basic_cosmos2_5_i2w.py

@@ -1,24 +1,30 @@
 # SPDX-License-Identifier: Apache-2.0
 from fastvideo import VideoGenerator
-from fastvideo.api.sampling_param import SamplingParam
+from fastvideo.api import (
+    EngineConfig, GenerationRequest, GeneratorConfig, InputConfig, OffloadConfig, OutputConfig,
+)
 
 
 def main():
     # Point this to your local diffusers model dir (or replace with a HF model ID).
     model_path = "KyleShao/Cosmos-Predict2.5-2B-Diffusers"
 
-    generator = VideoGenerator.from_pretrained(
-        model_path,
-        num_gpus=1,
-        use_fsdp_inference=False,  # set True if GPU is out of memory
-        dit_cpu_offload=False,
-        vae_cpu_offload=False,
-        text_encoder_cpu_offload=True,
-        pin_cpu_memory=True,
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path=model_path,
+            engine=EngineConfig(
+                num_gpus=1,
+                use_fsdp_inference=False,  # set True if GPU is out of memory
+                offload=OffloadConfig(
+                    dit=False,
+                    vae=False,
+                    text_encoder=True,
+                    pin_cpu_memory=True,
+                ),
+            ),
+        )
     )
 
-    sampling_param = SamplingParam.from_pretrained(model_path)
-
     # image2world example from official repo
     image_path = "assets/images/bus_terminal.jpg"
 
@@ -33,13 +39,16 @@ def main():
         "Overhead signage in Chinese characters remains illuminated, enhancing the vibrant, urban night scene."
     )
 
-    generator.generate_video(
-        prompt,
-        sampling_param=sampling_param,
-        image_path=str(image_path),
-        num_cond_frames=1,
-        output_path="outputs_video/cosmos2_5_i2w.mp4",
-        save_video=True,
+    generator.generate(
+        GenerationRequest(
+            prompt=prompt,
+            inputs=InputConfig(image_path=str(image_path)),
+            output=OutputConfig(
+                output_path="outputs_video/cosmos2_5_i2w.mp4",
+                save_video=True,
+            ),
+            extensions={"num_cond_frames": 1},
+        )
     )
 
     generator.shutdown()
@@ -47,4 +56,3 @@ def main():
 
 if __name__ == "__main__":
     main()
-

examples/inference/basic/basic_cosmos2_5_t2w.py

@@ -1,24 +1,29 @@
 from fastvideo import VideoGenerator
-from fastvideo.api.sampling_param import SamplingParam
+from fastvideo.api import (
+    EngineConfig, GenerationRequest, GeneratorConfig, OffloadConfig, OutputConfig,
+)
 
 
 def main():
     # Point this to your local diffusers model dir (or replace with a HF model ID).
     model_path = "KyleShao/Cosmos-Predict2.5-2B-Diffusers"
 
-    generator = VideoGenerator.from_pretrained(
-        model_path,
-        num_gpus=1,
-        use_fsdp_inference=False,  # set True if GPU is out of memory
-        dit_cpu_offload=False,
-        vae_cpu_offload=False,
-        text_encoder_cpu_offload=True,
-        pin_cpu_memory=True,
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path=model_path,
+            engine=EngineConfig(
+                num_gpus=1,
+                use_fsdp_inference=False,  # set True if GPU is out of memory
+                offload=OffloadConfig(
+                    dit=False,
+                    vae=False,
+                    text_encoder=True,
+                    pin_cpu_memory=True,
+                ),
+            ),
+        )
     )
 
-    # Load default sampling parameters (negative_prompt, resolution, steps, etc.)
-    sampling_param = SamplingParam.from_pretrained(model_path)
-
     prompt = (
         "A high-definition video captures the precision of robotic welding in an industrial setting. "
         "The first frame showcases a robotic arm, equipped with a welding torch, positioned over a large metal structure. "
@@ -34,11 +39,14 @@ def main():
         "underscoring the ongoing nature of the welding operation."
     )
 
-    generator.generate_video(
-        prompt,
-        sampling_param=sampling_param,
-        output_path="outputs_video/cosmos2_5_t2w.mp4",
-        save_video=True,
+    generator.generate(
+        GenerationRequest(
+            prompt=prompt,
+            output=OutputConfig(
+                output_path="outputs_video/cosmos2_5_t2w.mp4",
+                save_video=True,
+            ),
+        )
     )
 
     generator.shutdown()
@@ -46,6 +54,3 @@ def main():
 
 if __name__ == "__main__":
     main()
-
-
-

examples/inference/basic/basic_cosmos2_5_v2w.py

@@ -1,23 +1,29 @@
 # SPDX-License-Identifier: Apache-2.0
 from fastvideo import VideoGenerator
-from fastvideo.api.sampling_param import SamplingParam
+from fastvideo.api import (
+    EngineConfig, GenerationRequest, GeneratorConfig, InputConfig,
+    OffloadConfig, OutputConfig,
+)
 
 
 def main():
     # Point this to your local diffusers model dir (or replace with a HF model ID).
     model_path = "KyleShao/Cosmos-Predict2.5-2B-Diffusers"
 
-    generator = VideoGenerator.from_pretrained(
-        model_path,
-        num_gpus=1,
-        use_fsdp_inference=False,  # set True if GPU is out of memory
-        dit_cpu_offload=False,
-        vae_cpu_offload=False,
-        text_encoder_cpu_offload=True,
-        pin_cpu_memory=True,
-    )
-
-    sampling_param = SamplingParam.from_pretrained(model_path)
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path=model_path,
+            engine=EngineConfig(
+                num_gpus=1,
+                use_fsdp_inference=False,  # set True if GPU is out of memory
+                offload=OffloadConfig(
+                    dit=False,
+                    vae=False,
+                    text_encoder=True,
+                    pin_cpu_memory=True,
+                ),
+            ),
+        ))
 
     # video2world example from official repo
     video_path = "assets/videos/robot_pouring.mp4"
@@ -36,18 +42,19 @@ def main():
         "The final frame captures the robotic arm with the pitcher finishing the pour, with the glass now filled to a higher level, while the pitcher is slightly tilted but still held securely by the gripper."
     )
 
-    generator.generate_video(
-        prompt,
-        sampling_param=sampling_param,
-        video_path=str(video_path),
-        num_cond_frames=1,
-        output_path="outputs_video/cosmos2_5_v2w.mp4",
-        save_video=True,
-    )
+    generator.generate(
+        GenerationRequest(
+            prompt=prompt,
+            inputs=InputConfig(video_path=str(video_path)),
+            output=OutputConfig(
+                output_path="outputs_video/cosmos2_5_v2w.mp4",
+                save_video=True,
+            ),
+            extensions={"num_cond_frames": 1},
+        ))
 
     generator.shutdown()
 
 
 if __name__ == "__main__":
     main()
-

examples/inference/basic/basic_dmd.py

@@ -2,7 +2,9 @@ import os
 import time
 from fastvideo import VideoGenerator
 
-from fastvideo.api.sampling_param import SamplingParam
+from fastvideo.api import (EngineConfig, GenerationRequest, GeneratorConfig,
+                           OffloadConfig, OutputConfig, PipelineSelection,
+                           SamplingConfig)
 
 OUTPUT_PATH = "video_samples_dmd2"
 def main():
@@ -10,30 +12,36 @@ def main():
 
     load_start_time = time.perf_counter()
     model_name = "FastVideo/FastWan2.1-T2V-1.3B-Diffusers"
-    generator = VideoGenerator.from_pretrained(
-        model_name,
-        # FastVideo will automatically handle distributed setup
-        num_gpus=1,
-        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"
-        dit_cpu_offload=False,
-        vae_cpu_offload=False,
-        VSA_sparsity=0.8,
-    )
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path=model_name,
+            engine=EngineConfig(
+                # FastVideo will automatically handle distributed setup
+                num_gpus=1,
+                use_fsdp_inference=False, # set to True if GPU is out of memory
+                # Adjust these offload parameters if you have < 32GB of VRAM
+                offload=OffloadConfig(
+                    text_encoder=True,
+                    pin_cpu_memory=True, # set to false if low CPU RAM or hit obscure "CUDA error: Invalid argument"
+                    dit=False,
+                    vae=False,
+                ),
+            ),
+            pipeline=PipelineSelection(experimental={"VSA_sparsity": 0.8}),
+        ))
     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
-
     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."
     )
     start_time = time.perf_counter()
-    video = generator.generate_video(prompt, output_path=OUTPUT_PATH, save_video=True, sampling_param=sampling_param)
+    video = generator.generate(
+        GenerationRequest(
+            prompt=prompt,
+            sampling=SamplingConfig(num_frames=81),
+            output=OutputConfig(output_path=OUTPUT_PATH, save_video=True),
+        ))
     end_time = time.perf_counter()
     gen_time = end_time - start_time
 
@@ -46,7 +54,12 @@ def main():
         "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)
+    video2 = generator.generate(
+        GenerationRequest(
+            prompt=prompt2,
+            sampling=SamplingConfig(num_frames=81),
+            output=OutputConfig(output_path=OUTPUT_PATH, save_video=True),
+        ))
     end_time = time.perf_counter()
     gen_time2 = end_time - start_time
 

examples/inference/basic/basic_dreamx_world.py

@@ -0,0 +1,79 @@
+import os
+
+from fastvideo import VideoGenerator
+from fastvideo.api import (ComponentConfig, EngineConfig, GenerationRequest,
+                           GeneratorConfig, InputConfig, OffloadConfig,
+                           OutputConfig, PipelineSelection, SamplingConfig)
+
+
+OUTPUT_PATH = os.getenv("DREAMX_WORLD_OUTPUT_PATH", "video_samples_dreamx_world")
+
+
+def _env_int(name: str, default: int) -> int:
+    return int(os.getenv(name, str(default)))
+
+
+def _env_float(name: str, default: float) -> float:
+    return float(os.getenv(name, str(default)))
+
+
+def main():
+    model_name = os.getenv("DREAMX_WORLD_MODEL_DIR", "FastVideo/DreamX-World-5B-Cam-Diffusers")
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path=model_name,
+            engine=EngineConfig(
+                num_gpus=1,
+                use_fsdp_inference=False,
+                offload=OffloadConfig(
+                    dit=False,
+                    vae=True,
+                    text_encoder=True,
+                    pin_cpu_memory=False,
+                ),
+            ),
+            pipeline=PipelineSelection(
+                components=ComponentConfig(override_pipeline_cls_name="DreamXWorldPipeline"), ),
+        ))
+
+    prompt = os.getenv(
+        "DREAMX_WORLD_PROMPT",
+        "A cinematic first-person drive through a futuristic coastal city at "
+        "sunrise, reflective glass towers, clean streets, soft volumetric light.",
+    )
+    image_path = os.getenv(
+        "DREAMX_WORLD_IMAGE_PATH",
+        "https://huggingface.co/datasets/YiYiXu/testing-images/resolve/main/wan_i2v_input.JPG",
+    )
+
+    request = GenerationRequest(
+        prompt=prompt,
+        inputs=InputConfig(image_path=image_path or None),
+        sampling=SamplingConfig(
+            height=_env_int("DREAMX_WORLD_HEIGHT", 480),
+            width=_env_int("DREAMX_WORLD_WIDTH", 832),
+            num_frames=_env_int("DREAMX_WORLD_NUM_FRAMES", 161),
+            num_inference_steps=_env_int("DREAMX_WORLD_STEPS", 30),
+            guidance_scale=_env_float("DREAMX_WORLD_GUIDANCE", 5.0),
+        ),
+        output=OutputConfig(
+            output_path=OUTPUT_PATH,
+            save_video=os.getenv("DREAMX_WORLD_SAVE_VIDEO", "1") != "0",
+        ),
+        extensions={
+            "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(",")
+            ],
+        },
+    )
+
+    try:
+        generator.generate(request)
+    finally:
+        generator.shutdown()
+
+
+if __name__ == "__main__":
+    main()

examples/inference/basic/basic_gamecraft.py

@@ -26,6 +26,15 @@ import os
 import torch
 
 from fastvideo import VideoGenerator
+from fastvideo.api import (
+    EngineConfig,
+    GenerationRequest,
+    GeneratorConfig,
+    InputConfig,
+    OffloadConfig,
+    OutputConfig,
+    SamplingConfig,
+)
 from fastvideo.models.camera import create_camera_trajectory
 
 # Model configuration (use GAMECRAFT_MODEL_PATH for local weights)
@@ -55,14 +64,20 @@ OUTPUT_PATH = "video_samples_gamecraft"
 def main():
     # Initialize generator
     # FastVideo will automatically download weights from HuggingFace
-    generator = VideoGenerator.from_pretrained(
-        MODEL_PATH,
-        num_gpus=1,
-        use_fsdp_inference=True,
-        dit_cpu_offload=True,
-        vae_cpu_offload=True,
-        text_encoder_cpu_offload=True,
-        pin_cpu_memory=True,
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path=MODEL_PATH,
+            engine=EngineConfig(
+                num_gpus=1,
+                use_fsdp_inference=True,
+                offload=OffloadConfig(
+                    dit=True,
+                    vae=True,
+                    text_encoder=True,
+                    pin_cpu_memory=True,
+                ),
+            ),
+        )
     )
 
     # Video parameters
@@ -96,23 +111,27 @@ def main():
     prompt = DEFAULT_I2V_PROMPT if is_i2v else DEFAULT_PROMPTS["temple"]
     print(f"Mode: {'I2V' if is_i2v else 'T2V'}, prompt: {prompt[:60]}...")
 
-    gen_kw = dict(
+    request = GenerationRequest(
         prompt=prompt,
         negative_prompt="",
-        camera_states=camera_states,
-        height=height,
-        width=width,
-        num_frames=num_frames,
-        num_inference_steps=50,
-        guidance_scale=6.0,
-        seed=42,
-        fps=24,
-        output_path=OUTPUT_PATH,
-        save_video=True,
+        sampling=SamplingConfig(
+            height=height,
+            width=width,
+            num_frames=num_frames,
+            num_inference_steps=50,
+            guidance_scale=6.0,
+            seed=42,
+            fps=24,
+        ),
+        output=OutputConfig(
+            output_path=OUTPUT_PATH,
+            save_video=True,
+        ),
+        extensions={"camera_states": camera_states},
     )
     if is_i2v:
-        gen_kw["image_path"] = image_path
-    generator.generate_video(**gen_kw)
+        request.inputs = InputConfig(image_path=image_path)
+    generator.generate(request)
 
 
 if __name__ == "__main__":

examples/inference/basic/basic_gen3c.py

@@ -22,6 +22,10 @@ Requirements:
 import argparse
 
 from fastvideo import VideoGenerator
+from fastvideo.api import (
+    EngineConfig, GenerationRequest, GeneratorConfig, InputConfig,
+    OffloadConfig, OutputConfig, SamplingConfig,
+)
 
 
 def main():
@@ -74,33 +78,47 @@ def main():
     parser.add_argument("--seed", type=int, default=42)
     args = parser.parse_args()
 
-    generator = VideoGenerator.from_pretrained(
-        args.model_path,
-        num_gpus=1,
-        use_fsdp_inference=False,
-        dit_cpu_offload=False,
-        vae_cpu_offload=True,
-        text_encoder_cpu_offload=True,
-        pin_cpu_memory=True,
-    )
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path=args.model_path,
+            engine=EngineConfig(
+                num_gpus=1,
+                use_fsdp_inference=False,
+                offload=OffloadConfig(
+                    dit=False,
+                    vae=True,
+                    text_encoder=True,
+                    pin_cpu_memory=True,
+                ),
+            ),
+        ))
 
-    video = generator.generate_video(
-        args.prompt,
-        negative_prompt=args.negative_prompt,
-        image_path=args.image_path,
-        trajectory_type=args.trajectory,
-        movement_distance=args.movement_distance,
-        camera_rotation=args.camera_rotation,
-        height=args.height,
-        width=args.width,
-        num_frames=args.num_frames,
-        num_inference_steps=args.num_inference_steps,
-        guidance_scale=args.guidance_scale,
-        fps=24,
-        seed=args.seed,
-        output_path=args.output_path,
-        save_video=True,
-    )
+    video = generator.generate(
+        GenerationRequest(
+            prompt=args.prompt,
+            negative_prompt=args.negative_prompt,
+            inputs=InputConfig(
+                image_path=args.image_path,
+            ),
+            sampling=SamplingConfig(
+                height=args.height,
+                width=args.width,
+                num_frames=args.num_frames,
+                num_inference_steps=args.num_inference_steps,
+                guidance_scale=args.guidance_scale,
+                fps=24,
+                seed=args.seed,
+            ),
+            output=OutputConfig(
+                output_path=args.output_path,
+                save_video=True,
+            ),
+            extensions={
+                "trajectory_type": args.trajectory,
+                "movement_distance": args.movement_distance,
+                "camera_rotation": args.camera_rotation,
+            },
+        ))
 
     generator.shutdown()
 

examples/inference/basic/basic_hy15.py

@@ -1,6 +1,13 @@
 from fastvideo import VideoGenerator
+from fastvideo.api import (
+    EngineConfig,
+    GenerationRequest,
+    GeneratorConfig,
+    OffloadConfig,
+    OutputConfig,
+    SamplingConfig,
+)
 import json
-# from fastvideo.api.sampling_param import SamplingParam
 
 OUTPUT_PATH = "video_samples_hy15"
 def main():
@@ -8,17 +15,21 @@ def main():
     # model.
     # If a local path is provided, FastVideo will make a best effort
     # attempt to identify the optimal arguments.
-    generator = VideoGenerator.from_pretrained(
-        "hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v",
+    generator = VideoGenerator.from_config(GeneratorConfig(
+        model_path="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
-        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"
-        # image_encoder_cpu_offload=False,
-    )
+        engine=EngineConfig(
+            num_gpus=1,
+            use_fsdp_inference=False, # set to True if GPU is out of memory
+            offload=OffloadConfig(
+                dit=True,
+                vae=True,
+                text_encoder=True,
+                pin_cpu_memory=True, # set to false if low CPU RAM or hit obscure "CUDA error: Invalid argument"
+                # image_encoder=False,
+            ),
+        ),
+    ))
 
     prompt = (
         "A curious raccoon peers through a vibrant field of yellow sunflowers, its eyes "
@@ -26,7 +37,12 @@ def main():
         "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)
+    generator.generate(GenerationRequest(
+        prompt=prompt,
+        negative_prompt="",
+        sampling=SamplingConfig(num_frames=81, fps=16),
+        output=OutputConfig(output_path=OUTPUT_PATH, save_video=True),
+    ))
 
     prompt2 = (
         "A majestic lion strides across the golden savanna, its powerful frame "
@@ -35,8 +51,13 @@ def main():
         "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)
+    generator.generate(GenerationRequest(
+        prompt=prompt2,
+        negative_prompt="",
+        sampling=SamplingConfig(num_frames=81, fps=16),
+        output=OutputConfig(output_path=OUTPUT_PATH, save_video=True),
+    ))
 
 
 if __name__ == "__main__":
-    main()
+    main()

examples/inference/basic/basic_hy15_1080p.py

@@ -1,6 +1,12 @@
 from fastvideo import VideoGenerator
+from fastvideo.api import (
+    EngineConfig,
+    GenerationRequest,
+    GeneratorConfig,
+    OffloadConfig,
+    OutputConfig,
+)
 import json
-# from fastvideo.api.sampling_param import SamplingParam
 
 OUTPUT_PATH = "video_samples_hy15_1080p"
 def main():
@@ -8,17 +14,23 @@ def main():
     # 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
-        # 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
-        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"
-        # image_encoder_cpu_offload=False,
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="weizhou03/HunyuanVideo-1.5-Diffusers-1080p-2SR", # 480p -> 720p -> 1080p
+            # or "weizhou03/HunyuanVideo-1.5-Diffusers-1080p" # 720p -> 1080p
+            engine=EngineConfig(
+                # FastVideo will automatically handle distributed setup
+                num_gpus=1,
+                use_fsdp_inference=False, # set to True if GPU is out of memory
+                offload=OffloadConfig(
+                    dit=True,
+                    vae=True,
+                    text_encoder=True,
+                    pin_cpu_memory=True, # set to false if low CPU RAM or hit obscure "CUDA error: Invalid argument"
+                    # image_encoder=False,
+                ),
+            ),
+        )
     )
 
     prompt = (
@@ -27,7 +39,13 @@ def main():
         "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="")
+    video = generator.generate(
+        GenerationRequest(
+            prompt=prompt,
+            negative_prompt="",
+            output=OutputConfig(output_path=OUTPUT_PATH, save_video=True),
+        )
+    )
 
     prompt2 = (
         "A majestic lion strides across the golden savanna, its powerful frame "
@@ -36,7 +54,13 @@ def main():
         "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="")
+    video2 = generator.generate(
+        GenerationRequest(
+            prompt=prompt2,
+            negative_prompt="",
+            output=OutputConfig(output_path=OUTPUT_PATH, save_video=True),
+        )
+    )
 
 
 if __name__ == "__main__":

examples/inference/basic/basic_hyworld.py

@@ -1,4 +1,6 @@
 from fastvideo import VideoGenerator
+from fastvideo.api import (EngineConfig, GenerationRequest, GeneratorConfig, InputConfig, OffloadConfig, OutputConfig,
+                           SamplingConfig)
 from fastvideo.models.dits.hyworld.resolution_utils import get_resolution_from_image
 
 # Default prompt from HY-WorldPlay run.sh
@@ -31,33 +33,45 @@ def main():
 
     # Initialize generator
     print("\nInitializing VideoGenerator for HYWorld...")
-    generator = VideoGenerator.from_pretrained(
-        "FastVideo/HY-WorldPlay-Bidirectional-Diffusers",
-        num_gpus=1,
-        use_fsdp_inference=True,
-        dit_cpu_offload=True,
-        vae_cpu_offload=True,
-        text_encoder_cpu_offload=True,
-        pin_cpu_memory=True,
-        image_encoder_cpu_offload=True,
-    )
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="FastVideo/HY-WorldPlay-Bidirectional-Diffusers",
+            engine=EngineConfig(
+                num_gpus=1,
+                use_fsdp_inference=True,
+                offload=OffloadConfig(
+                    dit=True,
+                    vae=True,
+                    text_encoder=True,
+                    pin_cpu_memory=True,
+                    image_encoder=True,
+                ),
+            ),
+        ))
 
     # Generate video
     # The pose string is automatically converted to camera matrices by the pipeline
     print("\nGenerating video...")
-    generator.generate_video(
-        prompt=args.prompt,
-        image_path=args.image,
-        pose=args.pose,  # Camera trajectory control
-        output_path=args.output_path,
-        save_video=True,
-        negative_prompt="",
-        num_frames=args.num_frames,
-        fps=24,
-        height=HEIGHT,
-        width=WIDTH,
-        seed=args.seed,
-    )
+    generator.generate(
+        GenerationRequest(
+            prompt=args.prompt,
+            negative_prompt="",
+            inputs=InputConfig(
+                image_path=args.image,
+                pose=args.pose,  # Camera trajectory control
+            ),
+            sampling=SamplingConfig(
+                num_frames=args.num_frames,
+                fps=24,
+                height=HEIGHT,
+                width=WIDTH,
+                seed=args.seed,
+            ),
+            output=OutputConfig(
+                output_path=args.output_path,
+                save_video=True,
+            ),
+        ))
 
     print(f"\nVideo saved to: {args.output_path}")
 

examples/inference/basic/basic_kandinsky5_i2v.py

@@ -0,0 +1,44 @@
+from fastvideo import VideoGenerator
+
+from fastvideo.api import (EngineConfig, GenerationRequest, GeneratorConfig,
+                           InputConfig, OffloadConfig, OutputConfig,
+                           SamplingConfig)
+
+OUTPUT_PATH = "video_samples_kandinsky5_i2v"
+
+IMAGE_PATH = "assets/girl.png"
+
+
+def main():
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="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"
+            engine=EngineConfig(
+                num_gpus=1,
+                use_fsdp_inference=False,
+                offload=OffloadConfig(
+                    dit=False,
+                    vae=False,
+                    text_encoder=True,
+                    pin_cpu_memory=True,
+                    # image_encoder=False,
+                ),
+            ),
+        ))
+
+    prompt = (
+        "A woman stands up and walks away"
+    )
+    _ = generator.generate(
+        GenerationRequest(
+            prompt=prompt,
+            inputs=InputConfig(image_path=IMAGE_PATH),
+            sampling=SamplingConfig(height=1024, width=1024, num_frames=121),
+            output=OutputConfig(output_path=OUTPUT_PATH, save_video=True),
+        ))
+
+
+if __name__ == "__main__":
+    main()

examples/inference/basic/basic_kandinsky5_t2v.py

@@ -0,0 +1,55 @@
+from fastvideo import VideoGenerator
+
+from fastvideo.api import (EngineConfig, GenerationRequest, GeneratorConfig,
+                           OffloadConfig, OutputConfig, SamplingConfig)
+
+OUTPUT_PATH = "video_samples_kandinsky5_t2v"
+
+def main():
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="kandinskylab/Kandinsky-5.0-T2V-Lite-sft-5s-Diffusers",
+            # "kandinskylab/Kandinsky-5.0-T2V-Pro-sft-5s-Diffusers"
+            # "kandinskylab/Kandinsky-5.0-T2V-Lite-distilled16steps-5s-Diffusers"
+            # "kandinskylab/Kandinsky-5.0-T2V-Pro-distilled-5s-Diffusers"
+            engine=EngineConfig(
+                num_gpus=1,
+                use_fsdp_inference=False,
+                offload=OffloadConfig(
+                    dit=False,
+                    vae=False,
+                    text_encoder=True,
+                    pin_cpu_memory=True,
+                    # image_encoder=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(
+        GenerationRequest(
+            prompt=prompt,
+            sampling=SamplingConfig(height=512, width=768, num_frames=121),
+            output=OutputConfig(output_path=OUTPUT_PATH, save_video=True),
+        ))
+
+    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(
+        GenerationRequest(
+            prompt=prompt2,
+            sampling=SamplingConfig(height=512, width=768, num_frames=121),
+            output=OutputConfig(output_path=OUTPUT_PATH, save_video=True),
+        ))
+
+
+if __name__ == "__main__":
+    main()

examples/inference/basic/basic_lingbotworld_base_cam.py

@@ -1,24 +1,31 @@
 from fastvideo import VideoGenerator
+from fastvideo.api import (
+    EngineConfig, GenerationRequest, GeneratorConfig, InputConfig, OffloadConfig, OutputConfig, SamplingConfig,
+)
 from fastvideo.models.dits.lingbotworld.cam_utils import prepare_camera_embedding
 
-# 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 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
-        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
-        pin_cpu_memory=True,
-        # image_encoder_cpu_offload=False,
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="FastVideo/LingBot-World-Base-Cam-Diffusers",
+            engine=EngineConfig(
+                # FastVideo will automatically handle distributed setup
+                num_gpus=1,
+                use_fsdp_inference=False,  # set to True if GPU is out of memory
+                offload=OffloadConfig(
+                    dit=True,  # DiT need to be offloaded for MoE
+                    vae=False,
+                    text_encoder=True,
+                    # Set pin_cpu_memory to false if CPU RAM is limited and there're no frequent CPU-GPU transfer
+                    pin_cpu_memory=True,
+                ),
+            ),
+        )
     )
 
     num_frames = 81
@@ -33,15 +40,23 @@ def main():
         spatial_scale=8,
     )
 
-    generator.generate_video(
-        prompt,
-        image_path=image_path,
-        output_path=OUTPUT_PATH,
-        save_video=True,
-        num_frames=num_frames,
-        height=480,
-        width=832,
-        c2ws_plucker_emb=c2ws_plucker_emb,
+    generator.generate(
+        GenerationRequest(
+            prompt=prompt,
+            inputs=InputConfig(
+                image_path=image_path,
+                c2ws_plucker_emb=c2ws_plucker_emb,
+            ),
+            sampling=SamplingConfig(
+                num_frames=num_frames,
+                height=480,
+                width=832,
+            ),
+            output=OutputConfig(
+                output_path=OUTPUT_PATH,
+                save_video=True,
+            ),
+        )
     )
 
 

examples/inference/basic/basic_longcat_i2v.py

@@ -19,6 +19,10 @@ import glob
 import os
 
 from fastvideo import VideoGenerator
+from fastvideo.api import (
+    ComponentConfig, EngineConfig, GenerationRequest, GeneratorConfig,
+    InputConfig, OffloadConfig, OutputConfig, PipelineSelection, SamplingConfig,
+)
 
 # Common prompts and settings matching the shell script examples
 PROMPT = (
@@ -45,41 +49,50 @@ SEED = 42
 def basic_generation():
     """
     Run basic LongCat I2V generation (50 steps at 480p).
-    
+
     This uses the full 50-step denoising process for highest quality.
     """
     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
-        dit_cpu_offload=False,
-        vae_cpu_offload=True,
-        text_encoder_cpu_offload=True,
-        pin_cpu_memory=False,
-        enable_bsa=False,
+
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="FastVideo/LongCat-Video-I2V-Diffusers",
+            engine=EngineConfig(
+                num_gpus=1,
+                use_fsdp_inference=False,  # set to True if GPU is out of memory
+                offload=OffloadConfig(
+                    dit=False,
+                    vae=True,
+                    text_encoder=True,
+                    pin_cpu_memory=False,
+                ),
+            ),
+            pipeline=PipelineSelection(experimental={"enable_bsa": False}),
+        )
     )
-    
+
     output_path = "outputs_video/longcat_i2v_basic"
-    
-    generator.generate_video(
-        prompt=PROMPT,
-        negative_prompt=NEGATIVE_PROMPT,
-        image_path=IMAGE_PATH,
-        output_path=output_path,
-        save_video=True,
-        height=480,
-        width=480,  # Square
-        num_frames=93,
-        num_inference_steps=50,
-        fps=15,
-        guidance_scale=4.0,
-        seed=SEED,
+
+    generator.generate(
+        GenerationRequest(
+            prompt=PROMPT,
+            negative_prompt=NEGATIVE_PROMPT,
+            inputs=InputConfig(image_path=IMAGE_PATH),
+            sampling=SamplingConfig(
+                height=480,
+                width=480,  # Square
+                num_frames=93,
+                num_inference_steps=50,
+                fps=15,
+                guidance_scale=4.0,
+                seed=SEED,
+            ),
+            output=OutputConfig(output_path=output_path, save_video=True),
+        )
     )
-    
+
     print(f"\nBasic generation complete! Video saved to: {output_path}")
     generator.shutdown()
 
@@ -87,55 +100,70 @@ def basic_generation():
 def distill_refine_generation():
     """
     Run LongCat I2V with distill+refine pipeline (16 steps + refinement to 768p).
-    
+
     This uses the distilled LoRA for fast 480p generation (16 steps),
     then refines to 768p using the refinement LoRA with BSA enabled.
     """
     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,
-        use_fsdp_inference=True,
-        dit_cpu_offload=False,
-        vae_cpu_offload=True,
-        text_encoder_cpu_offload=True,
-        pin_cpu_memory=False,
-        enable_bsa=False,
-        lora_path="FastVideo/LongCat-Video-T2V-Distilled-LoRA",
-        lora_nickname="distilled",
+
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="FastVideo/LongCat-Video-I2V-Diffusers",
+            engine=EngineConfig(
+                num_gpus=1,
+                use_fsdp_inference=True,
+                offload=OffloadConfig(
+                    dit=False,
+                    vae=True,
+                    text_encoder=True,
+                    pin_cpu_memory=False,
+                ),
+            ),
+            pipeline=PipelineSelection(
+                components=ComponentConfig(
+                    lora_path="FastVideo/LongCat-Video-T2V-Distilled-LoRA",
+                ),
+                experimental={
+                    "enable_bsa": False,
+                    "lora_nickname": "distilled",
+                },
+            ),
+        )
     )
-    
+
     distill_output_path = "outputs_video/longcat_i2v_distill"
-    
-    generator.generate_video(
-        prompt=PROMPT,
-        negative_prompt=NEGATIVE_PROMPT,
-        image_path=IMAGE_PATH,
-        output_path=distill_output_path,
-        save_video=True,
-        height=480,
-        width=480,  # Square
-        num_frames=93,
-        num_inference_steps=16,
-        fps=15,
-        guidance_scale=1.0,
-        seed=SEED,
+
+    generator.generate(
+        GenerationRequest(
+            prompt=PROMPT,
+            negative_prompt=NEGATIVE_PROMPT,
+            inputs=InputConfig(image_path=IMAGE_PATH),
+            sampling=SamplingConfig(
+                height=480,
+                width=480,  # Square
+                num_frames=93,
+                num_inference_steps=16,
+                fps=15,
+                guidance_scale=1.0,
+                seed=SEED,
+            ),
+            output=OutputConfig(output_path=distill_output_path, save_video=True),
+        )
     )
-    
+
     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:
@@ -143,46 +171,63 @@ 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
     # 768x768: latent 48x48, 48%8=0 ✓
-    refine_generator = VideoGenerator.from_pretrained(
-        "FastVideo/LongCat-Video-T2V-Diffusers",
-        num_gpus=1,
-        use_fsdp_inference=True,
-        dit_cpu_offload=True,
-        vae_cpu_offload=True,
-        text_encoder_cpu_offload=True,
-        pin_cpu_memory=False,
-        enable_bsa=True,
-        bsa_sparsity=0.875,
-        bsa_chunk_q=[4, 4, 4],
-        bsa_chunk_k=[4, 4, 4],
-        lora_path="FastVideo/LongCat-Video-T2V-Refinement-LoRA",
-        lora_nickname="refinement",
+    refine_generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="FastVideo/LongCat-Video-T2V-Diffusers",
+            engine=EngineConfig(
+                num_gpus=1,
+                use_fsdp_inference=True,
+                offload=OffloadConfig(
+                    dit=True,
+                    vae=True,
+                    text_encoder=True,
+                    pin_cpu_memory=False,
+                ),
+            ),
+            pipeline=PipelineSelection(
+                components=ComponentConfig(
+                    lora_path="FastVideo/LongCat-Video-T2V-Refinement-LoRA",
+                ),
+                experimental={
+                    "enable_bsa": True,
+                    "bsa_sparsity": 0.875,
+                    "bsa_chunk_q": [4, 4, 4],
+                    "bsa_chunk_k": [4, 4, 4],
+                    "lora_nickname": "refinement",
+                },
+            ),
+        )
     )
-    
+
     refine_output_path = "outputs_video/longcat_i2v_refine_720p"
-    
-    refine_generator.generate_video(
-        prompt=PROMPT,
-        negative_prompt=NEGATIVE_PROMPT,
-        output_path=refine_output_path,
-        save_video=True,
-        refine_from=distill_video_path,
-        t_thresh=0.5,
-        spatial_refine_only=False,
-        num_cond_frames=0,
-        height=720,
-        width=720,
-        num_inference_steps=50,
-        fps=30,
-        guidance_scale=1.0,
-        seed=SEED,
+
+    refine_generator.generate(
+        GenerationRequest(
+            prompt=PROMPT,
+            negative_prompt=NEGATIVE_PROMPT,
+            inputs=InputConfig(refine_from=distill_video_path),
+            sampling=SamplingConfig(
+                height=720,
+                width=720,
+                num_inference_steps=50,
+                fps=30,
+                guidance_scale=1.0,
+                seed=SEED,
+            ),
+            output=OutputConfig(output_path=refine_output_path, save_video=True),
+            extensions={
+                "t_thresh": 0.5,
+                "spatial_refine_only": False,
+                "num_cond_frames": 0,
+            },
+        )
     )
-    
+
     print(f"Refinement complete! Video saved to: {refine_output_path}")
     refine_generator.shutdown()
 
@@ -192,13 +237,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)

examples/inference/basic/basic_longcat_t2v.py

@@ -13,6 +13,10 @@ import glob
 import os
 
 from fastvideo import VideoGenerator
+from fastvideo.api import (
+    ComponentConfig, EngineConfig, GenerationRequest, GeneratorConfig,
+    InputConfig, OffloadConfig, OutputConfig, PipelineSelection, SamplingConfig,
+)
 
 # Common prompts and settings matching the shell script examples
 PROMPT = (
@@ -38,40 +42,54 @@ SEED = 42
 def basic_generation():
     """
     Run basic LongCat T2V generation (50 steps at 480p).
-    
+
     This uses the full 50-step denoising process for highest quality.
     """
     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
-        dit_cpu_offload=False,
-        vae_cpu_offload=True,
-        text_encoder_cpu_offload=True,
-        pin_cpu_memory=False,
-        enable_bsa=False,
+
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="FastVideo/LongCat-Video-T2V-Diffusers",
+            engine=EngineConfig(
+                num_gpus=1,
+                use_fsdp_inference=False, # set to True if GPU is out of memory
+                offload=OffloadConfig(
+                    dit=False,
+                    vae=True,
+                    text_encoder=True,
+                    pin_cpu_memory=False,
+                ),
+            ),
+            pipeline=PipelineSelection(
+                experimental={"enable_bsa": False},
+            ),
+        )
     )
-    
+
     output_path = "outputs_video/longcat_t2v_basic"
-    
-    generator.generate_video(
-        prompt=PROMPT,
-        negative_prompt=NEGATIVE_PROMPT,
-        output_path=output_path,
-        save_video=True,
-        height=480,
-        width=832,
-        num_frames=93,
-        num_inference_steps=50,
-        fps=15,
-        guidance_scale=4.0,
-        seed=SEED,
+
+    generator.generate(
+        GenerationRequest(
+            prompt=PROMPT,
+            negative_prompt=NEGATIVE_PROMPT,
+            output=OutputConfig(
+                output_path=output_path,
+                save_video=True,
+            ),
+            sampling=SamplingConfig(
+                height=480,
+                width=832,
+                num_frames=93,
+                num_inference_steps=50,
+                fps=15,
+                guidance_scale=4.0,
+                seed=SEED,
+            ),
+        )
     )
-    
+
     print(f"\nBasic generation complete! Video saved to: {output_path}")
     generator.shutdown()
 
@@ -79,54 +97,72 @@ def basic_generation():
 def distill_refine_generation():
     """
     Run LongCat T2V with distill+refine pipeline (16 steps + refinement to 720p).
-    
+
     This uses the distilled LoRA for fast 480p generation (16 steps),
     then refines to 720p using the refinement LoRA with BSA enabled.
     """
     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,
-        use_fsdp_inference=True,
-        dit_cpu_offload=False,
-        vae_cpu_offload=True,
-        text_encoder_cpu_offload=True,
-        pin_cpu_memory=False,
-        enable_bsa=False,
-        lora_path="FastVideo/LongCat-Video-T2V-Distilled-LoRA",
-        lora_nickname="distilled",
+
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="FastVideo/LongCat-Video-T2V-Diffusers",
+            engine=EngineConfig(
+                num_gpus=1,
+                use_fsdp_inference=True,
+                offload=OffloadConfig(
+                    dit=False,
+                    vae=True,
+                    text_encoder=True,
+                    pin_cpu_memory=False,
+                ),
+            ),
+            pipeline=PipelineSelection(
+                components=ComponentConfig(
+                    lora_path="FastVideo/LongCat-Video-T2V-Distilled-LoRA",
+                ),
+                experimental={
+                    "enable_bsa": False,
+                    "lora_nickname": "distilled",
+                },
+            ),
+        )
     )
-    
+
     distill_output_path = "outputs_video/longcat_t2v_distill"
-    
-    generator.generate_video(
-        prompt=PROMPT,
-        negative_prompt=NEGATIVE_PROMPT,
-        output_path=distill_output_path,
-        save_video=True,
-        height=480,
-        width=832,
-        num_frames=93,
-        num_inference_steps=16,
-        fps=15,
-        guidance_scale=1.0,
-        seed=SEED,
+
+    generator.generate(
+        GenerationRequest(
+            prompt=PROMPT,
+            negative_prompt=NEGATIVE_PROMPT,
+            output=OutputConfig(
+                output_path=distill_output_path,
+                save_video=True,
+            ),
+            sampling=SamplingConfig(
+                height=480,
+                width=832,
+                num_frames=93,
+                num_inference_steps=16,
+                fps=15,
+                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:
@@ -134,43 +170,65 @@ 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",
-        num_gpus=1,
-        use_fsdp_inference=True,
-        dit_cpu_offload=True,
-        vae_cpu_offload=True,
-        text_encoder_cpu_offload=True,
-        pin_cpu_memory=False,
-        enable_bsa=True,
-        bsa_sparsity=0.875,
-        bsa_chunk_q=[4, 4, 8],
-        bsa_chunk_k=[4, 4, 8],
-        lora_path="FastVideo/LongCat-Video-T2V-Refinement-LoRA",
-        lora_nickname="refinement",
+    refine_generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="FastVideo/LongCat-Video-T2V-Diffusers",
+            engine=EngineConfig(
+                num_gpus=1,
+                use_fsdp_inference=True,
+                offload=OffloadConfig(
+                    dit=True,
+                    vae=True,
+                    text_encoder=True,
+                    pin_cpu_memory=False,
+                ),
+            ),
+            pipeline=PipelineSelection(
+                components=ComponentConfig(
+                    lora_path="FastVideo/LongCat-Video-T2V-Refinement-LoRA",
+                ),
+                experimental={
+                    "enable_bsa": True,
+                    "bsa_sparsity": 0.875,
+                    "bsa_chunk_q": [4, 4, 8],
+                    "bsa_chunk_k": [4, 4, 8],
+                    "lora_nickname": "refinement",
+                },
+            ),
+        )
     )
-    
+
     refine_output_path = "outputs_video/longcat_t2v_refine_720p"
-    
-    refine_generator.generate_video(
-        prompt=PROMPT,
-        negative_prompt=NEGATIVE_PROMPT,
-        output_path=refine_output_path,
-        save_video=True,
-        refine_from=distill_video_path,
-        t_thresh=0.5,
-        spatial_refine_only=False,
-        num_cond_frames=0,
-        height=720,
-        width=1280,
-        num_inference_steps=50,
-        fps=30,
-        guidance_scale=1.0,
-        seed=SEED,
+
+    refine_generator.generate(
+        GenerationRequest(
+            prompt=PROMPT,
+            negative_prompt=NEGATIVE_PROMPT,
+            output=OutputConfig(
+                output_path=refine_output_path,
+                save_video=True,
+            ),
+            inputs=InputConfig(
+                refine_from=distill_video_path,
+            ),
+            sampling=SamplingConfig(
+                height=720,
+                width=1280,
+                num_inference_steps=50,
+                fps=30,
+                guidance_scale=1.0,
+                seed=SEED,
+            ),
+            extensions={
+                "t_thresh": 0.5,
+                "spatial_refine_only": False,
+                "num_cond_frames": 0,
+            },
+        )
     )
-    
+
     print(f"Refinement complete! Video saved to: {refine_output_path}")
     refine_generator.shutdown()
 
@@ -180,13 +238,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)
@@ -194,5 +252,3 @@ def main():
 
 if __name__ == "__main__":
     main()
-
-

examples/inference/basic/basic_longcat_vc.py

@@ -19,6 +19,10 @@ import glob
 import os
 
 from fastvideo import VideoGenerator
+from fastvideo.api import (
+    ComponentConfig, EngineConfig, GenerationRequest, GeneratorConfig, InputConfig, OffloadConfig, OutputConfig,
+    PipelineSelection, SamplingConfig,
+)
 
 # Common prompts and settings matching the shell script examples
 PROMPT = (
@@ -63,35 +67,49 @@ def basic_generation():
             "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
-        dit_cpu_offload=False,
-        vae_cpu_offload=True,
-        text_encoder_cpu_offload=True,
-        pin_cpu_memory=False,
-        enable_bsa=False,
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="FastVideo/LongCat-Video-VC-Diffusers",
+            engine=EngineConfig(
+                num_gpus=1,
+                use_fsdp_inference=False, # set to True if GPU is out of memory
+                offload=OffloadConfig(
+                    dit=False,
+                    vae=True,
+                    text_encoder=True,
+                    pin_cpu_memory=False,
+                ),
+            ),
+            pipeline=PipelineSelection(
+                experimental={"enable_bsa": False},
+            ),
+        )
     )
-    
+
     output_path = "outputs_video/longcat_vc_basic"
-    
-    generator.generate_video(
-        prompt=PROMPT,
-        negative_prompt=NEGATIVE_PROMPT,
-        video_path=VIDEO_PATH,
-        num_cond_frames=NUM_COND_FRAMES,
-        output_path=output_path,
-        save_video=True,
-        height=480,
-        width=832,
-        num_frames=93,
-        num_inference_steps=50,
-        fps=15,
-        guidance_scale=4.0,
-        seed=SEED,
+
+    generator.generate(
+        GenerationRequest(
+            prompt=PROMPT,
+            negative_prompt=NEGATIVE_PROMPT,
+            inputs=InputConfig(video_path=VIDEO_PATH),
+            sampling=SamplingConfig(
+                height=480,
+                width=832,
+                num_frames=93,
+                num_inference_steps=50,
+                fps=15,
+                guidance_scale=4.0,
+                seed=SEED,
+            ),
+            output=OutputConfig(
+                output_path=output_path,
+                save_video=True,
+            ),
+            extensions={"num_cond_frames": NUM_COND_FRAMES},
+        )
     )
-    
+
     print(f"\nBasic generation complete! Video saved to: {output_path}")
     generator.shutdown()
 
@@ -118,37 +136,55 @@ def distill_refine_generation():
     print("\n[Stage 1] Distilled generation (16 steps, 480p)")
     print("-" * 40)
     
-    generator = VideoGenerator.from_pretrained(
-        "FastVideo/LongCat-Video-VC-Diffusers",
-        num_gpus=1,
-        use_fsdp_inference=True,
-        dit_cpu_offload=False,
-        vae_cpu_offload=True,
-        text_encoder_cpu_offload=True,
-        pin_cpu_memory=False,
-        enable_bsa=False,
-        lora_path="FastVideo/LongCat-Video-T2V-Distilled-LoRA",
-        lora_nickname="distilled",
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="FastVideo/LongCat-Video-VC-Diffusers",
+            engine=EngineConfig(
+                num_gpus=1,
+                use_fsdp_inference=True,
+                offload=OffloadConfig(
+                    dit=False,
+                    vae=True,
+                    text_encoder=True,
+                    pin_cpu_memory=False,
+                ),
+            ),
+            pipeline=PipelineSelection(
+                components=ComponentConfig(
+                    lora_path="FastVideo/LongCat-Video-T2V-Distilled-LoRA",
+                ),
+                experimental={
+                    "enable_bsa": False,
+                    "lora_nickname": "distilled",
+                },
+            ),
+        )
     )
-    
+
     distill_output_path = "outputs_video/longcat_vc_distill"
-    
-    generator.generate_video(
-        prompt=PROMPT,
-        negative_prompt=NEGATIVE_PROMPT,
-        video_path=VIDEO_PATH,
-        num_cond_frames=NUM_COND_FRAMES,
-        output_path=distill_output_path,
-        save_video=True,
-        height=480,
-        width=832,
-        num_frames=93,
-        num_inference_steps=16,
-        fps=15,
-        guidance_scale=1.0,
-        seed=SEED,
+
+    generator.generate(
+        GenerationRequest(
+            prompt=PROMPT,
+            negative_prompt=NEGATIVE_PROMPT,
+            inputs=InputConfig(video_path=VIDEO_PATH),
+            sampling=SamplingConfig(
+                height=480,
+                width=832,
+                num_frames=93,
+                num_inference_steps=16,
+                fps=15,
+                guidance_scale=1.0,
+                seed=SEED,
+            ),
+            output=OutputConfig(
+                output_path=distill_output_path,
+                save_video=True,
+            ),
+            extensions={"num_cond_frames": NUM_COND_FRAMES},
+        )
     )
-    
+
     print(f"Distilled generation complete! Video saved to: {distill_output_path}")
     generator.shutdown()
     
@@ -166,41 +202,61 @@ def distill_refine_generation():
     
     # 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(
-        "FastVideo/LongCat-Video-T2V-Diffusers",
-        num_gpus=1,
-        use_fsdp_inference=True,
-        dit_cpu_offload=True,
-        vae_cpu_offload=True,
-        text_encoder_cpu_offload=True,
-        pin_cpu_memory=False,
-        enable_bsa=True,
-        bsa_sparsity=0.875,
-        bsa_chunk_q=[4, 4, 8],
-        bsa_chunk_k=[4, 4, 8],
-        lora_path="FastVideo/LongCat-Video-T2V-Refinement-LoRA",
-        lora_nickname="refinement",
+    refine_generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="FastVideo/LongCat-Video-T2V-Diffusers",
+            engine=EngineConfig(
+                num_gpus=1,
+                use_fsdp_inference=True,
+                offload=OffloadConfig(
+                    dit=True,
+                    vae=True,
+                    text_encoder=True,
+                    pin_cpu_memory=False,
+                ),
+            ),
+            pipeline=PipelineSelection(
+                components=ComponentConfig(
+                    lora_path="FastVideo/LongCat-Video-T2V-Refinement-LoRA",
+                ),
+                experimental={
+                    "enable_bsa": True,
+                    "bsa_sparsity": 0.875,
+                    "bsa_chunk_q": [4, 4, 8],
+                    "bsa_chunk_k": [4, 4, 8],
+                    "lora_nickname": "refinement",
+                },
+            ),
+        )
     )
-    
+
     refine_output_path = "outputs_video/longcat_vc_refine_720p"
-    
-    refine_generator.generate_video(
-        prompt=PROMPT,
-        negative_prompt=NEGATIVE_PROMPT,
-        output_path=refine_output_path,
-        save_video=True,
-        refine_from=distill_video_path,
-        t_thresh=0.5,
-        spatial_refine_only=False,
-        num_cond_frames=0,  # For refinement, no conditioning frames
-        height=720,
-        width=1280,
-        num_inference_steps=50,
-        fps=30,
-        guidance_scale=1.0,
-        seed=SEED,
+
+    refine_generator.generate(
+        GenerationRequest(
+            prompt=PROMPT,
+            negative_prompt=NEGATIVE_PROMPT,
+            inputs=InputConfig(refine_from=distill_video_path),
+            sampling=SamplingConfig(
+                height=720,
+                width=1280,
+                num_inference_steps=50,
+                fps=30,
+                guidance_scale=1.0,
+                seed=SEED,
+            ),
+            output=OutputConfig(
+                output_path=refine_output_path,
+                save_video=True,
+            ),
+            extensions={
+                "t_thresh": 0.5,
+                "spatial_refine_only": False,
+                "num_cond_frames": 0,  # For refinement, no conditioning frames
+            },
+        )
     )
-    
+
     print(f"Refinement complete! Video saved to: {refine_output_path}")
     refine_generator.shutdown()
 

examples/inference/basic/basic_ltx2.py

@@ -1,4 +1,11 @@
 from fastvideo import VideoGenerator
+from fastvideo.api import (
+    EngineConfig,
+    GenerationRequest,
+    GeneratorConfig,
+    OutputConfig,
+    SamplingConfig,
+)
 
 
 PROMPT = (
@@ -18,22 +25,32 @@ PROMPT = (
 
 def main() -> None:
     # Uses FastVideo default sampling settings for LTX2 base.
-    generator = VideoGenerator.from_pretrained(
-        "Davids048/LTX2-Base-Diffusers",
-        num_gpus=1,
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="Davids048/LTX2-Base-Diffusers",
+            engine=EngineConfig(
+                num_gpus=1,
+            ),
+        )
     )
 
     output_path = "outputs_video/ltx2_basic/output_ltx2_base_t2v_1088_1920_1.1.mp4"
-    generator.generate_video(
-        prompt=PROMPT,
-        output_path=output_path,
-        save_video=True,
-        num_frames=121,
-        height=1088,
-        width=1920,
+    generator.generate(
+        GenerationRequest(
+            prompt=PROMPT,
+            output=OutputConfig(
+                output_path=output_path,
+                save_video=True,
+            ),
+            sampling=SamplingConfig(
+                num_frames=121,
+                height=1088,
+                width=1920,
+            ),
+        )
     )
     generator.shutdown()
 
 
 if __name__ == "__main__":
-    main()
+    main()

examples/inference/basic/basic_ltx2_3_distilled_i2v.py

@@ -49,6 +49,11 @@ from pathlib import Path
 import torch._inductor.config as _inductor
 
 from fastvideo import VideoGenerator
+from fastvideo.api import (
+    CompileConfig, ComponentConfig, EngineConfig, GenerationRequest,
+    GeneratorConfig, OffloadConfig, OutputConfig, PipelineSelection,
+    SamplingConfig,
+)
 from fastvideo.configs.pipelines.base import PipelineConfig
 from fastvideo.utils import maybe_download_model
 
@@ -86,9 +91,9 @@ PROMPT = os.getenv("LTX23_I2V_PROMPT", DEFAULT_PROMPT)
 
 # Per-stage timing helpers --------------------------------------------------
 
-def _print_stage_breakdown(result: dict, label: str) -> float | None:
+def _print_stage_breakdown(result, label: str) -> float | None:
     """Print stage execution times and return the sum, or None if missing."""
-    logging_info = result.get("logging_info")
+    logging_info = result.logging_info
     stages = getattr(logging_info, "stages", None) if logging_info else None
     if not stages:
         print(f"  [{label}] stage breakdown unavailable")
@@ -104,11 +109,11 @@ def _print_stage_breakdown(result: dict, label: str) -> float | None:
 
 
 def _collect_stage_times(
-    result: dict,
+    result,
     stage_times: dict[str, list[float]],
     stage_order: OrderedDict[str, None],
 ) -> None:
-    logging_info = result.get("logging_info")
+    logging_info = result.logging_info
     stages = getattr(logging_info, "stages", None) if logging_info else None
     if not stages:
         return
@@ -169,34 +174,54 @@ def main() -> None:
     pipeline_config = PipelineConfig.from_pretrained(model_root)
     pipeline_config.dit_config.quant_config = None
 
-    generator = VideoGenerator.from_pretrained(
-        model_root,
-        num_gpus=1,
-        # LTX-2.3 distilled uses the two-stage refine pipeline; the refine
-        # LoRA is intentionally empty for the distilled student.
-        ltx2_refine_enabled=True,
-        ltx2_refine_upsampler_path=str(refine_upsampler_path),
-        ltx2_refine_lora_path="",
-        ltx2_refine_num_inference_steps=3,
-        ltx2_refine_guidance_scale=1.0,
-        ltx2_refine_add_noise=True,
-        pipeline_config=pipeline_config,
-        enable_torch_compile=True,
-        enable_torch_compile_text_encoder=True,
-        # Compile the VAE codec submodules (encoder / decoder) too. The
-        # `LTX2CausalVideoAutoencoder` declares `_compile_conditions` so
-        # `_compile_with_conditions` targets just those submodules and
-        # leaves the surrounding tiling control flow eager — needed for
-        # fullgraph + dynamic=False to succeed. VAE eager decode is
-        # ~1.0s; compiling it brings the stage to ~0.3s.
-        enable_torch_compile_vae=True,
-        torch_compile_kwargs=torch_compile_kwargs,
-        torch_compile_kwargs_vae=torch_compile_kwargs,
-        # Keep everything resident — no CPU offload for serving-style runs.
-        dit_cpu_offload=False,
-        text_encoder_cpu_offload=False,
-        vae_cpu_offload=False,
-        ltx2_vae_tiling=False,
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path=model_root,
+            engine=EngineConfig(
+                num_gpus=1,
+                compile=CompileConfig(
+                    enabled=True,
+                    text_encoder_enabled=True,
+                    # Compile the VAE codec submodules (encoder / decoder)
+                    # too. The `LTX2CausalVideoAutoencoder` declares
+                    # `_compile_conditions` so `_compile_with_conditions`
+                    # targets just those submodules and leaves the
+                    # surrounding tiling control flow eager — needed for
+                    # fullgraph + dynamic=False to succeed. VAE eager decode
+                    # is ~1.0s; compiling it brings the stage to ~0.3s.
+                    vae_enabled=True,
+                    backend=torch_compile_kwargs["backend"],
+                    fullgraph=torch_compile_kwargs["fullgraph"],
+                    mode=torch_compile_kwargs["mode"],
+                    dynamic=torch_compile_kwargs["dynamic"],
+                    vae_kwargs=torch_compile_kwargs,
+                ),
+                # Keep everything resident — no CPU offload for serving runs.
+                offload=OffloadConfig(
+                    dit=False,
+                    text_encoder=False,
+                    vae=False,
+                ),
+            ),
+            pipeline=PipelineSelection(
+                vae_tiling=False,
+                # LTX-2.3 distilled uses the two-stage refine pipeline; the
+                # refine LoRA is intentionally empty for the distilled
+                # student.
+                components=ComponentConfig(
+                    upsampler_weights=str(refine_upsampler_path),
+                ),
+                preset_overrides={
+                    "refine": {
+                        "enabled": True,
+                        "num_inference_steps": 3,
+                        "guidance_scale": 1.0,
+                        "add_noise": True,
+                    }
+                },
+                experimental={"pipeline_config": pipeline_config},
+            ),
+        )
     )
 
     common_kwargs = dict(
@@ -206,12 +231,15 @@ def main() -> None:
         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.
+    )
+
+    # 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. These are model-specific knobs routed through
+    # the request extensions escape hatch.
+    common_extensions = dict(
         ltx2_images=[(I2V_IMAGE, 0, 1.0)],
         ltx2_image_crf=0.0,
-        save_video=True,
     )
 
     warmup_runs = 2
@@ -227,10 +255,25 @@ def main() -> None:
         for w in range(warmup_runs):
             t0 = time.perf_counter()
             print(f"\n[warmup {w + 1}/{warmup_runs}] compiling + generating…")
-            generator.generate_video(
-                output_path=str(OUTPUT_DIR / f"_warmup_{w + 1}.mp4"),
-                seed=7,
-                **common_kwargs,
+            generator.generate(
+                GenerationRequest(
+                    prompt=common_kwargs["prompt"],
+                    negative_prompt=common_kwargs["negative_prompt"],
+                    sampling=SamplingConfig(
+                        guidance_scale=common_kwargs["guidance_scale"],
+                        height=common_kwargs["height"],
+                        width=common_kwargs["width"],
+                        num_frames=common_kwargs["num_frames"],
+                        fps=common_kwargs["fps"],
+                        num_inference_steps=common_kwargs["num_inference_steps"],
+                        seed=7,
+                    ),
+                    output=OutputConfig(
+                        output_path=str(OUTPUT_DIR / f"_warmup_{w + 1}.mp4"),
+                        save_video=True,
+                    ),
+                    extensions=common_extensions,
+                )
             )
             dt = time.perf_counter() - t0
             warmup_secs.append(dt)
@@ -245,19 +288,31 @@ def main() -> None:
             out_path = OUTPUT_DIR / f"output_ltx2_3_distilled_i2v_run_{m + 1}.mp4"
             print(f"\n[measured {m + 1}/{measured_runs}] generating: {out_path}")
             t0 = time.perf_counter()
-            result = generator.generate_video(
-                output_path=str(out_path),
-                seed=2002 + m,
-                **common_kwargs,
+            result = generator.generate(
+                GenerationRequest(
+                    prompt=common_kwargs["prompt"],
+                    negative_prompt=common_kwargs["negative_prompt"],
+                    sampling=SamplingConfig(
+                        guidance_scale=common_kwargs["guidance_scale"],
+                        height=common_kwargs["height"],
+                        width=common_kwargs["width"],
+                        num_frames=common_kwargs["num_frames"],
+                        fps=common_kwargs["fps"],
+                        num_inference_steps=common_kwargs["num_inference_steps"],
+                        seed=2002 + m,
+                    ),
+                    output=OutputConfig(
+                        output_path=str(out_path),
+                        save_video=True,
+                    ),
+                    extensions=common_extensions,
+                )
             )
             wall = time.perf_counter() - t0
-            e2e = (
-                result.get("e2e_latency")
-                if isinstance(result, dict) else None
-            ) or wall
+            e2e = (result.extra.get("e2e_latency") if result is not None 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):
+            if result is not None:
                 _print_stage_breakdown(result, f"measured {m + 1}")
                 _collect_stage_times(result, stage_times, stage_order)
 

examples/inference/basic/basic_ltx2_distilled.py

@@ -1,4 +1,5 @@
 from fastvideo import VideoGenerator
+from fastvideo.api import EngineConfig, GenerationRequest, GeneratorConfig, OutputConfig
 
 PROMPT = (
     "A warm sunny backyard. The camera starts in a tight cinematic close-up "
@@ -17,16 +18,19 @@ import os
 os.environ["FASTVIDEO_ATTENTION_BACKEND"] = "FLASH_ATTN"
 
 def main() -> None:
-    generator = VideoGenerator.from_pretrained(
-        "FastVideo/LTX2-Distilled-Diffusers",
-        num_gpus=4,
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="FastVideo/LTX2-Distilled-Diffusers",
+            engine=EngineConfig(num_gpus=4),
+        )
     )
 
     output_path = "outputs_video/ltx2_basic/output_ltx2_distilled_t2v.mp4"
-    generator.generate_video(
-        prompt=PROMPT,
-        output_path=output_path,
-        save_video=True,
+    generator.generate(
+        GenerationRequest(
+            prompt=PROMPT,
+            output=OutputConfig(output_path=output_path, save_video=True),
+        )
     )
     generator.shutdown()
 

examples/inference/basic/basic_ltx2_distilled_fast_profile.py

@@ -8,6 +8,11 @@ from pathlib import Path
 import torch
 import torch._inductor.config
 from fastvideo import VideoGenerator
+from fastvideo.api import (
+    CompileConfig, ComponentConfig, EngineConfig, GenerationRequest,
+    GenerationResult, GeneratorConfig, OffloadConfig, OutputConfig,
+    PipelineSelection, SamplingConfig,
+)
 from fastvideo.configs.pipelines.base import PipelineConfig
 from fastvideo.layers.quantization.nvfp4_config import NVFP4Config
 from fastvideo.utils import maybe_download_model
@@ -45,11 +50,11 @@ def load_validation_entries(path: Path) -> list[dict]:
 
 
 def print_stage_breakdown(
-    result: dict,
+    result: GenerationResult,
     run_idx: int,
     num_runs: int,
 ) -> float | None:
-    logging_info = result.get("logging_info")
+    logging_info = result.logging_info
     if logging_info is None:
         print(f"[{run_idx}/{num_runs}] Stage breakdown unavailable: no logging_info")
         return None
@@ -70,9 +75,9 @@ def print_stage_breakdown(
 
 
 def extract_sr_forward_latency(
-    result: dict,
+    result: GenerationResult,
 ) -> tuple[float | None, list[tuple[str, float]], list[str]]:
-    logging_info = result.get("logging_info")
+    logging_info = result.logging_info
     if logging_info is None:
         return None, [], []
 
@@ -106,11 +111,11 @@ def extract_sr_forward_latency(
 
 
 def collect_stage_times(
-    result: dict,
+    result: GenerationResult,
     stage_times: dict[str, list[float]],
     stage_order: OrderedDict[str, None],
 ) -> None:
-    logging_info = result.get("logging_info")
+    logging_info = result.logging_info
     if logging_info is None:
         return
     stages = getattr(logging_info, "stages", None)
@@ -202,26 +207,45 @@ def main() -> None:
         "dynamic": False,
     }
 
-    generator = VideoGenerator.from_pretrained(
-        model_root,
-        num_gpus=1,
-        ltx2_refine_enabled=True,
-        ltx2_refine_upsampler_path=str(refine_upsampler_path),
-        refine_lora_path="",  # keep refine LoRA disabled in this repo's typed adapter
-        ltx2_refine_lora_path="",  # keep refine LoRA disabled for distilled model
-        ltx2_refine_num_inference_steps=2,
-        ltx2_refine_guidance_scale=1.0,
-        ltx2_refine_add_noise=True,
-        pipeline_config=pipeline_config,
-        enable_torch_compile=True,
-        enable_torch_compile_text_encoder=True,
-        enable_torch_compile_vae=True,
-        torch_compile_kwargs=torch_compile_kwargs,
-        torch_compile_kwargs_vae=torch_compile_kwargs,
-        dit_cpu_offload=False,
-        text_encoder_cpu_offload=False,
-        vae_cpu_offload=False,
-        ltx2_vae_tiling=False,
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path=model_root,
+            engine=EngineConfig(
+                num_gpus=1,
+                offload=OffloadConfig(
+                    dit=False,
+                    text_encoder=False,
+                    vae=False,
+                ),
+                compile=CompileConfig(
+                    enabled=True,
+                    text_encoder_enabled=True,
+                    vae_enabled=True,
+                    backend="inductor",
+                    fullgraph=True,
+                    dynamic=False,
+                    vae_kwargs=torch_compile_kwargs,
+                ),
+            ),
+            pipeline=PipelineSelection(
+                vae_tiling=False,
+                components=ComponentConfig(
+                    upsampler_weights=str(refine_upsampler_path),
+                ),
+                preset_overrides={
+                    "refine": {
+                        "enabled": True,
+                        "num_inference_steps": 2,
+                        "guidance_scale": 1.0,
+                        "add_noise": True,
+                    }
+                },
+                experimental={
+                    "refine_lora_path": "",  # keep refine LoRA disabled in this repo's typed adapter
+                    "pipeline_config": pipeline_config,
+                },
+            ),
+        )
     )
 
     run_times: list[float] = []
@@ -243,25 +267,31 @@ def main() -> None:
                 torch.cuda.synchronize()
 
             start = time.perf_counter()
-            result = generator.generate_video(
-                prompt=prompt,
-                output_path=str(output_path),
-                fps=24,
-                seed=10,
-                save_video=True,
-                guidance_scale=1.0,
-                height=benchmark_entry.get("height", 1088),
-                width=benchmark_entry.get("width", 1920),
-                num_frames=121,
-                num_inference_steps=5,
-                # image_path="examples/inference/basic/prompt1.png",
-                # ltx2_image_crf=0.0
+            result = generator.generate(
+                GenerationRequest(
+                    prompt=prompt,
+                    sampling=SamplingConfig(
+                        fps=24,
+                        seed=10,
+                        guidance_scale=1.0,
+                        height=benchmark_entry.get("height", 1088),
+                        width=benchmark_entry.get("width", 1920),
+                        num_frames=121,
+                        num_inference_steps=5,
+                    ),
+                    output=OutputConfig(
+                        output_path=str(output_path),
+                        save_video=True,
+                    ),
+                    # inputs=InputConfig(image_path="examples/inference/basic/prompt1.png"),
+                    # extensions={"ltx2_image_crf": 0.0},
+                )
             )
             if os.environ.get("FASTVIDEO_STAGE_LOGGING") == "0":
                 torch.cuda.synchronize()
 
-            elapsed = result.get("generation_time") if isinstance(result, dict) else None
-            e2e_elapsed = result.get("e2e_latency") if isinstance(result, dict) else None
+            elapsed = result.generation_time if isinstance(result, GenerationResult) else None
+            e2e_elapsed = result.extra.get("e2e_latency") if isinstance(result, GenerationResult) else None
             if elapsed is None:
                 elapsed = time.perf_counter() - start
             if e2e_elapsed is None:
@@ -272,7 +302,7 @@ def main() -> None:
             print(f"[{i + 1}/{num_runs}] Generation time: {elapsed:.2f}s")
             print(f"[{i + 1}/{num_runs}] End-to-end latency: {e2e_elapsed:.2f}s")
 
-            if isinstance(result, dict):
+            if isinstance(result, GenerationResult):
                 stage_sum = print_stage_breakdown(result, i + 1, num_runs)
                 if stage_sum is not None:
                     non_stage_overhead = e2e_elapsed - stage_sum

examples/inference/basic/basic_lucy_edit.py

@@ -1,18 +1,27 @@
 from fastvideo import VideoGenerator
+from fastvideo.api import (
+    EngineConfig, GenerationRequest, GeneratorConfig, InputConfig,
+    OffloadConfig, OutputConfig, SamplingConfig,
+)
 
 OUTPUT_PATH = "video_samples_lucy_edit"
 
 
 def main():
-    generator = VideoGenerator.from_pretrained(
-        "decart-ai/Lucy-Edit-Dev",
-        num_gpus=1,
-        use_fsdp_inference=False,
-        dit_cpu_offload=True,
-        vae_cpu_offload=False,
-        text_encoder_cpu_offload=True,
-        pin_cpu_memory=True,
-    )
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="decart-ai/Lucy-Edit-Dev",
+            engine=EngineConfig(
+                num_gpus=1,
+                use_fsdp_inference=False,
+                offload=OffloadConfig(
+                    dit=True,
+                    vae=False,
+                    text_encoder=True,
+                    pin_cpu_memory=True,
+                ),
+            ),
+        ))
 
     prompt = ("Change the apron and blouse to a classic clown costume: satin "
               "polka-dot jumpsuit in bright primary colors, ruffled white collar, "
@@ -20,18 +29,20 @@ def main():
               "foam nose; soft window light from left, eye-level medium shot.")
     video_path = "https://d2drjpuinn46lb.cloudfront.net/painter_original_edit.mp4"
 
-    generator.generate_video(
-        prompt,
-        negative_prompt="",
-        video_path=video_path,
-        output_path=OUTPUT_PATH,
-        save_video=True,
-        height=480,
-        width=832,
-        num_frames=81,
-        fps=24,
-        guidance_scale=5.0,
-    )
+    generator.generate(
+        GenerationRequest(
+            prompt=prompt,
+            negative_prompt="",
+            inputs=InputConfig(video_path=video_path),
+            sampling=SamplingConfig(
+                height=480,
+                width=832,
+                num_frames=81,
+                fps=24,
+                guidance_scale=5.0,
+            ),
+            output=OutputConfig(output_path=OUTPUT_PATH, save_video=True),
+        ))
 
 
 if __name__ == "__main__":

examples/inference/basic/basic_matrixgame2.py

@@ -1,4 +1,6 @@
 from fastvideo import VideoGenerator
+from fastvideo.api import (EngineConfig, GenerationRequest, GeneratorConfig, InputConfig, OffloadConfig, OutputConfig,
+                           SamplingConfig)
 from fastvideo.models.dits.matrixgame2.utils import create_action_presets
 
 import torch
@@ -38,35 +40,48 @@ def main():
     # attempt to identify the optimal arguments.
     config = VARIANT_CONFIG[MODEL_VARIANT]
 
-    generator = VideoGenerator.from_pretrained(
-        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
-        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
-        pin_cpu_memory=True,
-        # image_encoder_cpu_offload=False,
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path=config["model_path"],
+            # FastVideo will automatically handle distributed setup
+            engine=EngineConfig(
+                num_gpus=1,
+                use_fsdp_inference=False,  # set to True if GPU is out of memory
+                offload=OffloadConfig(
+                    dit=True,  # DiT need to be offloaded for MoE
+                    vae=False,
+                    text_encoder=True,
+                    # Set pin_cpu_memory to false if CPU RAM is limited and there're no frequent CPU-GPU transfer
+                    pin_cpu_memory=True,
+                ),
+            ),
+        )
     )
 
     num_frames = 597
     actions = create_action_presets(num_frames, keyboard_dim=config["keyboard_dim"])
     grid_sizes = torch.tensor([150, 44, 80])
 
-    generator.generate_video(
-        prompt="",
-        image_path=config["image_url"],
-        mouse_cond=actions["mouse"].unsqueeze(0),
-        keyboard_cond=actions["keyboard"].unsqueeze(0),
-        grid_sizes=grid_sizes,
-        num_frames=num_frames,
-        height=352,
-        width=640,
-        num_inference_steps=50,
-        output_path=OUTPUT_PATH,
-        save_video=True,
+    generator.generate(
+        GenerationRequest(
+            prompt="",
+            inputs=InputConfig(
+                image_path=config["image_url"],
+                mouse_cond=actions["mouse"].unsqueeze(0),
+                keyboard_cond=actions["keyboard"].unsqueeze(0),
+                grid_sizes=grid_sizes,
+            ),
+            sampling=SamplingConfig(
+                num_frames=num_frames,
+                height=352,
+                width=640,
+                num_inference_steps=50,
+            ),
+            output=OutputConfig(
+                output_path=OUTPUT_PATH,
+                save_video=True,
+            ),
+        )
     )
 
 

examples/inference/basic/basic_matrixgame2_streaming.py

@@ -1,5 +1,6 @@
 from fastvideo.entrypoints.streaming_generator import StreamingVideoGenerator
 from fastvideo.models.dits.matrixgame2.utils import get_current_action_async, expand_action_to_frames
+from fastvideo.api import EngineConfig, GeneratorConfig, OffloadConfig
 
 import torch
 import asyncio
@@ -42,17 +43,23 @@ async def main():
     # attempt to identify the optimal arguments.
     config = VARIANT_CONFIG[MODEL_VARIANT]
 
-    generator = StreamingVideoGenerator.from_pretrained(
-        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
-        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
-        pin_cpu_memory=True,
-        # image_encoder_cpu_offload=False,
+    generator = StreamingVideoGenerator.from_config(
+        GeneratorConfig(
+            model_path=config["model_path"],
+            # FastVideo will automatically handle distributed setup
+            engine=EngineConfig(
+                num_gpus=1,
+                use_fsdp_inference=False,  # set to True if GPU is out of memory
+                offload=OffloadConfig(
+                    dit=True,  # DiT need to be offloaded for MoE
+                    vae=False,
+                    text_encoder=True,
+                    # Set pin_cpu_memory to false if CPU RAM is limited and there're no frequent CPU-GPU transfer
+                    pin_cpu_memory=True,
+                    # image_encoder=False,
+                ),
+            ),
+        )
     )
 
     max_blocks = 50

examples/inference/basic/basic_matrixgame3.py

@@ -1,4 +1,7 @@
 from fastvideo import VideoGenerator
+from fastvideo.api import (
+    EngineConfig, GenerationRequest, GeneratorConfig, InputConfig, OffloadConfig, OutputConfig, SamplingConfig,
+)
 
 MODEL_PATH = "FastVideo/Matrix-Game-3.0-Base-Distilled-Diffusers"
 IMAGE_URL = "https://raw.githubusercontent.com/SkyworkAI/Matrix-Game/main/Matrix-Game-3/demo_images/001/image.png"
@@ -7,28 +10,38 @@ OUTPUT_PATH = "video_samples_matrixgame3"
 
 
 def main():
-    generator = VideoGenerator.from_pretrained(
-        MODEL_PATH,
-        num_gpus=1,
-        use_fsdp_inference=False,
-        dit_cpu_offload=False,
-        vae_cpu_offload=False,
-        text_encoder_cpu_offload=True,
-        pin_cpu_memory=True,
-    )
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path=MODEL_PATH,
+            engine=EngineConfig(
+                num_gpus=1,
+                use_fsdp_inference=False,
+                offload=OffloadConfig(
+                    dit=False,
+                    vae=False,
+                    text_encoder=True,
+                    pin_cpu_memory=True,
+                ),
+            ),
+        ))
 
-    generator.generate_video(
-        prompt=PROMPT,
-        image_path=IMAGE_URL,
-        height=720,
-        width=1280,
-        num_frames=57,
-        num_inference_steps=3,
-        guidance_scale=1.0,
-        seed=42,
-        output_path=OUTPUT_PATH,
-        save_video=True,
-    )
+    generator.generate(
+        GenerationRequest(
+            prompt=PROMPT,
+            inputs=InputConfig(image_path=IMAGE_URL),
+            sampling=SamplingConfig(
+                height=720,
+                width=1280,
+                num_frames=57,
+                num_inference_steps=3,
+                guidance_scale=1.0,
+                seed=42,
+            ),
+            output=OutputConfig(
+                output_path=OUTPUT_PATH,
+                save_video=True,
+            ),
+        ))
 
 
 if __name__ == "__main__":

examples/inference/basic/basic_mps.py

@@ -1,40 +1,56 @@
 from fastvideo import VideoGenerator, PipelineConfig
-from fastvideo.api.sampling_param import SamplingParam
+from fastvideo.api import (
+    EngineConfig,
+    GenerationRequest,
+    GeneratorConfig,
+    OffloadConfig,
+    PipelineSelection,
+    SamplingConfig,
+)
 
 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,      
+
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="Wan-AI/Wan2.1-T2V-1.3B-Diffusers",
+            engine=EngineConfig(
+                num_gpus=1,
+                use_fsdp_inference=False,      # Disable FSDP for MPS
+                disable_autocast=False,
+                offload=OffloadConfig(
+                    dit=True,
+                    text_encoder=True,
+                    pin_cpu_memory=True,
+                ),
+            ),
+            pipeline=PipelineSelection(
+                experimental={"pipeline_config": config},
+            ),
+        )
     )
 
-    # Create sampling parameters with reduced number of frames
-    sampling_param = SamplingParam.from_pretrained("Wan-AI/Wan2.1-T2V-1.3B-Diffusers")
-    sampling_param.num_frames = 25  # Reduce from default 81 to 25 frames bc we have to use the SDPA attn backend for mps
-    sampling_param.height = 256
-    sampling_param.width = 256
+    # Reduce from default 81 to 25 frames bc we have to use the SDPA attn backend for mps
+    sampling = SamplingConfig(
+        num_frames=25,
+        height=256,
+        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.")
-    
-    video = generator.generate_video(prompt, sampling_param=sampling_param)
+
+    video = generator.generate(GenerationRequest(prompt=prompt, sampling=sampling))
 
     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, sampling_param=sampling_param)
+
+    video2 = generator.generate(GenerationRequest(prompt=prompt2, sampling=sampling))
 
 if __name__ == "__main__":
     main()

examples/inference/basic/basic_ray.py

@@ -1,6 +1,8 @@
 from fastvideo import VideoGenerator
-
-# from fastvideo.api.sampling_param import SamplingParam
+from fastvideo.api import (
+    EngineConfig, GenerationRequest, GeneratorConfig, OffloadConfig,
+    OutputConfig,
+)
 
 OUTPUT_PATH = "video_samples"
 def main():
@@ -8,17 +10,23 @@ def main():
     # model.
     # If a local path is provided, FastVideo will make a best effort
     # attempt to identify the optimal arguments.
-    generator = VideoGenerator.from_pretrained(
-        "Wan-AI/Wan2.1-T2V-1.3B-Diffusers",
-        # FastVideo will automatically handle distributed setup
-        num_gpus=2,
-        use_fsdp_inference=True,
-        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"
-        distributed_executor_backend="ray",
-        # image_encoder_cpu_offload=False,
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="Wan-AI/Wan2.1-T2V-1.3B-Diffusers",
+            # FastVideo will automatically handle distributed setup
+            engine=EngineConfig(
+                num_gpus=2,
+                use_fsdp_inference=True,
+                execution_backend="ray",
+                offload=OffloadConfig(
+                    dit=False,
+                    vae=False,
+                    text_encoder=True,
+                    pin_cpu_memory=True, # set to false if low CPU RAM or hit obscure "CUDA error: Invalid argument"
+                    # image_encoder=False,
+                ),
+            ),
+        )
     )
 
     # Generate videos with the same simple API, regardless of GPU count
@@ -27,7 +35,8 @@ def main():
         "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(
+        GenerationRequest(prompt=prompt, output=OutputConfig(output_path=OUTPUT_PATH, save_video=True)))
 
     # Generate another video with a different prompt, without reloading the
     # model!
@@ -37,7 +46,8 @@ def main():
         "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)
+    video2 = generator.generate(
+        GenerationRequest(prompt=prompt2, output=OutputConfig(output_path=OUTPUT_PATH, save_video=True)))
 
 
 if __name__ == "__main__":

examples/inference/basic/basic_sd35_t2i.py

@@ -85,24 +85,35 @@ def main() -> None:
         os.environ["FASTVIDEO_ATTENTION_BACKEND"] = args.backend
 
     from fastvideo import VideoGenerator
+    from fastvideo.api import (
+        EngineConfig, GenerationRequest, GeneratorConfig, OffloadConfig, OutputConfig,
+        ParallelismConfig, PipelineSelection, SamplingConfig,
+    )
 
     os.makedirs(args.out_dir, exist_ok=True)
 
-    init_kwargs = {
-        "num_gpus": args.num_gpus,
-        "workload_type": "t2i",
-        "sp_size": 1,
-        "tp_size": 1,
-        "dit_cpu_offload": False,
-        "dit_layerwise_offload": False,
-        "text_encoder_cpu_offload": False,
-        "vae_cpu_offload": False,
-        "image_encoder_cpu_offload": False,
-        "pin_cpu_memory": False,
-        "use_fsdp_inference": False,
-    }
-
-    generator = VideoGenerator.from_pretrained(model_path=args.model_path, **init_kwargs)
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path=args.model_path,
+            engine=EngineConfig(
+                num_gpus=args.num_gpus,
+                use_fsdp_inference=False,
+                parallelism=ParallelismConfig(
+                    sp_size=1,
+                    tp_size=1,
+                ),
+                offload=OffloadConfig(
+                    dit=False,
+                    dit_layerwise=False,
+                    text_encoder=False,
+                    vae=False,
+                    image_encoder=False,
+                    pin_cpu_memory=False,
+                ),
+            ),
+            pipeline=PipelineSelection(workload_type="t2i"),
+        )
+    )
     try:
         for i, prompt in enumerate(prompts):
             seed = args.seed + i
@@ -113,20 +124,25 @@ def main() -> None:
             output_path = os.path.join(args.out_dir, f"{filename_base}.png")
             print(f"[sd35] prompt_idx={i} seed={seed} output_path={output_path}")
 
-            generation_kwargs = {
-                "output_path": output_path,
-                "height": args.height,
-                "width": args.width,
-                "num_frames": 1,
-                "fps": 1,
-                "num_inference_steps": args.steps,
-                "guidance_scale": args.guidance,
-                "seed": seed,
-                "negative_prompt": args.negative,
-                "save_video": True,
-            }
-
-            generator.generate_video(prompt, **generation_kwargs)
+            generator.generate(
+                GenerationRequest(
+                    prompt=prompt,
+                    negative_prompt=args.negative,
+                    sampling=SamplingConfig(
+                        height=args.height,
+                        width=args.width,
+                        num_frames=1,
+                        fps=1,
+                        num_inference_steps=args.steps,
+                        guidance_scale=args.guidance,
+                        seed=seed,
+                    ),
+                    output=OutputConfig(
+                        output_path=output_path,
+                        save_video=True,
+                    ),
+                )
+            )
 
         print(f"[sd35] done. outputs written to: {args.out_dir}")
     finally:

examples/inference/basic/basic_self_forcing_causal.py

@@ -1,6 +1,14 @@
 import os
 import time
-from fastvideo import VideoGenerator, SamplingParam
+
+from fastvideo import VideoGenerator
+from fastvideo.api import (
+    EngineConfig,
+    GenerationRequest,
+    GeneratorConfig,
+    OffloadConfig,
+    OutputConfig,
+)
 
 OUTPUT_PATH = "video_samples_causal"
 def main():
@@ -9,23 +17,33 @@ def main():
     # If a local path is provided, FastVideo will make a best effort
     # attempt to identify the optimal arguments.
     model_name = "wlsaidhi/SFWan2.1-T2V-1.3B-Diffusers"
-    generator = VideoGenerator.from_pretrained(
-        model_name,
+    generator_config = GeneratorConfig(
+        model_path=model_name,
         # FastVideo will automatically handle distributed setup
-        num_gpus=1,
-        use_fsdp_inference=False, # set to True if GPU is out of memory
-        text_encoder_cpu_offload=False,
-        dit_cpu_offload=False,
+        engine=EngineConfig(
+            num_gpus=1,
+            use_fsdp_inference=False, # set to True if GPU is out of memory
+            offload=OffloadConfig(
+                text_encoder=False,
+                dit=False,
+            ),
+        ),
     )
-
-    sampling_param = SamplingParam.from_pretrained(model_name)
+    generator = VideoGenerator.from_config(generator_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."
     )
-    video = generator.generate_video(prompt, output_path=OUTPUT_PATH, save_video=True, sampling_param=sampling_param)
+    request = GenerationRequest(
+        prompt=prompt,
+        output=OutputConfig(
+            output_path=OUTPUT_PATH,
+            save_video=True,
+        ),
+    )
+    video = generator.generate(request)
 
 if __name__ == "__main__":
     main()

examples/inference/basic/basic_self_forcing_causal_wan2_2_i2v.py

@@ -1,8 +1,17 @@
 # NOTE: This is still a work in progress, and the checkpoints are not released yet.
 
-from fastvideo import VideoGenerator, SamplingParam
+from fastvideo import VideoGenerator
+from fastvideo.api import (
+    EngineConfig,
+    GenerationRequest,
+    GeneratorConfig,
+    InputConfig,
+    OffloadConfig,
+    OutputConfig,
+    PipelineSelection,
+    SamplingConfig,
+)
 import json
-# from fastvideo.api.sampling_param import SamplingParam
 
 OUTPUT_PATH = "video_samples_self_forcing_causal_wan2_2_14B_i2v"
 def main():
@@ -10,26 +19,37 @@ def main():
     # model.
     # If a local path is provided, FastVideo will make a best effort
     # attempt to identify the optimal arguments.
-    generator = VideoGenerator.from_pretrained(
-        "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
-        dit_precision="fp32",
-        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,
-        # image_encoder_cpu_offload=False,
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="FastVideo/SFWan2.2-I2V-A14B-Preview-Diffusers",
+            # FastVideo will automatically handle distributed setup
+            engine=EngineConfig(
+                num_gpus=1,
+                use_fsdp_inference=False,  # set to True if GPU is out of memory
+                offload=OffloadConfig(
+                    dit=True,  # DiT need to be offloaded for MoE
+                    vae=False,
+                    text_encoder=True,
+                    # Set pin_cpu_memory to false if CPU RAM is limited and there're no frequent CPU-GPU transfer
+                    pin_cpu_memory=True,
+                    # image_encoder=False,
+                ),
+            ),
+            pipeline=PipelineSelection(
+                experimental={
+                    "dit_precision": "fp32",
+                    "dmd_denoising_steps": [1000, 850, 700, 550, 350, 275, 200, 125],
+                },
+            ),
+        )
     )
 
-    sampling_param = SamplingParam.from_pretrained("FastVideo/SFWan2.2-I2V-A14B-Preview-Diffusers")
-    sampling_param.num_frames = 81
-    sampling_param.width = 832
-    sampling_param.height = 480
-    sampling_param.seed = 1000
+    sampling = SamplingConfig(
+        num_frames=81,
+        width=832,
+        height=480,
+        seed=1000,
+    )
 
     with open("assets/prompts/mixkit_i2v.jsonl", "r") as f:
         prompt_image_pairs = json.load(f)
@@ -37,7 +57,14 @@ 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(
+            GenerationRequest(
+                prompt=prompt,
+                inputs=InputConfig(image_path=image_path),
+                sampling=sampling,
+                output=OutputConfig(output_path=OUTPUT_PATH, save_video=True),
+            )
+        )
 
 
 if __name__ == "__main__":

examples/inference/basic/basic_self_forcing_causal_wan2_2_t2v.py

@@ -1,8 +1,10 @@
 # NOTE: This is still a work in progress, and the checkpoints are not released yet.
 
 from fastvideo import VideoGenerator
-
-# from fastvideo.api.sampling_param import SamplingParam
+from fastvideo.api import (
+    ComponentConfig, EngineConfig, GenerationRequest, GeneratorConfig,
+    OffloadConfig, OutputConfig, PipelineSelection, SamplingConfig,
+)
 
 OUTPUT_PATH = "video_samples_self_forcing_causal_wan2_2_14B_t2v"
 def main():
@@ -10,34 +12,49 @@ def main():
     # model.
     # If a local path is provided, FastVideo will make a best effort
     # attempt to identify the optimal arguments.
-    generator = VideoGenerator.from_pretrained(
-        "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
-        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/",
-        num_frame_per_block=7,
-        # image_encoder_cpu_offload=False,
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="rand0nmr/SFWan2.2-T2V-A14B-Diffusers",
+            engine=EngineConfig(
+                # FastVideo will automatically handle distributed setup
+                num_gpus=1,
+                use_fsdp_inference=False,  # set to True if GPU is out of memory
+                offload=OffloadConfig(
+                    dit=True,  # DiT need to be offloaded for MoE
+                    vae=False,
+                    text_encoder=True,
+                    # Set pin_cpu_memory to false if CPU RAM is limited and there're no frequent CPU-GPU transfer
+                    pin_cpu_memory=True,
+                ),
+            ),
+            pipeline=PipelineSelection(
+                components=ComponentConfig(
+                    transformer_weights="/mnt/sharefs/users/hao.zhang/wei/SFwan2.2_distill_self_forcing_release_cfg2/checkpoint-246_weight_only/generator_inference_transformer/",
+                    transformer_2_weights="/mnt/sharefs/users/hao.zhang/wei/SFwan2.2_distill_self_forcing_release_cfg2/checkpoint-246_weight_only/generator_2_inference_transformer/",
+                ),
+                experimental={
+                    "dmd_denoising_steps": [1000, 850, 700, 550, 350, 275, 200, 125],
+                    "num_frame_per_block": 7,
+                },
+            ),
+            # image_encoder_cpu_offload=False,
+        )
     )
 
-    # sampling_param = SamplingParam.from_pretrained("Wan-AI/Wan2.1-T2V-1.3B-Diffusers")
-    # 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, num_frames=81)
+    _ = generator.generate(
+        GenerationRequest(
+            prompt=prompt,
+            sampling=SamplingConfig(num_frames=81),
+            output=OutputConfig(output_path=OUTPUT_PATH, save_video=True),
+        )
+    )
 
 
 if __name__ == "__main__":
-    main()
+    main()

examples/inference/basic/basic_stable_audio.py

@@ -51,25 +51,31 @@ Prerequisites:
          uv pip install k_diffusion einops_exts alias_free_torch torchsde
 """
 from fastvideo import VideoGenerator
+from fastvideo.api import (EngineConfig, GenerationRequest, GeneratorConfig,
+                           OutputConfig)
 
 PROMPT = "Lo-fi hip hop instrumental with vinyl crackle and gentle piano."
 
 
 def main() -> None:
-    generator = VideoGenerator.from_pretrained(
-        "FastVideo/stable-audio-open-1.0-Diffusers",
-        num_gpus=1,
-    )
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="FastVideo/stable-audio-open-1.0-Diffusers",
+            engine=EngineConfig(num_gpus=1),
+        ))
     output_path = "outputs_audio/stable_audio_basic/output_stable_audio.wav"
-    generator.generate_video(
-        prompt=PROMPT,
-        output_path=output_path,
-        save_video=True,
-        # 6-second clip; the model max is ~47.5s.
-        audio_end_in_s=6.0,
-        # The registered preset gives 100 steps + CFG=7.0 by default;
-        # override num_inference_steps / guidance_scale here for QA.
-    )
+    generator.generate(
+        GenerationRequest(
+            prompt=PROMPT,
+            output=OutputConfig(
+                output_path=output_path,
+                save_video=True,
+            ),
+            # 6-second clip; the model max is ~47.5s.
+            extensions={"audio_end_in_s": 6.0},
+            # The registered preset gives 100 steps + CFG=7.0 by default;
+            # override num_inference_steps / guidance_scale here for QA.
+        ))
     generator.shutdown()
 
 

examples/inference/basic/basic_stable_audio_a2a.py

@@ -48,6 +48,12 @@ Picking `init_audio_strength` (0.0 to 1.0):
 Prerequisites: same as `basic_stable_audio.py`.
 """
 from fastvideo import VideoGenerator
+from fastvideo.api import (
+    EngineConfig,
+    GenerationRequest,
+    GeneratorConfig,
+    OutputConfig,
+)
 
 PROMPT = "Change the piano to a cello playing the same notes"
 # Path to any audio-bearing file (wav, mp3, mp4, m4a, flac, ...).
@@ -58,18 +64,24 @@ INIT_AUDIO_STRENGTH = 0.6
 
 
 def main() -> None:
-    generator = VideoGenerator.from_pretrained(
-        "FastVideo/stable-audio-open-1.0-Diffusers",
-        num_gpus=1,
-    )
-    generator.generate_video(
-        prompt=PROMPT,
-        output_path="outputs_audio/stable_audio_a2a/output_a2a.wav",
-        save_video=True,
-        audio_end_in_s=6.0,
-        init_audio=INIT_AUDIO_PATH,
-        init_audio_strength=INIT_AUDIO_STRENGTH,
-    )
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="FastVideo/stable-audio-open-1.0-Diffusers",
+            engine=EngineConfig(num_gpus=1),
+        ))
+    generator.generate(
+        GenerationRequest(
+            prompt=PROMPT,
+            output=OutputConfig(
+                output_path="outputs_audio/stable_audio_a2a/output_a2a.wav",
+                save_video=True,
+            ),
+            extensions={
+                "audio_end_in_s": 6.0,
+                "init_audio": INIT_AUDIO_PATH,
+                "init_audio_strength": INIT_AUDIO_STRENGTH,
+            },
+        ))
     generator.shutdown()
 
 

examples/inference/basic/basic_stable_audio_inpaint.py

@@ -48,6 +48,9 @@ Prerequisites: same as `basic_stable_audio.py`.
 import os
 
 from fastvideo import VideoGenerator
+from fastvideo.api import (
+    EngineConfig, GeneratorConfig, GenerationRequest, OutputConfig,
+)
 
 PROMPT = "Steady lo-fi hip hop drum loop with vinyl crackle."
 # Required: path to the reference audio file (wav, mp3, mp4, m4a, flac,
@@ -64,19 +67,25 @@ def main() -> None:
             f"REFERENCE_AUDIO_PATH={REFERENCE_AUDIO_PATH!r} does not exist. "
             "Edit this script to point at a real audio file (wav/mp3/mp4/"
             "m4a/flac) before running.")
-    generator = VideoGenerator.from_pretrained(
-        "FastVideo/stable-audio-open-1.0-Diffusers",
-        num_gpus=1,
-    )
-    generator.generate_video(
-        prompt=PROMPT,
-        output_path="outputs_audio/stable_audio_inpaint/output_inpaint.wav",
-        save_video=True,
-        audio_end_in_s=TOTAL_SECONDS,
-        inpaint_audio=REFERENCE_AUDIO_PATH,
-        # Tuple form: keep first KEEP_SECONDS, regenerate the rest.
-        inpaint_mask=(KEEP_SECONDS, TOTAL_SECONDS),
-    )
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="FastVideo/stable-audio-open-1.0-Diffusers",
+            engine=EngineConfig(num_gpus=1),
+        ))
+    generator.generate(
+        GenerationRequest(
+            prompt=PROMPT,
+            output=OutputConfig(
+                output_path="outputs_audio/stable_audio_inpaint/output_inpaint.wav",
+                save_video=True,
+            ),
+            extensions={
+                "audio_end_in_s": TOTAL_SECONDS,
+                "inpaint_audio": REFERENCE_AUDIO_PATH,
+                # Tuple form: keep first KEEP_SECONDS, regenerate the rest.
+                "inpaint_mask": (KEEP_SECONDS, TOTAL_SECONDS),
+            },
+        ))
     generator.shutdown()
 
 

examples/inference/basic/basic_stable_audio_small.py

@@ -28,24 +28,27 @@ Prerequisites: same as `basic_stable_audio.py`. The converted repo is
 public so no gated-access flow is required.
 """
 from fastvideo import VideoGenerator
+from fastvideo.api import (EngineConfig, GenerationRequest, GeneratorConfig,
+                           OutputConfig)
 
 PROMPT = "Lo-fi hip hop instrumental with vinyl crackle and gentle piano."
 
 
 def main() -> None:
-    generator = VideoGenerator.from_pretrained(
-        "FastVideo/stable-audio-open-small-Diffusers",
-        num_gpus=1,
-    )
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="FastVideo/stable-audio-open-small-Diffusers",
+            engine=EngineConfig(num_gpus=1),
+        ))
     output_path = "outputs_audio/stable_audio_small/output_stable_audio_small.wav"
-    generator.generate_video(
-        prompt=PROMPT,
-        output_path=output_path,
-        save_video=True,
-        # Small variant trains on a ~11.9s window — keep `audio_end_in_s`
-        # at or below that.
-        audio_end_in_s=6.0,
-    )
+    generator.generate(
+        GenerationRequest(
+            prompt=PROMPT,
+            output=OutputConfig(output_path=output_path, save_video=True),
+            # Small variant trains on a ~11.9s window — keep `audio_end_in_s`
+            # at or below that.
+            extensions={"audio_end_in_s": 6.0},
+        ))
     generator.shutdown()
 
 

examples/inference/basic/basic_turbodiffusion.py

@@ -4,6 +4,9 @@ import os
 os.environ["FASTVIDEO_ATTENTION_BACKEND"] = "SLA_ATTN"
 
 from fastvideo import VideoGenerator
+from fastvideo.api import (
+    EngineConfig, GenerationRequest, GeneratorConfig, OutputConfig, SamplingConfig,
+)
 
 OUTPUT_PATH = "video_samples_turbodiffusion"
 
@@ -11,14 +14,17 @@ OUTPUT_PATH = "video_samples_turbodiffusion"
 def main() -> None:
     # TurboDiffusion: 1-4 step video generation using RCM scheduler + SLA attention
     # FastVideo will automatically use TurboDiffusionPipeline when specified
-    generator = VideoGenerator.from_pretrained(
-        "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
-
-        # set to false if using RTX 4090 
-        # pin_cpu_memory=False,
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="loayrashid/TurboWan2.1-T2V-1.3B-Diffusers",
+            # FastVideo will automatically handle distributed setup
+            engine=EngineConfig(
+                num_gpus=1,
+                use_fsdp_inference=False,  # set to True if GPU is out of memory
+            ),
+            # set to false if using RTX 4090
+            # pin_cpu_memory=False,
+        )
     )
 
     # Generate videos with the same simple API, regardless of GPU count
@@ -28,11 +34,17 @@ def main() -> None:
         "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,
-        seed=42,
+    video = generator.generate(
+        GenerationRequest(
+            prompt=prompt,
+            output=OutputConfig(
+                output_path=OUTPUT_PATH,
+                save_video=True,
+            ),
+            sampling=SamplingConfig(
+                seed=42,
+            ),
+        )
     )
 
     # Generate another video with a different prompt, without reloading the model!
@@ -43,11 +55,17 @@ def main() -> None:
         "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,
-        seed=42,
+    video2 = generator.generate(
+        GenerationRequest(
+            prompt=prompt2,
+            output=OutputConfig(
+                output_path=OUTPUT_PATH,
+                save_video=True,
+            ),
+            sampling=SamplingConfig(
+                seed=42,
+            ),
+        )
     )
 
 

examples/inference/basic/basic_turbodiffusion_14b.py

@@ -4,6 +4,9 @@ import os
 os.environ["FASTVIDEO_ATTENTION_BACKEND"] = "SLA_ATTN"
 
 from fastvideo import VideoGenerator
+from fastvideo.api import (
+    EngineConfig, GenerationRequest, GeneratorConfig, OutputConfig, SamplingConfig,
+)
 
 OUTPUT_PATH = "video_samples_turbodiffusion_14B"
 
@@ -11,10 +14,12 @@ OUTPUT_PATH = "video_samples_turbodiffusion_14B"
 def main() -> None:
     # TurboDiffusion 14B: 1-4 step video generation using RCM scheduler + SLA attention
     # FastVideo will automatically use TurboDiffusionPipeline when specified
-    generator = VideoGenerator.from_pretrained(
-        "loayrashid/TurboWan2.1-T2V-14B-Diffusers",
-        # 14B model needs more GPUs
-        num_gpus=2,
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="loayrashid/TurboWan2.1-T2V-14B-Diffusers",
+            # 14B model needs more GPUs
+            engine=EngineConfig(num_gpus=2),
+        )
     )
 
     prompt = (
@@ -22,11 +27,12 @@ def main() -> None:
         "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,
-        seed=42,
+    video = generator.generate(
+        GenerationRequest(
+            prompt=prompt,
+            output=OutputConfig(output_path=OUTPUT_PATH, save_video=True),
+            sampling=SamplingConfig(seed=42),
+        )
     )
 
     # Generate another video with a different prompt, without reloading the model!
@@ -37,11 +43,12 @@ def main() -> None:
         "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,
-        seed=42,
+    video2 = generator.generate(
+        GenerationRequest(
+            prompt=prompt2,
+            output=OutputConfig(output_path=OUTPUT_PATH, save_video=True),
+            sampling=SamplingConfig(seed=42),
+        )
     )
 
 

examples/inference/basic/basic_turbodiffusion_i2v.py

@@ -4,6 +4,10 @@ import os
 os.environ["FASTVIDEO_ATTENTION_BACKEND"] = "SLA_ATTN"
 
 from fastvideo import VideoGenerator
+from fastvideo.api import (
+    EngineConfig, GenerationRequest, GeneratorConfig, InputConfig,
+    OutputConfig, SamplingConfig,
+)
 
 # Use local model path
 MODEL_PATH = "loayrashid/TurboWan2.2-I2V-A14B-Diffusers"
@@ -12,9 +16,11 @@ OUTPUT_PATH = "video_samples_turbodiffusion_i2v"
 
 def main() -> None:
     # TurboDiffusion I2V: 1-4 step image-to-video generation
-    generator = VideoGenerator.from_pretrained(
-        MODEL_PATH,
-        num_gpus=2,
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path=MODEL_PATH,
+            engine=EngineConfig(num_gpus=2),
+        )
     )
 
     # Example prompt and image for I2V
@@ -24,12 +30,13 @@ def main() -> None:
     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,
-        seed=42,
+    video = generator.generate(
+        GenerationRequest(
+            prompt=prompt,
+            inputs=InputConfig(image_path=image_path),
+            sampling=SamplingConfig(seed=42),
+            output=OutputConfig(output_path=OUTPUT_PATH, save_video=True),
+        )
     )
 
 

examples/inference/basic/basic_wan2_2.py

@@ -1,6 +1,8 @@
 from fastvideo import VideoGenerator
-
-# from fastvideo.api.sampling_param import SamplingParam
+from fastvideo.api import (
+    EngineConfig, GenerationRequest, GeneratorConfig, OffloadConfig,
+    OutputConfig, SamplingConfig,
+)
 
 OUTPUT_PATH = "video_samples_wan2_2_14B_t2v"
 def main():
@@ -8,30 +10,37 @@ def main():
     # model.
     # If a local path is provided, FastVideo will make a best effort
     # attempt to identify the optimal arguments.
-    generator = VideoGenerator.from_pretrained(
-        "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
-        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
-        pin_cpu_memory=True,
-        # image_encoder_cpu_offload=False,
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="Wan-AI/Wan2.2-T2V-A14B-Diffusers",
+            engine=EngineConfig(
+                # FastVideo will automatically handle distributed setup
+                num_gpus=2,
+                use_fsdp_inference=False,  # set to True if GPU is out of memory
+                offload=OffloadConfig(
+                    dit=True,  # DiT need to be offloaded for MoE
+                    vae=False,
+                    text_encoder=True,
+                    # Set pin_cpu_memory to false if CPU RAM is limited and there're no frequent CPU-GPU transfer
+                    pin_cpu_memory=True,
+                ),
+            ),
+        )
     )
 
-    # sampling_param = SamplingParam.from_pretrained("Wan-AI/Wan2.1-T2V-1.3B-Diffusers")
-    # 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)
-    # video = generator.generate_video(prompt, sampling_param=sampling_param, output_path="wan_t2v_videos/")
+    _ = generator.generate(
+        GenerationRequest(
+            prompt=prompt,
+            sampling=SamplingConfig(height=720, width=1280, num_frames=81),
+            output=OutputConfig(output_path=OUTPUT_PATH, save_video=True),
+        )
+    )
 
     # Generate another video with a different prompt, without reloading the
     # model!
@@ -41,8 +50,14 @@ def main():
         "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)
+    _ = generator.generate(
+        GenerationRequest(
+            prompt=prompt2,
+            sampling=SamplingConfig(height=720, width=1280, num_frames=81),
+            output=OutputConfig(output_path=OUTPUT_PATH, save_video=True),
+        )
+    )
 
 
 if __name__ == "__main__":
-    main()
+    main()

examples/inference/basic/basic_wan2_2_Fun.py

@@ -1,6 +1,12 @@
 from fastvideo import VideoGenerator
-
-# from fastvideo.api.sampling_param import SamplingParam
+from fastvideo.api import (
+    EngineConfig,
+    GenerationRequest,
+    GeneratorConfig,
+    InputConfig,
+    OffloadConfig,
+    OutputConfig,
+)
 
 OUTPUT_PATH = "video_samples_wan2_1_Fun"
 OUTPUT_NAME = "wan2.1_test"
@@ -9,18 +15,24 @@ def main():
     # model.
     # If a local path is provided, FastVideo will make a best effort
     # attempt to identify the optimal arguments.
-    generator = VideoGenerator.from_pretrained(
-        "IRMChen/Wan2.1-Fun-1.3B-Control-Diffusers",
-        # "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
-        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
-        pin_cpu_memory=True,
-        # image_encoder_cpu_offload=False,
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="IRMChen/Wan2.1-Fun-1.3B-Control-Diffusers",
+            # "alibaba-pai/Wan2.2-Fun-A14B-Control",
+            engine=EngineConfig(
+                # FastVideo will automatically handle distributed setup
+                num_gpus=1,
+                use_fsdp_inference=False, # set to True if GPU is out of memory
+                offload=OffloadConfig(
+                    dit=True, # DiT need to be offloaded for MoE
+                    vae=False,
+                    text_encoder=True,
+                    # Set pin_cpu_memory to false if CPU RAM is limited and there're no frequent CPU-GPU transfer
+                    pin_cpu_memory=True,
+                    # image_encoder=False,
+                ),
+            ),
+        )
     )
 
     prompt = "一位年轻女性穿着一件粉色的连衣裙，裙子上有白色的装饰和粉色的纽扣。她的头发是紫色的，头上戴着一个红色的大蝴蝶结，显得非常可爱和精致。她还戴着一个红色的领结，整体造型充满了少女感和活力。她的表情温柔，双手轻轻交叉放在身前，姿态优雅。背景是简单的灰色，没有任何多余的装饰，使得人物更加突出。她的妆容清淡自然，突显了她的清新气质。整体画面给人一种甜美、梦幻的感觉，仿佛置身于童话世界中。"
@@ -30,7 +42,14 @@ 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(
+        GenerationRequest(
+            prompt=prompt,
+            negative_prompt=negative_prompt,
+            inputs=InputConfig(image_path=image_path, video_path=control_video_path),
+            output=OutputConfig(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

@@ -1,6 +1,8 @@
 from fastvideo import VideoGenerator
-
-# from fastvideo.api.sampling_param import SamplingParam
+from fastvideo.api import (
+    EngineConfig, GenerationRequest, GeneratorConfig, InputConfig,
+    OffloadConfig, OutputConfig, SamplingConfig,
+)
 
 OUTPUT_PATH = "video_samples_wan2_2_14B_i2v"
 def main():
@@ -8,23 +10,36 @@ def main():
     # model.
     # If a local path is provided, FastVideo will make a best effort
     # attempt to identify the optimal arguments.
-    generator = VideoGenerator.from_pretrained(
-        "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
-        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
-        pin_cpu_memory=True,
-        # image_encoder_cpu_offload=False,
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="Wan-AI/Wan2.2-I2V-A14B-Diffusers",
+            # FastVideo will automatically handle distributed setup
+            engine=EngineConfig(
+                num_gpus=1,
+                use_fsdp_inference=False,  # set to True if GPU is out of memory
+                offload=OffloadConfig(
+                    dit=True,  # DiT need to be offloaded for MoE
+                    vae=False,
+                    text_encoder=True,
+                    # Set pin_cpu_memory to false if CPU RAM is limited and there're no frequent CPU-GPU transfer
+                    pin_cpu_memory=True,
+                    # image_encoder=False,
+                ),
+            ),
+        )
     )
 
     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(
+        GenerationRequest(
+            prompt=prompt,
+            inputs=InputConfig(image_path=image_path),
+            sampling=SamplingConfig(height=832, width=480, num_frames=81),
+            output=OutputConfig(output_path=OUTPUT_PATH, save_video=True),
+        )
+    )
 
 if __name__ == "__main__":
-    main()
+    main()

examples/inference/basic/basic_wan2_2_ti2v.py

@@ -1,4 +1,7 @@
 from fastvideo import VideoGenerator
+from fastvideo.api import (
+    EngineConfig, GenerationRequest, GeneratorConfig, InputConfig, OffloadConfig, OutputConfig,
+)
 
 OUTPUT_PATH = "video_samples_wan2_2_5B_ti2v"
 def main():
@@ -7,22 +10,34 @@ def main():
     # If a local path is provided, FastVideo will make a best effort
     # attempt to identify the optimal arguments.
     model_name = "Wan-AI/Wan2.2-TI2V-5B-Diffusers"
-    generator = VideoGenerator.from_pretrained(
-        model_name,
-        # 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,
-        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"
-        # image_encoder_cpu_offload=False,
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path=model_name,
+            engine=EngineConfig(
+                # FastVideo will automatically handle distributed setup
+                num_gpus=1,
+                use_fsdp_inference=False,  # set to True if GPU is out of memory
+                offload=OffloadConfig(
+                    dit=True,
+                    vae=False,
+                    text_encoder=True,
+                    pin_cpu_memory=True,  # set to false if low CPU RAM or hit obscure "CUDA error: Invalid argument"
+                    # image_encoder=False,
+                ),
+            ),
+        )
     )
 
     # I2V is triggered just by passing in an image_path argument
     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, output_path=OUTPUT_PATH, save_video=True, image_path=image_path)
+    video = generator.generate(
+        GenerationRequest(
+            prompt=prompt,
+            inputs=InputConfig(image_path=image_path),
+            output=OutputConfig(output_path=OUTPUT_PATH, save_video=True),
+        )
+    )
 
     # Generate another video with a different prompt, without reloading the
     # model!
@@ -34,8 +49,13 @@ def main():
         "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)
+    video2 = generator.generate(
+        GenerationRequest(
+            prompt=prompt2,
+            output=OutputConfig(output_path=OUTPUT_PATH, save_video=True),
+        )
+    )
 
 
 if __name__ == "__main__":
-    main()
+    main()

examples/inference/basic/v2_basic.py

@@ -1,36 +0,0 @@
-"""v2 port of basic.py — Wan2.1-T2V-1.3B through the v2 VideoGenerator.
-
-Same convenience API as upstream (from_pretrained + generate_video); only delta is importing
-VideoGenerator from v2. v2 bring-up: single-GPU, resident, SDPA; modest res/frames for a quick run.
-"""
-from v2 import VideoGenerator
-
-OUTPUT_PATH = "v2_video_samples"
-
-
-def main() -> None:
-    generator = VideoGenerator.from_pretrained(
-        "Wan-AI/Wan2.1-T2V-1.3B-Diffusers",
-        num_gpus=1,
-        use_fsdp_inference=False,
-        dit_cpu_offload=False,
-        vae_cpu_offload=False,
-        text_encoder_cpu_offload=False,
-        pin_cpu_memory=False,
-    )
-    common = dict(output_path=OUTPUT_PATH, save_video=True,
-                  num_frames=25, height=480, width=832, num_inference_steps=30, guidance_scale=5.0)
-
-    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_video_name="wan21_raccoon", **common)
-
-    prompt2 = ("A majestic lion strides across the golden savanna, its powerful frame glistening under "
-               "the warm afternoon sun. Low angle, steady tracking shot, cinematic.")
-    video2 = generator.generate_video(prompt2, output_video_name="wan21_lion", **common)
-    print(f"Outputs: {video.video_path} , {video2.video_path}")
-
-
-if __name__ == "__main__":
-    main()

examples/inference/basic/v2_basic_ltx2.py

@@ -1,29 +0,0 @@
-"""v2 port of basic_ltx2.py — LTX-2 base (single-stage) through the v2 VideoGenerator.
-
-Same convenience API as upstream; only delta is importing VideoGenerator from v2. LTX-2 base is the
-single-stage (non-distilled) model: the v2 single-stage card (build_ltx2_base_card) runs a request-driven
-many-step flow-match at FULL latent res (no distilled base/refine split, no spatial upsampler), reusing
-the LTX-2 DiT/VAE/Gemma adapters. The SAME single-stage card also serves LTX-2.3-Distilled (which is also
-single-stage) — just pass fewer num_inference_steps for the few-step distilled schedule.
-
-NOTE: modest res/frames here — upstream defaults to 1088x1920x121, which on an 18.88B base is very slow;
-raise them for full quality. v2 bring-up: single-GPU, resident, SDPA.
-"""
-from v2 import VideoGenerator
-
-PROMPT = ("A warm sunny backyard, cinematic close-up of two people talking; the camera slowly pans right "
-          "to reveal a grandfather in the garden wearing enormous butterfly wings, flapping his arms like "
-          "he is trying to take off. Deadpan, absurd, quietly tragic.")
-
-
-def main() -> None:
-    generator = VideoGenerator.from_pretrained("Davids048/LTX2-Base-Diffusers", num_gpus=1)
-    video = generator.generate_video(
-        prompt=PROMPT, output_path="v2_video_samples_ltx2_base", output_video_name="ltx2_base_backyard",
-        save_video=True, num_frames=25, height=512, width=768, num_inference_steps=30)
-    print(f"Output: {video.video_path}")
-    generator.shutdown()
-
-
-if __name__ == "__main__":
-    main()

examples/inference/basic/v2_basic_ltx2_3_distilled.py

@@ -1,36 +0,0 @@
-"""v2 port of basic_ltx2_3_distilled.py — LTX-2.3 Distilled (single-stage, joint A/V) through the v2
-VideoGenerator.
-
-Unlike LTX-2.0 distilled (two-stage, video-only), LTX-2.3 is a single-stage *audio+video* model. The
-shared registry (v2/registry.py) maps ``FastVideo/LTX-2.3-Distilled-Diffusers`` to its OWN card,
-``build_ltx2_3_card`` — distinct from the LTX-2 base/2-stage cards — which wires the 2.3-specific path:
-  * SEPARATE video + audio text connectors (the Gemma encoder projects the prompt to two embeddings,
-    2048-dim for audio, 4096-dim for video) plus gated attention;
-  * a JOINT DiT forward where video and audio latents cross-attend in a single denoise per step;
-  * a video VAE decode + an AudioDecoder→Vocoder decode → video frames AND a stereo waveform @24kHz.
-
-Because the model advertises TEXT_TO_VIDEO_SOUND, the VideoGenerator issues a T2VS request by default,
-so ``generate_video`` returns BOTH modalities: the mp4 plus a sibling ``.wav`` (and ``result.audio`` /
-``result.audio_sample_rate`` in memory). Being distilled, it wants FEW steps (8). GPU-verified on the
-rebuilt x86 stack: video (3,33,256,384) + stereo audio (2×61920 @ 24kHz).
-"""
-from v2 import VideoGenerator
-
-PROMPT = "ocean waves crashing on rocks at sunset, seagulls calling in the distance, cinematic, highly detailed"
-
-
-def main() -> None:
-    generator = VideoGenerator.from_pretrained("FastVideo/LTX-2.3-Distilled-Diffusers", num_gpus=1)
-    # audio=None auto-enables sound for this A/V model (pass audio=False to force video-only).
-    result = generator.generate_video(
-        prompt=PROMPT, output_path="v2_video_samples_ltx2_3", output_video_name="ltx2_3_ocean",
-        save_video=True, num_frames=33, height=512, width=768, num_inference_steps=8, seed=1)
-    print(f"Video: {result.video_path}")
-    audio_path = result.extra.get("audio_path")
-    if audio_path:
-        print(f"Audio: {audio_path}  ({result.audio_sample_rate} Hz)")
-    generator.shutdown()
-
-
-if __name__ == "__main__":
-    main()

examples/inference/basic/v2_basic_new_api.py

@@ -1,87 +0,0 @@
-"""v2 typed-API inference example — mirrors ``basic_dmd_new_api.py`` but drives the **v2
-(recipe, runtime) substrate + real torch backend** for the three models brought up on GPU
-(Wan2.1, SF-causal Wan, LTX-2).
-
-The ONLY delta from the upstream example is importing ``VideoGenerator`` from ``v2`` instead of
-``fastvideo`` — the typed config classes are the SAME ``fastvideo.api`` dataclasses.
-
-Run (on a GPU box, with the v2 venv active):
-    python examples/inference/basic/v2_basic_new_api.py
-
-Notes vs upstream: the v2 bring-up runs single-GPU, resident, on the TORCH_SDPA backend (no
-fastvideo-kernel / VSA), so resolutions/steps are modest here for a quick runnable demo. LTX-2 loads
-an 18.88B DiT (slow first load).
-"""
-import os
-import time
-
-from v2 import VideoGenerator
-from fastvideo.api import (
-    EngineConfig,
-    GenerationRequest,
-    GeneratorConfig,
-    OffloadConfig,
-    OutputConfig,
-    SamplingConfig,
-)
-
-OUTPUT_PATH = "v2_video_samples"
-
-MODELS = [
-    {
-        "family": "wan21",
-        "model_path": "Wan-AI/Wan2.1-T2V-1.3B-Diffusers",
-        "prompt": "a red panda surfing on ocean waves at sunset, cinematic, highly detailed",
-        "sampling": SamplingConfig(num_frames=25, height=480, width=832,
-                                   num_inference_steps=30, guidance_scale=5.0, seed=1, fps=16),
-    },
-    {
-        "family": "wan_causal",
-        "model_path": "wlsaidhi/SFWan2.1-T2V-1.3B-Diffusers",
-        "prompt": "a cat walking through a sunlit garden, cinematic",
-        "sampling": SamplingConfig(num_frames=25, height=480, width=832,
-                                   num_inference_steps=4, guidance_scale=5.0, seed=1, fps=16),
-    },
-    {
-        "family": "ltx2",
-        "model_path": "FastVideo/LTX2-Distilled-Diffusers",
-        "prompt": "surfers riding ocean waves at sunset, cinematic, highly detailed",
-        "sampling": SamplingConfig(num_frames=9, height=512, width=768,
-                                   num_inference_steps=8, guidance_scale=1.0, seed=1, fps=16),
-    },
-]
-
-
-def run_one(m: dict) -> None:
-    generator_config = GeneratorConfig(
-        model_path=m["model_path"],
-        engine=EngineConfig(
-            num_gpus=1,
-            use_fsdp_inference=False,
-            offload=OffloadConfig(text_encoder=False, dit=False, vae=False, pin_cpu_memory=False),
-        ),
-    )
-    load_start = time.perf_counter()
-    generator = VideoGenerator.from_config(generator_config)
-    load_time = time.perf_counter() - load_start
-
-    request = GenerationRequest(
-        prompt=m["prompt"],
-        sampling=m["sampling"],
-        output=OutputConfig(output_path=OUTPUT_PATH, output_video_name=f"v2_{m['family']}",
-                            save_video=True, return_frames=False),
-    )
-    gen_start = time.perf_counter()
-    result = generator.generate(request)
-    gen_time = time.perf_counter() - gen_start
-
-    print(f"[{m['family']:10s}] load={load_time:6.1f}s  gen={gen_time:6.1f}s  -> {result.video_path}")
-
-
-def main() -> None:
-    for m in MODELS:
-        run_one(m)
-
-
-if __name__ == "__main__":
-    main()

examples/inference/basic/v2_basic_self_forcing_causal.py

@@ -1,30 +0,0 @@
-"""v2 port of basic_self_forcing_causal.py — SF-causal Wan2.1 (CausalWanTransformer3DModel) through
-the v2 VideoGenerator (chunk_rollout loop).
-
-Same convenience API as upstream; only delta is importing VideoGenerator from v2. NOTE: the v2 causal
-loop runs per-chunk few-step (not the upstream kv-cache streaming + SF schedule), so output is coherent
-but lower-fidelity (a documented gap). num_frames is set by the card's chunk schedule; height/width
-drive the latent geometry.
-"""
-from v2 import VideoGenerator
-from fastvideo.api.sampling_param import SamplingParam
-
-OUTPUT_PATH = "v2_video_samples_causal"
-
-
-def main() -> None:
-    model_name = "wlsaidhi/SFWan2.1-T2V-1.3B-Diffusers"
-    generator = VideoGenerator.from_pretrained(
-        model_name, num_gpus=1, 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.")
-    video = generator.generate_video(prompt, output_path=OUTPUT_PATH, output_video_name="causal_raccoon",
-                                     save_video=True, sampling_param=sampling_param, height=480, width=832)
-    print(f"Output: {video.video_path}")
-
-
-if __name__ == "__main__":
-    main()

examples/inference/basic/v2_basic_wan2_2.py

@@ -1,40 +0,0 @@
-"""v2 port of basic_wan2_2.py — Wan2.2-T2V-A14B (MoE) through the v2 VideoGenerator.
-
-Same convenience API as upstream; only delta is importing VideoGenerator from v2. A14B is a 2-expert
-MoE: WanTransformer3DModel x2 (in_ch=16, Wan2.1 geometry) with a boundary-timestep switch
-(boundary_ratio 0.875) — ported via build_wan22_a14b_card (BoundaryTimestepRouting: transformer =
-high-noise expert, transformer_2 = low-noise), reusing the Wan adapters for both experts.
-
-NOTE: upstream runs A14B with num_gpus=2 + dit_cpu_offload=True ("DiT need to be offloaded for MoE").
-The v2 bring-up is single-GPU + resident (no offload), so the two 14B experts (~56GB bf16) + UMT5 are
-near an 80GB GPU's limit — this example uses reduced res/frames to fit. If it OOMs, the A14B card is
-still correct; it just needs the (not-yet-ported) MoE DiT CPU offload. See V2_PORTING_STATUS.md.
-"""
-from v2 import VideoGenerator
-
-OUTPUT_PATH = "v2_video_samples_wan2_2_14B_t2v"
-
-
-def main() -> None:
-    generator = VideoGenerator.from_pretrained(
-        "Wan-AI/Wan2.2-T2V-A14B-Diffusers",
-        num_gpus=1,
-        use_fsdp_inference=False,
-        dit_cpu_offload=False,
-        vae_cpu_offload=False,
-        text_encoder_cpu_offload=False,
-        pin_cpu_memory=False,
-    )
-
-    prompt = ("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. Low angle, steady "
-              "tracking shot, cinematic.")
-    # Reduced res/frames so the two resident 14B experts fit a single 80GB GPU (upstream: 720x1280x81).
-    video = generator.generate_video(prompt, output_path=OUTPUT_PATH, output_video_name="wan22_a14b_lion",
-                                     save_video=True, num_frames=17, height=480, width=832,
-                                     num_inference_steps=20, guidance_scale=5.0)
-    print(f"Output: {video.video_path}")
-
-
-if __name__ == "__main__":
-    main()

examples/inference/basic/v2_basic_wan2_2_ti2v.py

@@ -1,38 +0,0 @@
-"""v2 port of basic_wan2_2_ti2v.py — Wan2.2-TI2V-5B (T2V mode) through the v2 VideoGenerator.
-
-Same convenience API as upstream (from_pretrained + generate_video); only delta is importing
-VideoGenerator from v2. Wan2.2-TI2V-5B reuses the Wan adapter classes (WanTransformer3DModel /
-AutoencoderKLWan / UMT5) with the higher-compression VAE geometry (z_dim=48, 16x spatial, 4x temporal).
-
-NOTE: upstream also runs I2V (image_path=...). The v2 program here is T2V-only (image conditioning is
-not yet ported), so this mirrors the upstream *T2V* branch (prompt2). Modest res/frames for a quick run.
-"""
-from v2 import VideoGenerator
-
-OUTPUT_PATH = "v2_video_samples_wan2_2_5B_ti2v"
-
-
-def main() -> None:
-    model_name = "Wan-AI/Wan2.2-TI2V-5B-Diffusers"
-    generator = VideoGenerator.from_pretrained(
-        model_name,
-        num_gpus=1,
-        use_fsdp_inference=False,
-        dit_cpu_offload=False,
-        vae_cpu_offload=False,
-        text_encoder_cpu_offload=False,
-        pin_cpu_memory=False,
-    )
-
-    # T2V mode (the v2 program is text-to-video; upstream's image_path I2V branch is not ported yet).
-    prompt = ("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. Low angle, steady tracking shot, cinematic.")
-    video = generator.generate_video(prompt, output_path=OUTPUT_PATH, output_video_name="wan22_ti2v_lion",
-                                     save_video=True, num_frames=25, height=448, width=768,
-                                     num_inference_steps=20, guidance_scale=5.0)
-    print(f"Output: {video.video_path}")
-
-
-if __name__ == "__main__":
-    main()

examples/inference/eval/all_metrics_demo.py

@@ -50,23 +50,33 @@ N_DUP = 4  # how many times to duplicate the video for the gen/ref corpora
 def generate_one_ltx2_video() -> str:
     os.environ.setdefault("FASTVIDEO_ATTENTION_BACKEND", "FLASH_ATTN")
     from fastvideo import VideoGenerator
+    from fastvideo.api import (EngineConfig, GenerationRequest, GeneratorConfig,
+                               OutputConfig, SamplingConfig)
 
     Path(OUTPUT_PATH).parent.mkdir(parents=True, exist_ok=True)
     # Davids048/LTX2-Base-Diffusers is the audio-capable LTX-2 checkpoint
     # (the Distilled variant ships without the audio VAE, so its mp4
     # audio track is silence/noise — unusable for audio.* metrics).
-    generator = VideoGenerator.from_pretrained(
-        "Davids048/LTX2-Base-Diffusers",
-        num_gpus=1,
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="Davids048/LTX2-Base-Diffusers",
+            engine=EngineConfig(num_gpus=1),
+        )
     )
-    generator.generate_video(
-        prompt=PROMPT,
-        output_path=OUTPUT_PATH,
-        save_video=True,
-        num_frames=121,  # ~5s @ 24 fps — long enough for audio.desync (Synchformer ≥14 segments)
-        height=480,
-        width=832,
-        fps=24,
+    generator.generate(
+        GenerationRequest(
+            prompt=PROMPT,
+            sampling=SamplingConfig(
+                num_frames=121,  # ~5s @ 24 fps — long enough for audio.desync (Synchformer ≥14 segments)
+                height=480,
+                width=832,
+                fps=24,
+            ),
+            output=OutputConfig(
+                output_path=OUTPUT_PATH,
+                save_video=True,
+            ),
+        )
     )
     generator.shutdown()
     torch.cuda.empty_cache()

examples/inference/eval/basic_ltx2_audio_eval.py

@@ -21,6 +21,10 @@ Install: ``uv pip install -e .[eval-audio]`` covers both metrics here
 import torch
 
 from fastvideo import VideoGenerator
+from fastvideo.api import (
+    EngineConfig, GenerationRequest, GeneratorConfig, OutputConfig,
+    SamplingConfig,
+)
 from fastvideo.eval import create_evaluator
 
 PROMPT = (
@@ -39,20 +43,26 @@ METRICS = [
 
 
 def main() -> None:
-    generator = VideoGenerator.from_pretrained(
-        "Davids048/LTX2-Base-Diffusers",
-        num_gpus=1,
-    )
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="Davids048/LTX2-Base-Diffusers",
+            engine=EngineConfig(num_gpus=1),
+        ))
 
     output_path = "outputs_video/ltx2_audio_eval/output.mp4"
-    generator.generate_video(
-        prompt=PROMPT,
-        output_path=output_path,
-        save_video=True,
-        num_frames=121,
-        height=1088,
-        width=1920,
-    )
+    generator.generate(
+        GenerationRequest(
+            prompt=PROMPT,
+            sampling=SamplingConfig(
+                num_frames=121,
+                height=1088,
+                width=1920,
+            ),
+            output=OutputConfig(
+                output_path=output_path,
+                save_video=True,
+            ),
+        ))
     generator.shutdown()
     torch.cuda.empty_cache()
 

examples/inference/eval/basic_ltx2_eval.py

@@ -22,6 +22,10 @@ sharing, or run on a smaller-resolution generation.
 import torch
 
 from fastvideo import VideoGenerator
+from fastvideo.api import (
+    EngineConfig, GenerationRequest, GeneratorConfig, OutputConfig,
+    SamplingConfig,
+)
 from fastvideo.eval import Evaluator
 from fastvideo.eval.io import build_eval_kwargs
 
@@ -58,19 +62,20 @@ METRICS = [
 
 def main() -> None:
     # ----- generation (matches examples/inference/basic/basic_ltx2.py) -----
-    generator = VideoGenerator.from_pretrained(
-        "Davids048/LTX2-Base-Diffusers",
-        num_gpus=1,
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="Davids048/LTX2-Base-Diffusers",
+            engine=EngineConfig(num_gpus=1),
+        )
     )
 
     output_path = "outputs_video/ltx2_basic/output_ltx2_base_t2v_1088_1920_1.1.mp4"
-    generator.generate_video(
-        prompt=PROMPT,
-        output_path=output_path,
-        save_video=True,
-        num_frames=121,
-        height=1088,
-        width=1920,
+    generator.generate(
+        GenerationRequest(
+            prompt=PROMPT,
+            output=OutputConfig(output_path=output_path, save_video=True),
+            sampling=SamplingConfig(num_frames=121, height=1088, width=1920),
+        )
     )
     generator.shutdown()
     # Free residual CUDA memory the generator left behind so the

examples/inference/eval/bench_physics_iq.py

@@ -45,6 +45,9 @@ 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
+    from fastvideo.api import (
+        EngineConfig, GenerationRequest, GeneratorConfig, OutputConfig, SamplingConfig,
+    )
 
     videos_dir.mkdir(parents=True, exist_ok=True)
     todo = [(row, videos_dir / _expected_filename(row)) for row in rows]
@@ -55,13 +58,16 @@ def _generate_videos(rows: list[dict], videos_dir: Path,
 
     print(f"[gen] {len(todo)}/{len(rows)} scenarios to render with {model} "
           f"({num_frames}x{height}x{width})...")
-    gen = VideoGenerator.from_pretrained(model, num_gpus=num_gpus)
+    gen = VideoGenerator.from_config(GeneratorConfig(
+        model_path=model, engine=EngineConfig(num_gpus=num_gpus),
+    ))
     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,
-            )
+            gen.generate(GenerationRequest(
+                prompt=row["prompt"],
+                sampling=SamplingConfig(num_frames=num_frames, height=height, width=width),
+                output=OutputConfig(output_path=str(out_path), save_video=True),
+            ))
     finally:
         gen.shutdown()
 

examples/inference/eval/bench_vbench.py

@@ -43,6 +43,8 @@ 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
+    from fastvideo.api import (EngineConfig, GenerationRequest, GeneratorConfig,
+                               OutputConfig, SamplingConfig)
 
     videos_dir.mkdir(parents=True, exist_ok=True)
     todo = [(p, videos_dir / f"{_slugify(p)}.mp4") for p in prompts]
@@ -53,13 +55,15 @@ def _generate_videos(prompts: list[str], videos_dir: Path,
 
     print(f"[gen] {len(todo)}/{len(prompts)} prompts to render with {model} "
           f"({num_frames}x{height}x{width})...")
-    gen = VideoGenerator.from_pretrained(model, num_gpus=num_gpus)
+    gen = VideoGenerator.from_config(GeneratorConfig(
+        model_path=model, engine=EngineConfig(num_gpus=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,
-            )
+            gen.generate(GenerationRequest(
+                prompt=prompt,
+                sampling=SamplingConfig(num_frames=num_frames, height=height, width=width),
+                output=OutputConfig(output_path=str(out_path), save_video=True),
+            ))
     finally:
         gen.shutdown()
 

examples/inference/eval/eval_ltx2_vbench.py

@@ -33,6 +33,13 @@ import json
 from pathlib import Path
 
 from fastvideo import VideoGenerator
+from fastvideo.api import (
+    EngineConfig,
+    GenerationRequest,
+    GeneratorConfig,
+    OutputConfig,
+    SamplingConfig,
+)
 from fastvideo.eval import create_evaluator
 from fastvideo.eval.io import load_video
 
@@ -99,16 +106,27 @@ def generate(args: argparse.Namespace) -> Path:
     out.parent.mkdir(parents=True, exist_ok=True)
 
     print(f"[gen] loading {args.model} ({args.num_gpus} GPU)...")
-    generator = VideoGenerator.from_pretrained(args.model, num_gpus=args.num_gpus)
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path=args.model,
+            engine=EngineConfig(num_gpus=args.num_gpus),
+        )
+    )
     try:
         print(f"[gen] generating to {out}...")
-        generator.generate_video(
-            prompt=args.prompt,
-            output_path=str(out),
-            save_video=True,
-            num_frames=args.num_frames,
-            height=args.height,
-            width=args.width,
+        generator.generate(
+            GenerationRequest(
+                prompt=args.prompt,
+                sampling=SamplingConfig(
+                    num_frames=args.num_frames,
+                    height=args.height,
+                    width=args.width,
+                ),
+                output=OutputConfig(
+                    output_path=str(out),
+                    save_video=True,
+                ),
+            )
         )
     finally:
         generator.shutdown()

examples/inference/gradio/local/README.md

@@ -33,7 +33,7 @@ This demo initializes a `VideoGenerator` with the minimum required arguments for
 
 The core functionality is in the `generate_video` function, which:
 1. Processes user inputs
-2. Uses the FastVideo VideoGenerator from earlier to run inference (`generator.generate_video()`)
+2. Uses the FastVideo VideoGenerator from earlier to run inference (`generator.generate(GenerationRequest(...))`)
 
 ## Gradio Interface
 

examples/inference/gradio/local/gradio_local_demo.py

@@ -5,7 +5,13 @@ import time
 
 import gradio as gr
 from fastvideo.entrypoints.video_generator import VideoGenerator
-from fastvideo.api.sampling_param import SamplingParam
+from fastvideo.api import (
+    GenerationRequest,
+    GeneratorConfig,
+    OutputConfig,
+    SamplingConfig,
+    SamplingParam,
+)
 from copy import deepcopy
 
 
@@ -129,9 +135,22 @@ 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(
+                GenerationRequest(
+                    prompt=prompt,
+                    negative_prompt=params.negative_prompt,
+                    sampling=SamplingConfig(
+                        seed=int(params.seed),
+                        guidance_scale=params.guidance_scale,
+                        num_frames=int(params.num_frames),
+                        height=int(params.height),
+                        width=int(params.width),
+                    ),
+                    output=OutputConfig(save_video=True, return_frames=False),
+                )
+            )
             inference_time = time.time() - start_time
-            logging_info = result.get("logging_info", None)
+            logging_info = result.logging_info
             if logging_info:
                 stage_names = logging_info.get_execution_order()
                 stage_execution_times = [
@@ -550,7 +569,7 @@ def main():
     for model_path in model_paths:
         print(f"Loading model: {model_path}")
         setup_model_environment(model_path)
-        generators[model_path] = VideoGenerator.from_pretrained(model_path)
+        generators[model_path] = VideoGenerator.from_config(GeneratorConfig(model_path=model_path))
         default_params[model_path] = SamplingParam.from_pretrained(model_path)
     demo = create_gradio_interface(default_params, generators)
     print(f"Starting Gradio frontend at http://{args.host}:{args.port}")

examples/inference/gradio/local/gradio_local_demo_ltx2_3/README.md

@@ -55,10 +55,11 @@ demo can actually boot:
    `fastvideo/fastvideo_args.py` currently wires only `ltx2_vae_tiling`.
    The backing stages (`ltx2_refine.py`, `ltx2_i2v_conditioning.py`) are
    also missing from `fastvideo/pipelines/stages/`.
-3. **`fastvideo.configs.sample.base.SamplingParam`** — the import path used
-   by this demo. Upstream moved sampling params to
-   `fastvideo.api.sampling_param`. A re-export shim at the old path, or an
-   import update here once the other two prereqs land, will resolve it.
+3. **`SamplingParam`** — now imported from `fastvideo.api` (the public
+   re-export of `fastvideo.api.sampling_param`); the old
+   `fastvideo.configs.sample.base` path was removed upstream. `SamplingParam`
+   here only sources model-default slider values — generation itself runs
+   through the typed `GenerationRequest` / `generator.generate(...)` path.
 
 ## Environment variables
 

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

@@ -4,8 +4,16 @@ from pathlib import Path
 
 import gradio as gr
 
+from fastvideo.api import (
+    CompileConfig,
+    ComponentConfig,
+    EngineConfig,
+    GeneratorConfig,
+    OffloadConfig,
+    PipelineSelection,
+    SamplingParam,
+)
 from fastvideo.configs.pipelines.base import PipelineConfig
-from fastvideo.configs.sample.base import SamplingParam
 from fastvideo.entrypoints.video_generator import VideoGenerator
 from fastvideo.layers.quantization.fp4_config import FP4Config
 from fastvideo.utils import maybe_download_model
@@ -48,28 +56,44 @@ def main():
         refine_upsampler_path = resolve_refine_upsampler_path(resolved_model_path)
         print(f"Using refine upsampler: {refine_upsampler_path}")
 
-        generators[model_path] = VideoGenerator.from_pretrained(
-            str(resolved_model_path),
-            num_gpus=1,
-            ltx2_refine_enabled=True,
-            ltx2_refine_upsampler_path=str(refine_upsampler_path),
-            ltx2_refine_lora_path="",  # disable refine LoRA for distilled model
-            ltx2_refine_num_inference_steps=2,
-            ltx2_refine_guidance_scale=1.0,
-            ltx2_refine_add_noise=True,
-            pipeline_config=pipeline_config,
-            enable_torch_compile=True,
-            enable_torch_compile_text_encoder=True,
-            torch_compile_kwargs={
-                "backend": "inductor",
-                "fullgraph": True,
-                "mode": "max-autotune-no-cudagraphs",
-                "dynamic": False,
-            },
-            dit_cpu_offload=False,
-            vae_cpu_offload=False,
-            text_encoder_cpu_offload=False,
-            ltx2_vae_tiling=False,
+        generators[model_path] = VideoGenerator.from_config(
+            GeneratorConfig(
+                model_path=str(resolved_model_path),
+                engine=EngineConfig(
+                    num_gpus=1,
+                    offload=OffloadConfig(
+                        dit=False,
+                        vae=False,
+                        text_encoder=False,
+                    ),
+                    compile=CompileConfig(
+                        enabled=True,
+                        text_encoder_enabled=True,
+                        backend="inductor",
+                        fullgraph=True,
+                        mode="max-autotune-no-cudagraphs",
+                        dynamic=False,
+                    ),
+                ),
+                pipeline=PipelineSelection(
+                    components=ComponentConfig(
+                        upsampler_weights=str(refine_upsampler_path),
+                        # Empty refine LoRA path (distilled needs none) -> omit.
+                    ),
+                    vae_tiling=False,
+                    preset_overrides={
+                        "refine": {
+                            "enabled": True,
+                            "num_inference_steps": 2,
+                            "guidance_scale": 1.0,
+                            "add_noise": True,
+                        },
+                    },
+                    # PipelineConfig object (with FP4 quant wired on above) has
+                    # no first-class typed field; route via experimental.
+                    experimental={"pipeline_config": pipeline_config},
+                ),
+            )
         )
         default_params[model_path] = apply_ltx2_defaults(
             SamplingParam.from_pretrained(str(resolved_model_path))

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

@@ -4,7 +4,7 @@ from pathlib import Path
 import torch
 import torch._inductor.config
 
-from fastvideo.configs.sample.base import SamplingParam
+from fastvideo.api import SamplingParam
 
 LOCAL_DEMO_DIR = Path(__file__).resolve().parent
 CLASSIFIER_DIR = Path(

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

@@ -5,8 +5,14 @@ from copy import deepcopy
 
 import gradio as gr
 
-from fastvideo.configs.sample.base import SamplingParam
-from fastvideo.entrypoints.video_generator import VideoGenerator
+from fastvideo import VideoGenerator
+from fastvideo.api import (
+    GenerationRequest,
+    InputConfig,
+    OutputConfig,
+    SamplingConfig,
+    SamplingParam,
+)
 
 from .config import (
     DEFAULT_FPS,
@@ -69,40 +75,38 @@ def create_gradio_interface(default_params: dict[str, SamplingParam], generators
             output_path = str(OUTPUT_DIR / video_filename)
             params.output_path = output_path
             start_time = time.perf_counter()
-            result = generator.generate_video(
-                prompt=prompt,
-                output_path=output_path,
-                fps=DEFAULT_FPS,
-                seed=int(params.seed),
-                save_video=True,
-                return_frames=False,
-                guidance_scale=float(params.guidance_scale),
-                height=int(params.height),
-                width=int(params.width),
-                num_frames=int(params.num_frames),
-                num_inference_steps=DEFAULT_NUM_INFERENCE_STEPS,
-                negative_prompt=params.negative_prompt,
-                image_path=params.image_path,
-                ltx2_image_crf=0.0
+            result = generator.generate(
+                GenerationRequest(
+                    prompt=prompt,
+                    negative_prompt=params.negative_prompt,
+                    inputs=InputConfig(image_path=params.image_path),
+                    sampling=SamplingConfig(
+                        seed=int(params.seed),
+                        fps=DEFAULT_FPS,
+                        guidance_scale=float(params.guidance_scale),
+                        height=int(params.height),
+                        width=int(params.width),
+                        num_frames=int(params.num_frames),
+                        num_inference_steps=DEFAULT_NUM_INFERENCE_STEPS,
+                    ),
+                    output=OutputConfig(
+                        output_path=output_path,
+                        save_video=True,
+                        return_frames=False,
+                    ),
+                    # LTX-2 i2v knob without a first-class typed field yet.
+                    extensions={"ltx2_image_crf": 0.0},
+                )
             )
             wall_time = time.perf_counter() - start_time
-            generation_time = (
-                result.get("generation_time")
-                if isinstance(result, dict) else None
-            )
-            e2e_latency = (
-                result.get("e2e_latency")
-                if isinstance(result, dict) else None
-            )
+            generation_time = result.generation_time
+            e2e_latency = result.extra.get("e2e_latency")
             if generation_time is None:
                 generation_time = wall_time
             if e2e_latency is None:
                 e2e_latency = wall_time
-            resolved_output_path = (
-                result.get("output_path", output_path)
-                if isinstance(result, dict) else output_path
-            )
-            logging_info = result.get("logging_info", None) if isinstance(result, dict) else None
+            resolved_output_path = result.video_path or output_path
+            logging_info = result.logging_info
             if logging_info:
                 stage_names = logging_info.get_execution_order()
                 stage_execution_times = [

examples/inference/gradio/local/gradio_local_demo_matrixgame2.py

@@ -9,6 +9,7 @@ import uvicorn
 from fastapi import FastAPI, Request, HTTPException
 from fastapi.responses import HTMLResponse, FileResponse
 
+from fastvideo.api import EngineConfig, GeneratorConfig, OffloadConfig
 from fastvideo.entrypoints.streaming_generator import StreamingVideoGenerator
 from fastvideo.models.dits.matrixgame2.utils import expand_action_to_frames
 
@@ -572,14 +573,20 @@ def main():
     
     print(f"Loading model: {model_path}")
     setup_model_environment(model_path)
-    generator = StreamingVideoGenerator.from_pretrained(
-        model_path,
-        num_gpus=1,
-        use_fsdp_inference=True,
-        dit_cpu_offload=True,
-        vae_cpu_offload=False,
-        text_encoder_cpu_offload=True,
-        pin_cpu_memory=True,
+    generator = StreamingVideoGenerator.from_config(
+        GeneratorConfig(
+            model_path=model_path,
+            engine=EngineConfig(
+                num_gpus=1,
+                use_fsdp_inference=True,
+                offload=OffloadConfig(
+                    dit=True,
+                    vae=False,
+                    text_encoder=True,
+                    pin_cpu_memory=True,
+                ),
+            ),
+        )
     )
     
     generators = {model_path: generator}

examples/inference/gradio/serving/ray_serve_backend.py

@@ -3,7 +3,6 @@ import os
 import torch
 import base64
 import io
-from copy import deepcopy
 from typing import Dict, Any, Optional, List
 import signal
 import sys
@@ -20,6 +19,17 @@ import imageio
 from ray.serve.handle import DeploymentHandle
 from prometheus_client import Counter, Histogram, generate_latest
 
+from fastvideo.api import (
+    EngineConfig,
+    GenerationRequest,
+    GeneratorConfig,
+    InputConfig,
+    OffloadConfig,
+    OutputConfig,
+    PipelineSelection,
+    SamplingConfig,
+)
+
 NUM_GPUS = 16
 DEFAULT_FPS = 16
 SEED_RANGE_MAX = 1_000_000
@@ -136,10 +146,10 @@ def setup_model_environment(model_path: str) -> None:
 
 
 def process_generation_result(result: Any) -> tuple[List[np.ndarray], float, List[str], List[float]]:
-    frames = result if isinstance(result, list) else result.get("frames", [])
-    generation_time = result.get("generation_time", 0.0) if isinstance(result, dict) else 0.0
-    
-    logging_info = result.get("logging_info", None)
+    frames = result.frames or []
+    generation_time = result.generation_time or 0.0
+
+    logging_info = result.logging_info
     if logging_info:
         stage_names = logging_info.get_execution_order()
         stage_execution_times = [
@@ -153,24 +163,29 @@ def process_generation_result(result: Any) -> tuple[List[np.ndarray], float, Lis
     return frames, generation_time, stage_names, stage_execution_times
 
 
-def prepare_sampling_params(video_request: VideoGenerationRequest, default_params: Any) -> Any:
-    params = deepcopy(default_params)
-    params.prompt = video_request.prompt
-    
-    if video_request.use_negative_prompt:
-        params.negative_prompt = video_request.negative_prompt
+def prepare_generation_request(video_request: VideoGenerationRequest, image_path: Optional[str] = None) -> Any:
+    seed = (video_request.seed if not video_request.randomize_seed
+            else torch.randint(0, SEED_RANGE_MAX, (1,)).item())
 
-    params.seed = (video_request.seed if not video_request.randomize_seed 
-                  else torch.randint(0, SEED_RANGE_MAX, (1,)).item())
-    params.randomize_seed = video_request.randomize_seed
-    params.guidance_scale = video_request.guidance_scale
-    params.num_frames = video_request.num_frames
-    params.height = video_request.height
-    params.width = video_request.width
-    params.save_video = False
-    params.return_frames = True
-    
-    return params
+    # "" explicitly clears the model preset's negative prompt (None would
+    # inherit it, changing this demo's long-standing behavior).
+    negative_prompt = video_request.negative_prompt if video_request.use_negative_prompt else ""
+
+    request = GenerationRequest(
+        prompt=video_request.prompt,
+        negative_prompt=negative_prompt,
+        inputs=InputConfig(image_path=image_path),
+        sampling=SamplingConfig(
+            seed=seed,
+            guidance_scale=video_request.guidance_scale,
+            num_frames=video_request.num_frames,
+            height=video_request.height,
+            width=video_request.width,
+        ),
+        output=OutputConfig(save_video=False, return_frames=True),
+    )
+
+    return request, seed
 
 
 class BaseModelDeployment:
@@ -185,31 +200,34 @@ class BaseModelDeployment:
 
     def _initialize_generator(self, config: Dict[str, Any]) -> None:
         from fastvideo.entrypoints.video_generator import VideoGenerator
-        from fastvideo.api.sampling_param import SamplingParam
 
         print(f"Initializing model: {self.model_path}")
-        self.generator = VideoGenerator.from_pretrained(
-            model_path=self.model_path,
-            num_gpus=1,
-            use_fsdp_inference=True,
-            text_encoder_cpu_offload=config["text_encoder_cpu_offload"],
-            dmd_denoising_steps=[1000, 850, 700, 550, 350, 275, 200, 125], # TODO: hardocde for I2V
-            dit_precision="fp32",  # TODO: hardocde for I2V
-            dit_cpu_offload=config["dit_cpu_offload"],
-            vae_cpu_offload=config["vae_cpu_offload"],
-            VSA_sparsity=config["VSA_sparsity"],
-            enable_stage_verification=False,
+        self.generator = VideoGenerator.from_config(
+            GeneratorConfig(
+                model_path=self.model_path,
+                engine=EngineConfig(
+                    num_gpus=1,
+                    use_fsdp_inference=True,
+                    enable_stage_verification=False,
+                    offload=OffloadConfig(
+                        text_encoder=config["text_encoder_cpu_offload"],
+                        dit=config["dit_cpu_offload"],
+                        vae=config["vae_cpu_offload"],
+                    ),
+                ),
+                pipeline=PipelineSelection(
+                    # I2V knobs without first-class typed fields yet.
+                    experimental={
+                        "dmd_denoising_steps": [1000, 850, 700, 550, 350, 275, 200, 125],
+                        "dit_precision": "fp32",
+                        "VSA_sparsity": config["VSA_sparsity"],
+                    },
+                ),
+            )
         )
-        self.default_params = SamplingParam.from_pretrained(self.model_path)
-        self.default_params.seed = 1000
-        self.default_params.num_frames = 73
-        self.default_params.width = 832
-        self.default_params.height = 480
 
     def generate_video(self, video_request: VideoGenerationRequest) -> VideoGenerationResponse:
         total_start_time = time.time()
-        
-        params = prepare_sampling_params(video_request, self.default_params)
 
         # Save image if provided (for I2V)
         image_path = None
@@ -218,19 +236,15 @@ class BaseModelDeployment:
             if image_path is None:
                 return VideoGenerationResponse(
                     video_data=None,
-                    seed=params.seed,
+                    seed=video_request.seed,
                     success=False,
                     error_message="Failed to save input image",
                 )
 
+        request, seed = prepare_generation_request(video_request, image_path)
+
         inference_start_time = time.time()
-        result = self.generator.generate_video(
-            prompt=video_request.prompt,
-            sampling_param=params,
-            image_path=image_path,
-            save_video=False,
-            return_frames=True,
-        )
+        result = self.generator.generate(request)
         inference_time = time.time() - inference_start_time
 
         frames, generation_time, stage_names, stage_execution_times = process_generation_result(result)
@@ -250,7 +264,7 @@ class BaseModelDeployment:
 
         return VideoGenerationResponse(
             video_data=video_data,
-            seed=params.seed,
+            seed=seed,
             success=True,
             generation_time=generation_time,
             inference_time=inference_time,

examples/inference/lora/wan_lora_inference.py

@@ -1,18 +1,31 @@
 from fastvideo import VideoGenerator
-from fastvideo.api.sampling_param import SamplingParam
+from fastvideo.api import (
+    ComponentConfig, EngineConfig, GenerationRequest, GeneratorConfig,
+    OffloadConfig, OutputConfig, PipelineSelection, SamplingConfig,
+)
 
 OUTPUT_PATH = "./lora_out"
 def main():
     # Initialize VideoGenerator with the Wan model
-    generator = VideoGenerator.from_pretrained(
-        "Wan-AI/Wan2.1-T2V-1.3B-Diffusers",
-        num_gpus=1,
-        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"
-        lora_path="benjamin-paine/steamboat-willie-1.3b",
-        lora_nickname="steamboat"
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="Wan-AI/Wan2.1-T2V-1.3B-Diffusers",
+            engine=EngineConfig(
+                num_gpus=1,
+                offload=OffloadConfig(
+                    dit=False,
+                    vae=False,
+                    text_encoder=True,
+                    pin_cpu_memory=True,  # set to false if low CPU RAM or hit obscure "CUDA error: Invalid argument"
+                ),
+            ),
+            pipeline=PipelineSelection(
+                components=ComponentConfig(
+                    lora_path="benjamin-paine/steamboat-willie-1.3b",
+                ),
+                experimental={"lora_nickname": "steamboat"},
+            ),
+        )
     )
     kwargs = {
         "height": 480,
@@ -26,25 +39,32 @@ def main():
     prompt = "steamboat willie style, golden era animation, close-up of a short fluffy monster  kneeling beside a melting red candle. the mood is one of wonder and curiosity,  as the monster gazes at the flame with wide eyes and open mouth. Its pose and expression  convey a sense of innocence and playfulness, as if it is exploring the world around it for the first time.  The use of warm colors and dramatic lighting further enhances the cozy atmosphere of the image."
     negative_prompt = "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走"
 
-    video = generator.generate_video(
-        prompt,
-        # sampling_param=sampling_param,
-        output_path=OUTPUT_PATH,
-        save_video=True,
-        negative_prompt=negative_prompt,
-        **kwargs
+    video = generator.generate(
+        GenerationRequest(
+            prompt=prompt,
+            negative_prompt=negative_prompt,
+            sampling=SamplingConfig(**kwargs),
+            output=OutputConfig(
+                output_path=OUTPUT_PATH,
+                save_video=True,
+            ),
+        )
     )
-    
+
     generator.set_lora_adapter(lora_nickname="flat_color", lora_path="motimalu/wan-flat-color-1.3b-v2")
     prompt = "flat color, no lineart, blending, negative space, artist:[john kafka|ponsuke kaikai|hara id 21|yoneyama mai|fuzichoco],  1girl, sakura miko, pink hair, cowboy shot, white shirt, floral print, off shoulder, outdoors, cherry blossom, tree shade, wariza, looking up, falling petals, half-closed eyes, white sky, clouds,  live2d animation, upper body, high quality cinematic video of a woman sitting under a sakura tree. Dreamy and lonely, the camera close-ups on the face of the woman as she turns towards the viewer. The Camera is steady, This is a cowboy shot. The animation is smooth and fluid."
     negative_prompt = "bad quality video,色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走"
-    video = generator.generate_video(
-        prompt,
-        output_path=OUTPUT_PATH,
-        save_video=True,
-        negative_prompt=negative_prompt,
-        **kwargs
+    video = generator.generate(
+        GenerationRequest(
+            prompt=prompt,
+            negative_prompt=negative_prompt,
+            sampling=SamplingConfig(**kwargs),
+            output=OutputConfig(
+                output_path=OUTPUT_PATH,
+                save_video=True,
+            ),
+        )
     )
 
 if __name__ == "__main__":
-    main()
+    main()

examples/inference/lora/wan_lora_inference_from_ckpt.py

@@ -2,45 +2,60 @@
 Inference using a LoRA checkpoint from FastVideo trainer.
 """
 from fastvideo import VideoGenerator
-from fastvideo.api.sampling_param import SamplingParam
+from fastvideo.api import (ComponentConfig, EngineConfig, GenerationRequest,
+                           GeneratorConfig, OffloadConfig, OutputConfig,
+                           PipelineSelection, SamplingConfig)
 
 OUTPUT_PATH = "./lora_out"
 def main():
     # Initialize VideoGenerator with the Wan model
-    generator = VideoGenerator.from_pretrained(
-        "Wan-AI/Wan2.1-T2V-1.3B-Diffusers",
-        num_gpus=1,
-        dit_cpu_offload=False,
-        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" 
-        lora_path="checkpoints/wan_t2v_finetune_lora/checkpoint-160/transformer",
-        lora_nickname="crush_smol"
-    )
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path="Wan-AI/Wan2.1-T2V-1.3B-Diffusers",
+            engine=EngineConfig(
+                num_gpus=1,
+                offload=OffloadConfig(
+                    dit=False,
+                    vae=True,
+                    text_encoder=True,
+                    pin_cpu_memory=True, # set to false if low CPU RAM or hit obscure "CUDA error: Invalid argument"
+                ),
+            ),
+            pipeline=PipelineSelection(
+                components=ComponentConfig(
+                    lora_path="checkpoints/wan_t2v_finetune_lora/checkpoint-160/transformer",
+                ),
+                experimental={"lora_nickname": "crush_smol"},
+            ),
+        ))
     generator.unmerge_lora_weights()
-    kwargs = {
-        "height": 480,
-        "width": 832,
-        "num_frames": 77,
-        "guidance_scale": 6.0,
-        "num_inference_steps": 50,
-        "seed": 42,
-    }
+    sampling = SamplingConfig(
+        height=480,
+        width=832,
+        num_frames=77,
+        guidance_scale=6.0,
+        num_inference_steps=50,
+        seed=42,
+    )
+    output = OutputConfig(
+        output_path=OUTPUT_PATH,
+        save_video=True,
+    )
     # Generate video with LoRA style
     prompt = "A large metal cylinder is seen pressing down on a pile of Oreo cookies, flattening them as if they were under a hydraulic press."
 
-    video = generator.generate_video(
-        prompt,
-        output_path=OUTPUT_PATH,
-        save_video=True,
-        **kwargs
-    )    
+    video = generator.generate(
+        GenerationRequest(
+            prompt=prompt,
+            sampling=sampling,
+            output=output,
+        ))
     prompt = "A large metal cylinder is seen compressing colorful clay into a compact shape, demonstrating the power of a hydraulic press."
-    video = generator.generate_video(
-        prompt,
-        output_path=OUTPUT_PATH,
-        save_video=True,
-        **kwargs
-    )
+    video = generator.generate(
+        GenerationRequest(
+            prompt=prompt,
+            sampling=sampling,
+            output=output,
+        ))
 if __name__ == "__main__":
-    main()
+    main()

examples/inference/ltx2_3/README.md

@@ -0,0 +1,69 @@
+# LTX-2.3 distilled inference configs
+
+Ready-to-run `fastvideo generate` run configs for the LTX-2.3
+distilled model (`FastVideo/LTX-2.3-Distilled-Diffusers`), covering both
+workloads (t2v / i2v), both two-stage step schedules (`5+2`, `8+3` = denoise
++ refine), and four resolutions.
+
+```bash
+fastvideo generate --config examples/inference/ltx2_3/t2v_8s3_1280x832.yaml
+```
+
+Each config is self-contained (no preset registry needed): the two-stage
+refine is wired via `generator.pipeline.preset_overrides.refine`, and the
+base sampling knobs live under `request.sampling`. The refine upsampler
+auto-resolves from the model's `spatial_upscaler`.
+
+## Configs
+
+| workload | schedule | resolution (HxW) | file |
+|---|---|---|---|
+| t2v | 5+2 | 1280x832 | `t2v_5s2_1280x832.yaml` |
+| t2v | 5+2 | 1024x1536 | `t2v_5s2_1024x1536.yaml` |
+| t2v | 5+2 | 768x1280 | `t2v_5s2_768x1280.yaml` |
+| t2v | 5+2 | 512x768 | `t2v_5s2_512x768.yaml` |
+| t2v | 8+3 | 1280x832 | `t2v_8s3_1280x832.yaml` |
+| t2v | 8+3 | 1024x1536 | `t2v_8s3_1024x1536.yaml` |
+| t2v | 8+3 | 768x1280 | `t2v_8s3_768x1280.yaml` |
+| t2v | 8+3 | 512x768 | `t2v_8s3_512x768.yaml` |
+| i2v | 5+2 | 1280x832 | `i2v_5s2_1280x832.yaml` |
+| i2v | 5+2 | 1024x1536 | `i2v_5s2_1024x1536.yaml` |
+| i2v | 5+2 | 768x1280 | `i2v_5s2_768x1280.yaml` |
+| i2v | 5+2 | 512x768 | `i2v_5s2_512x768.yaml` |
+| i2v | 8+3 | 1280x832 | `i2v_8s3_1280x832.yaml` |
+| i2v | 8+3 | 1024x1536 | `i2v_8s3_1024x1536.yaml` |
+| i2v | 8+3 | 768x1280 | `i2v_8s3_768x1280.yaml` |
+| i2v | 8+3 | 512x768 | `i2v_8s3_512x768.yaml` |
+
+## Overriding without editing a file
+
+Dotted overrides (prefixes `generator.` / `request.`) let you tweak any field:
+
+```bash
+# swap prompt
+fastvideo generate --config examples/inference/ltx2_3/t2v_8s3_1280x832.yaml \
+  --request.prompt "a red fox running through fresh snow"
+
+# change output path / gpu count
+fastvideo generate --config examples/inference/ltx2_3/t2v_5s2_512x768.yaml \
+  --request.output.output_path outputs/preview.mp4 \
+  --generator.engine.num_gpus 4
+```
+
+## i2v
+
+The `i2v_*` configs take a first-frame image via
+`request.extensions.ltx2_images` (`[[path, frame_offset, weight]]`). Edit the
+path in the file, or override it:
+
+```bash
+fastvideo generate --config examples/inference/ltx2_3/i2v_8s3_1280x832.yaml \
+  --request.extensions.ltx2_images '[["/data/portrait.jpg", 0, 1.0]]'
+```
+
+## Schedules
+
+`5+2` is the fast preview schedule; `8+3` is the higher-quality distilled
+recipe. Refine (`preset_overrides.refine.num_inference_steps`) only accepts 2
+or 3 steps.
+

examples/inference/ltx2_3/i2v_5s2_1024x1536.yaml

@@ -0,0 +1,38 @@
+# LTX-2.3 distilled i2v — 5+2 two-stage at 1024x1536.
+#
+# Run:
+#   fastvideo generate --config examples/inference/ltx2_3/i2v_5s2_1024x1536.yaml
+#
+# Stage 1 denoises for 5 steps at half resolution; the latents are then
+# spatially upsampled and refined for 2 steps (refine only supports 2 or 3).
+# The refine upsampler auto-resolves from the model's `spatial_upscaler`.
+generator:
+  model_path: FastVideo/LTX-2.3-Distilled-Diffusers
+  engine:
+    num_gpus: 1
+  pipeline:
+    workload_type: i2v
+    preset_overrides:
+      refine:
+        enabled: true
+        num_inference_steps: 2
+        guidance_scale: 1.0
+        add_noise: true
+request:
+  prompt: >-
+    The subject slowly turns toward the camera with a soft, natural expression, hair and clothing swaying gently, shallow depth of field, subtle cinematic motion.
+  sampling:
+    height: 1024
+    width: 1536
+    num_frames: 121
+    fps: 24
+    guidance_scale: 1.0
+    num_inference_steps: 5
+  # i2v conditioning — replace the path with your own first-frame image.
+  extensions:
+    ltx2_images:
+      - ["/path/to/your/first_frame.jpg", 0, 1.0]
+    ltx2_image_crf: 0.0
+  output:
+    output_path: outputs/ltx2_3_i2v_5s2_1024x1536.mp4
+    save_video: true

examples/inference/ltx2_3/i2v_5s2_1280x832.yaml

@@ -0,0 +1,38 @@
+# LTX-2.3 distilled i2v — 5+2 two-stage at 1280x832.
+#
+# Run:
+#   fastvideo generate --config examples/inference/ltx2_3/i2v_5s2_1280x832.yaml
+#
+# Stage 1 denoises for 5 steps at half resolution; the latents are then
+# spatially upsampled and refined for 2 steps (refine only supports 2 or 3).
+# The refine upsampler auto-resolves from the model's `spatial_upscaler`.
+generator:
+  model_path: FastVideo/LTX-2.3-Distilled-Diffusers
+  engine:
+    num_gpus: 1
+  pipeline:
+    workload_type: i2v
+    preset_overrides:
+      refine:
+        enabled: true
+        num_inference_steps: 2
+        guidance_scale: 1.0
+        add_noise: true
+request:
+  prompt: >-
+    The subject slowly turns toward the camera with a soft, natural expression, hair and clothing swaying gently, shallow depth of field, subtle cinematic motion.
+  sampling:
+    height: 1280
+    width: 832
+    num_frames: 121
+    fps: 24
+    guidance_scale: 1.0
+    num_inference_steps: 5
+  # i2v conditioning — replace the path with your own first-frame image.
+  extensions:
+    ltx2_images:
+      - ["/path/to/your/first_frame.jpg", 0, 1.0]
+    ltx2_image_crf: 0.0
+  output:
+    output_path: outputs/ltx2_3_i2v_5s2_1280x832.mp4
+    save_video: true