diff --git a/README.md b/README.md index 346206a..7127efc 100755 --- a/README.md +++ b/README.md @@ -11,11 +11,14 @@ H3 context loop into one continuous multi-clip video, so pasting one `plan.json` queuing once is all the rendering takes. Instead of asking the LLM to emit that whole JSON in one turn, the gate is agent-shaped: -one outline turn, then **the LLM writes each scene one at a time** — a single turn fully -focused on that scene's action, camera, audio, and continuity — and the scripts **put it -all together at the end** into the same plan JSON the single-pass prompt would have -produced, validated before it ever reaches the node. Long stories stop drifting, and any -single scene can be regenerated without touching the rest. +one outline turn, then **the LLM writes each scene one at a time** — a single turn that +exists purely to compose that scene from every element a good scene needs (subject, +style, continuity, blocking, camera, performance, texture, sound, exit state) — and the +scripts **put it all together at the end** into the same plan JSON the single-pass +prompt would have produced, validated before it ever reaches the node. The point is +compositional attention, not word counts: the validator checks structure and trips only +a thin-scene floor, so any scene can be rewritten until its elements are right, then +re-merged without touching the rest. ### Files @@ -26,7 +29,7 @@ single scene can be regenerated without touching the rest. | `h3_plan_assembler_system_prompt.md` | Stage 3 LLM merge prompt — only when you cannot run scripts | | `h3_plan_json_system_prompt.md` | Single-pass variant (whole plan in one turn) — fastest for 2–4 scene stories | | `build_plan.py` | Deterministic Stage 3 merger — puts all the scenes together at the end: strips `_handoff`, injects `"prompt_prefix": [""]` + defaults, validates everything before writing `plan.json` | -| `verify_plan_rules.py` | Node-replica validator (final plans *and* per-turn fragments) with an embedded test suite | +| `verify_plan_rules.py` | Node-replica validator (final plans *and* per-turn fragments): structure, handoff truth, continuity, thin-scene floor — no word band — with an embedded test suite | | `count_prompt_tokens.py` | o200k token counter for the prompt fences (needs `pip install tiktoken`) | | `h3_agent_workflow_examples/` | Worked 3-scene greenhouse-courier run: `outline.json` → `scene_01..03.json` → `plan.json` | @@ -51,7 +54,7 @@ PREVIOUS HANDOFF: `, the full wardrobe, and the visual style in EVERY scene — nothing is shared between scenes or from a prefix. -- Word budget for the description line: scenes under 10 s aim for ~175 words (never below - 150); scenes of 10 s or longer carry 200–300. Spend them on blocking, camera path and - speed, expression beats, body mechanics, wardrobe behavior, weather on skin and fabric, - lighting, and the exact mid-action end point. +- Scene composition, not word count: the description line must carry every element — + subject anchor (`` and wardrobe restated), style anchor, continuity anchor + (opens inside the previous end_state), blocking, one camera idea, performance beats, + physical texture (wardrobe behavior, weather on skin and fabric, lighting), and a + concrete mid-action exit state. Never pad to a length and never hand in a thin + one-liner — a scene with every element is long enough on its own. The validator only + trips a thin-scene floor (about 100 words); there is no target band. - Open by continuing the previous `_handoff` end_state ("Continue the same stride", "without resetting the motion", "keep the incoming camera direction"); scene 1 sets the opening. End mid-action except the final scene. No camera cuts inside a scene. diff --git a/h3-plan-gate/h3_plan_json_system_prompt.md b/h3-plan-gate/h3_plan_json_system_prompt.md index 68caa7b..7d9a54d 100755 --- a/h3-plan-gate/h3_plan_json_system_prompt.md +++ b/h3-plan-gate/h3_plan_json_system_prompt.md @@ -121,14 +121,23 @@ Shots are flat. A shot never contains a nested object. 2. Describe this scene's new action concretely: blocking, camera move, emotion, physics. 3. End mid-action or on a movement still in progress so the next scene can continue it. Only the final scene may resolve and come to rest. -- The integrated_multimodal_description line must fill the scene's duration. Keep it - within 150-300 words, tiered by scene length: scenes under 10 seconds aim for about - 175 words; scenes of 10 seconds or longer carry 200 to 300 words. Spend the words on - concrete detail: full blocking (who moves where, which hand does what), camera path - and speed, facial-expression beats, body mechanics, wardrobe behavior, weather and - surfaces on skin and fabric, lighting on faces, and the exact mid-action point where - the scene ends. Thin one-line scenes are a failure; vague summary sentences are - filler. +- Compose every scene from the same eight elements, and never chase a word count — + chase the elements. A description that genuinely carries them comes out long enough + on its own; padding to a number is as much a failure as a thin one-liner: + 1. SUBJECT ANCHOR — restated: identity, wardrobe head to toe, hair, build. + 2. STYLE ANCHOR — the one consistent look: medium, lighting quality, palette. + 3. CONTINUITY ANCHOR — open inside the previous scene's end state (scene 1 sets the + opening) and name what carries over: the stride, the camera direction, the light, + the weather. + 4. BLOCKING — the new action as concrete staging: who moves where, which hand does + what, at what pace, handling which object. + 5. CAMERA — one clear camera idea per scene: shot size, height, path, speed, and what + it holds in frame. No cuts inside a scene. + 6. PERFORMANCE — facial-expression beats and body mechanics timed to the action. + 7. PHYSICAL TEXTURE — wardrobe behavior, weather and surfaces on skin and fabric, + weight, momentum, lighting on faces. + 8. EXIT STATE — the exact mid-action point where the scene ends (only the final scene + may come to rest), concrete enough that the next scene opens from it. - Never compress a change into a stated outcome. A line like " is now an 18 year old man" is FORBIDDEN. Show the change as a continuous on-screen progression in the same take — for an age change: wrinkles smoothing, jaw and cheekbones softening, @@ -278,10 +287,11 @@ Correct reply: 7. Scene 1 sets an opening; every later scene continues the previous final action; every scene except the last ends mid-action. Every description line is self-sufficient: it re-states who is, wardrobe, and visual style, because the prefix is empty. -8. Every integrated_multimodal_description line stays within its duration's word - budget — under 10 s: about 175 words (never below 150); 10 s or longer: 200-300 — - and no change anywhere is stated as a bare outcome like "is now"; every - transformation is shown as a continuous on-screen progression. +8. Every description line carries every element of a scene composition — subject, + style, continuity, blocking, camera, performance, texture, exit state — and no + change anywhere is stated as a bare outcome like "is now"; every transformation is + shown as a continuous on-screen progression. Length is a side effect of the + elements, never a target. 9. Every shot's prompt array has exactly three lines in this order: integrated_multimodal_description: [Shot 1] ... / overall_soundscape: ... / non_diegetic_music: ... diff --git a/h3-plan-gate/h3_scene_agent_system_prompt.md b/h3-plan-gate/h3_scene_agent_system_prompt.md index 6b293b1..614b69b 100755 --- a/h3-plan-gate/h3_scene_agent_system_prompt.md +++ b/h3-plan-gate/h3_scene_agent_system_prompt.md @@ -6,7 +6,7 @@ same contract as the single-pass prompt, split into an agent workflow. **Verified against:** commit `43afeff` — `chain_nodes.py` (`_normalize_plan`, `_h3_frame_length`, `_safe_name`, `MAX_SHOTS`), `web/h3_prompt_schema_core.mjs` (`H3_BASE_SECTIONS`), and the same -dialogue/word-budget rules as `h3_plan_json_system_prompt.md`. +dialogue and scene-composition rules as `h3_plan_json_system_prompt.md`. --- @@ -29,10 +29,12 @@ PREVIOUS HANDOFF: restated: identity, wardrobe head to toe, hair, + build. Nothing is shared between scenes or from a prefix. + 2. STYLE ANCHOR — the one consistent look: medium, lighting quality, palette. + 3. CONTINUITY ANCHOR — open inside the previous end_state (scene 1 instead + establishes place, light, and the first action). Name what carries over: the + stride, the camera direction, the light, the weather. + 4. BLOCKING — the new action as concrete staging: who moves where, which hand + does what, at what pace, handling which object. + 5. CAMERA — one clear camera idea: shot size, height, path, speed, and what it + holds in frame. No cuts inside the scene. + 6. PERFORMANCE — facial-expression beats and body mechanics timed to the action. + 7. PHYSICAL TEXTURE — wardrobe behavior, weather and surfaces on skin and fabric, + weight, momentum, lighting on faces. + 8. EXIT STATE — the exact mid-action point where the scene ends (only the final + outline scene may come to rest), concrete enough that the next scene opens + from it. + +The sound picture is its own element and lives in the overall_soundscape line (AUDIO +below); dialogue lives inside the description line (DIALOGUE below). + # PROMPT CRAFT -- The integrated_multimodal_description line must fill the scene's duration. Keep it - within 150-300 words, tiered by scene length: scenes under 10 seconds aim for about - 175 words; scenes of 10 seconds or longer carry 200 to 300 words. Spend the words on - concrete detail: full blocking (who moves where, which hand does what), camera path - and speed, facial-expression beats, body mechanics, wardrobe behavior, weather and - surfaces on skin and fabric, lighting on faces, and the exact mid-action point where - the scene ends. Thin one-line scenes are a failure; vague summary sentences are - filler. - Never compress a change into a stated outcome. A line like " is now an 18 year old man" is FORBIDDEN. Show the change as a continuous on-screen progression in the same take — for an age change: wrinkles smoothing, jaw and cheekbones softening, @@ -372,10 +393,11 @@ Correct reply: and the visual style. 5. The description opens by continuing the PREVIOUS HANDOFF's end_state (scene 1 sets the opening instead) and ends mid-action — except the final outline scene. -6. The description line stays within its duration's word budget — under 10 s: about 175 - words (never below 150); 10 s or longer: 200-300 — and no change anywhere is stated - as a bare outcome like "is now"; every transformation is shown as a continuous - on-screen progression. +6. The description line carries every element of a scene composition — subject anchor, + style anchor, continuity anchor, blocking, camera, performance, physical texture, + exit state — and no change anywhere is stated as a bare outcome like "is now"; + every transformation is shown as a continuous on-screen progression. Length is a + side effect of the elements, never a target. 7. overall_soundscape continues the previous soundscape ("the same ... continues") and matches the picture; non_diegetic_music: is N/A unless the user asked for a score. 8. There is no span anywhere unless this scene's outline row or the story gave @@ -417,5 +439,5 @@ Correct reply: workflow for long stories, per-scene iteration, or regenerating single scenes. - **Validation without assembly:** `python scripts/verify_plan_rules.py fragment scene_02.json --index 2 --prev scene_01.json` checks one fragment against all rules - (structure, word budget, handoff truthfulness, soundscape continuity, dialogue - mirror). + (structure, composition floor, handoff truthfulness, soundscape and description + continuity, dialogue mirror). diff --git a/h3-plan-gate/verify_plan_rules.py b/h3-plan-gate/verify_plan_rules.py index 001baef..c6606a3 100755 --- a/h3-plan-gate/verify_plan_rules.py +++ b/h3-plan-gate/verify_plan_rules.py @@ -27,6 +27,13 @@ DIALOGUE_SPAN_RE = re.compile(r"(.*?)") MARKER_RE = re.compile(r"^\[[^\]]+\]\s*") CONTINUITY_RE = re.compile(r"\b(same\b|continu|still\b)", re.I) +# 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 # description words, scenes under 10 s +THIN_FLOOR_LONG = 120 # description words, scenes of 10 s or longer + def load_json_text(text, label=""): """json.loads tolerant of a surrounding markdown fence (LLM output).""" @@ -180,9 +187,11 @@ def check_h3_sections(plan): f"shot {idx}: description line must re-state (prefix is empty)" dur = float(shot.get("duration_seconds", plan.get("defaults", {}).get("duration_seconds", 15))) - lo, hi = (200, 300) if dur >= 10 else (150, 200) - assert lo <= wc <= hi, \ - f"shot {idx}: {wc} words outside {lo}-{hi} budget for a {dur:g}s scene" + floor = THIN_FLOOR_LONG if dur >= 10 else THIN_FLOOR_SHORT + assert wc >= floor, \ + (f"shot {idx}: description is only {wc} words - too thin to carry the " + f"elements of a scene composition (subject, wardrobe, style, continuity, " + f"blocking, camera, performance, texture, sound, exit state)") assert " is now " not in lines[0].lower(), \ f"shot {idx}: change stated as bare outcome instead of shown progression" assert "" not in lines[1] and "" not in lines[1], \ @@ -191,10 +200,11 @@ def check_h3_sections(plan): assert re.search(r"silently with mouth", lines[0]), \ f"shot {idx}: dialogue span lacks a mouth-state cue" print(" H3 section structure: all shots have the 3 sections in canonical order") - print(" description word budget:", + print(" description lengths:", [(f"{len(s['prompt'][0].split())}w @ " f"{s.get('duration_seconds', plan.get('defaults', {}).get('duration_seconds', 15))}s") - for s in plan["shots"]], "| <10s: 150-200, >=10s: 200-300") + for s in plan["shots"]], + "| composition elements are the gate - no word band") return True @@ -253,10 +263,12 @@ def validate_fragment(obj, index=1, total=None, prev_handoff=None, expect=None): raise ValueError(f"{where}: line 3 must start with 'non_diegetic_music:'") wc = len(desc.split()) - lo, hi = (200, 300) if dur >= 10 else (150, 200) - if not lo <= wc <= hi: - raise ValueError(f"{where}: description is {wc} words, outside {lo}-{hi} " - f"for a {dur:g}s scene") + 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 "" not in desc: raise ValueError(f"{where}: description must re-state (prefix is empty)") if " is now " in desc.lower(): @@ -295,6 +307,10 @@ def validate_fragment(obj, index=1, total=None, prev_handoff=None, expect=None): 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(desc): + 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}, " @@ -314,7 +330,7 @@ def validate_fragment(obj, index=1, total=None, prev_handoff=None, expect=None): raise ValueError(f"{where}: seed out of range") print(f" {where} id={shot_id!r} dur={dur:g}s raw={raw_frames} frames " - f"words={wc} (band {lo}-{hi}) handoff ok" + f"words={wc} handoff ok" + (f" dialogue={len(spans)}" if spans else "")) return handoff @@ -411,7 +427,7 @@ def run_fragment_suite(): cases = [ ("missing _handoff", {k: v for k, v in NURSE_OK.items() if k != "_handoff"}, {}), ("duration outside 2-15", _short_fragment(duration_seconds=20), {}), - ("description far under word budget", + ("description too thin to compose the scene", _short_fragment(prompt=["integrated_multimodal_description: [Shot 1] " " walks on. End mid-stride.", NURSE_OK["prompt"][1], "non_diegetic_music: N/A"]), {}),