Realign: one plan JSON, written one scene at a time
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.
This commit is contained in:
parent
54a8271072
commit
83cc5145bf
85
README.md
85
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
|
||||
|
||||
|
||||
@ -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)
|
||||
|
||||
|
||||
@ -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()
|
||||
|
||||
0
h3-plan-gate/count_prompt_tokens.py
Normal file → Executable file
0
h3-plan-gate/count_prompt_tokens.py
Normal file → Executable file
0
h3-plan-gate/h3_agent_workflow_examples/outline.json
Normal file → Executable file
0
h3-plan-gate/h3_agent_workflow_examples/outline.json
Normal file → Executable file
0
h3-plan-gate/h3_agent_workflow_examples/plan.json
Normal file → Executable file
0
h3-plan-gate/h3_agent_workflow_examples/plan.json
Normal file → Executable file
0
h3-plan-gate/h3_agent_workflow_examples/scene_01.json
Normal file → Executable file
0
h3-plan-gate/h3_agent_workflow_examples/scene_01.json
Normal file → Executable file
0
h3-plan-gate/h3_agent_workflow_examples/scene_02.json
Normal file → Executable file
0
h3-plan-gate/h3_agent_workflow_examples/scene_02.json
Normal file → Executable file
0
h3-plan-gate/h3_agent_workflow_examples/scene_03.json
Normal file → Executable file
0
h3-plan-gate/h3_agent_workflow_examples/scene_03.json
Normal file → Executable file
0
h3-plan-gate/h3_plan_assembler_system_prompt.md
Normal file → Executable file
0
h3-plan-gate/h3_plan_assembler_system_prompt.md
Normal file → Executable file
0
h3-plan-gate/h3_scene_agent_system_prompt.md
Normal file → Executable file
0
h3-plan-gate/h3_scene_agent_system_prompt.md
Normal file → Executable file
Loading…
Reference in New Issue
Block a user