From 83cc5145bf74237e5ace62af44ecdd885187cfe3 Mon Sep 17 00:00:00 2001 From: Z User Date: Thu, 29 Oct 2026 19:00:11 +0000 Subject: [PATCH] Realign: one plan JSON, written one scene at a time MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The deliverable is the single merged plan.json — the same shape the single-pass system prompt emits — and the multi-clip video is what the node itself produces from it: each shot renders as its own clip, chained through the H3 context loop into one continuous video. Removed the --clips per-scene export (external stitching is NOT the design). Workflow restated everywhere: outline turn -> the LLM writes each scene one at a time (one focused turn per scene) -> build_plan.py puts it all together at the end into plan.json -> paste once, queue once. build_plan.py: --clips option and export block removed; docstring now describes the node-side chaining. README: intro/example/validating/ wiring rewritten around the single deliverable. SKILL.md: goal, Step 3 (Put it all together at the end), Step 4 (the node makes the multi-clip video), and the revising loop updated. Suite + --check green. --- README.md | 85 +++++++++---------- h3-plan-gate/SKILL.md | 49 +++++------ h3-plan-gate/build_plan.py | 39 +++------ h3-plan-gate/count_prompt_tokens.py | 0 .../h3_agent_workflow_examples/outline.json | 0 .../h3_agent_workflow_examples/plan.json | 0 .../h3_agent_workflow_examples/scene_01.json | 0 .../h3_agent_workflow_examples/scene_02.json | 0 .../h3_agent_workflow_examples/scene_03.json | 0 .../h3_plan_assembler_system_prompt.md | 0 h3-plan-gate/h3_scene_agent_system_prompt.md | 0 11 files changed, 69 insertions(+), 104 deletions(-) mode change 100644 => 100755 h3-plan-gate/count_prompt_tokens.py mode change 100644 => 100755 h3-plan-gate/h3_agent_workflow_examples/outline.json mode change 100644 => 100755 h3-plan-gate/h3_agent_workflow_examples/plan.json mode change 100644 => 100755 h3-plan-gate/h3_agent_workflow_examples/scene_01.json mode change 100644 => 100755 h3-plan-gate/h3_agent_workflow_examples/scene_02.json mode change 100644 => 100755 h3-plan-gate/h3_agent_workflow_examples/scene_03.json mode change 100644 => 100755 h3-plan-gate/h3_plan_assembler_system_prompt.md mode change 100644 => 100755 h3-plan-gate/h3_scene_agent_system_prompt.md diff --git a/README.md b/README.md index a40ebe4..346206a 100755 --- a/README.md +++ b/README.md @@ -5,12 +5,17 @@ Prompt set and tooling that turn a story idea into the `plan_json_input` JSON for the **Production Plan** node (`MiniMax H3 Context Loop Plan` / `MiniMax H3 Plan (Modern)`) in [ComfyUI-MiniMaxH3-Context-Loop](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Context-Loop), -verified against commit `43afeff`. The workflow is agent-shaped: one outline turn, one turn -per scene, then a validated merge — so long stories are written scene by scene and single -scenes can be regenerated without touching the rest. The merge exports **one render-ready -JSON per scene** (`clips/clip_NN.json`) for making **multi-clip videos** — each scene is -rendered as its own clip and stitched in an editor — plus an optional merged `plan.json` -for a single continuous chain take. +verified against commit `43afeff`. The deliverable is always **one plan JSON with one shot +per scene** — the node renders every shot as its own clip and chains the clips through the +H3 context loop into one continuous multi-clip video, so pasting one `plan.json` and +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. ### Files @@ -20,7 +25,7 @@ for a single continuous chain take. | `h3_scene_agent_system_prompt.md` | Stage 1 + 2 system prompts: **PROMPT A** (outline planner) and **PROMPT B** (one-scene-per-turn writer with a `_handoff` chain) | | `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: strips `_handoff`, injects `"prompt_prefix": [""]` + defaults, validates everything before writing; `--clips` exports one single-scene plan JSON per scene for multi-clip rendering | +| `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 | | `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` | @@ -89,7 +94,8 @@ right on time. .venv\Scripts\python.exe h3-plan-gate/build_plan.py --check h3-plan-gate/h3_agent_workflow_examples/plan.json ``` -Expect the suite to pass and `PLAN OK — 1042 delivered frames = 43.42s`. +Expect the suite to pass and, from the second command, `PLAN OK` with +`total delivered: 1042 frames = 43.42s`. **3. The agent writes `outline.json`** — the skeleton that freezes cast, style, ids, durations, and dialogue so later scenes cannot drift: @@ -117,7 +123,8 @@ durations, and dialogue so later scenes cannot drift: } ``` -**4. The agent writes the scenes one file at a time**, validating each before moving on: +**4. The agent writes each scene one at a time** — one file per turn, fully focused on +that scene, validating it before moving to the next: ```sh .venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py fragment scene_01.json --index 1 --total 3 @@ -142,10 +149,11 @@ lighting detail): } ``` -**5. The agent merges, exports the clips, and checks** — never writing plan JSON by hand: +**5. The agent puts it all together at the end** — merging every scene into one plan +JSON, never writing plan JSON by hand: ```sh -.venv\Scripts\python.exe h3-plan-gate/build_plan.py outline.json scene_01.json scene_02.json scene_03.json -o plan.json --clips +.venv\Scripts\python.exe h3-plan-gate/build_plan.py outline.json scene_01.json scene_02.json scene_03.json -o plan.json .venv\Scripts\python.exe h3-plan-gate/build_plan.py --check plan.json ``` @@ -160,38 +168,22 @@ Merged plan: shot 3 id='greenhouse_delivery' raw=362 delivered=340 steps=20 total delivered: 1042 frames = 43.42s wrote plan.json - paste its full contents into plan_json_input - -clip 1/3 -> clips/clip_01.json (id=greenhouse_arrival) - shot 1 id='greenhouse_arrival' raw=362 delivered=362 steps=20 - total delivered: 362 frames = 15.08s - … -clip 3/3 -> clips/clip_03.json (id=greenhouse_delivery) - shot 1 id='greenhouse_delivery' raw=362 delivered=362 steps=20 - total delivered: 362 frames = 15.08s - … -wrote 3 single-scene clip plans -> clips/ - render each clip_NN.json through -plan_json_input as its own video, then stitch the clips in order ``` -Two deliverables: **`clips/clip_01.json`, `clip_02.json`, `clip_03.json`** — one -single-scene plan per clip, the input for a multi-clip video — and the merged -`plan.json` for an optional single continuous take (full file: -`h3_agent_workflow_examples/plan.json`). +The deliverable is the single `plan.json` — `"prompt_prefix": [""]`, `defaults`, and +three self-sufficient shots: exactly the shape the single-pass system prompt emits (full +file: `h3_agent_workflow_examples/plan.json`). -**6. Render the multi-clip video (the main use).** For each clip in order: paste the full -contents of `clips/clip_NN.json` into the Production Plan node's `plan_json_input`, queue -one render, save the output — then stitch the clips in order in any editor. Every clip -renders at its FULL duration (three 15-second scenes = 45 seconds of footage; the chain -overlap trim does not apply to independent clips), and because every description opens -mid-motion and ends mid-action, the cuts read as one continuous take. - -*Alternative — one continuous take:* paste `plan.json` instead and the node renders the -whole story as a single chain video (1042 delivered frames ≈ 43.4 s at 24 fps — every -scene after the first loses ~1 second to overlap trimming). +**6. Render the multi-clip video.** Paste the full contents of `plan.json` into the +Production Plan node's forced STRING input `plan_json_input` and queue **once**. The node +renders each shot as its own clip and chains the clips through the H3 context loop — +scene 2 continues from scene 1's final frames, scene 3 from scene 2's — producing ONE +continuous multi-clip video: 1042 delivered frames ≈ 43.4 s at 24 fps (every scene after +the first loses ~1 second to the fixed overlap trim that stitches the clips together). Want scene 2 different? Just tell the agent "rewrite scene 2, keep everything else": it -rewrites only `scene_02.json`, re-validates, and re-merges — refreshing both the clip and -the merged plan. +rewrites only `scene_02.json`, re-validates it, and re-merges — refreshing `plan.json` +in one command. ### Validating @@ -199,7 +191,6 @@ the merged plan. .venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py # embedded pass/fail suite .venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py plan plan.json # node-rule replica on a final plan .venv\Scripts\python.exe h3-plan-gate/build_plan.py --check plan.json # same checks + frame/duration report -.venv\Scripts\python.exe h3-plan-gate/build_plan.py --check clips/clip_01.json # clips validate the same way ``` Smoke test with the shipped examples: @@ -211,14 +202,14 @@ Smoke test with the shipped examples: ### Wiring the result -For a **multi-clip video**, render one clip at a time: paste the full contents of -`clips/clip_NN.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 run), queue, save, -next clip — then stitch in order. For a **single continuous take**, paste `plan.json` -instead and render once. Resolution, context length, audio mode, and `base_seed` stay on -the node's own widgets (the JSON cannot set them; default canvas is 960×544 — set -width/height widgets and wire the width/height outputs into the conditioning node and -sampler latent to avoid square output). +Paste the full contents of `plan.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 run) and queue once — the node's context loop turns the multi-shot plan into one +multi-clip video by itself; no per-scene renders, no editor stitching. Resolution, +context length, audio mode, and `base_seed` stay on the node's own widgets (the JSON +cannot set them; default canvas is 960×544 — set width/height widgets and wire the +width/height outputs into the conditioning node and sampler latent to avoid square +output). ### Requirements diff --git a/h3-plan-gate/SKILL.md b/h3-plan-gate/SKILL.md index 12b6d01..47097e3 100755 --- a/h3-plan-gate/SKILL.md +++ b/h3-plan-gate/SKILL.md @@ -10,9 +10,9 @@ description: Turn a story idea into a validated plan_json_input JSON for the Min # H3 Plan Gate — agent procedure Goal: produce `plan.json`, the JSON pasted into the Production Plan node's `plan_json_input`, -by writing an outline and then one scene file at a time, validating every file with the -bundled scripts, and merging with `build_plan.py`. Never deliver a plan that did not pass -`--check`. +by writing an outline and then one scene file at a time — each turn fully focused on that +one scene — validating every file with the bundled scripts, and putting all the scenes +together at the end with `build_plan.py`. Never deliver a plan that did not pass `--check`. ## Paths and Python (read first — these exact forms prevent most errors) @@ -92,39 +92,32 @@ Each fragment is exactly this shape: } ``` -## Step 3 — Merge, export clips, check +## Step 3 — Put it all together at the end -Never write the plan JSON by hand and never edit fragment prose during the merge. Run: +Once every scene file passes, merge them into the ONE plan JSON. Never write the plan +JSON by hand and never edit fragment prose during the merge. Run: ```sh -.venv\Scripts\python.exe h3-plan-gate/build_plan.py outline.json scene_01.json scene_02.json scene_03.json -o plan.json --clips +.venv\Scripts\python.exe h3-plan-gate/build_plan.py outline.json scene_01.json scene_02.json scene_03.json -o plan.json .venv\Scripts\python.exe h3-plan-gate/build_plan.py --check plan.json ``` The merger strips `_handoff`, injects `"prompt_prefix": [""]` and `defaults`, validates -everything, and writes two deliverables: +everything, and writes the single deliverable: `plan.json` — `"prompt_prefix": [""]`, +`defaults`, and one self-sufficient shot per scene, exactly the shape the single-pass +system prompt emits. Report the delivered frames/seconds it prints. -- `clips/clip_01.json`, `clip_02.json`, … — one single-scene plan per clip. **This is the - main output: the goal is a multi-clip video**, one rendered clip per scene. -- `plan.json` — all shots in one chain plan (optional: a single continuous take instead). +## Step 4 — Deliver (the node makes the multi-clip video) -Report the delivered frames/seconds it prints. +The user pastes the full contents of `plan.json` into the Plan node's `plan_json_input` +and queues ONCE. The node renders each shot as its own clip and chains the clips through +the H3 context loop — scene 2 continues from scene 1's final frames, scene 3 from scene +2's — producing one continuous multi-clip video. Every scene after the first loses about +1 second to the fixed overlap trim that stitches the clips together. -## Step 4 — Deliver (multi-clip is the default goal) - -**Multi-clip video (main use):** the user renders each scene as its own video — paste the -full contents of `clips/clip_01.json` into the Plan node's `plan_json_input`, queue one -render, save the output, then repeat with `clip_02.json`, `clip_03.json`, … — and stitches -the clips in order in any editor. Each clip renders at its FULL duration (no chain overlap -trimming), and because every description opens mid-motion and ends mid-action, the cuts -read as one continuous take. - -**Continuous take (optional):** pasting `plan.json` instead renders the whole story in one -chain run; every scene after the first then loses about 1 second to overlap trimming. - -Either way: resolution, context length, audio mode, and `base_seed` stay on the node's -widgets — the JSON cannot set them; the width/height outputs must be wired into the -conditioning node and sampler latent or the video can come out square. +Resolution, context length, audio mode, and `base_seed` stay on the node's widgets — the +JSON cannot set them; the width/height outputs must be wired into the conditioning node +and sampler latent or the video can come out square. ## Craft rules for every fragment (violations fail the validator) @@ -164,8 +157,8 @@ conditioning node and sampler latent or the video can come out square. ## Revising one scene Rewrite that `scene_NN.json` (keep its id and duration from the outline), re-validate it -with the fragment command, then re-run the Step 3 merge so `clips/clip_NN.json` and -`plan.json` refresh together. Never patch `plan.json` or a clip file directly. +with the fragment command, then re-run the Step 3 merge so `plan.json` refreshes. Never +patch `plan.json` directly. ## Short stories (2–4 scenes) diff --git a/h3-plan-gate/build_plan.py b/h3-plan-gate/build_plan.py index 5f375fc..bbf683c 100755 --- a/h3-plan-gate/build_plan.py +++ b/h3-plan-gate/build_plan.py @@ -1,22 +1,21 @@ #!/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. +Stage 3 of the agent workflow (outline -> one scene per turn -> put it all together +at the end). 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. + +The merged plan carries one shot per scene. The node renders each shot as its own +clip and chains the clips through the H3 context loop into one continuous video — +this one plan JSON is the whole multi-clip deliverable; paste it into plan_json_input +once and queue once. Usage: - python build_plan.py outline.json scene_01.json scene_02.json scene_03.json -o plan.json --clips + 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 ---clips [DIR] (default dir: clips) additionally writes one single-shot plan JSON per -scene (clip_01.json, clip_02.json, ...) for MULTI-CLIP rendering: render each clip -through plan_json_input as its own video, then stitch the clips in an editor. Each -clip plays at its full duration (no chain overlap trimming). The merged plan (-o / -stdout) remains the single continuous-take render. - 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. @@ -72,9 +71,6 @@ def main(): help="defaults.steps when no outline is given") ap.add_argument("--check", metavar="PLAN", default=None, help="validate an existing plan JSON and exit") - ap.add_argument("--clips", nargs="?", const="clips", default=None, metavar="DIR", - help="also write one single-shot plan JSON per scene here " - "(multi-clip rendering; default dir: clips)") args = ap.parse_args() if args.check: @@ -145,21 +141,6 @@ def main(): else: print("\n" + out_text) - if args.clips: - os.makedirs(args.clips, exist_ok=True) - for i, shot in enumerate(final_shots, 1): - clip = {"prompt_prefix": [""], "defaults": dict(defaults), "shots": [shot]} - print(f"\nclip {i}/{n} -> {args.clips}/clip_{i:02d}.json " - f"(id={shot.get('id')})") - vpr.validate_plan(clip) - vpr.check_h3_sections(clip) - with open(os.path.join(args.clips, f"clip_{i:02d}.json"), "w", - encoding="utf-8") as fh: - fh.write(json.dumps(clip, indent=2, ensure_ascii=False) + "\n") - print(f"\nwrote {n} single-scene clip plans -> {args.clips}/ - render each " - f"clip_NN.json through plan_json_input as its own video, then stitch " - f"the clips in order (each clip plays at its full duration)") - if __name__ == "__main__": main() diff --git a/h3-plan-gate/count_prompt_tokens.py b/h3-plan-gate/count_prompt_tokens.py old mode 100644 new mode 100755 diff --git a/h3-plan-gate/h3_agent_workflow_examples/outline.json b/h3-plan-gate/h3_agent_workflow_examples/outline.json old mode 100644 new mode 100755 diff --git a/h3-plan-gate/h3_agent_workflow_examples/plan.json b/h3-plan-gate/h3_agent_workflow_examples/plan.json old mode 100644 new mode 100755 diff --git a/h3-plan-gate/h3_agent_workflow_examples/scene_01.json b/h3-plan-gate/h3_agent_workflow_examples/scene_01.json old mode 100644 new mode 100755 diff --git a/h3-plan-gate/h3_agent_workflow_examples/scene_02.json b/h3-plan-gate/h3_agent_workflow_examples/scene_02.json old mode 100644 new mode 100755 diff --git a/h3-plan-gate/h3_agent_workflow_examples/scene_03.json b/h3-plan-gate/h3_agent_workflow_examples/scene_03.json old mode 100644 new mode 100755 diff --git a/h3-plan-gate/h3_plan_assembler_system_prompt.md b/h3-plan-gate/h3_plan_assembler_system_prompt.md old mode 100644 new mode 100755 diff --git a/h3-plan-gate/h3_scene_agent_system_prompt.md b/h3-plan-gate/h3_scene_agent_system_prompt.md old mode 100644 new mode 100755