[refactor]: group model-family settings under pipeline.model

pipeline.model is a tagged union: a mapping with exactly one key, which
names the model family (ltx2, minimax_h3, longcat, or generic) and selects
that family's options class. The former sibling sections pipeline.ltx2,
pipeline.minimax_h3, and pipeline.longcat, and the DiT/VAE architecture
override dicts pipeline.dit and pipeline.vae, live inside the family block.
The parser implements tagged unions as a general mechanism (a dataclass
with a TAGS table); the family is readable as pipeline.model.family.

Resolution validates the tag against the family that the registry chose
for model_path (validate_model_family raises and names the registry class
and the right block) and fills the family's empty block when the input has
none (fill_model_family), so readers never see None. Family-only fills and
derivations (the MiniMax-H3 parallel-VAE environment variables, the LTX-2
tile-size derivation and refine preset copy, the LongCat BSA mirrors) run
only for their family.

Against the 3f6893a0 goldens every PipelineConfig is identical and no
other field differs beyond the allowed categories; family-only settings
are no longer decided on models of another family. LingBot-Video reads
its refiner switch from pipeline.preset_overrides.refine.enabled and loads
the refiner by default when the checkpoint has one, as at 3f6893a0.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CbSuTKA9oX4YsECdcBPAsX

examples/inference/basic/basic_fasth3.py

@@ -263,7 +263,7 @@ def build_generator_config(args: argparse.Namespace) -> GeneratorConfig:
                 lora_path=getattr(args, "lora_path", None),
                 lora_strength=float(getattr(args, "lora_strength", 1.0)),
             ),
-            minimax_h3=MiniMaxH3Options(
+            model=MiniMaxH3Options(
                 sequential_load=args.h3_sequential_load,
                 video_decode_backend=None if args.video_decode_backend == "h3-vae" else args.video_decode_backend,
                 taeh3_checkpoint=args.taeh3_checkpoint,

examples/inference/basic/basic_fasth3_simplified.py

@@ -73,7 +73,7 @@ def main() -> None:
             model_path="MiniMaxAI/MiniMax-H3",
             pipeline=PipelineSelection(
                 components=ComponentConfig(lora_path=adapter_path, lora_strength=1.0),
-                minimax_h3=MiniMaxH3Options(vae_parallel_decode=True, vae_parallel_decode_strategy="gather"),
+                model=MiniMaxH3Options(vae_parallel_decode=True, vae_parallel_decode_strategy="gather"),
             ),
             engine=EngineConfig(
                 num_gpus=4,

examples/inference/basic/basic_fasth3_simplified_profile.py

@@ -63,7 +63,7 @@ def main() -> None:
             model_path="MiniMaxAI/MiniMax-H3",
             pipeline=PipelineSelection(
                 components=ComponentConfig(lora_path=adapter_path, lora_strength=1.0),
-                minimax_h3=MiniMaxH3Options(vae_parallel_decode=True, vae_parallel_decode_strategy="gather"),
+                model=MiniMaxH3Options(vae_parallel_decode=True, vae_parallel_decode_strategy="gather"),
             ),
             engine=EngineConfig(
                 num_gpus=4,

examples/inference/basic/basic_fasth3_spark.yaml

@@ -36,9 +36,10 @@ generator:
       vsa_sparsity: 0.9
       vsa_tile_size: 64
   pipeline:
-    minimax_h3:
-      vae_parallel_decode: true
-      vae_parallel_decode_strategy: gather
+    model:
+      minimax_h3:
+        vae_parallel_decode: true
+        vae_parallel_decode_strategy: gather
 request:
   prompt: >-
     A wide cinematic shot of an alpine meadow at sunrise, pale pink mountain

examples/inference/basic/basic_fasth3_spark_pair.yaml

@@ -36,9 +36,10 @@ generator:
       vsa_sparsity: 0.9
       vsa_tile_size: 64
   pipeline:
-    minimax_h3:
-      vae_parallel_decode: true
-      vae_parallel_decode_strategy: gather
+    model:
+      minimax_h3:
+        vae_parallel_decode: true
+        vae_parallel_decode_strategy: gather
 request:
   prompt: >-
     A wide cinematic shot of an alpine meadow at sunrise, pale pink mountain

examples/inference/basic/basic_longcat_i2v.py

@@ -60,7 +60,7 @@ def basic_generation():
                 "pin_cpu_memory": False,
             },
         },
-        "pipeline": {"longcat": {"enable_bsa": False}},
+        "pipeline": {"model": {"longcat": {"enable_bsa": False}}},
     })
 
     output_path = "outputs_video/longcat_i2v_basic"
@@ -113,7 +113,7 @@ def distill_refine_generation():
             },
         },
         "pipeline": {
-            "longcat": {"enable_bsa": False},
+            "model": {"longcat": {"enable_bsa": False}},
             "components": {
                 "lora_path": "FastVideo/LongCat-Video-T2V-Distilled-LoRA",
                 "lora_nickname": "distilled",
@@ -171,11 +171,13 @@ def distill_refine_generation():
             },
         },
         "pipeline": {
-            "longcat": {
-                "enable_bsa": True,
-                "bsa_sparsity": 0.875,
-                "bsa_chunk_q": [4, 4, 4],
-                "bsa_chunk_k": [4, 4, 4],
+            "model": {
+                "longcat": {
+                    "enable_bsa": True,
+                    "bsa_sparsity": 0.875,
+                    "bsa_chunk_q": [4, 4, 4],
+                    "bsa_chunk_k": [4, 4, 4],
+                },
             },
             "components": {
                 "lora_path": "FastVideo/LongCat-Video-T2V-Refinement-LoRA",

examples/inference/basic/basic_longcat_t2v.py

@@ -53,7 +53,7 @@ def basic_generation():
                 "pin_cpu_memory": False,
             },
         },
-        "pipeline": {"longcat": {"enable_bsa": False}},
+        "pipeline": {"model": {"longcat": {"enable_bsa": False}}},
     })
 
     output_path = "outputs_video/longcat_t2v_basic"
@@ -105,7 +105,7 @@ def distill_refine_generation():
             },
         },
         "pipeline": {
-            "longcat": {"enable_bsa": False},
+            "model": {"longcat": {"enable_bsa": False}},
             "components": {
                 "lora_path": "FastVideo/LongCat-Video-T2V-Distilled-LoRA",
                 "lora_nickname": "distilled",
@@ -159,11 +159,13 @@ def distill_refine_generation():
             },
         },
         "pipeline": {
-            "longcat": {
-                "enable_bsa": True,
-                "bsa_sparsity": 0.875,
-                "bsa_chunk_q": [4, 4, 8],
-                "bsa_chunk_k": [4, 4, 8],
+            "model": {
+                "longcat": {
+                    "enable_bsa": True,
+                    "bsa_sparsity": 0.875,
+                    "bsa_chunk_q": [4, 4, 8],
+                    "bsa_chunk_k": [4, 4, 8],
+                },
             },
             "components": {
                 "lora_path": "FastVideo/LongCat-Video-T2V-Refinement-LoRA",

examples/inference/basic/basic_longcat_vc.py

@@ -69,7 +69,7 @@ def basic_generation():
                 "pin_cpu_memory": False,
             },
         },
-        "pipeline": {"longcat": {"enable_bsa": False}},
+        "pipeline": {"model": {"longcat": {"enable_bsa": False}}},
     })
 
     output_path = "outputs_video/longcat_vc_basic"
@@ -128,7 +128,7 @@ def distill_refine_generation():
             },
         },
         "pipeline": {
-            "longcat": {"enable_bsa": False},
+            "model": {"longcat": {"enable_bsa": False}},
             "components": {
                 "lora_path": "FastVideo/LongCat-Video-T2V-Distilled-LoRA",
                 "lora_nickname": "distilled",
@@ -185,11 +185,13 @@ def distill_refine_generation():
             },
         },
         "pipeline": {
-            "longcat": {
-                "enable_bsa": True,
-                "bsa_sparsity": 0.875,
-                "bsa_chunk_q": [4, 4, 8],
-                "bsa_chunk_k": [4, 4, 8],
+            "model": {
+                "longcat": {
+                    "enable_bsa": True,
+                    "bsa_sparsity": 0.875,
+                    "bsa_chunk_q": [4, 4, 8],
+                    "bsa_chunk_k": [4, 4, 8],
+                },
             },
             "components": {
                 "lora_path": "FastVideo/LongCat-Video-T2V-Refinement-LoRA",

examples/inference/basic/basic_ltx2_3_distilled_i2v.py

@@ -195,7 +195,7 @@ def main() -> None:
                 },
             },
             "components": {"upsampler_weights": str(refine_upsampler_path)},
-            "ltx2": {"refine": {"lora_path": ""}},
+            "model": {"ltx2": {"refine": {"lora_path": ""}}},
             "experimental": {"pipeline_config": pipeline_config},
             "vae_tiling": False,
         },

examples/inference/basic/basic_ltx2_3_distilled_i2v_typed.py

@@ -54,7 +54,7 @@ Recipe setting ↔ typed field
 - VAE tiling                       ↔ ``pipeline.vae_tiling``
 - Refine stage on                  ↔ ``pipeline.preset_overrides["refine"]["enabled"]``
 - Refine upsampler                 ↔ ``pipeline.components.upsampler_weights``
-- Refine LoRA                      ↔ ``pipeline.ltx2.refine.lora_path``
+- Refine LoRA                      ↔ ``pipeline.model.ltx2.refine.lora_path``
 - Refine denoising steps           ↔ ``pipeline.preset_overrides["refine"]["num_inference_steps"]``
 - Refine guidance scale            ↔ ``pipeline.preset_overrides["refine"]["guidance_scale"]``
 - Refine noise injection           ↔ ``pipeline.preset_overrides["refine"]["add_noise"]``

examples/inference/basic/basic_ltx2_distilled_fast_profile.py

@@ -234,7 +234,7 @@ def main() -> None:
                 },
             },
             "components": {"upsampler_weights": str(refine_upsampler_path)},
-            "ltx2": {"refine": {"lora_path": ""}},  # keep refine LoRA disabled for distilled model
+            "model": {"ltx2": {"refine": {"lora_path": ""}}},  # keep refine LoRA disabled for distilled model
             "experimental": {
                 "pipeline_config": pipeline_config,
             },