Files
ComfyUI-H3-Continuum-Tiled/v3/refine_scope.py
T

180 lines
6.0 KiB
Python

"""Versioned physical-group selection for Experimental selective refinement."""
from __future__ import annotations
import hashlib
import json
from collections.abc import Mapping, Sequence
from dataclasses import dataclass
from types import MappingProxyType
from typing import Any
MAGIC = "H3_CONTINUUM_REFINE_SCOPE"
SCHEMA_VERSION = 1
MODE_ALL = "all"
MODE_PHYSICAL_GROUP = "physical_group"
MODE_LOGICAL_CHUNK = "logical_chunk"
MODES = (MODE_ALL, MODE_PHYSICAL_GROUP, MODE_LOGICAL_CHUNK)
class RefineScopeError(ValueError):
"""Raised before preparation when a requested scope cannot be resolved."""
@dataclass(frozen=True)
class RefineScope:
"""One immutable scope resolution containing no Tensor or runtime object."""
mode: str
selected_group_indices: tuple[int, ...]
contract: Mapping[str, Any]
@property
def is_all(self) -> bool:
return self.mode == MODE_ALL
def _identity(payload: Mapping[str, Any]) -> str:
encoded = json.dumps(
dict(payload),
sort_keys=True,
separators=(",", ":"),
).encode("utf-8")
return hashlib.sha256(encoded).hexdigest()
def _physical_groups(assembly_plan: Mapping[str, Any]) -> list[Mapping[str, Any]]:
if not isinstance(assembly_plan, Mapping):
raise RefineScopeError("assembly_plan must be a mapping")
second_pass = assembly_plan.get("second_pass_contract")
if not isinstance(second_pass, Mapping) or second_pass.get("version") != 1:
raise RefineScopeError("assembly_plan has no Second Pass contract version 1")
groups = second_pass.get("physical_groups")
if (
not isinstance(groups, Sequence)
or isinstance(groups, (str, bytes))
or not groups
or not all(isinstance(group, Mapping) for group in groups)
):
raise RefineScopeError("assembly_plan has no physical groups")
return list(groups)
def _logical_chunks(group: Mapping[str, Any], group_index: int) -> tuple[int, ...]:
values = group.get("logical_chunks")
if (
not isinstance(values, Sequence)
or isinstance(values, (str, bytes))
or not values
or any(type(value) is not int or value <= 0 for value in values)
):
raise RefineScopeError(
f"physical group {group_index + 1} has invalid logical chunk identity"
)
chunks = tuple(int(value) for value in values)
if len(set(chunks)) != len(chunks):
raise RefineScopeError(
f"physical group {group_index + 1} repeats a logical chunk"
)
return chunks
def resolve_refine_scope(
mode: str | None,
scope_index: int,
assembly_plan: Mapping[str, Any],
) -> RefineScope:
"""Resolve one public 1-based selection to complete physical groups.
Logical chunks never split a physical group. Selecting either logical half of
a Terminal Merge group therefore selects the complete terminal pair.
"""
if mode is None:
canonical_mode = MODE_ALL
elif not isinstance(mode, str):
raise RefineScopeError(f"unsupported refine scope mode {mode!r}")
else:
canonical_mode = mode.strip().lower()
if canonical_mode not in MODES:
raise RefineScopeError(f"unsupported refine scope mode {mode!r}")
if type(scope_index) is not int or scope_index <= 0:
raise RefineScopeError("refine scope index must be a positive integer")
groups = _physical_groups(assembly_plan)
group_chunks = [
_logical_chunks(group, group_index)
for group_index, group in enumerate(groups)
]
terminal_expanded = False
requested_index: int | None = None
if canonical_mode == MODE_ALL:
selected = tuple(range(len(groups)))
elif canonical_mode == MODE_PHYSICAL_GROUP:
requested_index = int(scope_index)
selected_index = requested_index - 1
if selected_index >= len(groups):
raise RefineScopeError(
f"physical group {requested_index} is outside 1..{len(groups)}"
)
selected = (selected_index,)
else:
requested_index = int(scope_index)
matches = [
group_index
for group_index, chunks in enumerate(group_chunks)
if requested_index in chunks
]
if len(matches) != 1:
if matches:
raise RefineScopeError(
f"logical chunk {requested_index} belongs to multiple physical groups"
)
raise RefineScopeError(
f"logical chunk {requested_index} is not present in the assembly plan"
)
selected = (matches[0],)
selected_group = groups[selected[0]]
selected_chunks = group_chunks[selected[0]]
terminal_expanded = bool(
selected_group.get("terminal_merged") and len(selected_chunks) > 1
)
selected_chunks = tuple(
chunk
for group_index in selected
for chunk in group_chunks[group_index]
)
contract: dict[str, Any] = {
"magic": MAGIC,
"schema_version": SCHEMA_VERSION,
"mode": canonical_mode,
"requested_index": requested_index,
"selected_physical_group_indices": tuple(selected),
"selected_physical_groups": tuple(index + 1 for index in selected),
"selected_logical_chunks": tuple(selected_chunks),
"terminal_expanded": terminal_expanded,
}
contract["scope_hash"] = _identity(contract)
return RefineScope(
mode=canonical_mode,
selected_group_indices=selected,
contract=MappingProxyType(contract),
)
def serializable_scope_contract(scope: RefineScope) -> dict[str, Any]:
if not isinstance(scope, RefineScope):
raise RefineScopeError("refine_scope must be a RefineScope")
return {
**dict(scope.contract),
"selected_physical_group_indices": list(
scope.contract["selected_physical_group_indices"]
),
"selected_physical_groups": list(scope.contract["selected_physical_groups"]),
"selected_logical_chunks": list(scope.contract["selected_logical_chunks"]),
}