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

207 lines
6.3 KiB
Python

"""Versioned stream-target policies for future Continuum refinement modes."""
from __future__ import annotations
import hashlib
import json
from dataclasses import dataclass
from types import MappingProxyType
from typing import Any, Mapping
MAGIC = "H3_CONTINUUM_REFINE_TARGET"
SCHEMA_VERSION = 1
EXECUTION_MAGIC = "H3_CONTINUUM_TARGETED_REFINE_EXECUTION"
EXECUTION_SCHEMA_VERSION = 1
MODE_VIDEO_ONLY = "video_only"
MODE_AUDIO_ONLY = "audio_only"
MODE_VIDEO_AUDIO = "video_audio"
MODES = (MODE_VIDEO_ONLY, MODE_AUDIO_ONLY, MODE_VIDEO_AUDIO)
NOISE_SEEDED_RANDOM = "seeded_random"
NOISE_ZERO = "zero"
OUTPUT_SAMPLED = "sampled"
OUTPUT_INPUT_PASSTHROUGH = "input_passthrough_bit_exact"
VIDEO_ONLY_SEED_NAMESPACE = "h3-continuum-refine-v1"
AUDIO_ONLY_SEED_NAMESPACE = "h3-continuum-refine-audio-v1"
VIDEO_AUDIO_SEED_NAMESPACE = "h3-continuum-refine-av-v1"
class RefineTargetError(ValueError):
"""Raised when a target policy or target execution contract is invalid."""
@dataclass(frozen=True)
class RefineTarget:
"""One immutable target policy; it contains no Tensor or runtime object."""
mode: str
contract: Mapping[str, Any]
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 _stream_policy(*, noise: str, mask: int, output: str) -> dict[str, Any]:
return {
"noise": str(noise),
"mask": int(mask),
"output": str(output),
}
_POLICIES: dict[str, dict[str, Any]] = {
MODE_VIDEO_ONLY: {
"video": _stream_policy(
noise=NOISE_SEEDED_RANDOM,
mask=1,
output=OUTPUT_SAMPLED,
),
"audio": _stream_policy(
noise=NOISE_ZERO,
mask=0,
output=OUTPUT_INPUT_PASSTHROUGH,
),
"seed_namespace": VIDEO_ONLY_SEED_NAMESPACE,
},
MODE_AUDIO_ONLY: {
"video": _stream_policy(
noise=NOISE_ZERO,
mask=0,
output=OUTPUT_INPUT_PASSTHROUGH,
),
"audio": _stream_policy(
noise=NOISE_SEEDED_RANDOM,
mask=1,
output=OUTPUT_SAMPLED,
),
"seed_namespace": AUDIO_ONLY_SEED_NAMESPACE,
},
MODE_VIDEO_AUDIO: {
"video": _stream_policy(
noise=NOISE_SEEDED_RANDOM,
mask=1,
output=OUTPUT_SAMPLED,
),
"audio": _stream_policy(
noise=NOISE_SEEDED_RANDOM,
mask=1,
output=OUTPUT_SAMPLED,
),
"seed_namespace": VIDEO_AUDIO_SEED_NAMESPACE,
},
}
def make_refine_target(mode: str) -> RefineTarget:
canonical_mode = str(mode).strip().lower()
if canonical_mode not in MODES:
raise RefineTargetError(f"unsupported refine target mode {mode!r}")
policy = _POLICIES[canonical_mode]
contract: dict[str, Any] = {
"magic": MAGIC,
"schema_version": SCHEMA_VERSION,
"mode": canonical_mode,
"video": dict(policy["video"]),
"audio": dict(policy["audio"]),
"seed_namespace": str(policy["seed_namespace"]),
}
contract["target_hash"] = _identity(contract)
return RefineTarget(
mode=canonical_mode,
contract=MappingProxyType(contract),
)
def resolve_refine_target(value: RefineTarget | str | None) -> RefineTarget:
if value is None:
return make_refine_target(MODE_VIDEO_ONLY)
if isinstance(value, str):
return make_refine_target(value)
if not isinstance(value, RefineTarget):
raise RefineTargetError("refine_target must be a RefineTarget or mode string")
rebuilt = make_refine_target(value.mode)
if dict(rebuilt.contract) != dict(value.contract):
raise RefineTargetError("refine_target contract identity is inconsistent")
return value
def serializable_target_contract(target: RefineTarget) -> dict[str, Any]:
resolved = resolve_refine_target(target)
return {
**dict(resolved.contract),
"video": dict(resolved.contract["video"]),
"audio": dict(resolved.contract["audio"]),
}
def derive_target_refine_seed(
refine_seed: int,
physical_group_index: int,
target: RefineTarget | str,
) -> int:
if type(refine_seed) is not int or refine_seed < 0:
raise RefineTargetError("refine_seed must be a non-negative integer")
if type(physical_group_index) is not int or physical_group_index < 0:
raise RefineTargetError("physical_group_index must be a non-negative integer")
resolved = resolve_refine_target(target)
namespace = str(resolved.contract["seed_namespace"])
payload = f"{namespace}:{refine_seed}:{physical_group_index}".encode("ascii")
return int.from_bytes(hashlib.blake2b(payload, digest_size=8).digest(), "big")
_SIGMA_RANGE_FIELDS = (
"schema_version",
"mode",
"source_sigma_hash",
"sigma_hash",
"start_sigma",
"end_sigma",
"evaluation_count",
"source_evaluation_count",
"start_index",
"end_index",
)
def build_target_execution_contract(
target: RefineTarget,
refine_schedule_contract: Mapping[str, Any],
) -> dict[str, Any]:
"""Combine target policy with sigma-range identity without mutating V1."""
resolved = resolve_refine_target(target)
if not isinstance(refine_schedule_contract, Mapping):
raise RefineTargetError("refine_schedule_contract must be a mapping")
missing = [
name for name in _SIGMA_RANGE_FIELDS if name not in refine_schedule_contract
]
if missing or not refine_schedule_contract.get("schedule_hash"):
details = ", ".join([*missing, "schedule_hash"] if not refine_schedule_contract.get("schedule_hash") else missing)
raise RefineTargetError(f"refine schedule range identity is incomplete: {details}")
sigma_range = {
name: refine_schedule_contract[name] for name in _SIGMA_RANGE_FIELDS
}
sigma_range["source_schedule_hash"] = str(
refine_schedule_contract["schedule_hash"]
)
contract: dict[str, Any] = {
"magic": EXECUTION_MAGIC,
"schema_version": EXECUTION_SCHEMA_VERSION,
"policy_authority": "refine_target_contract_v1",
"target": serializable_target_contract(resolved),
"sigma_range": sigma_range,
}
contract["execution_hash"] = _identity(contract)
return contract