Promote the refine-override field accessors to module-level frozenset
constants (``REFINE_PRESET_OVERRIDE_FIELDS``,
``REFINE_STAGE_OVERRIDE_FIELDS``, ``REFINE_FLAT_KEYS``) so callers
reference a single source of truth instead of recomputing on each
call. Drop the redundant ``dict(deepcopy(value))`` double-copy on the
``torch_compile_kwargs`` legacy path, compress the
``_compile_config_to_torch_kwargs`` docstring, and remove a handful of
comments that just restated the code or named a future PR. Narrow the
schema-parity ``walk_packages`` traversal to
``configs/pipelines/*`` and ``basic/<family>/pipeline_configs`` so the
test no longer imports every heavy model module under ``basic/``.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Post-review cleanup (no behavior change):
Correctness:
* compat.py refine reverse-flatten now iterates
_LTX2_REFINE_FLAT_KEYS, which unions the typed
LTX2RefinePresetOverride and LTX2RefineStageOverride field sets.
The previous hardcoded 4-tuple missed image_crf and
video_position_offset_sec, so any init-time
preset_overrides.refine.image_crf would silently drop on reverse.
New regression test TestRefineFlattenCoversAllTypedFields pins the
invariant.
Simplification:
* refine_preset_override_to_dict and refine_stage_override_to_dict
were byte-identical; collapse to a single refine_override_to_dict.
* Trim narrative / PR-migration prose from docstrings and re-export
shims: stage_overrides.py module + field docstrings, schema.py
CompileConfig + PipelineSelection.vae_tiling, presets.py
LTX2_TWO_STAGE header, configs/pipelines/__init__.py and
pipelines/stages/__init__.py and ltx2/stages/__init__.py.
Close out PR 6 with the compat mappings for every flat LTX-2 kwarg
the FastVideo-internal ui/ltx2-streaming/server/gpu_pool.py passes to
VideoGenerator.from_pretrained, plus an integration test that freezes
the gpu_pool load_kwargs dict as a parity guard.
Compat additions (fastvideo/api/compat.py):
legacy_from_pretrained_to_config forward routing for:
- config_model_path -> components.config_root
- ltx2_refine_enabled -> preset_overrides.refine.enabled
- ltx2_refine_upsampler_path -> components.upsampler_weights
(empty string collapses to None)
- ltx2_refine_lora_path -> components.lora_path
(empty string collapses to None)
- ltx2_refine_add_noise -> preset_overrides.refine.add_noise
- ltx2_refine_num_inference_steps -> preset_overrides.refine.num_inference_steps
- ltx2_refine_guidance_scale -> preset_overrides.refine.guidance_scale
generator_config_to_fastvideo_args reverse routing:
- components.config_root -> config_model_path
- components.upsampler_weights -> ltx2_refine_upsampler_path
(no longer raises NotImplementedError)
- preset_overrides.refine.{...} now flattens back to
ltx2_refine_{enabled, add_noise, num_inference_steps, guidance_scale}
instead of leaking as a nested "refine" kwarg.
PR 7.6 (gpu_pool upstream) and the Dynamo adapter can now build a typed
GeneratorConfig from their CLI without knowing any legacy LTX-2 kwarg
name — the hard gate called out in PR plan.md § "Why the gpu_pool.py
typed-replacement scope matters".
Tests (fastvideo/tests/api/test_ltx2_gpu_pool_translation.py):
- GPU_POOL_LOAD_KWARGS fixture mirrors gpu_pool.py lines 233-260
(minus opaque objects: PipelineConfig instance, the text-encoder
torch.compile flag not yet in the public FastVideoArgs).
- TestGpuPoolForwardTranslation asserts each flat kwarg lands on the
correct typed field and that pipeline.experimental stays empty
(no silent fallthrough).
- TestGpuPoolReverseTranslation asserts the same dict reproduces on
the FastVideoArgs.from_kwargs call — including the four ltx2_refine_*
fields, ltx2_vae_tiling, torch_compile_kwargs, and config_model_path.
- TestCompileExtrasPreserved checks non-typed torch.compile kwargs
(options, disable) ride through CompileConfig.extras in both
directions.
All 148 API tests pass locally (227 including entrypoints).
Move the LTX-2 family's PipelineConfig and the four LTX-2-specific
stage modules into fastvideo/pipelines/basic/ltx2/ so each model family
directory is self-contained (pipeline implementation + presets +
stage_overrides + pipeline_configs + stages in one place). See the
"Pipeline Package Structure" section in PR plan.md and the per-model
colocation plan in apirefactor.md Phase 8.
File moves (git mv preserves history):
fastvideo/configs/pipelines/ltx2.py
-> fastvideo/pipelines/basic/ltx2/pipeline_configs.py
fastvideo/pipelines/stages/ltx2_audio_decoding.py
-> fastvideo/pipelines/basic/ltx2/stages/ltx2_audio_decoding.py
fastvideo/pipelines/stages/ltx2_denoising.py
-> fastvideo/pipelines/basic/ltx2/stages/ltx2_denoising.py
fastvideo/pipelines/stages/ltx2_latent_preparation.py
-> fastvideo/pipelines/basic/ltx2/stages/ltx2_latent_preparation.py
fastvideo/pipelines/stages/ltx2_text_encoding.py
-> fastvideo/pipelines/basic/ltx2/stages/ltx2_text_encoding.py
Import/export updates:
- fastvideo/registry.py and tests/local_tests/test_ltx2_registry.py
now import LTX2T2VConfig from the new colocated path directly.
- fastvideo/configs/pipelines/__init__.py keeps the legacy
`fastvideo.configs.pipelines.LTX2T2VConfig` export by re-exporting
from the new location — external users of the old path keep working.
- fastvideo/pipelines/stages/__init__.py does the same for the four
LTX-2 stage classes, re-exporting from the new
pipelines/basic/ltx2/stages/ subpackage.
- new fastvideo/pipelines/basic/ltx2/stages/__init__.py is the
canonical home for the stage exports.
Parity-inventory walker (fastvideo/tests/api/test_schema_parity_inventory.py):
_get_extra_dataclass_fields now accepts a tuple of package roots and
descends recursively via pkgutil.walk_packages, so it discovers
PipelineConfig subclasses that have moved out of
fastvideo.configs.pipelines into fastvideo.pipelines.basic.<family>.
The pipeline_config_extensions classification test now walks both
roots so the LTX-2 fields (vocoder_config, audio_decoder_config,
vocoder_precision, audio_decoder_precision) stay accounted for.
Nothing else changes: no behavior change; no test changes beyond the
walker; all 210 API+entrypoints tests still pass.
Promote the four torch.compile kwargs the FastVideo-internal
ltx2-streaming gpu_pool hard-codes in its torch_compile_kwargs dict
into first-class typed fields on CompileConfig, and add a typed home
for ltx2_vae_tiling on PipelineSelection so PR 7.6's public gpu_pool
upstream has a typed boundary to hit.
Schema changes (fastvideo/api/schema.py):
CompileConfig:
- rename kwargs -> extras (breaking; pre-stable API)
- add backend: str | None (e.g. "inductor")
- add fullgraph: bool | None
- add mode: str | None (e.g. "max-autotune-no-cudagraphs")
- add dynamic: bool | None
extras still holds uncommon kwargs (e.g. options, disable).
PipelineSelection:
- add vae_tiling: bool | None. Shared across model families that
expose VAE tiling (LTX-2, Wan configs, etc.); None leaves the
model default in place.
Compat (fastvideo/api/compat.py):
- legacy_from_pretrained_to_config splits incoming
torch_compile_kwargs={backend, fullgraph, mode, dynamic, ...}
across the four typed fields and drops the remainder into extras.
- generator_config_to_fastvideo_args reconstructs the flat
torch_compile_kwargs dict via _compile_config_to_torch_kwargs,
emitting only user-set typed fields plus extras.
- legacy ltx2_vae_tiling routes to pipeline.vae_tiling on the way in
and back to ltx2_vae_tiling on the way out.
Parity inventory (docs/design/inference_schema_parity_inventory.yaml):
- torch_compile_kwargs now maps to the comma-separated leaf
generator.engine.compile.backend,fullgraph,mode,dynamic,extras
- ltx2_vae_tiling reclassified from preset_owned nested dict
(.preset_overrides.ltx2.vae_tiling) to moved (.pipeline.vae_tiling)
11 new tests in fastvideo/tests/api/test_compat_translation.py cover
typed-key promotion, extras merge, None suppression, round-trip back
to FastVideoArgs, and the vae_tiling forward/reverse path. Parser
round-trip fixture updated for the new schema fields.
Add typed public dataclasses that describe the LTX-2 refine override
surfaces, and bind them to the ltx2_two_stage preset's stage schema so
the validation-layer field set stays in lockstep with the dataclass:
* LTX2RefinePresetOverride (init-time, for preset_overrides.refine):
- enabled: bool | None — toggle the refine stage topology
- add_noise: bool | None — controls LTX2UpsampleStage noise mixing
* LTX2RefineStageOverride (per-request, for stage_overrides.refine):
- num_inference_steps: int | None — stage-2 denoise steps (2 or 3)
- guidance_scale: float | None — force_guidance_scale for stage-2
- image_crf: int | None — image-encoding CRF hint
- video_position_offset_sec: float | None — RoPE shift for audio
conditioning continuation
Asset wiring (upsampler weights, refine LoRA) stays on
ComponentConfig.upsampler_weights / .lora_path — no new typed home is
added here because those already exist.
The ltx2_two_stage refine stage schema's allowed_overrides now reads
from refine_stage_override_fields() so the dataclass is the single
source of truth. Serialisation helpers
(refine_{preset,stage}_override_to_dict) drop None entries so only
user-set fields flow through the preset/stage override dicts.
The runtime still reads the refine knobs off FastVideoArgs at
pipeline-construction time; wiring these typed objects through compat
+ runtime is the next slice. This commit ships only the public
typed surface and the preset/dataclass invariant.
12 new tests in fastvideo/tests/api/test_ltx2_stage_overrides.py cover
default None construction, explicit construction, to_dict() dropping
None, fields() accessor, and an invariant test proving the preset's
refine stage allowed_overrides exactly matches the dataclass fields.
Land the ltx2_two_stage inference preset (PR 6 commit 1/5) that exposes
the public LTX-2 two-stage distilled flow: half-resolution denoise
followed by 2x spatial upsample + stage-2 refine denoise (3 steps with
the official distilled sigma schedule, or 2 steps with the reduced
variant).
Schema:
- new _REFINE_STAGE PresetStageSpec with kind="refinement" and
allowed per-request overrides {num_inference_steps, guidance_scale,
image_crf, video_position_offset_sec}
- new LTX2_TWO_STAGE preset with stage_schemas=(denoise, refine) and
stage_defaults.refine={num_inference_steps: 2, guidance_scale: 1.0}
matching the load_kwargs the internal ltx2-streaming gpu_pool uses
- LTX2_TWO_STAGE registered via ALL_PRESETS -> _register_presets()
Init-time refine wiring (enabled, add_noise, upsampler/LoRA/transformer
paths) flows through generator.pipeline.preset_overrides.refine.* and
generator.pipeline.components.{upsampler_weights, lora_path} in a
follow-up commit — the refine stage's internal implementation
(fastvideo/pipelines/stages/ltx2_refine.py in FastVideo-internal) already
treats those as FastVideoArgs fields; this commit only ships the public
preset surface.
5 new tests under fastvideo/tests/api/test_presets.py::TestLtx2Presets:
registration count (3 presets now), two-stage topology, stage defaults,
valid per-request refine override keys, and unknown-override rejection.
