Files
ComfyUI-H3-Continuum-Tiled/tests/terminal_merge_diagnostics.py
T

379 lines
12 KiB
Python

"""Tests-only capture and comparison helpers for Terminal Merge diagnostics.
This module deliberately has no production imports or runtime hooks. Tests can
monkeypatch Core and Continuum boundaries, feed the captured values here, and
identify the first pipeline stage that differs without changing generation
semantics.
"""
from __future__ import annotations
from dataclasses import dataclass
from enum import Enum
from hashlib import sha256
import json
from pathlib import Path
from typing import Any, Mapping
import torch
STAGE_ORDER = (
"A_pre_sampler",
"B_first_model_call",
"C_sampled_physical_av",
"D_split_recombine",
"E_decode_assembly",
)
@dataclass(frozen=True)
class TensorFingerprint:
shape: tuple[int, ...]
dtype: str
sha256: str
def as_dict(self) -> dict[str, Any]:
return {
"shape": list(self.shape),
"dtype": self.dtype,
"sha256": self.sha256,
}
@dataclass(frozen=True)
class TensorDifference:
same_shape: bool
same_dtype: bool
bit_exact: bool
allclose: bool
max_abs_diff: float | None
mean_abs_diff: float | None
@dataclass(frozen=True)
class StageSnapshot:
name: str
sha256: str
payload: Any
@dataclass(frozen=True)
class StageComparison:
name: str
equal: bool
core_sha256: str | None
continuum_sha256: str | None
missing_from: str | None = None
def _tensor_raw_bytes(tensor: torch.Tensor) -> bytes:
value = tensor.detach().to("cpu").contiguous()
if value.numel() == 0:
return b""
return value.reshape(-1).view(torch.uint8).numpy().tobytes()
def tensor_fingerprint(tensor: torch.Tensor) -> TensorFingerprint:
if not torch.is_tensor(tensor):
raise TypeError("tensor_fingerprint expects a torch.Tensor")
return TensorFingerprint(
shape=tuple(int(size) for size in tensor.shape),
dtype=str(tensor.dtype),
sha256=sha256(_tensor_raw_bytes(tensor)).hexdigest(),
)
def tensor_difference(
core: torch.Tensor,
continuum: torch.Tensor,
*,
rtol: float = 1.0e-5,
atol: float = 1.0e-6,
) -> TensorDifference:
if not torch.is_tensor(core) or not torch.is_tensor(continuum):
raise TypeError("tensor_difference expects two torch.Tensor values")
same_shape = tuple(core.shape) == tuple(continuum.shape)
same_dtype = core.dtype == continuum.dtype
bit_exact = (
same_shape
and same_dtype
and tensor_fingerprint(core).sha256 == tensor_fingerprint(continuum).sha256
)
if not same_shape:
return TensorDifference(
same_shape=False,
same_dtype=same_dtype,
bit_exact=False,
allclose=False,
max_abs_diff=None,
mean_abs_diff=None,
)
core_value = core.detach().to("cpu")
continuum_value = continuum.detach().to("cpu")
if core_value.is_complex() or continuum_value.is_complex():
core_numeric = core_value.to(torch.complex128)
continuum_numeric = continuum_value.to(torch.complex128)
else:
core_numeric = core_value.to(torch.float64)
continuum_numeric = continuum_value.to(torch.float64)
if core_numeric.numel() == 0:
max_abs_diff = 0.0
mean_abs_diff = 0.0
else:
absolute = (core_numeric - continuum_numeric).abs()
max_abs_diff = float(absolute.max().item())
mean_abs_diff = float(absolute.mean().item())
return TensorDifference(
same_shape=True,
same_dtype=same_dtype,
bit_exact=bit_exact,
allclose=bool(
torch.allclose(
core_numeric,
continuum_numeric,
rtol=rtol,
atol=atol,
equal_nan=True,
)
),
max_abs_diff=max_abs_diff,
mean_abs_diff=mean_abs_diff,
)
def packed_layout_snapshot(layout: Any) -> dict[str, Any]:
return {
"signature": stable_snapshot(getattr(layout, "signature", None)),
"segments": stable_snapshot(getattr(layout, "segments", None)),
"position_ids": stable_snapshot(getattr(layout, "position_ids", None)),
}
def stable_snapshot(value: Any) -> Any:
"""Convert diagnostic data to deterministic JSON-compatible state."""
if torch.is_tensor(value):
return {"kind": "tensor", **tensor_fingerprint(value).as_dict()}
if isinstance(value, TensorFingerprint):
return {"kind": "tensor", **value.as_dict()}
if value is None or isinstance(value, (bool, int, str)):
return value
if isinstance(value, float):
return {"kind": "float", "hex": value.hex()}
if isinstance(value, bytes):
return {
"kind": "bytes",
"length": len(value),
"sha256": sha256(value).hexdigest(),
}
if isinstance(value, (Path, torch.device, torch.dtype)):
return str(value)
if isinstance(value, Enum):
return {
"kind": "enum",
"type": f"{type(value).__module__}.{type(value).__qualname__}",
"value": stable_snapshot(value.value),
}
if isinstance(value, slice):
return {
"kind": "slice",
"start": value.start,
"stop": value.stop,
"step": value.step,
}
if isinstance(value, Mapping):
return {
"kind": "mapping",
"items": [
[str(key), stable_snapshot(item)]
for key, item in sorted(value.items(), key=lambda pair: str(pair[0]))
],
}
if isinstance(value, tuple):
return {"kind": "tuple", "items": [stable_snapshot(item) for item in value]}
if isinstance(value, list):
return {"kind": "list", "items": [stable_snapshot(item) for item in value]}
if isinstance(value, (set, frozenset)):
items = [stable_snapshot(item) for item in value]
items.sort(key=lambda item: json.dumps(item, sort_keys=True, separators=(",", ":")))
return {"kind": type(value).__name__, "items": items}
if callable(value):
return {
"kind": "callable",
"module": getattr(value, "__module__", type(value).__module__),
"qualname": getattr(value, "__qualname__", type(value).__qualname__),
}
if all(hasattr(value, name) for name in ("signature", "segments", "position_ids")):
return {"kind": "packed_layout", **packed_layout_snapshot(value)}
if hasattr(value, "__dict__"):
public_state = {
key: item
for key, item in vars(value).items()
if not key.startswith("_") and not callable(item)
}
return {
"kind": "object",
"type": f"{type(value).__module__}.{type(value).__qualname__}",
"state": stable_snapshot(public_state),
}
raise TypeError(f"Unsupported diagnostic value: {type(value)!r}")
def snapshot_sha256(payload: Any) -> str:
normalized = stable_snapshot(payload)
encoded = json.dumps(
normalized,
ensure_ascii=True,
sort_keys=True,
separators=(",", ":"),
).encode("utf-8")
return sha256(encoded).hexdigest()
class DiagnosticCapture:
def __init__(self) -> None:
self._stages: dict[str, StageSnapshot] = {}
@property
def stages(self) -> Mapping[str, StageSnapshot]:
return self._stages
def capture(self, stage: str, **payload: Any) -> StageSnapshot:
if stage not in STAGE_ORDER:
raise ValueError(f"Unknown diagnostic stage: {stage}")
if stage in self._stages:
raise ValueError(f"Diagnostic stage already captured: {stage}")
normalized = stable_snapshot(payload)
snapshot = StageSnapshot(
name=stage,
sha256=snapshot_sha256(normalized),
payload=normalized,
)
self._stages[stage] = snapshot
return snapshot
def capture_pre_sampler(
self,
*,
physical_frames: int,
seed: int,
conditioning: Any,
latent: Any,
noise: torch.Tensor,
keyframes: Any = None,
qwen_images: Any = None,
minimax_refs: Any = None,
) -> StageSnapshot:
return self.capture(
"A_pre_sampler",
physical_frames=physical_frames,
seed=seed,
conditioning=conditioning,
latent=latent,
noise=noise,
keyframes=keyframes,
qwen_images=qwen_images,
minimax_refs=minimax_refs,
)
def capture_first_model_call(
self,
*,
minimax_payload: Any,
transformer_options: Any,
) -> StageSnapshot:
return self.capture(
"B_first_model_call",
minimax_payload=minimax_payload,
transformer_options=transformer_options,
)
def capture_sampled_physical_av(
self,
*,
video: torch.Tensor,
audio: torch.Tensor,
) -> StageSnapshot:
return self.capture(
"C_sampled_physical_av",
video=video,
audio=audio,
)
def capture_split_recombine(
self,
*,
physical_video: torch.Tensor,
physical_audio: torch.Tensor,
recombined_video: torch.Tensor,
recombined_audio: torch.Tensor,
) -> StageSnapshot:
return self.capture(
"D_split_recombine",
physical_video=physical_video,
physical_audio=physical_audio,
recombined_video=recombined_video,
recombined_audio=recombined_audio,
video_difference=tensor_difference(physical_video, recombined_video).__dict__,
audio_difference=tensor_difference(physical_audio, recombined_audio).__dict__,
)
def capture_decode_assembly(
self,
*,
physical_decoded: torch.Tensor,
assembled_decoded: torch.Tensor,
) -> StageSnapshot:
return self.capture(
"E_decode_assembly",
physical_decoded=physical_decoded,
assembled_decoded=assembled_decoded,
difference=tensor_difference(physical_decoded, assembled_decoded).__dict__,
)
def compare_captures(
core: DiagnosticCapture,
continuum: DiagnosticCapture,
) -> tuple[StageComparison, ...]:
comparisons = []
for stage in STAGE_ORDER:
core_stage = core.stages.get(stage)
continuum_stage = continuum.stages.get(stage)
missing = None
if core_stage is None and continuum_stage is None:
missing = "both"
elif core_stage is None:
missing = "core"
elif continuum_stage is None:
missing = "continuum"
comparisons.append(
StageComparison(
name=stage,
equal=(
core_stage is not None
and continuum_stage is not None
and core_stage.sha256 == continuum_stage.sha256
),
core_sha256=None if core_stage is None else core_stage.sha256,
continuum_sha256=None if continuum_stage is None else continuum_stage.sha256,
missing_from=missing,
)
)
return tuple(comparisons)
def first_divergent_stage(
core: DiagnosticCapture,
continuum: DiagnosticCapture,
) -> str | None:
for comparison in compare_captures(core, continuum):
if not comparison.equal:
return comparison.name
return None