222 lines
7.1 KiB
Python
222 lines
7.1 KiB
Python
"""Explicit opt-in A7b memory actions that preserve Production ownership.
|
|
|
|
This module resolves only Reference sizing policy. Model unloading and
|
|
attention/backend selection remain advisory because ComfyUI Core and external
|
|
MODEL wrappers own those lifecycles.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from dataclasses import dataclass
|
|
import hashlib
|
|
import json
|
|
from typing import Any
|
|
|
|
from ..reference import REFERENCE_SIZE_MATCH_OUTPUT, REFERENCE_SIZE_MAX_IDENTITY
|
|
from ..reference_video import (
|
|
REFERENCE_VIDEO_SIZE_BALANCED,
|
|
REFERENCE_VIDEO_SIZE_EFFICIENT,
|
|
REFERENCE_VIDEO_SIZE_MATCH_OUTPUT,
|
|
)
|
|
|
|
|
|
MEMORY_ACTION_POLICY_TYPE = "H3_CONTINUUM_MEMORY_ACTION_POLICY"
|
|
MEMORY_ACTION_POLICY_VERSION = 1
|
|
|
|
ACTION_DISABLED = "Disabled"
|
|
ACTION_REDUCE_REFERENCES_ONE_STEP = "Reduce References One Step"
|
|
ACTION_OPTIONS = (
|
|
ACTION_DISABLED,
|
|
ACTION_REDUCE_REFERENCES_ONE_STEP,
|
|
)
|
|
|
|
_IMAGE_DOWNGRADE = {
|
|
REFERENCE_SIZE_MAX_IDENTITY: REFERENCE_SIZE_MATCH_OUTPUT,
|
|
REFERENCE_SIZE_MATCH_OUTPUT: REFERENCE_SIZE_MATCH_OUTPUT,
|
|
}
|
|
_VIDEO_DOWNGRADE = {
|
|
REFERENCE_VIDEO_SIZE_MATCH_OUTPUT: REFERENCE_VIDEO_SIZE_BALANCED,
|
|
REFERENCE_VIDEO_SIZE_BALANCED: REFERENCE_VIDEO_SIZE_EFFICIENT,
|
|
REFERENCE_VIDEO_SIZE_EFFICIENT: REFERENCE_VIDEO_SIZE_EFFICIENT,
|
|
}
|
|
|
|
|
|
def _canonical_hash(value: Any) -> str:
|
|
payload = json.dumps(
|
|
value,
|
|
sort_keys=True,
|
|
separators=(",", ":"),
|
|
ensure_ascii=True,
|
|
).encode("utf-8")
|
|
return hashlib.sha256(payload).hexdigest()
|
|
|
|
|
|
def _contract_base(action: str) -> dict[str, Any]:
|
|
return {
|
|
"memory_action_policy_version": MEMORY_ACTION_POLICY_VERSION,
|
|
"action": action,
|
|
"reference_downgrade": (
|
|
"one_step"
|
|
if action == ACTION_REDUCE_REFERENCES_ONE_STEP
|
|
else "disabled"
|
|
),
|
|
"auto_unload": "advisory_only",
|
|
"backend_switch": "advisory_only",
|
|
"same_run_actual_row_trigger": False,
|
|
}
|
|
|
|
|
|
def make_memory_action_policy(action: str = ACTION_DISABLED) -> dict[str, Any]:
|
|
"""Build the versioned policy object emitted by the public helper node."""
|
|
|
|
normalized = str(action)
|
|
if normalized not in ACTION_OPTIONS:
|
|
raise ValueError(f"unsupported memory action {action!r}")
|
|
contract = _contract_base(normalized)
|
|
return {**contract, "contract_hash": _canonical_hash(contract)}
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class MemoryActionDecision:
|
|
action: str
|
|
enabled: bool
|
|
requested_image_mode: str
|
|
effective_image_mode: str
|
|
requested_video_mode: str
|
|
effective_video_mode: str
|
|
image_applied: bool
|
|
video_applied: bool
|
|
contract_hash: str | None
|
|
warning: str | None = None
|
|
|
|
@property
|
|
def applied(self) -> bool:
|
|
return bool(self.image_applied or self.video_applied)
|
|
|
|
|
|
def _disabled_decision(
|
|
*,
|
|
image_mode: str,
|
|
video_mode: str,
|
|
contract_hash: str | None = None,
|
|
warning: str | None = None,
|
|
) -> MemoryActionDecision:
|
|
return MemoryActionDecision(
|
|
action=ACTION_DISABLED,
|
|
enabled=False,
|
|
requested_image_mode=image_mode,
|
|
effective_image_mode=image_mode,
|
|
requested_video_mode=video_mode,
|
|
effective_video_mode=video_mode,
|
|
image_applied=False,
|
|
video_applied=False,
|
|
contract_hash=contract_hash,
|
|
warning=warning,
|
|
)
|
|
|
|
|
|
def resolve_memory_action_policy(
|
|
policy: Any,
|
|
*,
|
|
image_mode: str,
|
|
video_mode: str,
|
|
has_reference_images: bool,
|
|
has_video_guide: bool,
|
|
) -> MemoryActionDecision:
|
|
"""Resolve an optional policy without changing tensors or runtime state.
|
|
|
|
Malformed or unsupported objects fail soft to Disabled. The caller may
|
|
surface ``warning`` after generation, but Sampling inputs remain unchanged.
|
|
"""
|
|
|
|
requested_image = str(image_mode)
|
|
requested_video = str(video_mode)
|
|
if policy is None:
|
|
return _disabled_decision(
|
|
image_mode=requested_image,
|
|
video_mode=requested_video,
|
|
)
|
|
if not isinstance(policy, dict):
|
|
return _disabled_decision(
|
|
image_mode=requested_image,
|
|
video_mode=requested_video,
|
|
warning="invalid policy object; no memory action was applied",
|
|
)
|
|
|
|
action = str(policy.get("action", ""))
|
|
try:
|
|
version = int(policy.get("memory_action_policy_version"))
|
|
except (TypeError, ValueError):
|
|
version = -1
|
|
supplied_hash = policy.get("contract_hash")
|
|
expected_contract = _contract_base(action) if action in ACTION_OPTIONS else None
|
|
expected_hash = (
|
|
_canonical_hash(expected_contract) if expected_contract is not None else None
|
|
)
|
|
if (
|
|
version != MEMORY_ACTION_POLICY_VERSION
|
|
or action not in ACTION_OPTIONS
|
|
or not isinstance(supplied_hash, str)
|
|
or supplied_hash != expected_hash
|
|
):
|
|
return _disabled_decision(
|
|
image_mode=requested_image,
|
|
video_mode=requested_video,
|
|
warning="unsupported or modified policy contract; no memory action was applied",
|
|
)
|
|
if action == ACTION_DISABLED:
|
|
return _disabled_decision(
|
|
image_mode=requested_image,
|
|
video_mode=requested_video,
|
|
contract_hash=supplied_hash,
|
|
)
|
|
|
|
effective_image = requested_image
|
|
effective_video = requested_video
|
|
if bool(has_reference_images):
|
|
effective_image = _IMAGE_DOWNGRADE.get(requested_image, requested_image)
|
|
if bool(has_video_guide):
|
|
effective_video = _VIDEO_DOWNGRADE.get(requested_video, requested_video)
|
|
return MemoryActionDecision(
|
|
action=action,
|
|
enabled=True,
|
|
requested_image_mode=requested_image,
|
|
effective_image_mode=effective_image,
|
|
requested_video_mode=requested_video,
|
|
effective_video_mode=effective_video,
|
|
image_applied=(
|
|
bool(has_reference_images) and effective_image != requested_image
|
|
),
|
|
video_applied=(bool(has_video_guide) and effective_video != requested_video),
|
|
contract_hash=supplied_hash,
|
|
)
|
|
|
|
|
|
def format_memory_action_status(decision: MemoryActionDecision) -> str | None:
|
|
"""Format post-generation status without claiming VRAM prediction."""
|
|
|
|
if decision.warning is not None:
|
|
return "Memory Action Policy [Experimental A7b v1]: " + decision.warning + "."
|
|
if not decision.enabled:
|
|
return None
|
|
changes: list[str] = []
|
|
if decision.image_applied:
|
|
changes.append(
|
|
"Reference Image "
|
|
f"{decision.requested_image_mode} -> {decision.effective_image_mode}"
|
|
)
|
|
if decision.video_applied:
|
|
changes.append(
|
|
"Video Guide "
|
|
f"{decision.requested_video_mode} -> {decision.effective_video_mode}"
|
|
)
|
|
action = "; ".join(changes) if changes else "no applicable Reference downgrade"
|
|
return (
|
|
"Memory Action Policy [Experimental A7b v1]: explicit opt-in; "
|
|
f"{action}.\n"
|
|
"Memory advisory: automatic MODEL unload was not executed; Core retains "
|
|
"lifecycle ownership.\n"
|
|
"Memory advisory: automatic attention/backend switching was not executed; "
|
|
"the external MODEL wrapper was preserved."
|
|
)
|