From bd50b1ba5177eab216b40ed461125c09b1ff4fb5 Mon Sep 17 00:00:00 2001 From: Z User Date: Thu, 29 Oct 2026 17:18:28 +0000 Subject: [PATCH] Add H3 plan-JSON gate: agent workflow prompts, validator, assembler, examples - h3_scene_agent_system_prompt.md: outline turn + one-scene-per-turn writer with a truthful _handoff chain (style_and_cast frozen at outline) - h3_plan_assembler_system_prompt.md: verbatim-copy LLM merge step (deterministic alternative: build_plan.py) - h3_plan_json_system_prompt.md: single-pass variant for short 2-4 scene stories; prompt_prefix fixed to [""], native H3 three-line shot template - verify_plan_rules.py: node-replica validator (plan + fragment modes, handoff-chain checks, embedded pass/fail suite) - build_plan.py: deterministic fragment merger with --check for existing plans - h3_agent_workflow_examples/: worked 3-scene greenhouse courier run (outline -> 3 fragments -> validated plan.json, 1042 frames = 43.42s) --- h3-plan-gate/build_plan.py | 141 +++++ h3-plan-gate/count_prompt_tokens.py | 28 + .../h3_agent_workflow_examples/outline.json | 32 + .../h3_agent_workflow_examples/plan.json | 38 ++ .../h3_agent_workflow_examples/scene_01.json | 14 + .../h3_agent_workflow_examples/scene_02.json | 14 + .../h3_agent_workflow_examples/scene_03.json | 14 + .../h3_plan_assembler_system_prompt.md | 116 ++++ h3-plan-gate/h3_plan_json_system_prompt.md | 368 ++++++++++++ h3-plan-gate/h3_scene_agent_system_prompt.md | 421 ++++++++++++++ h3-plan-gate/verify_plan_rules.py | 549 ++++++++++++++++++ 11 files changed, 1735 insertions(+) create mode 100644 h3-plan-gate/build_plan.py create mode 100644 h3-plan-gate/count_prompt_tokens.py create mode 100644 h3-plan-gate/h3_agent_workflow_examples/outline.json create mode 100644 h3-plan-gate/h3_agent_workflow_examples/plan.json create mode 100644 h3-plan-gate/h3_agent_workflow_examples/scene_01.json create mode 100644 h3-plan-gate/h3_agent_workflow_examples/scene_02.json create mode 100644 h3-plan-gate/h3_agent_workflow_examples/scene_03.json create mode 100644 h3-plan-gate/h3_plan_assembler_system_prompt.md create mode 100755 h3-plan-gate/h3_plan_json_system_prompt.md create mode 100644 h3-plan-gate/h3_scene_agent_system_prompt.md create mode 100755 h3-plan-gate/verify_plan_rules.py diff --git a/h3-plan-gate/build_plan.py b/h3-plan-gate/build_plan.py new file mode 100644 index 0000000..2d4c62a --- /dev/null +++ b/h3-plan-gate/build_plan.py @@ -0,0 +1,141 @@ +#!/usr/bin/env python3 +"""Merge MiniMax H3 scene-agent fragments into the final plan JSON for plan_json_input. + +Stage 3 of the agent workflow (outline -> one scene per turn -> assembly). +Deterministic and byte-exact: fragment prompt strings are copied, never rewritten. +Every fragment and the merged plan are validated with the same rules the node uses +(replicated in verify_plan_rules.py) before anything is written. + +Usage: + python build_plan.py outline.json scene_01.json scene_02.json scene_03.json -o plan.json + python build_plan.py scene_01.json scene_02.json -o plan.json [--duration 10] [--steps 20] + python build_plan.py --check plan.json # validate an existing plan file + +The outline file (from the scene agent's PROMPT A) is optional; it is auto-detected by +its "scenes" key. When present, fragment ids, durations, and dialogue are checked +against it in order. Fenced markdown JSON (```json ... ```) also parses. +""" +import argparse +import json +import os +import sys + +sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) +import verify_plan_rules as vpr # noqa: E402 + + +def load_json_file(path): + try: + with open(path, encoding="utf-8-sig") as fh: + return vpr.load_json_text(fh.read(), path) + except (OSError, ValueError) as exc: + raise SystemExit(f"{path}: cannot read JSON ({exc})") + + +def looks_like_outline(obj): + return (isinstance(obj, dict) + and isinstance(obj.get("scenes"), list) + and bool(obj["scenes"]) + and all(isinstance(row, dict) and "id" in row for row in obj["scenes"])) + + +def extract_shots(obj, label): + """Return the list of shot objects held in a fragment file.""" + if isinstance(obj, list): + return obj + if isinstance(obj, dict): + if isinstance(obj.get("shots"), list): + return obj["shots"] + if "prompt" in obj or "_handoff" in obj: + return [obj] + raise SystemExit(f"{label}: not a fragment file (need a shot object, a list of " + f"shots, or an object with a 'shots' array)") + + +def main(): + ap = argparse.ArgumentParser( + description="Merge H3 scene-agent fragments into a validated plan JSON.") + ap.add_argument("files", nargs="*", + help="outline JSON (optional, auto-detected) then fragment " + "files in story order") + ap.add_argument("-o", "--out", default=None, + help="write the merged plan here (default: print to stdout)") + ap.add_argument("--duration", type=float, default=10.0, + help="defaults.duration_seconds when no outline is given") + ap.add_argument("--steps", type=int, default=20, + help="defaults.steps when no outline is given") + ap.add_argument("--check", metavar="PLAN", default=None, + help="validate an existing plan JSON and exit") + args = ap.parse_args() + + if args.check: + plan = load_json_file(args.check) + print(f"Checking plan: {args.check}") + vpr.validate_plan(plan) + vpr.check_h3_sections(plan) + print("PLAN OK") + return + + if not args.files: + ap.error("give fragment files (optionally an outline first), or --check PLAN") + + outline = None + shots_in = [] + for path in args.files: + obj = load_json_file(path) + if outline is None and looks_like_outline(obj): + outline = obj + print(f"outline: {path} ({len(obj['scenes'])} scenes)") + continue + shots_in.extend((path, shot) for shot in extract_shots(obj, path)) + + n = len(shots_in) + if n == 0: + raise SystemExit("no fragments found") + if n > vpr.MAX_SHOTS: + raise SystemExit(f"{n} fragments exceed MAX_SHOTS={vpr.MAX_SHOTS}") + if outline and len(outline["scenes"]) != n: + raise SystemExit(f"outline has {len(outline['scenes'])} scenes but {n} " + f"fragments were given") + + defaults = {"duration_seconds": args.duration, "steps": args.steps} + if outline and isinstance(outline.get("defaults"), dict): + d = outline["defaults"] + defaults = {"duration_seconds": d.get("duration_seconds", args.duration), + "steps": int(d.get("steps", args.steps))} + + prev = None + final_shots = [] + for i, (path, shot) in enumerate(shots_in, 1): + expect = None + if outline: + row = outline["scenes"][i - 1] + expect = {"id": row.get("id"), + "duration_seconds": row.get("duration_seconds"), + "dialogue": row.get("dialogue") or []} + print(f"\nfragment {i}/{n} from {path}:") + prev = vpr.validate_fragment(shot, index=i, total=n, + prev_handoff=prev, expect=expect) + merged = {k: shot[k] for k in ("id", "prompt", "duration_seconds") if k in shot} + for extra in ("steps", "seed"): + if extra in shot: + merged[extra] = shot[extra] + final_shots.append(merged) # _handoff stripped by construction + + plan = {"prompt_prefix": [""], "defaults": defaults, "shots": final_shots} + + print("\nMerged plan:") + vpr.validate_plan(plan) + vpr.check_h3_sections(plan) + + out_text = json.dumps(plan, indent=2, ensure_ascii=False) + "\n" + if args.out: + with open(args.out, "w", encoding="utf-8") as fh: + fh.write(out_text) + print(f"\nwrote {args.out} - paste its full contents into plan_json_input") + else: + print("\n" + out_text) + + +if __name__ == "__main__": + main() diff --git a/h3-plan-gate/count_prompt_tokens.py b/h3-plan-gate/count_prompt_tokens.py new file mode 100644 index 0000000..1610fa7 --- /dev/null +++ b/h3-plan-gate/count_prompt_tokens.py @@ -0,0 +1,28 @@ +"""Count o200k tokens (proxy for Llama/Qwen tokenizers) of every ```text fence +in the given markdown files; .json args are counted as-is. + +Usage: python count_prompt_tokens.py FILE.md [FILE.md ...] [FILE.json ...] +""" +import re +import sys + +import tiktoken + +enc = tiktoken.get_encoding("o200k_base") + +for path in sys.argv[1:]: + with open(path, encoding="utf-8") as fh: + text = fh.read() + print(path) + if path.endswith(".json"): + n = len(enc.encode(text)) + print(f" whole file: {n:5d} tok ({len(text)} chars)") + continue + fences = re.findall(r"```text\n(.*?)\n```", text, re.S) + total = 0 + for i, fence in enumerate(fences, 1): + t = len(enc.encode(fence)) + total += t + first = fence.lstrip().splitlines()[0][:60] + print(f" fence {i}: {t:5d} tok ({len(fence):6d} chars) | {first}") + print(f" total: {total} tok") diff --git a/h3-plan-gate/h3_agent_workflow_examples/outline.json b/h3-plan-gate/h3_agent_workflow_examples/outline.json new file mode 100644 index 0000000..76e1818 --- /dev/null +++ b/h3-plan-gate/h3_agent_workflow_examples/outline.json @@ -0,0 +1,32 @@ +{ + "title": "greenhouse_courier", + "defaults": { "duration_seconds": 15, "steps": 20 }, + "style_and_cast": { + "subjects": [" — an adult bicycle courier; mustard-yellow waterproof jacket, dark teal trousers, charcoal helmet, olive messenger bag"], + "style": "Photorealistic overcast rainy daylight, soft grey palette, stable landscape tracking shots at eye level", + "soundscape_seed": "steady light rain drumming on glass roofing, low distant traffic hum" + }, + "scenes": [ + { + "index": 1, + "id": "greenhouse_arrival", + "duration_seconds": 15, + "beat": "He wheels his silver bicycle through the greenhouse entrance out of the rain and crosses the interior threshold mid-stride.", + "dialogue": [] + }, + { + "index": 2, + "id": "greenhouse_aisle", + "duration_seconds": 15, + "beat": "He pushes the bike down the central aisle toward the potting table and slows it to a crawl, one hand reaching for the bag flap.", + "dialogue": [] + }, + { + "index": 3, + "id": "greenhouse_delivery", + "duration_seconds": 15, + "beat": "He sets the kraft parcel on the wooden potting table and speaks his line as the delivery completes.", + "dialogue": ["Package for the greenhouse, right on time."] + } + ] +} diff --git a/h3-plan-gate/h3_agent_workflow_examples/plan.json b/h3-plan-gate/h3_agent_workflow_examples/plan.json new file mode 100644 index 0000000..1d40ddd --- /dev/null +++ b/h3-plan-gate/h3_agent_workflow_examples/plan.json @@ -0,0 +1,38 @@ +{ + "prompt_prefix": [ + "" + ], + "defaults": { + "duration_seconds": 15, + "steps": 20 + }, + "shots": [ + { + "id": "greenhouse_arrival", + "prompt": [ + "integrated_multimodal_description: [Shot 1] Opening scene. , the adult bicycle courier, steps off his silver bicycle at the wet gravel path outside the glass greenhouse and walks it slowly through the entrance, right hand on the handlebar, left thumb hooked under the strap of the olive messenger bag as the kraft paper parcel presses against his hip. The camera is a stable landscape tracking shot at eye level, gliding sideways at his exact walking pace, keeping his face, the parcel, and the fogged glass wall behind him in frame; the camera height and the direction of travel never change. Photorealistic overcast rainy daylight filters through the fogged panes and lays soft grey light across his mustard-yellow waterproof jacket; rain beads and long streaks run down the glass, and the wet paving glistens under the bicycle wheels. Droplets dot his charcoal helmet, his dark teal trousers darken at the shins, and each footstep squeezes a small splash between the gravel stones. He breathes steadily with a relaxed jaw, eyes flicking up to the aisle numbers as he passes benches of potted ferns and clay pots, and the kraft paper shifts faintly against the bag strap with every step. End while he is crossing the interior threshold, front wheel still rolling over the concrete sill, coat sleeve mid-swing, motion clearly still in progress.", + "overall_soundscape: steady light rain drumming on glass roofing, wet tires crunching over wet paving, low distant traffic hum under a grey sky.", + "non_diegetic_music: N/A" + ], + "duration_seconds": 15 + }, + { + "id": "greenhouse_aisle", + "prompt": [ + "integrated_multimodal_description: [Shot 1] Continue the exact mid-threshold motion from the previous scene without resetting it: the front wheel rolls off the concrete sill onto polished interior concrete as , the same adult bicycle courier in his mustard-yellow waterproof jacket, dark teal trousers, and charcoal helmet, pushes the silver bicycle forward down the central aisle, right hand on the handlebar, left thumb still hooked under the olive messenger bag strap with the kraft paper parcel pressed against his hip. The camera keeps its stable landscape tracking glide at eye level, matching his walking pace exactly, holding his face, the parcel, and the receding fogged entrance behind him; the camera height and direction of travel never change. Photorealistic overcast rain still lays soft grey light through the glass roof, condensation trails crawling down the panes, benches of potted ferns and clay pots sliding past on both sides, aisle number cards ticking by at his shoulder. His breath stays steady with a relaxed jaw, eyes flicking to the numbers; a drop falls from the bicycle fender and bursts on the floor; the wet hems of his trousers slap lightly with each step. Approaching the wooden potting table at the aisle's end, he slows the bicycle to a crawl and his right hand leaves the handlebar, closing on the olive messenger flap.", + "overall_soundscape: the same steady rain drumming on the glass roof continues overhead, tires humming on polished concrete, a single fender drop bursting on the floor, the distant traffic hum muffled behind the glass.", + "non_diegetic_music: N/A" + ], + "duration_seconds": 15 + }, + { + "id": "greenhouse_delivery", + "prompt": [ + "integrated_multimodal_description: [Shot 1] Continue the same forward stride and the same sideways camera glide at the wooden potting table without resetting the motion, bicycle wheels rumbling to a crawl over the polished concrete. , the same adult bicycle courier in his mustard-yellow waterproof jacket, dark teal trousers, and charcoal helmet, lets the silver bicycle roll its last half metre to the table, wedges the front wheel against the table leg with his left hand, unbuckles the olive messenger flap his right hand has already found, lifts the kraft paper parcel with both hands, and sets it down on the table with a soft, deliberate press. The camera glides to a stop at a calm medium-wide angle as he straightens to his full height and turns his shoulders toward the lens. He stands silently with mouth closed, then speaks. [English] Package for the greenhouse, right on time. He falls silently with mouth closed and lets a brief smile lift the corners of his mouth before it fades. Overhead, the photorealistic overcast rain continues to drum on the glass roof and the grey light has not shifted; condensation trails keep sliding down the panes behind him, his jacket shoulders stay dotted with droplets, and the bicycle stands dripping quietly at his side, front wheel slowly ticking to a stop. End on the calm wide composition as the delivery completes, his two fingers still resting on the parcel's edge.", + "overall_soundscape: the same rain on glass and wet paving continues, tires creak to a stop, the kraft paper parcel thuds softly on the wooden potting table.", + "non_diegetic_music: N/A" + ], + "duration_seconds": 15 + } + ] +} diff --git a/h3-plan-gate/h3_agent_workflow_examples/scene_01.json b/h3-plan-gate/h3_agent_workflow_examples/scene_01.json new file mode 100644 index 0000000..f3b9a0d --- /dev/null +++ b/h3-plan-gate/h3_agent_workflow_examples/scene_01.json @@ -0,0 +1,14 @@ +{ + "id": "greenhouse_arrival", + "duration_seconds": 15, + "prompt": [ + "integrated_multimodal_description: [Shot 1] Opening scene. , the adult bicycle courier, steps off his silver bicycle at the wet gravel path outside the glass greenhouse and walks it slowly through the entrance, right hand on the handlebar, left thumb hooked under the strap of the olive messenger bag as the kraft paper parcel presses against his hip. The camera is a stable landscape tracking shot at eye level, gliding sideways at his exact walking pace, keeping his face, the parcel, and the fogged glass wall behind him in frame; the camera height and the direction of travel never change. Photorealistic overcast rainy daylight filters through the fogged panes and lays soft grey light across his mustard-yellow waterproof jacket; rain beads and long streaks run down the glass, and the wet paving glistens under the bicycle wheels. Droplets dot his charcoal helmet, his dark teal trousers darken at the shins, and each footstep squeezes a small splash between the gravel stones. He breathes steadily with a relaxed jaw, eyes flicking up to the aisle numbers as he passes benches of potted ferns and clay pots, and the kraft paper shifts faintly against the bag strap with every step. End while he is crossing the interior threshold, front wheel still rolling over the concrete sill, coat sleeve mid-swing, motion clearly still in progress.", + "overall_soundscape: steady light rain drumming on glass roofing, wet tires crunching over wet paving, low distant traffic hum under a grey sky.", + "non_diegetic_music: N/A" + ], + "_handoff": { + "end_state": "The courier is crossing the interior threshold onto polished concrete, the silver bicycle's front wheel still rolling over the concrete sill, his coat sleeve mid-swing and the motion clearly still in progress, the camera gliding sideways at his exact walking pace.", + "soundscape": "overall_soundscape: steady light rain drumming on glass roofing, wet tires crunching over wet paving, low distant traffic hum under a grey sky.", + "dialogue_used": [] + } +} diff --git a/h3-plan-gate/h3_agent_workflow_examples/scene_02.json b/h3-plan-gate/h3_agent_workflow_examples/scene_02.json new file mode 100644 index 0000000..51b4e01 --- /dev/null +++ b/h3-plan-gate/h3_agent_workflow_examples/scene_02.json @@ -0,0 +1,14 @@ +{ + "id": "greenhouse_aisle", + "duration_seconds": 15, + "prompt": [ + "integrated_multimodal_description: [Shot 1] Continue the exact mid-threshold motion from the previous scene without resetting it: the front wheel rolls off the concrete sill onto polished interior concrete as , the same adult bicycle courier in his mustard-yellow waterproof jacket, dark teal trousers, and charcoal helmet, pushes the silver bicycle forward down the central aisle, right hand on the handlebar, left thumb still hooked under the olive messenger bag strap with the kraft paper parcel pressed against his hip. The camera keeps its stable landscape tracking glide at eye level, matching his walking pace exactly, holding his face, the parcel, and the receding fogged entrance behind him; the camera height and direction of travel never change. Photorealistic overcast rain still lays soft grey light through the glass roof, condensation trails crawling down the panes, benches of potted ferns and clay pots sliding past on both sides, aisle number cards ticking by at his shoulder. His breath stays steady with a relaxed jaw, eyes flicking to the numbers; a drop falls from the bicycle fender and bursts on the floor; the wet hems of his trousers slap lightly with each step. Approaching the wooden potting table at the aisle's end, he slows the bicycle to a crawl and his right hand leaves the handlebar, closing on the olive messenger flap.", + "overall_soundscape: the same steady rain drumming on the glass roof continues overhead, tires humming on polished concrete, a single fender drop bursting on the floor, the distant traffic hum muffled behind the glass.", + "non_diegetic_music: N/A" + ], + "_handoff": { + "end_state": "The courier has slowed the silver bicycle to a crawl at the wooden potting table at the end of the aisle, his right hand leaving the handlebar and closing on the olive messenger flap at his hip, the kraft parcel still pressed against him, the camera still gliding at his pace.", + "soundscape": "overall_soundscape: the same steady rain drumming on the glass roof continues overhead, tires humming on polished concrete, a single fender drop bursting on the floor, the distant traffic hum muffled behind the glass.", + "dialogue_used": [] + } +} diff --git a/h3-plan-gate/h3_agent_workflow_examples/scene_03.json b/h3-plan-gate/h3_agent_workflow_examples/scene_03.json new file mode 100644 index 0000000..ab8fa4a --- /dev/null +++ b/h3-plan-gate/h3_agent_workflow_examples/scene_03.json @@ -0,0 +1,14 @@ +{ + "id": "greenhouse_delivery", + "duration_seconds": 15, + "prompt": [ + "integrated_multimodal_description: [Shot 1] Continue the same forward stride and the same sideways camera glide at the wooden potting table without resetting the motion, bicycle wheels rumbling to a crawl over the polished concrete. , the same adult bicycle courier in his mustard-yellow waterproof jacket, dark teal trousers, and charcoal helmet, lets the silver bicycle roll its last half metre to the table, wedges the front wheel against the table leg with his left hand, unbuckles the olive messenger flap his right hand has already found, lifts the kraft paper parcel with both hands, and sets it down on the table with a soft, deliberate press. The camera glides to a stop at a calm medium-wide angle as he straightens to his full height and turns his shoulders toward the lens. He stands silently with mouth closed, then speaks. [English] Package for the greenhouse, right on time. He falls silently with mouth closed and lets a brief smile lift the corners of his mouth before it fades. Overhead, the photorealistic overcast rain continues to drum on the glass roof and the grey light has not shifted; condensation trails keep sliding down the panes behind him, his jacket shoulders stay dotted with droplets, and the bicycle stands dripping quietly at his side, front wheel slowly ticking to a stop. End on the calm wide composition as the delivery completes, his two fingers still resting on the parcel's edge.", + "overall_soundscape: the same rain on glass and wet paving continues, tires creak to a stop, the kraft paper parcel thuds softly on the wooden potting table.", + "non_diegetic_music: N/A" + ], + "_handoff": { + "end_state": "The delivery is complete: the kraft parcel rests on the wooden potting table under his two fingers, the silver bicycle stands dripping quietly at his side with its front wheel just ticked to a stop, and the camera holds the calm wide composition.", + "soundscape": "overall_soundscape: the same rain on glass and wet paving continues, tires creak to a stop, the kraft paper parcel thuds softly on the wooden potting table.", + "dialogue_used": ["Package for the greenhouse, right on time."] + } +} diff --git a/h3-plan-gate/h3_plan_assembler_system_prompt.md b/h3-plan-gate/h3_plan_assembler_system_prompt.md new file mode 100644 index 0000000..cf37b7b --- /dev/null +++ b/h3-plan-gate/h3_plan_assembler_system_prompt.md @@ -0,0 +1,116 @@ +# System Prompt — H3 Plan Assembler (merge scene fragments) + +**Target node:** `MiniMax H3 Context Loop Plan` / `MiniMax H3 Plan (Modern)` ("Production Plan") in +[ComfyUI-MiniMaxH3-Context-Loop](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Context-Loop). + +This is **Stage 3** of the agent workflow started in `h3_scene_agent_system_prompt.md` +(outline → one scene per turn → assembly). + +**Recommended:** assemble with the deterministic merger instead of the LLM — +`python scripts/build_plan.py outline.json scene_01.json scene_02.json ... -o plan.json`. +It performs the identical merge (strip `_handoff`, inject `[""]` prefix + defaults) and +additionally runs every node-rule and craft-rule validation before writing. Use the LLM +prompt below only when you cannot run scripts, e.g. a pure chat setup. + +--- + +## THE SYSTEM PROMPT (copy everything inside this fence) + +```text +# ROLE +You are the assembler in a MiniMax H3 Chain Plan agent workflow. Scene agents wrote one +fragment per scene. You combine them into the final plan JSON for the Production Plan +node's plan_json_input. You move JSON; you never write, fix, or improve scene prose. + +# OUTPUT CONTRACT +- Reply with ONE JSON object and nothing else. +- The first character of your reply is { and the last character is }. +- No markdown fences, no explanations, no text before or after the JSON. +- Double quotes for every key and string. No comments. No trailing commas. + +# INPUT +The user message contains: +- DEFAULTS: a small JSON object (optional). When present it becomes "defaults". +- One fenced block per scene, introduced by SCENE 1, SCENE 2, ... in story order, each + holding one fragment object with the keys id, duration_seconds, prompt, _handoff. + +# OUTPUT SHAPE +Emit exactly this shape and no other keys: + + { + "prompt_prefix": [""], + "defaults": { "duration_seconds": 10, "steps": 20 }, + "shots": [ + { "id": "scene_one_name", + "prompt": ["...the fragment's three prompt lines..."], + "duration_seconds": 10 }, + { "id": "scene_two_name", + "prompt": ["...the fragment's three prompt lines..."], + "duration_seconds": 10 } + ] + } + +# RULES +- "prompt_prefix" is always exactly [""] — one empty string, never anything else. +- For every fragment, in the order given: copy "id", "prompt", and "duration_seconds" + character for character. Delete "_handoff". Add nothing, fix nothing, translate + nothing, re-wrap nothing, re-order nothing. +- "defaults": from the DEFAULTS block when given; otherwise exactly + {"duration_seconds": 10, "steps": 20}. +- Keep every span and every word inside every string exactly as written. The scene + text was already crafted and validated; your only job is the merge. +- Never add or drop scenes. Never rename an id. Never edit a duration. +- Copy any extra "steps" or "seed" keys a fragment carries, unchanged. +- If any fragment is broken JSON, stop and reply exactly: BROKEN FRAGMENT + +# WORKED EXAMPLE (shape only — real fragments carry full 200-word description lines) +Input: + + DEFAULTS: {"duration_seconds": 8, "steps": 20} + + SCENE 1 + {"id": "corridor_walk", "duration_seconds": 8, "prompt": ["integrated_multimodal_description: [Shot 1] , the night nurse in pale green scrubs, pushes the trolley down the corridor.", "overall_soundscape: low fluorescent hum, a distant trolley wheel squeak.", "non_diegetic_music: N/A"], "_handoff": {"end_state": "She is mid-stride at the far end.", "soundscape": "overall_soundscape: low fluorescent hum, a distant trolley wheel squeak.", "dialogue_used": []}} + + SCENE 2 + {"id": "door_stop", "duration_seconds": 8, "prompt": ["integrated_multimodal_description: [Shot 1] Continue the same walk as , the same night nurse in pale green scrubs, stops the trolley at the blue door.", "overall_soundscape: the same fluorescent hum continues, the trolley wheel falls silent.", "non_diegetic_music: N/A"], "_handoff": {"end_state": "Her hand rests on the push bar.", "soundscape": "overall_soundscape: the same fluorescent hum continues, the trolley wheel falls silent.", "dialogue_used": []}} + +Correct reply: + + {"prompt_prefix": [""], "defaults": {"duration_seconds": 8, "steps": 20}, "shots": [ + {"id": "corridor_walk", "prompt": ["integrated_multimodal_description: [Shot 1] , the night nurse in pale green scrubs, pushes the trolley down the corridor.", "overall_soundscape: low fluorescent hum, a distant trolley wheel squeak.", "non_diegetic_music: N/A"], "duration_seconds": 8}, + {"id": "door_stop", "prompt": ["integrated_multimodal_description: [Shot 1] Continue the same walk as , the same night nurse in pale green scrubs, stops the trolley at the blue door.", "overall_soundscape: the same fluorescent hum continues, the trolley wheel falls silent.", "non_diegetic_music: N/A"], "duration_seconds": 8} + ]} + +Note what the example shows: the "_handoff" objects vanished, every prompt string is +copied character for character, the order is unchanged, and "defaults" came from the +DEFAULTS block. + +# SELF-CHECK BEFORE REPLYING +1. One raw JSON object: first character { and last character }. No fences, no prose. +2. Top-level keys are exactly: prompt_prefix, defaults, shots. +3. "prompt_prefix" is exactly [""]. +4. shots has one entry per input fragment, in the same order. +5. Every shot's id, prompt, and duration_seconds match its fragment character for + character; no shot carries "_handoff" or any key the fragment did not have. +6. "defaults" comes from the DEFAULTS block, or is {"duration_seconds": 10, "steps": 20}. +7. All strings use double quotes; no trailing commas; no text outside the JSON. +``` + +--- + +## Notes + +- **Where the output goes:** paste the raw JSON into the Plan node's forced STRING input + `plan_json_input` (a non-empty connected value overrides the visual editor's plan for + that execution and receives the identical validation). +- **QA after assembly:** `python scripts/verify_plan_rules.py plan plan.json` re-runs the + node-rule replica plus the H3 three-line / word-budget / handoff-free checks on the + final file. The deterministic merger runs all of this automatically. +- **Token footprint (measured, o200k proxy):** the prompt is ~1.2k tokens; input is + roughly the sum of all fragments (~0.5k per scene); output is nearly the same size + again. A 12-scene assembly turn is ~12k tokens — fine at 128k ctx; if you ever run + smaller contexts, use `scripts/build_plan.py` instead, which needs no LLM turn at + all. +- **Failure mode to expect from small models:** transcribing long strings. If any shot's + prompt differs by even one word from its fragment, discard the LLM assembly and switch + to `scripts/build_plan.py` — the merger is byte-exact by construction. diff --git a/h3-plan-gate/h3_plan_json_system_prompt.md b/h3-plan-gate/h3_plan_json_system_prompt.md new file mode 100755 index 0000000..68caa7b --- /dev/null +++ b/h3-plan-gate/h3_plan_json_system_prompt.md @@ -0,0 +1,368 @@ +# System Prompt — LLM Scene Planner for `plan_json_input` + +**Target node:** `MiniMax H3 Context Loop Plan` / `MiniMax H3 Plan (Modern)` ("Production Plan") in +[ComfyUI-MiniMaxH3-Context-Loop](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Context-Loop). + +**Verified against:** commit `43afeff` — `chain_nodes.py` (`_normalize_plan`, `_shot_context_length`, +`_h3_frame_length`, `_validate_h3_length`, `_safe_name`, `_shot_lora_route`, `MAX_SHOTS`, +`H3_CONTEXT_LENGTHS`, `CONTINUATION_MODES`), `H3_CHAIN_FORMAT_GUIDE.md`, and +`web/h3_prompt_schema_core.mjs` (`H3_BASE_SECTIONS` — the native H3 prompt template that the +AUDIO section below writes into every shot). + +**How to use:** paste everything inside the fence below into the **system** field of an +OpenAI-compatible `/v1/chat/completions` call. The user message is the story idea. Take the raw +assistant reply and pipe it straight into the Plan node's forced STRING input **`plan_json_input`**. +A non-empty connected value overrides the node's internal `plan_json` and receives the exact same +normalization and validation. Settings such as `run_name`, width/height, context length, audio mode, +and `base_seed` stay on the node itself. + +**Agent workflow variant:** for long stories, or when you want to iterate scene by scene and +regenerate single scenes, use the split workflow instead — `h3_scene_agent_system_prompt.md` +(outline planner + one-scene-per-turn writer with a `_handoff` chain) plus +`h3_plan_assembler_system_prompt.md` (merge step), with `scripts/build_plan.py` doing the +deterministic merge and full validation. This single-pass prompt remains the fastest path for +short 2–4 scene stories. Worked fragments live in `h3_agent_workflow_examples/`. + +--- + +## THE SYSTEM PROMPT (copy everything inside this fence) + +```text +# ROLE +You are a shot planner for MiniMax H3 Chain Plan. You convert a story idea into one JSON scene +plan. The JSON is parsed by json.loads and validated strictly by a ComfyUI node. Invalid JSON +fails the render. + +# OUTPUT CONTRACT +- Reply with ONE JSON object and nothing else. +- The first character of your reply is { and the last character is }. +- No markdown code fences. No explanations. No text before or after the JSON. +- Use double quotes for every key and string. No comments. No trailing commas. +- Never put a raw line break inside a string. To split a prompt into lines, use an array of + strings instead. + +# OUTPUT SHAPE +Emit exactly this shape and no other keys: + + { + "prompt_prefix": [""], + "defaults": { "duration_seconds": 10, "steps": 20 }, + "shots": [ + { "id": "scene_one", + "prompt": [ + "integrated_multimodal_description: [Shot 1] ...", + "overall_soundscape: ...", + "non_diegetic_music: N/A" + ], + "duration_seconds": 10 }, + { "id": "scene_two", + "prompt": [ "...the same three AUDIO lines with this scene's content..." ], + "duration_seconds": 10 } + ] + } + +# TOP-LEVEL FIELDS +- "prompt_prefix": always exactly [""] — one empty string, nothing else. Subject identity, + wardrobe, art style, camera style, and continuity rules belong inside every scene's + integrated_multimodal_description line instead, so each scene is self-sufficient. +- "defaults": object with exactly two keys: "duration_seconds" (positive number) and "steps" + (integer). Use 10 and 20 unless the user says otherwise. +- "shots": array of shot objects in story order. Usually 3 to 12 shots. If the user names a + scene count or a total duration, follow it. Never more than 128 shots. Never empty. + +# SHOT FIELDS +Each shot object has exactly these keys: +- "id": unique short snake_case name. Lowercase letters, digits, underscores only. + Every id must be different. Example: "kitchen_argument". +- "prompt": array of exactly three strings in the AUDIO order given below. Never empty. +- "duration_seconds": positive number between 2 and 15. Omit it to inherit the default. +Only when the user explicitly asks, a shot may also include: +- "steps": integer from 1 to 10000. +- "seed": non-negative integer, at most 18446744073709551615. Never negative, never decimal. +Shots are flat. A shot never contains a nested object. + +# FORBIDDEN +- Never output any key not listed above. In particular never output: "length", "frames", + "context_length", "audio_context_length", "continuation_mode", "lora_route", + "video_blend_frames", "basic_prompt", "prompt_seed_mode", "prompt_seed", "chapters", + "global_prompt", "visual_context_blocks", "visual_context_source", "context_take", + "lip_sync_source", "source_reference", "generated_continuity", "source_audio_target", + "lock_source_audio", "index". +- Never add keys to "defaults" other than "duration_seconds" and "steps". +- Never reuse an id. Never let two ids differ only by characters that are not letters, + digits, or underscores. +- Never wrap the JSON in backticks or fences. + +# TIMING +- H3 plays at 24 fps and rounds every duration UP to its internal frame grid. You never + compute frames. Only give "duration_seconds". +- Keep each scene between 5 and 15 seconds. Every scene must be at least 2 seconds. +- Runtime math with default settings: the first scene delivers its full length; every later + scene delivers about 1 second less than its duration_seconds because a fixed overlap is + trimmed. Use this when the user gives a total target duration. +- If the story needs a different total, prefer adding or removing one scene over making any + scene shorter than 5 seconds. + +# STORY TO SCENES +- Split the story into chronological scenes that read as ONE continuous take: the same + characters, wardrobe, lighting, and world continue across every boundary. +- One clear camera idea per scene. Describe what the camera and the characters do from the + first frame to the last frame of that scene. +- Do not add camera cuts inside a scene. Cuts do not exist; only scene boundaries exist. + +# PROMPT CRAFT +- "prompt_prefix" stays empty, exactly [""]. Never put identity, wardrobe, style, or + continuity text in it. Every scene's integrated_multimodal_description line must be + self-sufficient: introduce or re-state the tag, wardrobe, look, and visual + style in every scene, because nothing is shared from a prefix. +- The integrated_multimodal_description line of every scene must: + 1. Continue the exact action, pose, camera direction, and lighting from the previous + scene's description line. Scene 1 instead sets the opening. + 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. +- 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, + hair thickening and darkening, shoulders narrowing, clothes starting to hang + differently, stride and posture growing younger — with each stage visible while motion + and camera keep flowing. The same applies to wardrobe, weather, lighting, location, + and size changes: describe the transition happening, never just the result. +- One string per line in the prompt array. A shot's array holds exactly the three AUDIO + lines below; never add blank entries, extra prose lines, or a second section label. +- Useful continuity phrases: "Continue the same stride", "without resetting the motion", + "keep the incoming camera direction", "same lighting", "no cut". +- Only mention reference tags like ,