Add a 28-step vs 8-step turbo LoRA sampling choice (lightx2v/Minimax-h3-Turbo)

README.md

@@ -12,6 +12,7 @@ short_description: Drive a world model with WASD and camera keys
 models:
   - MiniMaxAI/MiniMax-H3
   - DANNY621/H3-World
+  - lightx2v/Minimax-h3-Turbo
 ---
 
 # H3-World — action-conditioned world model
@@ -122,6 +123,39 @@ gate/value halves swapped, and the fused `attn.qkv_proj` de-interleaved per head
 `to_q` / `to_k` / `to_v`. 104 LoRA pairs become 208 merged weight deltas; **any target that fails to resolve is
 fatal**, never skipped.
 
+## 28 steps vs the 8-step turbo LoRA
+
+**Sampling** in the UI picks between two configurations of the same request — same seed, same action
+script, same directed mask — so the quality cost of the distillation is directly visible:
+
+| mode | steps | transformer |
+|---|---|---|
+| `28 steps · no turbo LoRA` | 28 (MiniMax-H3's default) | H3-World only |
+| `8 steps · turbo LoRA` | 8 | H3-World **+** [`lightx2v/Minimax-h3-Turbo`](https://huggingface.co/lightx2v/Minimax-h3-Turbo) `minimax_h3_fl2v_turbo_8step_v1.0_bf16.safetensors` |
+
+`h3_turbo_lora.py` mirrors the `h3_lora.py` of the Spaces that already run this adapter —
+[`MiniMaxAI/MiniMax-H3-Turbo-Lora`](https://huggingface.co/spaces/MiniMaxAI/MiniMax-H3-Turbo-Lora)
+(its `lightx` set) and
+[`hugging-apps/minimax-h3-turbo-sla-demo`](https://huggingface.co/spaces/hugging-apps/minimax-h3-turbo-sla-demo):
+
+* the file is a **PEFT checkpoint against the diffusers module tree itself**
+  (`transformer_blocks.N.attn.to_q.lora_A.default.weight`), so unlike H3-World it needs no key
+  conversion — 312 targets (50 transformer blocks + 2 token-refiner blocks x
+  `to_q`/`to_k`/`to_v`/`to_out.0`/`ff.net.0.proj`/`ff.net.2`) map name-for-name;
+* rank 128 with `alpha: 8` in the file's own safetensors metadata, so the fold scale is
+  `alpha / rank = 0.0625` — what `set_adapters(weights=1.0)` applies in lightx2v's reference script;
+* the step count is overridden to the distillation's own **8 NFE**. No scheduler swap and no CFG
+  change: MiniMax-H3 is already guidance-distilled and every Space above keeps its native
+  `MiniMaxH3Scheduler` with the turbo LoRA folded.
+
+It is *folded* into the bf16 weights, like H3-World, because this Space patches
+`MiniMaxH3AttnProcessor` and drives the transformer's live weights. Fold and unfold are the same
+operation with a sign, so the low-rank factors stay resident and `set_active` flips the mode in
+place inside the `@spaces.GPU` call, through one bf16 rounding.
+
+The Steps slider still overrides the mode's count (4–50), so `50 steps + turbo LoRA` or
+`8 steps without it` are both reachable for the sake of the comparison.
+
 ## Generation constraints
 
 Fixed by the checkpoint: 24 fps, `num_frames` snapped to `17n + 5`, no CFG and no negative prompt (it is
@@ -160,6 +194,11 @@ manifest prompt.
 | `H3_MODEL_REPO` | `MiniMaxAI/MiniMax-H3` | The diffusers-layout base checkpoint. |
 | `H3_LORA_REPO` | `DANNY621/H3-World` | The LoRA. |
 | `H3_LORA_FILE` | `step-10000.safetensors` | The checkpoint the author's own test runs used. |
+| `H3_TURBO_REPO` | `lightx2v/Minimax-h3-Turbo` | The turbo-LoRA repo. |
+| `H3_TURBO_FILE` | `minimax_h3_fl2v_turbo_8step_v1.0_bf16.safetensors` | The 8-step distillation. |
+| `H3_TURBO_STEPS` | `8` | Steps the turbo mode asks for (the card also offers 4). |
+| `H3_TURBO_ALPHA` | `0` | `0` reads `alpha` out of the file's metadata (`8`). |
+| `H3_TURBO_STRENGTH` | `1.0` | Extra multiplier on the turbo delta. |
 | `H3_CONDITIONER` | `multimodalart/qwen3vl-conditioner` | The Space this one asks for embeddings. |
 | `H3_ATTENTION` | `_native_cudnn` | cuDNN's fused kernel. flash-attention 3 is sm90-only; this pool is sm120. |
 | `H3_GPU_SIZE` | `xlarge` | ZeroGPU allocation size. `large` does not fit. |

app.py

@@ -48,6 +48,8 @@ import spaces
 import gradio as gr
 import torch
 
+import h3_turbo_lora
+
 MODEL_REPO = os.environ.get("H3_MODEL_REPO", "MiniMaxAI/MiniMax-H3")
 LORA_REPO = os.environ.get("H3_LORA_REPO", "DANNY621/H3-World")
 LORA_FILE = os.environ.get("H3_LORA_FILE", "step-10000.safetensors")
@@ -59,11 +61,21 @@ GPU_SIZE = os.environ.get("H3_GPU_SIZE", "xlarge")
 FPS, FRAMES_PER_CHUNK, LATENTS_PER_CHUNK = 24, 17, 5
 MIN_UI_DURATION, MAX_UI_DURATION = 2, 8
 # The H3-World inference runs recorded in the checkpoint's own manifests: 124 frames, 480x832, 24 fps,
-# 50 steps, seed 0. Keep those as the defaults so the Space reproduces the released results.
+# 50 steps, seed 0. 50 is still reachable on the Steps slider (it is its maximum).
 DEFAULT_DURATION = 5
-DEFAULT_STEPS = 50
+DEFAULT_STEPS = 28
 DEFAULT_SUBJECT = "the man"
 
+# The two sampling modes the quality comparison is between: MiniMax-H3's own 28-step default with
+# H3-World alone, and `lightx2v/Minimax-h3-Turbo`'s 8-NFE distillation folded in on top of it.
+MODE_BASE = "28 steps · no turbo LoRA"
+MODE_TURBO = "8 steps · turbo LoRA"
+MODES: dict[str, tuple[int, bool]] = {
+    MODE_BASE: (DEFAULT_STEPS, False),
+    MODE_TURBO: (h3_turbo_lora.TURBO_STEPS, True),
+}
+DEFAULT_MODE = MODE_BASE
+
 # The conditioner offers canvases up to 1344x768, but H3-World was trained at 832x480 and the directed
 # mask costs O(sequence x captions) — at 1344x768 / 8s a request would need ~35 GPU-minutes, far past
 # what any visitor's ZeroGPU quota can book. So the list is the cheap tier of each aspect ratio, which
@@ -89,6 +101,7 @@ os.makedirs(OUTPUT_DIR, exist_ok=True)
 PIPE = None
 LOAD_ERROR: str | None = None
 LOADED_IN: float | None = None
+TURBO_ERROR: str | None = None
 
 
 # ── The action vocabulary ────────────────────────────────────────────────────
@@ -575,7 +588,7 @@ def lower_duration_floor(seconds: float = MIN_UI_DURATION) -> None:
 
 def load_models() -> str | None:
     """Load the denoising half at startup: transformer + VAEs, fold H3-World in, patch attention."""
-    global PIPE, LOAD_ERROR, LOADED_IN
+    global PIPE, LOAD_ERROR, LOADED_IN, TURBO_ERROR
 
     if PIPE is not None or LOAD_ERROR is not None:
         return LOAD_ERROR
@@ -601,6 +614,15 @@ def load_models() -> str | None:
 
         print(f"[gen] {load_and_apply_lora(pipe.transformer)}", flush=True)
 
+        # The turbo LoRA is only *prepared* here — its factors stay resident and are folded in (and
+        # back out) per request, so both sampling modes are one click apart.
+        try:
+            print(f"[gen] {h3_turbo_lora.prepare(pipe.transformer)}", flush=True)
+        except Exception as error:  # noqa: BLE001
+            traceback.print_exc()
+            TURBO_ERROR = f"{type(error).__name__}: {error}"
+            print(f"[gen] WARNING: turbo LoRA unavailable ({TURBO_ERROR})", flush=True)
+
         if PLACEMENT == "pack":
             pipe.transformer.to("cuda")
 
@@ -740,9 +762,14 @@ _TOKENS_PER_CAPTION = 8
 _DECODE_BASE, _DECODE_PER_DEFAULT_CANVAS, _DEFAULT_CANVAS_PIXELS = 15, 15, 960 * 544 * 124
 # ~12% over the fit, plus one cold worker's weight placement.
 _MARGIN, _PLACEMENT_ALLOWANCE = 1.12, 12
+# Folding (or unfolding) the turbo LoRA rewrites 312 weights through a rank-128 matmul each — a few
+# seconds of card, but budget generously since a worker may have to unfold the other state first.
+_TURBO_FOLD_ALLOWANCE = 60
 
 
-def get_duration(prompt_embeds, tags, plan, image, height, width, num_frames, steps, seed, *args, **kwargs):
+def get_duration(
+    prompt_embeds, tags, plan, image, height, width, num_frames, steps, seed, turbo=False, *args, **kwargs
+):
     """Estimate GPU seconds for one ``_generate`` call, from measurements rather than guesswork."""
     height, width, num_frames, steps = int(height), int(width), int(num_frames), int(steps)
     patches = (height // 32) * (width // 32)
@@ -753,14 +780,17 @@ def get_duration(prompt_embeds, tags, plan, image, height, width, num_frames, st
     if plan is not None:
         per_step += _MASK * rows * len(plan["spans"]) * _TOKENS_PER_CAPTION
     decode = _DECODE_BASE + _DECODE_PER_DEFAULT_CANVAS * (height * width * num_frames) / _DEFAULT_CANVAS_PIXELS
-    return max(60, int((steps * per_step + decode) * _MARGIN) + _PLACEMENT_ALLOWANCE)
+    # Either direction can cost a fold: a turbo request folds it in, and the next base request on a
+    # warm worker folds it back out. So the allowance rides along whenever the LoRA is loaded at all.
+    fold = _TURBO_FOLD_ALLOWANCE if TURBO_ERROR is None else 0
+    return max(60, int((steps * per_step + decode) * _MARGIN) + _PLACEMENT_ALLOWANCE) + fold
 
 
 # ── Inference ────────────────────────────────────────────────────────────────
 
 
 @spaces.GPU(duration=get_duration, size=GPU_SIZE)
-def _generate(prompt_embeds, tags, plan, image, height, width, num_frames, steps, seed):
+def _generate(prompt_embeds, tags, plan, image, height, width, num_frames, steps, seed, turbo=False):
     """Denoise + decode on GPU time, with the directed mask active for this request's geometry."""
     if PLACEMENT == "pack":
         PIPE.vae.to("cuda")
@@ -768,6 +798,10 @@ def _generate(prompt_embeds, tags, plan, image, height, width, num_frames, steps
     elif PLACEMENT == "lazy":
         PIPE.to("cuda")
 
+    # In or out, in place, on the card the weights already sit on.
+    folded = h3_turbo_lora.set_active(PIPE.transformer, turbo)
+    print(f"[gen] turbo LoRA {'folded in' if folded else 'off'}", flush=True)
+
     DIRECTED["plan"] = plan
     try:
         state = PIPE(
@@ -801,10 +835,11 @@ def generate(
     script: str = "forward",
     canvas: str = DEFAULT_CANVAS,
     duration: float = DEFAULT_DURATION,
-    steps: int = DEFAULT_STEPS,
+    steps: int = 0,
     seed: int = 0,
     subject: str = DEFAULT_SUBJECT,
     directed: bool = True,
+    mode: str = DEFAULT_MODE,
     progress=gr.Progress(track_tqdm=True),
 ):
     """Roll a world forward from one frame under a keyboard action script.
@@ -818,11 +853,15 @@ def generate(
             tilt-down, or a raw key combination out of W A S D I J K L F.
         canvas: Output resolution; snapped to the first frame's aspect ratio when one is given.
         duration: Seconds of video, rounded up to the next frame count the VAE can decode.
-        steps: Denoising steps. The released H3-World results use 50.
+        steps: Denoising steps, or ``0`` for whatever ``mode`` asks for (28 without the turbo LoRA,
+            8 with it). 28 is MiniMax-H3's default; the released H3-World results use 50.
         seed: Random seed.
         subject: How the per-frame sentences refer to the character.
         directed: Bind each sentence to its own latent frame with H3-World's directed attention mask.
             Turning it off is the ablation: the sentences become one global prompt.
+        mode: ``"28 steps · no turbo LoRA"`` or ``"8 steps · turbo LoRA"`` — the second folds
+            ``lightx2v/Minimax-h3-Turbo``'s 8-step distillation in on top of H3-World and drops the
+            step count to 8, for a quality-versus-speed comparison at the same seed.
 
     Returns:
         The generated video (with MiniMax-H3's native soundtrack) and a markdown report holding the
@@ -835,6 +874,11 @@ def generate(
     if not prompt or not prompt.strip():
         raise gr.Error("H3-World still needs a scene description alongside the actions.")
 
+    mode_steps, turbo = MODES.get(str(mode), MODES[DEFAULT_MODE])
+    if turbo and TURBO_ERROR:
+        raise gr.Error(f"The turbo LoRA failed to load, so only {MODE_BASE} is available: {TURBO_ERROR}")
+    steps = int(steps) or mode_steps
+
     from PIL import Image, ImageOps
     from diffusers.utils import encode_video
 
@@ -872,7 +916,7 @@ def generate(
     progress(0.1, desc=f"Generating {num_frames / FPS:.1f}s at {width}x{height} in {int(steps)} steps ...")
     started = time.time()
     frames, audio, sampling_rate = _generate(
-        prompt_embeds, tags, plan, keyframe, height, width, num_frames, int(steps), int(seed)
+        prompt_embeds, tags, plan, keyframe, height, width, num_frames, int(steps), int(seed), turbo
     )
     generate_seconds = time.time() - started
 
@@ -884,8 +928,10 @@ def generate(
         if plan is not None
         else "directed mask **off** (sentences act as one global prompt)"
     )
+    turbo_note = "turbo LoRA **on** (8-step distillation)" if turbo else "no turbo LoRA"
     report = (
         f"{width}x{height} · {num_frames} frames ({num_frames / FPS:.2f}s) · {int(steps)} steps · "
+        f"{turbo_note} · "
         f"{mask_note} · conditioner {condition_seconds:.0f}s · denoise + decode {generate_seconds:.0f}s · "
         f"seed {int(seed)}\n\n"
         f"<details><summary>Action timeline</summary>\n\n{summarize(sequence, subject)}\n\n</details>"
@@ -924,7 +970,12 @@ Each frame's key state becomes one short sentence — *"the man walks forward, c
 sharply"* — and a **directed attention mask** binds that sentence to that frame inside MiniMax-H3's
 packed sequence, which is what makes the control per-frame rather than a global prompt.
 
-`W`/`A`/`S`/`D` move · `I`/`J`/`K`/`L` aim the camera · `F` makes the camera move sharp."""
+`W`/`A`/`S`/`D` move · `I`/`J`/`K`/`L` aim the camera · `F` makes the camera move sharp.
+
+**Sampling** picks between MiniMax-H3's 28-step default and
+[`lightx2v/Minimax-h3-Turbo`](https://huggingface.co/lightx2v/Minimax-h3-Turbo)'s **8-step**
+distillation (`minimax_h3_fl2v_turbo_8step_v1.0_bf16`) folded in on top of H3-World — same seed,
+same action script, ~3.5x fewer steps, so you can judge the quality difference yourself."""
 
 CSS = """
 .main.fillable { max-width: 1150px !important; }
@@ -984,6 +1035,15 @@ with gr.Blocks(title="H3-World") as demo:
                     + " — or raw keys like WA, LF."
                 ),
             )
+            mode = gr.Radio(
+                label="Sampling",
+                choices=list(MODES),
+                value=DEFAULT_MODE,
+                info=(
+                    "Same seed, same script — compare MiniMax-H3's 28-step default against "
+                    "lightx2v/Minimax-h3-Turbo's 8-step distillation folded in on top of H3-World."
+                ),
+            )
             run = gr.Button("Roll the world forward", variant="primary", size="lg")
 
             with gr.Accordion("Advanced", open=False):
@@ -995,7 +1055,12 @@ with gr.Blocks(title="H3-World") as demo:
                     value=DEFAULT_DURATION,
                 )
                 steps_slider = gr.Slider(
-                    label="Steps", minimum=16, maximum=50, step=1, value=DEFAULT_STEPS
+                    label="Steps",
+                    minimum=4,
+                    maximum=50,
+                    step=1,
+                    value=DEFAULT_STEPS,
+                    info="Follows the sampling mode; 50 is the released H3-World configuration.",
                 )
                 canvas = gr.Dropdown(label="Canvas", choices=list(CANVASES), value=DEFAULT_CANVAS)
                 seed = gr.Number(label="Seed", value=0, precision=0)
@@ -1013,12 +1078,15 @@ with gr.Blocks(title="H3-World") as demo:
                 preview_md = gr.Markdown(preview("forward*20, forward-right*10, pan-right-fast*7",
                                                  DEFAULT_DURATION, DEFAULT_SUBJECT))
 
-    INPUTS = [prompt, image, script, canvas, duration_slider, steps_slider, seed, subject, directed]
+    INPUTS = [prompt, image, script, canvas, duration_slider, steps_slider, seed, subject, directed, mode]
     OUTPUTS = [result, report]
 
     image.upload(_fit_keyframe_ui, [image, canvas], [image, canvas])
     for control in (script, duration_slider, subject):
         control.change(preview, [script, duration_slider, subject], [preview_md])
+    # Picking a sampling mode moves the Steps slider to that mode's own count; the slider stays an
+    # override, so 50 (the released configuration) is still reachable with the LoRA either way.
+    mode.change(lambda choice: gr.update(value=MODES.get(choice, MODES[DEFAULT_MODE])[0]), [mode], [steps_slider])
 
     gr.Examples(
         examples=EXAMPLES,

h3_turbo_lora.py

@@ -0,0 +1,144 @@
+"""The lightx2v 8-step Turbo LoRA, folded into the same bf16 weights H3-World is merged into.
+
+This mirrors the `h3_lora.py` of the Spaces that already run this adapter on MiniMax-H3 —
+[`MiniMaxAI/MiniMax-H3-Turbo-Lora`](https://huggingface.co/spaces/MiniMaxAI/MiniMax-H3-Turbo-Lora)
+(its `lightx` set) and
+[`hugging-apps/minimax-h3-turbo-sla-demo`](https://huggingface.co/spaces/hugging-apps/minimax-h3-turbo-sla-demo):
+
+* `lightx2v/Minimax-h3-Turbo` is a **PEFT checkpoint against the diffusers module tree itself** —
+  `transformer_blocks.N.attn.to_q.lora_A.default.weight` and friends — so unlike H3-World it needs
+  no key conversion at all: 312 targets (50 transformer blocks + 2 token-refiner blocks x
+  `to_q/to_k/to_v/to_out.0/ff.net.0.proj/ff.net.2`) map name-for-name.
+* Rank is 128 and the file's own safetensors metadata records `alpha: 8`, so the fold scale is
+  `alpha / rank = 0.0625` — exactly what `set_adapters(weights=1.0)` applies in lightx2v's
+  reference inference script, and what the Spaces above use for this repo.
+* `minimax_h3_fl2v_turbo_8step_v1.0_bf16.safetensors` is an 8-NFE distillation, so the step count
+  is overridden to **8** when it is active. No scheduler swap and no CFG change: MiniMax-H3 is
+  already guidance-distilled and its own `MiniMaxH3Scheduler` is what every one of those Spaces
+  keeps using with the turbo LoRA folded.
+
+The adapter is *folded* into the weights rather than wrapped as a runtime module, for the same
+reason H3-World is: this Space patches `MiniMaxH3AttnProcessor` and drives the transformer's live
+weights. Fold and unfold are the same operation with a sign, so the active set can be flipped per
+request (`set_active`) through one bf16 rounding, with the low-rank factors staying resident.
+"""
+
+from __future__ import annotations
+
+import os
+
+import torch
+
+TURBO_REPO = os.environ.get("H3_TURBO_REPO", "lightx2v/Minimax-h3-Turbo")
+TURBO_FILE = os.environ.get("H3_TURBO_FILE", "minimax_h3_fl2v_turbo_8step_v1.0_bf16.safetensors")
+# The distillation's own NFE count; the card offers 4 as the faster, softer alternative.
+TURBO_STEPS = int(os.environ.get("H3_TURBO_STEPS", "8"))
+# 0 = read `alpha` out of the file's safetensors metadata (it is `8` for every lightx2v file).
+TURBO_ALPHA = float(os.environ.get("H3_TURBO_ALPHA", "0"))
+TURBO_STRENGTH = float(os.environ.get("H3_TURBO_STRENGTH", "1.0"))
+
+SUFFIX_A, SUFFIX_B = ".lora_A.default.weight", ".lora_B.default.weight"
+
+
+def load() -> dict:
+    """Download the adapter and return ``{"label", "scale", "entries"}``; entries are ``(param_key, A, B)``."""
+    from huggingface_hub import hf_hub_download
+    from safetensors import safe_open
+    from safetensors.torch import load_file
+
+    path = hf_hub_download(TURBO_REPO, TURBO_FILE)
+    with safe_open(path, framework="pt") as handle:
+        metadata = handle.metadata() or {}
+    alpha = TURBO_ALPHA or float(metadata.get("alpha", 8))
+
+    lora = load_file(path)
+    bases = sorted({key[: -len(SUFFIX_A)] for key in lora if key.endswith(SUFFIX_A)})
+    if not bases:
+        raise ValueError(f"No lora_A/lora_B pairs found in {TURBO_FILE}")
+    unexpected = [key for key in lora if not key.endswith((SUFFIX_A, SUFFIX_B))]
+    if unexpected:
+        raise ValueError(f"{TURBO_FILE} holds {len(unexpected)} non-LoRA tensors, e.g. {unexpected[:5]}")
+    for name in bases:
+        if f"{name}{SUFFIX_B}" not in lora:
+            raise ValueError(f"LoRA is missing the lora_B twin of {name}{SUFFIX_A}")
+
+    ranks = {lora[f"{name}{SUFFIX_A}"].shape[0] for name in bases}
+    if len(ranks) != 1:
+        raise ValueError(f"LoRA mixes ranks {sorted(ranks)}")
+    rank = ranks.pop()
+
+    entries = [(f"{name}.weight", lora[f"{name}{SUFFIX_A}"], lora[f"{name}{SUFFIX_B}"]) for name in bases]
+    return {
+        "label": f"{TURBO_REPO}/{TURBO_FILE}",
+        "scale": alpha / rank * TURBO_STRENGTH,
+        "entries": entries,
+        "rank": rank,
+        "alpha": alpha,
+    }
+
+
+def _fold(transformer, spec: dict, sign: float) -> None:
+    """Add ``sign * scale * (B @ A)`` to every target weight, in place.
+
+    The factors ride to the weight's own device before the matmul — the deltas are 5 TFLOP in
+    total, which is seconds on the card and minutes on a Space's two vCPUs.
+    """
+    params = dict(transformer.named_parameters())
+    scale = sign * spec["scale"]
+    with torch.no_grad():
+        for key, a, b in spec["entries"]:
+            param = params[key]
+            delta = b.to(param.device, torch.float32) @ a.to(param.device, torch.float32)
+            if delta.shape != param.shape:
+                raise ValueError(
+                    f"Turbo LoRA delta for `{key}` has shape {tuple(delta.shape)}, "
+                    f"base weight is {tuple(param.shape)}"
+                )
+            param.data = (param.data.float() + scale * delta).to(param.dtype)
+            del delta
+
+
+def prepare(transformer) -> str:
+    """Load the adapter and validate it against ``transformer``, without folding it yet."""
+    spec = load()
+    params = dict(transformer.named_parameters())
+    missed = [key for key, _, _ in spec["entries"] if key not in params]
+    if missed:
+        raise ValueError(
+            f"{len(missed)} turbo-LoRA targets matched no transformer weight, e.g. {missed[:5]}. "
+            "The LoRA and the diffusers transformer disagree on module naming."
+        )
+    for key, a, b in spec["entries"]:  # cheaper here than discovering it mid-request
+        shape = (b.shape[0], a.shape[1])
+        if shape != tuple(params[key].shape):
+            raise ValueError(
+                f"Turbo LoRA delta for `{key}` would be {shape}, base weight is {tuple(params[key].shape)}"
+            )
+    transformer._turbo_state = {"active": False, "spec": spec}
+    return (
+        f"Turbo LoRA ready · {spec['label']} · {len(spec['entries'])} targets, "
+        f"rank {spec['rank']}, alpha {spec['alpha']:g} -> scale {spec['scale']:.4f} · "
+        f"{TURBO_STEPS} steps when active"
+    )
+
+
+def is_available(transformer) -> bool:
+    return getattr(transformer, "_turbo_state", None) is not None
+
+
+def set_active(transformer, on: bool) -> bool:
+    """Fold the turbo LoRA in (or back out). No-op when the weights already match. Returns the state.
+
+    Called from inside the ``@spaces.GPU`` function: the transformer's weights live on the card
+    there, and a ZeroGPU worker that is reused keeps both them and this state, while a freshly
+    forked one starts from the unfolded weights *and* the unfolded state — consistent either way.
+    """
+    state = getattr(transformer, "_turbo_state", None)
+    if state is None:
+        return False
+    on = bool(on)
+    if state["active"] == on:
+        return on
+    _fold(transformer, state["spec"], 1.0 if on else -1.0)
+    state["active"] = on
+    return on