Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

27.7 KB
Raw Blame
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0

"""FLUX.3 Klein Base conditioning blocks run once per render, bit-identical; cache cleared at start
and end of each pipeline call; installed only on matching diffusers forward hash, else stock;
UNSLOTH_DIFFUSION_COND_BLOCKS=0 disables. Offloaded (CUDA): computed inside the hooked forward,
UNSLOTH_DIFFUSION_OFFLOAD_COND_CACHE=0 keeps stock. Modulation heads project one row per sample,
not per token (any FLUX.3), UNSLOTH_DIFFUSION_FLUX3_COMPACT_MOD=0 restores per-token rows. With reference
images the joint blocks take one row per span (image, references) instead of a per-token copy, bit-identical;
UNSLOTH_DIFFUSION_FLUX3_SPAN_MOD=0 restores the per-token rows"""

from __future__ import annotations

import hashlib
import inspect
import os
import weakref
from typing import Any, Optional

from .rocm_bf16 import is_rocm_torch

COND_BLOCKS_ENV = "UNSLOTH_DIFFUSION_COND_BLOCKS"
OFFLOAD_COND_ENV = "UNSLOTH_DIFFUSION_OFFLOAD_COND_CACHE"
COMPACT_MOD_ENV = "UNSLOTH_DIFFUSION_FLUX3_COMPACT_MOD"
SPAN_MOD_ENV = "UNSLOTH_DIFFUSION_FLUX3_SPAN_MOD"
SPAN_KWARG = "unsloth_cond_mod"
SPAN_LEN_KWARG = "unsloth_cond_span"
COND_KWARG = "unsloth_cond"
_COMPACT_ATTR = "_unsloth_compact_mod"
_SPAN_ATTR = "_unsloth_span_mod"
_OFFLOADED_ATTR = "_unsloth_cond_offloaded"

# sha256[:16] of inspect.getsource(Flux3Transformer2DModel.forward) the replacement mirrors (d42ebf9c and 0.42.1).
_FLUX3_FORWARD_SHA = frozenset({"f2f7c836416cfd58"})
# Same, for Flux3SingleTransformerBlock.forward (the span-modulated joint block mirrors it).
_FLUX3_SINGLE_SHA = frozenset({"92269bb072da8335"})

_PATCHED: dict[type, Any] = {}
_PATCHED_SINGLE: dict[type, Any] = {}
# (attention output, MLP output) of a joint block on its combined input, bit-identical to ``self.attn`` / ``self.ff``,
# or None for the modules: set by diffusion_flux_convrot_fused (one shared int8 ConvRot quant) while installed.
JOINT_ATTN_FF: Any = None


def _switch(name: str) -> bool:
    return (os.environ.get(name) or "").strip().lower() not in ("0", "off", "false", "no")


def enabled() -> bool:
    return _switch(COND_BLOCKS_ENV)


def offload_cache_enabled() -> bool:
    return _switch(OFFLOAD_COND_ENV)


def compact_enabled() -> bool:
    return _switch(COMPACT_MOD_ENV)


def span_enabled() -> bool:
    return _switch(SPAN_MOD_ENV)


def _forward_sha(cls: type) -> Optional[str]:
    try:
        return hashlib.sha256(inspect.getsource(cls.forward).encode()).hexdigest()[:16]
    except Exception:  # noqa: BLE001
        return None


def _tkey(t: Any) -> Any:
    if t is None:
        return None
    return (id(t), t.data_ptr(), tuple(t.shape), t.dtype, str(t.device))


class _Entry:
    __slots__ = ("refs", "states")

    def __init__(self, sources: tuple, states: dict) -> None:
        self.refs = tuple(weakref.ref(t) if t is not None else None for t in sources)
        self.states = states

    def matches(self, sources: tuple) -> bool:
        for ref, t in zip(self.refs, sources):
            if (ref is None) != (t is None):
                return False
            if ref is not None and ref() is not t:
                return False
        return True


def _offloaded(module: Any) -> Optional[str]:
    """Why ``module`` is offloaded (None: resident); its conditioning then runs only inside the hooked forward."""
    for name, sub in module.named_modules():
        if getattr(sub, "_hf_hook", None) is not None:
            return f"{name or '<root>'} carries an accelerate hook"
        registry = getattr(sub, "_diffusers_hook", None)
        hooks = getattr(registry, "hooks", None) or {}
        if any("offload" in str(k).lower() for k in hooks):
            return f"{name or '<root>'} is group offloaded"
    return None


def _fixed_prefetch_chain(module: Any) -> Optional[str]:
    """diffusers' fixed next-group prefetch chain would leave a skipped block on the device."""
    for name, sub in module.named_modules():
        hooks = getattr(getattr(sub, "_diffusers_hook", None), "hooks", None) or {}
        for key, hook in hooks.items():
            if "lazy_prefetch" in str(key).lower() or getattr(hook, "next_group", None) is not None:
                return f"{name or '<root>'} streams with diffusers' prefetch chain"
    return None


def _offload_device_ok(t: Any) -> bool:
    """Offload cache: CUDA only for now (ROCm, XPU, MPS, CPU keep stock)."""
    import torch
    return bool(t.is_cuda) and not is_rocm_torch(torch)


def _rows(t: Any, batch_size: int, n: int) -> Any:
    return t if t.shape[1] == n else t.expand(batch_size, n, -1)


def flux3_conditioning(
    module: Any,
    *,
    encoder_hidden_states: Any,
    txt_ids: Any,
    image_cond_hidden_states: Any,
    image_cond_ids: Any,
    batch_size: int,
    dtype: Any,
    device: Any,
    compact: bool = False,
    target_temb: Any = None,
) -> dict:
    """The conditioning part of ``Flux3Transformer2DModel.forward``, op for op. ``compact``: one modulation row per
    sample (every token of a mode shares its timestep), broadcast by the blocks."""
    import torch
    import torch.nn.functional as F

    zero_temb = module.time_proj(torch.zeros(batch_size, device = device, dtype = dtype))
    zero_temb = module.timestep_embedder(zero_temb.to(dtype))[:, None, :]
    if target_temb is not None:
        zero_temb = zero_temb + target_temb
    zero_temb_act = F.silu(zero_temb)

    txt_temb_act = (
        zero_temb_act
        if compact
        else zero_temb_act.expand(batch_size, encoder_hidden_states.shape[1], -1)
    )
    txt_early_mod = module.early_stream_modulations["txt"](txt_temb_act)
    txt_single_mod = module.single_stream_modulations["txt"](txt_temb_act)
    txt_states = module.context_embedder(encoder_hidden_states)
    txt_cos, txt_sin = module.pos_embed(txt_ids)

    out: dict = {}
    if image_cond_hidden_states is not None:
        cond_temb_act = (
            zero_temb_act
            if compact
            else zero_temb_act.expand(batch_size, image_cond_hidden_states.shape[1], -1)
        )
        cond_early_mod = module.early_stream_modulations["image_cond"](cond_temb_act)
        cond_single_mod = module.single_stream_modulations["image_cond"](cond_temb_act)
        cond_states = module.x_embedders["image_cond"](image_cond_hidden_states)
        cond_cos, cond_sin = module.pos_embed(image_cond_ids)

    for block in module.txt_mode_blocks:
        txt_states = block(txt_states, txt_early_mod, (txt_cos, txt_sin))
    if image_cond_hidden_states is not None:
        for block in module.mode_blocks["image_cond"]:
            cond_states = block(cond_states, cond_early_mod, (cond_cos, cond_sin))
        out.update(
            cond_states = cond_states,
            cond_single_mod = cond_single_mod,
            cond_cos = cond_cos,
            cond_sin = cond_sin,
        )
    out.update(
        txt_states = txt_states, txt_single_mod = txt_single_mod, txt_cos = txt_cos, txt_sin = txt_sin
    )
    return out


def _compact_call(module: Any, attention_kwargs: Any) -> bool:
    """Inference without a per-call LoRA scale (stock ``apply_lora_scale`` handles it)."""
    import torch

    if not module.__dict__.get(_COMPACT_ATTR) or torch.is_grad_enabled():
        return False
    return not (attention_kwargs and "scale" in attention_kwargs)


class Pending:
    """An offloaded miss passed as ``unsloth_cond``: a non-tensor, so a CUDA graph runs this call eager and a CFG
    router records no template from it (``pending``)."""

    __slots__ = ("key", "sources")
    pending = True

    def __init__(self, key: tuple, sources: tuple) -> None:
        self.key = key
        self.sources = sources


def _claim_pending(
    module: Any, hidden_states: Any, pending: Pending, sources: tuple
) -> Optional[dict]:
    """Offloaded miss: compute and cache inside the hooked forward, only for the exact call it was recorded for."""
    import torch

    key, recorded = pending.key, pending.sources
    if key[1] != int(hidden_states.shape[0]) or any(a is not b for a, b in zip(sources, recorded)):
        return None
    if hidden_states.is_cuda and torch.cuda.is_current_stream_capturing():
        return None
    ehs, txt_ids, ich, iid = sources
    states = flux3_conditioning(
        module,
        encoder_hidden_states = ehs,
        txt_ids = txt_ids,
        image_cond_hidden_states = ich,
        image_cond_ids = iid,
        batch_size = int(hidden_states.shape[0]),
        dtype = hidden_states.dtype,
        device = hidden_states.device,
        compact = bool(module.__dict__.get(_COMPACT_ATTR)),
    )
    module.__dict__.setdefault("_unsloth_cond_cache", {})[key] = _Entry(sources, states)
    stats = _stats(module)
    stats["misses"] += 1
    stats["in_forward"] = stats.get("in_forward", 0) + 1
    return states


def _flux3_cached_forward(
    self: Any,
    hidden_states: Any,
    encoder_hidden_states: Any = None,
    timestep: Any = None,
    img_ids: Any = None,
    txt_ids: Any = None,
    image_cond_hidden_states: Any = None,
    image_cond_ids: Any = None,
    target_timestep: Any = None,
    attention_kwargs: Optional[dict] = None,
    return_dict: bool = True,
    unsloth_cond: Optional[dict] = None,
) -> Any:
    """Stock forward op for op, with precomputed ``unsloth_cond`` and / or compact modulation; else stock."""
    if isinstance(unsloth_cond, Pending):
        unsloth_cond = _claim_pending(
            self,
            hidden_states,
            unsloth_cond,
            (encoder_hidden_states, txt_ids, image_cond_hidden_states, image_cond_ids),
        )
    if unsloth_cond is None and not _compact_call(self, attention_kwargs):
        return _stock_forward(self)(
            self,
            hidden_states = hidden_states,
            encoder_hidden_states = encoder_hidden_states,
            timestep = timestep,
            img_ids = img_ids,
            txt_ids = txt_ids,
            image_cond_hidden_states = image_cond_hidden_states,
            image_cond_ids = image_cond_ids,
            target_timestep = target_timestep,
            attention_kwargs = attention_kwargs,
            return_dict = return_dict,
        )
    import torch
    import torch.nn.functional as F
    from diffusers.models.modeling_outputs import Transformer2DModelOutput

    batch_size, image_seq_len = hidden_states.shape[:2]
    dtype = hidden_states.dtype
    compact = bool(self.__dict__.get(_COMPACT_ATTR))

    image_temb = self.time_proj(timestep.to(dtype) * 1000)
    image_temb = self.timestep_embedder(image_temb.to(dtype))[:, None, :]
    if unsloth_cond is not None:
        if target_timestep is not None or bool(self.config.flow_map):
            raise ValueError(
                "cached conditioning states are only valid for a non-flow-map transformer"
            )
    else:
        if image_cond_hidden_states is not None and image_cond_ids is None:
            raise ValueError("`image_cond_hidden_states` requires `image_cond_ids`.")
        if image_cond_hidden_states is None and image_cond_ids is not None:
            raise ValueError("`image_cond_ids` was passed without `image_cond_hidden_states`.")
        if (target_timestep is not None) != bool(self.config.flow_map):
            raise ValueError(
                "`target_timestep` is required by, and only by, a flow-map transformer (`flow_map=True`)."
            )
        target_temb = None
        if target_timestep is not None:
            target_temb = self.time_proj(target_timestep.to(dtype) * 1000)
            target_temb = self.target_timestep_embedder(target_temb.to(dtype))[:, None, :]
            image_temb = image_temb + target_temb
        unsloth_cond = flux3_conditioning(
            self,
            encoder_hidden_states = encoder_hidden_states,
            txt_ids = txt_ids,
            image_cond_hidden_states = image_cond_hidden_states,
            image_cond_ids = image_cond_ids,
            batch_size = batch_size,
            dtype = dtype,
            device = hidden_states.device,
            compact = True,
            target_temb = target_temb,
        )
        if (
            not torch.compiler.is_compiling()
        ):  # a module int Dynamo would guard on: one recompile per call
            _stats(self)["compact"] = _stats(self).get("compact", 0) + 1
    if not compact:
        image_temb = image_temb.expand(batch_size, image_seq_len, -1)

    encoder_hidden_states = unsloth_cond["txt_states"]
    txt_single_mod = unsloth_cond["txt_single_mod"]
    txt_rotary_emb = (unsloth_cond["txt_cos"], unsloth_cond["txt_sin"])

    image_temb_act = F.silu(image_temb)
    image_early_mod = self.early_stream_modulations["image"](image_temb_act)
    image_single_mod = self.single_stream_modulations["image"](image_temb_act)
    hidden_states = self.x_embedders["image"](hidden_states)
    image_rotary_emb = self.pos_embed(img_ids)

    has_cond = "cond_states" in unsloth_cond
    for block in self.mode_blocks["image"]:
        hidden_states = block(hidden_states, image_early_mod, image_rotary_emb)

    block_kwargs: dict = {}
    if has_cond:
        cond_states = unsloth_cond["cond_states"]
        cond_rotary_emb = (unsloth_cond["cond_cos"], unsloth_cond["cond_sin"])
        content_states = torch.cat([hidden_states, cond_states], dim = 1)
        cond_single_mod = unsloth_cond["cond_single_mod"]
        if (
            self.__dict__.get(_SPAN_ATTR)
            and image_single_mod.shape[1] == 1
            and cond_single_mod.shape[1] == 1
        ):
            # one row per span; the span length rides on a storage-free tensor so block graphs can copy every input
            content_mod = image_single_mod
            block_kwargs[SPAN_KWARG] = cond_single_mod
            block_kwargs[SPAN_LEN_KWARG] = cond_states.new_empty((cond_states.shape[1], 0))
        else:
            # image and reference spans carry different timesteps: per token here
            content_mod = torch.cat(
                [
                    _rows(image_single_mod, batch_size, image_seq_len),
                    _rows(cond_single_mod, batch_size, cond_states.shape[1]),
                ],
                dim = 1,
            )
        joint_rotary_emb = (
            torch.cat([txt_rotary_emb[0], image_rotary_emb[0], cond_rotary_emb[0]], dim = 0),
            torch.cat([txt_rotary_emb[1], image_rotary_emb[1], cond_rotary_emb[1]], dim = 0),
        )
    else:
        content_states = hidden_states
        content_mod = image_single_mod
        joint_rotary_emb = (
            torch.cat([txt_rotary_emb[0], image_rotary_emb[0]], dim = 0),
            torch.cat([txt_rotary_emb[1], image_rotary_emb[1]], dim = 0),
        )

    for block in self.single_transformer_blocks:
        encoder_hidden_states, content_states = block(
            hidden_states = content_states,
            encoder_hidden_states = encoder_hidden_states,
            temb_mod = content_mod,
            temb_mod_context = txt_single_mod,
            image_rotary_emb = joint_rotary_emb,
            **block_kwargs,
        )

    hidden_states = content_states[:, :image_seq_len]
    hidden_states = self.norm_out(hidden_states, image_temb)
    output = self.proj_out(hidden_states)

    if not return_dict:
        return (output,)
    return Transformer2DModelOutput(sample = output)


def _flux3_span_single_forward(
    self: Any,
    hidden_states: Any,
    encoder_hidden_states: Any,
    temb_mod: Any,
    temb_mod_context: Any,
    image_rotary_emb: Any,
    unsloth_cond_mod: Any = None,
    unsloth_cond_span: Any = None,
) -> Any:
    """Stock joint block, op for op, with one ``[B, 1, 3D]`` modulation row per span: ``temb_mod`` (image),
    ``unsloth_cond_mod`` (reference, length = ``unsloth_cond_span``'s ``[reference_tokens, 0]`` shape)."""
    if unsloth_cond_mod is None or unsloth_cond_span is None:
        return _stock_single_forward(self)(
            self,
            hidden_states = hidden_states,
            encoder_hidden_states = encoder_hidden_states,
            temb_mod = temb_mod,
            temb_mod_context = temb_mod_context,
            image_rotary_emb = image_rotary_emb,
        )
    import torch

    n_cond = unsloth_cond_span.shape[0]
    n_image = hidden_states.shape[1] - n_cond
    mod_shift, mod_scale, mod_gate = torch.chunk(temb_mod, 3, dim = -1)
    r_shift, r_scale, r_gate = torch.chunk(unsloth_cond_mod, 3, dim = -1)
    c_mod_shift, c_mod_scale, c_mod_gate = torch.chunk(temb_mod_context, 3, dim = -1)

    norm_hidden_states = self.norm(hidden_states)
    norm_image, norm_cond = torch.split(norm_hidden_states, [n_image, n_cond], dim = 1)
    norm_hidden_states = torch.cat(
        [(1 + mod_scale) * norm_image + mod_shift, (1 + r_scale) * norm_cond + r_shift], dim = 1
    )

    norm_encoder_hidden_states = self.norm(encoder_hidden_states)
    norm_encoder_hidden_states = (1 + c_mod_scale) * norm_encoder_hidden_states + c_mod_shift

    combined = torch.cat([norm_encoder_hidden_states, norm_hidden_states], dim = 1)

    both = JOINT_ATTN_FF(self, combined, image_rotary_emb) if JOINT_ATTN_FF is not None else None
    if both is None:
        attn_output = self.attn(hidden_states = combined, image_rotary_emb = image_rotary_emb)
        ff_output = self.ff(combined)
    else:
        attn_output, ff_output = both
    output = attn_output + ff_output

    context_output, image_output, cond_output = torch.split(
        output, [encoder_hidden_states.shape[1], n_image, n_cond], dim = 1
    )
    encoder_hidden_states = encoder_hidden_states + c_mod_gate * context_output
    image_states, cond_states = torch.split(hidden_states, [n_image, n_cond], dim = 1)
    hidden_states = torch.cat(
        [image_states + mod_gate * image_output, cond_states + r_gate * cond_output], dim = 1
    )

    return encoder_hidden_states, hidden_states


def _stock_single_forward(module: Any) -> Any:
    for cls in type(module).__mro__:
        stock = _PATCHED_SINGLE.get(cls)
        if stock is not None:
            return stock
    raise RuntimeError(f"{type(module).__name__} has no stock forward recorded")


def patch_single_class(cls: type) -> Optional[str]:
    """Install the span-aware joint block forward on ``cls`` (at load, before compile or a hook binds it)."""
    if any(c in _PATCHED_SINGLE for c in cls.__mro__):
        return None
    sha = _forward_sha(cls)
    if sha not in _FLUX3_SINGLE_SHA:
        return f"diffusers joint block changed (source {sha})"
    _PATCHED_SINGLE[cls] = cls.forward
    cls.forward = _flux3_span_single_forward
    return None


def _span_ready(transformer: Any) -> Optional[str]:
    """None when every joint block runs the span-aware forward; else why the per-token rows stay."""
    blocks = list(getattr(transformer, "single_transformer_blocks", None) or ())
    if not blocks:
        return "no joint blocks"
    for block in blocks:
        why = patch_single_class(type(block))
        if why is not None:
            return why
        if type(block).forward is not _flux3_span_single_forward:
            return "the joint block forward is not the patched one"
    return None


def _stock_forward(module: Any) -> Any:
    for cls in type(module).__mro__:
        stock = _PATCHED.get(cls)
        if stock is not None:
            return stock
    raise RuntimeError(f"{type(module).__name__} has no stock forward recorded")


def patch_class(cls: type) -> Optional[str]:
    """Install the cached forward on ``cls`` (safe before a CUDA graph or compile binds it). None, else why."""
    if any(c in _PATCHED for c in cls.__mro__):
        return None
    sha = _forward_sha(cls)
    if sha not in _FLUX3_FORWARD_SHA:
        return f"diffusers forward changed (source {sha})"
    # The stock forward carries apply_lora_scale; the replacement declines a per-call scale (the pre-hook passes no
    # states then), so it needs no wrapper of its own and the scale is never applied twice.
    _PATCHED[cls] = cls.forward
    cls.forward = _flux3_cached_forward
    return None


def _stats(module: Any) -> dict:
    stats = module.__dict__.get("_unsloth_cond_stats")
    if stats is None:
        stats = {"hits": 0, "misses": 0, "skipped": 0, "reason": None}
        module.__dict__["_unsloth_cond_stats"] = stats
    return stats


def _conditioning_blocks(module: Any, has_cond: bool) -> list:
    blocks = list(module.txt_mode_blocks)
    if has_cond:
        blocks += list(module.mode_blocks["image_cond"])
    return blocks


def _match_prefetch_order(module: Any, has_cond: bool, *, skipping: bool) -> None:
    """Keep the streamed prefetch on order when a hit skips (or a miss runs) the conditioning blocks."""
    from .diffusion_offload_prefetch import match_skipped_order
    try:
        match_skipped_order(module, _conditioning_blocks(module, has_cond), skipping = skipping)
    except Exception:  # noqa: BLE001 - speed hint only
        pass


def _pre_hook(module: Any, args: tuple, kwargs: dict) -> Any:
    import torch

    if args or kwargs.get(COND_KWARG) is not None or not module.__dict__.get("_unsloth_cond_live"):
        return None
    if (
        torch.compiler.is_compiling()
    ):  # a whole-model compile: identity cache and counters stay out of the graph
        return None
    if torch.is_grad_enabled() or kwargs.get("target_timestep") is not None:
        return None
    stats = _stats(module)
    attention_kwargs = kwargs.get("attention_kwargs")
    if attention_kwargs and "scale" in attention_kwargs:
        stats["skipped"] += 1
        stats["reason"] = "a per-call LoRA scale"
        return None
    hidden_states = kwargs.get("hidden_states")
    ehs = kwargs.get("encoder_hidden_states")
    txt_ids = kwargs.get("txt_ids")
    ich = kwargs.get("image_cond_hidden_states")
    iid = kwargs.get("image_cond_ids")
    if hidden_states is None or ehs is None or txt_ids is None or (ich is None) != (iid is None):
        return None
    if ich is None and not module.__dict__.get("_unsloth_cond_text_only"):
        # Text alone is ~0.6% of a 1024^2 step (noise on B200); the saving is the ~4k-token reference stream.
        return None
    if hidden_states.is_cuda and torch.cuda.is_current_stream_capturing():
        return None
    offloaded = bool(module.__dict__.get(_OFFLOADED_ATTR))
    if offloaded and not _offload_device_ok(hidden_states):
        stats["skipped"] += 1
        stats["reason"] = (
            f"offloaded on {hidden_states.device.type} (the offload cache is CUDA only)"
        )
        return None
    sources = (ehs, txt_ids, ich, iid)
    key = (
        tuple(_tkey(t) for t in sources),
        int(hidden_states.shape[0]),
        hidden_states.dtype,
        str(hidden_states.device),
    )
    cache = module.__dict__.setdefault("_unsloth_cond_cache", {})
    entry = cache.get(key)
    if entry is None or not entry.matches(sources):
        if offloaded:
            _match_prefetch_order(module, ich is not None, skipping = False)
            new_kwargs = dict(kwargs)
            new_kwargs[COND_KWARG] = Pending(key, sources)
            return args, new_kwargs
        states = flux3_conditioning(
            module,
            encoder_hidden_states = ehs,
            txt_ids = txt_ids,
            image_cond_hidden_states = ich,
            image_cond_ids = iid,
            batch_size = int(hidden_states.shape[0]),
            dtype = hidden_states.dtype,
            device = hidden_states.device,
            compact = bool(module.__dict__.get(_COMPACT_ATTR)),
        )
        cache[key] = _Entry(sources, states)
        stats["misses"] += 1
    else:
        states = entry.states
        stats["hits"] += 1
        if offloaded:
            _match_prefetch_order(module, ich is not None, skipping = True)
    new_kwargs = dict(kwargs)
    new_kwargs[COND_KWARG] = states
    return args, new_kwargs


def _applies(transformer: Any) -> Optional[str]:
    if type(transformer).__name__ != "Flux3Transformer2DModel":
        return "not a FLUX.3 transformer"
    if bool(getattr(getattr(transformer, "config", None), "flow_map", False)):
        return "flow map: each step's target time modulates the conditioning"
    return None


def prepare(transformer: Any, logger: Any = None) -> bool:
    """Call at load, before the speed layer binds the class forward. True when the conditioning cache can arm."""
    cond_on = enabled()
    compact = compact_enabled()
    if transformer is None or not (cond_on or compact):
        return False
    applies = _applies(transformer)
    if applies is not None and (not compact or "not a FLUX.3" in applies):
        if cond_on:
            _stats(transformer)["reason"] = applies
            if logger is not None and "not a FLUX.3" not in applies:
                logger.info("diffusion.cond_blocks: off (%s)", applies)
        return False
    why = patch_class(type(transformer))
    if why is not None:
        _stats(transformer)["reason"] = why
        if logger is not None:
            logger.info("diffusion.cond_blocks: off (%s)", why)
        return False
    transformer.__dict__[_COMPACT_ATTR] = compact
    if compact and logger is not None:
        logger.info("diffusion.cond_blocks: FLUX.3 modulation heads project one row per sample")
    span = False
    if compact and span_enabled():
        why = _span_ready(transformer)
        span = why is None
        if why is not None and logger is not None:
            logger.info("diffusion.cond_blocks: reference modulation stays per token (%s)", why)
    transformer.__dict__[_SPAN_ATTR] = span
    if not cond_on:
        return False
    if applies is not None:
        _stats(transformer)["reason"] = applies
        if logger is not None:
            logger.info("diffusion.cond_blocks: off (%s)", applies)
        return False
    return True


def begin_render(transformer: Any, logger: Any = None) -> bool:
    """Arm for one pipeline call. The pre-hook must stay LAST so it runs inside earlier hooks' scope (dynamic text
    dims marks the text length dynamic for the compiled blocks)."""
    if transformer is None:
        return False
    clear(transformer)
    transformer.__dict__["_unsloth_cond_live"] = False
    if not enabled() or _applies(transformer) is not None:
        return False
    if (
        _stock_forward_or_none(transformer) is None
        or type(transformer).forward is not _flux3_cached_forward
    ):
        _stats(transformer)["reason"] = "the class forward was not patched at load"
        return False
    why = _offloaded(transformer)
    if why is not None and (not offload_cache_enabled() or _fixed_prefetch_chain(transformer)):
        _stats(transformer)["reason"] = _fixed_prefetch_chain(transformer) or why
        return False
    transformer.__dict__[_OFFLOADED_ATTR] = why is not None
    handle = transformer.__dict__.get("_unsloth_cond_hook")
    hooks = transformer._forward_pre_hooks
    if handle is None or handle.id not in hooks:
        handle = transformer.register_forward_pre_hook(_pre_hook, with_kwargs = True)
        transformer.__dict__["_unsloth_cond_hook"] = handle
        if logger is not None:
            logger.info(
                "diffusion.cond_blocks: FLUX.3 text and reference streams run once per render"
            )
    elif next(reversed(hooks)) != handle.id:
        hooks.move_to_end(handle.id)
    transformer.__dict__["_unsloth_cond_live"] = True
    _stats(transformer)["reason"] = None
    return True


def _stock_forward_or_none(module: Any) -> Any:
    try:
        return _stock_forward(module)
    except RuntimeError:
        return None


def end_render(transformer: Any) -> None:
    if transformer is not None:
        clear(transformer)
        transformer.__dict__["_unsloth_cond_live"] = False


def clear(transformer: Any) -> None:
    if transformer is not None:
        cache = transformer.__dict__.get("_unsloth_cond_cache")
        if cache:
            cache.clear()


def status(transformer: Any) -> Optional[dict]:
    if transformer is None:
        return None
    stats = transformer.__dict__.get("_unsloth_cond_stats")
    if stats is None:
        return None
    return {"armed": transformer.__dict__.get("_unsloth_cond_hook") is not None, **stats}