diffusers-workflow 0.14.0__tar.gz → 0.16.0__tar.gz

{diffusers_workflow-0.14.0/diffusers_workflow.egg-info → diffusers_workflow-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: diffusers-workflow
-Version: 0.14.0
+Version: 0.16.0
 Summary: Declarative workflow engine and web UI for Hugging Face Diffusers
 Author: dkackman
 License: Apache-2.0
@@ -37,6 +37,7 @@ Requires-Dist: controlnet-aux>=0.0.10
 Requires-Dist: opencv-python-headless>=5.0.0.93
 Requires-Dist: kornia>=0.8.3
 Requires-Dist: kernels>=0.17.2
+Requires-Dist: comfy-kitchen<0.3,>=0.2.38
 Requires-Dist: spandrel>=0.4.2
 Requires-Dist: facexlib>=0.3.0
 Requires-Dist: numpy>=2.5.4

{diffusers_workflow-0.14.0 → diffusers_workflow-0.16.0/diffusers_workflow.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: diffusers-workflow
-Version: 0.14.0
+Version: 0.16.0
 Summary: Declarative workflow engine and web UI for Hugging Face Diffusers
 Author: dkackman
 License: Apache-2.0
@@ -37,6 +37,7 @@ Requires-Dist: controlnet-aux>=0.0.10
 Requires-Dist: opencv-python-headless>=5.0.0.93
 Requires-Dist: kornia>=0.8.3
 Requires-Dist: kernels>=0.17.2
+Requires-Dist: comfy-kitchen<0.3,>=0.2.38
 Requires-Dist: spandrel>=0.4.2
 Requires-Dist: facexlib>=0.3.0
 Requires-Dist: numpy>=2.5.4

{diffusers_workflow-0.14.0 → diffusers_workflow-0.16.0}/diffusers_workflow.egg-info/SOURCES.txt

@@ -52,6 +52,7 @@ dw/output_extraction.py
 dw/path_redaction.py
 dw/pipeline_ownership.py
 dw/plan.py
+dw/plan_downloads.py
 dw/previous_results.py
 dw/probe_paths.py
 dw/prompt_schema.json
@@ -75,6 +76,7 @@ dw/settings.py
 dw/shot_span_preflight.py
 dw/shots.py
 dw/slice_preflight.py
+dw/sparse_attention.py
 dw/step.py
 dw/step_cache.py
 dw/step_value_checks.py
@@ -134,6 +136,8 @@ dw/pipeline_processors/h3_guides.py
 dw/pipeline_processors/h3_hold.py
 dw/pipeline_processors/h3_hold_steps.py
 dw/pipeline_processors/h3_rules.py
+dw/pipeline_processors/h3_tiles.py
+dw/pipeline_processors/mag_calibration.py
 dw/pipeline_processors/pipeline.py
 dw/pipeline_processors/placement.py
 dw/pipeline_processors/progress.py
@@ -192,44 +196,44 @@ dw/server/ui/assets/csharp-BKxtCVv1.js
 dw/server/ui/assets/csp-bTuwJoIa.js
 dw/server/ui/assets/css-DIMkf-bt.js
 dw/server/ui/assets/css.worker-C6lDtRpF.js
-dw/server/ui/assets/cssMode-BM_j_5VW.js
+dw/server/ui/assets/cssMode-Cx99RWkL.js
 dw/server/ui/assets/cypher-CVaqCwHa.js
 dw/server/ui/assets/dart-onAF5SnQ.js
 dw/server/ui/assets/dockerfile-DZFCIeNp.js
 dw/server/ui/assets/ecl-D05T4iGw.js
 dw/server/ui/assets/editor-DjpsE8to.css
-dw/server/ui/assets/editor.api-CEPMtaHf.js
+dw/server/ui/assets/editor.api-jKhYFhrF.js
 dw/server/ui/assets/editor.worker-BmdWdrHZ.js
 dw/server/ui/assets/elixir-6RTg0lbw.js
 dw/server/ui/assets/flow9-C5_-GSwl.js
-dw/server/ui/assets/freemarker2-BVTL0E_v.js
+dw/server/ui/assets/freemarker2-Cr_kdwwJ.js
 dw/server/ui/assets/fsharp-C8Ef5oNN.js
 dw/server/ui/assets/go-C-y9NEjX.js
 dw/server/ui/assets/graphql-fmXr3nnJ.js
-dw/server/ui/assets/handlebars-DN1SqR7g.js
+dw/server/ui/assets/handlebars-CnbOycVf.js
 dw/server/ui/assets/hcl-CpzslTdj.js
-dw/server/ui/assets/html-BYdDV855.js
+dw/server/ui/assets/html-vCIOVoPc.js
 dw/server/ui/assets/html.worker-C5yZDBHz.js
-dw/server/ui/assets/htmlMode-CktrpppH.js
-dw/server/ui/assets/index-Dd1gXnAH.js
-dw/server/ui/assets/index-PRSQwOeN.css
+dw/server/ui/assets/htmlMode-B5ESZlHK.js
+dw/server/ui/assets/index-Bm_jBlG4.css
+dw/server/ui/assets/index-DIXj1Pp3.js
 dw/server/ui/assets/ini-sBoK_t0W.js
 dw/server/ui/assets/java-BEtHBSE6.js
-dw/server/ui/assets/javascript-DvSbrt_n.js
+dw/server/ui/assets/javascript-DpV2UaWD.js
 dw/server/ui/assets/json.worker-DdeUAmHa.js
-dw/server/ui/assets/jsonMode-CXzErKKD.js
+dw/server/ui/assets/jsonMode-DaGlZZy1.js
 dw/server/ui/assets/julia-Bri6UV-V.js
 dw/server/ui/assets/kotlin-BOotOW0E.js
 dw/server/ui/assets/less-B9JPFI3C.js
 dw/server/ui/assets/lexon-CfSJPG6W.js
-dw/server/ui/assets/liquid-BRCKFwoi.js
-dw/server/ui/assets/lspLanguageFeatures-njtWwPtu.js
+dw/server/ui/assets/liquid-Ds835QKV.js
+dw/server/ui/assets/lspLanguageFeatures-Cd9OxrIO.js
 dw/server/ui/assets/lua-CsQS60Ue.js
 dw/server/ui/assets/m3-D-oSqn_W.js
 dw/server/ui/assets/markdown-Cimd5fb3.js
-dw/server/ui/assets/mdx-BUaukvEP.js
+dw/server/ui/assets/mdx-BozOHFIi.js
 dw/server/ui/assets/mips-CIPQ_RoX.js
-dw/server/ui/assets/monaco-gga5ZcVz.js
+dw/server/ui/assets/monaco-673w9Wwq.js
 dw/server/ui/assets/monaco-n7clI0si.css
 dw/server/ui/assets/msdax-DauUninz.js
 dw/server/ui/assets/mysql-SOo6toE5.js
@@ -245,10 +249,10 @@ dw/server/ui/assets/powerquery-D3hlyOfw.js
 dw/server/ui/assets/powershell-DmHpPYUd.js
 dw/server/ui/assets/protobuf-C531GsRP.js
 dw/server/ui/assets/pug-Z5eAx3Zn.js
-dw/server/ui/assets/python-BlUYF5iw.js
+dw/server/ui/assets/python-D_HjE-WC.js
 dw/server/ui/assets/qsharp-DkqhCAOL.js
 dw/server/ui/assets/r-BwWrilGY.js
-dw/server/ui/assets/razor-C_60BEWv.js
+dw/server/ui/assets/razor-DjEZAQZw.js
 dw/server/ui/assets/redis-ClamHrr6.js
 dw/server/ui/assets/redshift-DT7zqm-g.js
 dw/server/ui/assets/restructuredtext-BYgofb2h.js
@@ -268,15 +272,15 @@ dw/server/ui/assets/swift-Bxkupp3x.js
 dw/server/ui/assets/systemverilog-Bz4Y3fRF.js
 dw/server/ui/assets/tcl-DISqw1ZD.js
 dw/server/ui/assets/ts.worker-DGGa2mF8.js
-dw/server/ui/assets/tsMode-DZ39FkiR.js
+dw/server/ui/assets/tsMode-B3g7-HAd.js
 dw/server/ui/assets/twig-De2hgUGE.js
-dw/server/ui/assets/typescript-DRuDz-v_.js
+dw/server/ui/assets/typescript-Bq3yLFs6.js
 dw/server/ui/assets/typespec-B8J7ngcE.js
 dw/server/ui/assets/vb-DV3o63ZY.js
 dw/server/ui/assets/wgsl-DpFanUEy.js
-dw/server/ui/assets/workers-BWXmwymL.js
-dw/server/ui/assets/xml-CBshcw4i.js
-dw/server/ui/assets/yaml-D1ZImLMB.js
+dw/server/ui/assets/workers-Jt2I7Jya.js
+dw/server/ui/assets/xml-BD0Sm95a.js
+dw/server/ui/assets/yaml-BSnko3ic.js
 dw/tasks/assess.py
 dw/tasks/audio_dynamics.py
 dw/tasks/audio_handlers.py
@@ -315,9 +319,11 @@ dw/tasks/model_handlers.py
 dw/tasks/pair_audio.py
 dw/tasks/qr_code.py
 dw/tasks/registry.py
+dw/tasks/remove_object.py
 dw/tasks/restore_faces.py
 dw/tasks/rife_model.py
 dw/tasks/script_check.py
+dw/tasks/script_take.py
 dw/tasks/segment.py
 dw/tasks/select.py
 dw/tasks/speech_generation.py
@@ -331,8 +337,11 @@ dw/tasks/upscale.py
 dw/tasks/video_handlers.py
 dw/tasks/video_utils.py
 dw/tasks/voice_attribution.py
+dw/tasks/weights.py
 dw/tasks/windows.py
 dw/tasks/zoe_depth.py
+dw/workflows/flux3_klein_upsample.json
+dw/workflows/flux3_klein_upsample_edit.json
 dw/workflows/h3_context_ir.json
 dw/workflows/test.json
 dw_mcp/__init__.py
@@ -379,6 +388,7 @@ tests/test_catalog_shape.py
 tests/test_catalog_speed_defaults.py
 tests/test_catalog_structure.py
 tests/test_chain.py
+tests/test_chain_h3_native.py
 tests/test_ci_config.py
 tests/test_cli.py
 tests/test_compare_route.py
@@ -390,6 +400,7 @@ tests/test_concat_videos.py
 tests/test_config_objects.py
 tests/test_configuration_schema.py
 tests/test_content_types.py
+tests/test_dependencies_declared.py
 tests/test_depth_estimator.py
 tests/test_device.py
 tests/test_device_helpers.py
@@ -411,12 +422,14 @@ tests/test_find_loop_bed.py
 tests/test_finish.py
 tests/test_fit_templates.py
 tests/test_fit_to_model.py
+tests/test_flux3_catalog.py
 tests/test_for_each.py
 tests/test_forget_workspace_history.py
 tests/test_gallery_roles.py
 tests/test_gather.py
 tests/test_grade.py
 tests/test_guide_chain_validation.py
+tests/test_guide_pointers.py
 tests/test_guides_validation.py
 tests/test_h3_adapters.py
 tests/test_h3_context_ir.py
@@ -426,6 +439,8 @@ tests/test_h3_latent_upscale.py
 tests/test_h3_refine.py
 tests/test_h3_rules.py
 tests/test_h3_schedule.py
+tests/test_h3_sparse_defaults.py
+tests/test_h3_tiles.py
 tests/test_h3_upscaler_source.py
 tests/test_h3_vram_ceiling.py
 tests/test_hf_placement.py
@@ -443,6 +458,7 @@ tests/test_integration.py
 tests/test_interpolate_frames.py
 tests/test_introspection.py
 tests/test_job_history_device.py
+tests/test_job_history_parity.py
 tests/test_job_history_wal.py
 tests/test_job_progress.py
 tests/test_job_warnings.py
@@ -533,6 +549,7 @@ tests/test_reference_limits.py
 tests/test_reference_names.py
 tests/test_reference_skip_sets.py
 tests/test_references.py
+tests/test_remove_object.py
 tests/test_rerun_lineage.py
 tests/test_rerun_new_seed.py
 tests/test_resize_bucket.py
@@ -550,6 +567,7 @@ tests/test_scalar_result_validation.py
 tests/test_scheduler_config.py
 tests/test_schema.py
 tests/test_script_check.py
+tests/test_seam_look.py
 tests/test_security.py
 tests/test_security_auth.py
 tests/test_security_decoder_bombs.py
@@ -579,6 +597,10 @@ tests/test_shaping_logs.py
 tests/test_shot_span_preflight.py
 tests/test_shots.py
 tests/test_slice_preflight.py
+tests/test_sparse_attention_backends.py
+tests/test_sparse_attention_processor.py
+tests/test_sparse_attention_tiles.py
+tests/test_sparse_attention_wiring.py
 tests/test_speech_generation.py
 tests/test_stabilize.py
 tests/test_stars.py
@@ -591,9 +613,11 @@ tests/test_subfolders.py
 tests/test_task.py
 tests/test_task_discovery.py
 tests/test_task_domains.py
+tests/test_task_file_weights.py
 tests/test_task_public_imports.py
 tests/test_task_registry_rules.py
 tests/test_task_signature_errors.py
+tests/test_task_weights.py
 tests/test_template_defaults.py
 tests/test_template_subfolders.py
 tests/test_tensor_image.py
@@ -631,4 +655,5 @@ tests/test_workflow_snapshot.py
 tests/test_workflow_step_cache.py
 tests/test_workflow_trust.py
 tests/test_workspace.py
-tests/test_workspace_copy.py
+tests/test_workspace_copy.py
+tests/test_zimage_vram.py

{diffusers_workflow-0.14.0 → diffusers_workflow-0.16.0}/diffusers_workflow.egg-info/requires.txt

@@ -18,6 +18,7 @@ controlnet-aux>=0.0.10
 opencv-python-headless>=5.0.0.93
 kornia>=0.8.3
 kernels>=0.17.2
+comfy-kitchen<0.3,>=0.2.38
 spandrel>=0.4.2
 facexlib>=0.3.0
 numpy>=2.5.4

{diffusers_workflow-0.14.0 → diffusers_workflow-0.16.0}/dw/acceleration_warnings.py

@@ -27,6 +27,9 @@ Each of these cost a render to find out in Don's `h3-quality` matrix:
   cache's skip decision needs (`docs/ACCELERATION.md`).
 - `attention_backend_unavailable`: a CUDA-only attention backend on a device
   that isn't CUDA passes validate and fails at load.
+- `sparse_attention_fallback`: the `sparse` attention backend on a device that
+  isn't CUDA. It never fails a run: it falls back to dense attention, so this
+  says the speedup is not coming, not that the job will break.
 
 Every one is a warning and never a refusal. A value that cannot be resolved
 before the run (a null variable, an unknown device) leaves its warning
@@ -39,6 +42,8 @@ import typing
 from . import get_device_type
 from .introspection import load_pipeline_class
 from .references import iter_steps, render_path
+from . import sparse_attention
+from .sparse_attention import SPARSE_BACKEND
 from .vram_estimate import required_vram_gb
 
 # The fewest denoise steps a threshold cache is expected to skip any of. A
@@ -82,10 +87,11 @@ SHORT_SCHEDULE = "cache_short_schedule"
 TAYLORSEER_STATE = "taylorseer_state_unestimated"
 FULLGRAPH_WITH_CACHE = "compile_fullgraph_with_cache"
 BACKEND_UNAVAILABLE = "attention_backend_unavailable"
+SPARSE_FALLBACK = "sparse_attention_fallback"
 CACHE_UNSUPPORTED = "cache_unsupported"
 
 # The component names a cache hook attaches to, as in
-# dw.pipeline_processors.components.get_cache_transformer
+# dw.pipeline_processors.mag_calibration.get_cache_transformer
 _CACHE_COMPONENTS = ("transformer", "transformer_ref")
 
 
@@ -258,6 +264,13 @@ def acceleration_warnings(context):
             continue
         for path, block in backends:
             name = block.get("attention_backend")
+            if name == SPARSE_BACKEND:
+                warnings.append(
+                    f"{render_path(path)}: {SPARSE_FALLBACK}: sparse attention "
+                    f"needs CUDA; this server is '{context.device_type}', so "
+                    f"the run uses dense attention{where}"
+                )
+                continue
             if name not in CUDA_ONLY_ATTENTION_BACKENDS:
                 continue
             warnings.append(
@@ -273,3 +286,26 @@ def acceleration_warnings(context):
         path, _, rest = warning.partition(": ")
         said.setdefault((path, rest.partition(": ")[0]), warning)
     return list(said.values())
+
+
+def available_attention_backends(device_type: str) -> list[str]:
+    """The attention backends a server on `device_type` can run, in menu order.
+
+    `native` first, then the other `native`-family names; on CUDA, `sparse`
+    (only where the compiled kernels loaded) and the CUDA-only names. A name
+    diffusers' `AttentionBackendName` lacks is dropped, so the menu never
+    offers one the pipeline would refuse.
+    """
+    from diffusers.models.attention_dispatch import AttentionBackendName
+
+    known = {backend.value for backend in AttentionBackendName}
+    cuda = device_type == "cuda"
+    names = ["native", "_native_flash", "_native_efficient", "_native_math"]
+    if cuda:
+        names.append("_native_cudnn")
+    names.append("flex")
+    if cuda:
+        if sparse_attention._kernels_importable():
+            names.append(SPARSE_BACKEND)
+        names.extend(sorted(CUDA_ONLY_ATTENTION_BACKENDS))
+    return [name for name in names if name == SPARSE_BACKEND or name in known]

{diffusers_workflow-0.14.0 → diffusers_workflow-0.16.0}/dw/adapter_compatibility.py

@@ -312,6 +312,21 @@ DISABLED_MESSAGE = (
 )
 
 
+# Step-distillation loras run in 4-9 steps; a null-lora step at or past this
+# has already been given the base model's schedule, so the warning is stale.
+RAISED_STEPS = 10
+
+
+def _schedule_raised(pipeline):
+    arguments = pipeline.get("arguments")
+    steps = (
+        arguments.get("num_inference_steps") if isinstance(arguments, dict) else None
+    )
+    return (
+        isinstance(steps, int) and not isinstance(steps, bool) and steps >= RAISED_STEPS
+    )
+
+
 def _disabled_loras(steps, source_indices, written=None, supplied=()):
     """Every `loras` entry switched off with a null model_name, as
     (path, message). Any pipeline, not only H3: the off switch is the
@@ -322,7 +337,7 @@ def _disabled_loras(steps, source_indices, written=None, supplied=()):
         steps, source_indices, "pipeline"
     ):
         loras = pipeline.get(LORAS_KEY)
-        if not isinstance(loras, list):
+        if not isinstance(loras, list) or _schedule_raised(pipeline):
             continue
         for position, lora in enumerate(loras):
             if not isinstance(lora, dict) or lora.get(MODEL_NAME_KEY) is not None:

{diffusers_workflow-0.14.0 → diffusers_workflow-0.16.0}/dw/argument_media.py

@@ -220,7 +220,7 @@ def _with_frame_rate(frames, location):
     only looks at a real local path. A file that says neither stays a plain
     list.
     """
-    from .tasks.video_utils import FrameList
+    from .media_types import FrameList
 
     if not isinstance(frames, list):
         return frames
@@ -273,7 +273,7 @@ def local_media_file(location, what, default_suffix=""):
 
 def _fetch_remote_video(url):
     """A video URL's frames, decoded from `local_media_file`'s copy."""
-    from .tasks.video_utils import FrameList
+    from .media_types import FrameList
 
     with local_media_file(url, "a video argument", default_suffix=".mp4") as path:
         frames = load_video(path)

{diffusers_workflow-0.14.0 → diffusers_workflow-0.16.0}/dw/devices.py

@@ -109,7 +109,7 @@ def check_device_present(device):
         raise DeviceConfigError(f"{device} is not available on this machine")
 
 
-def resolve_serve_devices(cli_value, settings_value):
+def resolve_serve_devices(cli_value, settings_value, on_absent=None):
     """The devices a server runs on - `--devices`, else the `devices`
     setting - or None when neither names any, which leaves today's single
     device (`DW_DEVICE`, then the `device` setting, then detection) alone.
@@ -117,7 +117,14 @@ def resolve_serve_devices(cli_value, settings_value):
     More than one entry runs a worker per card, so each must be a card of
     its own. Raises DeviceConfigError for a duplicate, for an unindexed
     `cuda` in a list of several (it would not be pinned, and would share
-    card 0), and for a device this machine does not have."""
+    card 0), and for a device this machine does not have.
+
+    A list of several survives a card being pulled: an absent entry is
+    dropped and its refusal passed to `on_absent`, so a box with a card
+    out for service comes up on the rest instead of refusing to start (a
+    service manager restarting it would loop forever). Only when no entry
+    is present - or `on_absent` is None - is the first absence raised, so
+    a lone typo (`cuda:7`) still refuses."""
     raw = cli_value if cli_value else settings_value
     devices = parse_devices(raw)
     if not devices:
@@ -139,9 +146,19 @@ def resolve_serve_devices(cli_value, settings_value):
                 "--devices with several entries must name each CUDA card by "
                 "index ('cuda:0,cuda:1'), not a bare 'cuda'"
             )
+    present, absences = [], []
     for device in devices:
-        check_device_present(device)
-    return devices
+        try:
+            check_device_present(device)
+        except DeviceConfigError as absence:
+            absences.append(absence)
+        else:
+            present.append(device)
+    if absences and (not present or on_absent is None):
+        raise absences[0]
+    for absence in absences:
+        on_absent(str(absence))
+    return present
 
 
 def _explicit_cuda_index(device):

{diffusers_workflow-0.14.0 → diffusers_workflow-0.16.0}/dw/docs/ACCELERATION.md

@@ -159,20 +159,58 @@ Select the attention implementation diffusers uses for the duration of each pipe
 }
 ```
 
-Common values: `"flash"`, `"flash_hub"`, `"sage"`, `"sage_hub"`, `"native"`, `"flex"`. The full set is diffusers' `AttentionBackendName` enum - availability depends on what's installed (`flash-attn`, `sageattention`, etc.) and the platform. `_hub`-suffixed backends are fetched from the Hugging Face Hub kernel registry on first use, which needs the `kernels` package installed (`pip install kernels`) - it is not a dw dependency, and no bundled workflow sets a backend, so each runs on a plain install. diffusers also refuses a Hub kernel whose publisher it does not list as trusted - `sage_hub` among them, since SageAttention 2 comes from `SageAttention/sage-attention` - until `DIFFUSERS_TRUST_REMOTE_KERNELS=true`, which allows remote code from any such publisher. On an RTX 3090 `sage_hub` measured about 30% faster per MiniMax-H3 step (13.8 s against 19.2 s at 960x544x124, 54.7 s against 81.2 s at 345 frames); the local `sage` backend needs `sageattention>=2.1.1`, which PyPI does not carry.
+Common values: `"flash"`, `"flash_hub"`, `"sage"`, `"sage_hub"`, `"native"`, `"flex"`. The full set is diffusers' `AttentionBackendName` enum - availability depends on what's installed (`flash-attn`, `sageattention`, etc.) and the platform. `_hub`-suffixed backends are fetched from the Hugging Face Hub kernel registry on first use, which needs the `kernels` package installed (`pip install kernels`) - it is not a dw dependency. The only backend a bundled workflow sets is `sparse`, the default on every MiniMax-H3 template, and it needs no `kernels` install (comfy-kitchen is a core dependency), so each bundled workflow runs on a plain install. diffusers also refuses a Hub kernel whose publisher it does not list as trusted - `sage_hub` among them, since SageAttention 2 comes from `SageAttention/sage-attention` - until `DIFFUSERS_TRUST_REMOTE_KERNELS=true`, which allows remote code from any such publisher. On an RTX 3090 `sage_hub` measured about 30% faster per MiniMax-H3 step (13.8 s against 19.2 s at 960x544x124, 54.7 s against 81.2 s at 345 frames); the local `sage` backend needs `sageattention>=2.1.1`, which PyPI does not carry.
 
 Every MiniMax-H3 template in [templates/minimax/](../workflows/templates/minimax/)
 exposes this as a variable: `attention_backend`, pinned on the H3 step's transformer
 (`components.transformer`, or `components.transformer_ref` for a ref2va workflow) and
-`null` by default. That covers the shots, chains and episodes - `dialogue-short`,
+`"sparse"` by default (with `sparse_tau`, below). That covers the shots, chains and episodes - `dialogue-short`,
 `shots-batch`, `music-video` and `storyboard` among them - and only their H3 steps: a
 Z-Image still or Music3 song beside an H3 shot keeps the process default. Pass
-`attention_backend=sage_hub` to a box with the `kernels` package and
-`DIFFUSERS_TRUST_REMOTE_KERNELS=true` in its `.env`; on MPS leave it null, since a
-CUDA-only kernel fails there at load (validation warns, below). LTX-2.5 cannot use it: its transformer
+`attention_backend=sage_hub` (or `native`) to override the default; `sage_hub` needs a box with the `kernels` package and
+`DIFFUSERS_TRUST_REMOTE_KERNELS=true` in its `.env`; on MPS the default falls back to dense, but a CUDA-only kernel such as `sage_hub` fails there at load (validation warns, below). LTX-2.5 cannot use it: its transformer
 passes an attention mask, and sage attention refuses one ("`attn_mask` is not supported
 for sage attention", measured 2026-10-10), so the LTX templates expose no backend.
 
+### `sparse` (MiniMax-H3)
+
+`attention_backend: "sparse"` runs H3's attention through comfy-kitchen's block-sparse kernel: each query tile attends only to the key tiles that matter, so the cost of the long video-token sequence falls. It applies to the H3 transformer only, at pipeline or component level, and is the default on every H3 template (#931). Set at both levels, the component's own `attention_backend` wins, as it does for every backend: a pipeline-level `sparse` skips a component pinned to `sage_hub` (or anything else) and warns `attention_backend 'sparse' at pipeline level skips '<component>', which pins '<backend>'`. When it does install, the run logs `Using attention backend: sparse (tau <tau>) on <components>`, or `(topk <k>)` with top-k routing. `sparse_tau` (number, minimum 0, default 0.5; anything else, such as a `variable:` that resolves to a string or a bool, fails the step rather than running dense) sets how much of the attention mass a tile may drop; 0 keeps the most. Observed at Ref2VA 1344x768, seed 42: tau 1.0 ran 42.1 s/forward against 44.8 s at 0.5, and by Don's eye 1.0 gave smoother skin while 0.5 matched dense (the table below). That is one shape and one seed, not a rule that higher is always faster or smoother.
+
+`sparse_topk` (a number strictly between 0 and 1; the H3 templates set 0.15, and a workflow that sets none routes by `sparse_tau`) switches the kernel to top-k routing: each query tile keeps that fraction of key tiles and drops the rest outright, with `sparse_tau` ignored. It is the selection lightx2v's Turbo-SLA LoRAs were trained against (85% sparsity, so `0.15`). Measured on `video-with-audio-768p`, seed 42 (#932): top-k 0.15 ran 21.1 s/forward against 23.6 s at tau 0.5, about 11% faster, and Don saw no difference on that clip, with either the Turbo-SLA LoRA or the default v1.2 turbo (so dw does not adopt the SLA LoRA). That clip has no faces, so it was checked on the H3 quality ramp's 4-reference sitcom shot at seeds 42, 7 and 1234 against tau 0.5. Don judged top-k equal or better: on the turbo L7 rung tau showed blue ghosting at seed 7 and slight smearing at all three, and on the 30-step base-model L5 rung the skin held. Top-k 0.15 is therefore the H3 templates' default; pass `sparse_topk=null` to route by `sparse_tau` instead.
+
+| rung (minutes per job, seeds 42 / 7 / 1234) | tau 0.5 | top-k 0.15 |
+|---|---|---|
+| L7: ref2v 4-step turbo, int8 | 6.5 / 6.5 / 6.5 | 6.1 / 6.2 / 5.8 |
+| L5: base model, int8, 30 steps | 26.8 / 26.6 / 26.4 | 23.9 / 25.5 / 23.9 |
+
+**What the default buys depends on what it replaces.** Against `native` attention, which is what an H3 template ran before #931 unless `attention_backend` was set, sparse is 2.2-4.4x faster per step. Against `sage_hub`, the gain is much smaller: 6-16% depending on the shape (the second table). So sparse's main win is for a run that set no backend, and it needs no `kernels` package or `DIFFUSERS_TRUST_REMOTE_KERNELS`. A box already on `sage_hub` gains a little, at equal quality: on the H3 skill's quality-ramp rungs, Don judged faces, skin and draft-to-final staging equal under both backends across three seeds (#931 stage 3).
+
+Measured on an RTX 3090, seed 42, s per transformer forward (one per denoise step), lower is faster:
+
+| shape | native | `sage_hub` | sparse | sparse vs native | sparse vs `sage_hub` |
+|---|---|---|---|---|---|
+| T2VA 960x544, 4-step turbo, tau 1.0 | 24.3 | - | 10.8 | 2.25x | - |
+| T2VA 1344x768, 4-step turbo, tau 1.0 | 96.1 | - | 21.9 | 4.38x | - |
+| Ref2VA 1344x768, 8-step ref2v turbo, tau 1.0 | 108.4 | - | 42.1 | 2.58x | - |
+| Ref2VA 1344x768, 8-step ref2v turbo, tau 0.5 (the default) | 108.4 | 51.0 | 44.1-44.8 | 2.42x | 1.16x |
+
+Wall time, same order: 150 -> 95 s, 457 -> 158 s, 965 -> 430 s, and for the last row 965 s native, 489 s `sage_hub`, 442-450 s sparse.
+
+Against `sage_hub` on the H3 skill's quality-ramp rungs (ep 6 cold open, 4 references, 1344x768, 124 frames; minutes per job, seeds 42 / 7 / 1234, all on the same diffusers):
+
+| rung | `sage_hub` | sparse | sparse vs `sage_hub` |
+|---|---|---|---|
+| L1: ref2v 4-step turbo, int4, 5 steps | 5.5 / 5.5 / 5.5 | 5.2 / 5.2 / 5.1 | 1.06-1.08x |
+| L7: ref2v 4-step turbo, int8, 5 steps | 7.1 / 6.9 / 7.1 | 6.5 / 6.5 / 6.5 | 1.06-1.09x |
+| B3: base model, int8, 12 steps | 13.0 / 12.9 / 12.9 | 12.3 / 12.0 / 12.1 | 1.06-1.07x |
+| L5: base model, int8, 30 steps | 29.7 / 29.7 / 29.7 | 26.8 / 26.6 / 26.4 | 1.11-1.12x |
+
+The `first_block` cache on `sage_hub` (23.1 min at L5's settings) is still faster than sparse alone there; sparse with that cache is not measured. The native and tau 1.0 figures come from the #931 prototype. The `sage_hub` figure and the 44.1 s come from the engine on lem after the deploy, with a newer diffusers (jobs 94c04976d21d and 593131ca713f), so the sage comparison is between those two jobs only. The T2VA rows have no `sage_hub` run. Peak VRAM did not change. Judged by eye, tau 0.5 matched dense; tau 1.0 was smoother in skin.
+
+It needs CUDA with compute capability 8.0 or higher. Anywhere else (MPS, CPU, an older card, an unsupported dtype or head size) the run goes dense instead of failing, and says so twice: `validate_workflow` warns `sparse_attention_fallback` when the server's device is not CUDA, and the run reports `<label>: sparse attention ran dense - <reason>` once per pipeline call. A job of one call warns once; a chained, `shots-batch` or `dialogue-short` job calls the pipeline once per segment or shot, so it warns once for each, under that segment's or shot's label. A comfy-kitchen kernel that fails on its first invocation in a call also runs that call dense, with `sparse kernel failed: <error>` as the reason; one that fails after it has run in the call fails the run, since some blocks have already run sparse.
+
+Unlike sage, sparse **moves composition** relative to dense: the same subject, story and cuts, but different framing and set dressing. A draft and its final must therefore use the same backend; mixing `sparse` and `sage_hub` between tiers means the draft no longer predicts the final.
+
 A component can also pin its backend persistently instead, via `set_attention_backend`:
 
 ```json