Release v3.7.0 refinement foundation

This commit is contained in:
ukr8b3g-cmyk
2026-08-30 02:46:02 +09:00
parent ecc72dae9b
commit fe4ff9c20c
40 changed files with 2681 additions and 85 deletions
+93
View File
@@ -6,6 +6,11 @@ import torch
from ..constants import CONTINUITY_OPTIONS, FPS
from ..driving_audio import prepare_driving_audio_source
from ..guide_timeline import (
GUIDE_TYPE,
make_still_image_guide,
prepare_still_image_guide_source,
)
from ..hardening import diagnostics_is_full
from ..reference_video import (
REFERENCE_VIDEO_SIZE_EFFICIENT,
@@ -373,6 +378,90 @@ class H3ContinuumSamplerV36(H3ContinuumSamplerV35):
return _prepend_v36_transport_report(outputs, fallback_reason)
class H3ContinuumStillImageGuideV37:
"""One frame-based image anchor for the V3.7 sampler."""
DEPRECATED = False
CATEGORY = CONTINUUM_CATEGORY
DESCRIPTION = (
"Prepare one Still Image Guide at an absolute 24 fps output frame. "
"The V3.7 sampler resolves it to the owning physical group and Core frame_idx."
)
SEARCH_ALIASES = [
"H3 Continuum Still Image Guide",
"MiniMax H3 Add Guide timeline",
]
@classmethod
def INPUT_TYPES(cls):
return {
"required": {
"image": ("IMAGE",),
"absolute_frame": (
"INT",
{
"default": 0,
"min": 0,
"max": 0x7FFFFFFF,
"step": 1,
"display_name": "Absolute Frame (24 fps)",
"tooltip": (
"Zero-based frame on the final visible Continuum timeline."
),
},
),
}
}
RETURN_TYPES = (GUIDE_TYPE,)
RETURN_NAMES = ("guide",)
FUNCTION = "pack"
CATEGORY = CONTINUUM_CATEGORY
def pack(self, image, absolute_frame):
return (make_still_image_guide(image, absolute_frame),)
class H3ContinuumSamplerV37(H3ContinuumSamplerV36):
"""V3.6-compatible sampler with one physical-group Still Image Guide."""
DEPRECATED = False
CATEGORY = CONTINUUM_CATEGORY
DESCRIPTION = (
"H3 Continuum V3.7 Stage 2 sampler. It preserves V3.6 behavior and can "
"inject one Still Image Guide into only its resolved physical sampling group."
)
SEARCH_ALIASES = [
"H3 Continuum Sampler V3.7",
"MiniMax H3 absolute frame guide",
]
@classmethod
def INPUT_TYPES(cls):
schema = super().INPUT_TYPES()
optional = dict(schema.get("optional", {}))
optional["guide"] = (
GUIDE_TYPE,
{
"display_name": "Still Image Guide (Optional)",
"tooltip": (
"Optional V3.7 Still Image Guide. Only the owning physical "
"sampling group receives the Core minimax_keyframes entry."
),
},
)
schema["optional"] = optional
return schema
def run(self, guide=None, **kwargs):
guide_source = prepare_still_image_guide_source(
guide,
output_width=int(kwargs["width"]),
output_height=int(kwargs["height"]),
)
return super().run(guide_source=guide_source, **kwargs)
class H3ContinuumAssembleSeamV34(H3ContinuumAssembleSeamExperimental):
"""Assemble decoded chunks and select original Driving Audio when connected."""
@@ -553,6 +642,8 @@ NODE_CLASS_MAPPINGS = {
"H3ContinuumSamplerV34": H3ContinuumSamplerV34,
"H3ContinuumSamplerV35": H3ContinuumSamplerV35,
"H3ContinuumSamplerV36": H3ContinuumSamplerV36,
"H3ContinuumStillImageGuideV37": H3ContinuumStillImageGuideV37,
"H3ContinuumSamplerV37": H3ContinuumSamplerV37,
"H3ContinuumAssembleSeamV34": H3ContinuumAssembleSeamV34,
"H3ContinuumAssembleSeamV35": H3ContinuumAssembleSeamV35,
}
@@ -561,6 +652,8 @@ NODE_DISPLAY_NAME_MAPPINGS = {
"H3ContinuumSamplerV34": "H3 Continuum Sampler V3.4",
"H3ContinuumSamplerV35": "H3 Continuum Sampler V3.5",
"H3ContinuumSamplerV36": "H3 Continuum Sampler V3.6",
"H3ContinuumStillImageGuideV37": "H3 Continuum Still Image Guide V3.7",
"H3ContinuumSamplerV37": "H3 Continuum Sampler V3.7",
"H3ContinuumAssembleSeamV34": "H3 Continuum Assemble + Seam V3.4",
"H3ContinuumAssembleSeamV35": "H3 Continuum Assemble + Seam V3.5",
}
+2
View File
@@ -404,6 +404,7 @@ class H3ContinuumHiResFixV35:
refine_seed,
refine_context=None,
video_vae=None,
refine_schedule=None,
):
plan = _single_list_input("assembly_plan", assembly_plan)
if not _enabled_value(enabled):
@@ -495,6 +496,7 @@ class H3ContinuumHiResFixV35:
),
video_vae=vae,
conditioning_upscale_method=_CONDITIONING_UPSCALE_METHOD,
refine_schedule=refine_schedule,
)
return (
refined_video,
+4
View File
@@ -269,6 +269,7 @@ class H3ContinuumSamplerV3:
driving_audio_vae=None,
reference_video_source=None,
timeline_video_source=None,
guide_source=None,
capture_refine_context=False,
memory_attribution=False,
prompt_conditioning_cache=False,
@@ -352,6 +353,7 @@ class H3ContinuumSamplerV3:
driving_audio_vae=driving_audio_vae,
reference_video_source=reference_video_source,
timeline_video_source=timeline_video_source,
guide_source=guide_source,
capture_refine_context=bool(capture_refine_context),
memory_attribution=bool(memory_attribution),
prompt_conditioning_cache=bool(prompt_conditioning_cache),
@@ -678,6 +680,7 @@ class H3ContinuumSamplerProduction(H3ContinuumSamplerV3):
driving_audio_vae=None,
reference_video_source=None,
timeline_video_source=None,
guide_source=None,
capture_refine_context=False,
memory_attribution=False,
prompt_conditioning_cache=False,
@@ -731,6 +734,7 @@ class H3ContinuumSamplerProduction(H3ContinuumSamplerV3):
driving_audio_vae=driving_audio_vae,
reference_video_source=reference_video_source,
timeline_video_source=timeline_video_source,
guide_source=guide_source,
capture_refine_context=bool(capture_refine_context),
memory_attribution=bool(memory_attribution),
prompt_conditioning_cache=bool(prompt_conditioning_cache),
+46 -2
View File
@@ -15,6 +15,7 @@ from typing import Any
import torch
from ..constants import MARK_VIDEO_CONTEXT
from ..guide_timeline import MARK_STILL_IMAGE_GUIDE
MAGIC = "H3_CONTINUUM_REFINE_CONTEXT"
@@ -100,6 +101,32 @@ def _validate_optional_image(value: Any, name: str) -> None:
)
def _guide_image_map(value: Any) -> Mapping[int, torch.Tensor]:
if value is None:
return MappingProxyType({})
if not isinstance(value, Mapping):
raise RefineContextError("guide_images must be a frame-to-IMAGE mapping")
output: dict[int, torch.Tensor] = {}
for frame_index, image in value.items():
if type(frame_index) is not int or frame_index < 0:
raise RefineContextError("guide_images frame indices must be non-negative integers")
prepared = _optional_image(image, f"guide_images[{frame_index}]")
assert prepared is not None
output[frame_index] = prepared
return MappingProxyType(output)
def _validate_guide_images(value: Any, *, physical_frames: int) -> None:
if value is None:
return
if not isinstance(value, Mapping):
raise RefineContextError("refine group guide_images is invalid")
for frame_index, image in value.items():
if type(frame_index) is not int or not 0 <= frame_index < physical_frames:
raise RefineContextError("refine group guide image frame is outside the physical group")
_validate_optional_image(image, f"guide_images[{frame_index}]")
def make_refine_group(
*,
conditioning: Any,
@@ -113,6 +140,7 @@ def make_refine_group(
context_frames: int,
first_image: torch.Tensor | None = None,
last_image: torch.Tensor | None = None,
guide_images: Mapping[int, torch.Tensor] | None = None,
) -> dict[str, Any]:
"""Capture one physical First Pass sampling group's effective conditioning."""
@@ -138,7 +166,7 @@ def make_refine_group(
raise RefineContextError("refine group physical clip index is invalid")
if context_frames < 0:
raise RefineContextError("refine group context frame count is invalid")
return {
output = {
"group_id": group_id,
"logical_chunks": chunks,
"physical_frames": physical_frames,
@@ -151,6 +179,10 @@ def make_refine_group(
"first_image": _optional_image(first_image, "first_image"),
"last_image": _optional_image(last_image, "last_image"),
}
frozen_guides = _guide_image_map(guide_images)
if frozen_guides:
output["guide_images"] = frozen_guides
return output
def make_refine_context(
@@ -271,6 +303,10 @@ def validate_refine_context(
_validate_frozen_conditioning(group.get("conditioning"), group_id=expected_id)
_validate_optional_image(group.get("first_image"), "first_image")
_validate_optional_image(group.get("last_image"), "last_image")
_validate_guide_images(
group.get("guide_images"),
physical_frames=int(group["physical_frames"]),
)
if assembly_plan is not None:
if not isinstance(assembly_plan, Mapping):
@@ -448,6 +484,7 @@ def adapt_group_conditioning(
"keyframes_resized": 0,
"keyframes_reencoded": 0,
"keyframes_latent_fallback": 0,
"guide_keyframes_reencoded": 0,
"context_refs_resized": 0,
}
output: list[list[Any]] = []
@@ -474,7 +511,12 @@ def adapt_group_conditioning(
frame_index = int(keyframe.get("resolved_frame_index", -1))
image = None
crop = "disabled"
if frame_index == 0:
if bool(keyframe.get(MARK_STILL_IMAGE_GUIDE)):
guide_images = group.get("guide_images")
if isinstance(guide_images, Mapping):
image = guide_images.get(frame_index)
crop = "center"
elif frame_index == 0:
image = group.get("first_image")
elif frame_index == physical_frames - 1:
image = group.get("last_image")
@@ -488,6 +530,8 @@ def adapt_group_conditioning(
video_vae=video_vae,
)
stats["keyframes_reencoded"] += 1
if bool(keyframe.get(MARK_STILL_IMAGE_GUIDE)):
stats["guide_keyframes_reencoded"] += 1
else:
keyframe["latent"] = _resize_latent(
latent,
+214
View File
@@ -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)
+25 -2
View File
@@ -21,6 +21,12 @@ from .refine_context import (
adapt_group_conditioning,
validate_refine_context,
)
from .refine_schedule import (
RefineSchedule,
RefineScheduleError,
resolve_refine_schedule,
serializable_schedule_contract,
)
from .refine_sampling import sample_refine_chunk
@@ -387,10 +393,17 @@ def run_second_pass_groups(
clone_model_fn=None,
validate_refine_context_fn=None,
adapt_group_conditioning_fn=None,
refine_schedule: RefineSchedule | None = None,
) -> tuple[list[dict[str, Any]], list[Any], dict[str, Any], str]:
"""Refine complete physical groups while preserving first-pass audio exactly."""
validation = validate_second_pass_inputs(video_latents, audio_latents, assembly_plan)
try:
resolved_schedule = resolve_refine_schedule(sigmas, refine_schedule)
except RefineScheduleError as exc:
raise SecondPassContractError(f"refine schedule is invalid: {exc}") from exc
effective_sigmas = resolved_schedule.sigmas
schedule_contract = serializable_schedule_contract(resolved_schedule)
groups = _contract_groups(assembly_plan)
latent_builder = latent_builder or latent_from_cpu
sample_fn = sample_fn or sample_refine_chunk
@@ -424,7 +437,7 @@ def run_second_pass_groups(
conditioning=conditioning,
latent=nested_latent,
sampler=sampler,
sigmas=sigmas,
sigmas=effective_sigmas,
seed=physical_seed,
enable_preview=bool(enable_preview),
)
@@ -456,6 +469,7 @@ def run_second_pass_groups(
f"{group_index + 1} target conditioning: "
f"keyframes_resized={int(adaptation_stats.get('keyframes_resized', 0))}, "
f"keyframes_reencoded={int(adaptation_stats.get('keyframes_reencoded', 0))}, "
f"guide_keyframes_reencoded={int(adaptation_stats.get('guide_keyframes_reencoded', 0))}, "
f"context_refs_resized={int(adaptation_stats.get('context_refs_resized', 0))}"
)
group_report_lines.extend(
@@ -484,7 +498,14 @@ def run_second_pass_groups(
"refine_context is available.",
f"Physical groups: {validation['physical_group_count']}.",
"Sampling contract: video random noise/mask=1; audio zero noise/mask=0; "
"workflow SIGMAS are applied directly by Core.",
"the resolved RefineSchedule SIGMAS are applied directly by Core.",
"RefineSchedule: "
f"schema={schedule_contract['schema_version']}, "
f"mode={schedule_contract['mode']}, "
f"evaluations={schedule_contract['evaluation_count']}, "
f"start_sigma={schedule_contract['start_sigma']}, "
f"end_sigma={schedule_contract['end_sigma']}, "
f"sigma_hash={schedule_contract['sigma_hash']}.",
*prepared["warnings"],
*group_report_lines,
]
@@ -505,6 +526,8 @@ def run_second_pass_groups(
contract["refine_group_seeds"] = group_seeds
contract["audio_output"] = "bit_exact_first_pass_passthrough"
contract["audio_sampling"] = "zero_noise_mask_locked"
contract["refine_schedule"] = schedule_contract
contract["refine_schedule_identity"] = schedule_contract["schedule_hash"]
report_lines.append(
"Audio output: first-pass physical audio LATENT objects returned bit-exact; "
"temporary refined audio discarded."
+2
View File
@@ -78,6 +78,7 @@ class H3ContinuumSecondPassV35:
refine_seed,
refine_context=None,
video_vae=None,
refine_schedule=None,
):
return run_second_pass_groups(
model=_single_list_input("model", model),
@@ -98,6 +99,7 @@ class H3ContinuumSecondPassV35:
if video_vae is None
else _single_list_input("video_vae", video_vae)
),
refine_schedule=refine_schedule,
)