Files
ComfyUI-H3-Continuum-Tiled/v3/reference_effective_plan.py

288 lines
12 KiB
Python

"""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),
)