Release v3.7.0 refinement foundation
This commit is contained in:
@@ -0,0 +1,214 @@
|
||||
"""Versioned, UI-independent sigma contracts for Continuum refinement.
|
||||
|
||||
The public Second Pass SIGMAS socket remains authoritative. These helpers attach
|
||||
meaning to that tensor without recreating it: External and Full retain the exact
|
||||
input object, while Tail and Partial return views into the same source values.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
import json
|
||||
from dataclasses import dataclass
|
||||
from types import MappingProxyType
|
||||
from typing import Any, Mapping
|
||||
|
||||
import torch
|
||||
|
||||
|
||||
MAGIC = "H3_CONTINUUM_REFINE_SCHEDULE"
|
||||
SCHEMA_VERSION = 1
|
||||
|
||||
MODE_EXTERNAL = "external"
|
||||
MODE_FULL = "full"
|
||||
MODE_TAIL = "tail"
|
||||
MODE_PARTIAL = "partial"
|
||||
MODES = (MODE_EXTERNAL, MODE_FULL, MODE_TAIL, MODE_PARTIAL)
|
||||
|
||||
NOISE_MODE_VIDEO_RANDOM_AUDIO_ZERO = "video_random_mask_1_audio_zero_mask_0"
|
||||
AUDIO_POLICY_LOCKED_PASSTHROUGH = "locked_first_pass_bit_exact_passthrough"
|
||||
|
||||
|
||||
class RefineScheduleError(ValueError):
|
||||
"""Raised when a refinement schedule cannot safely describe its SIGMAS."""
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class RefineSchedule:
|
||||
"""One validated effective SIGMAS tensor and its serializable identity."""
|
||||
|
||||
sigmas: torch.Tensor
|
||||
contract: Mapping[str, Any]
|
||||
source_sigma_hash: str
|
||||
|
||||
|
||||
def _validate_sigmas(sigmas: Any, *, name: str) -> torch.Tensor:
|
||||
if not torch.is_tensor(sigmas) or sigmas.ndim != 1 or sigmas.numel() < 2:
|
||||
raise RefineScheduleError(f"{name} must be a one-dimensional tensor with at least two values")
|
||||
detached = sigmas.detach()
|
||||
if not bool(torch.isfinite(detached.float()).all().item()):
|
||||
raise RefineScheduleError(f"{name} contains NaN or Inf")
|
||||
values = detached.float().to(device="cpu")
|
||||
if bool((values[1:] > values[:-1]).any().item()):
|
||||
raise RefineScheduleError(f"{name} must be monotonically non-increasing")
|
||||
return sigmas
|
||||
|
||||
|
||||
def sigma_hash(sigmas: torch.Tensor) -> str:
|
||||
"""Hash dtype, shape, and exact tensor bytes without changing the input."""
|
||||
|
||||
_validate_sigmas(sigmas, name="sigmas")
|
||||
cpu = sigmas.detach().to(device="cpu").contiguous()
|
||||
payload = cpu.view(torch.uint8).numpy().tobytes()
|
||||
digest = hashlib.sha256()
|
||||
digest.update(str(cpu.dtype).encode("ascii"))
|
||||
digest.update(b"|")
|
||||
digest.update(str(tuple(int(value) for value in cpu.shape)).encode("ascii"))
|
||||
digest.update(b"|")
|
||||
digest.update(payload)
|
||||
return digest.hexdigest()
|
||||
|
||||
|
||||
def _schedule_identity(contract: Mapping[str, Any]) -> str:
|
||||
payload = {
|
||||
key: value
|
||||
for key, value in contract.items()
|
||||
if key != "schedule_hash"
|
||||
}
|
||||
encoded = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
|
||||
return hashlib.sha256(encoded).hexdigest()
|
||||
|
||||
|
||||
def _build_schedule(
|
||||
source_sigmas: torch.Tensor,
|
||||
*,
|
||||
mode: str,
|
||||
start_index: int,
|
||||
end_index: int,
|
||||
) -> RefineSchedule:
|
||||
source = _validate_sigmas(source_sigmas, name="source_sigmas")
|
||||
canonical_mode = str(mode).lower()
|
||||
if canonical_mode not in MODES:
|
||||
raise RefineScheduleError(f"unsupported refine schedule mode {mode!r}")
|
||||
source_evaluations = int(source.numel()) - 1
|
||||
if type(start_index) is not int or type(end_index) is not int:
|
||||
raise RefineScheduleError("schedule indices must be integers")
|
||||
if start_index < 0 or end_index <= start_index or end_index > source_evaluations:
|
||||
raise RefineScheduleError(
|
||||
f"schedule range {start_index}:{end_index} is outside 0:{source_evaluations}"
|
||||
)
|
||||
|
||||
if start_index == 0 and end_index == source_evaluations:
|
||||
effective = source
|
||||
else:
|
||||
effective = source[start_index : end_index + 1]
|
||||
_validate_sigmas(effective, name="effective sigmas")
|
||||
effective_hash = sigma_hash(effective)
|
||||
source_hash = sigma_hash(source)
|
||||
values = tuple(float(value) for value in effective.detach().to(device="cpu").tolist())
|
||||
contract: dict[str, Any] = {
|
||||
"magic": MAGIC,
|
||||
"schema_version": SCHEMA_VERSION,
|
||||
"mode": canonical_mode,
|
||||
"sigma_values": values,
|
||||
"sigma_hash": effective_hash,
|
||||
"source_sigma_hash": source_hash,
|
||||
"start_sigma": values[0],
|
||||
"end_sigma": values[-1],
|
||||
"evaluation_count": len(values) - 1,
|
||||
"source_evaluation_count": source_evaluations,
|
||||
"start_index": start_index,
|
||||
"end_index": end_index,
|
||||
"noise_mode": NOISE_MODE_VIDEO_RANDOM_AUDIO_ZERO,
|
||||
"audio_policy": AUDIO_POLICY_LOCKED_PASSTHROUGH,
|
||||
}
|
||||
contract["schedule_hash"] = _schedule_identity(contract)
|
||||
return RefineSchedule(
|
||||
sigmas=effective,
|
||||
contract=MappingProxyType(contract),
|
||||
source_sigma_hash=source_hash,
|
||||
)
|
||||
|
||||
|
||||
def make_external_schedule(sigmas: torch.Tensor) -> RefineSchedule:
|
||||
evaluations = int(_validate_sigmas(sigmas, name="sigmas").numel()) - 1
|
||||
return _build_schedule(
|
||||
sigmas,
|
||||
mode=MODE_EXTERNAL,
|
||||
start_index=0,
|
||||
end_index=evaluations,
|
||||
)
|
||||
|
||||
|
||||
def make_full_schedule(sigmas: torch.Tensor) -> RefineSchedule:
|
||||
evaluations = int(_validate_sigmas(sigmas, name="sigmas").numel()) - 1
|
||||
return _build_schedule(
|
||||
sigmas,
|
||||
mode=MODE_FULL,
|
||||
start_index=0,
|
||||
end_index=evaluations,
|
||||
)
|
||||
|
||||
|
||||
def make_tail_schedule(
|
||||
sigmas: torch.Tensor,
|
||||
*,
|
||||
evaluation_count: int,
|
||||
) -> RefineSchedule:
|
||||
source_evaluations = int(_validate_sigmas(sigmas, name="sigmas").numel()) - 1
|
||||
if type(evaluation_count) is not int or not 1 <= evaluation_count <= source_evaluations:
|
||||
raise RefineScheduleError(
|
||||
f"tail evaluation_count must be between 1 and {source_evaluations}"
|
||||
)
|
||||
return _build_schedule(
|
||||
sigmas,
|
||||
mode=MODE_TAIL,
|
||||
start_index=source_evaluations - evaluation_count,
|
||||
end_index=source_evaluations,
|
||||
)
|
||||
|
||||
|
||||
def make_partial_schedule(
|
||||
sigmas: torch.Tensor,
|
||||
*,
|
||||
start_index: int,
|
||||
end_index: int,
|
||||
) -> RefineSchedule:
|
||||
return _build_schedule(
|
||||
sigmas,
|
||||
mode=MODE_PARTIAL,
|
||||
start_index=start_index,
|
||||
end_index=end_index,
|
||||
)
|
||||
|
||||
|
||||
def resolve_refine_schedule(
|
||||
sigmas: torch.Tensor,
|
||||
schedule: RefineSchedule | None = None,
|
||||
) -> RefineSchedule:
|
||||
"""Return External compatibility or validate an explicit internal schedule."""
|
||||
|
||||
source = _validate_sigmas(sigmas, name="sigmas")
|
||||
if schedule is None:
|
||||
return make_external_schedule(source)
|
||||
if not isinstance(schedule, RefineSchedule):
|
||||
raise RefineScheduleError("refine_schedule must be a RefineSchedule")
|
||||
if sigma_hash(source) != schedule.source_sigma_hash:
|
||||
raise RefineScheduleError("refine_schedule was derived from different source SIGMAS")
|
||||
rebuilt = _build_schedule(
|
||||
source,
|
||||
mode=str(schedule.contract.get("mode", "")),
|
||||
start_index=int(schedule.contract.get("start_index", -1)),
|
||||
end_index=int(schedule.contract.get("end_index", -1)),
|
||||
)
|
||||
if rebuilt.contract["schedule_hash"] != schedule.contract.get("schedule_hash"):
|
||||
raise RefineScheduleError("refine_schedule contract identity is inconsistent")
|
||||
return schedule
|
||||
|
||||
|
||||
def serializable_schedule_contract(schedule: RefineSchedule) -> dict[str, Any]:
|
||||
"""Return a mutable JSON-safe copy for Assembly/diagnostic identity."""
|
||||
|
||||
if not isinstance(schedule, RefineSchedule):
|
||||
raise RefineScheduleError("schedule must be a RefineSchedule")
|
||||
return dict(schedule.contract)
|
||||
Reference in New Issue
Block a user