Publish V3.9 source with per-chunk references and retained V3.8X2 workflows
This commit is contained in:
@@ -28,6 +28,11 @@ from ..reference_video import (
|
||||
REFERENCE_VIDEO_SIZE_OPTIONS,
|
||||
)
|
||||
from ..reference import H3ContinuumReferenceImages, REFERENCE_IMAGES_TYPE
|
||||
from .reference_images_v39 import (
|
||||
H3ContinuumReferenceImagesV39,
|
||||
REFERENCE_IMAGES_V39_TYPE,
|
||||
effective_reference_inputs,
|
||||
)
|
||||
from ..reference_audio import (
|
||||
H3ContinuumReferenceAudios,
|
||||
REFERENCE_AUDIOS_TYPE,
|
||||
@@ -800,6 +805,61 @@ class H3ContinuumSamplerV38(H3ContinuumSamplerV37):
|
||||
)
|
||||
|
||||
|
||||
class H3ContinuumSamplerV39(H3ContinuumSamplerV38):
|
||||
"""Single nine-image input using the existing group-local routing engine."""
|
||||
|
||||
DESCRIPTION = (
|
||||
"H3 Continuum V3.9. Connect Reference Images V3.9 to assign fixed "
|
||||
"images 1–9 to all chunks or selected chunks."
|
||||
)
|
||||
SEARCH_ALIASES = ["H3 Continuum Sampler V3.9", "MiniMax H3 Reference Routing"]
|
||||
|
||||
@classmethod
|
||||
def INPUT_TYPES(cls):
|
||||
schema = super().INPUT_TYPES()
|
||||
schema["required"] = dict(schema["required"])
|
||||
optional = dict(schema["optional"])
|
||||
for index in range(1, 4):
|
||||
optional.pop(f"reference_image_{index}", None)
|
||||
optional.pop("image_references", None)
|
||||
optional.pop("reference_image_4", None)
|
||||
optional.pop("reference_image_5", None)
|
||||
optional["reference_images"] = (
|
||||
REFERENCE_IMAGES_V39_TYPE,
|
||||
{"display_name": "Reference Images (Optional)",
|
||||
"tooltip": "Connect H3 Continuum Reference Images V3.9; assign chunks there."},
|
||||
)
|
||||
schema["optional"] = optional
|
||||
return schema
|
||||
|
||||
def run(self, reference_images=None, **kwargs):
|
||||
# The public V3.9 schema owns a single Reference input. Stale API
|
||||
# keys must not create a second route around that input.
|
||||
for name in (
|
||||
*(f"reference_image_{index}" for index in range(1, 6)),
|
||||
"image_references", "reference_routing_mode",
|
||||
*(f"reference_r{index}_chunks" for index in range(1, 10)),
|
||||
):
|
||||
kwargs.pop(name, None)
|
||||
direct, extra, selectors = effective_reference_inputs(
|
||||
reference_images, chunks=int(kwargs.get("chunks", 3)),
|
||||
)
|
||||
kwargs.update({f"reference_image_{index}": image
|
||||
for index, image in enumerate(direct, start=1)})
|
||||
kwargs["image_references"] = extra
|
||||
outputs = super().run(_reference_routing_settings=selectors, **kwargs)
|
||||
if not isinstance(outputs, tuple) or len(outputs) < 4:
|
||||
return outputs
|
||||
from .reference_plan_inspector import format_reference_plan
|
||||
plan = outputs[2].get("reference_routing_v1")
|
||||
if not isinstance(plan, dict):
|
||||
raise RuntimeError("V3.9 Reference Routing has no verified output Plan")
|
||||
return {
|
||||
"ui": {"h3_reference_plan": [format_reference_plan(plan)]},
|
||||
"result": outputs,
|
||||
}
|
||||
|
||||
|
||||
class H3ContinuumMemoryActionPolicyExperimental:
|
||||
"""Explicit opt-in Reference sizing policy for the A7b experiment."""
|
||||
|
||||
@@ -1091,8 +1151,10 @@ NODE_CLASS_MAPPINGS = {
|
||||
"H3ContinuumStillImageGuideV37": H3ContinuumStillImageGuideV37,
|
||||
"H3ContinuumSamplerV37": H3ContinuumSamplerV37,
|
||||
"H3ContinuumSamplerV38": H3ContinuumSamplerV38,
|
||||
"H3ContinuumSamplerV39": H3ContinuumSamplerV39,
|
||||
"H3ContinuumReferenceAudios": H3ContinuumReferenceAudios,
|
||||
"H3ContinuumReferenceImages": H3ContinuumReferenceImages,
|
||||
"H3ContinuumReferenceImagesV39": H3ContinuumReferenceImagesV39,
|
||||
"H3ContinuumMemoryActionPolicyExperimental": (
|
||||
H3ContinuumMemoryActionPolicyExperimental
|
||||
),
|
||||
@@ -1110,8 +1172,10 @@ NODE_DISPLAY_NAME_MAPPINGS = {
|
||||
"H3ContinuumStillImageGuideV37": "H3 Continuum Still Image Guide V3.7",
|
||||
"H3ContinuumSamplerV37": "H3 Continuum Sampler V3.7",
|
||||
"H3ContinuumSamplerV38": "H3 Continuum Sampler V3.8",
|
||||
"H3ContinuumSamplerV39": "H3 Continuum Sampler V3.9",
|
||||
"H3ContinuumReferenceAudios": "H3 Continuum Reference Audios",
|
||||
"H3ContinuumReferenceImages": "H3 Continuum Reference Images",
|
||||
"H3ContinuumReferenceImagesV39": "H3 Continuum Reference Images V3.9",
|
||||
"H3ContinuumMemoryActionPolicyExperimental": (
|
||||
"H3 Continuum Memory Action Policy (Experimental)"
|
||||
),
|
||||
|
||||
@@ -130,6 +130,12 @@ def execute_v38_runtime_request(
|
||||
if request.diagnostics_mode == diagnostics_off:
|
||||
return output.as_public_tuple()
|
||||
|
||||
# The V3.8 reliability summary counts every connected Reference image.
|
||||
# A Custom V3.9 group intentionally prepares only its selected images, so
|
||||
# that legacy summary would describe a different conditioning path.
|
||||
if "_reference_routing_settings" in request.runtime_kwargs:
|
||||
return output.as_public_tuple()
|
||||
|
||||
try:
|
||||
inputs = request.diagnostics_inputs
|
||||
diagnostics = build_diagnostics(
|
||||
|
||||
+63
-18
@@ -220,6 +220,12 @@ def _apply_review_decode_scope(
|
||||
terminal_merged=selected_terminal_merged,
|
||||
terminal_initial_pair=(start == 1),
|
||||
)
|
||||
# Projection narrows the AV decode view, not the already-verified routing
|
||||
# decision. Keep that Queue-local plan available to the public Inspector.
|
||||
route_plan = assembly_plan.get("reference_routing_v1")
|
||||
if isinstance(route_plan, dict):
|
||||
scoped_plan = dict(scoped_plan)
|
||||
scoped_plan["reference_routing_v1"] = route_plan
|
||||
scoped_video = [{"samples": entry["video"]} for entry in decode_entries]
|
||||
scoped_audio = [{"samples": entry["audio"]} for entry in decode_entries]
|
||||
scoped_result = dict(result)
|
||||
@@ -528,6 +534,7 @@ class H3ContinuumSamplerV3:
|
||||
reference_encode_cache=False,
|
||||
continuation_transport="reference_context_v1",
|
||||
max_new_physical_groups=None,
|
||||
reference_routing_request=None,
|
||||
):
|
||||
if prompt_overrides is not None and not isinstance(prompt_overrides, dict):
|
||||
prompt_overrides = None
|
||||
@@ -615,6 +622,7 @@ class H3ContinuumSamplerV3:
|
||||
reference_encode_cache=bool(reference_encode_cache),
|
||||
continuation_transport=str(continuation_transport),
|
||||
max_new_physical_groups=max_new_physical_groups,
|
||||
reference_routing_request=reference_routing_request,
|
||||
_diagnostic_continuation_policy=advanced_values[
|
||||
"_diagnostic_continuation_policy"
|
||||
],
|
||||
@@ -642,7 +650,7 @@ class H3ContinuumSamplerV3:
|
||||
prompt_hashes=[str(entry["prompt_hash"]) for entry in entries],
|
||||
timeline_video_source=timeline_video_source,
|
||||
)
|
||||
decode_entries, assembly_plan = prepare_physical_decode_entries(
|
||||
decode_entries, assembly_plan = prepare_physical_decode_entries(
|
||||
entries,
|
||||
chunk_seconds=float(chunk_seconds),
|
||||
preserve_final_frame=(
|
||||
@@ -650,6 +658,13 @@ class H3ContinuumSamplerV3:
|
||||
),
|
||||
terminal_merged=terminal_merged,
|
||||
)
|
||||
if reference_routing_request is not None:
|
||||
from .reference_plan_inspector import project_reference_plan
|
||||
runtime = reference_routing_request.runtime
|
||||
if runtime is None:
|
||||
raise RuntimeError("Reference Routing completed without its runtime Plan")
|
||||
assembly_plan = dict(assembly_plan)
|
||||
assembly_plan["reference_routing_v1"] = project_reference_plan(runtime)
|
||||
video_latents = [{"samples": entry["video"]} for entry in decode_entries]
|
||||
audio_latents = [{"samples": entry["audio"]} for entry in decode_entries]
|
||||
if terminal_merged:
|
||||
@@ -1027,6 +1042,7 @@ class H3ContinuumSamplerProduction(H3ContinuumSamplerV3):
|
||||
reference_image_4=None,
|
||||
reference_image_5=None,
|
||||
image_references=None,
|
||||
_reference_routing_settings=None,
|
||||
):
|
||||
runtime_started_at = time.perf_counter()
|
||||
from ..reference import prepare_reference_assets
|
||||
@@ -1047,26 +1063,54 @@ class H3ContinuumSamplerProduction(H3ContinuumSamplerV3):
|
||||
)
|
||||
if take_requested and generation_mode != "Review Each Chunk":
|
||||
raise ValueError("Take selection requires Review Each Chunk")
|
||||
reference_assets = prepare_reference_assets(
|
||||
reference_image_1=reference_image_1,
|
||||
reference_image_2=reference_image_2,
|
||||
output_width=int(width),
|
||||
output_height=int(height),
|
||||
size_mode=reference_size,
|
||||
reference_image_3=reference_image_3,
|
||||
reference_image_4=reference_image_4,
|
||||
reference_image_5=reference_image_5,
|
||||
image_references=image_references,
|
||||
)
|
||||
reference_routing_request = None
|
||||
if _reference_routing_settings is None:
|
||||
reference_assets = prepare_reference_assets(
|
||||
reference_image_1=reference_image_1,
|
||||
reference_image_2=reference_image_2,
|
||||
output_width=int(width),
|
||||
output_height=int(height),
|
||||
size_mode=reference_size,
|
||||
reference_image_3=reference_image_3,
|
||||
reference_image_4=reference_image_4,
|
||||
reference_image_5=reference_image_5,
|
||||
image_references=image_references,
|
||||
)
|
||||
else:
|
||||
from .reference_runtime import ReferenceInputSet, ReferenceRoutingRequest
|
||||
reference_assets = None
|
||||
reference_routing_request = ReferenceRoutingRequest(
|
||||
selectors_by_slot=dict(_reference_routing_settings),
|
||||
inputs=ReferenceInputSet.from_inputs(
|
||||
reference_image_1=reference_image_1,
|
||||
reference_image_2=reference_image_2,
|
||||
reference_image_3=reference_image_3,
|
||||
reference_image_4=reference_image_4,
|
||||
reference_image_5=reference_image_5,
|
||||
image_references=image_references,
|
||||
output_width=int(width),
|
||||
output_height=int(height),
|
||||
size_mode=reference_size,
|
||||
),
|
||||
)
|
||||
reference_audio_source, resolved_reference_audio_vae = resolve_reference_audio_input(
|
||||
reference_audio_1,
|
||||
reference_audio_vae,
|
||||
audio_references,
|
||||
)
|
||||
def mark_runtime_start(assembly_plan):
|
||||
marked = dict(assembly_plan)
|
||||
marked["_runtime_started_at"] = runtime_started_at
|
||||
return marked
|
||||
def mark_runtime_start(assembly_plan):
|
||||
marked = dict(assembly_plan)
|
||||
marked["_runtime_started_at"] = runtime_started_at
|
||||
return marked
|
||||
|
||||
def append_reference_plan(report, assembly_plan):
|
||||
if reference_routing_request is None:
|
||||
return str(report)
|
||||
from .reference_plan_inspector import format_reference_plan
|
||||
plan_view = assembly_plan.get("reference_routing_v1")
|
||||
if not isinstance(plan_view, dict):
|
||||
raise RuntimeError("Reference Routing output has no verified Plan")
|
||||
return str(report).rstrip() + "\n" + format_reference_plan(plan_view)
|
||||
|
||||
def execute():
|
||||
return super(H3ContinuumSamplerProduction, self).run(
|
||||
@@ -1097,6 +1141,7 @@ class H3ContinuumSamplerProduction(H3ContinuumSamplerV3):
|
||||
memory_attribution=bool(memory_attribution),
|
||||
prompt_conditioning_cache=bool(prompt_conditioning_cache),
|
||||
reference_encode_cache=bool(reference_encode_cache),
|
||||
reference_routing_request=reference_routing_request,
|
||||
continuation_transport=str(continuation_transport),
|
||||
max_new_physical_groups=max_new_physical_groups,
|
||||
advanced={
|
||||
@@ -1134,7 +1179,7 @@ class H3ContinuumSamplerProduction(H3ContinuumSamplerV3):
|
||||
video_latents,
|
||||
audio_latents,
|
||||
mark_runtime_start(assembly_plan),
|
||||
str(result["report"]),
|
||||
append_reference_plan(result["report"], assembly_plan),
|
||||
)
|
||||
if bool(capture_refine_context):
|
||||
return (*outputs, refine_context)
|
||||
@@ -1179,7 +1224,7 @@ class H3ContinuumSamplerProduction(H3ContinuumSamplerV3):
|
||||
else:
|
||||
video_latents, audio_latents, assembly_plan, result = execute_outputs
|
||||
result = dict(result)
|
||||
report = str(result["report"]) + "\n" + storage.summary(
|
||||
report = append_reference_plan(result["report"], assembly_plan) + "\n" + storage.summary(
|
||||
detailed=diagnostics == DIAGNOSTICS_FULL
|
||||
)
|
||||
warning = _partial_review_warning(
|
||||
|
||||
@@ -0,0 +1,287 @@
|
||||
"""Pure RR-R3 plan joining fixed Reference identities to Core Picture numbers.
|
||||
|
||||
The caller supplies only immutable routing and Reference metadata. This module
|
||||
does not encode images, rewrite prompts, select runtime sources, or sample.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass
|
||||
from typing import Any
|
||||
|
||||
from .reference_routing import REFERENCE_SLOT_IDS, ReferenceRoutingSchedule
|
||||
|
||||
|
||||
_SLOT_ORDER = {slot_id: index for index, slot_id in enumerate(REFERENCE_SLOT_IDS)}
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class EffectivePlanIssue:
|
||||
code: str
|
||||
message: str
|
||||
source_slot_id: str | None = None
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class ReferencePicture:
|
||||
"""A fixed source slot, compact asset, content hash, and Qwen Picture number."""
|
||||
|
||||
source_slot_id: str
|
||||
asset_index: int
|
||||
image_sha256: str
|
||||
picture_number: int
|
||||
|
||||
@property
|
||||
def picture_tag(self) -> str:
|
||||
return f"<Picture {self.picture_number}>"
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class PictureMap:
|
||||
"""Core's image presentation order; First/Last are not Reference assets."""
|
||||
|
||||
first_picture_number: int | None
|
||||
last_picture_number: int | None
|
||||
references: tuple[ReferencePicture, ...]
|
||||
|
||||
@property
|
||||
def source_slot_ids(self) -> tuple[str, ...]:
|
||||
return tuple(item.source_slot_id for item in self.references)
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class LogicalEffectiveRoute:
|
||||
logical_chunk: int
|
||||
requested_source_slot_ids: tuple[str, ...]
|
||||
picture_map: PictureMap
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class PhysicalEffectiveRoute:
|
||||
physical_group: int
|
||||
logical_chunks: tuple[int, ...]
|
||||
terminal_atomic: bool
|
||||
routing_status: str
|
||||
status: str
|
||||
requested_source_slot_ids: tuple[str, ...] | None
|
||||
picture_map: PictureMap | None
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class EffectiveReferencePlan:
|
||||
mode: str
|
||||
legacy_fallback: bool
|
||||
connected_source_slot_ids: tuple[str, ...]
|
||||
logical_routes: tuple[LogicalEffectiveRoute, ...] = ()
|
||||
physical_routes: tuple[PhysicalEffectiveRoute, ...] = ()
|
||||
issues: tuple[EffectivePlanIssue, ...] = ()
|
||||
|
||||
@property
|
||||
def valid(self) -> bool:
|
||||
return not self.issues
|
||||
|
||||
@property
|
||||
def has_route_conflicts(self) -> bool:
|
||||
return any(group.status == "conflict" for group in self.physical_routes)
|
||||
|
||||
|
||||
def _schedule_issues(schedule: ReferenceRoutingSchedule) -> tuple[EffectivePlanIssue, ...]:
|
||||
if not schedule.valid:
|
||||
return tuple(
|
||||
EffectivePlanIssue(f"routing_{issue.code}", issue.message, issue.slot_id)
|
||||
for issue in schedule.issues
|
||||
)
|
||||
total = schedule.total_chunks
|
||||
if isinstance(total, bool) or not isinstance(total, int) or total < 1:
|
||||
return (EffectivePlanIssue("invalid_routing_schedule", "missing logical chunk count"),)
|
||||
if tuple(route.logical_chunk for route in schedule.logical_routes) != tuple(range(1, total + 1)):
|
||||
return (EffectivePlanIssue("invalid_routing_schedule", "logical chunks are not the full project sequence"),)
|
||||
|
||||
logical_slots = {route.logical_chunk: route.reference_slot_ids for route in schedule.logical_routes}
|
||||
for route in schedule.logical_routes:
|
||||
if any(slot_id not in _SLOT_ORDER for slot_id in route.reference_slot_ids):
|
||||
return (EffectivePlanIssue("invalid_routing_schedule", "logical route has an unknown Reference slot"),)
|
||||
if len(set(route.reference_slot_ids)) != len(route.reference_slot_ids):
|
||||
return (EffectivePlanIssue("invalid_routing_schedule", "logical route repeats a Reference slot"),)
|
||||
if tuple(sorted(route.reference_slot_ids, key=_SLOT_ORDER.get)) != route.reference_slot_ids:
|
||||
return (EffectivePlanIssue("invalid_routing_schedule", "logical Reference slots are not ordered"),)
|
||||
|
||||
covered = tuple(chunk for group in schedule.physical_routes for chunk in group.logical_chunks)
|
||||
if covered != tuple(range(1, total + 1)):
|
||||
return (EffectivePlanIssue("invalid_routing_schedule", "physical groups do not cover the logical sequence"),)
|
||||
for group in schedule.physical_routes:
|
||||
if group.terminal_atomic != (len(group.logical_chunks) > 1):
|
||||
return (EffectivePlanIssue("invalid_routing_schedule", "physical group atomicity disagrees with its chunks"),)
|
||||
members = tuple(logical_slots[chunk] for chunk in group.logical_chunks)
|
||||
if group.logical_reference_slot_ids != members:
|
||||
return (EffectivePlanIssue("invalid_routing_schedule", "physical group member routes disagree with logical routes"),)
|
||||
consistent = all(member == members[0] for member in members[1:])
|
||||
if consistent:
|
||||
expected_status = "empty" if not members[0] else "consistent"
|
||||
if group.status != expected_status or group.reference_slot_ids != members[0]:
|
||||
return (EffectivePlanIssue("invalid_routing_schedule", "physical group route is not its shared member route"),)
|
||||
elif group.status != "conflict" or group.reference_slot_ids is not None:
|
||||
return (EffectivePlanIssue("invalid_routing_schedule", "conflicting physical group has an effective route"),)
|
||||
return ()
|
||||
|
||||
|
||||
def _source_issues(
|
||||
source_slot_ids: Any, image_hashes: Any, asset_count: Any
|
||||
) -> tuple[EffectivePlanIssue, ...]:
|
||||
issues: list[EffectivePlanIssue] = []
|
||||
if isinstance(asset_count, bool) or not isinstance(asset_count, int) or asset_count < 0:
|
||||
issues.append(EffectivePlanIssue("invalid_asset_count", "Reference asset count must be a non-negative integer"))
|
||||
if not isinstance(source_slot_ids, tuple):
|
||||
issues.append(EffectivePlanIssue("invalid_source_slots", "source_slot_ids must be a tuple"))
|
||||
return tuple(issues)
|
||||
if not isinstance(image_hashes, tuple):
|
||||
issues.append(EffectivePlanIssue("invalid_image_hashes", "Reference image hashes must be a tuple"))
|
||||
elif len(image_hashes) != len(source_slot_ids):
|
||||
issues.append(EffectivePlanIssue("hash_count_mismatch", "Reference image hashes do not align with fixed source slots"))
|
||||
elif any(not isinstance(value, str) or len(value) != 64 or
|
||||
any(char not in "0123456789abcdef" for char in value) for value in image_hashes):
|
||||
issues.append(EffectivePlanIssue("invalid_image_hash", "Reference image hashes must be lowercase SHA-256 values"))
|
||||
if isinstance(asset_count, int) and not isinstance(asset_count, bool):
|
||||
if asset_count > 0 and not source_slot_ids:
|
||||
issues.append(EffectivePlanIssue("missing_source_slots", "connected Reference assets have no fixed source slot IDs"))
|
||||
elif asset_count != len(source_slot_ids):
|
||||
issues.append(EffectivePlanIssue("asset_count_mismatch", "source slot IDs do not align with compact Reference assets"))
|
||||
for slot_id in source_slot_ids:
|
||||
if not isinstance(slot_id, str) or slot_id not in _SLOT_ORDER:
|
||||
issues.append(EffectivePlanIssue("unknown_source_slot", f"unknown Reference source slot: {slot_id!r}", str(slot_id)))
|
||||
if not any(issue.code == "unknown_source_slot" for issue in issues):
|
||||
if len(set(source_slot_ids)) != len(source_slot_ids):
|
||||
issues.append(EffectivePlanIssue("duplicate_source_slot", "a fixed Reference source slot occurs more than once"))
|
||||
elif tuple(sorted(source_slot_ids, key=_SLOT_ORDER.get)) != source_slot_ids:
|
||||
issues.append(EffectivePlanIssue("source_slot_order", "source slot IDs do not follow the compact R1-R9 order"))
|
||||
return tuple(issues)
|
||||
|
||||
|
||||
def _picture_map(
|
||||
requested_source_slot_ids: tuple[str, ...],
|
||||
connected_asset_indices: dict[str, int],
|
||||
image_hashes: tuple[str, ...],
|
||||
*,
|
||||
has_first_image: bool,
|
||||
has_last_image: bool,
|
||||
) -> PictureMap:
|
||||
first_number = 1 if has_first_image else None
|
||||
last_number = 1 + int(has_first_image) if has_last_image else None
|
||||
picture_offset = int(has_first_image) + int(has_last_image)
|
||||
selected = tuple(slot_id for slot_id in requested_source_slot_ids if slot_id in connected_asset_indices)
|
||||
references = tuple(
|
||||
ReferencePicture(
|
||||
slot_id, connected_asset_indices[slot_id],
|
||||
image_hashes[connected_asset_indices[slot_id]], picture_offset + index,
|
||||
)
|
||||
for index, slot_id in enumerate(selected, start=1)
|
||||
)
|
||||
return PictureMap(first_number, last_number, references)
|
||||
|
||||
|
||||
def compile_group_picture_map(
|
||||
*,
|
||||
source_slot_ids: tuple[str, ...],
|
||||
reference_image_hashes: tuple[str, ...],
|
||||
has_first_image: bool,
|
||||
has_last_image: bool,
|
||||
) -> PictureMap:
|
||||
"""Use RR-R3's Picture numbering for one already-selected physical group."""
|
||||
|
||||
issues = _source_issues(source_slot_ids, reference_image_hashes, len(source_slot_ids))
|
||||
if issues or type(has_first_image) is not bool or type(has_last_image) is not bool:
|
||||
raise ValueError("invalid internal Reference group identity or anchor flags")
|
||||
return _picture_map(
|
||||
source_slot_ids,
|
||||
{slot_id: index for index, slot_id in enumerate(source_slot_ids)},
|
||||
reference_image_hashes,
|
||||
has_first_image=has_first_image,
|
||||
has_last_image=has_last_image,
|
||||
)
|
||||
|
||||
|
||||
def compile_effective_reference_plan(
|
||||
*,
|
||||
routing_schedule: ReferenceRoutingSchedule,
|
||||
source_slot_ids: tuple[str, ...],
|
||||
reference_image_hashes: tuple[str, ...],
|
||||
reference_asset_count: int,
|
||||
has_first_image: bool,
|
||||
has_last_image: bool,
|
||||
) -> EffectiveReferencePlan:
|
||||
"""Map full logical routes to compact assets and Core Qwen Picture numbers.
|
||||
|
||||
Anchor flags describe the presentation being planned. The caller retains
|
||||
responsibility for choosing when First/Last are supplied to conditioning.
|
||||
"""
|
||||
|
||||
if not isinstance(routing_schedule, ReferenceRoutingSchedule):
|
||||
return EffectiveReferencePlan(
|
||||
mode="invalid", legacy_fallback=False, connected_source_slot_ids=(),
|
||||
issues=(EffectivePlanIssue("invalid_routing_schedule", "expected an RR-R2 routing schedule"),),
|
||||
)
|
||||
issues = [
|
||||
*_schedule_issues(routing_schedule),
|
||||
*_source_issues(source_slot_ids, reference_image_hashes, reference_asset_count),
|
||||
]
|
||||
if type(has_first_image) is not bool or type(has_last_image) is not bool:
|
||||
issues.append(EffectivePlanIssue("invalid_anchor_flags", "First/Last presence flags must be booleans"))
|
||||
if issues:
|
||||
return EffectiveReferencePlan(
|
||||
mode=routing_schedule.mode,
|
||||
legacy_fallback=routing_schedule.legacy_fallback,
|
||||
connected_source_slot_ids=source_slot_ids if isinstance(source_slot_ids, tuple) else (),
|
||||
issues=tuple(issues),
|
||||
)
|
||||
|
||||
asset_indices = {slot_id: index for index, slot_id in enumerate(source_slot_ids)}
|
||||
logical_routes = tuple(
|
||||
LogicalEffectiveRoute(
|
||||
logical_chunk=route.logical_chunk,
|
||||
requested_source_slot_ids=route.reference_slot_ids,
|
||||
picture_map=_picture_map(
|
||||
route.reference_slot_ids, asset_indices, reference_image_hashes,
|
||||
has_first_image=has_first_image, has_last_image=has_last_image,
|
||||
),
|
||||
)
|
||||
for route in routing_schedule.logical_routes
|
||||
)
|
||||
physical_routes: list[PhysicalEffectiveRoute] = []
|
||||
for group in routing_schedule.physical_routes:
|
||||
if group.status == "conflict":
|
||||
physical_routes.append(
|
||||
PhysicalEffectiveRoute(
|
||||
physical_group=group.physical_group,
|
||||
logical_chunks=group.logical_chunks,
|
||||
terminal_atomic=group.terminal_atomic,
|
||||
routing_status=group.status,
|
||||
status="conflict",
|
||||
requested_source_slot_ids=None,
|
||||
picture_map=None,
|
||||
)
|
||||
)
|
||||
continue
|
||||
requested = group.reference_slot_ids
|
||||
assert requested is not None
|
||||
picture_map = _picture_map(
|
||||
requested, asset_indices, reference_image_hashes,
|
||||
has_first_image=has_first_image, has_last_image=has_last_image,
|
||||
)
|
||||
physical_routes.append(
|
||||
PhysicalEffectiveRoute(
|
||||
physical_group=group.physical_group,
|
||||
logical_chunks=group.logical_chunks,
|
||||
terminal_atomic=group.terminal_atomic,
|
||||
routing_status=group.status,
|
||||
status="active" if picture_map.references else "empty",
|
||||
requested_source_slot_ids=requested,
|
||||
picture_map=picture_map,
|
||||
)
|
||||
)
|
||||
return EffectiveReferencePlan(
|
||||
mode=routing_schedule.mode,
|
||||
legacy_fallback=routing_schedule.legacy_fallback,
|
||||
connected_source_slot_ids=source_slot_ids,
|
||||
logical_routes=logical_routes,
|
||||
physical_routes=tuple(physical_routes),
|
||||
)
|
||||
@@ -0,0 +1,111 @@
|
||||
"""Fixed nine-slot Reference Images input for the V3.9 sampler."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass
|
||||
|
||||
import torch
|
||||
|
||||
from ..reference import ReferenceImageBundle
|
||||
from .reference_routing import REFERENCE_SLOT_IDS, parse_chunk_selector
|
||||
|
||||
|
||||
REFERENCE_IMAGES_V39_TYPE = "H3_CONTINUUM_REFERENCE_IMAGES_V39"
|
||||
REFERENCE_USE_ALL = "All chunks"
|
||||
REFERENCE_USE_PER_CHUNK = "Per chunk"
|
||||
REFERENCE_USE_OPTIONS = (REFERENCE_USE_ALL, REFERENCE_USE_PER_CHUNK)
|
||||
MAX_CHUNKS = 16 # Current Sampler schema limit; checked in integration tests.
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class ReferenceImagesV39Bundle:
|
||||
images: tuple[torch.Tensor | None, ...]
|
||||
reference_use: str
|
||||
selectors: tuple[str, ...]
|
||||
|
||||
|
||||
def _canonical_selector(value: str) -> str:
|
||||
parsed = parse_chunk_selector(value, total_chunks=MAX_CHUNKS)
|
||||
if not parsed.valid:
|
||||
details = "; ".join(issue.message for issue in parsed.issues)
|
||||
raise ValueError(f"invalid V3.9 Reference chunk selection: {details}")
|
||||
return ",".join(map(str, parsed.logical_chunks)) or "off"
|
||||
|
||||
|
||||
def effective_reference_inputs(bundle: ReferenceImagesV39Bundle | None, *, chunks: int):
|
||||
"""Return legacy-shaped images and private selectors without changing saved data."""
|
||||
if not isinstance(chunks, int) or isinstance(chunks, bool) or not 1 <= chunks <= MAX_CHUNKS:
|
||||
raise ValueError(f"V3.9 Reference Chunks must be within 1..{MAX_CHUNKS}")
|
||||
if bundle is None:
|
||||
images = (None,) * 9
|
||||
mode = REFERENCE_USE_ALL
|
||||
selections = ("off",) * 9
|
||||
elif (not isinstance(bundle, ReferenceImagesV39Bundle)
|
||||
or len(bundle.images) != 9 or len(bundle.selectors) != 9
|
||||
or bundle.reference_use not in REFERENCE_USE_OPTIONS):
|
||||
raise ValueError("V3.9 Reference Images requires its nine-slot V3.9 bundle")
|
||||
else:
|
||||
images = bundle.images
|
||||
mode = bundle.reference_use
|
||||
selections = bundle.selectors
|
||||
selectors = {}
|
||||
for index, (image, selection) in enumerate(zip(images, selections, strict=True), start=1):
|
||||
if image is None:
|
||||
selectors[f"R{index}"] = "off"
|
||||
elif mode == REFERENCE_USE_ALL:
|
||||
selectors[f"R{index}"] = "all"
|
||||
else:
|
||||
parsed = parse_chunk_selector(selection, total_chunks=MAX_CHUNKS)
|
||||
if not parsed.valid:
|
||||
details = "; ".join(issue.message for issue in parsed.issues)
|
||||
raise ValueError(f"R{index} chunk selection: {details}")
|
||||
active = (n for n in parsed.logical_chunks if n <= chunks)
|
||||
selectors[f"R{index}"] = ",".join(map(str, active)) or "off"
|
||||
if tuple(selectors) != REFERENCE_SLOT_IDS:
|
||||
raise ValueError("V3.9 Reference slot ordering changed")
|
||||
return images[:3], ReferenceImageBundle(images[3:]), selectors
|
||||
|
||||
|
||||
class H3ContinuumReferenceImagesV39:
|
||||
CATEGORY = "MiniMax H3/Continuum/Input"
|
||||
DESCRIPTION = "Connect up to nine fixed Reference Images; choose chunks in this node."
|
||||
RETURN_TYPES = (REFERENCE_IMAGES_V39_TYPE,)
|
||||
RETURN_NAMES = ("reference_images",)
|
||||
FUNCTION = "pack"
|
||||
|
||||
@classmethod
|
||||
def INPUT_TYPES(cls):
|
||||
return {
|
||||
"required": {
|
||||
"reference_use": (REFERENCE_USE_OPTIONS, {
|
||||
"default": REFERENCE_USE_ALL,
|
||||
"display_name": "Reference Use",
|
||||
"tooltip": "All chunks uses connected images throughout. Per chunk uses the assignments below.",
|
||||
}),
|
||||
**{
|
||||
f"reference_r{index}_chunks": ("STRING", {
|
||||
"default": "off", "advanced": True,
|
||||
"display_name": f"Image {index} chunks",
|
||||
"tooltip": f"Saved assignments for Reference Image {index}; use the in-node table.",
|
||||
}) for index in range(1, 10)
|
||||
},
|
||||
},
|
||||
"optional": {
|
||||
f"reference_image_{index}": ("IMAGE", {
|
||||
"display_name": f"Reference Image {index} (Optional)",
|
||||
"tooltip": f"Fixed Image {index} / @R{index}. Its number never changes with other connections.",
|
||||
}) for index in range(1, 10)
|
||||
},
|
||||
}
|
||||
|
||||
def pack(self, reference_use=REFERENCE_USE_ALL, **kwargs):
|
||||
if reference_use not in REFERENCE_USE_OPTIONS:
|
||||
raise ValueError("Reference Use must be All chunks or Per chunk")
|
||||
images = tuple(kwargs.get(f"reference_image_{index}") for index in range(1, 10))
|
||||
selectors = tuple(
|
||||
(_canonical_selector(kwargs.get(f"reference_r{index}_chunks", "off"))
|
||||
if reference_use == REFERENCE_USE_PER_CHUNK else
|
||||
str(kwargs.get(f"reference_r{index}_chunks", "off")))
|
||||
for index in range(1, 10)
|
||||
)
|
||||
return (ReferenceImagesV39Bundle(images, reference_use, selectors),)
|
||||
@@ -0,0 +1,69 @@
|
||||
"""Read-only V3.9 projection of the Reference contract used by this Queue.
|
||||
|
||||
This module never selects images or changes a route. Pending groups are shown
|
||||
as settings only; accepted groups use the frozen/observed RR-R5 descriptor.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any
|
||||
|
||||
from .reference_runtime import ReferenceRoutingRuntime
|
||||
|
||||
|
||||
def project_reference_plan(runtime: ReferenceRoutingRuntime) -> dict[str, Any]:
|
||||
if not isinstance(runtime, ReferenceRoutingRuntime):
|
||||
raise TypeError("Reference Plan Inspector requires the active routing runtime")
|
||||
accepted = int(runtime.accepted_chunks)
|
||||
generated = set(runtime.generated_groups)
|
||||
groups: list[dict[str, Any]] = []
|
||||
for route in runtime.schedule.physical_routes:
|
||||
group = int(route.physical_group)
|
||||
complete = route.logical_chunks[-1] <= accepted
|
||||
item: dict[str, Any] = {
|
||||
"physical_group": group,
|
||||
"logical_chunks": list(route.logical_chunks),
|
||||
"requested_slots": list(route.reference_slot_ids or ()),
|
||||
"status": (
|
||||
"pending" if not complete else
|
||||
"generated" if group in generated else "reused"
|
||||
),
|
||||
}
|
||||
if complete:
|
||||
contract = runtime.group_contract_for(group)
|
||||
item["contract_sha256"] = contract["sha256"]
|
||||
item["descriptor"] = contract["descriptor"]
|
||||
item["warnings"] = list(runtime.group_warnings.get(group, ()))
|
||||
groups.append(item)
|
||||
return {
|
||||
"version": 1,
|
||||
"mode": runtime.schedule.mode,
|
||||
"accepted_chunks": accepted,
|
||||
"connected_slots": list(runtime.inputs.connected_source_slot_ids),
|
||||
"groups": groups,
|
||||
}
|
||||
|
||||
|
||||
def format_reference_plan(plan: dict[str, Any]) -> str:
|
||||
lines = [
|
||||
"Reference Plan Inspector (last Queue, runtime verified)",
|
||||
f"Mode: {plan['mode']}; accepted chunks: {plan['accepted_chunks']}",
|
||||
"Connected: " + (", ".join(plan["connected_slots"]) or "none"),
|
||||
]
|
||||
for group in plan["groups"]:
|
||||
label = ",".join(str(chunk) for chunk in group["logical_chunks"])
|
||||
head = f"Group {group['physical_group']} [C{label}] {group['status']}"
|
||||
descriptor = group.get("descriptor")
|
||||
if descriptor is None:
|
||||
lines.append(head + " — configured " + (
|
||||
", ".join(group["requested_slots"]) or "no References"
|
||||
))
|
||||
continue
|
||||
mapping = ", ".join(
|
||||
f"{ref['source_slot_id']}=<Picture {ref['picture_number']}>"
|
||||
for ref in descriptor["references"]
|
||||
) or "no References"
|
||||
lines.append(head + " — " + mapping + f"; contract={group['contract_sha256'][:12]}")
|
||||
for warning in group["warnings"]:
|
||||
lines.append(" Warning: " + warning)
|
||||
return "\n".join(lines)
|
||||
@@ -0,0 +1,365 @@
|
||||
"""Pure V3.9 Reference selector parsing and group schedule planning.
|
||||
|
||||
V3.9 Custom consumes this plan through the Reference runtime and storage
|
||||
contracts. Planning here remains free of Sampling and persistence side effects.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import Mapping
|
||||
from dataclasses import dataclass
|
||||
import re
|
||||
from typing import Any
|
||||
|
||||
from ..branch_provenance import BranchProvenanceError, physical_groups
|
||||
|
||||
|
||||
REFERENCE_SLOT_IDS = tuple(f"R{index}" for index in range(1, 10))
|
||||
|
||||
_INTEGER_TOKEN = re.compile(r"^[0-9]+$")
|
||||
_RANGE_TOKEN = re.compile(r"^([0-9]+)\s*-\s*([0-9]+)$")
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class RoutingIssue:
|
||||
"""A classified parser/planner issue; it does not itself stop execution."""
|
||||
|
||||
code: str
|
||||
message: str
|
||||
slot_id: str | None = None
|
||||
selector: str | None = None
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class ChunkSelectorResult:
|
||||
"""Parsed selector with all/off kept distinct from explicit chunk lists."""
|
||||
|
||||
kind: str
|
||||
logical_chunks: tuple[int, ...]
|
||||
issues: tuple[RoutingIssue, ...] = ()
|
||||
|
||||
@property
|
||||
def valid(self) -> bool:
|
||||
return self.kind != "invalid" and not self.issues
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class LogicalReferenceRoute:
|
||||
"""Reference identities selected for one project-wide logical chunk."""
|
||||
|
||||
logical_chunk: int
|
||||
reference_slot_ids: tuple[str, ...]
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class PhysicalReferenceRoute:
|
||||
"""Routing facts for one authoritative atomic physical sampling group."""
|
||||
|
||||
physical_group: int
|
||||
logical_chunks: tuple[int, ...]
|
||||
terminal_atomic: bool
|
||||
logical_reference_slot_ids: tuple[tuple[str, ...], ...]
|
||||
status: str
|
||||
reference_slot_ids: tuple[str, ...] | None
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class ReferenceRoutingSchedule:
|
||||
"""Full logical schedule plus its physical-group compatibility view."""
|
||||
|
||||
mode: str
|
||||
legacy_fallback: bool
|
||||
total_chunks: int | None
|
||||
terminal_merge_enabled: bool | None
|
||||
logical_routes: tuple[LogicalReferenceRoute, ...] = ()
|
||||
physical_routes: tuple[PhysicalReferenceRoute, ...] = ()
|
||||
issues: tuple[RoutingIssue, ...] = ()
|
||||
|
||||
@property
|
||||
def valid(self) -> bool:
|
||||
return not self.issues
|
||||
|
||||
|
||||
def _invalid_selector(code: str, message: str, selector: str | None) -> ChunkSelectorResult:
|
||||
return ChunkSelectorResult(
|
||||
kind="invalid",
|
||||
logical_chunks=(),
|
||||
issues=(RoutingIssue(code=code, message=message, selector=selector),),
|
||||
)
|
||||
|
||||
|
||||
def parse_chunk_selector(selector: Any, *, total_chunks: int) -> ChunkSelectorResult:
|
||||
"""Parse all/off, a one-based chunk, inclusive ranges, and their combinations.
|
||||
|
||||
Invalid values are returned as structured issues so callers can inspect
|
||||
them without introducing a new runtime execution stop.
|
||||
"""
|
||||
|
||||
if isinstance(total_chunks, bool) or not isinstance(total_chunks, int) or total_chunks < 1:
|
||||
return _invalid_selector(
|
||||
"invalid_chunk_count",
|
||||
"total_chunks must be a positive integer",
|
||||
selector if isinstance(selector, str) else None,
|
||||
)
|
||||
if not isinstance(selector, str):
|
||||
return _invalid_selector(
|
||||
"selector_not_string",
|
||||
"selector must be a string",
|
||||
None,
|
||||
)
|
||||
|
||||
text = selector.strip()
|
||||
normalized = text.casefold()
|
||||
if not normalized:
|
||||
return _invalid_selector("selector_empty", "selector is empty", selector)
|
||||
if normalized == "all":
|
||||
return ChunkSelectorResult("all", tuple(range(1, total_chunks + 1)))
|
||||
if normalized == "off":
|
||||
return ChunkSelectorResult("off", ())
|
||||
|
||||
selected: set[int] = set()
|
||||
issues: list[RoutingIssue] = []
|
||||
for raw_token in text.split(","):
|
||||
token = raw_token.strip()
|
||||
if not token:
|
||||
issues.append(
|
||||
RoutingIssue(
|
||||
"empty_selector_item",
|
||||
"selector contains an empty comma-separated item",
|
||||
selector=selector,
|
||||
)
|
||||
)
|
||||
continue
|
||||
|
||||
if _INTEGER_TOKEN.fullmatch(token):
|
||||
start = end = int(token)
|
||||
else:
|
||||
match = _RANGE_TOKEN.fullmatch(token)
|
||||
if match is None:
|
||||
issues.append(
|
||||
RoutingIssue(
|
||||
"invalid_selector_item",
|
||||
f"invalid selector item: {token!r}",
|
||||
selector=selector,
|
||||
)
|
||||
)
|
||||
continue
|
||||
start, end = int(match.group(1)), int(match.group(2))
|
||||
if start > end:
|
||||
issues.append(
|
||||
RoutingIssue(
|
||||
"reversed_range",
|
||||
f"range start {start} exceeds end {end}",
|
||||
selector=selector,
|
||||
)
|
||||
)
|
||||
continue
|
||||
|
||||
if start < 1 or end > total_chunks:
|
||||
issues.append(
|
||||
RoutingIssue(
|
||||
"chunk_out_of_range",
|
||||
f"selector item {token!r} is outside 1..{total_chunks}",
|
||||
selector=selector,
|
||||
)
|
||||
)
|
||||
continue
|
||||
|
||||
values = set(range(start, end + 1))
|
||||
if selected.intersection(values):
|
||||
issues.append(
|
||||
RoutingIssue(
|
||||
"duplicate_chunk",
|
||||
f"selector item {token!r} overlaps an earlier item",
|
||||
selector=selector,
|
||||
)
|
||||
)
|
||||
continue
|
||||
selected.update(values)
|
||||
|
||||
if issues:
|
||||
return ChunkSelectorResult("invalid", (), tuple(issues))
|
||||
return ChunkSelectorResult("chunks", tuple(sorted(selected)))
|
||||
|
||||
|
||||
def _invalid_schedule(
|
||||
*,
|
||||
mode: str,
|
||||
legacy_fallback: bool,
|
||||
total_chunks: int | None,
|
||||
terminal_merge_enabled: bool | None,
|
||||
issues: tuple[RoutingIssue, ...],
|
||||
) -> ReferenceRoutingSchedule:
|
||||
return ReferenceRoutingSchedule(
|
||||
mode=mode,
|
||||
legacy_fallback=legacy_fallback,
|
||||
total_chunks=total_chunks,
|
||||
terminal_merge_enabled=terminal_merge_enabled,
|
||||
issues=issues,
|
||||
)
|
||||
|
||||
|
||||
def compile_reference_routing_schedule(
|
||||
*,
|
||||
total_chunks: int,
|
||||
terminal_merge_enabled: bool,
|
||||
mode: Any = None,
|
||||
selectors_by_slot: Any = None,
|
||||
) -> ReferenceRoutingSchedule:
|
||||
"""Compile routing over full logical chunk numbers and physical groups.
|
||||
|
||||
An absent mode preserves legacy All behavior. Custom mode requires an
|
||||
explicit selector for each fixed R1-R9 slot; explicit all-off is valid and
|
||||
remains distinct from an absent mode. Terminal atomic groups with
|
||||
different member routes are surfaced as conflicts without auto-correction.
|
||||
"""
|
||||
|
||||
legacy_fallback = mode is None
|
||||
normalized_mode = "all" if legacy_fallback else None
|
||||
issues: list[RoutingIssue] = []
|
||||
|
||||
if isinstance(total_chunks, bool) or not isinstance(total_chunks, int) or total_chunks < 1:
|
||||
issues.append(RoutingIssue("invalid_chunk_count", "total_chunks must be a positive integer"))
|
||||
if type(terminal_merge_enabled) is not bool:
|
||||
issues.append(
|
||||
RoutingIssue("invalid_terminal_merge", "terminal_merge_enabled must be a boolean")
|
||||
)
|
||||
|
||||
if not legacy_fallback:
|
||||
if not isinstance(mode, str):
|
||||
issues.append(RoutingIssue("invalid_mode", "mode must be All or Custom"))
|
||||
else:
|
||||
token = mode.strip().casefold()
|
||||
if token == "all":
|
||||
normalized_mode = "all"
|
||||
elif token == "custom":
|
||||
normalized_mode = "custom"
|
||||
else:
|
||||
issues.append(RoutingIssue("invalid_mode", "mode must be All or Custom"))
|
||||
|
||||
if issues:
|
||||
return _invalid_schedule(
|
||||
mode=normalized_mode or "invalid",
|
||||
legacy_fallback=legacy_fallback,
|
||||
total_chunks=total_chunks if isinstance(total_chunks, int) and not isinstance(total_chunks, bool) else None,
|
||||
terminal_merge_enabled=terminal_merge_enabled if type(terminal_merge_enabled) is bool else None,
|
||||
issues=tuple(issues),
|
||||
)
|
||||
|
||||
slot_selectors: dict[str, ChunkSelectorResult] = {}
|
||||
if normalized_mode == "custom":
|
||||
if not isinstance(selectors_by_slot, Mapping):
|
||||
issues.append(
|
||||
RoutingIssue(
|
||||
"selectors_required",
|
||||
"Custom mode requires an explicit selector map for R1-R9",
|
||||
)
|
||||
)
|
||||
else:
|
||||
for slot_id in selectors_by_slot:
|
||||
if slot_id not in REFERENCE_SLOT_IDS:
|
||||
issues.append(
|
||||
RoutingIssue(
|
||||
"unknown_reference_slot",
|
||||
f"unknown Reference slot: {slot_id!r}",
|
||||
slot_id=str(slot_id),
|
||||
)
|
||||
)
|
||||
for slot_id in REFERENCE_SLOT_IDS:
|
||||
if slot_id not in selectors_by_slot:
|
||||
issues.append(
|
||||
RoutingIssue(
|
||||
"missing_selector",
|
||||
f"Custom mode has no selector for {slot_id}",
|
||||
slot_id=slot_id,
|
||||
)
|
||||
)
|
||||
continue
|
||||
parsed = parse_chunk_selector(
|
||||
selectors_by_slot[slot_id], total_chunks=total_chunks
|
||||
)
|
||||
if not parsed.valid:
|
||||
issues.extend(
|
||||
RoutingIssue(
|
||||
issue.code,
|
||||
issue.message,
|
||||
slot_id=slot_id,
|
||||
selector=issue.selector,
|
||||
)
|
||||
for issue in parsed.issues
|
||||
)
|
||||
else:
|
||||
slot_selectors[slot_id] = parsed
|
||||
|
||||
if issues:
|
||||
return _invalid_schedule(
|
||||
mode=normalized_mode or "invalid",
|
||||
legacy_fallback=legacy_fallback,
|
||||
total_chunks=total_chunks,
|
||||
terminal_merge_enabled=terminal_merge_enabled,
|
||||
issues=tuple(issues),
|
||||
)
|
||||
|
||||
logical_routes: list[LogicalReferenceRoute] = []
|
||||
for logical_chunk in range(1, total_chunks + 1):
|
||||
if normalized_mode == "all":
|
||||
selected_slots = REFERENCE_SLOT_IDS
|
||||
else:
|
||||
selected_slots = tuple(
|
||||
slot_id
|
||||
for slot_id in REFERENCE_SLOT_IDS
|
||||
if logical_chunk in slot_selectors[slot_id].logical_chunks
|
||||
)
|
||||
logical_routes.append(
|
||||
LogicalReferenceRoute(logical_chunk, tuple(selected_slots))
|
||||
)
|
||||
|
||||
try:
|
||||
groups = physical_groups(
|
||||
chunks=total_chunks,
|
||||
terminal_merge_enabled=terminal_merge_enabled,
|
||||
)
|
||||
except BranchProvenanceError as exc:
|
||||
return _invalid_schedule(
|
||||
mode=normalized_mode or "invalid",
|
||||
legacy_fallback=legacy_fallback,
|
||||
total_chunks=total_chunks,
|
||||
terminal_merge_enabled=terminal_merge_enabled,
|
||||
issues=(RoutingIssue("invalid_physical_groups", str(exc)),),
|
||||
)
|
||||
|
||||
routes_by_chunk = {route.logical_chunk: route.reference_slot_ids for route in logical_routes}
|
||||
physical_routes: list[PhysicalReferenceRoute] = []
|
||||
for group in groups:
|
||||
chunks = tuple(range(group.start, group.end + 1))
|
||||
member_routes = tuple(routes_by_chunk[chunk] for chunk in chunks)
|
||||
first_route = member_routes[0]
|
||||
consistent = all(route == first_route for route in member_routes[1:])
|
||||
if not consistent:
|
||||
group_status = "conflict"
|
||||
group_slots = None
|
||||
elif not first_route:
|
||||
group_status = "empty"
|
||||
group_slots = ()
|
||||
else:
|
||||
group_status = "consistent"
|
||||
group_slots = first_route
|
||||
physical_routes.append(
|
||||
PhysicalReferenceRoute(
|
||||
physical_group=int(group.physical_group),
|
||||
logical_chunks=chunks,
|
||||
terminal_atomic=group.start != group.end,
|
||||
logical_reference_slot_ids=member_routes,
|
||||
status=group_status,
|
||||
reference_slot_ids=group_slots,
|
||||
)
|
||||
)
|
||||
|
||||
return ReferenceRoutingSchedule(
|
||||
mode=normalized_mode or "invalid",
|
||||
legacy_fallback=legacy_fallback,
|
||||
total_chunks=total_chunks,
|
||||
terminal_merge_enabled=terminal_merge_enabled,
|
||||
logical_routes=tuple(logical_routes),
|
||||
physical_routes=tuple(physical_routes),
|
||||
)
|
||||
@@ -0,0 +1,342 @@
|
||||
"""V3.9 Custom group-local Reference conditioning.
|
||||
|
||||
The V3.9 caller supplies this adapter after routing is resolved. V3.8 and
|
||||
V3.9 All retain the legacy path; saved-run compatibility is handled by the
|
||||
separate Reference storage contract.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass
|
||||
import hashlib
|
||||
import json
|
||||
import re
|
||||
import uuid
|
||||
from typing import Any
|
||||
|
||||
import torch
|
||||
|
||||
from ..reference import (
|
||||
ReferenceAssets,
|
||||
ReferenceImageBundle,
|
||||
encode_reference_latents,
|
||||
encode_reference_latents_cached,
|
||||
encode_reference_prompt,
|
||||
prepare_reference_assets,
|
||||
resolve_reference_image_inputs,
|
||||
)
|
||||
from ..v2.h3_builder import encode_prompt_conditioning
|
||||
from .reference_effective_plan import PictureMap, compile_group_picture_map
|
||||
from .reference_routing import REFERENCE_SLOT_IDS, ReferenceRoutingSchedule
|
||||
|
||||
|
||||
_REFERENCE_TAG = re.compile(r"(?<![A-Za-z0-9_])@R([1-9])(?![A-Za-z0-9_])")
|
||||
|
||||
|
||||
class ReferenceRuntimeContractError(ValueError):
|
||||
"""An internal RR-R4 caller supplied an unusable routing contract."""
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class ReferenceRoutingRequest:
|
||||
"""Private V3.9 node-to-V2 request; never part of a saved node schema."""
|
||||
|
||||
selectors_by_slot: dict[str, str]
|
||||
inputs: ReferenceInputSet
|
||||
runtime: ReferenceRoutingRuntime | None = None
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class ReferenceInputSet:
|
||||
"""Raw R1-R9 sockets; no image is validated, resized, or VAE-encoded here."""
|
||||
|
||||
images: tuple[torch.Tensor | None, ...]
|
||||
output_width: int
|
||||
output_height: int
|
||||
size_mode: str
|
||||
|
||||
@classmethod
|
||||
def from_inputs(
|
||||
cls,
|
||||
*,
|
||||
reference_image_1: torch.Tensor | None = None,
|
||||
reference_image_2: torch.Tensor | None = None,
|
||||
reference_image_3: torch.Tensor | None = None,
|
||||
reference_image_4: torch.Tensor | None = None,
|
||||
reference_image_5: torch.Tensor | None = None,
|
||||
image_references: ReferenceImageBundle | None = None,
|
||||
output_width: int,
|
||||
output_height: int,
|
||||
size_mode: str,
|
||||
) -> ReferenceInputSet:
|
||||
images = resolve_reference_image_inputs(
|
||||
reference_image_1, reference_image_2, reference_image_3,
|
||||
reference_image_4, reference_image_5, image_references,
|
||||
)
|
||||
return cls(images, int(output_width), int(output_height), str(size_mode))
|
||||
|
||||
@property
|
||||
def connected_source_slot_ids(self) -> tuple[str, ...]:
|
||||
return tuple(
|
||||
slot_id for slot_id, image in zip(REFERENCE_SLOT_IDS, self.images, strict=True)
|
||||
if image is not None
|
||||
)
|
||||
|
||||
def prepare_selected(self, selected_source_slot_ids: tuple[str, ...]) -> ReferenceAssets | None:
|
||||
return prepare_reference_assets(
|
||||
reference_image_1=self.images[0],
|
||||
reference_image_2=self.images[1],
|
||||
reference_image_3=self.images[2],
|
||||
image_references=ReferenceImageBundle(self.images[3:]),
|
||||
output_width=self.output_width,
|
||||
output_height=self.output_height,
|
||||
size_mode=self.size_mode,
|
||||
selected_source_slot_ids=selected_source_slot_ids,
|
||||
)
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class GroupReferenceConditioning:
|
||||
physical_group: int
|
||||
logical_chunks: tuple[int, ...]
|
||||
requested_source_slot_ids: tuple[str, ...]
|
||||
selected_assets: ReferenceAssets | None
|
||||
picture_map: PictureMap
|
||||
effective_prompt: str
|
||||
conditioning: list[list[Any]]
|
||||
warnings: tuple[str, ...]
|
||||
|
||||
|
||||
def rewrite_reference_tags(prompt: str, picture_map: PictureMap) -> tuple[str, tuple[str, ...]]:
|
||||
"""Rewrite active @R tags only; inactive tags are diagnostic, never blocking."""
|
||||
|
||||
tags = {item.source_slot_id: item.picture_tag for item in picture_map.references}
|
||||
inactive: set[str] = set()
|
||||
|
||||
def replace_tag(match: re.Match[str]) -> str:
|
||||
slot_id = f"R{match.group(1)}"
|
||||
replacement = tags.get(slot_id)
|
||||
if replacement is None:
|
||||
inactive.add(slot_id)
|
||||
return match.group(0)
|
||||
return replacement
|
||||
|
||||
effective = _REFERENCE_TAG.sub(replace_tag, str(prompt))
|
||||
warnings = tuple(
|
||||
f"{slot_id} is not active in this physical group; {slot_id}'s @R tag was left unchanged"
|
||||
for slot_id in REFERENCE_SLOT_IDS if slot_id in inactive
|
||||
)
|
||||
return effective, warnings
|
||||
|
||||
|
||||
def resolve_reference_group_prompt(
|
||||
*, physical_group: int, prompt: str,
|
||||
requested_source_slot_ids: tuple[str, ...],
|
||||
connected_source_slot_ids: tuple[str, ...],
|
||||
picture_map: PictureMap,
|
||||
) -> tuple[str, tuple[str, ...]]:
|
||||
"""Use the same prompt and warning rules for planned and sampled groups."""
|
||||
|
||||
effective_prompt, prompt_warnings = rewrite_reference_tags(prompt, picture_map)
|
||||
connected = set(connected_source_slot_ids)
|
||||
disconnected_warnings = tuple(
|
||||
f"{slot_id} is routed to physical group {physical_group} but no image is connected"
|
||||
for slot_id in requested_source_slot_ids if slot_id not in connected
|
||||
)
|
||||
return effective_prompt, disconnected_warnings + prompt_warnings
|
||||
|
||||
|
||||
class ReferenceRoutingRuntime:
|
||||
"""Prepare and encode only the images selected by a physical group."""
|
||||
|
||||
def __init__(self, *, schedule: ReferenceRoutingSchedule, inputs: ReferenceInputSet):
|
||||
if not isinstance(schedule, ReferenceRoutingSchedule) or not schedule.valid:
|
||||
raise ReferenceRuntimeContractError("RR-R4 requires a valid RR-R2 routing schedule")
|
||||
if not isinstance(inputs, ReferenceInputSet) or len(inputs.images) != len(REFERENCE_SLOT_IDS):
|
||||
raise ReferenceRuntimeContractError("RR-R4 requires nine fixed raw Reference slots")
|
||||
self.schedule = schedule
|
||||
self.inputs = inputs
|
||||
# RR-R4 has no saved-run/prefix contract. Keep its session identity
|
||||
# queue-local without reading images assigned only to later groups.
|
||||
self._run_nonce = uuid.uuid4().hex
|
||||
self.storage_plan: Any = None
|
||||
self.generated_groups: tuple[int, ...] = ()
|
||||
self.accepted_chunks = 0
|
||||
self.observed_group_contracts: dict[int, dict[str, Any]] = {}
|
||||
self.group_warnings: dict[int, tuple[str, ...]] = {}
|
||||
|
||||
def group_contract_for(self, physical_group: int) -> dict[str, Any]:
|
||||
group = int(physical_group)
|
||||
observed = self.observed_group_contracts.get(group)
|
||||
if observed is not None:
|
||||
return observed
|
||||
if self.storage_plan is not None:
|
||||
return self.storage_plan.group_for(group)
|
||||
raise ReferenceRuntimeContractError(
|
||||
f"physical group {group} has no observed Reference contract"
|
||||
)
|
||||
|
||||
def check_physical_contract(self, *, chunks: int, terminal_merge_enabled: bool) -> None:
|
||||
if self.schedule.total_chunks != int(chunks) or self.schedule.terminal_merge_enabled != bool(terminal_merge_enabled):
|
||||
raise ReferenceRuntimeContractError(
|
||||
"RR-R4 routing schedule does not match the current physical group topology"
|
||||
)
|
||||
if any(route.status == "conflict" for route in self.schedule.physical_routes):
|
||||
raise ReferenceRuntimeContractError(
|
||||
"RR-R4 cannot select one Reference set for a conflicting terminal physical group"
|
||||
)
|
||||
|
||||
@property
|
||||
def has_selected_references(self) -> bool:
|
||||
connected = set(self.inputs.connected_source_slot_ids)
|
||||
return any(
|
||||
slot_id in connected
|
||||
for route in self.schedule.physical_routes
|
||||
for slot_id in (route.reference_slot_ids or ())
|
||||
)
|
||||
|
||||
def global_identity(self, keyframe_identity_hash: str) -> str:
|
||||
"""Queue-local identity; RR-R5 will define persistent prefix reuse."""
|
||||
|
||||
payload = {
|
||||
"rr_r4_identity_version": 1,
|
||||
"run_nonce": self._run_nonce,
|
||||
"keyframe_identity_hash": str(keyframe_identity_hash),
|
||||
"mode": self.schedule.mode,
|
||||
"logical_routes": [
|
||||
(route.logical_chunk, route.reference_slot_ids)
|
||||
for route in self.schedule.logical_routes
|
||||
],
|
||||
"physical_groups": [
|
||||
(route.physical_group, route.logical_chunks)
|
||||
for route in self.schedule.physical_routes
|
||||
],
|
||||
"connected_source_slot_ids": self.inputs.connected_source_slot_ids,
|
||||
"size_mode": self.inputs.size_mode,
|
||||
"output_size": (self.inputs.output_width, self.inputs.output_height),
|
||||
}
|
||||
return hashlib.sha256(
|
||||
json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
|
||||
).hexdigest()
|
||||
|
||||
def _route(self, physical_group: int):
|
||||
for route in self.schedule.physical_routes:
|
||||
if route.physical_group == physical_group:
|
||||
if route.status == "conflict" or route.reference_slot_ids is None:
|
||||
raise ReferenceRuntimeContractError(
|
||||
f"physical group {physical_group} has no single Reference route"
|
||||
)
|
||||
return route
|
||||
raise ReferenceRuntimeContractError(f"unknown physical group {physical_group}")
|
||||
|
||||
def prepare_group(
|
||||
self,
|
||||
*,
|
||||
physical_group: int,
|
||||
prompt: str,
|
||||
clip: Any,
|
||||
video_vae: Any,
|
||||
first_image: torch.Tensor | None,
|
||||
last_image: torch.Tensor | None,
|
||||
include_last_image: bool = True,
|
||||
reference_audio_assets: Any = None,
|
||||
timeline_video_assets: Any = None,
|
||||
reference_encode_cache: bool = False,
|
||||
cache_event: Any = None,
|
||||
expected_group_contract: dict[str, Any] | None = None,
|
||||
first_frame_hash: str = "none",
|
||||
last_frame_hash: str = "none",
|
||||
terminal_prompt_policy: str | None = None,
|
||||
) -> GroupReferenceConditioning:
|
||||
route = self._route(int(physical_group))
|
||||
requested = route.reference_slot_ids
|
||||
connected = set(self.inputs.connected_source_slot_ids)
|
||||
selected = tuple(slot_id for slot_id in requested if slot_id in connected)
|
||||
assets = self.inputs.prepare_selected(selected)
|
||||
if assets is not None and assets.source_slot_ids != selected:
|
||||
raise ReferenceRuntimeContractError("prepared Reference slots differ from the selected route")
|
||||
# The legacy no-Reference path presents Last Image only to the final
|
||||
# group. With References, Core's hybrid Qwen presentation includes it
|
||||
# in every group even though the Last keyframe is attached only at end.
|
||||
presented_last_image = last_image if assets is not None or include_last_image else None
|
||||
picture_map = compile_group_picture_map(
|
||||
source_slot_ids=assets.source_slot_ids if assets is not None else (),
|
||||
reference_image_hashes=assets.image_hashes if assets is not None else (),
|
||||
has_first_image=first_image is not None,
|
||||
has_last_image=presented_last_image is not None,
|
||||
)
|
||||
effective_prompt, warnings = resolve_reference_group_prompt(
|
||||
physical_group=int(physical_group), prompt=prompt,
|
||||
requested_source_slot_ids=requested,
|
||||
connected_source_slot_ids=self.inputs.connected_source_slot_ids,
|
||||
picture_map=picture_map,
|
||||
)
|
||||
# Direct RR-R4 callers predate the saved-plan fingerprints. The normal
|
||||
# V3.9 Sequence supplies both hashes; for an unsaved direct call only,
|
||||
# derive a truthful anchor from the exact image being presented.
|
||||
if expected_group_contract is None and self.storage_plan is None:
|
||||
from ..v2.h3_builder import _tensor_fingerprint
|
||||
if first_image is not None and first_frame_hash == "none":
|
||||
first_frame_hash = _tensor_fingerprint(first_image)
|
||||
if presented_last_image is not None and last_frame_hash == "none":
|
||||
last_frame_hash = _tensor_fingerprint(presented_last_image)
|
||||
from .reference_storage_contract import (
|
||||
ReferenceStorageContractError, canonical_sha256, descriptor_from_facts,
|
||||
)
|
||||
descriptor = descriptor_from_facts(
|
||||
physical_group=int(physical_group),
|
||||
logical_chunks=route.logical_chunks,
|
||||
selected_source_slot_ids=assets.source_slot_ids if assets is not None else (),
|
||||
prepared_image_hashes=assets.image_hashes if assets is not None else (),
|
||||
picture_map=picture_map,
|
||||
first_frame_hash=first_frame_hash,
|
||||
last_frame_hash=last_frame_hash,
|
||||
effective_prompt=effective_prompt,
|
||||
size_mode=self.inputs.size_mode,
|
||||
terminal_prompt_policy=terminal_prompt_policy,
|
||||
)
|
||||
group_contract = {"descriptor": descriptor, "sha256": canonical_sha256(descriptor)}
|
||||
if expected_group_contract is not None:
|
||||
if (canonical_sha256(descriptor) != expected_group_contract.get("sha256")
|
||||
or descriptor != expected_group_contract.get("descriptor")):
|
||||
raise ReferenceStorageContractError(
|
||||
f"physical group {physical_group} Reference inputs changed after the "
|
||||
"saved-run preflight; no VAE, Prompt, or Sampling was started"
|
||||
)
|
||||
if assets is not None:
|
||||
assets = (
|
||||
encode_reference_latents_cached(video_vae, assets, cache_event=cache_event)
|
||||
if reference_encode_cache else encode_reference_latents(video_vae, assets)
|
||||
)
|
||||
conditioning = encode_reference_prompt(
|
||||
clip, effective_prompt, assets,
|
||||
first_image=first_image,
|
||||
last_image=presented_last_image,
|
||||
reference_audio_assets=reference_audio_assets,
|
||||
timeline_video_assets=timeline_video_assets,
|
||||
)
|
||||
else:
|
||||
conditioning = encode_prompt_conditioning(
|
||||
clip, effective_prompt,
|
||||
first_image=first_image,
|
||||
last_image=presented_last_image,
|
||||
reference_audio_assets=reference_audio_assets,
|
||||
timeline_video_assets=timeline_video_assets,
|
||||
)
|
||||
existing = self.observed_group_contracts.get(int(physical_group))
|
||||
if existing is not None and existing != group_contract:
|
||||
raise ReferenceRuntimeContractError(
|
||||
f"physical group {physical_group} Reference contract changed within one Queue"
|
||||
)
|
||||
self.observed_group_contracts[int(physical_group)] = group_contract
|
||||
self.group_warnings[int(physical_group)] = warnings
|
||||
return GroupReferenceConditioning(
|
||||
physical_group=int(physical_group),
|
||||
logical_chunks=route.logical_chunks,
|
||||
requested_source_slot_ids=requested,
|
||||
selected_assets=assets,
|
||||
picture_map=picture_map,
|
||||
effective_prompt=effective_prompt,
|
||||
conditioning=conditioning,
|
||||
warnings=warnings,
|
||||
)
|
||||
@@ -0,0 +1,379 @@
|
||||
"""Private RR-R5 physical-group Reference persistence contract.
|
||||
|
||||
The stored descriptor records *effective* conditioning, not selector spelling.
|
||||
No VAE, CLIP, Sampling, or saved-run operation is performed here.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass, field
|
||||
import hashlib
|
||||
import json
|
||||
from typing import Any
|
||||
|
||||
from ..branch_provenance import physical_groups
|
||||
from ..reference import HYBRID_PRESENTATION_VERSION, REFERENCE_PREPROCESS_VERSION
|
||||
from .reference_effective_plan import PictureMap, compile_group_picture_map
|
||||
from .reference_routing import REFERENCE_SLOT_IDS
|
||||
|
||||
|
||||
REFERENCE_ROUTING_CONTRACT_VERSION = 1
|
||||
SESSION_ROUTING_IDENTITY_VERSION = 1
|
||||
_HEX = frozenset("0123456789abcdef")
|
||||
|
||||
|
||||
class ReferenceStorageContractError(ValueError):
|
||||
"""A routed producer or accepted-prefix contract cannot be trusted."""
|
||||
|
||||
|
||||
def canonical_json(value: Any) -> str:
|
||||
return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
|
||||
|
||||
|
||||
def canonical_sha256(value: Any) -> str:
|
||||
return hashlib.sha256(canonical_json(value).encode("utf-8")).hexdigest()
|
||||
|
||||
|
||||
def routed_session_identity(base_identity_hash: str) -> str:
|
||||
return canonical_sha256({
|
||||
"rr_r5_session_identity_version": SESSION_ROUTING_IDENTITY_VERSION,
|
||||
"base_identity_hash": str(base_identity_hash),
|
||||
})
|
||||
|
||||
|
||||
def _valid_sha(value: Any) -> bool:
|
||||
return isinstance(value, str) and len(value) == 64 and all(c in _HEX for c in value)
|
||||
|
||||
|
||||
def _anchor(value: str, present: bool) -> str | None:
|
||||
if not present:
|
||||
return None
|
||||
if not _valid_sha(value):
|
||||
raise ReferenceStorageContractError("routed First/Last image fingerprint is invalid")
|
||||
return value
|
||||
|
||||
|
||||
def _present(value: str) -> bool:
|
||||
if str(value).lower() in {"", "none", "null"}:
|
||||
return False
|
||||
if not _valid_sha(value):
|
||||
raise ReferenceStorageContractError("routed First/Last image fingerprint is invalid")
|
||||
return True
|
||||
|
||||
|
||||
def descriptor_from_facts(
|
||||
*, physical_group: int, logical_chunks: tuple[int, ...],
|
||||
selected_source_slot_ids: tuple[str, ...],
|
||||
prepared_image_hashes: tuple[str, ...], picture_map: PictureMap,
|
||||
first_frame_hash: str, last_frame_hash: str,
|
||||
effective_prompt: str, size_mode: str,
|
||||
terminal_prompt_policy: str | None,
|
||||
) -> dict[str, Any]:
|
||||
if len(selected_source_slot_ids) != len(prepared_image_hashes):
|
||||
raise ReferenceStorageContractError("selected Reference slots and image hashes differ")
|
||||
if picture_map.source_slot_ids != selected_source_slot_ids:
|
||||
raise ReferenceStorageContractError("Reference Picture map differs from selected source slots")
|
||||
if any(slot not in REFERENCE_SLOT_IDS for slot in selected_source_slot_ids):
|
||||
raise ReferenceStorageContractError("selected Reference slot is unknown")
|
||||
if tuple(sorted(selected_source_slot_ids, key=REFERENCE_SLOT_IDS.index)) != selected_source_slot_ids:
|
||||
raise ReferenceStorageContractError("selected Reference slots are not in fixed R1-R9 order")
|
||||
if len(set(selected_source_slot_ids)) != len(selected_source_slot_ids):
|
||||
raise ReferenceStorageContractError("selected Reference slot is duplicated")
|
||||
if any(not _valid_sha(value) for value in prepared_image_hashes):
|
||||
raise ReferenceStorageContractError("prepared Reference image hash is invalid")
|
||||
if any(item.image_sha256 != prepared_image_hashes[index]
|
||||
for index, item in enumerate(picture_map.references)):
|
||||
raise ReferenceStorageContractError("Reference Picture map image hash is inconsistent")
|
||||
if not logical_chunks or tuple(range(logical_chunks[0], logical_chunks[-1] + 1)) != logical_chunks:
|
||||
raise ReferenceStorageContractError("physical group logical chunks are not contiguous")
|
||||
if int(physical_group) != logical_chunks[0]:
|
||||
raise ReferenceStorageContractError("physical group number differs from its first logical chunk")
|
||||
if (len(logical_chunks) > 1) != (terminal_prompt_policy is not None):
|
||||
raise ReferenceStorageContractError("terminal prompt policy does not match physical group")
|
||||
first_present = picture_map.first_picture_number is not None
|
||||
last_present = picture_map.last_picture_number is not None
|
||||
order = []
|
||||
if first_present:
|
||||
order.append("first_frame")
|
||||
if last_present:
|
||||
order.append("last_frame")
|
||||
order.extend(selected_source_slot_ids)
|
||||
descriptor: dict[str, Any] = {
|
||||
"version": REFERENCE_ROUTING_CONTRACT_VERSION,
|
||||
"physical_group": int(physical_group),
|
||||
"logical_chunks": list(logical_chunks),
|
||||
"terminal_atomic": len(logical_chunks) > 1,
|
||||
"references": [
|
||||
{
|
||||
"source_slot_id": slot_id,
|
||||
"prepared_sha256": prepared_image_hashes[index],
|
||||
"picture_number": picture_map.references[index].picture_number,
|
||||
}
|
||||
for index, slot_id in enumerate(selected_source_slot_ids)
|
||||
],
|
||||
"first_anchor": _anchor(first_frame_hash, first_present),
|
||||
"last_anchor": _anchor(last_frame_hash, last_present),
|
||||
"picture_order": order,
|
||||
"picture_presentation_version": HYBRID_PRESENTATION_VERSION,
|
||||
"effective_prompt_sha256": hashlib.sha256(str(effective_prompt).encode("utf-8")).hexdigest(),
|
||||
"terminal_prompt_policy": str(terminal_prompt_policy) if len(logical_chunks) > 1 else None,
|
||||
}
|
||||
if selected_source_slot_ids:
|
||||
descriptor["reference_size_mode"] = str(size_mode)
|
||||
descriptor["reference_preprocess_version"] = REFERENCE_PREPROCESS_VERSION
|
||||
return descriptor
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class ReferenceStoragePlan:
|
||||
"""Canonical JSON is immutable even if the caller's source dicts are not."""
|
||||
|
||||
descriptor_jsons: tuple[str, ...]
|
||||
routing_config_sha256: str
|
||||
requested_routes: tuple[tuple[str, ...], ...]
|
||||
_group_index: dict[int, int] = field(init=False, repr=False, compare=False, hash=False)
|
||||
|
||||
def __post_init__(self) -> None:
|
||||
index: dict[int, int] = {}
|
||||
for position, payload in enumerate(self.descriptor_jsons):
|
||||
descriptor = json.loads(payload)
|
||||
# Preserve the former first-match lookup for duplicate group IDs.
|
||||
index.setdefault(int(descriptor["physical_group"]), position)
|
||||
object.__setattr__(self, "_group_index", index)
|
||||
|
||||
def _record_at(self, position: int) -> dict[str, Any]:
|
||||
payload = self.descriptor_jsons[position]
|
||||
return {
|
||||
"descriptor": json.loads(payload),
|
||||
"sha256": hashlib.sha256(payload.encode("utf-8")).hexdigest(),
|
||||
}
|
||||
|
||||
@property
|
||||
def group_contracts(self) -> list[dict[str, Any]]:
|
||||
return [self._record_at(position) for position in range(len(self.descriptor_jsons))]
|
||||
|
||||
def group_for(self, physical_group: int) -> dict[str, Any]:
|
||||
position = self._group_index.get(int(physical_group))
|
||||
if position is None:
|
||||
raise ReferenceStorageContractError(
|
||||
f"physical group {physical_group} has no frozen Reference contract"
|
||||
)
|
||||
return self._record_at(position)
|
||||
|
||||
def audit(self) -> dict[str, Any]:
|
||||
return {
|
||||
"version": REFERENCE_ROUTING_CONTRACT_VERSION,
|
||||
"routing_config_sha256": self.routing_config_sha256,
|
||||
"requested_routes": [list(route) for route in self.requested_routes],
|
||||
}
|
||||
|
||||
|
||||
def build_reference_storage_plan(
|
||||
*, runtime: Any, prompts: list[str], first_frame_hash: str,
|
||||
last_frame_hash: str, terminal_prompt: str | None = None,
|
||||
terminal_prompt_policy: str | None = None,
|
||||
through_chunk: int | None = None,
|
||||
) -> ReferenceStoragePlan:
|
||||
"""Prehash only connected R slots selected by the requested group prefix."""
|
||||
from .reference_runtime import ReferenceRoutingRuntime, resolve_reference_group_prompt
|
||||
|
||||
if not isinstance(runtime, ReferenceRoutingRuntime):
|
||||
raise ReferenceStorageContractError("routed storage requires ReferenceRoutingRuntime")
|
||||
schedule = runtime.schedule
|
||||
total = int(schedule.total_chunks or 0)
|
||||
if total < 1 or len(prompts) != total:
|
||||
raise ReferenceStorageContractError("Reference schedule and prompt count differ")
|
||||
runtime.check_physical_contract(
|
||||
chunks=total, terminal_merge_enabled=bool(schedule.terminal_merge_enabled),
|
||||
)
|
||||
limit = total if through_chunk is None else int(through_chunk)
|
||||
if limit < 1 or limit > total:
|
||||
raise ReferenceStorageContractError("Reference plan prefix is outside configured chunks")
|
||||
routes = [route for route in schedule.physical_routes if route.logical_chunks[-1] <= limit]
|
||||
if not routes or routes[-1].logical_chunks[-1] != limit:
|
||||
raise ReferenceStorageContractError("Reference plan prefix ends inside a physical group")
|
||||
connected = set(runtime.inputs.connected_source_slot_ids)
|
||||
selected = {slot for route in routes for slot in (route.reference_slot_ids or ()) if slot in connected}
|
||||
image_hashes: dict[str, str] = {}
|
||||
for slot in REFERENCE_SLOT_IDS:
|
||||
if slot not in selected:
|
||||
continue
|
||||
assets = runtime.inputs.prepare_selected((slot,))
|
||||
if assets is None or assets.source_slot_ids != (slot,) or len(assets.image_hashes) != 1:
|
||||
raise ReferenceStorageContractError(f"selected {slot} cannot be prepared")
|
||||
image_hashes[slot] = assets.image_hashes[0]
|
||||
del assets
|
||||
descriptor_jsons: list[str] = []
|
||||
requested_routes: list[tuple[str, ...]] = []
|
||||
pending_group_warnings: dict[int, tuple[str, ...]] = {}
|
||||
for route in routes:
|
||||
requested = route.reference_slot_ids
|
||||
if requested is None:
|
||||
raise ReferenceStorageContractError("conflicting terminal Reference route")
|
||||
requested_routes.append(requested)
|
||||
source_slots = tuple(slot for slot in requested if slot in connected)
|
||||
hashes = tuple(image_hashes[slot] for slot in source_slots)
|
||||
final = route.logical_chunks[-1] == total
|
||||
has_first = _present(first_frame_hash)
|
||||
has_last = _present(last_frame_hash) and (bool(source_slots) or final)
|
||||
picture_map = compile_group_picture_map(
|
||||
source_slot_ids=source_slots,
|
||||
reference_image_hashes=hashes,
|
||||
has_first_image=has_first,
|
||||
has_last_image=has_last,
|
||||
)
|
||||
prompt = (
|
||||
terminal_prompt if len(route.logical_chunks) > 1
|
||||
else prompts[route.logical_chunks[0] - 1]
|
||||
)
|
||||
if prompt is None:
|
||||
raise ReferenceStorageContractError("terminal physical prompt is unavailable")
|
||||
effective_prompt, warnings = resolve_reference_group_prompt(
|
||||
physical_group=int(route.physical_group), prompt=prompt,
|
||||
requested_source_slot_ids=requested,
|
||||
connected_source_slot_ids=runtime.inputs.connected_source_slot_ids,
|
||||
picture_map=picture_map,
|
||||
)
|
||||
pending_group_warnings[int(route.physical_group)] = warnings
|
||||
descriptor = descriptor_from_facts(
|
||||
physical_group=route.physical_group,
|
||||
logical_chunks=route.logical_chunks,
|
||||
selected_source_slot_ids=source_slots,
|
||||
prepared_image_hashes=hashes,
|
||||
picture_map=picture_map,
|
||||
first_frame_hash=first_frame_hash,
|
||||
last_frame_hash=last_frame_hash,
|
||||
effective_prompt=effective_prompt,
|
||||
size_mode=runtime.inputs.size_mode,
|
||||
terminal_prompt_policy=terminal_prompt_policy if len(route.logical_chunks) > 1 else None,
|
||||
)
|
||||
descriptor_jsons.append(canonical_json(descriptor))
|
||||
routing_config_sha256 = canonical_sha256({
|
||||
"version": REFERENCE_ROUTING_CONTRACT_VERSION,
|
||||
"mode": schedule.mode,
|
||||
"logical_routes": [
|
||||
[route.logical_chunk, list(route.reference_slot_ids)]
|
||||
for route in schedule.logical_routes
|
||||
],
|
||||
})
|
||||
plan = ReferenceStoragePlan(
|
||||
tuple(descriptor_jsons), routing_config_sha256, tuple(requested_routes)
|
||||
)
|
||||
runtime.group_warnings.update({
|
||||
group: warnings for group, warnings in pending_group_warnings.items()
|
||||
if group not in runtime.observed_group_contracts
|
||||
})
|
||||
return plan
|
||||
|
||||
|
||||
def validate_reference_group_contracts(
|
||||
records: Any, *, chunk_count: int, terminal_merge_enabled: bool,
|
||||
) -> list[dict[str, Any]]:
|
||||
"""Validate the complete routed stored plan, not just its declared hashes."""
|
||||
expected = physical_groups(chunks=chunk_count, terminal_merge_enabled=terminal_merge_enabled)
|
||||
if not isinstance(records, list) or len(records) != len(expected):
|
||||
raise ReferenceStorageContractError("stored Reference group count does not match physical topology")
|
||||
clean: list[dict[str, Any]] = []
|
||||
for record, group in zip(records, expected):
|
||||
if not isinstance(record, dict) or not isinstance(record.get("descriptor"), dict):
|
||||
raise ReferenceStorageContractError("stored Reference group descriptor is missing")
|
||||
descriptor = record["descriptor"]
|
||||
if descriptor.get("version") != REFERENCE_ROUTING_CONTRACT_VERSION:
|
||||
raise ReferenceStorageContractError("stored Reference group version is unsupported")
|
||||
if (descriptor.get("physical_group") != group.physical_group
|
||||
or descriptor.get("logical_chunks") != list(range(group.start, group.end + 1))
|
||||
or descriptor.get("terminal_atomic") is not (group.start != group.end)):
|
||||
raise ReferenceStorageContractError("stored Reference group boundary is invalid")
|
||||
if not _valid_sha(record.get("sha256")) or canonical_sha256(descriptor) != record["sha256"]:
|
||||
raise ReferenceStorageContractError("stored Reference group SHA-256 is invalid")
|
||||
refs = descriptor.get("references")
|
||||
if not isinstance(refs, list):
|
||||
raise ReferenceStorageContractError("stored Reference group source list is invalid")
|
||||
slots = [ref.get("source_slot_id") for ref in refs if isinstance(ref, dict)]
|
||||
if (len(slots) != len(refs) or any(slot not in REFERENCE_SLOT_IDS for slot in slots)
|
||||
or slots != sorted(set(slots), key=REFERENCE_SLOT_IDS.index)
|
||||
or any(not _valid_sha(ref.get("prepared_sha256")) for ref in refs)):
|
||||
raise ReferenceStorageContractError("stored Reference group source identity is invalid")
|
||||
expected_order = (["first_frame"] if descriptor.get("first_anchor") else [])
|
||||
expected_order += (["last_frame"] if descriptor.get("last_anchor") else [])
|
||||
expected_order += slots
|
||||
if descriptor.get("picture_order") != expected_order:
|
||||
raise ReferenceStorageContractError("stored Reference Picture order is invalid")
|
||||
if descriptor.get("picture_presentation_version") != HYBRID_PRESENTATION_VERSION:
|
||||
raise ReferenceStorageContractError("stored Reference Picture presentation version is invalid")
|
||||
offset = int(descriptor.get("first_anchor") is not None) + int(
|
||||
descriptor.get("last_anchor") is not None
|
||||
)
|
||||
if any(ref.get("picture_number") != offset + index + 1
|
||||
for index, ref in enumerate(refs)):
|
||||
raise ReferenceStorageContractError("stored Reference Picture numbers are invalid")
|
||||
if (group.start != group.end) != (descriptor.get("terminal_prompt_policy") is not None):
|
||||
raise ReferenceStorageContractError("stored terminal prompt policy is invalid")
|
||||
if any(not _valid_sha(descriptor.get(name)) for name in ("effective_prompt_sha256",)):
|
||||
raise ReferenceStorageContractError("stored Reference effective Prompt hash is invalid")
|
||||
if any(descriptor.get(name) is not None and not _valid_sha(descriptor[name])
|
||||
for name in ("first_anchor", "last_anchor")):
|
||||
raise ReferenceStorageContractError("stored Reference anchor hash is invalid")
|
||||
if refs and (descriptor.get("reference_preprocess_version") != REFERENCE_PREPROCESS_VERSION
|
||||
or not isinstance(descriptor.get("reference_size_mode"), str)):
|
||||
raise ReferenceStorageContractError("stored Reference preprocessing contract is invalid")
|
||||
if not refs and ("reference_preprocess_version" in descriptor or "reference_size_mode" in descriptor):
|
||||
raise ReferenceStorageContractError("empty Reference group has preprocessing metadata")
|
||||
clean.append(record)
|
||||
return clean
|
||||
|
||||
|
||||
def session_routing_settings(plan: ReferenceStoragePlan, accepted_chunks: int) -> dict[str, Any]:
|
||||
accepted: list[dict[str, Any]] = []
|
||||
for record in plan.group_contracts:
|
||||
descriptor = record["descriptor"]
|
||||
end = int(descriptor["logical_chunks"][-1])
|
||||
if end > accepted_chunks:
|
||||
break
|
||||
accepted.append({
|
||||
"physical_group": int(descriptor["physical_group"]),
|
||||
"logical_chunks": list(descriptor["logical_chunks"]),
|
||||
"sha256": record["sha256"],
|
||||
})
|
||||
if not accepted or accepted[-1]["logical_chunks"][-1] != accepted_chunks:
|
||||
raise ReferenceStorageContractError("accepted Session ends inside a physical group")
|
||||
return {
|
||||
"version": REFERENCE_ROUTING_CONTRACT_VERSION,
|
||||
"accepted_groups": accepted,
|
||||
"routing_config_sha256": plan.routing_config_sha256,
|
||||
}
|
||||
|
||||
|
||||
def compatible_session_prefix(
|
||||
evidence: Any, plan: ReferenceStoragePlan, *, saved_chunks: int,
|
||||
) -> int:
|
||||
"""Return a complete-group accepted prefix; malformed evidence is rejected."""
|
||||
if not isinstance(evidence, dict) or evidence.get("version") != REFERENCE_ROUTING_CONTRACT_VERSION:
|
||||
raise ReferenceStorageContractError("saved Session has no RR-R5 group evidence")
|
||||
groups = evidence.get("accepted_groups")
|
||||
if not isinstance(groups, list) or not groups:
|
||||
raise ReferenceStorageContractError("saved Session group evidence is missing")
|
||||
last_end = 0
|
||||
for position, item in enumerate(groups):
|
||||
if not isinstance(item, dict) or not _valid_sha(item.get("sha256")):
|
||||
raise ReferenceStorageContractError("saved Session group hash is invalid")
|
||||
chunks = item.get("logical_chunks")
|
||||
if (not isinstance(chunks, list) or not chunks or chunks[0] != last_end + 1
|
||||
or chunks != list(range(chunks[0], chunks[-1] + 1))
|
||||
or item.get("physical_group") != chunks[0]):
|
||||
raise ReferenceStorageContractError("saved Session group boundaries are invalid")
|
||||
last_end = chunks[-1]
|
||||
if last_end != saved_chunks:
|
||||
raise ReferenceStorageContractError("saved Session group evidence does not cover its chunks")
|
||||
preserved = 0
|
||||
current = plan.group_contracts
|
||||
for position, item in enumerate(groups):
|
||||
if position >= len(current):
|
||||
break
|
||||
now = current[position]
|
||||
if (item["physical_group"] != now["descriptor"]["physical_group"]
|
||||
or item["logical_chunks"] != now["descriptor"]["logical_chunks"]
|
||||
or item["sha256"] != now["sha256"]):
|
||||
break
|
||||
preserved = item["logical_chunks"][-1]
|
||||
return preserved
|
||||
@@ -9,6 +9,7 @@ without mutating the captured source context.
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import Mapping, Sequence
|
||||
import copy
|
||||
from types import MappingProxyType
|
||||
from typing import Any
|
||||
|
||||
@@ -141,6 +142,7 @@ def make_refine_group(
|
||||
first_image: torch.Tensor | None = None,
|
||||
last_image: torch.Tensor | None = None,
|
||||
guide_images: Mapping[int, torch.Tensor] | None = None,
|
||||
reference_routing_group_contract: Mapping[str, Any] | None = None,
|
||||
) -> dict[str, Any]:
|
||||
"""Capture one physical First Pass sampling group's effective conditioning."""
|
||||
|
||||
@@ -182,6 +184,15 @@ def make_refine_group(
|
||||
frozen_guides = _guide_image_map(guide_images)
|
||||
if frozen_guides:
|
||||
output["guide_images"] = frozen_guides
|
||||
if reference_routing_group_contract is not None:
|
||||
from .reference_storage_contract import canonical_sha256
|
||||
descriptor = reference_routing_group_contract.get("descriptor")
|
||||
digest = reference_routing_group_contract.get("sha256")
|
||||
if not isinstance(descriptor, dict) or canonical_sha256(descriptor) != digest:
|
||||
raise RefineContextError("refine group Reference contract SHA-256 is invalid")
|
||||
if descriptor.get("logical_chunks") != list(chunks):
|
||||
raise RefineContextError("refine group Reference contract has different logical chunks")
|
||||
output["reference_routing_v1"] = copy.deepcopy(dict(reference_routing_group_contract))
|
||||
return output
|
||||
|
||||
|
||||
@@ -307,6 +318,16 @@ def validate_refine_context(
|
||||
group.get("guide_images"),
|
||||
physical_frames=int(group["physical_frames"]),
|
||||
)
|
||||
route_contract = group.get("reference_routing_v1")
|
||||
if route_contract is not None:
|
||||
from .reference_storage_contract import canonical_sha256
|
||||
if not isinstance(route_contract, Mapping):
|
||||
raise RefineContextError("refine group Reference contract is invalid")
|
||||
descriptor = route_contract.get("descriptor")
|
||||
if (not isinstance(descriptor, dict)
|
||||
or canonical_sha256(descriptor) != route_contract.get("sha256")
|
||||
or descriptor.get("logical_chunks") != list(logical_chunks)):
|
||||
raise RefineContextError("refine group Reference contract differs from its content")
|
||||
|
||||
if assembly_plan is not None:
|
||||
if not isinstance(assembly_plan, Mapping):
|
||||
@@ -337,6 +358,21 @@ def validate_refine_context(
|
||||
f"refine group {group_id} has no matching assembly-plan group"
|
||||
)
|
||||
planned = plan_groups[group_id]
|
||||
route_view = assembly_plan.get("reference_routing_v1")
|
||||
if route_view is not None:
|
||||
view_groups = route_view.get("groups") if isinstance(route_view, Mapping) else None
|
||||
expected_route = (
|
||||
view_groups[group_id] if isinstance(view_groups, list)
|
||||
and group_id < len(view_groups) else None
|
||||
)
|
||||
captured_route = group.get("reference_routing_v1")
|
||||
if (not isinstance(expected_route, Mapping)
|
||||
or not isinstance(captured_route, Mapping)
|
||||
or captured_route.get("sha256") != expected_route.get("contract_sha256")
|
||||
or captured_route.get("descriptor") != expected_route.get("descriptor")):
|
||||
raise RefineContextError(
|
||||
f"refine group {group_id} Reference route differs from First Pass Plan"
|
||||
)
|
||||
comparisons = (
|
||||
("logical_chunks", tuple(int(v) for v in group["logical_chunks"]),
|
||||
tuple(int(v) for v in planned.get("logical_chunks", ()))),
|
||||
|
||||
@@ -376,6 +376,10 @@ def prepare_physical_refine_groups(
|
||||
"adaptation_stats": adaptation_stats,
|
||||
"physical_clip_index": physical_clip_index,
|
||||
"context_frames": context_frames,
|
||||
"reference_routing_v1": (
|
||||
captured_group.get("reference_routing_v1")
|
||||
if captured_group is not None else None
|
||||
),
|
||||
}
|
||||
if group_consumer_fn is not None:
|
||||
group_consumer_fn(
|
||||
@@ -472,7 +476,9 @@ def run_second_pass_groups(
|
||||
)
|
||||
group_seeds: list[int] = []
|
||||
conditioning_sources: list[str] = []
|
||||
reference_inheritance: list[dict[str, Any]] = []
|
||||
group_report_lines: list[str] = []
|
||||
routed_first_pass = isinstance(assembly_plan.get("reference_routing_v1"), Mapping)
|
||||
|
||||
def sample_prepared_group(
|
||||
group_index,
|
||||
@@ -492,6 +498,17 @@ def run_second_pass_groups(
|
||||
physical_seed = derive_refine_seed(int(refine_seed), group_index)
|
||||
group_seeds.append(physical_seed)
|
||||
conditioning_sources.append(conditioning_source)
|
||||
route_record = detail.get("reference_routing_v1")
|
||||
inheritance = (
|
||||
"verified" if conditioning_source == "refine_context" and route_record is not None
|
||||
else "not_inherited" if routed_first_pass
|
||||
else "not_applicable"
|
||||
)
|
||||
reference_inheritance.append({
|
||||
"physical_group": group_index + 1,
|
||||
"status": inheritance,
|
||||
"contract_sha256": route_record.get("sha256") if route_record is not None else None,
|
||||
})
|
||||
nested_latent = latent_builder(video_samples, audio_samples)
|
||||
sample_arguments = dict(
|
||||
model=chunk_model,
|
||||
@@ -530,6 +547,7 @@ def run_second_pass_groups(
|
||||
f"{group_index + 1}: logical_chunks={group.get('logical_chunks')}, "
|
||||
f"prompt_policy={group.get('prompt_policy', 'unknown')}, "
|
||||
f"conditioning_source={conditioning_source}, "
|
||||
f"reference_inheritance={inheritance}, "
|
||||
f"physical_clip_index={physical_clip_index}, "
|
||||
f"context_frames={context_frames}, "
|
||||
f"refine_seed={physical_seed}, shape={tuple(refined_video.shape)}, "
|
||||
@@ -607,6 +625,8 @@ def run_second_pass_groups(
|
||||
else:
|
||||
contract["execution"] = "t2va_physical_groups_audio_locked_v2"
|
||||
contract["conditioning_sources"] = conditioning_sources
|
||||
if any(item["status"] != "not_applicable" for item in reference_inheritance):
|
||||
contract["reference_inheritance"] = reference_inheritance
|
||||
contract["refine_seed_base"] = int(refine_seed)
|
||||
contract["refine_group_seeds"] = group_seeds
|
||||
contract["audio_output"] = "bit_exact_first_pass_passthrough"
|
||||
|
||||
Reference in New Issue
Block a user