Vito Sansevero
4b4fa7f8ff
The #390 ruling queues a file that only its saver's file name resolves for Needs review, never linking it. inspection_resolution gains name_anchor; the ladder passes False, so such a file falls to the legacy floor in the scan (and to Needs review) and is never stored by the monitor, while the recorded saver still decides. The inspector keeps the name anchor.
772 lines
30 KiB
Python
772 lines
30 KiB
Python
"""Read prompt evidence without inference, indexing, or decoding image pixels.
|
|
|
|
``inspection_resolution`` is the inspector's resolve (inspection profile, then
|
|
the recorded saver anchor, #386). Ingestion (the output scan, through
|
|
``utils.file_prompt``) calls it too, only for files the default profile
|
|
cannot decide (#247), so the inspector and ingestion cannot drift.
|
|
"""
|
|
|
|
import hashlib
|
|
import io
|
|
import json
|
|
import re
|
|
import struct
|
|
import subprocess # nosec B404
|
|
import threading
|
|
import zlib
|
|
from dataclasses import dataclass, field as dataclass_field
|
|
from pathlib import Path
|
|
from collections.abc import Mapping
|
|
from typing import Any
|
|
|
|
from PIL import Image
|
|
|
|
from .inspection_outcomes import UNREADABLE_METADATA_REASON, outcome_message
|
|
from .pair_execution import EXECUTION_KEY
|
|
from .prompt_pair_resolver import (
|
|
_FOOTER,
|
|
EMPTY_POSITIVE_REASON,
|
|
INSPECTION_PROFILE,
|
|
MALFORMED_EVIDENCE_REASON,
|
|
ResolverProfile,
|
|
resolve_prompt_pair,
|
|
)
|
|
from .video_metadata import (
|
|
ENVELOPE_TAG_KEYS,
|
|
ROLE_TAG_KEYS,
|
|
VIDEO_TAG_KEYS,
|
|
DuplicateVideoTagError,
|
|
ffprobe_path,
|
|
is_video_path,
|
|
select_video_carrier,
|
|
)
|
|
|
|
# Role records (prompt, parameters, the pair execution record) share one
|
|
# budget, encoded and decoded: roles cannot be trusted from a partial record,
|
|
# so exceeding it fails the whole read. A workflow has its own budget; past it
|
|
# only the workflow is ``limited``. Other text chunks are never retained.
|
|
ROLE_METADATA_BYTES = 2 * 1024 * 1024
|
|
WORKFLOW_METADATA_BYTES = 4 * 1024 * 1024
|
|
# Total bytes read for byte-identical duplicate chunks of one file, per class
|
|
# so workflow repeats can never starve role records: two budgets each, making
|
|
# repeated chunks cost bounded I/O instead of file size.
|
|
DUPLICATE_WORKFLOW_BYTES = 2 * WORKFLOW_METADATA_BYTES
|
|
DUPLICATE_ROLE_BYTES = 2 * ROLE_METADATA_BYTES
|
|
# ffprobe stdout bounds. ffprobe JSON-escapes tag text (at most doubling it),
|
|
# and the decoded per-record budgets below are the only gate that may make a
|
|
# record fail or ``limited``: a video must read exactly as the identical PNG.
|
|
# So the first probe allows twice the role and workflow budgets plus 64 KiB of
|
|
# JSON envelope; past that only the per-key ``workflow`` tag can be dropped,
|
|
# and the re-probe asks for role and envelope tags within twice the role
|
|
# budget (an envelope cannot be split, so an over-budget one fails the read).
|
|
MAX_METADATA_BYTES = ROLE_METADATA_BYTES
|
|
VIDEO_PROBE_BYTES = 2 * (ROLE_METADATA_BYTES + WORKFLOW_METADATA_BYTES) + 64 * 1024
|
|
VIDEO_REPROBE_BYTES = 2 * ROLE_METADATA_BYTES + 64 * 1024
|
|
VIDEO_PROBE_SECONDS = 3
|
|
_VIDEO_ROLE_PROBE_KEYS = ROLE_TAG_KEYS + ENVELOPE_TAG_KEYS
|
|
MAX_KEYWORD_BYTES = 80 # a 1-79 byte PNG keyword plus its NUL separator
|
|
MAX_HEADER_BYTES = 8 * 1024 * 1024
|
|
MAX_PNG_CHUNKS = 10_000
|
|
_ROLE_METADATA_KEYS = frozenset({"prompt", "parameters", EXECUTION_KEY})
|
|
_METADATA_KEYS = _ROLE_METADATA_KEYS | {"workflow"}
|
|
_TEXT_CHUNKS = (b"tEXt", b"zTXt", b"iTXt")
|
|
# An accumulating batch saver writes one A1111 ``parameters`` record per batch
|
|
# item, identical except this field (R3); Pillow keeps the last one.
|
|
# Matched only inside the record's one ``Steps: N, ...`` settings footer line.
|
|
_BATCH_INDEX = re.compile(r"(?:^|(?<=, ))Batch index: \d+(?=, |$)")
|
|
|
|
|
|
def _batch_normalized(text: str) -> str | None:
|
|
"""``text`` with its footer's single batch index blanked, else ``None``."""
|
|
footers = list(_FOOTER.finditer(text))
|
|
if len(footers) != 1:
|
|
return None
|
|
line, count = _BATCH_INDEX.subn("Batch index: #", footers[0].group())
|
|
if count != 1:
|
|
return None
|
|
return text[: footers[0].start()] + line + text[footers[0].end() :]
|
|
|
|
|
|
_SIGNATURE = b"\x89PNG\r\n\x1a\n"
|
|
|
|
|
|
class MetadataReadError(ValueError):
|
|
"""Prompt evidence is unreadable, incomplete, or exceeds inspection limits."""
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class InspectionRead:
|
|
"""One bounded read, with its transient exact video source kept private."""
|
|
|
|
metadata: dict[str, str]
|
|
record_formats: dict[str, str]
|
|
video_carrier_text: str | None
|
|
format: str | None
|
|
width: int | None
|
|
height: int | None
|
|
# Records present but over their budget: no text, format ``limited``.
|
|
limited_records: frozenset[str] = dataclass_field(default_factory=frozenset)
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class _VideoInspection:
|
|
metadata: dict[str, str | None]
|
|
record_formats: dict[str, str]
|
|
carrier_text: str | None
|
|
limited: frozenset[str] = dataclass_field(default_factory=frozenset)
|
|
|
|
|
|
def _inflate(data: bytes, limit: int) -> bytes | None:
|
|
"""Inflate at most ``limit + 1`` bytes; ``None`` when the output is over limit."""
|
|
inflater = zlib.decompressobj()
|
|
result = inflater.decompress(data, limit + 1)
|
|
if len(result) > limit:
|
|
return None
|
|
if not inflater.eof or inflater.unused_data:
|
|
raise MetadataReadError("Compressed metadata is invalid or exceeds limits")
|
|
return result
|
|
|
|
|
|
def _keyword(prefix: bytes) -> str:
|
|
keyword, separator, _ = prefix.partition(b"\0")
|
|
if not separator or not 1 <= len(keyword) <= 79:
|
|
raise MetadataReadError("Malformed PNG text metadata")
|
|
return keyword.decode("latin-1")
|
|
|
|
|
|
def _png_text(kind: bytes, data: bytes, limit: int) -> tuple[str, str | None]:
|
|
"""Decode one retained text chunk; ``None`` text when it inflates past limit."""
|
|
_, _, body = data.partition(b"\0")
|
|
key = _keyword(data[:MAX_KEYWORD_BYTES])
|
|
encoding = "latin-1"
|
|
if kind == b"zTXt":
|
|
if not body or body[0] != 0:
|
|
raise MetadataReadError("Unsupported PNG text compression")
|
|
body = _inflate(body[1:], limit)
|
|
elif kind == b"iTXt":
|
|
if len(body) < 2 or body[0] not in (0, 1):
|
|
raise MetadataReadError("Malformed international PNG metadata")
|
|
flag, method = body[:2]
|
|
fields = body[2:].split(b"\0", 2)
|
|
if len(fields) != 3 or (flag and method != 0):
|
|
raise MetadataReadError("Malformed international PNG metadata")
|
|
fields[0].decode("ascii")
|
|
fields[1].decode("utf-8")
|
|
body = _inflate(fields[2], limit) if flag else fields[2]
|
|
encoding = "utf-8"
|
|
if body is None:
|
|
return key, None
|
|
if b"\0" in body:
|
|
raise MetadataReadError("Malformed PNG text metadata")
|
|
return key, body.decode(encoding)
|
|
|
|
|
|
class _PngRecords:
|
|
"""Retained records with per-class budgets and byte-identical duplicates."""
|
|
|
|
def __init__(self) -> None:
|
|
self.found: dict[str, str] = {}
|
|
self.limited: set[str] = set()
|
|
self.digests: dict[str, tuple[int, bytes]] = {}
|
|
self.role_encoded = self.role_decoded = 0
|
|
self.duplicate_workflow = self.duplicate_role = 0
|
|
self.duplicate_decoded = 0
|
|
|
|
def skip(self, key: str, length: int) -> bool:
|
|
"""Decide from the keyword and length alone whether to seek past a chunk."""
|
|
if key not in _METADATA_KEYS or key in self.limited:
|
|
return True # never retained, or a duplicate of a limited workflow
|
|
if key in self.digests:
|
|
if self.digests[key][0] != length and key != "parameters":
|
|
raise MetadataReadError("Duplicate prompt metadata")
|
|
if key == "workflow":
|
|
if self.duplicate_workflow + length > DUPLICATE_WORKFLOW_BYTES:
|
|
self.limited.add(key)
|
|
self.found.pop(key, None)
|
|
return True
|
|
self.duplicate_workflow += length
|
|
else:
|
|
if self.duplicate_role + length > DUPLICATE_ROLE_BYTES:
|
|
raise MetadataReadError("Metadata exceeds inspection limits")
|
|
self.duplicate_role += length
|
|
return False # same length: read and compare bytes
|
|
if key == "workflow":
|
|
if length > WORKFLOW_METADATA_BYTES:
|
|
self.limited.add(key)
|
|
return True
|
|
return False
|
|
self.role_encoded += length
|
|
if self.role_encoded > ROLE_METADATA_BYTES:
|
|
raise MetadataReadError("Metadata exceeds inspection limits")
|
|
return False
|
|
|
|
def add(self, kind: bytes, data: bytes) -> None:
|
|
key = _keyword(data[:MAX_KEYWORD_BYTES])
|
|
digest = hashlib.sha256(kind + data).digest()
|
|
if key in self.digests:
|
|
if self.digests[key][1] != digest:
|
|
if key != "parameters":
|
|
raise MetadataReadError("Duplicate prompt metadata")
|
|
self.batch_copy(kind, data)
|
|
# The kept copy is the last one; later repeats compare with it.
|
|
self.digests[key] = (len(data), digest)
|
|
return
|
|
self.digests[key] = (len(data), digest)
|
|
workflow = key == "workflow"
|
|
limit = (
|
|
WORKFLOW_METADATA_BYTES
|
|
if workflow
|
|
else ROLE_METADATA_BYTES - self.role_decoded
|
|
)
|
|
_, value = _png_text(kind, data, limit)
|
|
size = None if value is None else len(value.encode("utf-8"))
|
|
if workflow:
|
|
if size is None or size > WORKFLOW_METADATA_BYTES:
|
|
self.limited.add(key)
|
|
return
|
|
else:
|
|
self.role_decoded += limit + 1 if size is None else size
|
|
if self.role_decoded > ROLE_METADATA_BYTES:
|
|
raise MetadataReadError("Metadata exceeds inspection limits")
|
|
self.found[key] = value
|
|
|
|
def batch_copy(self, kind: bytes, data: bytes) -> None:
|
|
"""Keep a later ``parameters`` copy that differs only in its batch index.
|
|
|
|
Each copy must carry exactly one ``Batch index: N`` settings field; any
|
|
other difference is still a conflict. Decoding every copy draws from the
|
|
duplicate role budget, so small compressed copies stay bounded.
|
|
"""
|
|
_, value = _png_text(kind, data, ROLE_METADATA_BYTES)
|
|
size = ROLE_METADATA_BYTES + 1 if value is None else len(value.encode())
|
|
self.duplicate_decoded += size
|
|
if value is None or self.duplicate_decoded > DUPLICATE_ROLE_BYTES:
|
|
raise MetadataReadError("Metadata exceeds inspection limits")
|
|
kept = self.found["parameters"]
|
|
normalized = _batch_normalized(kept)
|
|
if normalized is None or normalized != _batch_normalized(value):
|
|
raise MetadataReadError("Duplicate prompt metadata")
|
|
self.role_decoded += max(0, size - len(kept.encode()))
|
|
if self.role_decoded > ROLE_METADATA_BYTES:
|
|
raise MetadataReadError("Metadata exceeds inspection limits")
|
|
self.found["parameters"] = value
|
|
|
|
|
|
def _png_metadata(stream: Any, size: int) -> tuple[dict, frozenset, int, int]:
|
|
"""CRC-check retained text and structural chunks, seeking past everything else.
|
|
|
|
PNG text chunks may follow IDAT. Pillow's ``.text`` loads pixels to find
|
|
them; this bounded reader instead follows the W3C PNG chunk layout. A text
|
|
chunk's keyword is read first (at most ``MAX_KEYWORD_BYTES``); chunks that
|
|
are not retained, or are over their budget, are skipped by length, so their
|
|
bytes are never held in memory or checksummed. IDAT checksums/pixel
|
|
validity are deliberately outside metadata inspection.
|
|
"""
|
|
records = _PngRecords()
|
|
saw_header = saw_pixels = False
|
|
for index in range(MAX_PNG_CHUNKS):
|
|
header = stream.read(8)
|
|
if len(header) != 8:
|
|
raise MetadataReadError("Incomplete PNG metadata")
|
|
length, kind = struct.unpack(">I4s", header)
|
|
if length > 0x7FFFFFFF or stream.tell() + length + 4 > size:
|
|
raise MetadataReadError("Incomplete PNG chunk")
|
|
if index == 0 and (kind != b"IHDR" or length != 13):
|
|
raise MetadataReadError("Missing PNG header")
|
|
if kind in _TEXT_CHUNKS:
|
|
prefix = stream.read(min(length, MAX_KEYWORD_BYTES))
|
|
if records.skip(_keyword(prefix), length):
|
|
stream.seek(length - len(prefix) + 4, 1)
|
|
continue
|
|
data = prefix + stream.read(length - len(prefix))
|
|
elif kind in (b"IHDR", b"IEND"):
|
|
data = stream.read(length)
|
|
else:
|
|
saw_pixels |= kind == b"IDAT"
|
|
stream.seek(length + 4, 1)
|
|
continue
|
|
checksum = stream.read(4)
|
|
if zlib.crc32(kind + data) != int.from_bytes(checksum, "big"):
|
|
raise MetadataReadError("PNG metadata checksum mismatch")
|
|
if kind == b"IHDR":
|
|
if saw_header or not all(struct.unpack(">II", data[:8])):
|
|
raise MetadataReadError("Malformed PNG header")
|
|
saw_header = True
|
|
width, height = struct.unpack(">II", data[:8])
|
|
elif kind == b"IEND":
|
|
if length or not saw_pixels:
|
|
raise MetadataReadError("Incomplete PNG image")
|
|
return records.found, frozenset(records.limited), width, height
|
|
else:
|
|
records.add(kind, data)
|
|
raise MetadataReadError("PNG chunk count exceeds inspection limits")
|
|
|
|
|
|
def _probe_video_tags(
|
|
probe: str, path: Path, keys: tuple[str, ...], limit: int
|
|
) -> bytes | None:
|
|
"""ffprobe's JSON for the container tags ``keys``; ``None`` past ``limit``."""
|
|
command = [
|
|
probe,
|
|
"-v",
|
|
"quiet",
|
|
"-show_entries",
|
|
"format_tags=" + ",".join(keys),
|
|
"-of",
|
|
"json",
|
|
str(path),
|
|
]
|
|
process = subprocess.Popen( # nosec B603
|
|
command,
|
|
stdout=subprocess.PIPE,
|
|
stderr=subprocess.DEVNULL,
|
|
creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0),
|
|
)
|
|
|
|
def stop() -> None:
|
|
if process.poll() is None:
|
|
try:
|
|
process.kill()
|
|
except OSError:
|
|
# Timeout and final cleanup can race with the process exiting.
|
|
pass
|
|
|
|
timer = threading.Timer(VIDEO_PROBE_SECONDS, stop)
|
|
timer.daemon = True
|
|
timer.start()
|
|
try:
|
|
raw = process.stdout.read(limit + 1)
|
|
if len(raw) > limit:
|
|
return None
|
|
process.wait()
|
|
if process.returncode:
|
|
raise MetadataReadError("Video metadata could not be read")
|
|
finally:
|
|
timer.cancel()
|
|
stop()
|
|
process.wait()
|
|
process.stdout.close()
|
|
return raw
|
|
|
|
|
|
def _video_metadata(path: Path) -> _VideoInspection:
|
|
probe = ffprobe_path()
|
|
if not probe:
|
|
raise MetadataReadError("Video metadata reader is unavailable")
|
|
limited = frozenset()
|
|
raw = _probe_video_tags(probe, path, VIDEO_TAG_KEYS, VIDEO_PROBE_BYTES)
|
|
if raw is None:
|
|
raw = _probe_video_tags(
|
|
probe, path, _VIDEO_ROLE_PROBE_KEYS, VIDEO_REPROBE_BYTES
|
|
)
|
|
if raw is None:
|
|
raise MetadataReadError("Video metadata exceeds inspection limits")
|
|
# Only the per-key workflow tag was left out, so it is the record over
|
|
# budget: limited when the per-key carrier (or no carrier) is selected.
|
|
limited = frozenset({"workflow"})
|
|
probed = json.loads(raw)
|
|
if not isinstance(probed, dict) or not isinstance(probed.get("format"), dict):
|
|
raise MetadataReadError("Malformed video metadata")
|
|
tags = probed["format"].get("tags", {})
|
|
if not isinstance(tags, dict):
|
|
raise MetadataReadError("Malformed video metadata")
|
|
# The shared selector keeps explicit null role markers so malformed
|
|
# evidence cannot silently fall back to an unrelated saved recipe or
|
|
# another carrier; ``read_inspection_file`` refuses them.
|
|
try:
|
|
selected = select_video_carrier(tags)
|
|
except DuplicateVideoTagError:
|
|
raise MetadataReadError("Duplicate prompt metadata") from None
|
|
if selected is None:
|
|
return _VideoInspection({}, {}, None, limited)
|
|
metadata, formats, carrier = selected
|
|
if carrier is not None:
|
|
# An envelope carrier is whole; the dropped per-key workflow belonged
|
|
# to the carrier that lost.
|
|
limited = frozenset()
|
|
return _VideoInspection(metadata, formats, carrier, limited)
|
|
|
|
|
|
def read_inspection_file(path: Path) -> InspectionRead:
|
|
"""Read bounded metadata and header facts without decoding media pixels."""
|
|
try:
|
|
formats, carrier, limited = {}, None, frozenset()
|
|
format_name = width = height = None
|
|
if is_video_path(path):
|
|
video = _video_metadata(path)
|
|
metadata, formats, carrier, limited = (
|
|
video.metadata,
|
|
video.record_formats,
|
|
video.carrier_text,
|
|
video.limited,
|
|
)
|
|
else:
|
|
with path.open("rb") as stream:
|
|
signature = stream.read(8)
|
|
if signature == _SIGNATURE:
|
|
metadata, limited, width, height = _png_metadata(
|
|
stream, path.stat().st_size
|
|
)
|
|
format_name = "PNG"
|
|
else:
|
|
stream.seek(0)
|
|
header = stream.read(MAX_HEADER_BYTES)
|
|
with Image.open(io.BytesIO(header)) as image:
|
|
metadata = dict(image.info)
|
|
format_name, (width, height) = image.format, image.size
|
|
result, role_size, limited = {}, 0, set(limited)
|
|
for key in _METADATA_KEYS:
|
|
if key not in metadata:
|
|
continue
|
|
value = metadata[key]
|
|
if key == "workflow" and not isinstance(value, str):
|
|
formats[key] = "invalid"
|
|
continue
|
|
if not isinstance(value, str):
|
|
raise MetadataReadError("Malformed prompt metadata")
|
|
size = len(value.encode("utf-8", "surrogatepass"))
|
|
if key == "workflow":
|
|
if size > WORKFLOW_METADATA_BYTES:
|
|
limited.add(key)
|
|
continue
|
|
else:
|
|
role_size += size
|
|
if role_size > ROLE_METADATA_BYTES:
|
|
raise MetadataReadError("Metadata exceeds inspection limits")
|
|
result[key] = value
|
|
formats.setdefault(key, "original-text")
|
|
if _ROLE_METADATA_KEYS.intersection(limited):
|
|
# A limited role record would vanish and let fallback evidence win.
|
|
raise MetadataReadError("Metadata exceeds inspection limits")
|
|
for key in limited:
|
|
formats[key] = "limited"
|
|
return InspectionRead(
|
|
result,
|
|
formats,
|
|
carrier,
|
|
format_name,
|
|
width,
|
|
height,
|
|
frozenset(limited),
|
|
)
|
|
except MetadataReadError:
|
|
raise
|
|
except (
|
|
OSError,
|
|
ValueError,
|
|
EOFError,
|
|
SyntaxError,
|
|
RecursionError,
|
|
struct.error,
|
|
zlib.error,
|
|
):
|
|
raise MetadataReadError("Media metadata could not be read") from None
|
|
|
|
|
|
def read_inspection_metadata(path: Path) -> dict[str, str]:
|
|
"""Compatible metadata-only projection of the single inspection read."""
|
|
return read_inspection_file(path).metadata
|
|
|
|
|
|
# A side whose branch recorded run history named (#386): the save node that
|
|
# wrote the file picked the sampler; the text is still that branch's graph walk.
|
|
RECORDED_RUN_SOURCE = "recorded-run"
|
|
RECORDED_TEXT_REASON = "PromptManager recorded this text when the run executed"
|
|
# Outcomes the file alone leaves open; only these ask recorded history.
|
|
_UNDECIDED = frozenset({"ambiguous", "unresolved"})
|
|
|
|
|
|
def _side(status: str, text: str | None = None, source: str | None = None) -> dict:
|
|
return {"status": status, "text": text, "source": source}
|
|
|
|
|
|
_EMPTY_POSITIVE = outcome_message(
|
|
{"state": "unresolved", "reason": EMPTY_POSITIVE_REASON}
|
|
)
|
|
|
|
|
|
def _explained(prompts: dict, resolution: dict) -> dict:
|
|
"""Each unresolved role carries the outcome's line; other roles are kept."""
|
|
message = outcome_message(resolution)
|
|
if message is None:
|
|
return prompts
|
|
return {
|
|
role: (
|
|
{**side, "message": message}
|
|
if side["status"] == "unresolved" and "message" not in side
|
|
else side
|
|
)
|
|
for role, side in prompts.items()
|
|
}
|
|
|
|
|
|
def unreadable_evidence() -> dict:
|
|
"""Both roles when the file's metadata could not be read at all."""
|
|
resolution = {
|
|
"state": "unresolved",
|
|
"sampler_id": None,
|
|
"reason": UNREADABLE_METADATA_REASON,
|
|
"reason_code": None,
|
|
"node": None,
|
|
}
|
|
prompts = {role: _side("unresolved") for role in ("positive", "negative")}
|
|
return {"prompts": _explained(prompts, resolution), "resolution": resolution}
|
|
|
|
|
|
def _may_hold_prompt_manager(metadata: dict) -> bool:
|
|
"""Whether the API graph can show the R1 signature, so the workflow is needed.
|
|
|
|
PromptManager classes, or a ``CLIPTextEncode`` carrying PromptManager's own
|
|
``search_text`` input (an older save rewrote the class).
|
|
"""
|
|
graph = metadata.get("prompt")
|
|
if not isinstance(graph, dict):
|
|
return False
|
|
for node in graph.values():
|
|
if not isinstance(node, dict):
|
|
continue
|
|
name = node.get("class_type")
|
|
inputs = node.get("inputs")
|
|
if isinstance(name, str) and "promptmanager" in name.lower():
|
|
return True
|
|
if isinstance(inputs, dict) and "search_text" in inputs:
|
|
return True
|
|
return False
|
|
|
|
|
|
def _parsed_workflow(value: Any) -> dict | None:
|
|
"""The UI workflow as an object, or ``None`` (absent, invalid or not JSON)."""
|
|
if isinstance(value, str):
|
|
try:
|
|
value = json.loads(value)
|
|
except (ValueError, RecursionError):
|
|
return None
|
|
return value if isinstance(value, dict) else None
|
|
|
|
|
|
def _recorded_execution(resolved: dict, texts: Mapping) -> dict | None:
|
|
"""Evidence from the texts recorded at one sampler of the file's run (#386).
|
|
|
|
Only for an outcome that names one sampler (a single stage stopped at a
|
|
run-time value, such as a language model's output feeding PromptManager)
|
|
and only when that sampler's positive text was recorded and is not empty.
|
|
"""
|
|
sampler = resolved.get("sampler_id")
|
|
roles = texts.get(sampler) if isinstance(sampler, str) else None
|
|
if not isinstance(roles, Mapping):
|
|
return None
|
|
positive = roles.get("positive")
|
|
if not isinstance(positive, str) or not positive.strip():
|
|
return None
|
|
negative = roles.get("negative")
|
|
prompts = {
|
|
"positive": _side("resolved", positive, "execution"),
|
|
"negative": (
|
|
_side("resolved", negative, "execution")
|
|
if isinstance(negative, str)
|
|
else _side("unresolved")
|
|
),
|
|
}
|
|
resolution = {
|
|
"state": "resolved",
|
|
"sampler_id": sampler,
|
|
"reason": RECORDED_TEXT_REASON,
|
|
"reason_code": None,
|
|
"node": None,
|
|
}
|
|
return {"prompts": prompts, "resolution": resolution}
|
|
|
|
|
|
_ABSENT_RESOLUTION = {
|
|
"state": "absent",
|
|
"sampler_id": None,
|
|
"reason": "No parsed prompt metadata",
|
|
"reason_code": None,
|
|
"node": None,
|
|
}
|
|
_MALFORMED_RESOLUTION = {
|
|
"state": "unresolved",
|
|
"sampler_id": None,
|
|
"reason": MALFORMED_EVIDENCE_REASON,
|
|
"reason_code": "malformed",
|
|
"node": None,
|
|
}
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class InspectionResult:
|
|
"""The inspector's resolution of one file's metadata (#386, #247).
|
|
|
|
``resolution`` is the result to use. ``anchored`` is the result anchored
|
|
on the recorded saver, kept or not (None when no anchored resolve ran).
|
|
``by_record`` says the anchored result was kept: history's saver chose
|
|
the samplers and the result names the positive. ``malformed`` marks
|
|
metadata the inspector cannot read as a graph.
|
|
"""
|
|
|
|
resolution: dict
|
|
anchored: dict | None = None
|
|
by_record: bool = False
|
|
malformed: bool = False
|
|
|
|
|
|
def inspection_resolution(
|
|
metadata: Mapping,
|
|
file_name: str | None,
|
|
recorded_saver_id: str | None,
|
|
*,
|
|
profile: ResolverProfile = INSPECTION_PROFILE,
|
|
name_anchor: bool = True,
|
|
) -> InspectionResult:
|
|
"""Resolve raw file metadata as the inspector does.
|
|
|
|
Keeps only the role records, parses a string ``prompt`` and attaches the
|
|
parsed ``workflow`` only when the graph may hold a PromptManager node.
|
|
Resolves with ``profile``; when that leaves the prompt open and
|
|
``recorded_saver_id`` is given, resolves again anchored on that saver
|
|
and keeps the anchored result only when it names the positive.
|
|
|
|
``name_anchor=False`` (ingestion, #247) resolves the unanchored pass
|
|
without ``file_name``, so the saver its file name names anchors nothing:
|
|
such a file goes to Needs review, never linked (#390 ruling). The
|
|
recorded-saver pass still gets ``file_name``, only to refuse a saver the
|
|
name contradicts.
|
|
"""
|
|
workflow = metadata.get("workflow")
|
|
canonical = {
|
|
key: value for key, value in metadata.items() if key in _ROLE_METADATA_KEYS
|
|
}
|
|
if not canonical:
|
|
return InspectionResult(dict(_ABSENT_RESOLUTION))
|
|
malformed = InspectionResult(dict(_MALFORMED_RESOLUTION), malformed=True)
|
|
if "prompt" not in canonical and "parameters" not in canonical:
|
|
return malformed
|
|
if isinstance(canonical.get("prompt"), str):
|
|
try:
|
|
canonical["prompt"] = json.loads(canonical["prompt"])
|
|
except (ValueError, RecursionError):
|
|
return malformed
|
|
workflow = (
|
|
_parsed_workflow(workflow) if _may_hold_prompt_manager(canonical) else None
|
|
)
|
|
if workflow is not None and "prompt" in canonical:
|
|
# Only to recognize overwritten PromptManager text (R1); never a role.
|
|
canonical["workflow"] = workflow
|
|
resolved = resolve_prompt_pair(
|
|
canonical, profile=profile, file_name=file_name if name_anchor else None
|
|
)
|
|
if resolved["state"] not in _UNDECIDED or recorded_saver_id is None:
|
|
return InspectionResult(resolved)
|
|
anchored = resolve_prompt_pair(
|
|
canonical,
|
|
profile=profile,
|
|
file_name=file_name,
|
|
recorded_saver_id=recorded_saver_id,
|
|
)
|
|
# Only a result whose samplers history's saver chose is about this file.
|
|
if (
|
|
anchored.get("recorded_anchor") is True
|
|
and anchored["state"] not in _UNDECIDED
|
|
and isinstance(anchored["positive"], dict)
|
|
):
|
|
return InspectionResult(anchored, anchored, True)
|
|
return InspectionResult(resolved, anchored)
|
|
|
|
|
|
def inspect_prompt_evidence(
|
|
metadata: dict,
|
|
saved: dict | None = None,
|
|
*,
|
|
profile: ResolverProfile = INSPECTION_PROFILE,
|
|
file_name: str | None = None,
|
|
recorded_saver_id: str | None = None,
|
|
recorded_texts: Mapping[str, Mapping[str, str | None]] | None = None,
|
|
) -> dict:
|
|
"""Keep uncertainty visible; a saved association never replaces file evidence.
|
|
|
|
``recorded_saver_id`` is the save node recorded run history says wrote the
|
|
file (#386). It is asked only when the file alone leaves the prompt open
|
|
(ambiguous or unresolved), and the anchored result is kept only when it
|
|
names the positive (resolved, or a guider with no negative); its
|
|
graph-inferred sides are then labelled ``recorded-run``. ``recorded_texts``
|
|
(sampler id to the effective texts PromptManager recorded at execution in
|
|
that run) is used last: when the prompt is still open at one named sampler
|
|
whose positive text was recorded, the recorded texts are shown as
|
|
``execution``.
|
|
|
|
Inspection routes resolve with ``INSPECTION_PROFILE``: bounded work, not
|
|
graph size. The resolve itself is ``inspection_resolution``, which
|
|
ingestion also calls for files its default profile cannot decide (#247).
|
|
``resolution`` carries the closed ``reason_code`` and, for a blocking
|
|
node, ``node: {id, class_type}``.
|
|
"""
|
|
roles = {key for key in metadata if key in _ROLE_METADATA_KEYS}
|
|
if not roles:
|
|
result = {role: _side("absent") for role in ("positive", "negative")}
|
|
if saved:
|
|
context = saved.get("pair_context")
|
|
paired = isinstance(saved.get("pair"), dict) or isinstance(context, dict)
|
|
for role in ("positive", "negative") if paired else ("positive",):
|
|
result[role] = {
|
|
**_side("unresolved", source="saved-association"),
|
|
"message": (
|
|
"A saved library association exists, but it cannot be "
|
|
"verified against this file."
|
|
),
|
|
}
|
|
return {"prompts": result, "resolution": dict(_ABSENT_RESOLUTION)}
|
|
inspected = inspection_resolution(
|
|
metadata, file_name, recorded_saver_id, profile=profile
|
|
)
|
|
if inspected.malformed:
|
|
resolution = inspected.resolution
|
|
return {
|
|
"prompts": _explained(
|
|
{role: _side("unresolved") for role in ("positive", "negative")},
|
|
resolution,
|
|
),
|
|
"resolution": resolution,
|
|
}
|
|
resolved, recorded = inspected.resolution, inspected.by_record
|
|
anchored = inspected.anchored
|
|
if (
|
|
not recorded
|
|
and recorded_texts
|
|
and anchored is not None
|
|
and anchored.get("recorded_anchor") is True
|
|
):
|
|
executed = _recorded_execution(anchored, recorded_texts)
|
|
if executed is not None:
|
|
return executed
|
|
state = resolved["state"]
|
|
result = {}
|
|
for role in ("positive", "negative"):
|
|
side = resolved[role]
|
|
if (
|
|
state != "ambiguous"
|
|
and isinstance(side, dict)
|
|
and (role == "negative" or side["text"].strip())
|
|
):
|
|
source = side["provenance"]["text_source"]
|
|
if recorded and source == "graph-inferred":
|
|
source = RECORDED_RUN_SOURCE
|
|
result[role] = _side("resolved", side["text"], source)
|
|
elif state == "resolved" and isinstance(side, dict):
|
|
# A resolved pair withholds only an empty positive.
|
|
result[role] = {**_side("unresolved"), "message": _EMPTY_POSITIVE}
|
|
else:
|
|
result[role] = _side(state if state != "resolved" else "unresolved")
|
|
resolution = {
|
|
"state": state,
|
|
"sampler_id": resolved.get("sampler_id"),
|
|
"reason": resolved.get("reason", ""),
|
|
"reason_code": resolved.get("reason_code"),
|
|
"node": resolved.get("node"),
|
|
}
|
|
return {"prompts": _explained(result, resolution), "resolution": resolution}
|
|
|
|
|
|
def inspect_prompt_roles(metadata: dict, saved: dict | None = None) -> dict:
|
|
"""Keep the established role-only helper contract."""
|
|
return inspect_prompt_evidence(metadata, saved)["prompts"]
|