mmprompt/h3-plan-gate/verify_plan_rules.py

1561 lines
78 KiB
Python
Executable File

"""Standalone replica of the plan_json validation rules from chain_nodes.py
(_h3_frame_length, _validate_h3_length, _safe_name, _prompt_text) plus the
six-section Ref2VA prompt contract from web/h3_prompt_schema_core.mjs
(H3_REFERENCE_SECTIONS), used to verify the system-prompt worked examples and
edge cases.
Scene-agent FRAGMENT validator (one scene per turn of the agent workflow) plus
a CLI:
python verify_plan_rules.py # embedded test suite
python verify_plan_rules.py plan FILE # validate a final plan JSON
python verify_plan_rules.py fragment FILE # validate one scene fragment
[--index N] [--total N] [--prev PREV_FILE] # --prev chains the handoff
The prompt setup validated here (user-tested; authoritative over older docs):
subject_definitions: one line per subject, exactly one of three forms:
"<Subject N> is a ..." no reference image:
physical traits only -
never clothing, never a
nude/bare skin state
"<Subject N> binds to <Image N> : <what the image shows>"
reference image: faithful
to the image; the writer
is multimodal
"<Subject N> identity: <verbatim>; voice: <verbatim>"
user refmod: the tested
wording carried through
untouched, the story's
&...& wrapper stripped;
exempt from the no-image
content bans
summary: exactly "[reference generation]"
retention_analysis: one "<Subject N>: fully_preserved" line per defined label
detailed_description: 1-2 style sentences, then the [Shot 1] body
overall_soundscape: the sound the scene itself makes
non_diegetic_music: N/A
No definition form carries a length cap - describe fully what the model needs.
REFMOD ISOLATION: a refmod subject is referenced by the bare "<Subject N>" token
everywhere outside subject_definitions. The body never re-states the subject's
name and never re-describes the look or voice the refmod already pins - the
workflow injects the reference blocks itself, and repeating them fights the
injection. No-image and binds subjects keep the opposite treatment: their full
look is still woven into every scene body (H3 drift rule).
"""
import json
import math
import re
FPS = 24
MAX_SHOTS = 128
MAX_SEED = 0xFFFFFFFFFFFFFFFF
MAX_H3_FRAMES = 3592
# Canonical six-section Ref2VA order (web/h3_prompt_schema_core.mjs
# H3_REFERENCE_SECTIONS; tokenizer-aligned section labels).
H3_REFERENCE_SECTIONS = ["subject_definitions", "summary", "retention_analysis",
"detailed_description", "overall_soundscape",
"non_diegetic_music"]
# Ref2VA (full-reference) mode: the six native H3 reference sections in canonical
# order, mirroring web/h3_prompt_schema_core.mjs H3_REFERENCE_SECTIONS. The skill
# emits this format; t2va (3-line) stays as an auto-detected legacy path.
REF2VA_SECTIONS = ["subject_definitions", "summary", "retention_analysis",
"detailed_description", "overall_soundscape", "non_diegetic_music"]
REF2VA_TASK_DIRECTIVE = "[reference generation]"
REF2VA_RETENTION_MARKERS = {"fully_preserved", "partially_preserved",
"attribute_transfer", "weak_reference"}
# Rule 7 - a subject_definitions line comes in exactly one of three forms:
# 1. no reference image -> "<Subject N> is a <age> ... with <hair>, <eyes> and
# <build>" - physical traits only: never clothing, never a nude/bare skin
# state
# 2. reference image -> "<Subject N> binds to <Image N> : <what the image
# actually shows>" - faithful to the image; the writer is multimodal
# 3. user refmod -> "<Subject N> identity: <verbatim>; voice: <verbatim>"
# - the user's own tested wording, carried through untouched (exempt from
# the no-image content bans: clothing and skin state)
# No form carries a length cap - describe fully what the model needs.
# No-image and binds subjects get their full look woven into the [Shot 1] body;
# a refmod subject is referenced by its <Subject N> label alone - the refmod
# text never leaves subject_definitions.
REF2VA_REFMOD_RE = re.compile(r"^identity\s*:", re.I)
REF2VA_BINDS_RE = re.compile(r"^binds to <Image\s+\d+>\s*:\s*", re.I)
REF2VA_DEF_SKINSTATE_RE = re.compile(
r"\b(?:nude|naked|unclothed|undressed|bare|barefoot|topless)\b", re.I)
REF2VA_DEF_CLOTHING_RE = re.compile(
r"\b(?:wearing|wears|dressed|dresses|dress|outfit|garment|clothes|clothing|"
r"uniform|scrubs?|jacket|coat|shirt|blouse|trousers|pants|jeans|shorts|skirt|"
r"gown|hoodie|sweater|shoes|sneakers|boots|sandals|socks|stockings|gloves|"
r"helmet|lanyard)\b", re.I)
def _refmod_echo(anchor, text, n=5):
"""First run of >= n consecutive refmod words echoed in text, else None.
A refmod subject's definition is the single source of its identity and look:
the [Shot 1] body must reference the label, never restate the refmod text.
"""
aw = re.sub(r"[^a-z0-9]+", " ", anchor.lower()).split()
tw = re.sub(r"[^a-z0-9]+", " ", text.lower()).split()
if len(aw) < n:
s = " ".join(aw)
return s if s and s in " ".join(tw) else None
grams = {" ".join(aw[i:i + n]) for i in range(len(aw) - n + 1)}
tjoin = " ".join(tw)
for g in sorted(grams):
if g in tjoin:
return g
return None
FENCE_RE = re.compile(r"^\s*```[a-zA-Z0-9_-]*\s*\n(.*?)\n?\s*```\s*$", re.S)
DIALOGUE_SPAN_RE = re.compile(r"<d>(.*?)</d>", re.S)
MARKER_RE = re.compile(r"^\[[^\]]+\]\s*")
CONTINUITY_RE = re.compile(r"\b(same\b|continu|still\b)", re.I)
# All seven canonical H3 section labels: the six Ref2VA sections plus the old
# base-mode description label, so a stale three-line section header inside a
# Ref2VA prompt is caught as unexpected instead of leaking into the body.
SECTION_HEAD_RE = re.compile(
r"^(subject_definitions|summary|retention_analysis|detailed_description"
r"|overall_soundscape|non_diegetic_music|integrated_multimodal_description):",
re.M)
REFERENCE_LABEL_RE = re.compile(r"<(?:Subject|Picture|Video|Audio)\s+\d+>")
RETENTION_LINE_RE = re.compile(r"^(<(?:Subject|Picture|Video|Audio)\s+\d+>)\s*:\s*(\S.*)$")
# The gate is a composition gate, not a word counter: there is no target band and
# no upper limit. The floor only trips on lazy output that could not possibly carry
# the elements of a scene composition (subject, wardrobe, style, continuity,
# blocking, camera, performance, texture, sound, exit state).
THIN_FLOOR_SHORT = 100 # body words, scenes under 10 s
THIN_FLOOR_LONG = 120 # body words, scenes of 10 s or longer
VISUAL_RETENTION_MARKERS = {"fully_preserved", "partially_preserved",
"attribute_transfer", "weak_reference"}
AUDIO_RETENTION_MARKERS = {"fully_copy", "partially_copy", "reference",
"weak_reference"}
RETENTION_MARKERS = VISUAL_RETENTION_MARKERS | AUDIO_RETENTION_MARKERS
# --- subject_definitions: the three legal forms -----------------------------
# Rule 7 - a subject_definitions line comes in exactly one of three forms:
# 1. no reference image -> "<Subject N> is a <age> ... with <hair>, <eyes> and
# <build>" - physical traits only: never clothing, never a nude/bare skin
# state
# 2. reference image -> "<Subject N> binds to <Image N> : <what the image
# actually shows>" - faithful to the image; the writer is multimodal
# 3. user refmod -> "<Subject N> identity: <verbatim>; voice: <verbatim>"
# - the user's own tested wording, carried through untouched (exempt from
# the no-image content bans: clothing and skin state)
# No form carries a length cap - describe fully what the model needs.
# REFMOD ISOLATION - a refmod subject's wording lives ONLY in subject_definitions.
# Everywhere else in the prompt the subject is referenced by the bare
# "<Subject N>" token: the body never re-states the name, never re-describes the
# look or voice the refmod already pins. (No-image and binds subjects keep the
# full look woven into every scene body.)
REF2VA_REFMOD_RE = re.compile(r"^identity\s*:", re.I)
REF2VA_VOICE_SPLIT_RE = re.compile(r";\s*voice\s*:", re.I)
REF2VA_BINDS_RE = re.compile(r"^binds\s+to\s+<Image\s+\d+>\s*:\s*\S", re.I)
REF2VA_WRAPPER_RE = re.compile(r"&")
REF2VA_DEF_SKINSTATE_RE = re.compile(
r"\b(nude|nudes|nudity|naked|bare|unclothed|undressed|topless)\b", re.I)
REF2VA_DEF_CLOTHING_RE = re.compile(
r"\b(dresses?|dressed|dressing|wearing|outfit|clothes|clothing|costume|"
r"uniform|apron|pinafore|shirt|blouse|sweater|hoodie|jacket|coat|cape|cloak|"
r"scarf|gloves|mittens|socks|stockings|tights|trousers|pants|jeans|shorts|"
r"skirt|leggings|overalls|shoes|sneakers|boots|sandals|slippers|hat|cap|"
r"beanie|bonnet|helmet|veil|lanyard)\b", re.I)
# Tokens so generic that any second subject, the camera prose, or the section
# labels could legitimately use them. Everything else from a refmod's identity
# and voice text is treated as that subject's pinned identity and is banned from
# the rest of the prompt (refmod isolation).
REF2VA_STOPWORDS = frozenset("""
a an the and or but nor so yet if then else as is are was were be been being am
do does did done have has had having will would shall should can could may might
must of to in on at by for from into onto over under with without within near
past through during before after above below between against along across behind
beyond than too very just even also still already always never only own same all
any both each every few more most other some such no not nor while when where how
why who whom whose which what that this these those there here now then once
twice s t ok up down out off again further
i you he she it we they me him us them my your his its our their mine yours ours
theirs myself yourself himself herself itself
year years old age middle aged
hair hairstyle eyes skin face faces build frame height weight complexion
identity identities voice voices vocal speaks speak speaking spoken says say
saying said tell tells told talks talking conversation
look looks looked looking wear wears wearing worn go goes going went come comes
coming
""".split())
def load_json_text(text, label=""):
"""json.loads tolerant of a surrounding markdown fence (LLM output)."""
text = (text or "").strip().lstrip("\ufeff")
m = FENCE_RE.match(text)
if m:
text = m.group(1).strip()
return json.loads(text)
def _safe_name(value, fallback="chain"):
text = re.sub(r"[^A-Za-z0-9._-]+", "_", str(value or "").strip())
text = text.strip("._-")
return (text or fallback)[:96]
def _prompt_text(value, label=""):
if isinstance(value, list):
if not all(isinstance(line, str) for line in value):
raise ValueError(f"{label} line arrays may contain only strings.")
return "\n".join(value).strip()
return str(value or "").strip()
def _h3_frame_length(seconds):
seconds = float(seconds)
if not math.isfinite(seconds) or seconds <= 0:
raise ValueError("duration must be finite positive")
requested = max(5, int(math.ceil(seconds * FPS - 1e-9)))
length = requested + (5 - requested % 17) % 17
if length > MAX_H3_FRAMES:
raise ValueError("too long")
return length
def detect_prompt_mode(prompt_text):
"""t2va (3-line) vs ref2va (six-section) - mirrors detectH3Mode()."""
if re.search(r"^(?:subject_definitions|summary|retention_analysis|"
r"detailed_description):", prompt_text, re.M):
return "ref2va"
return "t2va"
def _split_ref2va_sections(lines, where):
"""Group ref2va prompt lines into [(section, [content lines])] in file order.
A line whose stripped form starts with '<section>:' opens that section (its
content is the rest of that line plus following lines until the next header) -
the same rule parseH3Sections() applies."""
records = []
for line in lines:
stripped = line.strip()
hit = None
for sec in REF2VA_SECTIONS:
if stripped.startswith(sec + ":"):
hit = sec
break
if hit is not None:
rest = stripped[len(hit) + 1:].strip()
records.append((hit, [rest] if rest else []))
elif records:
records[-1][1].append(stripped)
else:
raise ValueError(f"{where}: ref2va prompt must open with "
f"'subject_definitions:', got {stripped[:60]!r}")
return records
def check_ref2va_prompt(lines, dur, where, prev_handoff=None):
"""Structural + craft checks for one ref2va prompt array.
Returns (shot_body, soundscape_text, dialogue_spans, defined_labels, wc) so
the fragment chain (handoff mirror, outline match) can reuse them; wc is the
detailed_description word count the thin-scene floor was applied to.
"""
if (not isinstance(lines, list) or len(lines) < 6
or not all(isinstance(line, str) and line.strip() for line in lines)):
raise ValueError(f"{where}: ref2va prompt must be an array of non-empty "
f"strings (headers on their own line, content on the "
f"following lines)")
records = _split_ref2va_sections(lines, where)
names = [name for name, _ in records]
if sorted(names) != sorted(REF2VA_SECTIONS):
missing = [s for s in REF2VA_SECTIONS if s not in names]
raise ValueError(f"{where}: ref2va sections missing {missing} - all six of "
f"{REF2VA_SECTIONS} are required, each exactly once")
if names != REF2VA_SECTIONS:
raise ValueError(f"{where}: ref2va sections must be in canonical order "
f"{REF2VA_SECTIONS}, got {names}")
by_name = dict(records)
summary = " ".join(by_name["summary"]).strip()
if summary != REF2VA_TASK_DIRECTIVE:
raise ValueError(f"{where}: summary must be exactly {REF2VA_TASK_DIRECTIVE!r} "
f"(every scene is built from the wired subject references), "
f"got {summary[:60]!r}")
defs = by_name["subject_definitions"]
if not defs:
raise ValueError(f"{where}: subject_definitions is empty")
defined = []
refmod_anchors = {}
for line in defs:
m = re.match(r"^(<(?:Subject|Picture|Video|Audio)\s+\d+>)\s+\S", line)
if not m:
raise ValueError(f"{where}: subject_definitions lines must start with a "
f"<Subject N> label followed by one of the three "
f"definition forms (is-a physical traits / binds to "
f"<Image N> / verbatim refmod): {line[:60]!r}")
if m.group(1) in defined:
raise ValueError(f"{where}: {m.group(1)} is defined more than once")
anchor = line[m.end(1):].strip()
if anchor.startswith("&"):
raise ValueError(f"{where}: {m.group(1)} keeps the user's &...& wrapper - "
f"strip the & marks and carry the refmod text verbatim "
f"('<Subject N> identity: ...; voice: ...'): {line[:60]!r}")
if REF2VA_REFMOD_RE.match(anchor):
defined.append(m.group(1)) # verbatim user refmod text - never edited
refmod_anchors[m.group(1)] = anchor
continue
mb = REF2VA_BINDS_RE.match(anchor)
if mb:
desc = anchor[mb.end():].strip()
if not desc:
raise ValueError(f"{where}: {m.group(1)} binds line needs a description "
f"after the colon - look at <Image N> and write what "
f"you see: {line[:60]!r}")
else:
if not re.match(r"^is\b", anchor, re.I):
raise ValueError(f"{where}: {m.group(1)} definition is none of the three "
f"forms - '<Subject N> is a ...' (physical traits only: "
f"age, hair, eyes, build), '<Subject N> binds to <Image "
f"N> : ...' (what the image shows), or the user's "
f"verbatim refmod '<Subject N> identity: ...; voice: "
f"...': {line[:60]!r}")
if REF2VA_DEF_SKINSTATE_RE.search(anchor):
raise ValueError(f"{where}: {m.group(1)} has no reference image, so its "
f"definition is physical traits only and carries a "
f"nude/bare skin state - weave the skin state into the "
f"[Shot 1] body where the scene shows it: {line[:60]!r}")
if REF2VA_DEF_CLOTHING_RE.search(anchor):
raise ValueError(f"{where}: {m.group(1)} describes clothing in a no-image "
f"definition - physical traits only (age, hair, eyes, "
f"build); weave every garment into the [Shot 1] body "
f"where the action touches it: {line[:60]!r}")
defined.append(m.group(1))
if "<Subject 1>" not in defined:
raise ValueError(f"{where}: <Subject 1> must be defined in subject_definitions")
retained = {}
for line in by_name["retention_analysis"]:
m = re.match(r"^(<(?:Subject|Picture|Video|Audio)\s+\d+>)\s*:\s*(\S+)\s*$", line)
if not m or m.group(2) not in REF2VA_RETENTION_MARKERS:
raise ValueError(f"{where}: retention_analysis lines must be "
f"'<Subject N>: fully_preserved' (or partially_preserved / "
f"attribute_transfer / weak_reference): {line[:60]!r}")
retained[m.group(1)] = m.group(2)
for label in defined:
if label not in retained:
raise ValueError(f"{where}: {label} has no retention_analysis entry")
dd = "\n".join(by_name["detailed_description"]).strip()
if "[Shot 1]" not in dd:
raise ValueError(f"{where}: detailed_description must contain '[Shot 1]'")
style_part, _, body = dd.partition("[Shot 1]")
body = body.strip()
if not style_part.strip():
raise ValueError(f"{where}: detailed_description needs 1-2 style sentences "
f"before [Shot 1] (medium, lighting quality, palette)")
wc = len((style_part + " " + body).split())
floor = THIN_FLOOR_LONG if dur >= 10 else THIN_FLOOR_SHORT
if wc < floor:
raise ValueError(f"{where}: detailed_description is only {wc} words - too thin "
f"to carry the elements of a scene composition (subject, "
f"wardrobe, style, continuity, blocking, camera, performance, "
f"texture, sound, exit state)")
if "<Subject 1>" not in body:
raise ValueError(f"{where}: the [Shot 1] body must reference <Subject 1> and "
f"carry the head-to-toe look woven into the action (for a "
f"refmod subject the label reference is enough - its "
f"definition carries the look)")
for rlabel, ranchor in refmod_anchors.items():
echo = _refmod_echo(ranchor, dd)
if echo:
raise ValueError(f"{where}: {rlabel} is defined by a verbatim refmod - the "
f"refmod text lives only in subject_definitions; reference "
f"{rlabel} by its label alone in the [Shot 1] body and "
f"never restate its identity, voice, or look (echoed "
f"{echo!r})")
if " is now " in dd.lower():
raise ValueError(f"{where}: change stated as bare outcome instead of shown progression")
if re.search(r"\bbare\b", dd, re.I):
print(f" note: {where} description says 'bare' - call uncovered body parts "
f"'nude' (e.g. 'nude arms')")
ssc_text = "\n".join(by_name["overall_soundscape"]).strip()
if not ssc_text:
raise ValueError(f"{where}: overall_soundscape is empty")
ndm_text = "\n".join(by_name["non_diegetic_music"]).strip()
if ndm_text.upper() != "N/A":
print(f" note: {where} non_diegetic_music is {ndm_text[:40]!r} - N/A unless "
f"the user asked for a score")
spans = [MARKER_RE.sub("", span, count=1).strip()
for span in DIALOGUE_SPAN_RE.findall(dd)]
if spans and not re.search(r"silently with mouth", dd):
raise ValueError(f"{where}: dialogue span lacks a 'silently with mouth' cue")
if prev_handoff is not None:
prev_ssc = ""
if isinstance(prev_handoff, dict):
prev_ssc = str(prev_handoff.get("soundscape", ""))
if prev_ssc and not CONTINUITY_RE.search(ssc_text):
raise ValueError(f"{where}: soundscape does not continue the previous audio "
f"bed (say 'the same ... continues')")
if prev_ssc and not CONTINUITY_RE.search(body):
raise ValueError(f"{where}: description does not open inside the previous "
f"end_state (use a continuity cue: 'Continue the same ...', "
f"'without resetting the motion')")
return body, ssc_text, spans, defined, wc
def validate_plan(raw, default_duration=15.0, default_steps=20):
if isinstance(raw, list):
raw = {"shots": raw}
if not isinstance(raw, dict):
raise ValueError("must be object or list")
shots_raw = raw.get("shots")
if not isinstance(shots_raw, list) or not shots_raw:
raise ValueError("requires non-empty shots")
if len(shots_raw) > MAX_SHOTS:
raise ValueError("too many shots")
defaults = raw.get("defaults") if isinstance(raw.get("defaults"), dict) else {}
dd = float(defaults.get("duration_seconds", default_duration))
ds = int(defaults.get("steps", default_steps))
if not math.isfinite(dd) or dd <= 0:
raise ValueError("default duration must be positive")
if ds < 1:
raise ValueError("default steps >= 1")
prompt_prefix = _prompt_text(raw.get("prompt_prefix", raw.get("global_prompt", "")))
seen = set()
delivered_total = 0
for offset, item in enumerate(shots_raw):
idx = offset + 1
if isinstance(item, str):
item = {"prompt": item}
if not isinstance(item, dict):
raise ValueError(f"shot {idx} not object/string")
shot_id = _safe_name(item.get("id", "clip_%04d" % idx), "clip_%04d" % idx)
if shot_id in seen:
raise ValueError(f"duplicate id {shot_id}")
seen.add(shot_id)
scene_prompt = _prompt_text(item.get("prompt", ""))
if not scene_prompt and not prompt_prefix:
raise ValueError(f"shot {idx} needs a prompt")
explicit = item.get("length", item.get("frames"))
if explicit is None:
dur = float(item.get("duration_seconds", dd))
if not math.isfinite(dur) or dur <= 0:
raise ValueError(f"shot {idx} bad duration")
raw_frames = _h3_frame_length(dur)
else:
n = int(explicit)
if n < 5 or n > MAX_H3_FRAMES or n % 17 != 5:
raise ValueError(f"shot {idx} bad length {n}")
raw_frames = n
steps = int(item.get("steps", ds))
if steps < 1 or steps > 10000:
raise ValueError(f"shot {idx} steps")
seed = item.get("seed")
if seed is not None:
s = int(seed)
if s < 0 or s > MAX_SEED:
raise ValueError(f"shot {idx} seed out of range")
context = 22 # default node context
delivered = raw_frames if idx == 1 else raw_frames - context
if idx > 1 and raw_frames <= context:
raise ValueError(f"shot {idx} shorter than context")
if idx > 1 and delivered_total < context:
raise ValueError(f"shot {idx-1} delivered too few for shot {idx} context")
delivered_total += delivered
print(f" shot {idx} id={shot_id!r} raw={raw_frames} delivered={delivered} "
f"steps={steps}")
print(f" total delivered: {delivered_total} frames = {delivered_total/FPS:.2f}s")
return True
# ---------------------------------------------------------------------------
# Ref2VA six-section prompt contract
# ---------------------------------------------------------------------------
def parse_h3_sections(text):
"""Mirror of parseH3Sections in web/h3_prompt_schema_core.mjs: find the
canonical section headers and slice their content spans."""
records = []
for m in SECTION_HEAD_RE.finditer(text):
records.append({"name": m.group(1), "start": m.start(),
"content_start": m.end()})
for i, rec in enumerate(records):
rec["end"] = records[i + 1]["start"] if i + 1 < len(records) else len(text)
return records
def parse_subject_definitions(block, where):
"""Parse the subject_definitions content into {label: info}.
Each non-empty line must be exactly one of the three legal forms. Returns
{label: {"form": "refmod"|"binds"|"no-image", "line": str, "text": str}}
where "text" carries the refmod's identity/voice content (for isolation).
"""
defined = {}
for lineno, line in enumerate(block.splitlines(), 1):
if not line.strip():
continue
m = re.match(r"^\s*(<(?:Subject|Picture|Video|Audio)\s+\d+>)\s*(.*)$", line)
if not m:
raise ValueError(
f"{where}: subject_definitions line {lineno} must start with a "
f"reference label like '<Subject 1>' - got {line.strip()[:60]!r}")
label, rest = m.group(1), m.group(2).strip()
if label in defined:
raise ValueError(f"{where}: {label} is defined more than once")
if REF2VA_WRAPPER_RE.search(line):
raise ValueError(
f"{where}: {label} still carries the story's &...& wrapper - strip "
f"the ampersands and copy the identity/voice text verbatim")
if REF2VA_REFMOD_RE.match(rest):
body = rest[rest.index(":") + 1:].strip()
parts = REF2VA_VOICE_SPLIT_RE.split(body, maxsplit=1)
if len(parts) != 2 or not parts[0].strip() or not parts[1].strip():
raise ValueError(
f"{where}: {label} refmod line must read 'identity: <user "
f"text>; voice: <user text>' with both parts non-empty")
defined[label] = {"form": "refmod", "line": line, "text": body}
continue
if REF2VA_BINDS_RE.match(rest):
defined[label] = {"form": "binds", "line": line, "text": rest}
continue
if re.match(r"^is\b", rest, re.I):
hit = REF2VA_DEF_SKINSTATE_RE.search(rest)
if hit:
raise ValueError(
f"{where}: {label} no-image definition may only carry physical "
f"traits (age, hair, eyes, build) - a nude/bare skin state "
f"({hit.group(0)!r}) belongs to the scene body, not the "
f"definition")
hit = REF2VA_DEF_CLOTHING_RE.search(rest)
if hit:
raise ValueError(
f"{where}: {label} no-image definition may only carry physical "
f"traits (age, hair, eyes, build) - clothing ({hit.group(0)!r}) "
f"belongs to a reference image or a refmod, not the definition")
defined[label] = {"form": "no-image", "line": line, "text": rest}
continue
raise ValueError(
f"{where}: {label} definition must be exactly one of '<Subject N> is a "
f"...' (no image), '<Subject N> binds to <Image N> : ...' (reference "
f"image), or '<Subject N> identity: ...; voice: ...' (user refmod) - "
f"got {rest[:60]!r}")
if not defined:
raise ValueError(f"{where}: subject_definitions needs at least one "
f"'<Subject N> ...' definition line")
return defined
def refmod_banned_tokens(refmod_text, other_defs_text):
"""Distinctive identity words of one refmod, for the isolation scan.
Takes the refmod's 'identity: ...; voice: ...' content and every OTHER
subject's definition line. A token is banned only if no other subject's
definition also uses it (shared traits like 'grey hair' cannot be attributed
to the refmod subject alone).
"""
words = re.findall(r"[A-Za-z][A-Za-z'-]*", refmod_text)
tokens = set()
for w in words:
lw = w.lower()
if len(lw) < 3 or lw in REF2VA_STOPWORDS:
continue
tokens.add(lw)
if lw.endswith("es") and len(lw) > 4:
tokens.add(lw[:-2])
elif lw.endswith("s") and len(lw) > 3:
tokens.add(lw[:-1])
# the subject's name: leading capitalized words of the identity text
m = re.match(r"\s*((?:[A-Z][a-z]{1,20}\s+){0,2}[A-Z][a-z]{1,20})\b", refmod_text)
if m:
for name in m.group(1).split():
if name.lower() not in REF2VA_STOPWORDS:
tokens.add(name.lower())
return {t for t in tokens
if not re.search(rf"\b{re.escape(t)}\b", other_defs_text, re.I)}
def check_refmod_isolation(defined, rest_text, where):
"""Refmod isolation: outside subject_definitions a refmod subject is only
ever the bare '<Subject N>' token. Any distinctive word of its refmod
identity/voice (including the subject's name) found in the rest of the
prompt is a re-description that fights the injected reference."""
refmod_labels = [lb for lb, info in defined.items() if info["form"] == "refmod"]
for label in refmod_labels:
others = " ".join(info["line"] for lb, info in defined.items() if lb != label)
banned = refmod_banned_tokens(defined[label]["text"], others)
hits = sorted(t for t in banned
if re.search(rf"\b{re.escape(t)}\b", rest_text, re.I))
if hits:
raise ValueError(
f"{where}: refmod isolation broken for {label} - the refmod wording "
f"lives only in subject_definitions, the rest of the prompt must "
f"reference the subject by the bare '{label}' token and never "
f"re-describe the pinned look or voice (found: {', '.join(hits)})")
def check_ref2va_prompt(text, where, duration=None):
"""Validate one compiled six-section Ref2VA prompt (the joined prompt lines
of one shot). Raises ValueError on the first broken rule.
Returns {"body", "style", "soundscape", "defined"} for callers that need the
handoff/continuity checks (fragment validator).
"""
records = parse_h3_sections(text)
by_name = {}
for rec in records:
by_name.setdefault(rec["name"], []).append(rec)
required = H3_REFERENCE_SECTIONS
for section in required:
if section not in by_name:
raise ValueError(f"{where}: missing {section}: - the six-section Ref2VA "
f"prompt needs all six sections in canonical order")
for section, recs in by_name.items():
if section not in required:
raise ValueError(f"{where}: {section}: does not belong in the six-section "
f"Ref2VA prompt")
if len(recs) > 1:
raise ValueError(f"{where}: duplicate {section}: section")
canonical = [required.index(r["name"]) for r in records]
if any(v < canonical[i - 1] for i, v in enumerate(canonical) if i):
raise ValueError(f"{where}: H3 sections are not in their required order "
f"(subject_definitions, summary, retention_analysis, "
f"detailed_description, overall_soundscape, "
f"non_diegetic_music)")
def content(section):
rec = by_name[section][0]
return text[rec["content_start"]:rec["end"]].strip()
# summary - the chain contract pins the reference-generation directive
summary_body = content("summary")
if summary_body != "[reference generation]":
raise ValueError(
f"{where}: summary must be exactly '[reference generation]' for the "
f"chain plan (node task-directive rules allow other H3 task types, but "
f"every chain shot is its own reference generation) - got "
f"{summary_body[:60]!r}")
# subject_definitions - the three legal forms
defs = parse_subject_definitions(content("subject_definitions"), where)
# every label used later must be defined
defs_rec = by_name["subject_definitions"][0]
rest_text = text[defs_rec["end"]:]
used = []
for m in REFERENCE_LABEL_RE.finditer(rest_text):
if m.group(0) not in used:
used.append(m.group(0))
for label in used:
if label not in defs:
raise ValueError(f"{where}: {label} is used but not defined in "
f"subject_definitions")
# refmod isolation - bare '<Subject N>' tokens only, outside the definitions
check_refmod_isolation(defs, rest_text, where)
# retention_analysis - every defined label once, with a known marker
retention_body = content("retention_analysis")
seen_labels = []
for lineno, line in enumerate(retention_body.splitlines(), 1):
if not line.strip():
continue
m = RETENTION_LINE_RE.match(line.strip())
if not m:
raise ValueError(
f"{where}: retention_analysis line {lineno} must read "
f"'<Subject N>: fully_preserved' - got {line.strip()[:60]!r}")
label, marker = m.group(1), m.group(2).strip()
if label in seen_labels:
raise ValueError(f"{where}: {label} has more than one retention_analysis "
f"entry")
seen_labels.append(label)
if marker not in RETENTION_MARKERS:
raise ValueError(
f"{where}: {label} retention marker {marker!r} is not an H3 "
f"retention marker (fully_preserved, partially_preserved, "
f"attribute_transfer, weak_reference)")
if label not in defs:
raise ValueError(f"{where}: {label} has a retention_analysis entry but "
f"is not defined in subject_definitions")
for label in defs:
if label not in seen_labels:
raise ValueError(f"{where}: {label} has no retention_analysis entry")
# detailed_description - style sentences, then the [Shot 1] body
desc = content("detailed_description")
first_marker = re.search(r"\[Shot\s+(\d+)\]", desc)
if not first_marker or int(first_marker.group(1)) != 1:
raise ValueError(f"{where}: the main description must begin its shot "
f"sequence with [Shot 1]")
idx = desc.find("[Shot 1]")
style = desc[:idx].strip()
body = desc[idx:]
if not style:
raise ValueError(f"{where}: the detailed_description needs 1-2 style "
f"sentences before [Shot 1]")
if "<d>" in style:
raise ValueError(f"{where}: dialogue belongs in the [Shot 1] body, not the "
f"style sentences")
extra_shots = re.findall(r"\[Shot\s+(\d+)\]", body)
if any(int(n) != 1 for n in extra_shots):
raise ValueError(f"{where}: every chain shot is its own single-shot "
f"generation - the body carries exactly [Shot 1], never "
f"[Shot 2] or later")
# overall_soundscape / non_diegetic_music
ssc = content("overall_soundscape")
if not ssc:
raise ValueError(f"{where}: overall_soundscape: still needs content")
music = content("non_diegetic_music")
if not music:
raise ValueError(f"{where}: non_diegetic_music: still needs content")
if music.strip().upper() != "N/A":
print(f" note: {where} non_diegetic_music is {music[:40]!r} - the chain "
f"contract keeps it N/A so the audio bed never restarts between clips")
return {"body": body, "style": style, "soundscape": ssc, "defined": defs,
"description": desc}
def check_ref2va_sections(plan):
"""Plan-level six-section check: every shot's compiled prompt is a complete
Ref2VA prompt in canonical order with legal definitions and isolation."""
assert plan["prompt_prefix"] == [""], \
"prompt_prefix must be exactly [''] (empirical: better H3 results, no prose preamble)"
counts = []
modes = []
for idx, shot in enumerate(plan["shots"], 1):
text = _prompt_text(shot.get("prompt", ""), f"shot {idx}")
dur = float(shot.get("duration_seconds",
plan.get("defaults", {}).get("duration_seconds", 15)))
info = check_ref2va_prompt(text, f"shot {idx} ({shot.get('id', '?')})",
duration=dur)
wc = len(info["body"].split())
floor = THIN_FLOOR_LONG if dur >= 10 else THIN_FLOOR_SHORT
if wc < floor:
raise ValueError(
f"shot {idx}: description is only {wc} words - too thin to carry "
f"the elements of a scene composition (subject, wardrobe, style, "
f"continuity, blocking, camera, performance, texture, sound, "
f"exit state)")
if "<Subject 1>" not in info["body"]:
raise ValueError(f"shot {idx}: description body must reference "
f"<Subject 1> (prefix is empty)")
if re.search(r"\bbare\b", info["body"], re.I):
print(f" note: shot {idx} body says 'bare' - call uncovered body "
f"parts 'nude' (e.g. 'nude arms')")
if " is now " in info["body"].lower():
raise ValueError(f"shot {idx}: change stated as bare outcome instead of "
f"shown progression")
if "<d>" in info["soundscape"]:
raise ValueError(f"shot {idx}: dialogue must not appear in the "
f"soundscape section")
spans = DIALOGUE_SPAN_RE.findall(info["body"])
if spans and not re.search(r"silently with mouth", info["body"]):
raise ValueError(f"shot {idx}: dialogue span lacks a mouth-state cue")
for span in spans:
if "\n" in span:
raise ValueError(f"shot {idx}: a <d> dialogue span contains a raw "
f"line break - keep every span on one line")
forms = sorted({info["defined"][lb]["form"] for lb in info["defined"]})
print(f" shot {idx} id={shot.get('id', '?')!r} six-section ref2va OK "
f"({len(info['defined'])} subject(s): {', '.join(forms)}; "
f"body {wc} words)")
print(" H3 section structure: all shots carry the six Ref2VA sections in "
"canonical order")
return True
# ---------------------------------------------------------------------------
# Scene-agent fragment validation (agent workflow)
# ---------------------------------------------------------------------------
def validate_fragment(obj, index=1, total=None, prev_handoff=None, expect=None):
"""Validate one scene-agent fragment (the future shot of a plan).
obj -- parsed fragment: {id, prompt, duration_seconds, _handoff}
index/total -- position in the story (1-based) for messages
prev_handoff -- previous fragment's _handoff dict, or None for scene 1
expect -- optional outline row {id, duration_seconds, dialogue}
Returns the fragment's _handoff so callers can chain turns.
"""
where = f"fragment {index}" + (f"/{total}" if total else "")
if not isinstance(obj, dict):
raise ValueError(f"{where}: must be a JSON object")
allowed = {"id", "prompt", "duration_seconds", "_handoff", "steps", "seed"}
required = {"id", "prompt", "duration_seconds", "_handoff"}
unknown = set(obj) - allowed
if unknown:
raise ValueError(f"{where}: unknown keys {sorted(unknown)} (allowed: {sorted(allowed)})")
missing = required - set(obj)
if missing:
raise ValueError(f"{where}: missing keys {sorted(missing)}")
shot_id = obj["id"]
if not isinstance(shot_id, str) or not shot_id.strip():
raise ValueError(f"{where}: id must be a non-empty string")
if _safe_name(shot_id) != shot_id:
raise ValueError(f"{where}: id {shot_id!r} does not survive node sanitization")
if not re.fullmatch(r"[a-z0-9_]+", shot_id):
print(f" note: id {shot_id!r} is not lowercase snake_case (node would allow it)")
dur = obj["duration_seconds"]
if isinstance(dur, bool) or not isinstance(dur, (int, float)) or not math.isfinite(dur):
raise ValueError(f"{where}: duration_seconds must be a finite number")
if not 2 <= dur <= 15:
raise ValueError(f"{where}: duration_seconds {dur} outside the 2-15 window")
raw_frames = _h3_frame_length(dur)
prompt = obj["prompt"]
if isinstance(prompt, str):
text = prompt.strip()
elif (isinstance(prompt, list) and prompt
and all(isinstance(line, str) and line.strip() for line in prompt)):
text = "\n".join(prompt)
else:
raise ValueError(f"{where}: prompt must be a string or an array of "
f"non-empty strings")
info = check_ref2va_prompt(text, where, duration=dur)
body, ssc = info["body"], info["soundscape"]
wc = len(body.split())
floor = THIN_FLOOR_LONG if dur >= 10 else THIN_FLOOR_SHORT
if wc < floor:
raise ValueError(f"{where}: description is only {wc} words - too thin to carry "
f"the elements of a scene composition (subject, wardrobe, "
f"style, continuity, blocking, camera, performance, texture, "
f"sound, exit state)")
if "<Subject 1>" not in body:
raise ValueError(f"{where}: description body must reference <Subject 1> "
f"(prefix is empty)")
if re.search(r"\bbare\b", body, re.I):
print(f" note: {where} body says 'bare' - call uncovered body parts "
f"'nude' (e.g. 'nude arms')")
if " is now " in body.lower():
raise ValueError(f"{where}: change stated as bare outcome instead of shown progression")
if "<d>" in ssc:
raise ValueError(f"{where}: dialogue must not appear in the soundscape section")
spans = [MARKER_RE.sub("", span, count=1).strip()
for span in DIALOGUE_SPAN_RE.findall(body)]
if spans and not re.search(r"silently with mouth", body):
raise ValueError(f"{where}: dialogue span lacks a 'silently with mouth' cue")
for span in spans:
if "\n" in span:
raise ValueError(f"{where}: a <d> dialogue span contains a raw line "
f"break - keep every span on one line")
handoff = obj["_handoff"]
if not isinstance(handoff, dict):
raise ValueError(f"{where}: _handoff must be an object")
for key in ("end_state", "soundscape", "dialogue_used"):
if key not in handoff:
raise ValueError(f"{where}: _handoff missing {key!r}")
end_state = handoff["end_state"]
if not isinstance(end_state, str) or len(end_state.split()) < 5:
raise ValueError(f"{where}: _handoff.end_state must describe the final frame "
f"(>= 5 words)")
if handoff["soundscape"] != ssc:
raise ValueError(f"{where}: _handoff.soundscape must copy the overall_soundscape "
f"text character for character (no section label)")
used = handoff["dialogue_used"]
if not isinstance(used, list) or not all(isinstance(x, str) for x in used):
raise ValueError(f"{where}: _handoff.dialogue_used must be a list of strings")
if sorted(used) != sorted(spans):
raise ValueError(f"{where}: _handoff.dialogue_used {used} does not mirror the "
f"<d> spans {spans}")
if mode == "t2va" and prev_handoff is not None:
prev_line = ""
if isinstance(prev_handoff, dict):
prev_line = str(prev_handoff.get("soundscape", ""))
if prev_line and not CONTINUITY_RE.search(ssc):
raise ValueError(f"{where}: soundscape does not continue the previous audio "
f"bed (say 'the same ... continues')")
if prev_line and not CONTINUITY_RE.search(body):
raise ValueError(f"{where}: description does not open inside the previous "
f"end_state (use a continuity cue: 'Continue the same ...', "
f"'without resetting the motion')")
if expect is not None:
if expect.get("id") not in (None, shot_id):
raise ValueError(f"{where}: outline says id {expect.get('id')!r}, "
f"fragment says {shot_id!r}")
exp_dur = expect.get("duration_seconds")
if exp_dur is not None and float(exp_dur) != float(dur):
raise ValueError(f"{where}: outline says duration {exp_dur}, fragment says {dur}")
exp_dialogue = list(expect.get("dialogue") or [])
if exp_dialogue != list(used):
raise ValueError(f"{where}: outline dialogue {exp_dialogue} != "
f"dialogue_used {used}")
if "steps" in obj and not 1 <= int(obj["steps"]) <= 10000:
raise ValueError(f"{where}: steps out of range")
if "seed" in obj:
s = int(obj["seed"])
if s < 0 or s > MAX_SEED:
raise ValueError(f"{where}: seed out of range")
print(f" {where} id={shot_id!r} dur={dur:g}s raw={raw_frames} frames "
f"body_words={wc} handoff ok"
+ (f" dialogue={len(spans)}" if spans else ""))
return handoff
# ---------------------------------------------------------------------------
# Fixtures - the candy-store reference run (six-section, refmod + no-image)
# ---------------------------------------------------------------------------
SAM_REFMOD = ("<Subject 1> identity: Sam is a 9 year old boy with his blonde hair "
"in pigtails that dresses like a baby girl; voice: Sam is a 9 year "
"old boy with his blonde hair in pigtails that dresses like a baby girl")
SHOPKEEPER_NOIMAGE = ("<Subject 2> is a 55 year old man with short grey hair, "
"brown eyes and a heavy build")
CANDY_SUMMARY = ["summary:", "[reference generation]"]
CANDY_RETENTION = ["retention_analysis:",
"<Subject 1>: fully_preserved",
"<Subject 2>: fully_preserved"]
CANDY_STYLE = ["detailed_description:",
"Warm photoreal candy-store realism, soft late-afternoon light "
"pooling through the front windows, saturated jar-glass golds and "
"wrapper reds under a gentle film grain.",
"Static eye-level camera held at <Subject 1>'s eye height, shallow "
"depth of field on the candy jars."]
CANDY_BROWSE_BODY = (
"[Shot 1] <Subject 1> stands rooted in front of the counter-height candy "
"shelves, both small hands hovering an inch from the glass. The camera holds "
"a static low wide angle at his exact eye height, the ranked candy jars and "
"bright wrapper rows sharp in shallow focus around him. <Subject 2>, the "
"heavy-set shopkeeper with short grey hair in his green apron over a "
"rolled-sleeve white shirt, sets a fresh jar of lollipops on the counter's "
"far end behind the register, his big hands careful with the glass. "
"<Subject 1> rocks on his heels with quick, eager breaths, eyes tracking jar "
"to jar; he rises on his toes until his fingertips squeak against the shelf "
"glass, taps it twice in front of a red-and-white swirl lollipop, then drops "
"his hand and turns his shoulders toward the counter, mid-step.")
CANDY_BROWSE_SSC = (
"the low hum of the candy-store fridge case, a soft crinkle of cellophane "
"wrappers, small soles squeaking on polished floorboards, muffled street "
"traffic behind the front glass.")
CANDY_BROWSE = {
"id": "candy_browse",
"duration_seconds": 10,
"prompt": (
["subject_definitions:", SAM_REFMOD, SHOPKEEPER_NOIMAGE]
+ CANDY_SUMMARY + CANDY_RETENTION + CANDY_STYLE
+ [CANDY_BROWSE_BODY, "overall_soundscape:", CANDY_BROWSE_SSC,
"non_diegetic_music:", "N/A"]),
"_handoff": {
"end_state": "<Subject 1> has turned from the candy shelves and is "
"stepping toward the counter, right fingertip just off the "
"glass, camera static at his eye height.",
"soundscape": CANDY_BROWSE_SSC,
"dialogue_used": [],
},
}
CANDY_PICKUP_BODY = (
"[Shot 1] Continuing the same shot without resetting the motion: <Subject 1> "
"closes the last step to the counter and leans both hands on the polished "
"wood. The camera holds a static counter-height medium shot at his eye "
"level, the register and stacked jars soft behind his shoulder. He stretches "
"his right hand across the counter, small fingers closing around the stick "
"of the red-and-white swirl lollipop lying beside the till, and lifts it up "
"in front of his eyes, the cellophane crinkling; his mouth falls open in a "
"delighted grin and he bounces once on his toes. <Subject 2>, the heavy-set "
"shopkeeper with short grey hair in his green apron over a rolled-sleeve "
"white shirt, watches from behind the register and nods once, wiping his "
"hands on a white cloth. End mid-motion: the lollipop held high in his "
"right fist, his left hand finding the small red coin purse on its strap at "
"his hip.")
CANDY_PICKUP_SSC = (
"the same low fridge-case hum and wrapper crinkle continue, the lollipop's "
"cellophane crackling under small fingers, the till drawer rattling softly "
"below the counter, street traffic still muffled behind the front glass.")
CANDY_PICKUP = {
"id": "lollipop_pickup",
"duration_seconds": 10,
"prompt": (
["subject_definitions:", SAM_REFMOD, SHOPKEEPER_NOIMAGE]
+ CANDY_SUMMARY + CANDY_RETENTION + CANDY_STYLE
+ [CANDY_PICKUP_BODY, "overall_soundscape:", CANDY_PICKUP_SSC,
"non_diegetic_music:", "N/A"]),
"_handoff": {
"end_state": "<Subject 1> stands at the counter, the swirl lollipop held "
"high in his right fist, his left hand finding the small red "
"coin purse on its strap at his hip, camera static at "
"counter height.",
"soundscape": CANDY_PICKUP_SSC,
"dialogue_used": [],
},
}
# A binds-form fixture: the look comes from the reference image and is still
# woven into the body (refmod isolation does not apply to binds subjects).
NURSE_BINDS = {
"id": "corridor_walk",
"duration_seconds": 8,
"prompt": [
"subject_definitions:",
"<Subject 1> binds to <Image 1> : the night nurse from the reference "
"photo - pale green scrub top and matching trousers, white sneakers, "
"brown hair pulled back in a low clip, a hospital ID badge on a lanyard",
"summary:", "[reference generation]",
"retention_analysis:", "<Subject 1>: fully_preserved",
"detailed_description:",
"Cool fluorescent corridor realism, steady over-the-shoulder framing at "
"shoulder height.",
"[Shot 1] <Subject 1>, the same night nurse in her pale green scrubs and "
"white sneakers, pushes the steel trolley forward with both hands, its "
"wheels squeaking softly on the linoleum, a paper cup and a clipped "
"chart riding on top. The camera keeps a steady over-the-shoulder "
"framing at her shoulder height, gliding at her pace, fluorescent "
"panels passing overhead in even rhythm, the corridor walls sliding "
"past in soft focus. Her sneakers land heel first and roll to the toe, "
"the cup's surface trembling with each push, and the hem of her scrub "
"top sways in counterpoint to the trolley's roll. Her jaw stays set, "
"eyes forward, one loose strand of hair lifting with each step; the "
"trolley's shadow stretches and compresses under each ceiling panel. "
"Reaching the blue door at the corridor's end, she slows the trolley to "
"a stop and her right hand leaves the handle, closing on the door's "
"cold push bar.",
"overall_soundscape:",
"the low fluorescent hum and a distant trolley squeak under a soft "
"draught breathing under the far door.",
"non_diegetic_music:", "N/A",
],
"_handoff": {
"end_state": "She is stopped at the blue door at the corridor's end, "
"right hand closing on the cold push bar, trolley at her "
"hip, camera still at her shoulder.",
"soundscape": "the low fluorescent hum and a distant trolley squeak "
"under a soft draught breathing under the far door.",
"dialogue_used": [],
},
}
# Ref2VA fragment: the six native H3 reference sections, one line per element,
# headers on their own line. handoff.soundscape copies the soundscape CONTENT
# line (the element after the overall_soundscape: header), not the header.
REF2VA_NURSE = {
"id": "corridor_walk",
"duration_seconds": 8,
"prompt": [
"subject_definitions:",
"<Subject 1> binds to <Image 1> : a woman in her thirties with dark brown "
"hair in a low bun, calm grey eyes, slim build, pale green scrubs, white "
"sneakers.",
"summary:",
"[reference generation]",
"retention_analysis:",
"<Subject 1>: fully_preserved",
"detailed_description:",
"Photorealistic cool fluorescent lighting, soft clinical palette, stable "
"over-the-shoulder tracking shots.",
"[Shot 1] Continue the same walk along the corridor without resetting the "
"motion. <Subject 1>, the same night nurse from her reference image with a "
"slim build and dark brown hair pulled back in a low bun, pushes the steel "
"trolley forward with both hands, its wheels squeaking softly on the linoleum, "
"a paper cup and a clipped chart riding on top. Her pale green scrub top and "
"matching scrub trousers hang smooth as she leans into the push, her nude "
"hands below the scrub cuffs wrapped around the cold handle, and her white "
"sneakers land heel first and roll to the toe, her nude lower legs showing "
"above the sneaker collars with each stride. The camera keeps a steady "
"over-the-shoulder framing at her shoulder height, gliding at her pace, "
"fluorescent panels passing overhead in even rhythm, the corridor walls "
"sliding past in soft focus. The cup's surface trembles with each push, and "
"the hem of her scrub top sways in counterpoint to the trolley's roll. Her "
"jaw stays set, her calm grey eyes forward, one loose strand of hair lifting "
"with each step; the trolley's shadow stretches and compresses under each "
"ceiling panel. Reaching the blue door at the corridor's end, she slows the "
"trolley to a stop and her right hand leaves the handle, closing on the "
"door's cold push bar.",
"overall_soundscape:",
"the same low fluorescent hum and distant trolley squeak continue, a soft "
"draught breathing under the far door.",
"non_diegetic_music:",
"N/A",
],
"_handoff": {
"end_state": "She is stopped at the blue door at the corridor's end, right "
"hand closing on the cold push bar, trolley at her hip, camera "
"still at her shoulder.",
"soundscape": "the same low fluorescent hum and distant trolley squeak "
"continue, a soft draught breathing under the far door.",
"dialogue_used": [],
},
}
# DOOR exercises the third definition form: a user refmod carried through
# verbatim (identity + voice), exempt from the no-image content bans.
REF2VA_DOOR = {
"id": "door_stop",
"duration_seconds": 8,
"prompt": [
"subject_definitions:",
"<Subject 1> identity: The night nurse is a woman in her thirties with "
"dark brown hair in a low bun and calm grey eyes; voice: The night nurse "
"speaks in a low, unhurried, even voice.",
"summary:",
"[reference generation]",
"retention_analysis:",
"<Subject 1>: fully_preserved",
"detailed_description:",
REF2VA_NURSE["prompt"][7],
"[Shot 1] Continue the same corridor walk without resetting the motion, the "
"trolley still rolling at her pace. <Subject 1> eases the steel trolley to "
"a stop beside the blue door, both hands relaxing on the handle one after "
"the other, its last wheel squeak dying on the linoleum. The camera holds "
"its over-the-shoulder framing while her shoulders settle and the paper "
"cup's surface stills on the trolley top; the fluorescent panels keep "
"their even rhythm overhead and the corridor walls stay in soft focus. "
"Her right hand leaves the handle, opens, and closes on the door's cold "
"push bar while the clipped chart keeps swaying on its clip.",
"overall_soundscape:",
"the same low fluorescent hum continues, the trolley wheels fall silent, a "
"soft draught breathing under the far door.",
"non_diegetic_music:",
"N/A",
],
"_handoff": {
"end_state": "Her right hand is closing on the cold push bar, trolley at her "
"hip, cup stilled, camera at her shoulder.",
"soundscape": "the same low fluorescent hum continues, the trolley wheels "
"fall silent, a soft draught breathing under the far door.",
"dialogue_used": [],
},
}
def _short_fragment(**over):
base = json.loads(json.dumps(CANDY_BROWSE)) # deep copy
base.update(over)
return base
def _ref2va_short(**over):
base = json.loads(json.dumps(REF2VA_NURSE)) # deep copy
base.update(over)
return base
def run_fragment_suite():
print("Fragment edge cases that must PASS:")
handoff = validate_fragment(dict(CANDY_BROWSE), index=1, total=3)
validate_fragment(dict(CANDY_PICKUP), index=2, total=3,
prev_handoff=handoff)
validate_fragment(dict(NURSE_BINDS), index=1, total=2)
chained_binds = json.loads(json.dumps(NURSE_BINDS))
chained_binds["id"] = "corridor_return"
chained_binds["prompt"] = [
"subject_definitions:", NURSE_BINDS["prompt"][1],
"summary:", "[reference generation]",
"retention_analysis:", "<Subject 1>: fully_preserved",
"detailed_description:",
"Cool fluorescent corridor realism, steady over-the-shoulder framing at "
"shoulder height.",
"[Shot 1] Continuing the same walk without resetting the motion, "
"<Subject 1>, the same night nurse in her pale green scrubs and white "
"sneakers, pulls the blue door open with her right hand while her left "
"hand keeps the steel trolley rolling beside her, its wheels squeaking "
"softly on the linoleum as the threshold passes under her white "
"sneakers. The camera keeps its over-the-shoulder framing at her "
"shoulder height and glides through the doorway after her, fluorescent "
"panels giving way to the ward's warmer night lights, the corridor "
"walls sliding past in soft focus. The paper cup trembles on the "
"trolley top with each push, the clipped chart shifts in its clip, and "
"the hem of her scrub top sways with her stride. She brings the "
"trolley alongside the ward bed and turns her shoulders toward it, "
"both hands still on the handle, the door swinging shut behind her.",
"overall_soundscape:",
"the same soft draught under the door now behind her, the trolley "
"squeak continues, a distant monitor beep joins the low hum.",
"non_diegetic_music:", "N/A",
]
chained_binds["_handoff"] = {
"end_state": "She stands beside the ward bed with both hands on the "
"trolley handle, shoulders turning toward the bed, the "
"door shut behind her.",
"soundscape": "the same soft draught under the door now behind her, the "
"trolley squeak continues, a distant monitor beep joins "
"the low hum.",
"dialogue_used": [],
}
validate_fragment(chained_binds, index=2, total=2,
prev_handoff=dict(NURSE_BINDS["_handoff"]))
print(" all fragment PASS cases ok (refmod verbatim, binds, no-image "
"traits, refmod isolation clean)")
def run_defs_suite():
defs_cases_pass = [
("no-image traits", SHOPKEEPER_NOIMAGE),
("long no-image traits, no cap",
"<Subject 1> is a 9 year old boy with long blonde hair in two pigtails "
"that reach past his shoulders, bright blue eyes, round cheeks, a small "
"button nose, fair skin and a slight narrow build"),
("long binds description, no cap",
"<Subject 1> binds to <Image 1> : a 9 year old boy with blonde hair in "
"pigtails, blue eyes, a small frame, wearing a pink frilly dress with "
"white lace trim, white socks and shiny black shoes"),
("refmod verbatim", SAM_REFMOD),
]
print("\nsubject_definitions forms that must PASS:")
for label, line in defs_cases_pass:
line = line.replace("<Subject 2>", "<Subject 1>")
frag = _short_fragment(prompt=["subject_definitions:", line]
+ CANDY_SUMMARY
+ ["retention_analysis:", "<Subject 1>: fully_preserved"]
+ CANDY_STYLE
+ [CANDY_BROWSE_BODY.replace("<Subject 2>, the "
"heavy-set shopkeeper "
"with short grey hair "
"in his green apron "
"over a rolled-sleeve "
"white shirt, ", "")
.replace("<Subject 2>", "the shopkeeper"),
"overall_soundscape:", CANDY_BROWSE_SSC,
"non_diegetic_music:", "N/A"])
frag["_handoff"] = dict(CANDY_BROWSE["_handoff"])
validate_fragment(frag, index=1, total=1)
print(f" {label}: ok")
print("\nsubject_definitions forms that must FAIL:")
fail_defs = [
("clothing in no-image defs",
"<Subject 2> is a 55 year old man with short grey hair, brown eyes, a "
"heavy build and a green apron"),
("nude skin state in no-image defs",
"<Subject 2> is a 55 year old man with short grey hair, nude arms and "
"a heavy build"),
("& wrapper kept on refmod",
"<Subject 1> &identity: Sam is a 9 year old boy; voice: Sam is a 9 "
"year old boy&"),
("refmod missing the voice part",
"<Subject 1> identity: Sam is a 9 year old boy with blonde pigtails"),
("binds without the colon description",
"<Subject 1> binds to <Image 1>"),
("unknown definition form",
"<Subject 2> has short grey hair and a heavy build"),
]
for label, line in fail_defs:
frag = _short_fragment(prompt=["subject_definitions:", line]
+ CANDY_SUMMARY + CANDY_RETENTION + CANDY_STYLE
+ [CANDY_BROWSE_BODY, "overall_soundscape:",
CANDY_BROWSE_SSC, "non_diegetic_music:", "N/A"])
frag["_handoff"] = dict(CANDY_BROWSE["_handoff"])
try:
validate_fragment(frag, index=1, total=1)
print(f" {label} UNEXPECTEDLY PASSED <-- BUG")
except (ValueError, AssertionError) as exc:
print(f" {label} rejected: {exc}")
def run_ref2va_fail_suite():
print("\nSix-section Ref2VA cases that must FAIL:")
def with_prompt(lines, **over):
frag = _short_fragment(prompt=lines, **over)
frag["_handoff"] = dict(CANDY_BROWSE["_handoff"],
soundscape=lines[lines.index("overall_soundscape:") + 1])
return frag
def defs_only(labels):
return ["subject_definitions:"] + labels
cases = [
("missing section (no summary)",
with_prompt(defs_only([SAM_REFMOD, SHOPKEEPER_NOIMAGE])
+ CANDY_RETENTION + CANDY_STYLE
+ [CANDY_BROWSE_BODY, "overall_soundscape:", CANDY_BROWSE_SSC,
"non_diegetic_music:", "N/A"]), {}),
("sections out of order",
with_prompt(CANDY_SUMMARY + defs_only([SAM_REFMOD, SHOPKEEPER_NOIMAGE])
+ CANDY_RETENTION + CANDY_STYLE
+ [CANDY_BROWSE_BODY, "overall_soundscape:", CANDY_BROWSE_SSC,
"non_diegetic_music:", "N/A"]), {}),
("summary is not the reference-generation directive",
with_prompt(defs_only([SAM_REFMOD, SHOPKEEPER_NOIMAGE])
+ ["summary:", "[video editing]"] + CANDY_RETENTION
+ CANDY_STYLE
+ [CANDY_BROWSE_BODY, "overall_soundscape:", CANDY_BROWSE_SSC,
"non_diegetic_music:", "N/A"]), {}),
("duplicate definition",
with_prompt(defs_only([SAM_REFMOD, SAM_REFMOD, SHOPKEEPER_NOIMAGE])
+ CANDY_SUMMARY + CANDY_RETENTION + CANDY_STYLE
+ [CANDY_BROWSE_BODY, "overall_soundscape:", CANDY_BROWSE_SSC,
"non_diegetic_music:", "N/A"]), {}),
("used but not defined (<Subject 3>)",
with_prompt(defs_only([SAM_REFMOD, SHOPKEEPER_NOIMAGE])
+ CANDY_SUMMARY
+ ["retention_analysis:", "<Subject 1>: fully_preserved",
"<Subject 2>: fully_preserved",
"<Subject 3>: fully_preserved"]
+ CANDY_STYLE
+ [CANDY_BROWSE_BODY, "overall_soundscape:", CANDY_BROWSE_SSC,
"non_diegetic_music:", "N/A"]), {}),
("defined but not retained",
with_prompt(defs_only([SAM_REFMOD, SHOPKEEPER_NOIMAGE])
+ CANDY_SUMMARY
+ ["retention_analysis:", "<Subject 1>: fully_preserved"]
+ CANDY_STYLE
+ [CANDY_BROWSE_BODY, "overall_soundscape:", CANDY_BROWSE_SSC,
"non_diegetic_music:", "N/A"]), {}),
("unknown retention marker",
with_prompt(defs_only([SAM_REFMOD, SHOPKEEPER_NOIMAGE])
+ CANDY_SUMMARY
+ ["retention_analysis:", "<Subject 1>: mostly_kept",
"<Subject 2>: fully_preserved"]
+ CANDY_STYLE
+ [CANDY_BROWSE_BODY, "overall_soundscape:", CANDY_BROWSE_SSC,
"non_diegetic_music:", "N/A"]), {}),
("refmod isolation broken in body (look re-described)",
with_prompt(defs_only([SAM_REFMOD, SHOPKEEPER_NOIMAGE])
+ CANDY_SUMMARY + CANDY_RETENTION + CANDY_STYLE
+ [CANDY_BROWSE_BODY.replace(
"stands rooted in front of the counter-height candy "
"shelves, both small hands hovering",
"his blonde pigtails bouncing, stands rooted in front "
"of the counter-height candy shelves, both small hands "
"hovering"),
"overall_soundscape:", CANDY_BROWSE_SSC,
"non_diegetic_music:", "N/A"]), {}),
("refmod isolation broken in body (name re-stated)",
with_prompt(defs_only([SAM_REFMOD, SHOPKEEPER_NOIMAGE])
+ CANDY_SUMMARY + CANDY_RETENTION + CANDY_STYLE
+ [CANDY_BROWSE_BODY.replace(
"[Shot 1] <Subject 1> stands rooted",
"[Shot 1] <Subject 1>, Sam, stands rooted"),
"overall_soundscape:", CANDY_BROWSE_SSC,
"non_diegetic_music:", "N/A"]), {}),
("refmod isolation broken in soundscape",
with_prompt(defs_only([SAM_REFMOD, SHOPKEEPER_NOIMAGE])
+ CANDY_SUMMARY + CANDY_RETENTION + CANDY_STYLE
+ [CANDY_BROWSE_BODY, "overall_soundscape:",
CANDY_BROWSE_SSC + " a baby girl giggles once.",
"non_diegetic_music:", "N/A"]), {}),
("unexpected section (old three-line label)",
with_prompt(defs_only([SAM_REFMOD, SHOPKEEPER_NOIMAGE])
+ CANDY_SUMMARY + CANDY_RETENTION + CANDY_STYLE
+ [CANDY_BROWSE_BODY,
"integrated_multimodal_description: leftover text",
"overall_soundscape:", CANDY_BROWSE_SSC,
"non_diegetic_music:", "N/A"]), {}),
("description too thin to compose the scene",
with_prompt(defs_only([SAM_REFMOD, SHOPKEEPER_NOIMAGE])
+ CANDY_SUMMARY + CANDY_RETENTION + CANDY_STYLE
+ ["[Shot 1] <Subject 1> walks on. End mid-stride.",
"overall_soundscape:", CANDY_BROWSE_SSC,
"non_diegetic_music:", "N/A"]), {}),
("body does not start with [Shot 1]",
with_prompt(defs_only([SAM_REFMOD, SHOPKEEPER_NOIMAGE])
+ CANDY_SUMMARY + CANDY_RETENTION + CANDY_STYLE
+ ["[Shot 2] <Subject 1> walks the aisle instead of the "
"candy shelves and keeps walking. " * 8,
"overall_soundscape:", CANDY_BROWSE_SSC,
"non_diegetic_music:", "N/A"]), {}),
("bare 'is now' outcome",
with_prompt(defs_only([SAM_REFMOD, SHOPKEEPER_NOIMAGE])
+ CANDY_SUMMARY + CANDY_RETENTION + CANDY_STYLE
+ [CANDY_BROWSE_BODY.replace("rocks on his heels with quick, "
"eager breaths",
"is now a toddler in the cart"),
"overall_soundscape:", CANDY_BROWSE_SSC,
"non_diegetic_music:", "N/A"]), {}),
("dialogue in the soundscape section",
with_prompt(defs_only([SAM_REFMOD, SHOPKEEPER_NOIMAGE])
+ CANDY_SUMMARY + CANDY_RETENTION + CANDY_STYLE
+ [CANDY_BROWSE_BODY, "overall_soundscape:",
CANDY_BROWSE_SSC + " <d>[English] One lollipop.</d>",
"non_diegetic_music:", "N/A"]), {}),
("handoff.soundscape not the soundscape text",
_short_fragment(_handoff={"end_state": CANDY_BROWSE["_handoff"]["end_state"],
"soundscape": "different soundscape text.",
"dialogue_used": []}), {}),
("dialogue_used does not mirror spans", None, None), # replaced below
("id disagrees with outline row",
_short_fragment(id="hallway_walk"),
{"expect": {"id": "candy_browse", "duration_seconds": 10, "dialogue": []}}),
("steps out of range", _short_fragment(steps=0), {}),
("duration outside 2-15", _short_fragment(duration_seconds=20), {}),
("missing _handoff",
{k: v for k, v in CANDY_BROWSE.items() if k != "_handoff"}, {}),
]
# dialogue_used mismatch case (add a spoken line properly first)
spoken = with_prompt(defs_only([SAM_REFMOD, SHOPKEEPER_NOIMAGE])
+ CANDY_SUMMARY + CANDY_RETENTION + CANDY_STYLE
+ [CANDY_BROWSE_BODY.replace(
"rocks on his heels with quick, eager breaths",
"stands silently with mouth closed, then speaks. "
"<d>[English] One lollipop, please.</d> He falls "
"silently with mouth closed and rocks on his "
"heels with quick, eager breaths"),
"overall_soundscape:", CANDY_BROWSE_SSC,
"non_diegetic_music:", "N/A"])
spoken["_handoff"]["dialogue_used"] = ["A line nobody said."]
cases[17] = ("dialogue_used does not mirror spans", spoken, {})
for i, (label, obj, kwargs) in enumerate(cases, 1):
if obj is None:
continue
try:
validate_fragment(obj, index=1, total=1, **kwargs)
print(f" case {i} ({label}) UNEXPECTEDLY PASSED <-- BUG")
except (ValueError, AssertionError) as exc:
print(f" case {i} ({label}) rejected: {str(exc)[:110]}")
def run_chain_fail_suite():
print("\nChain continuity cases that must FAIL:")
prev = dict(CANDY_BROWSE["_handoff"])
def fresh():
return json.loads(json.dumps(CANDY_PICKUP))
no_ssc_cont = fresh()
no_ssc_cont["prompt"][-3] = ("seagulls cry over fresh surf and a busker's "
"guitar plinks somewhere on the promenade.")
no_ssc_cont["_handoff"] = dict(no_ssc_cont["_handoff"],
soundscape=no_ssc_cont["prompt"][-3])
no_desc_cont = fresh()
no_desc_cont["prompt"] = list(no_desc_cont["prompt"])
no_desc_cont["prompt"][11] = CANDY_PICKUP_BODY.replace(
"Continuing the same shot without resetting the motion: ", "")
no_desc_cont["_handoff"] = dict(no_desc_cont["_handoff"])
cases = [
("soundscape ignores previous audio bed", no_ssc_cont,
{"prev_handoff": prev}),
("description does not open inside the previous end_state", no_desc_cont,
{"prev_handoff": prev}),
]
for i, (label, obj, kwargs) in enumerate(cases, 1):
try:
validate_fragment(obj, index=2, total=3, **kwargs)
print(f" case {i} ({label}) UNEXPECTEDLY PASSED <-- BUG")
except (ValueError, AssertionError) as exc:
print(f" case {i} ({label}) rejected: {str(exc)[:110]}")
# The 90-second, 6-scene example user message -> plausible LLM output
SIX_SCENE = {
"prompt_prefix": ["<Subject 1> is the same retired boxer...",
"Warm film look, one continuous take."],
"defaults": {"duration_seconds": 15, "steps": 20},
"shots": [{"id": f"kitchen_dance_{i:02d}", "prompt": ["Continue..."],
"duration_seconds": 15} for i in range(1, 7)],
}
# Edge cases that must PASS
edge_ok = [
{"shots": ["Opening scene.", "Continue through the doorway."]}, # bare strings
{"prompt_prefix": "Shared style.", "shots": [{"id": "a", "length": 362},
{"id": "b", "frames": 124}]}, # exact frames
{"prompt_prefix": "p", "shots": [{"id": "a", "prompt": ["x"], "duration_seconds": 7.5},
{"id": "b", "prompt": ["y"], "context_length": 0},
{"id": "c", "prompt": ["z"], "context_length": 0}]},
]
# Edge cases that must FAIL
edge_bad = [
{"prompt_prefix": "p", "shots": [{"id": "a", "length": 360}]}, # invalid grid
{"prompt_prefix": "p", "shots": [{"id": "a", "prompt": "x", "duration_seconds": 200}]},
{"shots": [{"id": "a", "prompt": "x"}, {"id": "a", "prompt": "y"}]}, # dup id
{"shots": []}, # empty shots
{"shots": [{"id": "a"}]}, # no prompt anywhere
]
def run_embedded_suite():
plan = {"prompt_prefix": [""],
"defaults": {"duration_seconds": 10, "steps": 5},
"shots": [{k: CANDY_BROWSE[k] for k in ("id", "prompt", "duration_seconds")},
{k: CANDY_PICKUP[k] for k in ("id", "prompt", "duration_seconds")}]}
print("Worked example (candy-store reference run, merged two-shot plan):")
validate_plan(plan)
check_ref2va_sections(plan)
print("\n6-scene 90s story example:")
validate_plan(SIX_SCENE)
print("\nEdge cases that must PASS:")
for i, case in enumerate(edge_ok):
validate_plan(case)
print(f" case {i} OK")
print("\nEdge cases that must FAIL:")
for i, case in enumerate(edge_bad):
try:
validate_plan(case)
print(f" case {i} UNEXPECTEDLY PASSED <-- BUG")
except ValueError as exc:
print(f" case {i} rejected: {exc}")
print()
run_fragment_suite()
run_defs_suite()
run_ref2va_fail_suite()
run_chain_fail_suite()
# delivered-duration math check used in the TIMING section
print("\nTiming table (raw frames from duration):")
for s in (0.2, 1, 2, 5, 10, 15, 30, 149.666, 149.667):
try:
print(f" {s}s -> {_h3_frame_length(s)} raw frames")
except ValueError as exc:
print(f" {s}s -> rejected ({exc})")
def main():
import argparse
parser = argparse.ArgumentParser(
description="Validate H3 plan JSONs and scene-agent fragments "
"(replica of chain_nodes.py rules + the six-section Ref2VA "
"prompt contract).")
sub = parser.add_subparsers(dest="cmd")
p_plan = sub.add_parser("plan", help="validate a final plan JSON")
p_plan.add_argument("file")
p_frag = sub.add_parser("fragment", help="validate one scene-agent fragment")
p_frag.add_argument("file")
p_frag.add_argument("--index", type=int, default=1)
p_frag.add_argument("--total", type=int, default=None)
p_frag.add_argument("--prev", default=None,
help="previous fragment file; chains the soundscape handoff")
args = parser.parse_args()
if args.cmd is None:
run_embedded_suite()
return
with open(args.file, encoding="utf-8-sig") as fh:
raw = load_json_text(fh.read(), args.file)
if args.cmd == "plan":
validate_plan(raw)
check_ref2va_sections(raw)
else:
prev = None
if args.prev:
with open(args.prev, encoding="utf-8-sig") as fh:
pf = load_json_text(fh.read(), args.prev)
if isinstance(pf, dict) and isinstance(pf.get("shots"), list) and pf["shots"]:
pf = pf["shots"][-1]
prev = pf.get("_handoff") if isinstance(pf, dict) else None
validate_fragment(raw, index=args.index, total=args.total, prev_handoff=prev)
print("OK")
if __name__ == "__main__":
main()