"""DUMAS MiniMax H3 RefMod storage helpers. This module deliberately works with the ``H3_REF_MODS`` object produced by the upstream MiniMax H3 RefMod nodes. It adds DUMAS-owned persistence policy without copying or shadowing the upstream extractor/loader implementation. """ from __future__ import annotations import os import re import sys try: import torch except ImportError: # import-time test fallback; ComfyUI supplies torch at runtime torch = None def _registered_refmod_root(): import folder_paths try: roots = list(folder_paths.get_folder_paths("refmods")) except Exception: roots = [] return os.path.realpath(roots[0] if roots else os.path.join(folder_paths.models_dir, "refmods")) def _safe_name(value, fallback="refmod"): value = str(value or "").strip() value = value.replace("\\", "/").split("/")[-1] value = re.sub(r"[^A-Za-z0-9._ -]+", "_", value).strip(" .") return value or fallback def _safe_destination(root, subfolder, filename): root = os.path.realpath(root) parts = [p for p in str(subfolder or "").replace("\\", "/").split("/") if p] if any(p in (".", "..") for p in parts): raise ValueError("RefMod subfolder must not contain '.' or '..'.") path = os.path.realpath(os.path.join(root, *parts, filename)) try: inside = os.path.commonpath((root, path)) == root except ValueError: inside = False if not inside: raise ValueError("RefMod destination must remain inside the selected folder.") return path def _next_path(path, reserved=()): stem, ext = os.path.splitext(path) index = 2 candidate = path reserved = {os.path.normcase(item) for item in reserved} while (os.path.normcase(candidate) in reserved or os.path.exists(candidate) or os.path.exists(candidate + ".safetensors") or os.path.exists(candidate + ".json")): candidate = f"{stem}_{index}{ext}" index += 1 return candidate def _mod_path(mod): return str(getattr(mod, "path", "") or "") def _continuum_reference_bundle_type(): """Resolve Continuum's native V3.9 bundle without copying its code.""" import importlib candidates = [ module for name, module in list(sys.modules.items()) if module is not None and name.endswith(".v3.reference_images_v39") ] try: candidates.append(importlib.import_module("v3.reference_images_v39")) except Exception: pass for module in candidates: bundle = getattr(module, "ReferenceImagesV39Bundle", None) if bundle is not None: return bundle raise RuntimeError( "DUMAS RefMod-to-Continuum requires the original " "ComfyUI-H3-Continuum v3.reference_images_v39 module." ) def _decode_refmod_image(video_vae, mod): if torch is None: raise RuntimeError("DUMAS RefMod-to-Continuum requires PyTorch/ComfyUI.") latent = getattr(mod, "latent", None) if getattr(mod, "kind", None) == "audio" or latent is None: return None if not torch.is_tensor(latent) or latent.ndim != 5: raise ValueError(f"RefMod '{getattr(mod, 'name', 'unknown')}' has no visual H3 latent.") with torch.no_grad(): decoded = video_vae.decode(latent[:, :, :1]) if not torch.is_tensor(decoded): raise ValueError("The connected H3 video VAE returned a non-tensor image.") if decoded.ndim == 5: decoded = decoded.reshape(-1, decoded.shape[-3], decoded.shape[-2], decoded.shape[-1]) if decoded.ndim != 4 or decoded.shape[0] < 1 or decoded.shape[-1] < 3: raise ValueError(f"Decoded RefMod image has unexpected shape {tuple(decoded.shape)}.") return decoded[:1, :, :, :3].clamp(0.0, 1.0).float().cpu() def _prompt_selectors(prompt, count): """Return R-slot selectors from chunk headers and @R tags.""" if not prompt: return ("all",) * 9 text = str(prompt) markers = list(re.finditer(r"\[[^\]]*?-[^\]]*?s\]", text, re.IGNORECASE)) if not markers: return ("all",) * 9 selectors = [] for ref_index in range(1, 10): chunks = [] for chunk_index, marker in enumerate(markers[:count], start=1): end = markers[chunk_index].start() if chunk_index < len(markers) else len(text) if re.search(rf"@R{ref_index}(?![A-Za-z0-9_])", text[marker.start():end], re.IGNORECASE): chunks.append(str(chunk_index)) selectors.append(",".join(chunks) or "off") return tuple(selectors) class DumasH3RefModSave: """Save upstream MiniMax H3 RefMods using an explicit DUMAS policy. ``input_folder`` is intentionally explicit: standard ComfyUI IMAGE and VIDEO tensors do not retain their source filesystem path. A folder-aware loader can connect its path here when it exposes one. """ @classmethod def INPUT_TYPES(cls): return { "required": { "mods": ("H3_REF_MODS",), "filename_prefix": ("STRING", {"default": ""}), "subfolder": ("STRING", {"default": ""}), "save_location": (["Registered RefMods", "Input folder", "Custom folder"], {"default": "Registered RefMods"}), "collision_policy": (["Increment filename", "Replace", "Fail"], {"default": "Increment filename"}), }, "optional": { "input_folder": ("STRING", {"default": "", "forceInput": True}), "custom_output_folder": ("STRING", {"default": "", "forceInput": True}), }, } RETURN_TYPES = ("H3_REF_MODS", "STRING") RETURN_NAMES = ("mods", "saved_paths") FUNCTION = "save" OUTPUT_NODE = True CATEGORY = "Dumas/MiniMax H3/RefMod" DESCRIPTION = ( "Save H3 RefMods atomically. Registered RefMods is the portable default; " "Input folder and Custom folder are explicit server-side destinations." ) def save(self, mods, filename_prefix="", subfolder="", save_location="Registered RefMods", collision_policy="Increment filename", input_folder="", custom_output_folder=""): if not mods: raise ValueError("The H3 RefMod bundle is empty; nothing to save.") if save_location == "Registered RefMods": root = _registered_refmod_root() os.makedirs(root, exist_ok=True) elif save_location == "Input folder": raw_folder = str(input_folder or "").strip() if not raw_folder: raise ValueError("Input folder mode requires a connected input_folder path.") root = os.path.realpath(raw_folder) try: from .dumas_h3_refmod_picker import register_refmod_root except ImportError: register_refmod_root = lambda _path: None register_refmod_root(root) elif save_location == "Custom folder": raw_folder = str(custom_output_folder or "").strip() if not raw_folder: raise ValueError("Custom folder mode requires a connected custom_output_folder path.") root = os.path.realpath(raw_folder) try: from .dumas_h3_refmod_picker import register_refmod_root except ImportError: register_refmod_root = lambda _path: None register_refmod_root(root) else: raise ValueError(f"Unknown RefMod save location: {save_location!r}") if not os.path.isdir(root): raise ValueError(f"RefMod destination folder does not exist: {root}") if not os.access(root, os.W_OK): raise ValueError(f"RefMod destination folder is not writable: {root}") planned = [] used = set() for mod, _strength in mods: name = _safe_name(f"{filename_prefix}{getattr(mod, 'name', 'refmod')}") path = _safe_destination(root, subfolder, name) if collision_policy == "Increment filename": path = _next_path(path, used) elif os.path.normcase(path) in used: path = _next_path(path, used) elif collision_policy == "Fail" and (os.path.exists(path) or os.path.exists(path + ".safetensors")): raise FileExistsError(f"RefMod already exists: {path}. Choose another name or policy.") elif collision_policy != "Replace": raise ValueError(f"Unknown collision policy: {collision_policy!r}") source = _mod_path(mod) if source and os.path.normcase(os.path.realpath(source)) == os.path.normcase(path): raise ValueError("RefMod destination is the source file; choose another folder or name.") used.add(os.path.normcase(path)) planned.append((mod, path)) saved = [] for mod, path in planned: os.makedirs(os.path.dirname(path), exist_ok=True) if not hasattr(mod, "save"): raise TypeError("Connected H3_REF_MODS contains an object without a save() method.") saved.append(mod.save(path)) report = "\n".join(saved) print(f"[DUMAS H3 RefMod Save] {save_location}; {collision_policy}; saved {len(saved)} file(s):\n{report}") return {"ui": {"text": saved}, "result": (mods, report)} class DumasH3RefModsToContinuum: """Decode visual RefMods into Continuum's native V3.9 image bundle.""" @classmethod def INPUT_TYPES(cls): return { "required": { "mods": ("H3_REF_MODS",), "video_vae": ("VAE",), "routing": (["All chunks", "Prompt @R tags"], {"default": "Prompt @R tags"}), "chunk_count": ("INT", {"default": 1, "min": 1, "max": 16}), }, "optional": { "sequence_prompt": ("STRING", {"default": "", "multiline": True}), "base_reference_images": ("H3_CONTINUUM_REFERENCE_IMAGES_V39",), "reference_offset": ("INT", {"default": 0, "min": 0, "max": 8}), }, } RETURN_TYPES = ("H3_CONTINUUM_REFERENCE_IMAGES_V39", "STRING") RETURN_NAMES = ("reference_images", "info") FUNCTION = "convert" CATEGORY = "Dumas/MiniMax H3/RefMod" DESCRIPTION = ( "Decode visual H3 RefMods and feed them through Continuum's native " "V3.9 Reference Images input. Connect the sequence prompt to route @R " "tags per chunk." ) def convert(self, mods, video_vae, routing="Prompt @R tags", chunk_count=1, sequence_prompt="", base_reference_images=None, reference_offset=0): if not mods and base_reference_images is None: raise ValueError("The H3 RefMod bundle is empty.") if routing not in ("All chunks", "Prompt @R tags"): raise ValueError(f"Unknown RefMod routing mode: {routing!r}") images, skipped_audio, ignored_strength = [], [], [] offset = int(reference_offset) if not 0 <= offset <= 8: raise ValueError("reference_offset must be between 0 and 8.") if base_reference_images is not None: base_images = getattr(base_reference_images, "images", None) if not isinstance(base_images, (tuple, list)) or len(base_images) != 9: raise ValueError("base_reference_images is not a valid Continuum V3.9 bundle.") slots = list(base_images) else: slots = [None] * 9 seen = set() for mod, _strength in mods: if getattr(mod, "kind", None) == "audio": skipped_audio.append(getattr(mod, "name", "audio")) continue source_key = _mod_path(mod) or (getattr(mod, "name", "refmod"), id(mod)) if source_key in seen: continue seen.add(source_key) strength = float(_strength) if strength <= 0: continue if abs(strength - 1.0) > 1e-6: ignored_strength.append(getattr(mod, "name", "refmod")) target = offset + len(images) if target >= 9: raise ValueError("Continuum V3.9 supports at most nine RefMod image slots.") image = _decode_refmod_image(video_vae, mod) if image is not None: images.append(image) if slots[offset + len(images) - 1] is not None: raise ValueError("A RefMod slot overlaps an existing image reference.") slots[offset + len(images) - 1] = image if not images and base_reference_images is None: raise ValueError("No visual RefMods were found; audio-only RefMods cannot feed image references.") selectors = (("all",) * 9 if routing == "All chunks" else _prompt_selectors(sequence_prompt, int(chunk_count))) bundle = _continuum_reference_bundle_type()( images=tuple(slots), reference_use="Per chunk", selectors=selectors, ) details = [f"decoded {len(images)} visual RefMod(s) into Continuum slots starting at R{offset + 1}"] if base_reference_images is not None: details.append("merged with builder image references") details.append("routing=all chunks" if routing == "All chunks" else "routing=prompt @R tags") if skipped_audio: details.append("skipped audio-only: " + ", ".join(skipped_audio)) if ignored_strength: details.append("native image routing ignores weights: " + ", ".join(ignored_strength)) return bundle, "; ".join(details) NODE_CLASS_MAPPINGS = { "DumasH3RefModSave": DumasH3RefModSave, "DumasH3RefModsToContinuum": DumasH3RefModsToContinuum, } NODE_DISPLAY_NAME_MAPPINGS = { "DumasH3RefModSave": "DUMAS H3 RefMod Save", "DumasH3RefModsToContinuum": "DUMAS H3 RefMods to Continuum", }