"""ComfyUI native-H3 and accelerator compatibility checks.""" from __future__ import annotations import inspect from typing import Any, Iterable class CompatibilityError(RuntimeError): """Raised when a MODEL is not the supported native MiniMax H3 runtime.""" def _missing_callable_parameters( callable_obj: Any, *, positional: Iterable[str] = (), keywords: Iterable[str] = (), ) -> list[str]: """Return parameters that a callable can no longer accept. Compatibility wrappers are allowed to replace a concrete signature with ``*args``/``**kwargs``. Sol-Attn's MiniMax-H3 Morton integration does this for ``PackedLayout.__init__`` while transparently forwarding the original arguments. Treating the wrapped signature as an API removal produces a false incompatibility even though construction remains valid. Explicit parameters are preferred when available. ``*args`` satisfies missing positional parameters and ``**kwargs`` satisfies missing keyword parameters. If ``inspect.signature`` itself is unavailable, the caller still receives the exception and may fail closed. """ params = inspect.signature(callable_obj).parameters has_var_positional = any( parameter.kind is inspect.Parameter.VAR_POSITIONAL for parameter in params.values() ) has_var_keyword = any( parameter.kind is inspect.Parameter.VAR_KEYWORD for parameter in params.values() ) missing: list[str] = [] for name in positional: if name not in params and not has_var_positional: missing.append(name) for name in keywords: if name not in params and not has_var_keyword: missing.append(name) return missing def check_comfy_h3_runtime() -> list[str]: """Return human-readable incompatibilities with ComfyUI's native H3 API. The check deliberately validates public/runtime contracts only. It does not import optional accelerators and therefore cannot make their installation a hard dependency. """ issues: list[str] = [] try: import comfy.ldm.minimax.model as h3_model except Exception as exc: # pragma: no cover - requires a broken Comfy install return [f"cannot import native MiniMax H3: {exc}"] layout_cls = getattr(h3_model, "PackedLayout", None) model_cls = getattr(h3_model, "MiniMaxH3Model", None) if layout_cls is None: issues.append("PackedLayout is missing") else: try: missing = _missing_callable_parameters( layout_cls.__init__, positional=( "text_len", "latent_t", "latent_h", "latent_w", "audio_t", ), keywords=( "keyframes", "refs", ), ) for name in missing: issues.append(f"PackedLayout no longer accepts '{name}'") except (TypeError, ValueError) as exc: issues.append(f"cannot inspect PackedLayout: {exc}") if model_cls is None: issues.append("MiniMaxH3Model is missing") else: for name in ( "forward", "rope_freqs", "_cond_video_rows", "_cond_audio_rows", ): if not hasattr(model_cls, name): issues.append(f"MiniMaxH3Model.{name} is missing") if tuple(getattr(h3_model, "FRAME_PER_TOKEN", ())) != (1, 4, 4, 4, 4): issues.append("MiniMax H3 temporal compression grid changed") try: import comfy.model_base as model_base base_cls = getattr(model_base, "MiniMaxH3", None) if base_cls is None or not hasattr(base_cls, "extra_conds"): issues.append("native MiniMaxH3 BaseModel.extra_conds is missing") except Exception as exc: issues.append(f"cannot inspect MiniMaxH3 BaseModel: {exc}") try: from comfy.patcher_extension import WrappersMP for name in ("APPLY_MODEL", "DIFFUSION_MODEL"): if not hasattr(WrappersMP, name): issues.append(f"WrappersMP.{name} is missing") except Exception as exc: issues.append(f"cannot import model wrapper API: {exc}") try: import comfy.nested_tensor if not hasattr(comfy.nested_tensor, "NestedTensor"): issues.append("comfy.nested_tensor.NestedTensor is missing") except Exception as exc: issues.append(f"cannot import NestedTensor API: {exc}") return issues def run_native_layout_self_test() -> str: """Exercise the installed native H3 PackedLayout without loading a model. This catches the most dangerous class of upstream change: a layout that can still be constructed but no longer maps reference/target rows the way the Continuum adapter expects. """ import torch import comfy.ldm.minimax.model as h3_model from .constants import ( MARK_AUDIO_CONTEXT, MARK_AUDIO_END_FRAME, MARK_AUDIO_OVERHANG, MARK_CONTEXT_FRAMES, MARK_VIDEO_CONTEXT, ) from .layout_adapter import normalize_condition_latents, patch_layout_in_place video = torch.zeros(1, 24, 2, 2, 2) # five-frame context audio = torch.zeros(1, 32, 2, 8) ref = { "kind": "video_audio", "latent_t": 2, "latent_h": 2, "latent_w": 2, "ref_audio_t": 8, "latent": video, "audio_latent": audio, MARK_VIDEO_CONTEXT: True, MARK_CONTEXT_FRAMES: 5, MARK_AUDIO_CONTEXT: True, MARK_AUDIO_END_FRAME: 5.0, MARK_AUDIO_OVERHANG: -1.0 / 3.0, } layout = h3_model.PackedLayout( 3, 7, 2, 2, 10, keyframes=None, refs=[ref] ) position_id = id(layout.position_ids) payload = {"layout": layout, "keyframes": [], "refs": [ref]} normalize_condition_latents(payload) result = patch_layout_in_place(payload, strict=True, debug=False) if id(layout.position_ids) != position_id: raise CompatibilityError("layout self-test replaced position_ids") ref_video = next((a, b) for a, b, kind in layout.segments if kind == "ref_img") target_video = next((a, b) for a, b, kind in layout.segments if kind == "video") ra, rb = ref_video va, _vb = target_video if not torch.equal(layout.position_ids[ra:rb], layout.position_ids[va : va + (rb - ra)]): raise CompatibilityError("layout self-test could not align video context") audio_refs = [ { "kind": "audio", "ref_audio_t": length, "audio_latent": torch.zeros(1, 32, 2, length), } for length in (2, 3, 4) ] audio_layout = h3_model.PackedLayout( 3, 7, 2, 2, 10, keyframes=None, refs=audio_refs ) audio_segments = [ stop - start for start, stop, kind in audio_layout.segments if kind == "ref_audio" ] packed_audio_rows = torch.cat( [h3_model.pack_audio(item["audio_latent"]) for item in audio_refs], dim=0 ).shape[0] if audio_segments != [4, 6, 8] or sum(audio_segments) != packed_audio_rows: raise CompatibilityError( "layout self-test found a multi-Reference-Audio packed-row mismatch" ) return ( f"native PackedLayout self-test passed; rows={layout.position_ids.shape[0]}, " f"position_ids_id={result['position_ids_id']}, " f"reference_audio_rows={packed_audio_rows}" ) def ensure_native_h3_base_model(base_model: Any) -> None: """Validate a ComfyUI BaseModel instance before adding our wrapper.""" inner = getattr(base_model, "diffusion_model", None) if inner is None: raise CompatibilityError("MODEL does not expose diffusion_model") missing = [ name for name in ( "blocks", "final_layer", "patch_size", "latents_dim", "audio_latents_dim", "rope_freqs", ) if not hasattr(inner, name) ] if missing: actual = f"{type(inner).__module__}.{type(inner).__name__}" raise CompatibilityError( f"MiniMax H3 model contract is unavailable on {actual}; missing " + ", ".join(missing) ) def _wrapper_keys(model: Any) -> tuple[str, ...]: """Collect ModelPatcher wrapper keys without depending on enum values.""" wrappers = getattr(model, "wrappers", {}) or {} found: list[str] = [] if not isinstance(wrappers, dict): return () for group in wrappers.values(): if not isinstance(group, dict): continue found.extend(str(key) for key in group.keys()) return tuple(found) def _contains_any(values: Iterable[str], *needles: str) -> bool: text = " ".join(values).lower() return any(needle.lower() in text for needle in needles) def accelerator_summary(model: Any) -> str: """Best-effort, non-authoritative summary of attached accelerators. Optional custom nodes expose different public markers across releases. The summary therefore reports only what is observable and never gates execution. """ options = getattr(model, "model_options", {}) or {} transformer = options.get("transformer_options", {}) or {} wrapper_keys = _wrapper_keys(model) parts: list[str] = [] if _contains_any(wrapper_keys, "spectrum"): parts.append("Spectrum wrapper detected") sol_marker = transformer.get("sol_compose") is not None or _contains_any( wrapper_keys, "sol_attn", "sol-attn", "solattn" ) if sol_marker: parts.append("Sol-Attn marker detected") if transformer.get("optimized_attention_override") is not None: if sol_marker: parts.append("chained attention override present (Sage/other fallback possible)") else: parts.append("attention override present (Sage/other)") if options.get("h3_continuum_join"): parts.append("Continuum APPLY_MODEL wrapper installed") return "; ".join(parts) if parts else "accelerator markers not detected (informational only)"