[feat] [4/n] Improve API: refactor sampling param and merge with presets

.github/mergify.yml

@@ -105,7 +105,7 @@ pull_request_rules:
           - files~=^fastvideo/pipelines/samplers/
           - files~=^fastvideo/entrypoints/
           - files~=^fastvideo/worker/
-          - files~=^fastvideo/configs/sample/
+          - files~=^fastvideo/api/sampling_param
           - files~=^fastvideo/configs/pipelines/
           - files~=^examples/inference/
       - -closed

docs/api/fastvideo.md

@@ -62,9 +62,9 @@ This page contains the complete API reference for the FastVideo library.
       show_root_toc_entry: true
       heading_level: 4
 
-#### fastvideo.configs.sample
+#### fastvideo.api.sampling_param
 
-::: fastvideo.configs.sample
+::: fastvideo.api.sampling_param
     options:
       show_source: true
       show_root_heading: true

docs/contributing/ci_architecture.md

@@ -173,7 +173,7 @@ Applied by Mergify based on which paths you modified. Multiple scope labels can
 | Label | File paths that trigger it |
 |-------|---------------------------|
 | `scope: training` | `fastvideo/train/`, `fastvideo/training/`, `fastvideo/distillation/`, `examples/train/`, `examples/training/`, `examples/distill/` |
-| `scope: inference` | `fastvideo/pipelines/basic/`, `fastvideo/pipelines/stages/`, `fastvideo/pipelines/samplers/`, `fastvideo/entrypoints/`, `fastvideo/worker/`, `fastvideo/configs/sample/`, `fastvideo/configs/pipelines/`, `examples/inference/` |
+| `scope: inference` | `fastvideo/pipelines/basic/`, `fastvideo/pipelines/stages/`, `fastvideo/pipelines/samplers/`, `fastvideo/entrypoints/`, `fastvideo/worker/`, `fastvideo/api/sampling_param.py`, `fastvideo/configs/pipelines/`, `examples/inference/` |
 | `scope: attention` | `fastvideo/attention/` |
 | `scope: kernel` | `fastvideo-kernel/`, `csrc/` |
 | `scope: data` | `fastvideo/dataset/`, `fastvideo/pipelines/preprocess/`, `examples/preprocessing/` |

docs/contributing/coding_agents.md

@@ -44,7 +44,7 @@ FastVideo maps a Diffusers-style repo into a pipeline like:
 - `fastvideo/configs/models/*`: arch configs and `param_names_mapping` for
   weight name translation.
 - `fastvideo/configs/pipelines/*`: pipeline wiring (component classes + names).
-- `fastvideo/configs/sample/*`: default runtime sampling parameters.
+- `fastvideo/api/sampling_param.py`: runtime sampling parameters.
 - `fastvideo/pipelines/basic/*`: end-to-end pipeline logic built from stages.
 - `model_index.json`: the HF repo entrypoint that maps component names to
   classes and weight files.
@@ -55,7 +55,7 @@ Minimal usage example (based on `examples/inference/basic/basic.py`):
 
 ```python
 from fastvideo import VideoGenerator
-from fastvideo.configs.sample import SamplingParam
+from fastvideo.api.sampling_param import SamplingParam
 
 model_id = "Wan-AI/Wan2.1-T2V-1.3B-Diffusers"  # or official_weights/<model_name>/
 generator = VideoGenerator.from_pretrained(model_id, num_gpus=1)
@@ -319,7 +319,8 @@ Purpose:
 
 - `fastvideo/configs/pipelines/` describes pipeline wiring and model module
   names.
-- `fastvideo/configs/sample/` defines default runtime parameters.
+- `fastvideo/api/sampling_param.py` defines runtime sampling parameters.
+  Defaults come from profiles in `fastvideo/pipelines/basic/<family>/profiles.py`.
 
 Action:
 
@@ -474,7 +475,7 @@ FastVideo integration.
 3. Pipeline wiring.
    - Pipeline: `fastvideo/pipelines/basic/wan/wan_pipeline.py`
    - Pipeline config: `fastvideo/configs/pipelines/wan.py`
-   - Sampling defaults: `fastvideo/configs/sample/wan.py`
+   - Sampling defaults: `fastvideo/pipelines/basic/wan/profiles.py`
 
 4. Minimal example.
    - Script: `examples/inference/basic/basic.py`

docs/design/inference_schema_parity_inventory.yaml

@@ -1,7 +1,7 @@
 status_definitions:
   kept: "Public field remains on a public adapter surface with the same meaning."
   moved: "Public field remains supported but normalizes into a different nested path."
-  profile_owned: "Public field remains supported only through a model/profile-specific surface."
+  preset_owned: "Public field remains supported only through a model/preset-specific surface."
   compatibility_only: "Legacy public field remains adapter-only during migration and is not part of the canonical typed schema."
   private_only: "Field should only be handled by private adapters and is not a public FastVideo compatibility promise."
   internal_only: "Field is runtime/config plumbing and should not be part of the new public typed inference API."
@@ -40,12 +40,12 @@ surfaces:
       init_weights_from_safetensors_2: generator.pipeline.components.transformer_2_weights
       override_pipeline_cls_name: generator.pipeline.components.override_pipeline_cls_name
       boundary_ratio: request.sampling.boundary_ratio
-    profile_owned:
-      ltx2_vae_tiling: generator.pipeline.profile_overrides.ltx2.vae_tiling
-      ltx2_vae_spatial_tile_size_in_pixels: generator.pipeline.profile_overrides.ltx2.vae.spatial_tile_size_in_pixels
-      ltx2_vae_spatial_tile_overlap_in_pixels: generator.pipeline.profile_overrides.ltx2.vae.spatial_tile_overlap_in_pixels
-      ltx2_vae_temporal_tile_size_in_frames: generator.pipeline.profile_overrides.ltx2.vae.temporal_tile_size_in_frames
-      ltx2_vae_temporal_tile_overlap_in_frames: generator.pipeline.profile_overrides.ltx2.vae.temporal_tile_overlap_in_frames
+    preset_owned:
+      ltx2_vae_tiling: generator.pipeline.preset_overrides.ltx2.vae_tiling
+      ltx2_vae_spatial_tile_size_in_pixels: generator.pipeline.preset_overrides.ltx2.vae.spatial_tile_size_in_pixels
+      ltx2_vae_spatial_tile_overlap_in_pixels: generator.pipeline.preset_overrides.ltx2.vae.spatial_tile_overlap_in_pixels
+      ltx2_vae_temporal_tile_size_in_frames: generator.pipeline.preset_overrides.ltx2.vae.temporal_tile_size_in_frames
+      ltx2_vae_temporal_tile_overlap_in_frames: generator.pipeline.preset_overrides.ltx2.vae.temporal_tile_overlap_in_frames
       ltx2_initial_latent_path: request.extensions.ltx2.initial_latent_path
     compatibility_only:
       mode: "Legacy multi-mode FastVideoArgs switch; typed inference config should not expose execution mode."
@@ -69,16 +69,16 @@ surfaces:
   pipeline_config_base:
     moved:
       pipeline_config_path: generator.pipeline.components.pipeline_config_path
-    profile_owned:
-      embedded_cfg_scale: generator.pipeline.profile_overrides.embedded_cfg_scale
-      flow_shift: generator.pipeline.profile_overrides.flow_shift
-      flow_shift_sr: generator.pipeline.profile_overrides.flow_shift_sr
-      is_causal: generator.pipeline.profile_overrides.is_causal
-      vae_tiling: generator.pipeline.profile_overrides.vae_tiling
-      vae_sp: generator.pipeline.profile_overrides.vae_sp
-      dmd_denoising_steps: generator.pipeline.profile_overrides.dmd_denoising_steps
-      ti2v_task: generator.pipeline.profile_overrides.ti2v_task
-      boundary_ratio: generator.pipeline.profile_overrides.boundary_ratio
+    preset_owned:
+      embedded_cfg_scale: generator.pipeline.preset_overrides.embedded_cfg_scale
+      flow_shift: generator.pipeline.preset_overrides.flow_shift
+      flow_shift_sr: generator.pipeline.preset_overrides.flow_shift_sr
+      is_causal: generator.pipeline.preset_overrides.is_causal
+      vae_tiling: generator.pipeline.preset_overrides.vae_tiling
+      vae_sp: generator.pipeline.preset_overrides.vae_sp
+      dmd_denoising_steps: generator.pipeline.preset_overrides.dmd_denoising_steps
+      ti2v_task: generator.pipeline.preset_overrides.ti2v_task
+      boundary_ratio: generator.pipeline.preset_overrides.boundary_ratio
     compatibility_only:
       model_path: "Redundant with generator.model_path."
       disable_autocast: "Duplicated by generator.engine.disable_autocast during migration."
@@ -97,7 +97,7 @@ surfaces:
       postprocess_text_funcs: "Internal text postprocessing hooks."
 
   pipeline_config_extensions:
-    profile_owned:
+    preset_owned:
       conditioning_strategy:
         sources:
           - fastvideo.configs.pipelines.cosmos.CosmosConfig
@@ -309,8 +309,8 @@ surfaces:
     compatibility_only:
       batch_size: "Gen3C inference-only tuning field pending typed batching design."
       gradient_checkpointing: "Gen3C inference-only compatibility field pending typed batching design."
-      guidance_scale: "Gen3C pipeline-level default pending profile/default-request cleanup."
-      num_inference_steps: "Gen3C pipeline-level default pending profile/default-request cleanup."
+      guidance_scale: "Gen3C pipeline-level default pending preset/default-request cleanup."
+      num_inference_steps: "Gen3C pipeline-level default pending preset/default-request cleanup."
     internal_only:
       audio_decoder_config: "Legacy internal component config object."
       audio_decoder_precision: "Precision override pending dedicated component precision design."
@@ -345,6 +345,7 @@ surfaces:
       num_inference_steps: request.sampling.num_inference_steps
       num_inference_steps_sr: request.sampling.num_inference_steps_sr
       guidance_scale: request.sampling.guidance_scale
+      guidance_scale_2: request.sampling.guidance_scale_2
       guidance_rescale: request.sampling.guidance_rescale
       boundary_ratio: request.sampling.boundary_ratio
       sigmas: request.sampling.sigmas
@@ -353,96 +354,34 @@ surfaces:
       return_frames: request.output.return_frames
       return_trajectory_latents: request.runtime.return_trajectory_latents
       return_trajectory_decoded: request.runtime.return_trajectory_decoded
-    profile_owned:
+    preset_owned:
       t_thresh: request.stage_overrides.refine.t_thresh
       spatial_refine_only: request.stage_overrides.refine.spatial_refine_only
       num_cond_frames: request.stage_overrides.refine.num_cond_frames
       trajectory_type: request.extensions.gen3c.trajectory_type
       movement_distance: request.extensions.gen3c.movement_distance
       camera_rotation: request.extensions.gen3c.camera_rotation
+      prompt_attention_mask: request.extensions.hyworld.prompt_attention_mask
+      negative_attention_mask: request.extensions.hyworld.negative_attention_mask
+      camera_states: request.extensions.hunyuangamecraft.camera_states
+      camera_trajectory: request.extensions.hunyuangamecraft.camera_trajectory
+      action_list: request.extensions.hunyuangamecraft.action_list
+      action_speed_list: request.extensions.hunyuangamecraft.action_speed_list
+      gt_latents: request.extensions.hunyuangamecraft.gt_latents
+      conditioning_mask: request.extensions.hunyuangamecraft.conditioning_mask
+      ltx2_cfg_scale_video: request.extensions.ltx2.cfg_scale_video
+      ltx2_cfg_scale_audio: request.extensions.ltx2.cfg_scale_audio
+      ltx2_modality_scale_video: request.extensions.ltx2.modality_scale_video
+      ltx2_modality_scale_audio: request.extensions.ltx2.modality_scale_audio
+      ltx2_rescale_scale: request.extensions.ltx2.rescale_scale
+      ltx2_stg_scale_video: request.extensions.ltx2.stg_scale_video
+      ltx2_stg_scale_audio: request.extensions.ltx2.stg_scale_audio
+      ltx2_stg_blocks_video: request.extensions.ltx2.stg_blocks_video
+      ltx2_stg_blocks_audio: request.extensions.ltx2.stg_blocks_audio
     internal_only:
       data_type: "Derived from the request shape and not a public input."
 
-  sampling_param_extensions:
-    moved:
-      guidance_scale_2:
-        target: request.sampling.guidance_scale_2
-        sources:
-          - fastvideo.configs.sample.lingbotworld.LingBotWorld_SamplingParam
-          - fastvideo.configs.sample.lingbotworld.Wan2_2_I2V_A14B_SamplingParam
-          - fastvideo.configs.sample.wan.SelfForcingWan2_2_T2V_A14B_480P_SamplingParam
-          - fastvideo.configs.sample.wan.Wan2_2_I2V_A14B_SamplingParam
-          - fastvideo.configs.sample.wan.Wan2_2_T2V_A14B_SamplingParam
-    profile_owned:
-      action_list:
-        target: request.extensions.hunyuangamecraft.action_list
-        sources:
-          - fastvideo.configs.sample.hunyuangamecraft.HunyuanGameCraftSamplingParam
-          - fastvideo.configs.sample.hunyuangamecraft.HunyuanGameCraft65FrameSamplingParam
-          - fastvideo.configs.sample.hunyuangamecraft.HunyuanGameCraft129FrameSamplingParam
-      action_speed_list:
-        target: request.extensions.hunyuangamecraft.action_speed_list
-        sources:
-          - fastvideo.configs.sample.hunyuangamecraft.HunyuanGameCraftSamplingParam
-          - fastvideo.configs.sample.hunyuangamecraft.HunyuanGameCraft65FrameSamplingParam
-          - fastvideo.configs.sample.hunyuangamecraft.HunyuanGameCraft129FrameSamplingParam
-      camera_states:
-        target: request.extensions.hunyuangamecraft.camera_states
-        sources:
-          - fastvideo.configs.sample.hunyuangamecraft.HunyuanGameCraftSamplingParam
-          - fastvideo.configs.sample.hunyuangamecraft.HunyuanGameCraft65FrameSamplingParam
-          - fastvideo.configs.sample.hunyuangamecraft.HunyuanGameCraft129FrameSamplingParam
-      camera_trajectory:
-        target: request.extensions.hunyuangamecraft.camera_trajectory
-        sources:
-          - fastvideo.configs.sample.hunyuangamecraft.HunyuanGameCraftSamplingParam
-          - fastvideo.configs.sample.hunyuangamecraft.HunyuanGameCraft65FrameSamplingParam
-          - fastvideo.configs.sample.hunyuangamecraft.HunyuanGameCraft129FrameSamplingParam
-      conditioning_mask:
-        target: request.extensions.hunyuangamecraft.conditioning_mask
-        sources:
-          - fastvideo.configs.sample.hunyuangamecraft.HunyuanGameCraftSamplingParam
-          - fastvideo.configs.sample.hunyuangamecraft.HunyuanGameCraft65FrameSamplingParam
-          - fastvideo.configs.sample.hunyuangamecraft.HunyuanGameCraft129FrameSamplingParam
-      gt_latents:
-        target: request.extensions.hunyuangamecraft.gt_latents
-        sources:
-          - fastvideo.configs.sample.hunyuangamecraft.HunyuanGameCraftSamplingParam
-          - fastvideo.configs.sample.hunyuangamecraft.HunyuanGameCraft65FrameSamplingParam
-          - fastvideo.configs.sample.hunyuangamecraft.HunyuanGameCraft129FrameSamplingParam
-      prompt_attention_mask:
-        target: request.extensions.hyworld.prompt_attention_mask
-        sources: [fastvideo.configs.sample.hyworld.HYWorld_SamplingParam]
-      negative_attention_mask:
-        target: request.extensions.hyworld.negative_attention_mask
-        sources: [fastvideo.configs.sample.hyworld.HYWorld_SamplingParam]
-      ltx2_cfg_scale_audio:
-        target: request.extensions.ltx2.cfg_scale_audio
-        sources: [fastvideo.configs.sample.ltx2.LTX2BaseSamplingParam]
-      ltx2_cfg_scale_video:
-        target: request.extensions.ltx2.cfg_scale_video
-        sources: [fastvideo.configs.sample.ltx2.LTX2BaseSamplingParam]
-      ltx2_modality_scale_audio:
-        target: request.extensions.ltx2.modality_scale_audio
-        sources: [fastvideo.configs.sample.ltx2.LTX2BaseSamplingParam]
-      ltx2_modality_scale_video:
-        target: request.extensions.ltx2.modality_scale_video
-        sources: [fastvideo.configs.sample.ltx2.LTX2BaseSamplingParam]
-      ltx2_rescale_scale:
-        target: request.extensions.ltx2.rescale_scale
-        sources: [fastvideo.configs.sample.ltx2.LTX2BaseSamplingParam]
-      ltx2_stg_blocks_audio:
-        target: request.extensions.ltx2.stg_blocks_audio
-        sources: [fastvideo.configs.sample.ltx2.LTX2BaseSamplingParam]
-      ltx2_stg_blocks_video:
-        target: request.extensions.ltx2.stg_blocks_video
-        sources: [fastvideo.configs.sample.ltx2.LTX2BaseSamplingParam]
-      ltx2_stg_scale_audio:
-        target: request.extensions.ltx2.stg_scale_audio
-        sources: [fastvideo.configs.sample.ltx2.LTX2BaseSamplingParam]
-      ltx2_stg_scale_video:
-        target: request.extensions.ltx2.stg_scale_video
-        sources: [fastvideo.configs.sample.ltx2.LTX2BaseSamplingParam]
+  sampling_param_extensions: {}
 
   openai_image_request:
     kept:

docs/design/overview.md

@@ -12,7 +12,7 @@ FastVideo maps a Diffusers-style repo into a pipeline like this:
 - `fastvideo/configs/models/*`: arch configs and `param_names_mapping` for
   weight name translation.
 - `fastvideo/configs/pipelines/*`: pipeline wiring (component classes + names).
-- `fastvideo/configs/sample/*`: default runtime sampling parameters.
+- `fastvideo/api/sampling_param.py`: runtime sampling parameters.
 - `fastvideo/pipelines/basic/*`: end-to-end pipelines.
 - `fastvideo/pipelines/stages/*`: reusable pipeline stages.
 - `fastvideo/models/loader/*`: component loaders for Diffusers-style repos.
@@ -26,7 +26,7 @@ Minimal usage (from `examples/inference/basic/basic.py`):
 
 ```python
 from fastvideo import VideoGenerator
-from fastvideo.configs.sample import SamplingParam
+from fastvideo.api.sampling_param import SamplingParam
 
 model_id = "Wan-AI/Wan2.1-T2V-1.3B-Diffusers"  # or official_weights/<model_name>/
 generator = VideoGenerator.from_pretrained(model_id, num_gpus=1)
@@ -49,8 +49,9 @@ runtime parameters consistent:
 - `fastvideo/configs/models/`: architecture definitions, layer shapes, and
   `param_names_mapping` rules for key renaming.
 - `fastvideo/configs/pipelines/`: pipeline wiring and required components.
-- `fastvideo/configs/sample/`: default sampling parameters (steps, frames,
-  guidance scale, resolution, fps).
+- `fastvideo/api/sampling_param.py`: sampling parameters (steps, frames,
+  guidance scale, resolution, fps). Defaults come from profiles in
+  `fastvideo/pipelines/basic/<family>/profiles.py`.
 - `fastvideo/registry.py`: unified registry for pipeline config + sampling
   defaults and model metadata resolution, defined via explicit
   `register_configs(...)` blocks (no separate dict registries).
@@ -142,7 +143,7 @@ How this maps to FastVideo:
 - `T5TokenizerFast` -> loaded via HF in `fastvideo/models/loader/`
 - `UniPCMultistepScheduler` -> loaded via Diffusers scheduler utilities
 - Pipeline defaults -> `fastvideo/configs/pipelines/wan.py`
-- Sampling defaults -> `fastvideo/configs/sample/wan.py`
+- Sampling defaults -> `fastvideo/pipelines/basic/wan/profiles.py`
 
 ## Pipeline system
 

docs/getting_started/v1_api.md

@@ -33,7 +33,7 @@ The following two classes `PipelineConfig` and `SamplingParam` are used to confi
 
 ### SamplingParam
 
-::: fastvideo.configs.sample.base.SamplingParam
+::: fastvideo.api.sampling_param.SamplingParam
     options:
       show_root_heading: true
       show_source: false

docs/inference/architecture.md

@@ -128,19 +128,14 @@ Concrete hierarchy: `DiTConfig` → `DiTArchConfig`, `VAEConfig` →
 - `dump_to_json()` / `load_from_json()` — JSON persistence. Callable
   fields and `arch_config` are excluded from dumps.
 
-### SamplingParam (`fastvideo/configs/sample/`)
+### SamplingParam (`fastvideo/api/sampling_param.py`)
 
 Generation parameters separate from pipeline config. Each model family
-provides defaults:
+provides defaults via a profile (see `fastvideo/pipelines/basic/<family>/profiles.py`):
 
 ```python
-@dataclass
-class WanT2V_1_3B_SamplingParam(SamplingParam):
-    height: int = 480
-    width: int = 832
-    num_frames: int = 81
-    guidance_scale: float = 3.0
-    num_inference_steps: int = 50
+sp = SamplingParam.from_pretrained("Wan-AI/Wan2.1-T2V-1.3B-Diffusers")
+# sp.height == 480, sp.width == 832, sp.num_frames == 81, etc.
 ```
 
 ## Component Loading
@@ -430,9 +425,9 @@ User: generator.generate_video(prompt, ...)
    `fastvideo/configs/pipelines/<model>.py`. Set DiT/VAE/encoder configs,
    flow_shift, precision defaults.
 
-2. **Sampling param** — Create a `SamplingParam` subclass in
-   `fastvideo/configs/sample/<model>.py`. Set default height, width,
-   num_frames, guidance_scale, num_inference_steps.
+2. **Sampling param profile** — Create a profile in
+   `fastvideo/pipelines/basic/<model>/profiles.py` with default height,
+   width, num_frames, guidance_scale, num_inference_steps.
 
 3. **Register configs** — In `fastvideo/registry.py`, add a
    `register_configs()` call inside `_register_configs()` with

docs/inference/gen3c.md

@@ -89,7 +89,7 @@ GEN3C defaults in FastVideo:
 
 These values are defined in:
 
-- `fastvideo/configs/sample/gen3c.py`
+- `fastvideo/pipelines/basic/gen3c/profiles.py`
 - `fastvideo/configs/pipelines/gen3c.py`
 
 and align with the official GEN3C inference defaults in:

examples/inference/basic/basic.py

@@ -1,6 +1,6 @@
 from fastvideo import VideoGenerator
 
-# from fastvideo.configs.sample import SamplingParam
+# from fastvideo.api.sampling_param import SamplingParam
 
 OUTPUT_PATH = "video_samples"
 def main():