Release V3.8 source, illustrated manual and Spectrum workflow

This commit is contained in:
ukr8b3g-cmyk
2026-09-07 21:25:51 +09:00
parent 0a7c6703b7
commit 315146946e
208 changed files with 74579 additions and 24542 deletions
+320
View File
@@ -0,0 +1,320 @@
"""Read-only Adaptive Continuity observation and decision trace for A8a.
The observer records the continuation contract that Production already chose.
It never changes context depth, transport, masks, tensors, conditioning, MODEL,
Seed, SIGMAS, physical grouping, or execution policy.
"""
from __future__ import annotations
import hashlib
import json
import math
from typing import Any
ADAPTIVE_CONTINUITY_OBSERVER_VERSION = 1
EXECUTION_APPLIED = False
INITIAL_TRANSPORT = "initial"
REFERENCE_CONTEXT_V1 = "reference_context_v1"
MASKED_VIDEO_PREFIX_V1 = "masked_video_prefix_v1"
MASKED_AV_PREFIX_22_V1 = "masked_av_prefix_22_v1"
MASKED_AV_PREFIX_39_V1 = "masked_av_prefix_39_v1"
_KNOWN_TRANSPORTS = frozenset(
(
INITIAL_TRANSPORT,
REFERENCE_CONTEXT_V1,
MASKED_VIDEO_PREFIX_V1,
MASKED_AV_PREFIX_22_V1,
MASKED_AV_PREFIX_39_V1,
)
)
_VALID_CONTEXT_FRAMES = frozenset((0, 5, 22, 39))
_PLANNER_CONTRACT = {
"planner_version": ADAPTIVE_CONTINUITY_OBSERVER_VERSION,
"mode": "read_only_observer",
"execution_applied": EXECUTION_APPLIED,
"confidence_scope": "observation_completeness_not_mitigation_efficacy",
"issue_13_mitigation_claim": False,
"mutations": [],
"observed_fields": [
"motion_score",
"current_context_frames",
"resolved_transport",
"terminal_atomic",
"boundary_index",
"boundary_count",
],
}
def _canonical_hash(value: Any) -> str:
payload = json.dumps(
value,
sort_keys=True,
separators=(",", ":"),
ensure_ascii=True,
).encode("utf-8")
return hashlib.sha256(payload).hexdigest()
ADAPTIVE_CONTINUITY_PLANNER_HASH = _canonical_hash(_PLANNER_CONTRACT)
class AdaptiveContinuityObservationError(ValueError):
"""One diagnostic observation is malformed or internally inconsistent."""
def _recommendation(
*,
current_context_frames: int,
resolved_transport: str,
terminal_atomic: bool,
) -> str:
if int(current_context_frames) == 0:
return "no_continuation_action_initial_group"
if bool(terminal_atomic):
return "keep_fixed_terminal_merge_contract"
if str(resolved_transport) == REFERENCE_CONTEXT_V1:
return "keep_current_reference_context_contract"
return "keep_current_masked_prefix_contract"
def make_adaptive_continuity_decision(
*,
physical_group: int,
logical_chunks: tuple[int, ...],
observed_motion_score: float,
current_context_frames: int,
resolved_transport: str,
terminal_atomic: bool,
boundary_index: int,
boundary_count: int,
reason: str,
fallback_reason: str | None = None,
reused: bool = False,
) -> dict[str, Any]:
"""Build one immutable, JSON-safe observation without retaining tensors."""
group = int(physical_group)
logical = tuple(int(value) for value in logical_chunks)
context = int(current_context_frames)
boundary = int(boundary_index)
boundaries = int(boundary_count)
transport = str(resolved_transport)
motion = float(observed_motion_score)
reason_text = str(reason).strip()
if group < 1 or not logical or any(value < 1 for value in logical):
raise AdaptiveContinuityObservationError(
"physical group and logical chunks must be positive"
)
if tuple(sorted(set(logical))) != logical:
raise AdaptiveContinuityObservationError(
"logical chunks must be ordered and unique"
)
if context not in _VALID_CONTEXT_FRAMES:
raise AdaptiveContinuityObservationError(
f"unsupported observed context frame count: {context}"
)
if transport not in _KNOWN_TRANSPORTS:
raise AdaptiveContinuityObservationError(
f"unknown resolved continuation transport: {transport!r}"
)
if context == 0 and transport != INITIAL_TRANSPORT:
raise AdaptiveContinuityObservationError(
"zero-context observations must use the initial transport marker"
)
if context > 0 and transport == INITIAL_TRANSPORT:
raise AdaptiveContinuityObservationError(
"continuation observations require a resolved transport"
)
if boundary < 0 or boundaries < 0 or boundary > boundaries:
raise AdaptiveContinuityObservationError(
"boundary index/count are inconsistent"
)
if not math.isfinite(motion) or motion < 0.0:
raise AdaptiveContinuityObservationError(
"observed motion score must be finite and non-negative"
)
confidence = 1.0 if reason_text else 0.5
payload: dict[str, Any] = {
"planner_version": ADAPTIVE_CONTINUITY_OBSERVER_VERSION,
"planner_hash": ADAPTIVE_CONTINUITY_PLANNER_HASH,
"physical_group": group,
"logical_chunks": list(logical),
"observed_motion_score": motion,
"current_context_frames": context,
"resolved_transport": transport,
"terminal_atomic": bool(terminal_atomic),
"boundary_index": boundary,
"boundary_count": boundaries,
"recommendation": _recommendation(
current_context_frames=context,
resolved_transport=transport,
terminal_atomic=bool(terminal_atomic),
),
"confidence": confidence,
"confidence_scope": "observation completeness only; not mitigation efficacy",
"reason": reason_text or "selection reason unavailable",
"fallback_reason": (
str(fallback_reason).strip() if fallback_reason is not None else None
),
"reused": bool(reused),
"execution_applied": EXECUTION_APPLIED,
"issue_13_mitigation_claim": False,
}
payload["decision_hash"] = _canonical_hash(payload)
return payload
class AdaptiveContinuityObserver:
"""Collect fail-soft A8a observations in deterministic physical-group order."""
def __init__(self) -> None:
self._records: list[dict[str, Any]] = []
self._advisories: list[str] = []
@property
def records(self) -> tuple[dict[str, Any], ...]:
return tuple(dict(record) for record in self._records)
def observe(self, **kwargs: Any) -> dict[str, Any]:
record = make_adaptive_continuity_decision(**kwargs)
self._records.append(record)
return record
def note_observation_failure(self, exc: Exception) -> None:
self._advisories.append(f"{type(exc).__name__}: {exc}")
def replay_prefix(
self,
*,
entries: list[dict[str, Any]],
total_chunks: int,
terminal_merge_enabled: bool,
resolved_transport: str,
) -> None:
"""Reconstruct trace-only records from accepted CPU chunk metadata."""
chunk_count = int(total_chunks)
completed = len(entries)
if chunk_count < 1 or completed > chunk_count:
raise AdaptiveContinuityObservationError(
"replayed prefix length is outside the configured sequence"
)
boundary_count = max(0, chunk_count - 1)
normal_count = completed
terminal_complete = False
pair_start = max(0, chunk_count - 2)
if bool(terminal_merge_enabled):
if pair_start < completed < chunk_count:
raise AdaptiveContinuityObservationError(
"terminal merged prefix contains only one logical half"
)
terminal_complete = completed == chunk_count
normal_count = pair_start if terminal_complete else completed
for index in range(normal_count):
entry = entries[index]
context = int(entry.get("context_frames", 0))
self.observe(
physical_group=index + 1,
logical_chunks=(index + 1,),
observed_motion_score=float(entry.get("motion_score", 0.0)),
current_context_frames=context,
resolved_transport=(
INITIAL_TRANSPORT if context == 0 else str(resolved_transport)
),
terminal_atomic=False,
boundary_index=index,
boundary_count=boundary_count,
reason="replayed from accepted chunk metadata",
fallback_reason=None,
reused=True,
)
if terminal_complete:
entry = entries[pair_start]
context = int(entry.get("context_frames", 0))
self.observe(
physical_group=pair_start + 1,
logical_chunks=(pair_start + 1, chunk_count),
observed_motion_score=float(entry.get("motion_score", 0.0)),
current_context_frames=context,
resolved_transport=(
INITIAL_TRANSPORT if context == 0 else str(resolved_transport)
),
terminal_atomic=True,
boundary_index=pair_start,
boundary_count=boundary_count,
reason="replayed from accepted Terminal Merge metadata",
fallback_reason=None,
reused=True,
)
def report_lines(self) -> list[str]:
lines = [
"Adaptive Continuity observer [A8a v1]: "
f"planner_hash={ADAPTIVE_CONTINUITY_PLANNER_HASH}, "
f"observed_groups={len(self._records)}, "
"execution_applied=false; recommendation trace only, "
"Issue #13 mitigation claim=none, Production continuity unchanged."
]
for record in self._records:
lines.append(
"Adaptive Continuity decision [A8a v1]: "
f"physical_group={record['physical_group']}, "
f"logical_chunks={record['logical_chunks']}, "
f"boundary={record['boundary_index']}/{record['boundary_count']}, "
f"motion={record['observed_motion_score']:.6f}, "
f"context={record['current_context_frames']}, "
f"transport={record['resolved_transport']}, "
f"terminal_atomic={str(record['terminal_atomic']).lower()}, "
f"reused={str(record['reused']).lower()}, "
f"recommendation={record['recommendation']}, "
f"confidence={record['confidence']:.2f}, "
f"reason={record['reason']}, "
f"fallback_reason={record['fallback_reason'] or 'none'}, "
f"decision_hash={record['decision_hash']}, "
"execution_applied=false."
)
lines.extend(
f"Adaptive Continuity advisory [A8a v1]: {item}; execution_applied=false."
for item in self._advisories
)
return lines
def adaptive_observer_event_fail_soft(
observer: Any,
method: str,
**kwargs: Any,
) -> Any:
"""Invoke one observer event without allowing diagnostics to stop Sampling."""
if observer is None:
return None
try:
return getattr(observer, str(method))(**kwargs)
except Exception as exc:
try:
observer.note_observation_failure(exc)
except Exception:
pass
return None
__all__ = [
"ADAPTIVE_CONTINUITY_OBSERVER_VERSION",
"ADAPTIVE_CONTINUITY_PLANNER_HASH",
"AdaptiveContinuityObservationError",
"AdaptiveContinuityObserver",
"EXECUTION_APPLIED",
"INITIAL_TRANSPORT",
"adaptive_observer_event_fail_soft",
"make_adaptive_continuity_decision",
]
+431 -431
View File
@@ -1,431 +1,431 @@
"""Decoded chunk assembly for latent-first H3 Continuum V3."""
from __future__ import annotations
import math
import time
from typing import Any
import torch
from ..media import validate_audio
from ..v2.decoder import _slice_audio_for_timeline, enforce_total_frames
from ..constants import (
DIAGNOSTICS_FULL,
DIAGNOSTICS_OFF,
DIAGNOSTICS_OPTIONS,
normalize_diagnostics_mode,
)
from ..v2.seam_guard import correct_audio_seam
from .plan import FPS, validate_assembly_plan
AUDIO_SEAM_OFF = "Off"
AUDIO_SEAM_AUTO = "Auto"
AUDIO_SEAM_OPTIONS = (AUDIO_SEAM_OFF, AUDIO_SEAM_AUTO)
VIDEO_SEAM_OFF = "Off"
VIDEO_SEAM_ANALYZE = "Analyze Only"
VIDEO_SEAM_AUTO = "Auto"
VIDEO_SEAM_AUTO_2 = "Auto 2"
VIDEO_SEAM_ANALYSIS_OPTIONS = (
VIDEO_SEAM_AUTO,
VIDEO_SEAM_AUTO_2,
VIDEO_SEAM_ANALYZE,
VIDEO_SEAM_OFF,
)
def _singleton(value: Any, name: str) -> Any:
while isinstance(value, list):
if len(value) != 1:
raise ValueError(f"{name} must contain exactly one value")
value = value[0]
return value
def _chunk_list(value: Any) -> list[Any]:
if isinstance(value, list):
if len(value) == 1 and isinstance(value[0], list):
return list(value[0])
return list(value)
return [value]
def _format_elapsed(seconds: float) -> str:
total = max(0.0, float(seconds))
hours, remainder = divmod(total, 3600.0)
minutes, seconds = divmod(remainder, 60.0)
return f"{int(hours):02d}:{int(minutes):02d}:{seconds:05.2f}"
def assemble_decoded_chunks(
*,
images: list[Any],
audio: list[Any],
assembly_plan: dict[str, Any],
exact_total_duration: bool,
audio_seam: str,
diagnostics: str,
):
plan = validate_assembly_plan(assembly_plan)
diagnostics_mode = normalize_diagnostics_mode(diagnostics)
if audio_seam not in AUDIO_SEAM_OPTIONS:
raise ValueError(f"unknown Audio Seam mode: {audio_seam!r}")
chunk_plans = list(
plan["decode_groups"] if "decode_groups" in plan else plan["chunks"]
)
if len(images) != len(chunk_plans) or len(audio) != len(chunk_plans):
raise ValueError(
"decoded chunk count does not match the V3 assembly plan: "
f"images={len(images)}, audio={len(audio)}, plan={len(chunk_plans)}"
)
total_retained_frames = sum(int(item["net_frames"]) for item in chunk_plans)
image_buffer = None
audio_buffer = None
audio_rate = None
frame_cursor = 0
reports = [
"H3 Continuum Assemble V3",
f"Audio Seam: {audio_seam}. Video seam correction is disabled.",
]
for index, (raw_images, raw_audio, chunk) in enumerate(
zip(images, audio, chunk_plans), start=1
):
if not torch.is_tensor(raw_images) or raw_images.ndim != 4:
raise ValueError(f"decoded image chunk {index} must be [frames,H,W,C]")
raw_images = raw_images.detach().to("cpu")
total_frames = int(chunk["total_frames"])
trim_frames = int(chunk["trim_frames"])
net_frames = int(chunk["net_frames"])
if int(raw_images.shape[0]) < total_frames:
raise ValueError(
f"decoded image chunk {index} has {raw_images.shape[0]} frames; "
f"expected at least {total_frames}"
)
segment_images = raw_images[:total_frames][trim_frames:].contiguous()
if int(segment_images.shape[0]) != net_frames:
raise ValueError(
f"decoded image chunk {index} retained {segment_images.shape[0]} frames; "
f"plan expects {net_frames}"
)
waveform, sample_rate = validate_audio(raw_audio)
waveform = waveform.detach().to("cpu")
sample_rate = int(sample_rate)
raw_audio_cpu = {"waveform": waveform, "sample_rate": sample_rate}
if audio_rate is None:
audio_rate = sample_rate
elif sample_rate != audio_rate:
raise ValueError(
f"audio sample rate changed between chunks: {audio_rate} -> {sample_rate}"
)
frame_stop = frame_cursor + net_frames
segment_waveform = _slice_audio_for_timeline(
raw_audio_cpu,
trim_frames=trim_frames,
frame_start=frame_cursor,
frame_stop=frame_stop,
)
if image_buffer is None:
image_buffer = torch.empty(
(total_retained_frames, *segment_images.shape[1:]),
dtype=segment_images.dtype,
device="cpu",
)
elif tuple(segment_images.shape[1:]) != tuple(image_buffer.shape[1:]):
raise ValueError(f"decoded image geometry changed at chunk {index}")
image_buffer[frame_cursor:frame_stop].copy_(segment_images)
if audio_buffer is None:
audio_buffer = torch.empty(
(
*waveform.shape[:-1],
int(round(total_retained_frames / FPS * sample_rate)),
),
dtype=waveform.dtype,
device="cpu",
)
elif tuple(segment_waveform.shape[:-1]) != tuple(audio_buffer.shape[:-1]):
raise ValueError(
"decoded audio batch/channel structure changed between chunks"
)
sample_start = int(round(frame_cursor / FPS * sample_rate))
sample_stop = int(round(frame_stop / FPS * sample_rate))
seam_report = None
if index > 1 and audio_seam == AUDIO_SEAM_AUTO:
try:
cut_sample = int(round(trim_frames / FPS * sample_rate))
patch, metrics, fade_samples, level_gain, dc_bias = correct_audio_seam(
audio_buffer[..., :sample_start],
waveform,
sample_rate=sample_rate,
cut_sample=cut_sample,
)
if patch is not None and int(patch.shape[-1]) > 0:
patch_start = sample_start - int(patch.shape[-1])
if patch_start < 0:
raise ValueError("audio seam patch starts before the output")
audio_buffer[..., patch_start:sample_start].copy_(patch)
seam_report = (
f"audio seam {index-1}->{index}: "
f"corr={metrics.correlation_before:.4f}->{metrics.correlation_after:.4f}, "
f"jump={metrics.boundary_jump_before:.6f}->{metrics.boundary_jump_after:.6f}, "
f"fade={fade_samples} samples"
)
if diagnostics_mode == DIAGNOSTICS_FULL:
seam_report += (
f", offset={metrics.offset_samples:+d}, "
f"gain={level_gain:.4f}, dc={dc_bias:+.6f}"
)
except Exception as exc:
seam_report = (
f"audio seam {index-1}->{index}: fallback to native boundary "
f"({type(exc).__name__}: {exc})"
)
audio_buffer[..., sample_start:sample_stop].copy_(segment_waveform)
if diagnostics_mode != DIAGNOSTICS_OFF:
reports.append(
f"assembled decoded chunk {index}: {net_frames} retained frames, "
f"cumulative {frame_stop}/{total_retained_frames}"
)
if seam_report:
reports.append(seam_report)
frame_cursor = frame_stop
if image_buffer is None or audio_buffer is None or audio_rate is None:
raise RuntimeError("V3 assembler failed to allocate output buffers")
if frame_cursor != total_retained_frames:
raise RuntimeError(
f"V3 assembly cursor mismatch: {frame_cursor} != {total_retained_frames}"
)
result_audio = {
"waveform": audio_buffer.contiguous(),
"sample_rate": audio_rate,
}
duration_report = ""
if exact_total_duration:
image_buffer, result_audio, duration_report = enforce_total_frames(
image_buffer.contiguous(),
result_audio,
target_frames=int(plan["target_frames"]),
preserve_final_frame=bool(plan.get("preserve_final_frame")),
)
reports.append(
f"Assembled {len(chunk_plans)} externally decoded chunks into "
f"{image_buffer.shape[0]} frames with cumulative sample-boundary alignment."
)
if duration_report:
reports.append(duration_report)
runtime_started_at = plan.get("_runtime_started_at")
if isinstance(runtime_started_at, (int, float)):
elapsed = time.perf_counter() - float(runtime_started_at)
if math.isfinite(elapsed) and elapsed >= 0.0:
reports.append(f"Total workflow elapsed: {_format_elapsed(elapsed)}")
return image_buffer.contiguous(), result_audio, "\n".join(reports)
class H3ContinuumAssembleV3:
DESCRIPTION = (
"Assemble full AV chunks decoded by ComfyUI Core. Trims decoded context, "
"aligns audio on cumulative frame boundaries, and optionally applies Audio Seam Auto."
)
SEARCH_ALIASES = ["H3 latent assemble", "H3 external VAE decode"]
@classmethod
def INPUT_TYPES(cls):
return {
"required": {
"images": ("IMAGE",),
"audio": ("AUDIO",),
"assembly_plan": ("H3_CONTINUUM_ASSEMBLY_PLAN",),
"exact_total_duration": (
"BOOLEAN",
{
"default": True,
"tooltip": "Adjust the final output to the exact requested total duration.",
},
),
"audio_seam": (
AUDIO_SEAM_OPTIONS,
{
"default": AUDIO_SEAM_AUTO,
"display_name": "Audio Seam",
"tooltip": (
"Auto corrects only decoded audio boundaries; "
"video frames are never altered."
),
},
),
"diagnostics": (
DIAGNOSTICS_OPTIONS,
{
"default": DIAGNOSTICS_OPTIONS[0],
"display_name": "Report Detail",
},
),
}
}
INPUT_IS_LIST = True
RETURN_TYPES = ("IMAGE", "AUDIO", "STRING")
RETURN_NAMES = ("images", "audio", "report")
FUNCTION = "assemble"
CATEGORY = "MiniMax H3/Continuum"
def assemble(
self,
images,
audio,
assembly_plan,
exact_total_duration,
audio_seam,
diagnostics,
):
return assemble_decoded_chunks(
images=_chunk_list(images),
audio=_chunk_list(audio),
assembly_plan=_singleton(assembly_plan, "assembly_plan"),
exact_total_duration=bool(
_singleton(exact_total_duration, "exact_total_duration")
),
audio_seam=str(_singleton(audio_seam, "audio_seam")),
diagnostics=str(_singleton(diagnostics, "diagnostics")),
)
# V3.0.1 hardening integration: preflight before allocation; Detailed Report only.
from ..hardening import assemble_with_hardening as _assemble_with_hardening
_assemble_decoded_chunks_v300 = assemble_decoded_chunks
def assemble_decoded_chunks(*args, **kwargs):
return _assemble_with_hardening(_assemble_decoded_chunks_v300, args, kwargs)
class H3ContinuumAssembleSeamExperimental(H3ContinuumAssembleV3):
DEPRECATED = False
CATEGORY = "MiniMax H3/Continuum"
DESCRIPTION = (
"Analyze decoded chunk boundaries and apply guarded video seam correction."
)
SEARCH_ALIASES = ["H3 seam analysis", "H3 boundary flicker analysis"]
@classmethod
def INPUT_TYPES(cls):
schema = super().INPUT_TYPES()
required = dict(schema["required"])
diagnostics = required.pop("diagnostics")
required["video_seam"] = (
VIDEO_SEAM_ANALYSIS_OPTIONS,
{
"default": VIDEO_SEAM_AUTO,
"display_name": "Video Seam",
"tooltip": (
"Analyze Only reports decoded video boundaries without changing them. "
"Auto applies the validated transient and micro-flash correction. "
"Auto 2 experimentally adds qualified exposure-ramp smoothing."
),
},
)
required["diagnostics"] = diagnostics
schema["required"] = required
return schema
def assemble(
self,
images,
audio,
assembly_plan,
exact_total_duration,
audio_seam,
video_seam,
diagnostics,
):
mode = str(_singleton(video_seam, "video_seam"))
if mode not in VIDEO_SEAM_ANALYSIS_OPTIONS:
raise ValueError(f"unknown Video Seam mode: {mode!r}")
if mode == VIDEO_SEAM_OFF:
return super().assemble(
images,
audio,
assembly_plan,
exact_total_duration,
audio_seam,
diagnostics,
)
image_chunks = _chunk_list(images)
plan = _singleton(assembly_plan, "assembly_plan")
analyses = []
analysis_error = None
actions = {}
try:
from .video_seam import (
analyze_decoded_boundaries,
correct_decoded_boundaries,
format_video_boundary_analysis,
)
analyses = analyze_decoded_boundaries(
images=image_chunks,
assembly_plan=plan,
)
if mode in (VIDEO_SEAM_AUTO, VIDEO_SEAM_AUTO_2):
image_chunks, actions = correct_decoded_boundaries(
images=image_chunks,
assembly_plan=plan,
analyses=analyses,
enable_exposure_ramp=mode == VIDEO_SEAM_AUTO_2,
)
except Exception as exc:
analysis_error = exc
result_images, result_audio, report = assemble_decoded_chunks(
images=image_chunks,
audio=_chunk_list(audio),
assembly_plan=plan,
exact_total_duration=bool(
_singleton(exact_total_duration, "exact_total_duration")
),
audio_seam=str(_singleton(audio_seam, "audio_seam")),
diagnostics=str(_singleton(diagnostics, "diagnostics")),
)
if mode == VIDEO_SEAM_ANALYZE:
status = "Video Seam: Analyze Only; decoded frames and audio are unchanged."
elif mode == VIDEO_SEAM_AUTO:
status = (
"Video Seam: Auto; guarded transient and micro-flash correction enabled."
)
else:
status = (
"Video Seam: Auto 2 (Experimental); guarded transient, micro-flash, "
"and exposure-ramp correction enabled."
)
report = report.replace("Video seam correction is disabled.", status, 1)
if analysis_error is None:
lines = [
format_video_boundary_analysis(
item,
action=(
"analysis only"
if mode == VIDEO_SEAM_ANALYZE
else actions.get(item.boundary_index, "kept native boundary")
),
)
for item in analyses
]
if not lines:
lines = [f"Video Seam {mode}: no decoded chunk boundary to analyze."]
else:
lines = [
f"Video Seam {mode}: native output preserved; analysis unavailable "
f"({type(analysis_error).__name__}: {analysis_error})"
]
return result_images, result_audio, report.rstrip() + "\n" + "\n".join(lines)
"""Decoded chunk assembly for latent-first H3 Continuum V3."""
from __future__ import annotations
import math
import time
from typing import Any
import torch
from ..media import validate_audio
from ..v2.decoder import _slice_audio_for_timeline, enforce_total_frames
from ..constants import (
DIAGNOSTICS_FULL,
DIAGNOSTICS_OFF,
DIAGNOSTICS_OPTIONS,
normalize_diagnostics_mode,
)
from ..v2.seam_guard import correct_audio_seam
from .plan import FPS, validate_assembly_plan
AUDIO_SEAM_OFF = "Off"
AUDIO_SEAM_AUTO = "Auto"
AUDIO_SEAM_OPTIONS = (AUDIO_SEAM_OFF, AUDIO_SEAM_AUTO)
VIDEO_SEAM_OFF = "Off"
VIDEO_SEAM_ANALYZE = "Analyze Only"
VIDEO_SEAM_AUTO = "Auto"
VIDEO_SEAM_AUTO_2 = "Auto 2"
VIDEO_SEAM_ANALYSIS_OPTIONS = (
VIDEO_SEAM_AUTO,
VIDEO_SEAM_AUTO_2,
VIDEO_SEAM_ANALYZE,
VIDEO_SEAM_OFF,
)
def _singleton(value: Any, name: str) -> Any:
while isinstance(value, list):
if len(value) != 1:
raise ValueError(f"{name} must contain exactly one value")
value = value[0]
return value
def _chunk_list(value: Any) -> list[Any]:
if isinstance(value, list):
if len(value) == 1 and isinstance(value[0], list):
return list(value[0])
return list(value)
return [value]
def _format_elapsed(seconds: float) -> str:
total = max(0.0, float(seconds))
hours, remainder = divmod(total, 3600.0)
minutes, seconds = divmod(remainder, 60.0)
return f"{int(hours):02d}:{int(minutes):02d}:{seconds:05.2f}"
def assemble_decoded_chunks(
*,
images: list[Any],
audio: list[Any],
assembly_plan: dict[str, Any],
exact_total_duration: bool,
audio_seam: str,
diagnostics: str,
):
plan = validate_assembly_plan(assembly_plan)
diagnostics_mode = normalize_diagnostics_mode(diagnostics)
if audio_seam not in AUDIO_SEAM_OPTIONS:
raise ValueError(f"unknown Audio Seam mode: {audio_seam!r}")
chunk_plans = list(
plan["decode_groups"] if "decode_groups" in plan else plan["chunks"]
)
if len(images) != len(chunk_plans) or len(audio) != len(chunk_plans):
raise ValueError(
"decoded chunk count does not match the V3 assembly plan: "
f"images={len(images)}, audio={len(audio)}, plan={len(chunk_plans)}"
)
total_retained_frames = sum(int(item["net_frames"]) for item in chunk_plans)
image_buffer = None
audio_buffer = None
audio_rate = None
frame_cursor = 0
reports = [
"H3 Continuum Assemble V3",
f"Audio Seam: {audio_seam}. Video seam correction is disabled.",
]
for index, (raw_images, raw_audio, chunk) in enumerate(
zip(images, audio, chunk_plans), start=1
):
if not torch.is_tensor(raw_images) or raw_images.ndim != 4:
raise ValueError(f"decoded image chunk {index} must be [frames,H,W,C]")
raw_images = raw_images.detach().to("cpu")
total_frames = int(chunk["total_frames"])
trim_frames = int(chunk["trim_frames"])
net_frames = int(chunk["net_frames"])
if int(raw_images.shape[0]) < total_frames:
raise ValueError(
f"decoded image chunk {index} has {raw_images.shape[0]} frames; "
f"expected at least {total_frames}"
)
segment_images = raw_images[:total_frames][trim_frames:].contiguous()
if int(segment_images.shape[0]) != net_frames:
raise ValueError(
f"decoded image chunk {index} retained {segment_images.shape[0]} frames; "
f"plan expects {net_frames}"
)
waveform, sample_rate = validate_audio(raw_audio)
waveform = waveform.detach().to("cpu")
sample_rate = int(sample_rate)
raw_audio_cpu = {"waveform": waveform, "sample_rate": sample_rate}
if audio_rate is None:
audio_rate = sample_rate
elif sample_rate != audio_rate:
raise ValueError(
f"audio sample rate changed between chunks: {audio_rate} -> {sample_rate}"
)
frame_stop = frame_cursor + net_frames
segment_waveform = _slice_audio_for_timeline(
raw_audio_cpu,
trim_frames=trim_frames,
frame_start=frame_cursor,
frame_stop=frame_stop,
)
if image_buffer is None:
image_buffer = torch.empty(
(total_retained_frames, *segment_images.shape[1:]),
dtype=segment_images.dtype,
device="cpu",
)
elif tuple(segment_images.shape[1:]) != tuple(image_buffer.shape[1:]):
raise ValueError(f"decoded image geometry changed at chunk {index}")
image_buffer[frame_cursor:frame_stop].copy_(segment_images)
if audio_buffer is None:
audio_buffer = torch.empty(
(
*waveform.shape[:-1],
int(round(total_retained_frames / FPS * sample_rate)),
),
dtype=waveform.dtype,
device="cpu",
)
elif tuple(segment_waveform.shape[:-1]) != tuple(audio_buffer.shape[:-1]):
raise ValueError(
"decoded audio batch/channel structure changed between chunks"
)
sample_start = int(round(frame_cursor / FPS * sample_rate))
sample_stop = int(round(frame_stop / FPS * sample_rate))
seam_report = None
if index > 1 and audio_seam == AUDIO_SEAM_AUTO:
try:
cut_sample = int(round(trim_frames / FPS * sample_rate))
patch, metrics, fade_samples, level_gain, dc_bias = correct_audio_seam(
audio_buffer[..., :sample_start],
waveform,
sample_rate=sample_rate,
cut_sample=cut_sample,
)
if patch is not None and int(patch.shape[-1]) > 0:
patch_start = sample_start - int(patch.shape[-1])
if patch_start < 0:
raise ValueError("audio seam patch starts before the output")
audio_buffer[..., patch_start:sample_start].copy_(patch)
seam_report = (
f"audio seam {index-1}->{index}: "
f"corr={metrics.correlation_before:.4f}->{metrics.correlation_after:.4f}, "
f"jump={metrics.boundary_jump_before:.6f}->{metrics.boundary_jump_after:.6f}, "
f"fade={fade_samples} samples"
)
if diagnostics_mode == DIAGNOSTICS_FULL:
seam_report += (
f", offset={metrics.offset_samples:+d}, "
f"gain={level_gain:.4f}, dc={dc_bias:+.6f}"
)
except Exception as exc:
seam_report = (
f"audio seam {index-1}->{index}: fallback to native boundary "
f"({type(exc).__name__}: {exc})"
)
audio_buffer[..., sample_start:sample_stop].copy_(segment_waveform)
if diagnostics_mode != DIAGNOSTICS_OFF:
reports.append(
f"assembled decoded chunk {index}: {net_frames} retained frames, "
f"cumulative {frame_stop}/{total_retained_frames}"
)
if seam_report:
reports.append(seam_report)
frame_cursor = frame_stop
if image_buffer is None or audio_buffer is None or audio_rate is None:
raise RuntimeError("V3 assembler failed to allocate output buffers")
if frame_cursor != total_retained_frames:
raise RuntimeError(
f"V3 assembly cursor mismatch: {frame_cursor} != {total_retained_frames}"
)
result_audio = {
"waveform": audio_buffer.contiguous(),
"sample_rate": audio_rate,
}
duration_report = ""
if exact_total_duration:
image_buffer, result_audio, duration_report = enforce_total_frames(
image_buffer.contiguous(),
result_audio,
target_frames=int(plan["target_frames"]),
preserve_final_frame=bool(plan.get("preserve_final_frame")),
)
reports.append(
f"Assembled {len(chunk_plans)} externally decoded chunks into "
f"{image_buffer.shape[0]} frames with cumulative sample-boundary alignment."
)
if duration_report:
reports.append(duration_report)
runtime_started_at = plan.get("_runtime_started_at")
if isinstance(runtime_started_at, (int, float)):
elapsed = time.perf_counter() - float(runtime_started_at)
if math.isfinite(elapsed) and elapsed >= 0.0:
reports.append(f"Total workflow elapsed: {_format_elapsed(elapsed)}")
return image_buffer.contiguous(), result_audio, "\n".join(reports)
class H3ContinuumAssembleV3:
DESCRIPTION = (
"Assemble full AV chunks decoded by ComfyUI Core. Trims decoded context, "
"aligns audio on cumulative frame boundaries, and optionally applies Audio Seam Auto."
)
SEARCH_ALIASES = ["H3 latent assemble", "H3 external VAE decode"]
@classmethod
def INPUT_TYPES(cls):
return {
"required": {
"images": ("IMAGE",),
"audio": ("AUDIO",),
"assembly_plan": ("H3_CONTINUUM_ASSEMBLY_PLAN",),
"exact_total_duration": (
"BOOLEAN",
{
"default": True,
"tooltip": "Adjust the final output to the exact requested total duration.",
},
),
"audio_seam": (
AUDIO_SEAM_OPTIONS,
{
"default": AUDIO_SEAM_AUTO,
"display_name": "Audio Seam",
"tooltip": (
"Auto corrects only decoded audio boundaries; "
"video frames are never altered."
),
},
),
"diagnostics": (
DIAGNOSTICS_OPTIONS,
{
"default": DIAGNOSTICS_OPTIONS[0],
"display_name": "Report Detail",
},
),
}
}
INPUT_IS_LIST = True
RETURN_TYPES = ("IMAGE", "AUDIO", "STRING")
RETURN_NAMES = ("images", "audio", "report")
FUNCTION = "assemble"
CATEGORY = "MiniMax H3/Continuum"
def assemble(
self,
images,
audio,
assembly_plan,
exact_total_duration,
audio_seam,
diagnostics,
):
return assemble_decoded_chunks(
images=_chunk_list(images),
audio=_chunk_list(audio),
assembly_plan=_singleton(assembly_plan, "assembly_plan"),
exact_total_duration=bool(
_singleton(exact_total_duration, "exact_total_duration")
),
audio_seam=str(_singleton(audio_seam, "audio_seam")),
diagnostics=str(_singleton(diagnostics, "diagnostics")),
)
# V3.0.1 hardening integration: preflight before allocation; Detailed Report only.
from ..hardening import assemble_with_hardening as _assemble_with_hardening
_assemble_decoded_chunks_v300 = assemble_decoded_chunks
def assemble_decoded_chunks(*args, **kwargs):
return _assemble_with_hardening(_assemble_decoded_chunks_v300, args, kwargs)
class H3ContinuumAssembleSeamExperimental(H3ContinuumAssembleV3):
DEPRECATED = False
CATEGORY = "MiniMax H3/Continuum"
DESCRIPTION = (
"Analyze decoded chunk boundaries and apply guarded video seam correction."
)
SEARCH_ALIASES = ["H3 seam analysis", "H3 boundary flicker analysis"]
@classmethod
def INPUT_TYPES(cls):
schema = super().INPUT_TYPES()
required = dict(schema["required"])
diagnostics = required.pop("diagnostics")
required["video_seam"] = (
VIDEO_SEAM_ANALYSIS_OPTIONS,
{
"default": VIDEO_SEAM_AUTO,
"display_name": "Video Seam",
"tooltip": (
"Analyze Only reports decoded video boundaries without changing them. "
"Auto applies the validated transient and micro-flash correction. "
"Auto 2 experimentally adds qualified exposure-ramp smoothing."
),
},
)
required["diagnostics"] = diagnostics
schema["required"] = required
return schema
def assemble(
self,
images,
audio,
assembly_plan,
exact_total_duration,
audio_seam,
video_seam,
diagnostics,
):
mode = str(_singleton(video_seam, "video_seam"))
if mode not in VIDEO_SEAM_ANALYSIS_OPTIONS:
raise ValueError(f"unknown Video Seam mode: {mode!r}")
if mode == VIDEO_SEAM_OFF:
return super().assemble(
images,
audio,
assembly_plan,
exact_total_duration,
audio_seam,
diagnostics,
)
image_chunks = _chunk_list(images)
plan = _singleton(assembly_plan, "assembly_plan")
analyses = []
analysis_error = None
actions = {}
try:
from .video_seam import (
analyze_decoded_boundaries,
correct_decoded_boundaries,
format_video_boundary_analysis,
)
analyses = analyze_decoded_boundaries(
images=image_chunks,
assembly_plan=plan,
)
if mode in (VIDEO_SEAM_AUTO, VIDEO_SEAM_AUTO_2):
image_chunks, actions = correct_decoded_boundaries(
images=image_chunks,
assembly_plan=plan,
analyses=analyses,
enable_exposure_ramp=mode == VIDEO_SEAM_AUTO_2,
)
except Exception as exc:
analysis_error = exc
result_images, result_audio, report = assemble_decoded_chunks(
images=image_chunks,
audio=_chunk_list(audio),
assembly_plan=plan,
exact_total_duration=bool(
_singleton(exact_total_duration, "exact_total_duration")
),
audio_seam=str(_singleton(audio_seam, "audio_seam")),
diagnostics=str(_singleton(diagnostics, "diagnostics")),
)
if mode == VIDEO_SEAM_ANALYZE:
status = "Video Seam: Analyze Only; decoded frames and audio are unchanged."
elif mode == VIDEO_SEAM_AUTO:
status = (
"Video Seam: Auto; guarded transient and micro-flash correction enabled."
)
else:
status = (
"Video Seam: Auto 2 (Experimental); guarded transient, micro-flash, "
"and exposure-ramp correction enabled."
)
report = report.replace("Video seam correction is disabled.", status, 1)
if analysis_error is None:
lines = [
format_video_boundary_analysis(
item,
action=(
"analysis only"
if mode == VIDEO_SEAM_ANALYZE
else actions.get(item.boundary_index, "kept native boundary")
),
)
for item in analyses
]
if not lines:
lines = [f"Video Seam {mode}: no decoded chunk boundary to analyze."]
else:
lines = [
f"Video Seam {mode}: native output preserved; analysis unavailable "
f"({type(analysis_error).__name__}: {analysis_error})"
]
return result_images, result_audio, report.rstrip() + "\n" + "\n".join(lines)
+861 -398
View File
File diff suppressed because it is too large Load Diff
+66
View File
@@ -0,0 +1,66 @@
"""Generic Easy workflow audio loader backed by ComfyUI Core LoadAudio."""
from __future__ import annotations
from types import SimpleNamespace
try:
from comfy_extras.nodes_audio import LoadAudio as CoreLoadAudio
except (ImportError, AttributeError): # pragma: no cover - standalone unit tests
class CoreLoadAudio:
"""Non-runtime shim; real ComfyUI always supplies Core LoadAudio."""
@classmethod
def define_schema(cls):
return SimpleNamespace(
node_id="LoadAudio",
display_name="Load Audio",
category="audio",
essentials_category="Audio",
description="",
search_aliases=["import audio", "open audio", "audio file"],
is_deprecated=False,
)
@classmethod
def execute(cls, audio):
return audio
load = execute
class H3EasyLoadAudio(CoreLoadAudio):
"""Core LoadAudio with an Easy frontend control for native node bypass."""
@classmethod
def define_schema(cls):
schema = super().define_schema()
schema.node_id = "H3EasyLoadAudio"
schema.display_name = "H3 Continuum Load Audio"
schema.category = "MiniMax H3/Continuum"
schema.description = (
"Loads audio through ComfyUI Core. Enable Audio controls the node's "
"native Bypass mode without changing the AUDIO contract."
)
schema.search_aliases = list(
dict.fromkeys(
[
*getattr(schema, "search_aliases", []),
"H3 Continuum Load Audio",
"H3 Easy Load Audio",
"H3 Easy Audio Loader",
"Load Audio with Bypass",
]
)
)
return schema
NODE_CLASS_MAPPINGS = {
"H3EasyLoadAudio": H3EasyLoadAudio,
}
NODE_DISPLAY_NAME_MAPPINGS = {
"H3EasyLoadAudio": "H3 Continuum Load Audio",
}
+48
View File
@@ -0,0 +1,48 @@
"""Generic Easy workflow image loader backed by ComfyUI Core LoadImage."""
from __future__ import annotations
try:
from nodes import LoadImage as CoreLoadImage
except (ImportError, AttributeError): # pragma: no cover - standalone unit tests
class CoreLoadImage:
"""Non-runtime shim; real ComfyUI always supplies Core LoadImage."""
@classmethod
def INPUT_TYPES(cls):
return {
"required": {
"image": (("",), {"image_upload": True}),
}
}
RETURN_TYPES = ("IMAGE", "MASK")
FUNCTION = "load_image"
class H3EasyLoadImage(CoreLoadImage):
"""Core LoadImage with an Easy frontend control for native node bypass."""
DEPRECATED = False
CATEGORY = "MiniMax H3/Continuum"
DESCRIPTION = (
"Loads an image through ComfyUI Core. Enable Image controls the node's "
"native Bypass mode, so the same node can serve First, Last, or Reference "
"image inputs without changing the IMAGE/MASK contract."
)
SEARCH_ALIASES = [
"H3 Continuum Load Image",
"H3 Easy Load Image",
"H3 Easy Image Loader",
"Load Image with Bypass",
]
NODE_CLASS_MAPPINGS = {
"H3EasyLoadImage": H3EasyLoadImage,
}
NODE_DISPLAY_NAME_MAPPINGS = {
"H3EasyLoadImage": "H3 Continuum Load Image",
}
+482
View File
@@ -0,0 +1,482 @@
"""V3.8 Easy Mode facade and deterministic UI resolvers."""
from __future__ import annotations
from dataclasses import dataclass
import math
from typing import Any
from ..conditioning import conditioning_display_label
from ..constants import (
CONTINUITY_OPTIONS,
DIAGNOSTICS_BASIC,
PROMPT_FORMAT_AUTO,
)
from ..reference import REFERENCE_SIZE_MATCH_OUTPUT
from ..reference_video import REFERENCE_VIDEO_SIZE_EFFICIENT
from .driving_nodes import (
CONTINUATION_BACKEND_STANDARD,
H3ContinuumSamplerV37,
)
from .nodes import CATEGORY as CONTINUUM_CATEGORY, REGENERATE_AUTO
from .resolution import (
H3_ASPECT_AUTO,
H3_ASPECT_LANDSCAPE,
H3_ASPECT_OPTIONS,
H3_ASPECT_PORTRAIT,
H3_ASPECT_SQUARE,
H3_BALANCED_MP,
H3_CANVAS_MULTIPLE,
H3_CUSTOM_MP_DEFAULT,
H3_CUSTOM_MP_MAX,
H3_CUSTOM_MP_MIN,
H3_CUSTOM_MP_STRONG_WARNING,
H3_DRAFT_MP,
H3_MP_PIXELS,
H3_NATIVE_LONG_EDGE_CAP,
H3_NATIVE_SHORT_EDGE,
H3_PRESET_BALANCED,
H3_PRESET_CUSTOM,
H3_PRESET_DRAFT,
H3_PRESET_NATIVE,
H3_PRESET_OPTIONS,
H3ResolutionPlan,
resolve_h3_aspect,
resolve_h3_resolution,
)
EASY_DURATION_DEFAULT = 10
EASY_DURATION_MIN = 4
EASY_DURATION_MAX = 480
EASY_TARGET_CHUNK_SECONDS = 10.0
EASY_MAX_CHUNKS = 16
EASY_SEED_MODE_RANDOMIZE = "Randomize"
EASY_SEED_MODE_FIXED = "Fixed"
EASY_SEED_MODE_OPTIONS = (
EASY_SEED_MODE_RANDOMIZE,
EASY_SEED_MODE_FIXED,
)
EASY_ASPECT_AUTO = H3_ASPECT_AUTO
EASY_ASPECT_LANDSCAPE = H3_ASPECT_LANDSCAPE
EASY_ASPECT_PORTRAIT = H3_ASPECT_PORTRAIT
EASY_ASPECT_SQUARE = H3_ASPECT_SQUARE
EASY_ASPECT_OPTIONS = H3_ASPECT_OPTIONS
EASY_PRESET_DRAFT = H3_PRESET_DRAFT
EASY_PRESET_BALANCED = H3_PRESET_BALANCED
EASY_PRESET_NATIVE = H3_PRESET_NATIVE
EASY_PRESET_CUSTOM = H3_PRESET_CUSTOM
EASY_PRESET_OPTIONS = H3_PRESET_OPTIONS
EASY_DRAFT_MP = H3_DRAFT_MP
EASY_BALANCED_MP = H3_BALANCED_MP
EASY_CUSTOM_MP_DEFAULT = H3_CUSTOM_MP_DEFAULT
EASY_CUSTOM_MP_MIN = H3_CUSTOM_MP_MIN
EASY_CUSTOM_MP_MAX = H3_CUSTOM_MP_MAX
EASY_CUSTOM_MP_STRONG_WARNING = H3_CUSTOM_MP_STRONG_WARNING
EASY_MP_PIXELS = H3_MP_PIXELS
EASY_CANVAS_MULTIPLE = H3_CANVAS_MULTIPLE
EASY_NATIVE_SHORT_EDGE = H3_NATIVE_SHORT_EDGE
EASY_NATIVE_LONG_EDGE_CAP = H3_NATIVE_LONG_EDGE_CAP
EasyResolutionPlan = H3ResolutionPlan
resolve_easy_aspect = resolve_h3_aspect
resolve_easy_resolution = resolve_h3_resolution
EASY_REFERENCES_TYPE = "H3_CONTINUUM_EASY_REFERENCES"
EASY_REFERENCES_SCHEMA_VERSION = 1
@dataclass(frozen=True)
class EasyDurationPlan:
duration_seconds: int
chunks: int
chunk_seconds: float
def make_easy_references(
reference_image_1: Any = None,
reference_image_2: Any = None,
reference_image_3: Any = None,
) -> dict[str, Any]:
"""Pack fixed Easy reference sockets without preprocessing their images."""
return {
"schema_version": EASY_REFERENCES_SCHEMA_VERSION,
"reference_image_1": reference_image_1,
"reference_image_2": reference_image_2,
"reference_image_3": reference_image_3,
}
def resolve_easy_references(references: Any = None) -> tuple[Any, Any, Any]:
"""Expand the private Easy bundle back into the mature V3.7 input contract."""
if references is None:
return None, None, None
if not isinstance(references, dict):
raise TypeError("Easy References must come from H3 Continuum Easy References")
if references.get("schema_version") != EASY_REFERENCES_SCHEMA_VERSION:
raise ValueError("Unsupported H3 Continuum Easy References schema version")
return tuple(
references.get(f"reference_image_{index}") for index in range(1, 4)
)
def resolve_easy_duration(duration_seconds: int) -> EasyDurationPlan:
"""Resolve one total duration around ten-second logical chunks."""
if isinstance(duration_seconds, bool):
raise TypeError("Duration must be an integer number of seconds")
duration = int(duration_seconds)
if duration != duration_seconds:
raise ValueError("Duration must be an integer number of seconds")
if not EASY_DURATION_MIN <= duration <= EASY_DURATION_MAX:
raise ValueError(
f"Duration must be between {EASY_DURATION_MIN} and {EASY_DURATION_MAX} seconds"
)
chunks = min(
EASY_MAX_CHUNKS,
max(1, int(math.ceil(float(duration) / EASY_TARGET_CHUNK_SECONDS))),
)
chunk_seconds = float(duration) / float(chunks)
if not 4.0 <= chunk_seconds <= 30.0:
raise ValueError("Duration cannot be represented by the Production chunk contract")
return EasyDurationPlan(
duration_seconds=duration,
chunks=chunks,
chunk_seconds=chunk_seconds,
)
class H3ContinuumEasyReferences:
"""Fixed three-image facade for the existing V3.7 reference contract."""
DEPRECATED = False
CATEGORY = CONTINUUM_CATEGORY
DESCRIPTION = (
"Collects up to three optional still-image references for H3 Continuum "
"Easy V3.8. Images are passed unchanged to the existing V3.7 reference "
"preprocessing and conditioning path."
)
SEARCH_ALIASES = [
"H3 Continuum Easy References",
"MiniMax H3 Easy Reference Images",
]
RETURN_TYPES = (EASY_REFERENCES_TYPE,)
RETURN_NAMES = ("references",)
FUNCTION = "pack"
@classmethod
def INPUT_TYPES(cls):
return {
"optional": {
"reference_image_1": (
"IMAGE",
{"display_name": "Reference Image 1 (Optional)"},
),
"reference_image_2": (
"IMAGE",
{"display_name": "Reference Image 2 (Optional)"},
),
"reference_image_3": (
"IMAGE",
{"display_name": "Reference Image 3 (Optional)"},
),
}
}
def pack(
self,
reference_image_1=None,
reference_image_2=None,
reference_image_3=None,
):
return (
make_easy_references(
reference_image_1=reference_image_1,
reference_image_2=reference_image_2,
reference_image_3=reference_image_3,
),
)
class H3ContinuumEasyV38(H3ContinuumSamplerV37):
"""Beginner-facing resolver over the unchanged V3.7 Production engine."""
DEPRECATED = False
CATEGORY = CONTINUUM_CATEGORY
DESCRIPTION = (
"Easy Mode facade over H3 Continuum V3.7 Production. It resolves total "
"duration, decimal-MP resolution, seed UI, and image mode without copying "
"the sampler or scheduler implementation."
)
SEARCH_ALIASES = [
"H3 Continuum Easy V3.8",
"MiniMax H3 Easy Mode",
]
RETURN_TYPES = (
"LATENT",
"LATENT",
"H3_CONTINUUM_ASSEMBLY_PLAN",
"STRING",
"AUDIO",
)
RETURN_NAMES = (
"video_latents",
"audio_latents",
"assembly_plan",
"status",
"driving_audio",
)
OUTPUT_IS_LIST = (True, True, False, False, False)
FUNCTION = "run"
@classmethod
def INPUT_TYPES(cls):
return {
"required": {
"model": ("MODEL",),
"clip": ("CLIP",),
"video_vae": (
"VAE",
{
"display_name": "Video VAE",
"tooltip": "Used only for connected image conditioning.",
},
),
"sampler": ("SAMPLER",),
"sigmas": ("SIGMAS",),
"prompt_text": (
"STRING",
{
"default": "",
"multiline": True,
"dynamicPrompts": True,
"display_name": "Prompt",
},
),
"duration": (
"INT",
{
"default": EASY_DURATION_DEFAULT,
"min": EASY_DURATION_MIN,
"max": EASY_DURATION_MAX,
"step": 1,
"display_name": "Duration (sec)",
},
),
"seed": (
"INT",
{
"default": 0,
"min": 0,
"max": 0xFFFFFFFFFFFFFFFF,
"control_after_generate": True,
"display_name": "Seed",
},
),
"seed_mode": (
EASY_SEED_MODE_OPTIONS,
{
"default": EASY_SEED_MODE_RANDOMIZE,
"display_name": "Seed Mode",
},
),
"aspect": (
EASY_ASPECT_OPTIONS,
{
"default": EASY_ASPECT_AUTO,
"display_name": "Aspect",
},
),
"preset": (
EASY_PRESET_OPTIONS,
{
"default": EASY_PRESET_DRAFT,
"display_name": "Resolution Preset",
},
),
"custom_mp": (
"FLOAT",
{
"default": EASY_CUSTOM_MP_DEFAULT,
"min": EASY_CUSTOM_MP_MIN,
"max": EASY_CUSTOM_MP_MAX,
"step": 0.01,
"display_name": "Custom MP",
},
),
"run_storage": (
("Off", "Save + Auto Resume"),
{
"default": "Off",
"display_name": "Run Storage",
"advanced": True,
},
),
"run_name": (
"STRING",
{
"default": "",
"display_name": "Run Name (Optional Override)",
"advanced": True,
},
),
"project_id": (
"STRING",
{
"default": "",
"display_name": "Auto Resume ID Override",
"advanced": True,
},
),
},
"optional": {
"first_frame": (
"IMAGE",
{"display_name": "First Image (Optional)"},
),
"last_frame": (
"IMAGE",
{"display_name": "Last Image (Optional)"},
),
"references": (
EASY_REFERENCES_TYPE,
{"display_name": "Easy References (Optional)"},
),
"driving_audio": (
"AUDIO",
{
"display_name": "Driving Audio",
"tooltip": (
"Optional original audio timeline. Uses the unchanged "
"V3.7 Driving Audio conditioning and final-output contract."
),
},
),
"audio_vae": (
"VAE",
{
"display_name": "Driving Audio VAE",
"tooltip": (
"Required only when Driving Audio is connected. It may be "
"shared with the external Core audio decode path."
),
},
),
},
"hidden": {
"prompt": "PROMPT",
"unique_id": "UNIQUE_ID",
},
}
def run(
self,
model,
clip,
video_vae,
sampler,
sigmas,
prompt_text,
duration,
seed,
seed_mode=EASY_SEED_MODE_RANDOMIZE,
aspect=EASY_ASPECT_AUTO,
preset=EASY_PRESET_DRAFT,
custom_mp=EASY_CUSTOM_MP_DEFAULT,
run_storage="Off",
run_name="",
project_id="",
first_frame=None,
last_frame=None,
references=None,
driving_audio=None,
audio_vae=None,
prompt=None,
unique_id=None,
):
del seed_mode # Queue-time seed mutation remains owned by ComfyUI's frontend.
duration_plan = resolve_easy_duration(duration)
resolution = resolve_easy_resolution(
aspect=aspect,
preset=preset,
custom_mp=custom_mp,
first_frame=first_frame,
)
reference_image_1, reference_image_2, reference_image_3 = (
resolve_easy_references(references)
)
outputs = super().run(
model=model,
clip=clip,
video_vae=video_vae,
sampler=sampler,
sigmas=sigmas,
sequence_prompt=prompt_text,
prompt_mode=PROMPT_FORMAT_AUTO,
chunks=duration_plan.chunks,
chunk_seconds=duration_plan.chunk_seconds,
width=resolution.width,
height=resolution.height,
continuity=CONTINUITY_OPTIONS[0],
base_seed=int(seed),
audio_continuity=True,
diagnostics=DIAGNOSTICS_BASIC,
reroll_from_chunk=REGENERATE_AUTO,
reroll_nonce=0,
strict_compatibility=False,
debug=False,
show_preview=True,
run_storage=run_storage,
run_name=run_name,
reference_size=REFERENCE_SIZE_MATCH_OUTPUT,
reference_image_1=reference_image_1,
reference_image_2=reference_image_2,
reference_image_3=reference_image_3,
driving_audio=driving_audio,
audio_vae=audio_vae,
project_id=project_id,
first_frame=first_frame,
last_frame=last_frame,
prompt=prompt,
unique_id=unique_id,
video_reference_size=REFERENCE_VIDEO_SIZE_EFFICIENT,
continuation_backend=CONTINUATION_BACKEND_STANDARD,
)
video, audio, assembly_plan, status, driving_audio = outputs[:5]
mode = conditioning_display_label(
has_first=first_frame is not None,
has_last=last_frame is not None,
has_reference=any(
image is not None
for image in (
reference_image_1,
reference_image_2,
reference_image_3,
)
),
)
warning_lines = "\n".join(resolution.warnings)
summary = (
f"H3 Continuum Easy V3.8\n"
f"{mode} / {duration_plan.duration_seconds} sec\n"
f"{resolution.preset}: {resolution.width} x {resolution.height} "
f"({resolution.actual_mp:.2f} MP)"
)
if warning_lines:
summary += f"\n{warning_lines}"
return video, audio, assembly_plan, f"{summary}\n\n{status}", driving_audio
NODE_CLASS_MAPPINGS = {
"H3ContinuumEasyReferences": H3ContinuumEasyReferences,
"H3ContinuumEasyV38": H3ContinuumEasyV38,
}
NODE_DISPLAY_NAME_MAPPINGS = {
"H3ContinuumEasyReferences": "H3 Continuum Easy References",
"H3ContinuumEasyV38": "H3 Continuum Easy V3.8",
}
+272
View File
@@ -0,0 +1,272 @@
"""Simple H3 video loader backed by the current ComfyUI Core video API."""
from __future__ import annotations
from fractions import Fraction
import os
import torch
try:
import folder_paths
except ImportError: # pragma: no cover - standalone unit tests
class _FolderPathsShim:
@staticmethod
def get_input_directory():
return "."
@staticmethod
def filter_files_content_types(files, content_types):
del files, content_types
return []
@staticmethod
def get_annotated_filepath(file):
raise RuntimeError(f"ComfyUI folder_paths is unavailable for {file}")
@staticmethod
def exists_annotated_filepath(file):
del file
return False
folder_paths = _FolderPathsShim()
try:
from comfy_api.latest import InputImpl, io
except ImportError: # pragma: no cover - standalone unit tests
class _SchemaItem:
def __init__(self, item_id=None, **kwargs):
self.id = item_id
for key, value in kwargs.items():
setattr(self, key, value)
class _InputFactory:
Input = _SchemaItem
class _OutputFactory:
@staticmethod
def Output(**kwargs):
return _SchemaItem(**kwargs)
class _UploadVideo:
value = "video_upload"
class _UploadType:
video = _UploadVideo()
class _Schema:
def __init__(self, **kwargs):
for key, value in kwargs.items():
setattr(self, key, value)
class _NodeOutput:
def __init__(self, *args):
self.args = args
class _ComfyNode:
pass
class _IOShim:
ComfyNode = _ComfyNode
Schema = _Schema
NodeOutput = _NodeOutput
Boolean = _InputFactory
Combo = _InputFactory
Float = _InputFactory
Image = _OutputFactory
Audio = _OutputFactory
UploadType = _UploadType
class _InputImplShim:
@staticmethod
def VideoFromFile(path):
raise RuntimeError(f"ComfyUI VideoFromFile is unavailable for {path}")
InputImpl = _InputImplShim
io = _IOShim()
try:
from comfy_execution.graph_utils import ExecutionBlocker
except ImportError: # pragma: no cover - standalone unit tests
class ExecutionBlocker:
def __init__(self, message):
self.message = message
CATEGORY = "MiniMax H3/Continuum"
def _fraction_from_rate(value: float) -> Fraction:
"""Convert a UI frame-rate value without introducing binary-float drift."""
return Fraction(str(float(value))).limit_denominator(1_000_000)
def _resample_video_frames(
images: torch.Tensor,
source_rate: Fraction,
target_rate: float,
) -> torch.Tensor:
"""Drop or duplicate IMAGE frames while preserving nominal duration."""
if images.ndim != 4:
raise ValueError(
f"Expected IMAGE batch [B,H,W,C], got shape {tuple(images.shape)}"
)
frame_count = int(images.shape[0])
if frame_count <= 0:
raise ValueError("Video contains no decodable frames")
source = Fraction(source_rate)
if source <= 0:
raise ValueError(f"Invalid source frame rate: {source_rate}")
requested_rate = float(target_rate)
if requested_rate <= 0:
return images
target = _fraction_from_rate(requested_rate)
if target == source:
return images
target_count = max(1, round(Fraction(frame_count, 1) * target / source))
source_numerator = source.numerator
source_denominator = source.denominator
target_numerator = target.numerator
target_denominator = target.denominator
indices = [
min(
frame_count - 1,
(
index
* source_numerator
* target_denominator
// (source_denominator * target_numerator)
),
)
for index in range(target_count)
]
index_tensor = torch.tensor(indices, dtype=torch.long, device=images.device)
return images.index_select(0, index_tensor)
def load_video_components(
*,
file: str,
enable_video: bool,
force_rate: float,
):
"""Decode through Core and return standard IMAGE/AUDIO outputs."""
if not enable_video:
blocker = ExecutionBlocker(None)
return blocker, blocker
video_path = folder_paths.get_annotated_filepath(file)
components = InputImpl.VideoFromFile(video_path).get_components()
images = _resample_video_frames(
components.images,
Fraction(components.frame_rate),
float(force_rate),
)
audio = components.audio
if audio is None:
audio = ExecutionBlocker(None)
return images, audio
class H3ContinuumLoadVideo(io.ComfyNode):
"""Minimal Core-backed video loader for H3 Continuum workflows."""
@classmethod
def define_schema(cls):
input_dir = folder_paths.get_input_directory()
files = [
name
for name in os.listdir(input_dir)
if os.path.isfile(os.path.join(input_dir, name))
]
files = folder_paths.filter_files_content_types(files, ["video"])
return io.Schema(
node_id="H3ContinuumLoadVideo",
display_name="H3 Continuum Load Video",
category=CATEGORY,
description=(
"Loads IMAGE and AUDIO through ComfyUI Core VideoFromFile. "
"Force Rate drops or duplicates frames without changing duration or audio."
),
search_aliases=[
"H3 Continuum Load Video",
"H3 Easy Load Video",
"MiniMax H3 Video Loader",
],
inputs=[
io.Boolean.Input(
"enable_video",
default=True,
display_name="Enable Video",
),
io.Combo.Input(
"file",
options=sorted(files),
upload=io.UploadType.video,
display_name="Video",
),
io.Float.Input(
"force_rate",
default=24.0,
min=0.0,
max=120.0,
step=0.01,
display_name="Force Rate",
tooltip=(
"0 uses the source FPS. A positive value resamples frames "
"while preserving nominal duration."
),
),
],
outputs=[
io.Image.Output(display_name="images"),
io.Audio.Output(display_name="audio"),
],
)
@classmethod
def execute(cls, enable_video: bool, file: str, force_rate: float):
return io.NodeOutput(
*load_video_components(
file=file,
enable_video=bool(enable_video),
force_rate=float(force_rate),
)
)
@classmethod
def fingerprint_inputs(cls, enable_video: bool, file: str, force_rate: float):
enabled = bool(enable_video)
file_name = str(file)
modification_time = None
if enabled and folder_paths.exists_annotated_filepath(file_name):
video_path = folder_paths.get_annotated_filepath(file_name)
modification_time = os.path.getmtime(video_path)
return enabled, file_name, float(force_rate), modification_time
@classmethod
def validate_inputs(cls, enable_video: bool, file: str, force_rate: float):
del force_rate
if not bool(enable_video):
return True
if not folder_paths.exists_annotated_filepath(file):
return f"Invalid video file: {file}"
return True
NODE_CLASS_MAPPINGS = {
"H3ContinuumLoadVideo": H3ContinuumLoadVideo,
}
NODE_DISPLAY_NAME_MAPPINGS = {
"H3ContinuumLoadVideo": "H3 Continuum Load Video",
}
+221
View File
@@ -0,0 +1,221 @@
"""Explicit opt-in A7b memory actions that preserve Production ownership.
This module resolves only Reference sizing policy. Model unloading and
attention/backend selection remain advisory because ComfyUI Core and external
MODEL wrappers own those lifecycles.
"""
from __future__ import annotations
from dataclasses import dataclass
import hashlib
import json
from typing import Any
from ..reference import REFERENCE_SIZE_MATCH_OUTPUT, REFERENCE_SIZE_MAX_IDENTITY
from ..reference_video import (
REFERENCE_VIDEO_SIZE_BALANCED,
REFERENCE_VIDEO_SIZE_EFFICIENT,
REFERENCE_VIDEO_SIZE_MATCH_OUTPUT,
)
MEMORY_ACTION_POLICY_TYPE = "H3_CONTINUUM_MEMORY_ACTION_POLICY"
MEMORY_ACTION_POLICY_VERSION = 1
ACTION_DISABLED = "Disabled"
ACTION_REDUCE_REFERENCES_ONE_STEP = "Reduce References One Step"
ACTION_OPTIONS = (
ACTION_DISABLED,
ACTION_REDUCE_REFERENCES_ONE_STEP,
)
_IMAGE_DOWNGRADE = {
REFERENCE_SIZE_MAX_IDENTITY: REFERENCE_SIZE_MATCH_OUTPUT,
REFERENCE_SIZE_MATCH_OUTPUT: REFERENCE_SIZE_MATCH_OUTPUT,
}
_VIDEO_DOWNGRADE = {
REFERENCE_VIDEO_SIZE_MATCH_OUTPUT: REFERENCE_VIDEO_SIZE_BALANCED,
REFERENCE_VIDEO_SIZE_BALANCED: REFERENCE_VIDEO_SIZE_EFFICIENT,
REFERENCE_VIDEO_SIZE_EFFICIENT: REFERENCE_VIDEO_SIZE_EFFICIENT,
}
def _canonical_hash(value: Any) -> str:
payload = json.dumps(
value,
sort_keys=True,
separators=(",", ":"),
ensure_ascii=True,
).encode("utf-8")
return hashlib.sha256(payload).hexdigest()
def _contract_base(action: str) -> dict[str, Any]:
return {
"memory_action_policy_version": MEMORY_ACTION_POLICY_VERSION,
"action": action,
"reference_downgrade": (
"one_step"
if action == ACTION_REDUCE_REFERENCES_ONE_STEP
else "disabled"
),
"auto_unload": "advisory_only",
"backend_switch": "advisory_only",
"same_run_actual_row_trigger": False,
}
def make_memory_action_policy(action: str = ACTION_DISABLED) -> dict[str, Any]:
"""Build the versioned policy object emitted by the public helper node."""
normalized = str(action)
if normalized not in ACTION_OPTIONS:
raise ValueError(f"unsupported memory action {action!r}")
contract = _contract_base(normalized)
return {**contract, "contract_hash": _canonical_hash(contract)}
@dataclass(frozen=True)
class MemoryActionDecision:
action: str
enabled: bool
requested_image_mode: str
effective_image_mode: str
requested_video_mode: str
effective_video_mode: str
image_applied: bool
video_applied: bool
contract_hash: str | None
warning: str | None = None
@property
def applied(self) -> bool:
return bool(self.image_applied or self.video_applied)
def _disabled_decision(
*,
image_mode: str,
video_mode: str,
contract_hash: str | None = None,
warning: str | None = None,
) -> MemoryActionDecision:
return MemoryActionDecision(
action=ACTION_DISABLED,
enabled=False,
requested_image_mode=image_mode,
effective_image_mode=image_mode,
requested_video_mode=video_mode,
effective_video_mode=video_mode,
image_applied=False,
video_applied=False,
contract_hash=contract_hash,
warning=warning,
)
def resolve_memory_action_policy(
policy: Any,
*,
image_mode: str,
video_mode: str,
has_reference_images: bool,
has_video_guide: bool,
) -> MemoryActionDecision:
"""Resolve an optional policy without changing tensors or runtime state.
Malformed or unsupported objects fail soft to Disabled. The caller may
surface ``warning`` after generation, but Sampling inputs remain unchanged.
"""
requested_image = str(image_mode)
requested_video = str(video_mode)
if policy is None:
return _disabled_decision(
image_mode=requested_image,
video_mode=requested_video,
)
if not isinstance(policy, dict):
return _disabled_decision(
image_mode=requested_image,
video_mode=requested_video,
warning="invalid policy object; no memory action was applied",
)
action = str(policy.get("action", ""))
try:
version = int(policy.get("memory_action_policy_version"))
except (TypeError, ValueError):
version = -1
supplied_hash = policy.get("contract_hash")
expected_contract = _contract_base(action) if action in ACTION_OPTIONS else None
expected_hash = (
_canonical_hash(expected_contract) if expected_contract is not None else None
)
if (
version != MEMORY_ACTION_POLICY_VERSION
or action not in ACTION_OPTIONS
or not isinstance(supplied_hash, str)
or supplied_hash != expected_hash
):
return _disabled_decision(
image_mode=requested_image,
video_mode=requested_video,
warning="unsupported or modified policy contract; no memory action was applied",
)
if action == ACTION_DISABLED:
return _disabled_decision(
image_mode=requested_image,
video_mode=requested_video,
contract_hash=supplied_hash,
)
effective_image = requested_image
effective_video = requested_video
if bool(has_reference_images):
effective_image = _IMAGE_DOWNGRADE.get(requested_image, requested_image)
if bool(has_video_guide):
effective_video = _VIDEO_DOWNGRADE.get(requested_video, requested_video)
return MemoryActionDecision(
action=action,
enabled=True,
requested_image_mode=requested_image,
effective_image_mode=effective_image,
requested_video_mode=requested_video,
effective_video_mode=effective_video,
image_applied=(
bool(has_reference_images) and effective_image != requested_image
),
video_applied=(bool(has_video_guide) and effective_video != requested_video),
contract_hash=supplied_hash,
)
def format_memory_action_status(decision: MemoryActionDecision) -> str | None:
"""Format post-generation status without claiming VRAM prediction."""
if decision.warning is not None:
return "Memory Action Policy [Experimental A7b v1]: " + decision.warning + "."
if not decision.enabled:
return None
changes: list[str] = []
if decision.image_applied:
changes.append(
"Reference Image "
f"{decision.requested_image_mode} -> {decision.effective_image_mode}"
)
if decision.video_applied:
changes.append(
"Video Guide "
f"{decision.requested_video_mode} -> {decision.effective_video_mode}"
)
action = "; ".join(changes) if changes else "no applicable Reference downgrade"
return (
"Memory Action Policy [Experimental A7b v1]: explicit opt-in; "
f"{action}.\n"
"Memory advisory: automatic MODEL unload was not executed; Core retains "
"lifecycle ownership.\n"
"Memory advisory: automatic attention/backend switching was not executed; "
"the external MODEL wrapper was preserved."
)
+949 -710
View File
File diff suppressed because it is too large Load Diff
+349
View File
@@ -0,0 +1,349 @@
"""Read-only A7a planning from actual ComfyUI H3 PackedLayout rows.
The planner observes layouts that ComfyUI Core already built for Sampling. It
does not estimate VRAM, change execution policy, mutate a layout, or influence
the physical-group order. Memory counters are point-in-time observations only.
"""
from __future__ import annotations
from dataclasses import dataclass
from typing import Any, Callable
PACKED_ROW_PLAN_VERSION = 1
MAX_CONCURRENT_PHYSICAL_GROUPS = 1
_VIDEO_CONDITION_KINDS = frozenset(("cond", "ref_img"))
_AUDIO_CONDITION_KINDS = frozenset(("cond_audio", "ref_audio"))
class PackedRowPlanningError(ValueError):
"""An observed object is not an internally consistent H3 PackedLayout."""
@dataclass(frozen=True)
class PackedRowBreakdown:
seq_len: int
text_rows: int
condition_video_rows: int
condition_audio_rows: int
target_video_rows: int
target_audio_rows: int
unknown_rows: int
segment_count: int
segment_signature: tuple[tuple[int, int, str], ...]
@property
def condition_rows(self) -> int:
return int(self.condition_video_rows + self.condition_audio_rows)
@property
def target_rows(self) -> int:
return int(self.target_video_rows + self.target_audio_rows)
@property
def condition_to_target_ratio(self) -> float | None:
if self.target_rows <= 0:
return None
return float(self.condition_rows / self.target_rows)
@dataclass(frozen=True)
class MemoryObservation:
system_available_bytes: int | None = None
cuda_allocated_bytes: int | None = None
cuda_reserved_bytes: int | None = None
core_visible_free_bytes: int | None = None
def analyze_packed_layout(layout: Any) -> PackedRowBreakdown:
"""Account actual rows without importing or recreating Core PackedLayout."""
if layout is None:
raise PackedRowPlanningError("Core PackedLayout is unavailable")
try:
seq_len = int(layout.seq_len)
raw_segments = tuple(layout.segments)
except Exception as exc:
raise PackedRowPlanningError(
"Core PackedLayout does not expose seq_len/segments"
) from exc
if seq_len <= 0 or not raw_segments:
raise PackedRowPlanningError("Core PackedLayout is empty")
signature: list[tuple[int, int, str]] = []
previous_stop = 0
counts = {
"text": 0,
"condition_video": 0,
"condition_audio": 0,
"target_video": 0,
"target_audio": 0,
"unknown": 0,
}
target_video_segments = 0
target_audio_segments = 0
for item in raw_segments:
if not isinstance(item, (tuple, list)) or len(item) != 3:
raise PackedRowPlanningError("PackedLayout segment is not (start, stop, kind)")
start, stop, kind = int(item[0]), int(item[1]), str(item[2])
if start != previous_stop or stop <= start or stop > seq_len:
raise PackedRowPlanningError(
"PackedLayout segments are not a contiguous in-range partition"
)
rows = stop - start
signature.append((start, stop, kind))
if kind == "text":
counts["text"] += rows
elif kind in _VIDEO_CONDITION_KINDS:
counts["condition_video"] += rows
elif kind in _AUDIO_CONDITION_KINDS:
counts["condition_audio"] += rows
elif kind == "video":
counts["target_video"] += rows
target_video_segments += 1
elif kind == "audio":
counts["target_audio"] += rows
target_audio_segments += 1
else:
counts["unknown"] += rows
previous_stop = stop
if previous_stop != seq_len:
raise PackedRowPlanningError("PackedLayout segment rows do not sum to seq_len")
if target_video_segments != 1 or target_audio_segments != 1:
raise PackedRowPlanningError(
"H3 PackedLayout must contain exactly one target Video and Audio segment"
)
return PackedRowBreakdown(
seq_len=seq_len,
text_rows=int(counts["text"]),
condition_video_rows=int(counts["condition_video"]),
condition_audio_rows=int(counts["condition_audio"]),
target_video_rows=int(counts["target_video"]),
target_audio_rows=int(counts["target_audio"]),
unknown_rows=int(counts["unknown"]),
segment_count=len(signature),
segment_signature=tuple(signature),
)
def read_memory_observation() -> MemoryObservation:
"""Read counters without CUDA synchronization, cache clearing, or peak reset."""
system_available = None
cuda_allocated = None
cuda_reserved = None
core_free = None
try:
import psutil
system_available = int(psutil.virtual_memory().available)
except Exception:
pass
try:
import torch
if torch.cuda.is_available():
cuda_allocated = int(torch.cuda.memory_allocated())
cuda_reserved = int(torch.cuda.memory_reserved())
except Exception:
pass
try:
import comfy.model_management as model_management
device = model_management.get_torch_device()
core_free = int(model_management.get_free_memory(device))
except Exception:
pass
return MemoryObservation(
system_available_bytes=system_available,
cuda_allocated_bytes=cuda_allocated,
cuda_reserved_bytes=cuda_reserved,
core_visible_free_bytes=core_free,
)
def _safe_memory_read(reader: Callable[[], MemoryObservation]) -> MemoryObservation:
try:
value = reader()
return value if isinstance(value, MemoryObservation) else MemoryObservation()
except Exception:
return MemoryObservation()
class PackedRowPlanner:
"""Collect one immutable actual-layout plan record per sampled group."""
def __init__(
self,
*,
memory_reader: Callable[[], MemoryObservation] = read_memory_observation,
) -> None:
self._memory_reader = memory_reader
self._active: dict[str, Any] | None = None
self._records: list[dict[str, Any]] = []
self._advisories: list[str] = []
@property
def records(self) -> tuple[dict[str, Any], ...]:
return tuple(self._records)
def begin_group(
self,
*,
physical_group: int,
logical_chunks: tuple[int, ...],
terminal_atomic: bool,
) -> None:
if self._active is not None:
self._advisories.append(
"a group began before the prior observation was finalized"
)
self.finish_group()
self._active = {
"physical_group": int(physical_group),
"logical_chunks": tuple(int(value) for value in logical_chunks),
"terminal_atomic": bool(terminal_atomic),
"pre_memory": _safe_memory_read(self._memory_reader),
"breakdown": None,
"unavailable": None,
}
def observe_layout(self, layout: Any) -> None:
if self._active is None:
return
try:
observed = analyze_packed_layout(layout)
except Exception as exc:
if self._active["breakdown"] is None:
self._active["unavailable"] = f"{type(exc).__name__}: {exc}"
return
current = self._active["breakdown"]
if current is not None and current != observed:
self._active["unavailable"] = (
"PackedLayout topology changed within one physical group"
)
self._active["breakdown"] = None
return
if self._active["unavailable"] is None:
self._active["breakdown"] = observed
def note_observation_failure(self, exc: Exception) -> None:
if self._active is not None and self._active["breakdown"] is None:
self._active["unavailable"] = f"{type(exc).__name__}: {exc}"
def finish_group(self) -> None:
if self._active is None:
return
record = dict(self._active)
record["post_memory"] = _safe_memory_read(self._memory_reader)
if record["breakdown"] is None and record["unavailable"] is None:
record["unavailable"] = "Core PackedLayout was not observed"
self._records.append(record)
self._active = None
@staticmethod
def _mib(value: int | None) -> str:
return "n/a" if value is None else f"{int(value) / 1024**2:.1f} MiB"
def report_lines(self) -> list[str]:
if self._active is not None:
self.finish_group()
valid = [record for record in self._records if record["breakdown"] is not None]
peak = None
if valid:
peak = max(valid, key=lambda record: record["breakdown"].seq_len)
order = [int(record["physical_group"]) for record in self._records]
lines = [
"Packed-row plan [A7a v1]: "
f"execution_order={order}, "
f"max_concurrent_physical_groups={MAX_CONCURRENT_PHYSICAL_GROUPS}, "
f"observed_groups={len(valid)}/{len(self._records)}, "
f"peak_candidate={int(peak['physical_group']) if peak else 'unavailable'}, "
f"peak_total_rows={peak['breakdown'].seq_len if peak else 'unavailable'}; "
"actual Core rows only, VRAM/time prediction=not provided, "
"execution policy=unchanged."
]
for record in self._records:
group = int(record["physical_group"])
logical = list(record["logical_chunks"])
breakdown = record["breakdown"]
if breakdown is None:
lines.append(
"Packed-row group [A7a v1]: "
f"physical_group={group}, logical_chunks={logical}, "
f"terminal_atomic={str(bool(record['terminal_atomic'])).lower()}, "
f"unavailable/advisory={record['unavailable']}."
)
continue
pre = record["pre_memory"]
post = record["post_memory"]
ratio = breakdown.condition_to_target_ratio
ratio_text = "n/a" if ratio is None else f"{ratio:.6f}"
lines.append(
"Packed-row group [A7a v1]: "
f"physical_group={group}, logical_chunks={logical}, "
f"terminal_atomic={str(bool(record['terminal_atomic'])).lower()}, "
f"total={breakdown.seq_len}, text={breakdown.text_rows}, "
f"condition_video={breakdown.condition_video_rows}, "
f"condition_audio={breakdown.condition_audio_rows}, "
f"target_video={breakdown.target_video_rows}, "
f"target_audio={breakdown.target_audio_rows}, "
f"unknown={breakdown.unknown_rows}, "
f"condition_to_target_ratio={ratio_text}, "
f"pre_system_available={self._mib(pre.system_available_bytes)}, "
f"pre_CUDA_allocated={self._mib(pre.cuda_allocated_bytes)}, "
f"pre_CUDA_reserved={self._mib(pre.cuda_reserved_bytes)}, "
f"pre_Core_free={self._mib(pre.core_visible_free_bytes)}, "
f"post_system_available={self._mib(post.system_available_bytes)}, "
f"post_CUDA_allocated={self._mib(post.cuda_allocated_bytes)}, "
f"post_CUDA_reserved={self._mib(post.cuda_reserved_bytes)}, "
f"post_Core_free={self._mib(post.core_visible_free_bytes)}."
)
lines.extend(f"Packed-row advisory [A7a v1]: {item}." for item in self._advisories)
return lines
def observe_layout_fail_soft(planner: Any, payload: Any) -> None:
"""Diagnostics must never replace a Sampling result."""
if planner is None:
return
try:
layout = payload.get("layout") if isinstance(payload, dict) else None
planner.observe_layout(layout)
except Exception as exc:
try:
planner.note_observation_failure(exc)
except Exception:
pass
def planner_event_fail_soft(planner: Any, method: str, **kwargs: Any) -> Any:
"""Invoke one lifecycle event without allowing diagnostics to stop Sampling."""
if planner is None:
return None
try:
return getattr(planner, str(method))(**kwargs)
except Exception as exc:
try:
planner.note_observation_failure(exc)
except Exception:
pass
return None
__all__ = [
"MAX_CONCURRENT_PHYSICAL_GROUPS",
"MemoryObservation",
"PACKED_ROW_PLAN_VERSION",
"PackedRowBreakdown",
"PackedRowPlanner",
"PackedRowPlanningError",
"analyze_packed_layout",
"observe_layout_fail_soft",
"planner_event_fail_soft",
"read_memory_observation",
]
+281 -281
View File
@@ -1,205 +1,205 @@
"""Assembly-plan contract for latent-first H3 Continuum V3."""
from __future__ import annotations
from typing import Any
import torch
from ..state import validate_plan
"""Assembly-plan contract for latent-first H3 Continuum V3."""
from __future__ import annotations
from typing import Any
import torch
from ..state import validate_plan
ASSEMBLY_PLAN_MAGIC = "H3_CONTINUUM_ASSEMBLY_PLAN"
ASSEMBLY_PLAN_SCHEMA_VERSION = 1
FPS = 24
SECOND_PASS_CONTRACT_VERSION = 1
class AssemblyPlanError(ValueError):
pass
def make_assembly_plan(
entries: list[dict[str, Any]],
*,
chunk_seconds: float,
preserve_final_frame: bool,
) -> dict[str, Any]:
if not entries:
raise AssemblyPlanError("cannot create an assembly plan for an empty sequence")
chunks: list[dict[str, Any]] = []
width = height = None
for sequence_index, entry in enumerate(entries, start=1):
if not isinstance(entry, dict):
raise AssemblyPlanError(f"chunk {sequence_index} entry is not a dictionary")
plan = validate_plan(entry.get("plan"))
video = entry.get("video")
audio = entry.get("audio")
if not torch.is_tensor(video) or video.ndim < 3:
raise AssemblyPlanError(f"chunk {sequence_index} video latent is invalid")
if not torch.is_tensor(audio) or audio.ndim < 3:
raise AssemblyPlanError(f"chunk {sequence_index} audio latent is invalid")
plan_width = int(plan["width"])
plan_height = int(plan["height"])
if width is None:
width, height = plan_width, plan_height
elif (plan_width, plan_height) != (width, height):
raise AssemblyPlanError("chunk dimensions changed within the sequence")
chunks.append(
{
"sequence_index": sequence_index,
"chunk_index": int(plan["clip_index"]),
"total_frames": int(plan["total_frames"]),
"trim_frames": int(plan["trim_frames"]),
"net_frames": int(plan["net_frames"]),
"context_frames": int(plan["context_frames"]),
"expected_video_latent_t": int(video.shape[2]),
"expected_audio_latent_t": int(audio.shape[-1]),
}
)
result = {
"magic": ASSEMBLY_PLAN_MAGIC,
"schema_version": ASSEMBLY_PLAN_SCHEMA_VERSION,
"fps": FPS,
"width": int(width),
"height": int(height),
"chunk_seconds": float(chunk_seconds),
"target_frames": int(round(len(chunks) * float(chunk_seconds) * FPS)),
"preserve_final_frame": bool(preserve_final_frame),
"chunks": chunks,
}
return validate_assembly_plan(result)
def validate_assembly_plan(plan: Any) -> dict[str, Any]:
if not isinstance(plan, dict) or plan.get("magic") != ASSEMBLY_PLAN_MAGIC:
raise AssemblyPlanError("invalid H3 Continuum V3 assembly plan")
if (
type(plan.get("schema_version")) is not int
or plan["schema_version"] != ASSEMBLY_PLAN_SCHEMA_VERSION
):
raise AssemblyPlanError(
f"unsupported assembly plan schema {plan.get('schema_version')!r}"
)
if int(plan.get("fps", 0)) != FPS:
raise AssemblyPlanError("assembly plan FPS must be 24")
if int(plan.get("width", 0)) <= 0 or int(plan.get("height", 0)) <= 0:
raise AssemblyPlanError("assembly plan dimensions are invalid")
if float(plan.get("chunk_seconds", 0.0)) <= 0:
raise AssemblyPlanError("assembly plan chunk duration is invalid")
if int(plan.get("target_frames", 0)) <= 0:
raise AssemblyPlanError("assembly plan target frame count is invalid")
chunks = plan.get("chunks")
if not isinstance(chunks, list) or not chunks:
raise AssemblyPlanError("assembly plan contains no chunks")
for expected_index, chunk in enumerate(chunks, start=1):
if not isinstance(chunk, dict):
raise AssemblyPlanError(f"assembly chunk {expected_index} is invalid")
if int(chunk.get("sequence_index", 0)) != expected_index:
raise AssemblyPlanError("assembly chunk order is not contiguous")
total = int(chunk.get("total_frames", 0))
trim = int(chunk.get("trim_frames", -1))
net = int(chunk.get("net_frames", 0))
if total <= 0 or trim < 0 or net <= 0 or total - trim != net:
raise AssemblyPlanError(
f"assembly chunk {expected_index} frame plan is invalid"
)
if int(chunk.get("context_frames", -1)) < 0:
raise AssemblyPlanError(
f"assembly chunk {expected_index} context is invalid"
)
if int(chunk.get("expected_video_latent_t", 0)) <= 0:
raise AssemblyPlanError(
f"assembly chunk {expected_index} video latent length is invalid"
)
if int(chunk.get("expected_audio_latent_t", 0)) <= 0:
raise AssemblyPlanError(
f"assembly chunk {expected_index} audio latent length is invalid"
)
return plan
# V3.0.1 hardening integration: redundant metadata plus fail-closed validation.
from ..hardening import (
enrich_assembly_plan as _enrich_assembly_plan,
validate_assembly_plan_contract as _validate_assembly_plan_contract,
)
_make_assembly_plan_v300 = make_assembly_plan
_validate_assembly_plan_v300 = validate_assembly_plan
def validate_assembly_plan(plan):
result = _validate_assembly_plan_v300(plan)
_validate_assembly_plan_contract(plan)
return result
def make_assembly_plan(*args, **kwargs):
plan = _make_assembly_plan_v300(*args, **kwargs)
_enrich_assembly_plan(plan)
validate_assembly_plan(plan)
return plan
def _recombine_terminal_tensor(
first,
second,
*,
slices,
time_dim: int,
name: str,
):
"""Invert the terminal logical split without changing any tensor value."""
import torch
if not torch.is_tensor(first) or not torch.is_tensor(second):
raise ValueError(f"terminal {name} entries must be tensors")
if first.ndim != second.ndim:
raise ValueError(f"terminal {name} tensor ranks differ")
dim = int(time_dim)
if dim < 0:
dim += first.ndim
if dim < 0 or dim >= first.ndim:
raise ValueError(f"terminal {name} time dimension is invalid")
for axis, (left, right) in enumerate(zip(first.shape, second.shape)):
if axis != dim and int(left) != int(right):
raise ValueError(f"terminal {name} tensor geometry differs")
(first_start, first_stop), (second_start, second_stop) = slices
first_start = int(first_start)
first_stop = int(first_stop)
second_start = int(second_start)
second_stop = int(second_stop)
if first_start != 0 or second_start > first_stop or second_stop <= first_stop:
raise ValueError(f"terminal {name} split ranges do not form one physical unit")
if int(first.shape[dim]) != first_stop - first_start:
raise ValueError(f"terminal {name} first slice length is inconsistent")
if int(second.shape[dim]) != second_stop - second_start:
raise ValueError(f"terminal {name} second slice length is inconsistent")
overlap_start = max(first_start, second_start)
overlap_stop = min(first_stop, second_stop)
overlap_length = max(0, overlap_stop - overlap_start)
if overlap_length:
first_overlap = first.narrow(dim, overlap_start - first_start, overlap_length)
second_overlap = second.narrow(dim, overlap_start - second_start, overlap_length)
if not torch.equal(first_overlap, second_overlap):
raise ValueError(
f"terminal {name} overlap differs; refusing lossy physical reconstruction"
)
output_shape = list(first.shape)
output_shape[dim] = second_stop
output = first.new_empty(output_shape)
output.narrow(dim, first_start, first_stop - first_start).copy_(first)
output.narrow(dim, second_start, second_stop - second_start).copy_(second)
return output.contiguous()
class AssemblyPlanError(ValueError):
pass
def make_assembly_plan(
entries: list[dict[str, Any]],
*,
chunk_seconds: float,
preserve_final_frame: bool,
) -> dict[str, Any]:
if not entries:
raise AssemblyPlanError("cannot create an assembly plan for an empty sequence")
chunks: list[dict[str, Any]] = []
width = height = None
for sequence_index, entry in enumerate(entries, start=1):
if not isinstance(entry, dict):
raise AssemblyPlanError(f"chunk {sequence_index} entry is not a dictionary")
plan = validate_plan(entry.get("plan"))
video = entry.get("video")
audio = entry.get("audio")
if not torch.is_tensor(video) or video.ndim < 3:
raise AssemblyPlanError(f"chunk {sequence_index} video latent is invalid")
if not torch.is_tensor(audio) or audio.ndim < 3:
raise AssemblyPlanError(f"chunk {sequence_index} audio latent is invalid")
plan_width = int(plan["width"])
plan_height = int(plan["height"])
if width is None:
width, height = plan_width, plan_height
elif (plan_width, plan_height) != (width, height):
raise AssemblyPlanError("chunk dimensions changed within the sequence")
chunks.append(
{
"sequence_index": sequence_index,
"chunk_index": int(plan["clip_index"]),
"total_frames": int(plan["total_frames"]),
"trim_frames": int(plan["trim_frames"]),
"net_frames": int(plan["net_frames"]),
"context_frames": int(plan["context_frames"]),
"expected_video_latent_t": int(video.shape[2]),
"expected_audio_latent_t": int(audio.shape[-1]),
}
)
result = {
"magic": ASSEMBLY_PLAN_MAGIC,
"schema_version": ASSEMBLY_PLAN_SCHEMA_VERSION,
"fps": FPS,
"width": int(width),
"height": int(height),
"chunk_seconds": float(chunk_seconds),
"target_frames": int(round(len(chunks) * float(chunk_seconds) * FPS)),
"preserve_final_frame": bool(preserve_final_frame),
"chunks": chunks,
}
return validate_assembly_plan(result)
def validate_assembly_plan(plan: Any) -> dict[str, Any]:
if not isinstance(plan, dict) or plan.get("magic") != ASSEMBLY_PLAN_MAGIC:
raise AssemblyPlanError("invalid H3 Continuum V3 assembly plan")
if (
type(plan.get("schema_version")) is not int
or plan["schema_version"] != ASSEMBLY_PLAN_SCHEMA_VERSION
):
raise AssemblyPlanError(
f"unsupported assembly plan schema {plan.get('schema_version')!r}"
)
if int(plan.get("fps", 0)) != FPS:
raise AssemblyPlanError("assembly plan FPS must be 24")
if int(plan.get("width", 0)) <= 0 or int(plan.get("height", 0)) <= 0:
raise AssemblyPlanError("assembly plan dimensions are invalid")
if float(plan.get("chunk_seconds", 0.0)) <= 0:
raise AssemblyPlanError("assembly plan chunk duration is invalid")
if int(plan.get("target_frames", 0)) <= 0:
raise AssemblyPlanError("assembly plan target frame count is invalid")
chunks = plan.get("chunks")
if not isinstance(chunks, list) or not chunks:
raise AssemblyPlanError("assembly plan contains no chunks")
for expected_index, chunk in enumerate(chunks, start=1):
if not isinstance(chunk, dict):
raise AssemblyPlanError(f"assembly chunk {expected_index} is invalid")
if int(chunk.get("sequence_index", 0)) != expected_index:
raise AssemblyPlanError("assembly chunk order is not contiguous")
total = int(chunk.get("total_frames", 0))
trim = int(chunk.get("trim_frames", -1))
net = int(chunk.get("net_frames", 0))
if total <= 0 or trim < 0 or net <= 0 or total - trim != net:
raise AssemblyPlanError(
f"assembly chunk {expected_index} frame plan is invalid"
)
if int(chunk.get("context_frames", -1)) < 0:
raise AssemblyPlanError(
f"assembly chunk {expected_index} context is invalid"
)
if int(chunk.get("expected_video_latent_t", 0)) <= 0:
raise AssemblyPlanError(
f"assembly chunk {expected_index} video latent length is invalid"
)
if int(chunk.get("expected_audio_latent_t", 0)) <= 0:
raise AssemblyPlanError(
f"assembly chunk {expected_index} audio latent length is invalid"
)
return plan
# V3.0.1 hardening integration: redundant metadata plus fail-closed validation.
from ..hardening import (
enrich_assembly_plan as _enrich_assembly_plan,
validate_assembly_plan_contract as _validate_assembly_plan_contract,
)
_make_assembly_plan_v300 = make_assembly_plan
_validate_assembly_plan_v300 = validate_assembly_plan
def validate_assembly_plan(plan):
result = _validate_assembly_plan_v300(plan)
_validate_assembly_plan_contract(plan)
return result
def make_assembly_plan(*args, **kwargs):
plan = _make_assembly_plan_v300(*args, **kwargs)
_enrich_assembly_plan(plan)
validate_assembly_plan(plan)
return plan
def _recombine_terminal_tensor(
first,
second,
*,
slices,
time_dim: int,
name: str,
):
"""Invert the terminal logical split without changing any tensor value."""
import torch
if not torch.is_tensor(first) or not torch.is_tensor(second):
raise ValueError(f"terminal {name} entries must be tensors")
if first.ndim != second.ndim:
raise ValueError(f"terminal {name} tensor ranks differ")
dim = int(time_dim)
if dim < 0:
dim += first.ndim
if dim < 0 or dim >= first.ndim:
raise ValueError(f"terminal {name} time dimension is invalid")
for axis, (left, right) in enumerate(zip(first.shape, second.shape)):
if axis != dim and int(left) != int(right):
raise ValueError(f"terminal {name} tensor geometry differs")
(first_start, first_stop), (second_start, second_stop) = slices
first_start = int(first_start)
first_stop = int(first_stop)
second_start = int(second_start)
second_stop = int(second_stop)
if first_start != 0 or second_start > first_stop or second_stop <= first_stop:
raise ValueError(f"terminal {name} split ranges do not form one physical unit")
if int(first.shape[dim]) != first_stop - first_start:
raise ValueError(f"terminal {name} first slice length is inconsistent")
if int(second.shape[dim]) != second_stop - second_start:
raise ValueError(f"terminal {name} second slice length is inconsistent")
overlap_start = max(first_start, second_start)
overlap_stop = min(first_stop, second_stop)
overlap_length = max(0, overlap_stop - overlap_start)
if overlap_length:
first_overlap = first.narrow(dim, overlap_start - first_start, overlap_length)
second_overlap = second.narrow(dim, overlap_start - second_start, overlap_length)
if not torch.equal(first_overlap, second_overlap):
raise ValueError(
f"terminal {name} overlap differs; refusing lossy physical reconstruction"
)
output_shape = list(first.shape)
output_shape[dim] = second_stop
output = first.new_empty(output_shape)
output.narrow(dim, first_start, first_stop - first_start).copy_(first)
output.narrow(dim, second_start, second_stop - second_start).copy_(second)
return output.contiguous()
def _terminal_physical_prompt(
prompts: list[str],
*,
@@ -284,20 +284,20 @@ def _attach_second_pass_contract(
def prepare_physical_decode_entries(
entries,
*,
chunk_seconds: float,
preserve_final_frame: bool,
terminal_merged: bool,
):
"""Return external-VAE decode units while preserving logical plan metadata."""
logical_entries = list(entries)
plan = make_assembly_plan(
logical_entries,
chunk_seconds=float(chunk_seconds),
preserve_final_frame=bool(preserve_final_frame),
)
entries,
*,
chunk_seconds: float,
preserve_final_frame: bool,
terminal_merged: bool,
):
"""Return external-VAE decode units while preserving logical plan metadata."""
logical_entries = list(entries)
plan = make_assembly_plan(
logical_entries,
chunk_seconds=float(chunk_seconds),
preserve_final_frame=bool(preserve_final_frame),
)
if not terminal_merged:
_attach_second_pass_contract(
plan,
@@ -306,75 +306,75 @@ def prepare_physical_decode_entries(
chunk_seconds=float(chunk_seconds),
)
return logical_entries, plan
if len(logical_entries) < 2:
raise ValueError("terminal physical decode requires two logical entries")
from ..v2.sequence import _terminal_pair_contract
initial_pair = len(logical_entries) == 2
contract = _terminal_pair_contract(
initial_pair=initial_pair,
chunk_seconds=float(chunk_seconds),
)
first_entry = logical_entries[-2]
second_entry = logical_entries[-1]
physical_video = _recombine_terminal_tensor(
first_entry["video"],
second_entry["video"],
slices=contract["video_slices"],
time_dim=2,
name="video",
)
physical_audio = _recombine_terminal_tensor(
first_entry["audio"],
second_entry["audio"],
slices=contract["audio_slices"],
time_dim=-1,
name="audio",
)
physical_entry = dict(first_entry)
physical_entry["video"] = physical_video
physical_entry["audio"] = physical_audio
decode_entries = [*logical_entries[:-2], physical_entry]
logical_chunks = list(plan["chunks"])
decode_groups = []
for chunk in logical_chunks[:-2]:
group = dict(chunk)
group["logical_chunk_indices"] = [int(chunk["chunk_index"])]
group["terminal_merged"] = False
decode_groups.append(group)
first_chunk = logical_chunks[-2]
second_chunk = logical_chunks[-1]
frame_start = int(first_chunk.get("frame_start", 0))
net_frames = int(contract["physical_frames"]) - int(
contract["physical_context_frames"]
)
terminal_group = dict(first_chunk)
terminal_group.update(
{
"total_frames": int(contract["physical_frames"]),
"trim_frames": int(contract["physical_context_frames"]),
"net_frames": net_frames,
"context_frames": int(contract["physical_context_frames"]),
"expected_video_latent_t": int(physical_video.shape[2]),
"expected_audio_latent_t": int(physical_audio.shape[-1]),
"frame_start": frame_start,
"frame_stop": frame_start + net_frames,
"logical_chunk_indices": [
int(first_chunk["chunk_index"]),
int(second_chunk["chunk_index"]),
],
"terminal_merged": True,
}
)
decode_groups.append(terminal_group)
plan = dict(plan)
plan["decode_group_version"] = 1
plan["logical_chunk_count"] = len(logical_chunks)
if len(logical_entries) < 2:
raise ValueError("terminal physical decode requires two logical entries")
from ..v2.sequence import _terminal_pair_contract
initial_pair = len(logical_entries) == 2
contract = _terminal_pair_contract(
initial_pair=initial_pair,
chunk_seconds=float(chunk_seconds),
)
first_entry = logical_entries[-2]
second_entry = logical_entries[-1]
physical_video = _recombine_terminal_tensor(
first_entry["video"],
second_entry["video"],
slices=contract["video_slices"],
time_dim=2,
name="video",
)
physical_audio = _recombine_terminal_tensor(
first_entry["audio"],
second_entry["audio"],
slices=contract["audio_slices"],
time_dim=-1,
name="audio",
)
physical_entry = dict(first_entry)
physical_entry["video"] = physical_video
physical_entry["audio"] = physical_audio
decode_entries = [*logical_entries[:-2], physical_entry]
logical_chunks = list(plan["chunks"])
decode_groups = []
for chunk in logical_chunks[:-2]:
group = dict(chunk)
group["logical_chunk_indices"] = [int(chunk["chunk_index"])]
group["terminal_merged"] = False
decode_groups.append(group)
first_chunk = logical_chunks[-2]
second_chunk = logical_chunks[-1]
frame_start = int(first_chunk.get("frame_start", 0))
net_frames = int(contract["physical_frames"]) - int(
contract["physical_context_frames"]
)
terminal_group = dict(first_chunk)
terminal_group.update(
{
"total_frames": int(contract["physical_frames"]),
"trim_frames": int(contract["physical_context_frames"]),
"net_frames": net_frames,
"context_frames": int(contract["physical_context_frames"]),
"expected_video_latent_t": int(physical_video.shape[2]),
"expected_audio_latent_t": int(physical_audio.shape[-1]),
"frame_start": frame_start,
"frame_stop": frame_start + net_frames,
"logical_chunk_indices": [
int(first_chunk["chunk_index"]),
int(second_chunk["chunk_index"]),
],
"terminal_merged": True,
}
)
decode_groups.append(terminal_group)
plan = dict(plan)
plan["decode_group_version"] = 1
plan["logical_chunk_count"] = len(logical_chunks)
plan["physical_decode_group_count"] = len(decode_groups)
plan["decode_groups"] = decode_groups
_attach_second_pass_contract(
+340
View File
@@ -0,0 +1,340 @@
"""Process-local, VAE-scoped cache for V3.8 reference encode tensors.
Only detached, contiguous CPU tensor copies are retained. The cache never
owns source images, video frames, audio waveforms, conditioning objects, or
sampling outputs.
"""
from __future__ import annotations
from collections import Counter, OrderedDict
from dataclasses import dataclass
import threading
from typing import Any, Callable
import weakref
import torch
REF_ENCODE_CACHE_VERSION = 1
DEFAULT_MAX_ENTRIES = 16
DEFAULT_MAX_BYTES = 512 * 1024 * 1024
@dataclass(frozen=True, slots=True)
class RefEncodeCacheKey:
kind: str
preprocess_version: int
identity: str
cache_version: int = REF_ENCODE_CACHE_VERSION
@dataclass(frozen=True, slots=True)
class RefEncodeCacheEvent:
kind: str
action: str
reason: str = ""
payload_bytes: int = 0
@dataclass(slots=True)
class _CacheEntry:
tensor: torch.Tensor
payload_bytes: int
last_used: int
CacheEventSink = Callable[[RefEncodeCacheEvent], None]
def make_ref_encode_cache_key(
kind: str,
preprocess_version: int,
identity: str,
) -> RefEncodeCacheKey:
return RefEncodeCacheKey(
kind=str(kind),
preprocess_version=int(preprocess_version),
identity=str(identity),
)
class RefEncodeCache:
"""Small process-local LRU split into weak VAE object namespaces."""
def __init__(
self,
*,
max_entries: int = DEFAULT_MAX_ENTRIES,
max_bytes: int = DEFAULT_MAX_BYTES,
) -> None:
if int(max_entries) < 1:
raise ValueError("max_entries must be positive")
if int(max_bytes) < 1:
raise ValueError("max_bytes must be positive")
self.max_entries = int(max_entries)
self.max_bytes = int(max_bytes)
self._lock = threading.RLock()
self._namespaces: weakref.WeakKeyDictionary[
Any, OrderedDict[RefEncodeCacheKey, _CacheEntry]
] = weakref.WeakKeyDictionary()
self._clock = 0
self._stats: Counter[str] = Counter()
self._kind_stats: dict[str, Counter[str]] = {}
@staticmethod
def _vae_cacheable(vae: Any) -> bool:
try:
weakref.ref(vae)
hash(vae)
except TypeError:
return False
return True
def supports_vae(self, vae: Any) -> bool:
return self._vae_cacheable(vae)
def _next_clock_locked(self) -> int:
self._clock += 1
return self._clock
def _record_locked(
self,
*,
key: RefEncodeCacheKey,
action: str,
reason: str = "",
payload_bytes: int = 0,
) -> RefEncodeCacheEvent:
self._stats[str(action)] += 1
self._kind_stats.setdefault(key.kind, Counter())[str(action)] += 1
return RefEncodeCacheEvent(
kind=key.kind,
action=str(action),
reason=str(reason),
payload_bytes=int(payload_bytes),
)
@staticmethod
def _emit(event: RefEncodeCacheEvent, sink: CacheEventSink | None) -> None:
if sink is not None:
sink(event)
def _resident_locked(self) -> tuple[int, int]:
entries = 0
payload_bytes = 0
for namespace in list(self._namespaces.values()):
entries += len(namespace)
payload_bytes += sum(entry.payload_bytes for entry in namespace.values())
return entries, payload_bytes
def _evict_locked(self) -> None:
while True:
entries, payload_bytes = self._resident_locked()
if entries <= self.max_entries and payload_bytes <= self.max_bytes:
return
oldest_namespace = None
oldest_key = None
oldest_clock = None
for namespace in list(self._namespaces.values()):
for key, entry in namespace.items():
if oldest_clock is None or entry.last_used < oldest_clock:
oldest_namespace = namespace
oldest_key = key
oldest_clock = entry.last_used
if oldest_namespace is None or oldest_key is None:
return
oldest_namespace.pop(oldest_key, None)
self._stats["evictions"] += 1
def lookup(
self,
vae: Any,
key: RefEncodeCacheKey,
*,
event_sink: CacheEventSink | None = None,
) -> torch.Tensor | None:
if not self._vae_cacheable(vae):
with self._lock:
event = self._record_locked(
key=key,
action="bypass",
reason="vae_not_weakrefable_or_hashable",
)
self._emit(event, event_sink)
return None
master = None
with self._lock:
namespace = self._namespaces.get(vae)
entry = namespace.get(key) if namespace is not None else None
if entry is None:
event = self._record_locked(key=key, action="miss")
else:
entry.last_used = self._next_clock_locked()
namespace.move_to_end(key)
master = entry.tensor
event = self._record_locked(
key=key,
action="hit",
payload_bytes=entry.payload_bytes,
)
self._emit(event, event_sink)
return None if master is None else master.clone()
def store(
self,
vae: Any,
key: RefEncodeCacheKey,
tensor: Any,
*,
event_sink: CacheEventSink | None = None,
) -> bool:
if not self._vae_cacheable(vae):
with self._lock:
event = self._record_locked(
key=key,
action="bypass",
reason="vae_not_weakrefable_or_hashable",
)
self._emit(event, event_sink)
return False
if not torch.is_tensor(tensor):
with self._lock:
event = self._record_locked(
key=key,
action="bypass",
reason="payload_not_tensor",
)
self._emit(event, event_sink)
return False
if tensor.device.type != "cpu":
with self._lock:
event = self._record_locked(
key=key,
action="bypass",
reason="payload_not_cpu",
)
self._emit(event, event_sink)
return False
payload_bytes = int(tensor.numel()) * int(tensor.element_size())
if payload_bytes > self.max_bytes:
with self._lock:
event = self._record_locked(
key=key,
action="bypass",
reason="entry_exceeds_byte_limit",
payload_bytes=payload_bytes,
)
self._emit(event, event_sink)
return False
try:
master = tensor.detach().contiguous().clone()
except Exception:
with self._lock:
event = self._record_locked(
key=key,
action="bypass",
reason="payload_copy_failed",
payload_bytes=payload_bytes,
)
self._emit(event, event_sink)
return False
with self._lock:
namespace = self._namespaces.get(vae)
if namespace is None:
namespace = OrderedDict()
self._namespaces[vae] = namespace
namespace[key] = _CacheEntry(
tensor=master,
payload_bytes=payload_bytes,
last_used=self._next_clock_locked(),
)
namespace.move_to_end(key)
self._evict_locked()
event = self._record_locked(
key=key,
action="store",
payload_bytes=payload_bytes,
)
self._emit(event, event_sink)
return True
def clear(self) -> None:
with self._lock:
self._namespaces = weakref.WeakKeyDictionary()
self._clock = 0
self._stats.clear()
self._kind_stats.clear()
def inspect(self) -> dict[str, Any]:
with self._lock:
entries, payload_bytes = self._resident_locked()
return {
"cache_version": REF_ENCODE_CACHE_VERSION,
"resident_entries": entries,
"resident_bytes": payload_bytes,
"max_entries": self.max_entries,
"max_bytes": self.max_bytes,
"stats": dict(self._stats),
"kind_stats": {
kind: dict(values)
for kind, values in sorted(self._kind_stats.items())
},
"vae_namespaces": len(self._namespaces),
}
_REF_ENCODE_CACHE = RefEncodeCache()
def get_ref_encode_cache() -> RefEncodeCache:
return _REF_ENCODE_CACHE
def clear_ref_encode_cache() -> None:
_REF_ENCODE_CACHE.clear()
def inspect_ref_encode_cache() -> dict[str, Any]:
return _REF_ENCODE_CACHE.inspect()
def format_ref_encode_cache_diagnostics(
events: list[RefEncodeCacheEvent] | tuple[RefEncodeCacheEvent, ...],
) -> str:
if not events:
return ""
labels = {
"reference_image": "image",
"video_guide": "video",
"reference_audio": "audio",
}
by_kind: dict[str, Counter[str]] = {}
totals: Counter[str] = Counter()
for event in events:
by_kind.setdefault(event.kind, Counter())[event.action] += 1
totals[event.action] += 1
components = []
for kind in ("reference_image", "video_guide", "reference_audio"):
values = by_kind.get(kind)
if not values:
continue
components.append(
f"{labels[kind]} hit={values['hit']}/miss={values['miss']}"
f"/store={values['store']}/bypass={values['bypass']}"
)
state = inspect_ref_encode_cache()
resident_mib = int(state["resident_bytes"]) / float(1024**2)
limit_mib = int(state["max_bytes"]) / float(1024**2)
components.append(
"total "
f"hits={totals['hit']}, misses={totals['miss']}, "
f"stores={totals['store']}, bypasses={totals['bypass']}"
)
components.append(
f"resident={resident_mib:.1f} MiB/{limit_mib:.1f} MiB "
f"({int(state['resident_entries'])}/{int(state['max_entries'])} entries)"
)
return "Reference encode cache: " + "; ".join(components) + "."
+282
View File
@@ -0,0 +1,282 @@
"""Persistent MiniMax H3 video-reference conditioning for the V3.4 sampler."""
from __future__ import annotations
from dataclasses import dataclass
import hashlib
import json
import math
from typing import Any
import torch
from .temporal import align_frame_count_up
REFERENCE_VIDEO_CONTRACT_VERSION = 1
REFERENCE_VIDEO_PREPROCESS_VERSION = 3
REFERENCE_VIDEO_SIZE_EFFICIENT = "Efficient - 0.4 MP"
REFERENCE_VIDEO_SIZE_BALANCED = "Balanced - 0.6 MP"
REFERENCE_VIDEO_SIZE_MATCH_OUTPUT = "Match Output"
REFERENCE_VIDEO_SIZE_OPTIONS = (
REFERENCE_VIDEO_SIZE_EFFICIENT,
REFERENCE_VIDEO_SIZE_BALANCED,
REFERENCE_VIDEO_SIZE_MATCH_OUTPUT,
)
_CANVAS_MULTIPLE = 32
_EFFICIENT_AREA = 400_000
_BALANCED_AREA = 600_000
_SOURCE_FPS = 24
class ReferenceVideoError(ValueError):
pass
def _canonical_hash(value: Any) -> str:
payload = json.dumps(
value, sort_keys=True, separators=(",", ":"), ensure_ascii=True
).encode("utf-8")
return hashlib.sha256(payload).hexdigest()
def _tensor_hash(value: torch.Tensor) -> str:
tensor = value.detach().to(device="cpu").contiguous()
digest = hashlib.sha256()
digest.update(str(tuple(int(v) for v in tensor.shape)).encode("ascii"))
digest.update(str(tensor.dtype).encode("ascii"))
digest.update(tensor.numpy().tobytes(order="C"))
return digest.hexdigest()
def _round_canvas(value: float) -> int:
return max(
_CANVAS_MULTIPLE,
int(round(float(value) / _CANVAS_MULTIPLE)) * _CANVAS_MULTIPLE,
)
def _resolved_size(
source_width: int,
source_height: int,
*,
output_width: int,
output_height: int,
size_mode: str,
) -> tuple[int, int]:
if size_mode == REFERENCE_VIDEO_SIZE_MATCH_OUTPUT:
target_area = int(output_width) * int(output_height)
elif size_mode == REFERENCE_VIDEO_SIZE_BALANCED:
target_area = _BALANCED_AREA
else:
target_area = _EFFICIENT_AREA
source_area = int(source_width) * int(source_height)
scale = min(1.0, math.sqrt(float(target_area) / float(source_area)))
target_width = _round_canvas(int(source_width) * scale)
target_height = _round_canvas(int(source_height) * scale)
if source_width >= _CANVAS_MULTIPLE:
target_width = min(
target_width,
max(_CANVAS_MULTIPLE, (int(source_width) // _CANVAS_MULTIPLE) * _CANVAS_MULTIPLE),
)
if source_height >= _CANVAS_MULTIPLE:
target_height = min(
target_height,
max(_CANVAS_MULTIPLE, (int(source_height) // _CANVAS_MULTIPLE) * _CANVAS_MULTIPLE),
)
return target_width, target_height
@dataclass(frozen=True)
class ReferenceVideoSource:
frames: torch.Tensor
source_shape: tuple[int, ...]
source_dtype: str
source_sha256: str
size_mode: str
target_width: int
target_height: int
frame_count: int
combined_hash: str
@property
def contract(self) -> dict[str, Any]:
return {
"reference_video_contract_version": REFERENCE_VIDEO_CONTRACT_VERSION,
"source_shape": list(self.source_shape),
"source_dtype": self.source_dtype,
"source_sha256": self.source_sha256,
"source_fps": _SOURCE_FPS,
"size_mode": self.size_mode,
"target_width": self.target_width,
"target_height": self.target_height,
"frame_count": self.frame_count,
"preprocess_version": REFERENCE_VIDEO_PREPROCESS_VERSION,
"combined_hash": self.combined_hash,
}
@dataclass(frozen=True)
class ReferenceVideoAssets:
source: ReferenceVideoSource
item: dict[str, Any]
block: dict[str, Any]
def _resolve_reference_frame_count(source_frames: int, target_frames: int) -> int:
source_count = int(source_frames)
target_count = int(target_frames)
if source_count < 5 or target_count < 5:
raise ReferenceVideoError("Video Reference requires at least 5 frames")
target_cap = align_frame_count_up(target_count)
available_count = min(source_count, target_cap)
return min(align_frame_count_up(available_count), target_cap)
def _fit_reference_frames(frames: torch.Tensor, frame_count: int) -> torch.Tensor:
requested_count = int(frame_count)
current_count = int(frames.shape[0])
if current_count >= requested_count:
return frames[:requested_count].contiguous()
if current_count < 1:
raise ReferenceVideoError("Video Reference contains no frames")
padding = frames[-1:].expand(requested_count - current_count, -1, -1, -1)
return torch.cat((frames, padding), dim=0).contiguous()
def prepare_reference_video_source(
reference_video_1: Any,
*,
target_frames: int,
output_width: int,
output_height: int,
size_mode: str = REFERENCE_VIDEO_SIZE_EFFICIENT,
) -> ReferenceVideoSource | None:
if reference_video_1 is None:
return None
if not torch.is_tensor(reference_video_1) or reference_video_1.ndim != 4:
raise ReferenceVideoError(
"Video Reference must be a ComfyUI IMAGE batch with shape [T, H, W, C]"
)
if int(reference_video_1.shape[-1]) < 3:
raise ReferenceVideoError("Video Reference must contain RGB channels")
frames = reference_video_1[:, :, :, :3].detach().to(
device="cpu", dtype=torch.float32
).contiguous()
if not bool(torch.isfinite(frames).all().item()):
raise ReferenceVideoError("Video Reference contains NaN or infinity")
source_shape = tuple(int(value) for value in frames.shape)
source_sha256 = _tensor_hash(frames)
frame_count = _resolve_reference_frame_count(
int(frames.shape[0]),
int(target_frames),
)
normalized_size_mode = (
str(size_mode)
if str(size_mode) in REFERENCE_VIDEO_SIZE_OPTIONS
else REFERENCE_VIDEO_SIZE_EFFICIENT
)
target_width, target_height = _resolved_size(
int(frames.shape[2]),
int(frames.shape[1]),
output_width=int(output_width),
output_height=int(output_height),
size_mode=normalized_size_mode,
)
contract_base = {
"reference_video_contract_version": REFERENCE_VIDEO_CONTRACT_VERSION,
"source_shape": list(source_shape),
"source_dtype": str(frames.dtype),
"source_sha256": source_sha256,
"source_fps": _SOURCE_FPS,
"size_mode": normalized_size_mode,
"target_width": target_width,
"target_height": target_height,
"frame_count": frame_count,
"preprocess_version": REFERENCE_VIDEO_PREPROCESS_VERSION,
}
return ReferenceVideoSource(
frames=frames,
source_shape=source_shape,
source_dtype=str(frames.dtype),
source_sha256=source_sha256,
size_mode=normalized_size_mode,
target_width=target_width,
target_height=target_height,
frame_count=frame_count,
combined_hash=_canonical_hash(contract_base),
)
def encode_reference_video(
video_vae: Any,
source: ReferenceVideoSource,
) -> ReferenceVideoAssets:
available_count = min(int(source.frames.shape[0]), int(source.frame_count))
frames = source.frames[:available_count]
if (
int(frames.shape[2]) != source.target_width
or int(frames.shape[1]) != source.target_height
):
try:
import comfy.utils
except Exception as exc:
raise ReferenceVideoError(
"ComfyUI Core image resize support is unavailable"
) from exc
frames = comfy.utils.common_upscale(
frames.movedim(-1, 1),
source.target_width,
source.target_height,
"lanczos",
"disabled",
).movedim(1, -1).contiguous()
frames = _fit_reference_frames(frames, source.frame_count)
try:
latent = video_vae.encode(frames).detach().to("cpu").contiguous()
except Exception as exc:
raise ReferenceVideoError("Video Reference VAE Encode failed") from exc
qwen_frames = frames[::_SOURCE_FPS // 2].contiguous()
item = {
"type": "video",
"data": qwen_frames,
"timestamps": [index / 2.0 for index in range(int(qwen_frames.shape[0]))],
}
block = {
"kind": "video",
"latent_t": int(latent.shape[2]),
"latent_h": source.target_height // 16,
"latent_w": source.target_width // 16,
"ref_audio_t": 0,
"latent": latent,
"audio_latent": None,
}
return ReferenceVideoAssets(source=source, item=item, block=block)
def combine_reference_video_identity(
visual_identity_hash: str,
source: ReferenceVideoSource | None,
) -> str:
if source is None:
return str(visual_identity_hash)
return _canonical_hash(
{
"reference_video_identity_version": 1,
"visual_identity_hash": str(visual_identity_hash),
"reference_video_hash": source.combined_hash,
}
)
def validate_reference_video_prompts(
prompts: list[str], source: ReferenceVideoSource | None
) -> str:
if source is None or any("<Video 1>" in str(prompt) for prompt in prompts):
return ""
return (
"H3C-P103 Warning: Video Reference is connected but the prompt contains no "
"<Video 1> tag; video still conditions generation, but an explicit tag is "
"recommended."
)
+179
View File
@@ -0,0 +1,179 @@
"""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"]),
}
+206
View File
@@ -0,0 +1,206 @@
"""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
+421
View File
@@ -0,0 +1,421 @@
"""Pure visible-timeline resolution for Experimental temporal refinement."""
from __future__ import annotations
import hashlib
import json
import math
from collections.abc import Mapping, Sequence
from dataclasses import dataclass
from types import MappingProxyType
from typing import Any
from ..temporal import audio_latent_t, latent_slot_offsets, pixel_frames_for_latent_t
MAGIC = "H3_CONTINUUM_REFINE_WINDOW"
SCHEMA_VERSION = 1
MODE_TIME_WINDOW = "time_window"
class RefineWindowError(ValueError):
"""Raised before preparation when a visible time window is invalid."""
@dataclass(frozen=True)
class GroupTemporalWindow:
"""One physical group's immutable temporal mask ranges."""
group_index: int
logical_chunks: tuple[int, ...]
terminal_merged: bool
visible_frame_ranges: tuple[tuple[int, int], ...]
physical_frame_ranges: tuple[tuple[int, int], ...]
video_slot_ranges: tuple[tuple[int, int], ...]
audio_tick_ranges: tuple[tuple[int, int], ...]
@dataclass(frozen=True)
class RefineWindow:
"""One versioned visible-output window with no Tensor or runtime object."""
selected_group_indices: tuple[int, ...]
groups: tuple[GroupTemporalWindow, ...]
contract: Mapping[str, Any]
def group(self, group_index: int) -> GroupTemporalWindow | None:
for group in self.groups:
if group.group_index == int(group_index):
return group
return None
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 _merge_ranges(values: Sequence[tuple[int, int]]) -> tuple[tuple[int, int], ...]:
ordered = sorted(
(int(start), int(stop))
for start, stop in values
if int(stop) > int(start)
)
merged: list[list[int]] = []
for start, stop in ordered:
if merged and start <= merged[-1][1]:
merged[-1][1] = max(merged[-1][1], stop)
else:
merged.append([start, stop])
return tuple((start, stop) for start, stop in merged)
def _indices_to_ranges(indices: Sequence[int]) -> tuple[tuple[int, int], ...]:
ordered = sorted(set(int(value) for value in indices))
if not ordered:
return ()
ranges: list[tuple[int, int]] = []
start = previous = ordered[0]
for value in ordered[1:]:
if value == previous + 1:
previous = value
continue
ranges.append((start, previous + 1))
start = previous = value
ranges.append((start, previous + 1))
return tuple(ranges)
def _overlaps(
start: int,
stop: int,
ranges: Sequence[tuple[int, int]],
) -> bool:
return any(start < range_stop and stop > range_start for range_start, range_stop in ranges)
def _contract_groups(assembly_plan: Mapping[str, Any]) -> list[Mapping[str, Any]]:
if not isinstance(assembly_plan, Mapping):
raise RefineWindowError("assembly_plan must be a mapping")
contract = assembly_plan.get("second_pass_contract")
if not isinstance(contract, Mapping) or contract.get("version") != 1:
raise RefineWindowError("assembly_plan has no Second Pass contract version 1")
groups = contract.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 RefineWindowError("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 RefineWindowError(
f"physical group {group_index + 1} has invalid logical chunk identity"
)
chunks = tuple(int(value) for value in values)
if tuple(sorted(chunks)) != chunks or len(set(chunks)) != len(chunks):
raise RefineWindowError(
f"physical group {group_index + 1} logical chunks are not ordered and unique"
)
return chunks
def _visible_units(
assembly_plan: Mapping[str, Any],
groups: Sequence[Mapping[str, Any]],
) -> tuple[list[dict[str, int]], int]:
decode_groups = assembly_plan.get("decode_groups")
if isinstance(decode_groups, Sequence) and not isinstance(
decode_groups, (str, bytes)
):
if len(decode_groups) != len(groups) or not all(
isinstance(group, Mapping) for group in decode_groups
):
raise RefineWindowError(
"assembly_plan decode groups differ from Second Pass physical groups"
)
source_units: Sequence[Mapping[str, Any]] = decode_groups
else:
source_units = groups
cursor = 0
units: list[dict[str, int]] = []
for group_index, (group, source) in enumerate(zip(groups, source_units, strict=True)):
physical_frames = int(group.get("physical_frames", 0))
trim_frames = int(group.get("trim_prefix_frames", -1))
source_latent_t = int(group.get("source_latent_t", 0))
audio_shape = group.get("source_audio_shape")
if physical_frames <= 0 or trim_frames < 0 or trim_frames >= physical_frames:
raise RefineWindowError(
f"physical group {group_index + 1} frame geometry is invalid"
)
if source_latent_t <= 0 or pixel_frames_for_latent_t(source_latent_t) != physical_frames:
raise RefineWindowError(
f"physical group {group_index + 1} Video latent T differs from its frame grid"
)
if (
not isinstance(audio_shape, Sequence)
or isinstance(audio_shape, (str, bytes))
or len(audio_shape) != 4
or int(audio_shape[-1]) != audio_latent_t(physical_frames)
):
raise RefineWindowError(
f"physical group {group_index + 1} Audio latent T differs from its frame grid"
)
net_frames = physical_frames - trim_frames
source_total = int(source.get("total_frames", physical_frames))
source_trim = int(source.get("trim_frames", trim_frames))
source_net = int(source.get("net_frames", source_total - source_trim))
source_start = int(source.get("frame_start", cursor))
source_stop = int(source.get("frame_stop", source_start + source_net))
if (
source_total != physical_frames
or source_trim != trim_frames
or source_net != net_frames
or source_start != cursor
or source_stop != cursor + net_frames
):
raise RefineWindowError(
f"physical group {group_index + 1} visible range is inconsistent"
)
units.append(
{
"group_index": group_index,
"visible_start": source_start,
"visible_stop": source_stop,
"physical_frames": physical_frames,
"trim_frames": trim_frames,
"video_t": source_latent_t,
"audio_t": int(audio_shape[-1]),
}
)
cursor = source_stop
return units, cursor
def _output_to_natural_ranges(
output_start: int,
output_stop: int,
*,
natural_frames: int,
target_frames: int,
preserve_final_frame: bool,
) -> tuple[tuple[int, int], ...]:
mappings: list[tuple[int, int, int, bool]] = []
if target_frames >= natural_frames:
mappings.append((0, natural_frames, 0, False))
if target_frames > natural_frames:
mappings.append((natural_frames, target_frames, natural_frames - 1, True))
elif preserve_final_frame and target_frames >= 2:
mappings.extend(
(
(0, target_frames - 1, 0, False),
(target_frames - 1, target_frames, natural_frames - 1, True),
)
)
else:
mappings.append((0, target_frames, 0, False))
natural_ranges: list[tuple[int, int]] = []
for destination_start, destination_stop, source_start, repeated in mappings:
overlap_start = max(output_start, destination_start)
overlap_stop = min(output_stop, destination_stop)
if overlap_stop <= overlap_start:
continue
if repeated:
natural_ranges.append((source_start, source_start + 1))
else:
mapped_start = source_start + overlap_start - destination_start
mapped_stop = source_start + overlap_stop - destination_start
natural_ranges.append((mapped_start, mapped_stop))
return _merge_ranges(natural_ranges)
def _group_window(
group: Mapping[str, Any],
unit: Mapping[str, int],
natural_ranges: Sequence[tuple[int, int]],
) -> GroupTemporalWindow | None:
visible_start = int(unit["visible_start"])
visible_stop = int(unit["visible_stop"])
visible_ranges = _merge_ranges(
(
max(start, visible_start),
min(stop, visible_stop),
)
for start, stop in natural_ranges
if start < visible_stop and stop > visible_start
)
if not visible_ranges:
return None
trim_frames = int(unit["trim_frames"])
physical_ranges = _merge_ranges(
(
trim_frames + start - visible_start,
trim_frames + stop - visible_start,
)
for start, stop in visible_ranges
)
video_t = int(unit["video_t"])
offsets = latent_slot_offsets(video_t)
selected_slots = []
for slot, slot_start in enumerate(offsets):
slot_stop = offsets[slot + 1] if slot + 1 < video_t else int(unit["physical_frames"])
if _overlaps(slot_start, slot_stop, physical_ranges):
selected_slots.append(slot)
video_ranges = _indices_to_ranges(selected_slots)
if video_ranges and offsets[video_ranges[0][0]] < trim_frames:
raise RefineWindowError(
f"physical group {int(unit['group_index']) + 1} Video grid would expose "
"the protected continuation prefix"
)
audio_ranges = _merge_ranges(
(
max(0, min(int(unit["audio_t"]), audio_latent_t(start))),
max(0, min(int(unit["audio_t"]), audio_latent_t(stop))),
)
for start, stop in physical_ranges
)
protected_audio_stop = audio_latent_t(trim_frames)
if audio_ranges and audio_ranges[0][0] < protected_audio_stop:
raise RefineWindowError(
f"physical group {int(unit['group_index']) + 1} Audio grid would expose "
"the protected continuation prefix"
)
if not video_ranges or not audio_ranges:
raise RefineWindowError(
f"physical group {int(unit['group_index']) + 1} window resolves to an empty AV grid"
)
return GroupTemporalWindow(
group_index=int(unit["group_index"]),
logical_chunks=_logical_chunks(group, int(unit["group_index"])),
terminal_merged=bool(group.get("terminal_merged", False)),
visible_frame_ranges=visible_ranges,
physical_frame_ranges=physical_ranges,
video_slot_ranges=video_ranges,
audio_tick_ranges=audio_ranges,
)
def resolve_refine_window(
start_sec: float,
end_sec: float,
assembly_plan: Mapping[str, Any],
) -> RefineWindow:
"""Resolve final visible output time to protected physical AV ranges.
The requested interval is half-open. Fractions select every output frame
interval they overlap. Continuation trim prefixes are never selected.
"""
try:
requested_start = float(start_sec)
requested_end = float(end_sec)
except (TypeError, ValueError) as exc:
raise RefineWindowError("refine window seconds must be numeric") from exc
if not math.isfinite(requested_start) or not math.isfinite(requested_end):
raise RefineWindowError("refine window seconds must be finite")
if requested_start >= requested_end:
raise RefineWindowError("refine window start must be less than end")
groups = _contract_groups(assembly_plan)
units, natural_frames = _visible_units(assembly_plan, groups)
fps = int(assembly_plan.get("fps", 0))
target_frames = int(assembly_plan.get("target_frames", 0))
if fps <= 0 or target_frames <= 0 or natural_frames <= 0:
raise RefineWindowError("assembly_plan visible timeline is invalid")
clamped_start = min(max(requested_start, 0.0), target_frames / fps)
clamped_end = min(max(requested_end, 0.0), target_frames / fps)
output_start = max(0, min(target_frames, math.floor(clamped_start * fps + 1e-9)))
output_stop = max(0, min(target_frames, math.ceil(clamped_end * fps - 1e-9)))
if output_stop <= output_start:
raise RefineWindowError("refine window does not overlap the visible output")
natural_ranges = _output_to_natural_ranges(
output_start,
output_stop,
natural_frames=natural_frames,
target_frames=target_frames,
preserve_final_frame=bool(assembly_plan.get("preserve_final_frame", False)),
)
if not natural_ranges:
raise RefineWindowError("refine window has no natural timeline source")
resolved_groups = tuple(
group_window
for group, unit in zip(groups, units, strict=True)
if (
group_window := _group_window(
group,
unit,
natural_ranges,
)
)
is not None
)
if not resolved_groups:
raise RefineWindowError("refine window selects no physical group")
selected = tuple(group.group_index for group in resolved_groups)
group_contracts = [
{
"group_index": group.group_index,
"physical_group": group.group_index + 1,
"logical_chunks": list(group.logical_chunks),
"terminal_merged": group.terminal_merged,
"visible_frame_ranges": [list(value) for value in group.visible_frame_ranges],
"physical_frame_ranges": [list(value) for value in group.physical_frame_ranges],
"video_slot_ranges": [list(value) for value in group.video_slot_ranges],
"audio_tick_ranges": [list(value) for value in group.audio_tick_ranges],
}
for group in resolved_groups
]
contract: dict[str, Any] = {
"magic": MAGIC,
"schema_version": SCHEMA_VERSION,
"mode": MODE_TIME_WINDOW,
"timeline": "final_visible_output",
"interval": "half_open",
"requested_start_sec": requested_start,
"requested_end_sec": requested_end,
"effective_start_sec": output_start / fps,
"effective_end_sec": output_stop / fps,
"output_frame_range": [output_start, output_stop],
"target_frames": target_frames,
"natural_frames": natural_frames,
"natural_frame_ranges": [list(value) for value in natural_ranges],
"selected_physical_groups": [index + 1 for index in selected],
"groups": group_contracts,
"continuation_prefix_policy": "always_protected",
"outside_window_policy": "mask_zero_then_bit_exact_restore",
"physical_group_atomicity": "preserved",
"temporal_quantization": "intersecting_video_slots_and_audio_ticks",
}
contract["window_hash"] = _identity(contract)
return RefineWindow(
selected_group_indices=selected,
groups=resolved_groups,
contract=MappingProxyType(contract),
)
def serializable_window_contract(window: RefineWindow) -> dict[str, Any]:
if not isinstance(window, RefineWindow):
raise RefineWindowError("refine_window must be a RefineWindow")
return json.loads(json.dumps(dict(window.contract)))
+920
View File
@@ -0,0 +1,920 @@
"""Read-only V3.8 reliability diagnostics.
The helpers in this module inspect shapes and existing metadata only. They do
not resize, encode, hash, copy, or otherwise modify user tensors.
"""
from __future__ import annotations
from collections.abc import Callable, Mapping, Sequence
from dataclasses import dataclass
from typing import Any
import torch
from ..compatibility import check_comfy_h3_runtime
from ..constants import (
DIAGNOSTICS_BASIC,
DIAGNOSTICS_FULL,
DIAGNOSTICS_OFF,
FPS,
normalize_diagnostics_mode,
)
from ..reference import resolve_reference_image_size
from ..reference_video import (
REFERENCE_VIDEO_SIZE_EFFICIENT,
resolve_reference_video_frame_count,
resolve_reference_video_size,
)
from ..temporal import (
align_frame_count_up,
audio_grid_offset,
audio_latent_t,
context_slots,
is_valid_frame_count,
video_latent_t,
)
VISUAL_LOAD_LOW_MAX = 0.75
VISUAL_LOAD_MEDIUM_MAX = 1.75
@dataclass(frozen=True, slots=True)
class DiagnosticSection:
basic: tuple[str, ...] = ()
detailed: tuple[str, ...] = ()
@dataclass(frozen=True, slots=True)
class V38Diagnostics:
basic: tuple[str, ...]
detailed: tuple[str, ...]
def _combine_sections(*sections: DiagnosticSection) -> V38Diagnostics:
return V38Diagnostics(
basic=tuple(line for section in sections for line in section.basic),
detailed=tuple(line for section in sections for line in section.detailed),
)
def _physical_groups(assembly_plan: Any) -> list[Any]:
if not isinstance(assembly_plan, Mapping):
return []
decode_groups = assembly_plan.get("decode_groups")
if isinstance(decode_groups, list) and decode_groups:
return list(decode_groups)
chunks = assembly_plan.get("chunks")
return list(chunks) if isinstance(chunks, list) else []
def _latent_outputs(value: Any) -> list[Any]:
return list(value) if isinstance(value, (list, tuple)) else []
def _latent_samples(value: Any) -> Any:
return value.get("samples") if isinstance(value, Mapping) else None
def _image_geometry(value: Any) -> tuple[int, int]:
shape = getattr(value, "shape", None)
if shape is None or len(shape) != 4:
raise ValueError("IMAGE must have shape [B,H,W,C]")
height = int(shape[1])
width = int(shape[2])
if height < 1 or width < 1:
raise ValueError("IMAGE geometry must be positive")
return width, height
def _video_guide_geometry(value: Any) -> tuple[int, int, int]:
shape = getattr(value, "shape", None)
if shape is None or len(shape) != 4:
raise ValueError("Video Guide must have shape [T,H,W,C]")
frames = int(shape[0])
height = int(shape[1])
width = int(shape[2])
if frames < 1 or height < 1 or width < 1:
raise ValueError("Video Guide geometry must be positive")
return frames, width, height
def _native_chunk_frames(chunk_seconds: float) -> int:
return align_frame_count_up(int(round(float(chunk_seconds) * FPS)))
def build_frame_alignment_diagnostics(
*,
video_latents: Any,
assembly_plan: Any,
video_guide: Any = None,
chunk_seconds: float,
) -> DiagnosticSection:
"""Inspect Video Guide alignment and physical video latent lengths."""
basic: list[str] = []
detailed: list[str] = []
if video_guide is not None:
try:
source_frames, _source_width, _source_height = _video_guide_geometry(
video_guide
)
aligned_frames = resolve_reference_video_frame_count(
source_frames,
_native_chunk_frames(chunk_seconds),
)
if source_frames < aligned_frames:
action = "final-frame pad"
elif source_frames > aligned_frames:
action = "trimmed to one-chunk H3 limit"
else:
action = "unchanged"
line = (
f"Frame alignment: Video Guide {source_frames} -> {aligned_frames} "
f"({action}, H3 17k+5)."
)
if action != "unchanged":
basic.append(line)
detailed.append(line)
except Exception as exc:
line = (
"Frame alignment advisory: Video Guide alignment could not be "
f"inspected ({type(exc).__name__}: {exc})."
)
basic.append(line)
detailed.append(line)
groups = _physical_groups(assembly_plan)
outputs = _latent_outputs(video_latents)
if not groups:
line = "Frame alignment advisory: physical group metadata is unavailable."
basic.append(line)
detailed.append(line)
return DiagnosticSection(tuple(basic), tuple(detailed))
if len(outputs) != len(groups):
line = (
"Frame alignment advisory: physical video output count "
f"{len(outputs)} does not match group count {len(groups)}."
)
basic.append(line)
detailed.append(line)
for index, group in enumerate(groups, start=1):
problems: list[str] = []
try:
if not isinstance(group, Mapping):
raise ValueError("group metadata is not a mapping")
frames = int(group["total_frames"])
trim = int(group["trim_frames"])
net = int(group["net_frames"])
metadata_t = int(group["expected_video_latent_t"])
if not is_valid_frame_count(frames):
problems.append("frames are not on H3 17k+5")
expected_t = None
else:
expected_t = video_latent_t(frames)
if metadata_t != expected_t:
problems.append("metadata T differs from native grid")
if frames - trim != net:
problems.append("total-trim differs from net")
samples = (
_latent_samples(outputs[index - 1])
if index <= len(outputs)
else None
)
if not torch.is_tensor(samples) or samples.ndim < 3:
actual_t = None
problems.append("video LATENT samples are missing or invalid")
else:
actual_t = int(samples.shape[2])
if actual_t != metadata_t:
problems.append("actual T differs from metadata")
if expected_t is not None and actual_t != expected_t:
problems.append("actual T differs from native grid")
result = "PASS" if not problems else "ADVISORY"
expected_text = "n/a" if expected_t is None else str(expected_t)
actual_text = "n/a" if actual_t is None else str(actual_t)
detailed.append(
f"Frame grid: group={index} frames={frames} trim={trim} net={net} "
f"video_t={actual_text} metadata={metadata_t} "
f"expected={expected_text} {result}."
)
except Exception as exc:
problems.append(f"{type(exc).__name__}: {exc}")
detailed.append(
f"Frame grid: group={index} unavailable ADVISORY "
f"({problems[-1]})."
)
if problems:
basic.append(
f"Frame alignment advisory: group {index}: "
+ "; ".join(problems)
+ "."
)
return DiagnosticSection(tuple(basic), tuple(detailed))
def validate_audio_latent_lengths(
*,
audio_latents: Any,
assembly_plan: Any,
) -> DiagnosticSection:
"""Validate physical audio latent shapes without reading tensor values."""
basic: list[str] = []
detailed: list[str] = []
groups = _physical_groups(assembly_plan)
outputs = _latent_outputs(audio_latents)
if not groups:
line = "Audio latent advisory: physical group metadata is unavailable."
return DiagnosticSection((line,), (line,))
if len(outputs) != len(groups):
line = (
f"Audio latent advisory: physical output count {len(outputs)} "
f"does not match group count {len(groups)}."
)
basic.append(line)
detailed.append(line)
for index, group in enumerate(groups, start=1):
problems: list[str] = []
frames = metadata_t = nominal_t = actual_t = None
phase = None
try:
if not isinstance(group, Mapping):
raise ValueError("group metadata is not a mapping")
frames = int(group["total_frames"])
metadata_t = int(group["expected_audio_latent_t"])
nominal_t = audio_latent_t(frames)
samples = (
_latent_samples(outputs[index - 1])
if index <= len(outputs)
else None
)
if not torch.is_tensor(samples):
problems.append("LATENT samples are missing or not a Tensor")
elif samples.ndim != 4:
problems.append(f"rank is {samples.ndim}, expected 4")
else:
if int(samples.shape[0]) < 1:
problems.append("batch dimension is empty")
if int(samples.shape[1]) != 32:
problems.append(f"channels={int(samples.shape[1])}, expected 32")
if int(samples.shape[2]) != 2:
problems.append(f"stereo={int(samples.shape[2])}, expected 2")
actual_t = int(samples.shape[-1])
if actual_t <= 0:
problems.append("T must be positive")
else:
phase = audio_grid_offset(frames, actual_t)
if actual_t != metadata_t:
problems.append(
f"metadata={metadata_t} actual={actual_t} "
f"delta={actual_t - metadata_t}"
)
if not -0.500001 <= phase <= 0.500001:
problems.append(f"phase={phase:.6f} is outside [-0.5,0.5]")
result = "PASS" if not problems else "ADVISORY"
detailed.append(
f"Audio latent check: group={index} frames={frames} "
f"metadata={metadata_t} actual="
f"{'n/a' if actual_t is None else actual_t} nominal={nominal_t} "
f"phase={'n/a' if phase is None else f'{phase:.6f}'} {result}."
)
except Exception as exc:
problems.append(f"{type(exc).__name__}: {exc}")
detailed.append(
f"Audio latent check: group={index} unavailable ADVISORY "
f"({problems[-1]})."
)
if problems:
basic.append(
f"Audio latent advisory: group {index}: "
+ "; ".join(problems)
+ "."
)
return DiagnosticSection(tuple(basic), tuple(detailed))
def collect_core_compatibility_advisory(
checker: Callable[[], list[str]] | None = None,
) -> DiagnosticSection:
"""Collect the existing feature-based Core advisory after successful generation."""
active_checker = checker or check_comfy_h3_runtime
try:
issues = tuple(dict.fromkeys(str(issue) for issue in active_checker() if issue))
except Exception as exc:
basic = (
"Core compatibility advisory unavailable; generation result was preserved.",
)
detailed = (
basic[0][:-1] + f" ({type(exc).__name__}: {exc}).",
)
return DiagnosticSection(basic, detailed)
if not issues:
return DiagnosticSection(
(),
("Core compatibility: native MiniMax H3 contracts detected.",),
)
return DiagnosticSection(
(
"Core compatibility advisory: "
f"{len(issues)} native H3 contract difference(s) detected; "
"generation completed; enable Detailed Report for details.",
),
tuple(f"Core compatibility advisory: {issue}." for issue in issues),
)
def _visual_load_class(total: float) -> str:
if total < VISUAL_LOAD_LOW_MAX:
return "Low"
if total < VISUAL_LOAD_MEDIUM_MAX:
return "Medium"
return "High"
def estimate_visual_conditioning_load(
*,
output_width: int,
output_height: int,
reference_images: Sequence[Any],
reference_size: str,
video_guide: Any,
video_guide_size: str = REFERENCE_VIDEO_SIZE_EFFICIENT,
chunk_seconds: float,
still_guide_active: bool,
) -> DiagnosticSection:
"""Estimate peak per-group relative visual conditioning from geometry only."""
output_area = int(output_width) * int(output_height)
if output_area <= 0:
line = "Visual conditioning load advisory: output geometry is invalid."
return DiagnosticSection((line,), (line,))
components: list[tuple[str, float]] = []
problems: list[str] = []
for socket_index, image in enumerate(reference_images, start=1):
if image is None:
continue
try:
source_width, source_height = _image_geometry(image)
target_width, target_height = resolve_reference_image_size(
source_width,
source_height,
output_width=int(output_width),
output_height=int(output_height),
size_mode=str(reference_size),
)
load = (target_width * target_height) / float(output_area)
components.append(
(f"Ref{socket_index}={target_width}x{target_height}", load)
)
except Exception as exc:
problems.append(
f"Reference Image {socket_index} unavailable "
f"({type(exc).__name__}: {exc})"
)
if video_guide is not None:
try:
source_frames, source_width, source_height = _video_guide_geometry(
video_guide
)
native_frames = _native_chunk_frames(chunk_seconds)
aligned_frames = resolve_reference_video_frame_count(
source_frames,
native_frames,
)
target_width, target_height = resolve_reference_video_size(
source_width,
source_height,
output_width=int(output_width),
output_height=int(output_height),
size_mode=str(video_guide_size),
)
spatial_ratio = (target_width * target_height) / float(output_area)
temporal_ratio = video_latent_t(aligned_frames) / float(
video_latent_t(native_frames)
)
components.append(
(
f"Video Guide={target_width}x{target_height}/{aligned_frames}f",
spatial_ratio * temporal_ratio,
)
)
except Exception as exc:
problems.append(
f"Video Guide unavailable ({type(exc).__name__}: {exc})"
)
basic: list[str] = []
detailed: list[str] = []
if components:
total = sum(load for _name, load in components)
classification = _visual_load_class(total)
basic_line = (
f"Visual conditioning load: {classification} "
"(peak per physical group)."
)
if still_guide_active:
basic_line = basic_line[:-1] + "; Still Guide active."
basic.append(basic_line)
details = "; ".join(
f"{name}={load:.3f}" for name, load in components
)
detailed_line = (
f"Visual conditioning load: total={total:.3f} "
f"class={classification}; {details}"
)
if still_guide_active:
detailed_line += "; Still Guide=active"
detailed.append(detailed_line + ".")
elif still_guide_active:
basic.append("Still Guide: active.")
detailed.append("Still Guide: active (excluded from numeric visual load).")
for problem in problems:
line = f"Visual conditioning load advisory: {problem}."
basic.append(line)
detailed.append(line)
return DiagnosticSection(tuple(basic), tuple(detailed))
@dataclass(frozen=True, slots=True)
class _LogicalChunkGeometry:
index: int
total_frames: int | None
trim_frames: int | None
net_frames: int | None
derived_start: int
derived_stop: int
visible_start: int | None
visible_stop: int | None
problems: tuple[str, ...]
def _chunk_boundary_advisory(message: str) -> str:
return f"Chunk boundary advisory: {str(message).rstrip('.')}."
def _logical_chunk_geometries(
assembly_plan: Any,
) -> tuple[list[_LogicalChunkGeometry], list[str]]:
problems: list[str] = []
if not isinstance(assembly_plan, Mapping):
return [], ["Assembly Plan metadata is unavailable"]
raw_chunks = assembly_plan.get("chunks")
if not isinstance(raw_chunks, list) or not raw_chunks:
return [], ["logical chunk metadata is unavailable"]
geometries: list[_LogicalChunkGeometry] = []
cursor = 0
for position, chunk in enumerate(raw_chunks, start=1):
local: list[str] = []
total = trim = net = None
visible_start = visible_stop = None
index = position
if not isinstance(chunk, Mapping):
local.append("metadata is not a mapping")
else:
try:
index = int(chunk.get("chunk_index", chunk.get("sequence_index", position)))
if index != position:
local.append(
f"logical order has Chunk {index} at position {position}"
)
except Exception:
index = position
local.append("logical chunk index is invalid")
try:
total = int(chunk["total_frames"])
trim = int(chunk["trim_frames"])
net = int(chunk["net_frames"])
if total < 0:
local.append("total_frames is negative")
if trim < 0:
local.append("trim_frames is negative")
if trim > total:
local.append("trim_frames exceeds total_frames")
if net < 0:
local.append("net_frames is negative")
if total - trim != net:
local.append("total_frames - trim_frames differs from net_frames")
except Exception as exc:
local.append(
"required geometry is unavailable "
f"({type(exc).__name__}: {exc})"
)
derived_start = cursor
derived_stop = cursor + (net if net is not None and net >= 0 else 0)
if isinstance(chunk, Mapping) and "frame_start" in chunk:
try:
visible_start = int(chunk["frame_start"])
if visible_start != derived_start:
local.append(
f"frame_start={visible_start} differs from derived {derived_start}"
)
except Exception:
local.append("frame_start is invalid")
else:
visible_start = derived_start if net is not None else None
if isinstance(chunk, Mapping) and "frame_stop" in chunk:
try:
visible_stop = int(chunk["frame_stop"])
if visible_stop != derived_stop:
local.append(
f"frame_stop={visible_stop} differs from derived {derived_stop}"
)
except Exception:
local.append("frame_stop is invalid")
else:
visible_stop = derived_stop if net is not None else None
geometries.append(
_LogicalChunkGeometry(
index=index,
total_frames=total,
trim_frames=trim,
net_frames=net,
derived_start=derived_start,
derived_stop=derived_stop,
visible_start=visible_start,
visible_stop=visible_stop,
problems=tuple(local),
)
)
problems.extend(f"Chunk {position}: {problem}" for problem in local)
cursor = derived_stop
return geometries, problems
def _physical_boundary_mapping(
*,
assembly_plan: Any,
logical_count: int,
video_latents: Any,
audio_latents: Any,
) -> tuple[list[Mapping[str, Any]], list[tuple[int, ...]], dict[int, int], list[str]]:
problems: list[str] = []
if not isinstance(assembly_plan, Mapping):
return [], [], {}, ["physical group metadata is unavailable"]
if "decode_groups" in assembly_plan:
raw_groups = assembly_plan.get("decode_groups")
if not isinstance(raw_groups, list) or not raw_groups:
return [], [], {}, ["physical groups are not a non-empty list"]
groups = list(raw_groups)
fallback = False
else:
raw_chunks = assembly_plan.get("chunks")
if not isinstance(raw_chunks, list) or not raw_chunks:
return [], [], {}, ["physical group metadata is unavailable"]
groups = list(raw_chunks)
fallback = True
normalized_groups: list[Mapping[str, Any]] = []
logical_groups: list[tuple[int, ...]] = []
logical_to_group: dict[int, int] = {}
flattened: list[int] = []
for group_index, group in enumerate(groups, start=1):
if not isinstance(group, Mapping):
problems.append(f"physical group {group_index} metadata is not a mapping")
normalized_groups.append({})
logical_groups.append(())
continue
normalized_groups.append(group)
raw_logical = (
[group.get("chunk_index", group.get("sequence_index", group_index))]
if fallback
else group.get("logical_chunk_indices")
)
if not isinstance(raw_logical, (list, tuple)) or not raw_logical:
problems.append(f"physical group {group_index} has no logical chunks")
logical_groups.append(())
continue
try:
logical = tuple(int(value) for value in raw_logical)
except Exception:
problems.append(f"physical group {group_index} logical chunks are invalid")
logical_groups.append(())
continue
logical_groups.append(logical)
flattened.extend(logical)
if tuple(sorted(logical)) != logical:
problems.append(f"physical group {group_index} logical order is reversed")
terminal = bool(group.get("terminal_merged", False))
if terminal:
expected_terminal = (logical_count - 1, logical_count)
if len(logical) != 2 or logical != expected_terminal:
problems.append(
f"physical group {group_index} Terminal Merge mapping is invalid"
)
elif len(logical) != 1:
problems.append(
f"physical group {group_index} has multiple logical chunks without Terminal Merge"
)
for chunk_index in logical:
if chunk_index < 1 or chunk_index > logical_count:
problems.append(
f"physical group {group_index} references invalid Chunk {chunk_index}"
)
elif chunk_index in logical_to_group:
problems.append(f"logical Chunk {chunk_index} is mapped more than once")
else:
logical_to_group[chunk_index] = group_index
expected = list(range(1, logical_count + 1))
if flattened != expected:
missing = [value for value in expected if value not in flattened]
if missing:
problems.append(
"physical group mapping does not cover all logical chunks "
f"(missing={missing})"
)
if not missing and flattened != sorted(flattened):
problems.append("physical group logical chunk order is not contiguous")
video_count = len(_latent_outputs(video_latents))
audio_count = len(_latent_outputs(audio_latents))
if video_count != len(groups) or audio_count != len(groups):
problems.append(
"physical output/group counts differ "
f"(groups={len(groups)}, video={video_count}, audio={audio_count})"
)
return normalized_groups, logical_groups, logical_to_group, problems
def _second_pass_boundary_contract_problems(
*,
assembly_plan: Any,
groups: Sequence[Mapping[str, Any]],
logical_groups: Sequence[tuple[int, ...]],
) -> tuple[list[str], str | None]:
if not isinstance(assembly_plan, Mapping) or "second_pass_contract" not in assembly_plan:
return [], None
contract = assembly_plan.get("second_pass_contract")
if not isinstance(contract, Mapping):
return ["Second Pass contract is not a mapping"], "Second Pass contract: UNAVAILABLE."
contract_groups = contract.get("physical_groups")
if not isinstance(contract_groups, list):
return ["Second Pass physical_groups is not a list"], "Second Pass contract: UNAVAILABLE."
problems: list[str] = []
if len(contract_groups) != len(groups):
problems.append(
"Second Pass physical group count differs from decode groups "
f"({len(contract_groups)} != {len(groups)})"
)
for index, (decode_group, logical) in enumerate(
zip(groups, logical_groups, strict=False)
):
if index >= len(contract_groups):
break
contract_group = contract_groups[index]
if not isinstance(contract_group, Mapping):
problems.append(f"Second Pass group {index} is not a mapping")
continue
raw_contract_logical = contract_group.get("logical_chunks")
contract_logical = (
tuple(raw_contract_logical)
if isinstance(raw_contract_logical, (list, tuple))
else ()
)
checks = (
("group_id", contract_group.get("group_id"), index),
("logical_chunks", contract_logical, logical),
(
"physical_frames",
contract_group.get("physical_frames"),
decode_group.get("total_frames"),
),
(
"trim_prefix_frames",
contract_group.get("trim_prefix_frames"),
decode_group.get("trim_frames"),
),
(
"terminal_merged",
bool(contract_group.get("terminal_merged", False)),
bool(decode_group.get("terminal_merged", False)),
),
)
for name, actual, expected in checks:
if actual != expected:
problems.append(
f"Second Pass group {index} {name} differs "
f"({actual!r} != {expected!r})"
)
result = "PASS" if not problems else "ADVISORY"
return problems, f"Second Pass contract: groups={len(contract_groups)} {result}."
def build_chunk_boundary_diagnostics(
*,
video_latents: Any,
audio_latents: Any,
assembly_plan: Any,
) -> DiagnosticSection:
"""Inspect logical/physical chunk boundaries using metadata and shapes only."""
detailed = [
"Chunk boundary contract: structural diagnostic only; "
"no image/audio similarity measurement."
]
basic: list[str] = []
geometries, logical_problems = _logical_chunk_geometries(assembly_plan)
groups, logical_groups, logical_to_group, mapping_problems = (
_physical_boundary_mapping(
assembly_plan=assembly_plan,
logical_count=len(geometries),
video_latents=video_latents,
audio_latents=audio_latents,
)
)
second_pass_problems, second_pass_line = _second_pass_boundary_contract_problems(
assembly_plan=assembly_plan,
groups=groups,
logical_groups=logical_groups,
)
global_problems = logical_problems + mapping_problems + second_pass_problems
for problem in dict.fromkeys(global_problems):
basic.append(_chunk_boundary_advisory(problem))
if second_pass_line is not None:
detailed.append(second_pass_line)
for boundary_index in range(1, len(geometries)):
left = geometries[boundary_index - 1]
right = geometries[boundary_index]
local = list(left.problems) + list(right.problems)
if left.visible_stop is None or right.visible_start is None:
gap = None
local.append("visible range is unavailable")
else:
gap = int(right.visible_start) - int(left.visible_stop)
if gap != 0:
local.append("non-contiguous visible range")
context_frames = right.trim_frames
context_video_t = context_audio_t = None
if context_frames is None:
local.append("incoming context is unavailable")
else:
try:
context_video_t = context_slots(context_frames)
context_audio_t = audio_latent_t(context_frames)
except Exception as exc:
local.append(
f"incoming context {context_frames}f is invalid "
f"({type(exc).__name__}: {exc})"
)
left_group = logical_to_group.get(left.index)
right_group = logical_to_group.get(right.index)
if left_group is None or right_group is None:
local.append("physical group mapping is unavailable")
classification = "UNAVAILABLE"
detailed.append(
f"Boundary {left.index}→{right.index}: physical mapping unavailable; "
f"UNAVAILABLE ({'; '.join(dict.fromkeys(local))})."
)
elif left_group == right_group:
group = groups[right_group - 1] if right_group <= len(groups) else {}
terminal = bool(group.get("terminal_merged", False))
expected_pair = (left.index, right.index)
actual_pair = (
logical_groups[right_group - 1]
if right_group <= len(logical_groups)
else ()
)
if not terminal:
local.append("shared physical group lacks terminal_merged=yes")
if actual_pair != expected_pair:
local.append("shared physical group does not match this boundary")
classification = "PASS" if not local else "ADVISORY"
detailed.append(
f"Boundary {left.index}→{right.index}: shared physical group={right_group}; "
f"terminal_merged={'yes' if terminal else 'no'}; "
"no external decode boundary; "
f"{classification}"
+ (f" ({'; '.join(dict.fromkeys(local))})" if local else "")
+ "."
)
else:
classification = "PASS" if not local else "ADVISORY"
visible_left = "n/a" if left.visible_stop is None else str(left.visible_stop)
visible_right = "n/a" if right.visible_start is None else str(right.visible_start)
gap_text = "n/a" if gap is None else str(gap)
context_text = "n/a" if context_frames is None else f"{context_frames}f"
video_text = "n/a" if context_video_t is None else f"{context_video_t}T"
audio_text = "n/a" if context_audio_t is None else f"{context_audio_t}T"
right_text = (
"right=unavailable"
if right.total_frames is None
or right.trim_frames is None
or right.net_frames is None
else (
f"right={right.total_frames}f trim={right.trim_frames} "
f"net={right.net_frames}"
)
)
detailed.append(
f"Boundary {left.index}→{right.index}: physical; "
f"visible={visible_left}→{visible_right} gap={gap_text}; "
f"context={context_text} video={video_text} audio={audio_text}; "
f"{right_text}; {classification}"
+ (f" ({'; '.join(dict.fromkeys(local))})" if local else "")
+ "."
)
if local:
if gap not in (None, 0):
message = (
f"boundary {left.index}→{right.index} has a non-contiguous "
"visible range"
)
elif classification == "UNAVAILABLE":
message = f"boundary {left.index}→{right.index} is unavailable"
else:
message = (
f"boundary {left.index}→{right.index}: "
+ "; ".join(dict.fromkeys(local))
)
advisory = _chunk_boundary_advisory(message)
if advisory not in basic:
basic.append(advisory)
return DiagnosticSection(tuple(basic), tuple(detailed))
def build_v38_diagnostics(
*,
video_latents: Any,
audio_latents: Any,
assembly_plan: Any,
output_width: int,
output_height: int,
chunk_seconds: float,
reference_images: Sequence[Any] = (),
reference_size: str = "Match Output",
video_guide: Any = None,
video_guide_size: str = REFERENCE_VIDEO_SIZE_EFFICIENT,
still_guide_active: bool = False,
core_checker: Callable[[], list[str]] | None = None,
) -> V38Diagnostics:
return _combine_sections(
build_frame_alignment_diagnostics(
video_latents=video_latents,
assembly_plan=assembly_plan,
video_guide=video_guide,
chunk_seconds=float(chunk_seconds),
),
validate_audio_latent_lengths(
audio_latents=audio_latents,
assembly_plan=assembly_plan,
),
build_chunk_boundary_diagnostics(
video_latents=video_latents,
audio_latents=audio_latents,
assembly_plan=assembly_plan,
),
collect_core_compatibility_advisory(core_checker),
estimate_visual_conditioning_load(
output_width=int(output_width),
output_height=int(output_height),
reference_images=tuple(reference_images),
reference_size=str(reference_size),
video_guide=video_guide,
video_guide_size=str(video_guide_size),
chunk_seconds=float(chunk_seconds),
still_guide_active=bool(still_guide_active),
),
)
def format_v38_diagnostics(
diagnostics: V38Diagnostics,
*,
mode: str = DIAGNOSTICS_BASIC,
) -> str:
normalized = normalize_diagnostics_mode(str(mode))
if normalized == DIAGNOSTICS_OFF:
return ""
lines = diagnostics.detailed if normalized == DIAGNOSTICS_FULL else diagnostics.basic
if not lines:
return ""
return "V3.8 Reliability\n" + "\n".join(lines)
def append_v38_status(
status: Any,
diagnostics: V38Diagnostics,
*,
mode: str = DIAGNOSTICS_BASIC,
) -> str:
suffix = format_v38_diagnostics(diagnostics, mode=mode)
original = str(status)
return original if not suffix else original.rstrip() + "\n" + suffix
+248
View File
@@ -0,0 +1,248 @@
"""Shared H3 resolution presets for Easy and V3.8 sampler facades."""
from __future__ import annotations
from dataclasses import dataclass
import math
from typing import Any
H3_ASPECT_AUTO = "Auto from First Image"
H3_ASPECT_LANDSCAPE = "Landscape 16:9"
H3_ASPECT_PORTRAIT = "Portrait 9:16"
H3_ASPECT_SQUARE = "Square 1:1"
H3_ASPECT_OPTIONS = (
H3_ASPECT_AUTO,
H3_ASPECT_LANDSCAPE,
H3_ASPECT_PORTRAIT,
H3_ASPECT_SQUARE,
)
H3_SIZE_SOURCE_FIRST_IMAGE = "First Image"
H3_SIZE_SOURCE_MANUAL = "Manual"
H3_SIZE_SOURCE_LEGACY = "Legacy Aspect"
H3_SIZE_SOURCE_OPTIONS = (
H3_SIZE_SOURCE_FIRST_IMAGE,
H3_SIZE_SOURCE_MANUAL,
H3_SIZE_SOURCE_LEGACY,
)
H3_PRESET_DRAFT = "Draft — 0.30 MP"
H3_PRESET_BALANCED = "Balanced — 0.60 MP"
H3_PRESET_NATIVE = "Native 768"
H3_PRESET_CUSTOM = "Custom"
H3_PRESET_OPTIONS = (
H3_PRESET_DRAFT,
H3_PRESET_BALANCED,
H3_PRESET_NATIVE,
H3_PRESET_CUSTOM,
)
H3_DRAFT_MP = 0.30
H3_BALANCED_MP = 0.60
H3_CUSTOM_MP_DEFAULT = 0.30
H3_CUSTOM_MP_MIN = 0.10
H3_CUSTOM_MP_MAX = 16.0
H3_CUSTOM_MP_STRONG_WARNING = 2.50
H3_MP_PIXELS = 1_000_000.0
H3_CANVAS_MULTIPLE = 32
H3_NATIVE_SHORT_EDGE = 768
H3_NATIVE_LONG_EDGE_CAP = 1344
H3_MANUAL_WIDTH_DEFAULT = 736
H3_MANUAL_HEIGHT_DEFAULT = 416
H3_CANVAS_MIN = 32
H3_CANVAS_MAX = 16384
@dataclass(frozen=True)
class H3ResolutionPlan:
width: int
height: int
aspect_ratio: float
aspect_source: str
preset: str
target_mp: float | None
warnings: tuple[str, ...]
@property
def actual_mp(self) -> float:
return float(self.width * self.height) / H3_MP_PIXELS
def _round_canvas(value: float) -> int:
units = math.floor(float(value) / H3_CANVAS_MULTIPLE + 0.5)
return max(H3_CANVAS_MULTIPLE, int(units) * H3_CANVAS_MULTIPLE)
def _first_image_aspect(first_frame: Any) -> float | None:
shape = getattr(first_frame, "shape", None)
if shape is None or len(shape) != 4:
return None
height = int(shape[1])
width = int(shape[2])
if width < 1 or height < 1:
return None
return float(width) / float(height)
def _manual_dimension(value: Any, name: str) -> int:
if isinstance(value, bool):
raise TypeError(f"Manual {name} must be an integer")
resolved = int(value)
if float(value) != float(resolved):
raise ValueError(f"Manual {name} must be an integer")
if not H3_CANVAS_MIN <= resolved <= H3_CANVAS_MAX:
raise ValueError(
f"Manual {name} must be between {H3_CANVAS_MIN} and {H3_CANVAS_MAX}"
)
if resolved % H3_CANVAS_MULTIPLE:
raise ValueError(
f"Manual {name} must be aligned to {H3_CANVAS_MULTIPLE} pixels"
)
return resolved
def _manual_resolution(width: Any, height: Any, *, warning: str | None = None) -> H3ResolutionPlan:
resolved_width = _manual_dimension(width, "Width")
resolved_height = _manual_dimension(height, "Height")
return H3ResolutionPlan(
width=resolved_width,
height=resolved_height,
aspect_ratio=float(resolved_width) / float(resolved_height),
aspect_source="Manual Width / Height",
preset="Manual",
target_mp=None,
warnings=(warning,) if warning else (),
)
def resolve_h3_aspect(aspect: str, first_frame: Any = None) -> tuple[float, str]:
"""Resolve the existing Easy aspect policy without creating a second fallback."""
if aspect == H3_ASPECT_AUTO:
image_aspect = _first_image_aspect(first_frame)
if image_aspect is not None:
return image_aspect, "First Image"
return 16.0 / 9.0, "Landscape 16:9 fallback"
if aspect == H3_ASPECT_LANDSCAPE:
return 16.0 / 9.0, H3_ASPECT_LANDSCAPE
if aspect == H3_ASPECT_PORTRAIT:
return 9.0 / 16.0, H3_ASPECT_PORTRAIT
if aspect == H3_ASPECT_SQUARE:
return 1.0, H3_ASPECT_SQUARE
return 16.0 / 9.0, "Landscape 16:9 fallback"
def _area_resolution(aspect_ratio: float, megapixels: float) -> tuple[int, int]:
target_pixels = float(megapixels) * H3_MP_PIXELS
raw_width = math.sqrt(target_pixels * float(aspect_ratio))
raw_height = math.sqrt(target_pixels / float(aspect_ratio))
return _round_canvas(raw_width), _round_canvas(raw_height)
def _native_resolution(aspect_ratio: float) -> tuple[int, int]:
landscape = float(aspect_ratio) >= 1.0
major_ratio = float(aspect_ratio) if landscape else 1.0 / float(aspect_ratio)
short_edge = float(H3_NATIVE_SHORT_EDGE)
long_edge = short_edge * major_ratio
if long_edge > H3_NATIVE_LONG_EDGE_CAP:
long_edge = float(H3_NATIVE_LONG_EDGE_CAP)
short_edge = long_edge / major_ratio
long_px = min(H3_NATIVE_LONG_EDGE_CAP, _round_canvas(long_edge))
short_px = min(H3_NATIVE_SHORT_EDGE, _round_canvas(short_edge))
if landscape:
return long_px, short_px
return short_px, long_px
def resolve_h3_resolution(
*,
aspect: str,
preset: str,
custom_mp: float = H3_CUSTOM_MP_DEFAULT,
first_frame: Any = None,
) -> H3ResolutionPlan:
"""Resolve decimal-MP or Native 768 dimensions on the H3 32-pixel grid."""
aspect_ratio, aspect_source = resolve_h3_aspect(aspect, first_frame)
warnings: list[str] = []
target_mp: float | None
if preset == H3_PRESET_DRAFT:
target_mp = H3_DRAFT_MP
width, height = _area_resolution(aspect_ratio, target_mp)
elif preset == H3_PRESET_BALANCED:
target_mp = H3_BALANCED_MP
width, height = _area_resolution(aspect_ratio, target_mp)
elif preset == H3_PRESET_NATIVE:
target_mp = None
width, height = _native_resolution(aspect_ratio)
else:
preset = H3_PRESET_CUSTOM
if isinstance(custom_mp, bool):
raise TypeError("Custom MP must be numeric")
target_mp = float(custom_mp)
if not H3_CUSTOM_MP_MIN <= target_mp <= H3_CUSTOM_MP_MAX:
raise ValueError(
f"Custom MP must be between {H3_CUSTOM_MP_MIN:.2f} and "
f"{H3_CUSTOM_MP_MAX:.2f}"
)
width, height = _area_resolution(aspect_ratio, target_mp)
native_width, native_height = _native_resolution(aspect_ratio)
native_pixels = native_width * native_height
if width * height > native_pixels:
warnings.append(
"Above Native 768: processing time and memory usage may increase."
)
if target_mp > H3_CUSTOM_MP_STRONG_WARNING:
warnings.append(
"High Custom MP: substantial VRAM use and generation time are possible."
)
return H3ResolutionPlan(
width=width,
height=height,
aspect_ratio=aspect_ratio,
aspect_source=aspect_source,
preset=preset,
target_mp=target_mp,
warnings=tuple(warnings),
)
def resolve_h3_size_source(
*,
size_source: str,
width: Any = H3_MANUAL_WIDTH_DEFAULT,
height: Any = H3_MANUAL_HEIGHT_DEFAULT,
aspect: str = H3_ASPECT_AUTO,
preset: str = H3_PRESET_DRAFT,
custom_mp: float = H3_CUSTOM_MP_DEFAULT,
first_frame: Any = None,
) -> H3ResolutionPlan:
"""Resolve the V3.8 two-choice Size Source while retaining legacy API input."""
if size_source == H3_SIZE_SOURCE_MANUAL:
return _manual_resolution(width, height)
if size_source == H3_SIZE_SOURCE_FIRST_IMAGE:
if _first_image_aspect(first_frame) is None:
return _manual_resolution(
width,
height,
warning=(
"First Image is unavailable for Size Source = First Image; "
"the displayed Manual Width / Height were used."
),
)
return resolve_h3_resolution(
aspect=H3_ASPECT_AUTO,
preset=preset,
custom_mp=custom_mp,
first_frame=first_frame,
)
# Existing API prompts and saved workflows omit size_source. Preserve their
# exact V3.8 aspect resolver until the frontend migrates the visible widgets.
return resolve_h3_resolution(
aspect=aspect,
preset=preset,
custom_mp=custom_mp,
first_frame=first_frame,
)
+767
View File
@@ -0,0 +1,767 @@
"""Pure execution-policy resolvers for V3.8 chunk review.
This module deliberately owns no ComfyUI, torch, filesystem, Run Storage, or
sampling behavior. It turns already-validated storage facts into an execution
decision that later phases can apply to the existing Production engine.
"""
from __future__ import annotations
from collections.abc import Mapping
from dataclasses import dataclass
from typing import Any
from ..branch_provenance import TAKE_ACTION_CONTINUE, TAKE_ACTION_USE
GENERATION_MODE_FULL_RUN = "Full Run"
GENERATION_MODE_REVIEW = "Review Each Chunk"
GENERATION_MODE_OPTIONS = (
GENERATION_MODE_FULL_RUN,
GENERATION_MODE_REVIEW,
)
REVIEW_ACTION_CONTINUE = "Continue / Next"
REVIEW_ACTION_REGENERATE_CURRENT = "Regenerate Current"
REVIEW_ACTION_FINISH_REMAINING = "Finish Remaining"
REVIEW_ACTION_OPTIONS = (
REVIEW_ACTION_CONTINUE,
REVIEW_ACTION_REGENERATE_CURRENT,
REVIEW_ACTION_FINISH_REMAINING,
)
RUN_STORAGE_OFF = "Off"
RUN_STORAGE_SAVE_AUTO_RESUME = "Save + Auto Resume"
REVISION_STATUS_IN_PROGRESS = "in_progress"
REVISION_STATUS_INTERRUPTED = "interrupted"
REVISION_STATUS_REVIEW_READY = "review_ready"
REVISION_STATUS_COMPLETE = "complete"
REVISION_STATUSES = (
REVISION_STATUS_IN_PROGRESS,
REVISION_STATUS_INTERRUPTED,
REVISION_STATUS_REVIEW_READY,
REVISION_STATUS_COMPLETE,
)
EXECUTION_MODE_FULL_RUN = "full_run"
EXECUTION_MODE_REVIEW_CONTINUE = "review_continue"
EXECUTION_MODE_REVIEW_REGENERATE = "review_regenerate_current"
EXECUTION_MODE_REVIEW_FINISH = "review_finish_remaining"
EXECUTION_MODE_REVIEW_USE_TAKE = "review_use_take"
EXECUTION_MODE_REVIEW_CONTINUE_FROM_TAKE = "review_continue_from_take"
NONCE_POLICY_INACTIVE = "inactive"
NONCE_POLICY_INHERIT = "inherit_branch"
NONCE_POLICY_ADVANCE = "advance_variation"
NONCE_POLICY_MANUAL = "manual"
REVIEW_PAUSE_REASON = "review_each_chunk"
class ReviewControlError(ValueError):
"""Raised when a requested review policy is structurally ambiguous."""
@dataclass(frozen=True)
class ReviewUnit:
"""One atomic physical sampling group expressed in logical chunk numbers."""
start: int
end: int
physical_group: int
def as_metadata(self) -> dict[str, int]:
return {
"start": self.start,
"end": self.end,
"physical_group": self.physical_group,
}
@dataclass(frozen=True)
class ReviewExecution:
"""Side-effect-free decision consumed by later execution phases."""
execution_mode: str
requires_run_storage: bool
effective_regenerate_from: int
max_new_physical_groups: int | None
next_review_unit_start: int | None
next_review_unit_end: int | None
next_review_physical_group: int | None
finish_remaining: bool
smart_regenerate: bool
one_shot_reset_required: bool
partial_review: bool
projected_prefix_count: int
nonce_policy: str
branch_regenerate_from: int
base_effective_nonce: int
requested_effective_nonce: int | None
status_hint: str
def _integer(value: Any, *, name: str, minimum: int, maximum: int) -> int:
if isinstance(value, bool) or not isinstance(value, int):
raise ReviewControlError(f"{name} must be an integer")
if not minimum <= value <= maximum:
raise ReviewControlError(
f"{name} must be between {minimum} and {maximum}"
)
return value
def _manual_regenerate_from(value: Any, *, configured_chunks: int) -> int:
if value is None or value == "Auto" or value == 0:
return 0
if isinstance(value, str) and value.startswith("Chunk "):
try:
value = int(value[6:])
except ValueError as exc:
raise ReviewControlError(
"manual_regenerate_from must be Auto or a valid chunk"
) from exc
return _integer(
value,
name="manual_regenerate_from",
minimum=1,
maximum=configured_chunks,
)
def _terminal_pair_start(
*,
configured_chunks: int,
terminal_merge_enabled: bool,
terminal_pair_start: Any,
) -> int | None:
if type(terminal_merge_enabled) is not bool:
raise ReviewControlError("terminal_merge_enabled must be a boolean")
if not terminal_merge_enabled:
return None
if configured_chunks < 2:
raise ReviewControlError(
"Terminal Merge requires at least two configured chunks"
)
start = _integer(
terminal_pair_start,
name="terminal_pair_start",
minimum=1,
maximum=configured_chunks - 1,
)
if start != configured_chunks - 1:
raise ReviewControlError(
"Terminal Merge must cover the final two configured chunks"
)
return start
def _review_geometry(
*,
configured_chunks: Any,
validated_prefix_count: Any,
terminal_merge_enabled: bool,
terminal_pair_start: Any,
) -> tuple[int, int, int | None]:
chunks = _integer(
configured_chunks,
name="configured_chunks",
minimum=1,
maximum=0x7FFFFFFF,
)
prefix = _integer(
validated_prefix_count,
name="validated_prefix_count",
minimum=0,
maximum=chunks,
)
pair_start = _terminal_pair_start(
configured_chunks=chunks,
terminal_merge_enabled=terminal_merge_enabled,
terminal_pair_start=terminal_pair_start,
)
if pair_start is not None and pair_start <= prefix < chunks:
raise ReviewControlError(
"validated prefix ends inside the atomic Terminal Merge pair"
)
return chunks, prefix, pair_start
def resolve_next_review_unit(
*,
configured_chunks: int,
validated_prefix_count: int,
terminal_merge_enabled: bool,
terminal_pair_start: int | None,
) -> ReviewUnit | None:
"""Return the next atomic physical group after a validated logical prefix."""
chunks, prefix, pair_start = _review_geometry(
configured_chunks=configured_chunks,
validated_prefix_count=validated_prefix_count,
terminal_merge_enabled=terminal_merge_enabled,
terminal_pair_start=terminal_pair_start,
)
if prefix == chunks:
return None
start = prefix + 1
if pair_start is not None and start == pair_start:
return ReviewUnit(
start=pair_start,
end=chunks,
physical_group=pair_start,
)
return ReviewUnit(start=start, end=start, physical_group=start)
def _review_unit_for_chunk(
chunk: int,
*,
configured_chunks: int,
terminal_pair_start: int | None,
) -> ReviewUnit:
if terminal_pair_start is not None and chunk >= terminal_pair_start:
return ReviewUnit(
start=terminal_pair_start,
end=configured_chunks,
physical_group=terminal_pair_start,
)
return ReviewUnit(start=chunk, end=chunk, physical_group=chunk)
def _validated_review_unit(
value: Any,
*,
configured_chunks: int,
validated_prefix_count: int,
terminal_pair_start: int | None,
) -> ReviewUnit | None:
if value is None:
return None
if isinstance(value, ReviewUnit):
unit = value
elif isinstance(value, Mapping):
try:
unit = ReviewUnit(
start=value["start"],
end=value["end"],
physical_group=value["physical_group"],
)
except KeyError as exc:
raise ReviewControlError(
"latest_review_unit is missing required metadata"
) from exc
else:
raise ReviewControlError(
"latest_review_unit must be review metadata or None"
)
start = _integer(
unit.start,
name="latest_review_unit.start",
minimum=1,
maximum=configured_chunks,
)
end = _integer(
unit.end,
name="latest_review_unit.end",
minimum=start,
maximum=configured_chunks,
)
physical_group = _integer(
unit.physical_group,
name="latest_review_unit.physical_group",
minimum=1,
maximum=configured_chunks,
)
if physical_group != start:
raise ReviewControlError(
"latest_review_unit physical group must equal its first logical chunk"
)
if terminal_pair_start is not None and start == terminal_pair_start:
if end != configured_chunks:
raise ReviewControlError(
"latest_review_unit splits the atomic Terminal Merge pair"
)
elif end != start:
raise ReviewControlError(
"a non-terminal review unit must contain exactly one logical chunk"
)
if terminal_pair_start is not None and start > terminal_pair_start:
raise ReviewControlError(
"latest_review_unit starts inside the atomic Terminal Merge pair"
)
if end != validated_prefix_count:
raise ReviewControlError(
"latest_review_unit is not the head of the validated prefix"
)
return ReviewUnit(start=start, end=end, physical_group=physical_group)
def make_review_pause_metadata(review_unit: ReviewUnit) -> dict[str, Any]:
"""Build non-identity manifest metadata for a successful review pause."""
if not isinstance(review_unit, ReviewUnit):
raise ReviewControlError("review_unit must be a ReviewUnit")
start = _integer(
review_unit.start,
name="review_unit.start",
minimum=1,
maximum=0x7FFFFFFF,
)
end = _integer(
review_unit.end,
name="review_unit.end",
minimum=start,
maximum=0x7FFFFFFF,
)
physical_group = _integer(
review_unit.physical_group,
name="review_unit.physical_group",
minimum=1,
maximum=0x7FFFFFFF,
)
if physical_group != start:
raise ReviewControlError(
"review_unit physical group must equal its first logical chunk"
)
return {
"review_unit": {
"start": start,
"end": end,
"physical_group": physical_group,
},
"review_pause_reason": REVIEW_PAUSE_REASON,
}
def _revision_status(value: Any, *, prefix: int, chunks: int) -> str | None:
if value is None or value == "":
if prefix:
raise ReviewControlError(
"a non-empty validated prefix requires a revision status"
)
return None
status = str(value)
if status not in REVISION_STATUSES:
raise ReviewControlError(f"unknown latest revision status: {status!r}")
if status == REVISION_STATUS_COMPLETE and prefix != chunks:
raise ReviewControlError(
"a complete revision must contain every configured chunk"
)
if status == REVISION_STATUS_REVIEW_READY and not 0 < prefix < chunks:
raise ReviewControlError(
"review_ready requires a non-empty incomplete prefix"
)
return status
def _branch_contract(
*,
latest_effective_nonce: Any,
latest_branch_regenerate_from: Any,
validated_prefix_count: int,
configured_chunks: int,
latest_revision_status: str | None,
) -> tuple[int, int]:
nonce = _integer(
latest_effective_nonce,
name="latest_effective_nonce",
minimum=0,
maximum=0xFFFFFFFF,
)
branch_start = _manual_regenerate_from(
latest_branch_regenerate_from,
configured_chunks=configured_chunks,
)
if nonce == 0 and branch_start != 0:
raise ReviewControlError(
"a regenerate branch requires a positive effective nonce"
)
if nonce > 0 and branch_start == 0:
raise ReviewControlError(
"a positive effective nonce requires its regenerate branch boundary"
)
if branch_start > validated_prefix_count + 1:
raise ReviewControlError(
"regenerate branch boundary skips the validated prefix head"
)
if (
latest_revision_status
in (REVISION_STATUS_REVIEW_READY, REVISION_STATUS_COMPLETE)
and branch_start > validated_prefix_count
):
raise ReviewControlError(
"a ready regenerate branch has not committed its boundary chunk"
)
return nonce, branch_start
def _nonce_decision(
*,
manual_regenerate_from: int,
smart_regenerate: bool,
latest_effective_nonce: int,
latest_branch_regenerate_from: int,
smart_target: int = 0,
) -> tuple[str, int, int | None]:
if smart_regenerate:
if latest_effective_nonce >= 0xFFFFFFFF:
raise ReviewControlError(
"effective reroll nonce variation space is exhausted"
)
return (
NONCE_POLICY_ADVANCE,
smart_target,
latest_effective_nonce + 1,
)
if manual_regenerate_from:
return NONCE_POLICY_MANUAL, manual_regenerate_from, None
if latest_effective_nonce:
return (
NONCE_POLICY_INHERIT,
latest_branch_regenerate_from,
latest_effective_nonce,
)
return NONCE_POLICY_INACTIVE, 0, 0
def _unit_status(unit: ReviewUnit, *, chunks: int, verb: str) -> str:
if unit.start == unit.end:
return f"{verb}: Chunk {unit.start} / {chunks}."
return (
f"{verb}: Chunks {unit.start}-{unit.end} / {chunks}; "
"Terminal Merge atomic group."
)
def resolve_review_execution(
*,
generation_mode: str,
review_action: str,
configured_chunks: int,
validated_prefix_count: int,
terminal_merge_enabled: bool,
terminal_pair_start: int | None,
manual_regenerate_from: Any,
run_storage_mode: str,
latest_review_unit: ReviewUnit | Mapping[str, Any] | None,
latest_revision_status: str | None,
latest_effective_nonce: int,
latest_branch_regenerate_from: Any = 0,
) -> ReviewExecution:
"""Resolve V3.8 review intent without touching Production or storage state."""
if generation_mode not in GENERATION_MODE_OPTIONS:
raise ReviewControlError(f"unknown Generation Mode: {generation_mode!r}")
if review_action not in REVIEW_ACTION_OPTIONS:
raise ReviewControlError(f"unknown Review Action: {review_action!r}")
chunks, prefix, pair_start = _review_geometry(
configured_chunks=configured_chunks,
validated_prefix_count=validated_prefix_count,
terminal_merge_enabled=terminal_merge_enabled,
terminal_pair_start=terminal_pair_start,
)
status = _revision_status(
latest_revision_status,
prefix=prefix,
chunks=chunks,
)
manual_from = _manual_regenerate_from(
manual_regenerate_from,
configured_chunks=chunks,
)
nonce, existing_branch_start = _branch_contract(
latest_effective_nonce=latest_effective_nonce,
latest_branch_regenerate_from=latest_branch_regenerate_from,
validated_prefix_count=prefix,
configured_chunks=chunks,
latest_revision_status=status,
)
if generation_mode == GENERATION_MODE_FULL_RUN:
nonce_policy, branch_start, requested_nonce = _nonce_decision(
manual_regenerate_from=manual_from,
smart_regenerate=False,
latest_effective_nonce=nonce,
latest_branch_regenerate_from=existing_branch_start,
)
return ReviewExecution(
execution_mode=EXECUTION_MODE_FULL_RUN,
requires_run_storage=False,
effective_regenerate_from=(manual_from or branch_start),
max_new_physical_groups=None,
next_review_unit_start=None,
next_review_unit_end=None,
next_review_physical_group=None,
finish_remaining=False,
smart_regenerate=False,
one_shot_reset_required=False,
partial_review=False,
projected_prefix_count=chunks,
nonce_policy=nonce_policy,
branch_regenerate_from=branch_start,
base_effective_nonce=nonce,
requested_effective_nonce=requested_nonce,
status_hint="Full Run: Review execution limit disabled.",
)
if run_storage_mode != RUN_STORAGE_SAVE_AUTO_RESUME:
raise ReviewControlError(
"Review Each Chunk requires Run Storage = Save + Auto Resume."
)
latest_unit = _validated_review_unit(
latest_review_unit,
configured_chunks=chunks,
validated_prefix_count=prefix,
terminal_pair_start=pair_start,
)
if review_action == REVIEW_ACTION_REGENERATE_CURRENT:
if manual_from:
raise ReviewControlError(
"Regenerate Current cannot be combined with manual Regenerate From. "
"Set Regenerate From to Auto."
)
if prefix == 0:
raise ReviewControlError(
"Regenerate Current requires an existing reviewed unit"
)
if latest_unit is None:
raise ReviewControlError(
"Regenerate Current requires latest review_unit metadata"
)
if status not in (
REVISION_STATUS_REVIEW_READY,
REVISION_STATUS_COMPLETE,
):
raise ReviewControlError(
"Regenerate Current requires a review_ready revision or a complete "
"revision with review_unit metadata"
)
nonce_policy, branch_start, requested_nonce = _nonce_decision(
manual_regenerate_from=0,
smart_regenerate=True,
latest_effective_nonce=nonce,
latest_branch_regenerate_from=existing_branch_start,
smart_target=latest_unit.start,
)
projected = latest_unit.end
return ReviewExecution(
execution_mode=EXECUTION_MODE_REVIEW_REGENERATE,
requires_run_storage=True,
effective_regenerate_from=latest_unit.start,
max_new_physical_groups=1,
next_review_unit_start=latest_unit.start,
next_review_unit_end=latest_unit.end,
next_review_physical_group=latest_unit.physical_group,
finish_remaining=False,
smart_regenerate=True,
one_shot_reset_required=True,
partial_review=projected < chunks,
projected_prefix_count=projected,
nonce_policy=nonce_policy,
branch_regenerate_from=branch_start,
base_effective_nonce=nonce,
requested_effective_nonce=requested_nonce,
status_hint=_unit_status(
latest_unit,
chunks=chunks,
verb="Smart Regenerate",
),
)
nonce_policy, branch_start, requested_nonce = _nonce_decision(
manual_regenerate_from=manual_from,
smart_regenerate=False,
latest_effective_nonce=nonce,
latest_branch_regenerate_from=existing_branch_start,
)
if review_action == REVIEW_ACTION_FINISH_REMAINING:
return ReviewExecution(
execution_mode=EXECUTION_MODE_REVIEW_FINISH,
requires_run_storage=True,
effective_regenerate_from=(manual_from or branch_start),
max_new_physical_groups=None,
next_review_unit_start=None,
next_review_unit_end=None,
next_review_physical_group=None,
finish_remaining=True,
smart_regenerate=False,
one_shot_reset_required=True,
partial_review=False,
projected_prefix_count=chunks,
nonce_policy=nonce_policy,
branch_regenerate_from=branch_start,
base_effective_nonce=nonce,
requested_effective_nonce=requested_nonce,
status_hint=(
f"Review Mode: finish remaining after accepted prefix "
f"{prefix} / {chunks}."
),
)
if manual_from:
next_unit = _review_unit_for_chunk(
manual_from,
configured_chunks=chunks,
terminal_pair_start=pair_start,
)
else:
next_unit = resolve_next_review_unit(
configured_chunks=chunks,
validated_prefix_count=prefix,
terminal_merge_enabled=terminal_merge_enabled,
terminal_pair_start=pair_start,
)
if next_unit is None:
projected = chunks
status_hint = "Review Mode: Sequence complete."
unit_start = unit_end = physical_group = None
else:
projected = next_unit.end
status_hint = _unit_status(
next_unit,
chunks=chunks,
verb="Review next unit",
)
unit_start = next_unit.start
unit_end = next_unit.end
physical_group = next_unit.physical_group
return ReviewExecution(
execution_mode=EXECUTION_MODE_REVIEW_CONTINUE,
requires_run_storage=True,
effective_regenerate_from=(manual_from or branch_start),
max_new_physical_groups=1,
next_review_unit_start=unit_start,
next_review_unit_end=unit_end,
next_review_physical_group=physical_group,
finish_remaining=False,
smart_regenerate=False,
one_shot_reset_required=False,
partial_review=projected < chunks,
projected_prefix_count=projected,
nonce_policy=nonce_policy,
branch_regenerate_from=branch_start,
base_effective_nonce=nonce,
requested_effective_nonce=requested_nonce,
status_hint=status_hint,
)
def resolve_take_execution(
*,
take_action: str,
configured_chunks: int,
selected_prefix_count: int,
terminal_merge_enabled: bool,
terminal_pair_start: int | None,
selected_review_unit: ReviewUnit | Mapping[str, Any],
selected_effective_nonce: int,
selected_branch_regenerate_from: int,
next_effective_nonce: int,
) -> ReviewExecution:
"""Resolve an already-validated immutable Take selection.
The selected prefix is a Run Storage fact. Continuing from it starts a
fresh downstream nonce boundary without changing the Sampling Contract.
"""
if take_action not in (TAKE_ACTION_USE, TAKE_ACTION_CONTINUE):
raise ReviewControlError(f"unknown Take action: {take_action!r}")
chunks, prefix, pair_start = _review_geometry(
configured_chunks=configured_chunks,
validated_prefix_count=selected_prefix_count,
terminal_merge_enabled=terminal_merge_enabled,
terminal_pair_start=terminal_pair_start,
)
unit = _validated_review_unit(
selected_review_unit,
configured_chunks=chunks,
validated_prefix_count=prefix,
terminal_pair_start=pair_start,
)
if unit is None:
raise ReviewControlError("selected Take is missing its physical review unit")
selected_nonce, selected_branch = _branch_contract(
latest_effective_nonce=selected_effective_nonce,
latest_branch_regenerate_from=selected_branch_regenerate_from,
validated_prefix_count=prefix,
configured_chunks=chunks,
latest_revision_status=(
REVISION_STATUS_COMPLETE if prefix == chunks else REVISION_STATUS_REVIEW_READY
),
)
if take_action == TAKE_ACTION_USE:
return ReviewExecution(
execution_mode=EXECUTION_MODE_REVIEW_USE_TAKE,
requires_run_storage=True,
effective_regenerate_from=selected_branch,
max_new_physical_groups=0,
next_review_unit_start=None,
next_review_unit_end=None,
next_review_physical_group=None,
finish_remaining=False,
smart_regenerate=False,
one_shot_reset_required=True,
partial_review=prefix < chunks,
projected_prefix_count=prefix,
nonce_policy=NONCE_POLICY_INHERIT if selected_nonce else NONCE_POLICY_INACTIVE,
branch_regenerate_from=selected_branch,
base_effective_nonce=selected_nonce,
requested_effective_nonce=selected_nonce,
status_hint=_unit_status(unit, chunks=chunks, verb="Use This Take"),
)
next_unit = resolve_next_review_unit(
configured_chunks=chunks,
validated_prefix_count=prefix,
terminal_merge_enabled=terminal_merge_enabled,
terminal_pair_start=pair_start,
)
if next_unit is None:
return ReviewExecution(
execution_mode=EXECUTION_MODE_REVIEW_USE_TAKE,
requires_run_storage=True,
effective_regenerate_from=selected_branch,
max_new_physical_groups=0,
next_review_unit_start=None,
next_review_unit_end=None,
next_review_physical_group=None,
finish_remaining=False,
smart_regenerate=False,
one_shot_reset_required=True,
partial_review=False,
projected_prefix_count=chunks,
nonce_policy=NONCE_POLICY_INHERIT if selected_nonce else NONCE_POLICY_INACTIVE,
branch_regenerate_from=selected_branch,
base_effective_nonce=selected_nonce,
requested_effective_nonce=selected_nonce,
status_hint="Continue From Here: selected Take is already complete.",
)
nonce = _integer(
next_effective_nonce,
name="next_effective_nonce",
minimum=1,
maximum=0xFFFFFFFF,
)
return ReviewExecution(
execution_mode=EXECUTION_MODE_REVIEW_CONTINUE_FROM_TAKE,
requires_run_storage=True,
effective_regenerate_from=next_unit.start,
max_new_physical_groups=1,
next_review_unit_start=next_unit.start,
next_review_unit_end=next_unit.end,
next_review_physical_group=next_unit.physical_group,
finish_remaining=False,
smart_regenerate=False,
one_shot_reset_required=True,
partial_review=next_unit.end < chunks,
projected_prefix_count=next_unit.end,
nonce_policy=NONCE_POLICY_ADVANCE,
branch_regenerate_from=next_unit.start,
base_effective_nonce=selected_nonce,
requested_effective_nonce=nonce,
status_hint=_unit_status(next_unit, chunks=chunks, verb="Continue From Here"),
)
+89 -4
View File
@@ -53,6 +53,13 @@ def _latent_samples(value: Any, *, name: str) -> torch.Tensor:
return samples
def _require_finite_samples(samples: torch.Tensor, *, name: str) -> None:
"""Reject unusable processor output before it reaches Second Pass Sampling."""
if not bool(torch.isfinite(samples).all().item()):
raise SecondPassContractError(f"{name}.samples contains NaN or Inf")
def _contract_groups(assembly_plan: Mapping[str, Any]) -> list[Mapping[str, Any]]:
if not isinstance(assembly_plan, Mapping):
raise SecondPassContractError("assembly_plan must be a mapping")
@@ -95,6 +102,7 @@ def _validate_video_groups(
source_w = int(group.get("source_latent_w", -1))
if source_h < 1 or source_w < 1 or height < source_h or width < source_w:
raise SecondPassContractError("video latent spatial size must be preserved or enlarged")
_require_finite_samples(samples, name=f"video_latents[{position}]")
if target_geometry is None:
target_geometry = (height, width)
elif target_geometry != (height, width):
@@ -121,6 +129,7 @@ def validate_second_pass_inputs(
expected_shape = group.get("source_audio_shape")
if not isinstance(expected_shape, list) or tuple(expected_shape) != tuple(samples.shape):
raise SecondPassContractError("audio latent shape or physical group order changed")
_require_finite_samples(samples, name=f"audio_latents[{position}]")
return {
"physical_group_count": len(groups),
@@ -135,6 +144,38 @@ def passthrough_audio_latents(audio_latents: Sequence[Any]) -> list[Any]:
return list(audio_latents)
def _normalize_selected_group_indices(
selected_group_indices: Sequence[int] | None,
physical_group_count: int,
) -> tuple[tuple[int, ...], bool]:
"""Validate an optional internal physical-group selection."""
if selected_group_indices is None:
return tuple(range(physical_group_count)), False
if (
not isinstance(selected_group_indices, Sequence)
or isinstance(selected_group_indices, (str, bytes))
or not selected_group_indices
):
raise SecondPassContractError(
"selected physical groups must be a non-empty integer sequence"
)
selected = tuple(selected_group_indices)
if any(type(index) is not int for index in selected):
raise SecondPassContractError(
"selected physical group indices must be integers"
)
if len(set(selected)) != len(selected):
raise SecondPassContractError("selected physical groups contain duplicates")
if tuple(sorted(selected)) != selected:
raise SecondPassContractError(
"selected physical groups must follow physical execution order"
)
if selected[0] < 0 or selected[-1] >= physical_group_count:
raise SecondPassContractError("selected physical group index is out of range")
return selected, True
def update_second_pass_geometry(
assembly_plan: Mapping[str, Any],
video_latents: Sequence[Any],
@@ -189,6 +230,7 @@ def prepare_physical_refine_groups(
adapt_group_conditioning_fn=None,
group_consumer_fn=None,
retain_group_outputs: bool = True,
selected_group_indices: Sequence[int] | None = None,
) -> dict[str, Any]:
"""Prepare one MODEL and one complete CONDITIONING per physical group.
@@ -202,6 +244,11 @@ def prepare_physical_refine_groups(
video_latents,
assembly_plan,
)
selected_indices, selection_active = _normalize_selected_group_indices(
selected_group_indices,
len(groups),
)
selected_index_set = set(selected_indices)
encode_prompt_fn = encode_prompt_fn or encode_prompt_conditioning
clone_model_fn = clone_model_fn or clone_model_for_chunk
validate_refine_context_fn = validate_refine_context_fn or validate_refine_context
@@ -248,6 +295,8 @@ def prepare_physical_refine_groups(
group_conditioning: list[list[Any]] = []
details: list[dict[str, Any]] = []
for group_index, group in enumerate(groups):
if group_index not in selected_index_set:
continue
captured_group = (
captured_groups[group_index] if captured_groups is not None else None
)
@@ -344,11 +393,12 @@ def prepare_physical_refine_groups(
details.append(detail)
physical_group_count = len(groups)
selected_group_count = len(selected_indices)
if retain_group_outputs and not (
len(group_models)
== len(group_conditioning)
== len(details)
== physical_group_count
== selected_group_count
):
raise SecondPassContractError(
"prepared MODEL/CONDITIONING physical group counts differ"
@@ -367,6 +417,9 @@ def prepare_physical_refine_groups(
"details": details,
"warnings": warnings,
"physical_group_count": physical_group_count,
"selected_group_count": selected_group_count,
"selected_group_indices": list(selected_indices),
"selection_active": selection_active,
"target_latent_h": target_h,
"target_latent_w": target_w,
}
@@ -394,6 +447,8 @@ def run_second_pass_groups(
validate_refine_context_fn=None,
adapt_group_conditioning_fn=None,
refine_schedule: RefineSchedule | None = None,
selected_group_indices: Sequence[int] | None = None,
temporal_windows_by_group: Mapping[int, Any] | None = None,
) -> tuple[list[dict[str, Any]], list[Any], dict[str, Any], str]:
"""Refine complete physical groups while preserving first-pass audio exactly."""
@@ -405,10 +460,16 @@ def run_second_pass_groups(
effective_sigmas = resolved_schedule.sigmas
schedule_contract = serializable_schedule_contract(resolved_schedule)
groups = _contract_groups(assembly_plan)
selected_indices, selection_active = _normalize_selected_group_indices(
selected_group_indices,
len(groups),
)
latent_builder = latent_builder or latent_from_cpu
sample_fn = sample_fn or sample_refine_chunk
stream_extractor = stream_extractor or extract_av_streams
refined_videos: list[dict[str, Any]] = []
refined_videos: list[dict[str, Any]] = (
list(video_latents) if selection_active else []
)
group_seeds: list[int] = []
conditioning_sources: list[str] = []
group_report_lines: list[str] = []
@@ -432,7 +493,7 @@ def run_second_pass_groups(
group_seeds.append(physical_seed)
conditioning_sources.append(conditioning_source)
nested_latent = latent_builder(video_samples, audio_samples)
sampled = sample_fn(
sample_arguments = dict(
model=chunk_model,
conditioning=conditioning,
latent=nested_latent,
@@ -441,6 +502,14 @@ def run_second_pass_groups(
seed=physical_seed,
enable_preview=bool(enable_preview),
)
if temporal_windows_by_group is not None:
temporal_window = temporal_windows_by_group.get(group_index)
if temporal_window is None:
raise SecondPassContractError(
f"selected physical group {group_index + 1} has no temporal window"
)
sample_arguments["temporal_window"] = temporal_window
sampled = sample_fn(**sample_arguments)
refined_video, _temporary_audio = stream_extractor(sampled)
if tuple(refined_video.shape) != tuple(video_samples.shape):
raise SecondPassContractError(
@@ -452,7 +521,10 @@ def run_second_pass_groups(
)
output_latent = dict(video_latent)
output_latent["samples"] = refined_video
refined_videos.append(output_latent)
if selection_active:
refined_videos[group_index] = output_latent
else:
refined_videos.append(output_latent)
group_report_lines.append(
"group "
f"{group_index + 1}: logical_chunks={group.get('logical_chunks')}, "
@@ -491,7 +563,12 @@ def run_second_pass_groups(
adapt_group_conditioning_fn=adapt_group_conditioning_fn,
group_consumer_fn=sample_prepared_group,
retain_group_outputs=False,
selected_group_indices=(selected_indices if selection_active else None),
)
if len(group_seeds) != len(selected_indices):
raise SecondPassContractError(
"Video refine Sampling count differs from selected physical group count"
)
report_lines = [
"H3 Continuum Second Pass V3.5",
"Mode: context-aware physical-group refine when a complete First Pass "
@@ -509,6 +586,14 @@ def run_second_pass_groups(
*prepared["warnings"],
*group_report_lines,
]
if selection_active:
report_lines.insert(
3,
"Selected physical groups: "
+ ", ".join(str(index + 1) for index in selected_indices)
+ "; non-selected groups were exact object passthrough with no "
"conditioning, MODEL clone, Sampling, or seed derivation.",
)
passthrough_audio = passthrough_audio_latents(audio_latents)
updated_plan = prepared["updated_assembly_plan"]
+274 -1
View File
@@ -4,7 +4,43 @@ from __future__ import annotations
from typing import Any
from .refine_target import MODE_AUDIO_ONLY, MODE_VIDEO_AUDIO, MODE_VIDEO_ONLY
from .refine_scope import MODE_ALL, MODE_LOGICAL_CHUNK, MODE_PHYSICAL_GROUP
from .refine_window import MODE_TIME_WINDOW
from .second_pass import run_second_pass_groups
from .targeted_second_pass import run_targeted_second_pass_groups
REFINE_TARGET_VIDEO_ONLY = "Video Only"
REFINE_TARGET_AUDIO_ONLY = "Audio Only"
REFINE_TARGET_VIDEO_AUDIO = "Video + Audio"
REFINE_TARGET_OPTIONS = (
REFINE_TARGET_VIDEO_ONLY,
REFINE_TARGET_AUDIO_ONLY,
REFINE_TARGET_VIDEO_AUDIO,
)
_REFINE_TARGET_MODES = {
REFINE_TARGET_VIDEO_ONLY: MODE_VIDEO_ONLY,
REFINE_TARGET_AUDIO_ONLY: MODE_AUDIO_ONLY,
REFINE_TARGET_VIDEO_AUDIO: MODE_VIDEO_AUDIO,
}
REFINE_SCOPE_ALL = "All"
REFINE_SCOPE_PHYSICAL_GROUP = "Physical Group"
REFINE_SCOPE_LOGICAL_CHUNK = "Logical Chunk"
REFINE_SCOPE_TIME_WINDOW = "Time Window"
REFINE_SCOPE_OPTIONS = (
REFINE_SCOPE_ALL,
REFINE_SCOPE_PHYSICAL_GROUP,
REFINE_SCOPE_LOGICAL_CHUNK,
REFINE_SCOPE_TIME_WINDOW,
)
_REFINE_SCOPE_MODES = {
REFINE_SCOPE_ALL: MODE_ALL,
REFINE_SCOPE_PHYSICAL_GROUP: MODE_PHYSICAL_GROUP,
REFINE_SCOPE_LOGICAL_CHUNK: MODE_LOGICAL_CHUNK,
REFINE_SCOPE_TIME_WINDOW: MODE_TIME_WINDOW,
}
def _single_list_input(name: str, value: Any) -> Any:
@@ -103,10 +139,247 @@ class H3ContinuumSecondPassV35:
)
def resolve_selective_refine_target(value: str) -> str:
"""Resolve one public UI label to the versioned internal target mode."""
try:
return _REFINE_TARGET_MODES[value]
except (KeyError, TypeError) as exc:
raise ValueError(f"unsupported selective refine target {value!r}") from exc
def resolve_selective_refine_scope(value: str) -> str:
"""Resolve one public UI label to the versioned internal scope mode."""
try:
return _REFINE_SCOPE_MODES[value]
except (KeyError, TypeError) as exc:
raise ValueError(f"unsupported selective refine scope {value!r}") from exc
def _selective_status_prefix(
label: str,
physical_group_count: int,
scope_label: str,
scope_index: int,
window_start_sec: float,
window_end_sec: float,
) -> str:
if label == REFINE_TARGET_VIDEO_ONLY:
detail = "Video=refined; Audio=bit-exact passthrough"
elif label == REFINE_TARGET_AUDIO_ONLY:
detail = "Experimental / Production HOLD; Video=locked; Audio=refined"
elif label == REFINE_TARGET_VIDEO_AUDIO:
detail = (
"GPU Experimental PASS / Production HOLD; "
"Video=refined; Audio=refined"
)
else:
raise ValueError(f"unsupported selective refine target {label!r}")
if scope_label == REFINE_SCOPE_ALL:
scope_detail = "."
elif scope_label == REFINE_SCOPE_TIME_WINDOW:
scope_detail = f" [{window_start_sec:g}, {window_end_sec:g}) sec."
else:
scope_detail = f" {scope_index}."
return (
f"Selective Refine: {label}; {detail}; "
f"physical groups={physical_group_count}; scope={scope_label}"
+ scope_detail
)
class H3ContinuumSelectiveSecondPassExperimental:
"""Experimental public adapter for versioned selective-refine targets."""
DEPRECATED = False
DESCRIPTION = (
"Experimental Selective Second Pass for MiniMax H3. Video Only preserves "
"compatibility with the existing Continuum Second Pass. Audio Only keeps "
"the input video locked and refines audio. Video + Audio refines both AV "
"streams. Audio-targeted modes remain Experimental while upstream H3 "
"denoise-mask correctness is under review. Chunk scope skips complete "
"physical groups without conditioning, model clone, Sampling, or seed use; "
"a logical chunk inside Terminal Merge expands to the complete pair. Time "
"Window uses the final visible output timeline, protects continuation "
"prefixes, and restores every out-of-window latent position bit-exactly."
)
@classmethod
def INPUT_TYPES(cls):
return {
"required": {
"model": ("MODEL",),
"clip": ("CLIP",),
"sampler": ("SAMPLER",),
"sigmas": ("SIGMAS",),
"video_latents": ("LATENT",),
"audio_latents": ("LATENT",),
"assembly_plan": ("H3_CONTINUUM_ASSEMBLY_PLAN",),
"refine_seed": (
"INT",
{
"default": 0,
"min": 0,
"max": 0xFFFFFFFFFFFFFFFF,
"control_after_generate": True,
"tooltip": "Base seed independently derived once per physical group.",
},
),
"refine_target": (
REFINE_TARGET_OPTIONS,
{"default": REFINE_TARGET_VIDEO_ONLY},
),
"refine_scope": (
REFINE_SCOPE_OPTIONS,
{"default": REFINE_SCOPE_ALL},
),
"refine_scope_index": (
"INT",
{
"default": 1,
"min": 1,
"max": 0x7FFFFFFF,
"tooltip": (
"1-based physical-group or logical-chunk number. "
"Ignored when Refine Scope is All or Time Window."
),
},
),
"window_start_sec": (
"FLOAT",
{
"default": 0.0,
"min": 0.0,
"max": 86400.0,
"step": 0.01,
"tooltip": (
"Time Window start on the final visible output timeline. "
"Ignored by other Refine Scope modes."
),
},
),
"window_end_sec": (
"FLOAT",
{
"default": 5.0,
"min": 0.01,
"max": 86400.0,
"step": 0.01,
"tooltip": (
"Exclusive Time Window end on the final visible output "
"timeline. Ignored by other Refine Scope modes."
),
},
),
},
"optional": {
"refine_context": ("H3_CONTINUUM_REFINE_CONTEXT",),
"video_vae": ("VAE",),
},
}
INPUT_IS_LIST = True
RETURN_TYPES = ("LATENT", "LATENT", "H3_CONTINUUM_ASSEMBLY_PLAN", "STRING")
RETURN_NAMES = (
"refined_video_latents",
"audio_latents",
"updated_assembly_plan",
"status",
)
OUTPUT_IS_LIST = (True, True, False, False)
FUNCTION = "refine"
CATEGORY = "MiniMax H3/Continuum/Advanced"
def refine(
self,
model,
clip,
sampler,
sigmas,
video_latents,
audio_latents,
assembly_plan,
refine_seed,
refine_target,
refine_scope=None,
refine_scope_index=None,
window_start_sec=None,
window_end_sec=None,
refine_context=None,
video_vae=None,
refine_schedule=None,
):
label = _single_list_input("refine_target", refine_target)
target_mode = resolve_selective_refine_target(label)
scope_label = (
REFINE_SCOPE_ALL
if refine_scope is None
else _single_list_input("refine_scope", refine_scope)
)
scope_mode = resolve_selective_refine_scope(scope_label)
resolved_scope_index = (
1
if refine_scope_index is None
else int(_single_list_input("refine_scope_index", refine_scope_index))
)
resolved_window_start = (
0.0
if window_start_sec is None
else float(_single_list_input("window_start_sec", window_start_sec))
)
resolved_window_end = (
5.0
if window_end_sec is None
else float(_single_list_input("window_end_sec", window_end_sec))
)
videos, audios, updated_plan, status = run_targeted_second_pass_groups(
model=_single_list_input("model", model),
clip=_single_list_input("clip", clip),
sampler=_single_list_input("sampler", sampler),
sigmas=_single_list_input("sigmas", sigmas),
video_latents=video_latents,
audio_latents=audio_latents,
assembly_plan=_single_list_input("assembly_plan", assembly_plan),
refine_seed=int(_single_list_input("refine_seed", refine_seed)),
refine_target=target_mode,
refine_scope=scope_mode,
refine_scope_index=resolved_scope_index,
window_start_sec=resolved_window_start,
window_end_sec=resolved_window_end,
refine_context=(
None
if refine_context is None
else _single_list_input("refine_context", refine_context)
),
video_vae=(
None
if video_vae is None
else _single_list_input("video_vae", video_vae)
),
refine_schedule=refine_schedule,
)
prefix = _selective_status_prefix(
label,
len(video_latents),
scope_label,
resolved_scope_index,
resolved_window_start,
resolved_window_end,
)
return videos, audios, updated_plan, f"{prefix}\n{status}"
NODE_CLASS_MAPPINGS = {
"H3ContinuumSecondPassV35": H3ContinuumSecondPassV35,
"H3ContinuumSelectiveSecondPassExperimental": (
H3ContinuumSelectiveSecondPassExperimental
),
}
NODE_DISPLAY_NAME_MAPPINGS = {
"H3ContinuumSecondPassV35": "H3 Continuum Second Pass V3.5",
"H3ContinuumSecondPassV35": "H3 Continuum Second Pass",
"H3ContinuumSelectiveSecondPassExperimental": (
"H3 Continuum Selective Second Pass (Experimental)"
),
}
+496
View File
@@ -0,0 +1,496 @@
"""Target-aware refinement sampling for frozen Video and Audio policies."""
from __future__ import annotations
from typing import Any, Callable
import torch
from ..state import extract_av_streams
from .refine_sampling import (
RefineSamplingRuntimeError,
_load_runtime_modules,
_make_basic_guider,
sample_refine_chunk,
)
from .refine_target import (
MODE_AUDIO_ONLY,
MODE_VIDEO_AUDIO,
MODE_VIDEO_ONLY,
RefineTarget,
RefineTargetError,
resolve_refine_target,
)
from .refine_window import GroupTemporalWindow
class TargetedRefineExecutionUnavailable(RefineTargetError):
"""Raised before Sampling when a future target mode is not implemented."""
def _validate_ranges(
ranges: tuple[tuple[int, int], ...],
length: int,
*,
name: str,
) -> tuple[tuple[int, int], ...]:
if not ranges:
raise RefineSamplingRuntimeError(f"{name} temporal window is empty")
previous_stop = 0
for start, stop in ranges:
if start < previous_stop or stop <= start or stop > int(length):
raise RefineSamplingRuntimeError(
f"{name} temporal window is outside its latent length"
)
previous_stop = stop
return ranges
def _window_masks(
video: torch.Tensor,
audio: torch.Tensor,
temporal_window: GroupTemporalWindow,
) -> tuple[torch.Tensor, torch.Tensor]:
if not isinstance(temporal_window, GroupTemporalWindow):
raise RefineSamplingRuntimeError(
"temporal window must be a resolved GroupTemporalWindow"
)
video_ranges = _validate_ranges(
temporal_window.video_slot_ranges,
int(video.shape[2]),
name="Video",
)
audio_ranges = _validate_ranges(
temporal_window.audio_tick_ranges,
int(audio.shape[-1]),
name="Audio",
)
video_mask = torch.zeros(
(
int(video.shape[0]),
1,
int(video.shape[2]),
int(video.shape[3]),
int(video.shape[4]),
),
dtype=torch.float32,
device="cpu",
)
audio_mask = torch.zeros(
(
int(audio.shape[0]),
1,
int(audio.shape[2]),
int(audio.shape[3]),
),
dtype=torch.float32,
device="cpu",
)
for start, stop in video_ranges:
video_mask[:, :, start:stop] = 1.0
for start, stop in audio_ranges:
audio_mask[..., start:stop] = 1.0
return video_mask, audio_mask
def _prepare_video_only_noise_and_mask(
video: torch.Tensor,
audio: torch.Tensor,
*,
seed: int,
batch_inds: Any = None,
prepare_noise_fn: Callable[[torch.Tensor, int, Any], torch.Tensor],
nested_builder: Callable[[tuple[torch.Tensor, torch.Tensor]], Any],
temporal_window: GroupTemporalWindow,
) -> tuple[Any, Any]:
"""Build windowed Video noise/mask while locking Audio completely."""
video_noise = prepare_noise_fn(video, int(seed), batch_inds)
if not torch.is_tensor(video_noise) or tuple(video_noise.shape) != tuple(video.shape):
raise RefineSamplingRuntimeError(
"ComfyUI returned invalid Video Only noise geometry"
)
video_mask, _audio_window_mask = _window_masks(video, audio, temporal_window)
audio_noise = torch.zeros_like(audio, device="cpu")
audio_mask = torch.zeros(
(int(audio.shape[0]), 1, 1, 1),
dtype=torch.float32,
device="cpu",
)
return (
nested_builder((video_noise, audio_noise)),
nested_builder((video_mask, audio_mask)),
)
def require_video_only_execution(
refine_target: RefineTarget | str | None,
) -> RefineTarget:
target = resolve_refine_target(refine_target)
if target.mode != MODE_VIDEO_ONLY:
raise TargetedRefineExecutionUnavailable(
f"refine target {target.mode!r} is contract-only in Phase A1"
)
return target
def _prepare_audio_only_noise_and_mask(
video: torch.Tensor,
audio: torch.Tensor,
*,
seed: int,
batch_inds: Any = None,
prepare_noise_fn: Callable[[torch.Tensor, int, Any], torch.Tensor],
nested_builder: Callable[[tuple[torch.Tensor, torch.Tensor]], Any],
temporal_window: GroupTemporalWindow | None = None,
) -> tuple[Any, Any]:
"""Build zero/locked Video and seeded-random/sampled Audio streams."""
if video.ndim != 5 or audio.ndim != 4:
raise RefineSamplingRuntimeError(
"targeted latent must contain video [B,C,T,H,W] and audio [B,C,2,T]"
)
if int(video.shape[0]) != int(audio.shape[0]):
raise RefineSamplingRuntimeError("targeted video/audio batch sizes differ")
audio_noise = prepare_noise_fn(audio, int(seed), batch_inds)
if not torch.is_tensor(audio_noise) or tuple(audio_noise.shape) != tuple(audio.shape):
raise RefineSamplingRuntimeError(
"ComfyUI returned invalid Audio Only noise geometry"
)
video_noise = torch.zeros_like(video, device="cpu")
if temporal_window is None:
video_mask = torch.zeros(
(int(video.shape[0]), 1, 1, 1, 1),
dtype=torch.float32,
device="cpu",
)
audio_mask = torch.ones(
(int(audio.shape[0]), 1, 1, 1),
dtype=torch.float32,
device="cpu",
)
else:
_video_window_mask, audio_mask = _window_masks(
video,
audio,
temporal_window,
)
video_mask = torch.zeros(
(int(video.shape[0]), 1, 1, 1, 1),
dtype=torch.float32,
device="cpu",
)
noise = nested_builder((video_noise, audio_noise))
noise_mask = nested_builder((video_mask, audio_mask))
return noise, noise_mask
def _prepare_video_audio_noise_and_mask(
video: torch.Tensor,
audio: torch.Tensor,
*,
seed: int,
batch_inds: Any = None,
prepare_noise_fn: Callable[[torch.Tensor, int, Any], torch.Tensor],
nested_builder: Callable[[tuple[torch.Tensor, torch.Tensor]], Any],
temporal_window: GroupTemporalWindow | None = None,
) -> tuple[Any, Any]:
"""Build seeded-random noise and sampled masks for both AV streams."""
if video.ndim != 5 or audio.ndim != 4:
raise RefineSamplingRuntimeError(
"targeted latent must contain video [B,C,T,H,W] and audio [B,C,2,T]"
)
if int(video.shape[0]) != int(audio.shape[0]):
raise RefineSamplingRuntimeError("targeted video/audio batch sizes differ")
video_noise = prepare_noise_fn(video, int(seed), batch_inds)
audio_noise = prepare_noise_fn(audio, int(seed), batch_inds)
if not torch.is_tensor(video_noise) or tuple(video_noise.shape) != tuple(video.shape):
raise RefineSamplingRuntimeError(
"ComfyUI returned invalid Video + Audio video noise geometry"
)
if not torch.is_tensor(audio_noise) or tuple(audio_noise.shape) != tuple(audio.shape):
raise RefineSamplingRuntimeError(
"ComfyUI returned invalid Video + Audio audio noise geometry"
)
if temporal_window is None:
video_mask = torch.ones(
(int(video.shape[0]), 1, 1, 1, 1),
dtype=torch.float32,
device="cpu",
)
audio_mask = torch.ones(
(int(audio.shape[0]), 1, 1, 1),
dtype=torch.float32,
device="cpu",
)
else:
video_mask, audio_mask = _window_masks(video, audio, temporal_window)
noise = nested_builder((video_noise, audio_noise))
noise_mask = nested_builder((video_mask, audio_mask))
return noise, noise_mask
def _sample_with_target_noise_and_mask(
*,
model: Any,
conditioning: list,
latent: dict[str, Any],
sampler: Any,
sigmas: torch.Tensor,
seed: int,
enable_preview: bool,
noise_mask_builder: Callable[..., tuple[Any, Any]],
temporal_window: GroupTemporalWindow | None = None,
restore_video_outside_window: bool = False,
restore_audio_outside_window: bool = False,
) -> dict[str, Any]:
"""Run Core once after constructing one explicit AV target policy."""
if not isinstance(latent, dict) or "samples" not in latent:
raise RefineSamplingRuntimeError("latent must be a ComfyUI LATENT dictionary")
if not torch.is_tensor(sigmas) or sigmas.ndim != 1 or sigmas.numel() < 2:
raise RefineSamplingRuntimeError("sigmas must contain at least two values")
model_management, nested_tensor, comfy_sample, comfy_utils, preview = (
_load_runtime_modules()
)
working = latent.copy()
latent_image = comfy_sample.fix_empty_latent_channels(
model,
working["samples"],
working.get("downscale_ratio_spacial"),
working.get("downscale_ratio_temporal"),
)
working["samples"] = latent_image
video, audio = extract_av_streams(working)
noise, noise_mask = noise_mask_builder(
video,
audio,
seed=int(seed),
batch_inds=working.get("batch_index"),
prepare_noise_fn=comfy_sample.prepare_noise,
nested_builder=nested_tensor.NestedTensor,
temporal_window=temporal_window,
)
guider = _make_basic_guider(model, conditioning)
x0_output: dict[str, Any] = {}
callback = None
if enable_preview:
callback = preview.prepare_callback(
model,
int(sigmas.shape[-1]) - 1,
x0_output,
)
samples = guider.sample(
noise,
latent_image,
sampler,
sigmas,
denoise_mask=noise_mask,
callback=callback,
disable_pbar=not comfy_utils.PROGRESS_BAR_ENABLED,
seed=int(seed),
)
samples = samples.to(model_management.intermediate_device())
if temporal_window is not None:
sampled_output = {"samples": samples}
sampled_video, sampled_audio = extract_av_streams(sampled_output)
if restore_video_outside_window:
sampled_video = _restore_outside_temporal_ranges(
sampled_video,
video,
temporal_window.video_slot_ranges,
time_dim=2,
name="Video",
)
if restore_audio_outside_window:
sampled_audio = _restore_outside_temporal_ranges(
sampled_audio,
audio,
temporal_window.audio_tick_ranges,
time_dim=-1,
name="Audio",
)
samples = nested_tensor.NestedTensor((sampled_video, sampled_audio))
output = working.copy()
output.pop("downscale_ratio_spacial", None)
output.pop("downscale_ratio_temporal", None)
output["samples"] = samples
extract_av_streams(output)
return output
def _restore_outside_temporal_ranges(
sampled: torch.Tensor,
source: torch.Tensor,
ranges: tuple[tuple[int, int], ...],
*,
time_dim: int,
name: str,
) -> torch.Tensor:
"""Restore every inactive temporal position from the input bit-exactly."""
if not torch.is_tensor(sampled) or not torch.is_tensor(source):
raise RefineSamplingRuntimeError(f"{name} temporal restore requires Tensors")
if tuple(sampled.shape) != tuple(source.shape):
raise RefineSamplingRuntimeError(
f"{name} temporal restore input/output shapes differ"
)
if sampled.dtype != source.dtype:
raise RefineSamplingRuntimeError(
f"{name} temporal restore input/output dtypes differ"
)
dim = int(time_dim)
if dim < 0:
dim += sampled.ndim
if dim < 0 or dim >= sampled.ndim:
raise RefineSamplingRuntimeError(f"{name} temporal restore dimension is invalid")
validated = _validate_ranges(ranges, int(sampled.shape[dim]), name=name)
restored = sampled.clone()
original = source.to(device=restored.device)
cursor = 0
for start, stop in validated:
if start > cursor:
restored.narrow(dim, cursor, start - cursor).copy_(
original.narrow(dim, cursor, start - cursor)
)
cursor = stop
if cursor < int(restored.shape[dim]):
restored.narrow(dim, cursor, int(restored.shape[dim]) - cursor).copy_(
original.narrow(dim, cursor, int(restored.shape[dim]) - cursor)
)
return restored
def sample_video_only_window_refine_chunk(
*,
model: Any,
conditioning: list,
latent: dict[str, Any],
sampler: Any,
sigmas: torch.Tensor,
seed: int,
temporal_window: GroupTemporalWindow,
enable_preview: bool = True,
) -> dict[str, Any]:
"""Refine only selected Video slots and restore all other AV positions."""
return _sample_with_target_noise_and_mask(
model=model,
conditioning=conditioning,
latent=latent,
sampler=sampler,
sigmas=sigmas,
seed=int(seed),
enable_preview=bool(enable_preview),
noise_mask_builder=_prepare_video_only_noise_and_mask,
temporal_window=temporal_window,
restore_video_outside_window=True,
restore_audio_outside_window=True,
)
def sample_audio_only_refine_chunk(
*,
model: Any,
conditioning: list,
latent: dict[str, Any],
sampler: Any,
sigmas: torch.Tensor,
seed: int,
temporal_window: GroupTemporalWindow | None = None,
enable_preview: bool = True,
) -> dict[str, Any]:
"""Sample Audio while Core carries Video with zero noise and mask zero."""
return _sample_with_target_noise_and_mask(
model=model,
conditioning=conditioning,
latent=latent,
sampler=sampler,
sigmas=sigmas,
seed=int(seed),
enable_preview=bool(enable_preview),
noise_mask_builder=_prepare_audio_only_noise_and_mask,
temporal_window=temporal_window,
restore_video_outside_window=temporal_window is not None,
restore_audio_outside_window=temporal_window is not None,
)
def sample_video_audio_refine_chunk(
*,
model: Any,
conditioning: list,
latent: dict[str, Any],
sampler: Any,
sigmas: torch.Tensor,
seed: int,
temporal_window: GroupTemporalWindow | None = None,
enable_preview: bool = True,
) -> dict[str, Any]:
"""Sample and adopt both Video and Audio using mask one for each stream."""
return _sample_with_target_noise_and_mask(
model=model,
conditioning=conditioning,
latent=latent,
sampler=sampler,
sigmas=sigmas,
seed=int(seed),
enable_preview=bool(enable_preview),
noise_mask_builder=_prepare_video_audio_noise_and_mask,
temporal_window=temporal_window,
restore_video_outside_window=temporal_window is not None,
restore_audio_outside_window=temporal_window is not None,
)
def sample_targeted_refine_chunk(
*,
model: Any,
conditioning: list,
latent: dict[str, Any],
sampler: Any,
sigmas: torch.Tensor,
seed: int,
refine_target: RefineTarget | str | None = MODE_VIDEO_ONLY,
temporal_window: GroupTemporalWindow | None = None,
enable_preview: bool = True,
legacy_sample_fn: Callable[..., dict[str, Any]] | None = None,
video_only_window_sample_fn: Callable[..., dict[str, Any]] | None = None,
audio_only_sample_fn: Callable[..., dict[str, Any]] | None = None,
video_audio_sample_fn: Callable[..., dict[str, Any]] | None = None,
) -> dict[str, Any]:
"""Dispatch an implemented target without changing its stream policy."""
target = resolve_refine_target(refine_target)
if target.mode == MODE_VIDEO_ONLY and temporal_window is not None:
sample_fn = video_only_window_sample_fn or sample_video_only_window_refine_chunk
elif target.mode == MODE_VIDEO_ONLY:
sample_fn = legacy_sample_fn or sample_refine_chunk
elif target.mode == MODE_AUDIO_ONLY:
sample_fn = audio_only_sample_fn or sample_audio_only_refine_chunk
elif target.mode == MODE_VIDEO_AUDIO:
sample_fn = video_audio_sample_fn or sample_video_audio_refine_chunk
else: # pragma: no cover - resolve_refine_target validates the mode.
raise TargetedRefineExecutionUnavailable(
f"refine target {target.mode!r} is unavailable"
)
arguments = dict(
model=model,
conditioning=conditioning,
latent=latent,
sampler=sampler,
sigmas=sigmas,
seed=int(seed),
enable_preview=bool(enable_preview),
)
if temporal_window is not None:
arguments["temporal_window"] = temporal_window
return sample_fn(**arguments)
+491
View File
@@ -0,0 +1,491 @@
"""Target-aware Second Pass orchestration over complete physical groups."""
from __future__ import annotations
from collections.abc import Mapping, Sequence
from typing import Any
import torch
from ..state import extract_av_streams
from ..v2.sampling import latent_from_cpu
from .refine_schedule import (
RefineScheduleError,
resolve_refine_schedule,
serializable_schedule_contract,
)
from .refine_scope import (
MODE_ALL as SCOPE_ALL,
resolve_refine_scope,
)
from .refine_target import (
MODE_AUDIO_ONLY,
MODE_VIDEO_AUDIO,
MODE_VIDEO_ONLY,
RefineTarget,
build_target_execution_contract,
derive_target_refine_seed,
resolve_refine_target,
serializable_target_contract,
)
from .refine_window import (
MODE_TIME_WINDOW,
GroupTemporalWindow,
RefineWindow,
resolve_refine_window,
)
from .second_pass import (
SecondPassContractError,
_normalize_selected_group_indices,
_latent_samples,
prepare_physical_refine_groups,
run_second_pass_groups,
validate_second_pass_inputs,
)
from .targeted_refine_sampling import (
TargetedRefineExecutionUnavailable,
sample_targeted_refine_chunk,
)
def _attach_target_contract(
updated_plan: dict[str, Any],
target: RefineTarget,
) -> None:
contract = updated_plan.get("second_pass_contract")
if not isinstance(contract, dict):
raise SecondPassContractError(
"targeted Second Pass output has no mutable contract"
)
if contract.get("version") != 1:
raise SecondPassContractError(
"targeted Second Pass must preserve contract version 1"
)
schedule_contract = contract.get("refine_schedule")
contract["refine_target_contract"] = serializable_target_contract(target)
contract["refine_execution_contract"] = build_target_execution_contract(
target,
schedule_contract,
)
def _run_video_only_groups(
*,
target: RefineTarget,
sample_fn,
arguments: dict[str, Any],
selected_group_indices: Sequence[int] | None = None,
temporal_windows_by_group: Mapping[int, GroupTemporalWindow] | None = None,
) -> tuple[list[dict[str, Any]], list[Any], dict[str, Any], str]:
def targeted_sample(**kwargs):
return sample_targeted_refine_chunk(
refine_target=target,
legacy_sample_fn=sample_fn,
video_only_window_sample_fn=sample_fn,
**kwargs,
)
videos, audios, updated_plan, status = run_second_pass_groups(
**arguments,
sample_fn=targeted_sample,
selected_group_indices=selected_group_indices,
temporal_windows_by_group=temporal_windows_by_group,
)
_attach_target_contract(updated_plan, target)
return videos, audios, updated_plan, status
def _run_sampled_target_groups(
*,
target: RefineTarget,
model: Any,
clip: Any,
sampler: Any,
sigmas: torch.Tensor,
video_latents: Sequence[Any],
audio_latents: Sequence[Any],
assembly_plan: Mapping[str, Any],
refine_seed: int,
refine_context: Any,
video_vae: Any,
conditioning_upscale_method: str,
enable_preview: bool,
encode_prompt_fn,
latent_builder,
sample_fn,
stream_extractor,
clone_model_fn,
validate_refine_context_fn,
adapt_group_conditioning_fn,
refine_schedule,
selected_group_indices: Sequence[int] | None = None,
temporal_windows_by_group: Mapping[int, GroupTemporalWindow] | None = None,
) -> tuple[list[Any], list[dict[str, Any]], dict[str, Any], str]:
"""Sample one non-legacy target and adopt only its configured outputs."""
if target.mode not in (MODE_AUDIO_ONLY, MODE_VIDEO_AUDIO):
raise TargetedRefineExecutionUnavailable(
f"refine target {target.mode!r} is not a sampled-stream target"
)
adopt_sampled_video = target.mode == MODE_VIDEO_AUDIO
validation = validate_second_pass_inputs(
video_latents,
audio_latents,
assembly_plan,
)
selected_indices, selection_active = _normalize_selected_group_indices(
selected_group_indices,
int(validation["physical_group_count"]),
)
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)
latent_builder = latent_builder or latent_from_cpu
stream_extractor = stream_extractor or extract_av_streams
refined_videos: list[dict[str, Any]] = (
list(video_latents) if selection_active else []
)
refined_audios: list[dict[str, Any]] = (
list(audio_latents) if selection_active else []
)
group_seeds: list[int] = []
conditioning_sources: list[str] = []
group_report_lines: list[str] = []
def sample_prepared_group(
group_index,
video_latent,
group,
chunk_model,
conditioning,
detail,
):
audio_latent = audio_latents[group_index]
video_samples = _latent_samples(
video_latent,
name=f"video_latents[{group_index}]",
)
audio_samples = _latent_samples(
audio_latent,
name=f"audio_latents[{group_index}]",
)
physical_seed = derive_target_refine_seed(
int(refine_seed),
group_index,
target,
)
group_seeds.append(physical_seed)
conditioning_source = str(detail["conditioning_source"])
conditioning_sources.append(conditioning_source)
nested_latent = latent_builder(video_samples, audio_samples)
sample_arguments = dict(
model=chunk_model,
conditioning=conditioning,
latent=nested_latent,
sampler=sampler,
sigmas=effective_sigmas,
seed=physical_seed,
refine_target=target,
enable_preview=bool(enable_preview),
audio_only_sample_fn=sample_fn,
video_audio_sample_fn=sample_fn,
)
if temporal_windows_by_group is not None:
temporal_window = temporal_windows_by_group.get(group_index)
if temporal_window is None:
raise SecondPassContractError(
f"selected physical group {group_index + 1} has no temporal window"
)
sample_arguments["temporal_window"] = temporal_window
sampled = sample_targeted_refine_chunk(**sample_arguments)
sampled_video, sampled_audio = stream_extractor(sampled)
if tuple(sampled_video.shape) != tuple(video_samples.shape):
raise SecondPassContractError(
f"sampled video group {group_index} changed B/C/T/H/W geometry"
)
if tuple(sampled_audio.shape) != tuple(audio_samples.shape):
raise SecondPassContractError(
f"refined audio group {group_index} changed B/C/stereo/T geometry"
)
if not bool(torch.isfinite(sampled_audio.float()).all().item()):
raise SecondPassContractError(
f"refined audio group {group_index} contains NaN or Inf"
)
if adopt_sampled_video:
if not bool(torch.isfinite(sampled_video.float()).all().item()):
raise SecondPassContractError(
f"refined video group {group_index} contains NaN or Inf"
)
output_video = dict(video_latent)
output_video["samples"] = sampled_video
if selection_active:
refined_videos[group_index] = output_video
else:
refined_videos.append(output_video)
output_audio = dict(audio_latent)
output_audio["samples"] = sampled_audio
if selection_active:
refined_audios[group_index] = output_audio
else:
refined_audios.append(output_audio)
adoption = (
f"video_shape={tuple(sampled_video.shape)}, "
"sampled_video_adopted=true, sampled_audio_adopted=true"
if adopt_sampled_video
else "temporary_video_discarded=true"
)
group_report_lines.append(
"group "
f"{group_index + 1}: logical_chunks={group.get('logical_chunks')}, "
f"prompt_policy={group.get('prompt_policy', 'unknown')}, "
f"conditioning_source={conditioning_source}, "
f"refine_seed={physical_seed}, "
f"audio_shape={tuple(sampled_audio.shape)}, sampling_passes=1, "
f"{adoption}"
)
prepared = prepare_physical_refine_groups(
model=model,
clip=clip,
video_latents=video_latents,
assembly_plan=assembly_plan,
refine_context=refine_context,
video_vae=video_vae,
conditioning_upscale_method=conditioning_upscale_method,
encode_prompt_fn=encode_prompt_fn,
clone_model_fn=clone_model_fn,
validate_refine_context_fn=validate_refine_context_fn,
adapt_group_conditioning_fn=adapt_group_conditioning_fn,
group_consumer_fn=sample_prepared_group,
retain_group_outputs=False,
selected_group_indices=(selected_indices if selection_active else None),
)
expected_groups = int(validation["physical_group_count"])
expected_sampled_groups = len(selected_indices)
if len(group_seeds) != expected_sampled_groups:
raise SecondPassContractError(
"targeted Sampling count differs from selected physical group count"
)
if len(refined_audios) != expected_groups:
raise SecondPassContractError(
"targeted Audio output count differs from physical group count"
)
if adopt_sampled_video and len(refined_videos) != expected_groups:
raise SecondPassContractError(
"targeted Video output count differs from physical group count"
)
output_videos = refined_videos if adopt_sampled_video else list(video_latents)
updated_plan = prepared["updated_assembly_plan"]
contract = updated_plan["second_pass_contract"]
execution_target = "both_sampled" if adopt_sampled_video else "video_locked_audio"
if conditioning_sources and all(
source == "refine_context" for source in conditioning_sources
):
contract["execution"] = (
f"context_aware_physical_groups_{execution_target}_v1"
)
elif any(source == "refine_context" for source in conditioning_sources):
contract["execution"] = f"mixed_context_physical_groups_{execution_target}_v1"
else:
contract["execution"] = f"t2va_physical_groups_{execution_target}_v1"
contract["conditioning_sources"] = conditioning_sources
contract["refine_seed_base"] = int(refine_seed)
contract["refine_group_seeds"] = group_seeds
contract["video_output"] = (
"sampled" if adopt_sampled_video else "bit_exact_first_pass_passthrough"
)
contract["video_sampling"] = (
"seeded_random_mask_1" if adopt_sampled_video else "zero_noise_mask_locked"
)
contract["audio_output"] = "sampled"
contract["audio_sampling"] = "seeded_random_mask_1"
contract["refine_schedule"] = schedule_contract
contract["refine_schedule_identity"] = schedule_contract["schedule_hash"]
_attach_target_contract(updated_plan, target)
if adopt_sampled_video:
target_line = (
"Target: Video + Audio "
"(GPU Experimental PASS / Production HOLD)."
)
sampling_line = (
"Sampling contract: video seeded random noise/mask=1 and adopted "
"sampled output; audio seeded random noise/mask=1 and adopted "
"sampled output."
)
output_line = (
"Outputs: sampled Video and sampled Audio adopted for every complete "
"physical group."
)
else:
target_line = "Target: Audio Only (Experimental / Production HOLD)."
sampling_line = (
"Sampling contract: video zero noise/mask=0 and discarded sampled "
"output; audio seeded random noise/mask=1 and adopted sampled output."
)
output_line = (
"Video output: original first-pass physical Video LATENT objects "
"returned bit-exact; temporary sampled Video discarded."
)
report_lines = [
"H3 Continuum Targeted Second Pass",
target_line,
f"Physical groups: {validation['physical_group_count']}.",
sampling_line,
"RefineSchedule: "
f"schema={schedule_contract['schema_version']}, "
f"mode={schedule_contract['mode']}, "
f"evaluations={schedule_contract['evaluation_count']}, "
f"sigma_hash={schedule_contract['sigma_hash']}.",
*prepared["warnings"],
*group_report_lines,
output_line,
]
if selection_active:
report_lines.insert(
3,
"Selected physical groups: "
+ ", ".join(str(index + 1) for index in selected_indices)
+ "; non-selected groups were exact object passthrough with no "
"conditioning, MODEL clone, Sampling, or seed derivation.",
)
return output_videos, refined_audios, updated_plan, "\n".join(report_lines)
def run_targeted_second_pass_groups(
*,
model: Any,
clip: Any,
sampler: Any,
sigmas: torch.Tensor,
video_latents: Sequence[Any],
audio_latents: Sequence[Any],
assembly_plan: Mapping[str, Any],
refine_seed: int,
refine_target: RefineTarget | str | None = MODE_VIDEO_ONLY,
refine_context: Any = None,
video_vae: Any = None,
conditioning_upscale_method: str = "bilinear",
enable_preview: bool = True,
encode_prompt_fn=None,
latent_builder=None,
sample_fn=None,
stream_extractor=None,
clone_model_fn=None,
validate_refine_context_fn=None,
adapt_group_conditioning_fn=None,
refine_schedule=None,
refine_scope: str | None = SCOPE_ALL,
refine_scope_index: int = 1,
window_start_sec: float = 0.0,
window_end_sec: float = 5.0,
) -> tuple[list[dict[str, Any]], list[Any], dict[str, Any], str]:
"""Run an implemented target without changing the V3.5 public node."""
target = resolve_refine_target(refine_target)
window: RefineWindow | None = None
if isinstance(refine_scope, str) and refine_scope.strip().lower() == MODE_TIME_WINDOW:
scope = None
window = resolve_refine_window(
window_start_sec,
window_end_sec,
assembly_plan,
)
selected_group_indices = window.selected_group_indices
temporal_windows_by_group = {
group.group_index: group for group in window.groups
}
else:
scope = resolve_refine_scope(
refine_scope,
refine_scope_index,
assembly_plan,
)
selected_group_indices = (
None if scope.is_all else scope.selected_group_indices
)
temporal_windows_by_group = None
arguments = dict(
model=model,
clip=clip,
sampler=sampler,
sigmas=sigmas,
video_latents=video_latents,
audio_latents=audio_latents,
assembly_plan=assembly_plan,
refine_seed=int(refine_seed),
refine_context=refine_context,
video_vae=video_vae,
conditioning_upscale_method=str(conditioning_upscale_method),
enable_preview=bool(enable_preview),
encode_prompt_fn=encode_prompt_fn,
latent_builder=latent_builder,
stream_extractor=stream_extractor,
clone_model_fn=clone_model_fn,
validate_refine_context_fn=validate_refine_context_fn,
adapt_group_conditioning_fn=adapt_group_conditioning_fn,
refine_schedule=refine_schedule,
)
if target.mode == MODE_VIDEO_ONLY:
result = _run_video_only_groups(
target=target,
sample_fn=sample_fn,
arguments=arguments,
selected_group_indices=selected_group_indices,
temporal_windows_by_group=temporal_windows_by_group,
)
elif target.mode == MODE_AUDIO_ONLY:
result = _run_sampled_target_groups(
target=target,
sample_fn=sample_fn,
selected_group_indices=selected_group_indices,
temporal_windows_by_group=temporal_windows_by_group,
**arguments,
)
elif target.mode == MODE_VIDEO_AUDIO:
result = _run_sampled_target_groups(
target=target,
sample_fn=sample_fn,
selected_group_indices=selected_group_indices,
temporal_windows_by_group=temporal_windows_by_group,
**arguments,
)
else:
raise TargetedRefineExecutionUnavailable(
f"refine target {target.mode!r} is unavailable"
)
videos, audios, updated_plan, status = result
if window is not None:
contract = window.contract
window_line = (
"Refine Window: timeline=final_visible_output, interval=["
f"{contract['effective_start_sec']:.6f}, "
f"{contract['effective_end_sec']:.6f}) sec, output_frames="
f"{contract['output_frame_range']}, selected_physical_groups="
f"{contract['selected_physical_groups']}, continuation_prefix=protected, "
"outside_window=mask_zero_then_bit_exact_restore, "
"physical_group_atomicity=preserved."
)
return videos, audios, updated_plan, f"{status}\n{window_line}"
assert scope is not None
if scope.is_all:
return videos, audios, updated_plan, status
scope_contract = scope.contract
scope_line = (
"Refine Scope: "
f"mode={scope.mode}, requested_index={scope_contract['requested_index']}, "
"selected_physical_groups="
f"{list(scope_contract['selected_physical_groups'])}, "
"selected_logical_chunks="
f"{list(scope_contract['selected_logical_chunks'])}, "
f"terminal_expanded={str(scope_contract['terminal_expanded']).lower()}."
)
return videos, audios, updated_plan, f"{status}\n{scope_line}"
+532 -532
View File
File diff suppressed because it is too large Load Diff