README: agent usage guide for the h3-plan-gate workflow
3-stage agent workflow (outline -> one scene per turn -> validated merge), per-turn fragment gate, validation commands, smoke test with the shipped examples, plan_json_input wiring notes, and requirements.
This commit is contained in:
parent
bd50b1ba51
commit
63a4469315
93
README.md
93
README.md
@ -1,2 +1,95 @@
|
||||
# mmprompt
|
||||
|
||||
## h3-plan-gate — MiniMax H3 plan-JSON agent workflow + validator
|
||||
|
||||
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.
|
||||
|
||||
### Files
|
||||
|
||||
| File | Role |
|
||||
|---|---|
|
||||
| `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 |
|
||||
| `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` |
|
||||
|
||||
### Agent workflow (3 stages)
|
||||
|
||||
**Stage 1 — Outline.** Put PROMPT A (from `h3_scene_agent_system_prompt.md`) in the system
|
||||
field, the story idea in the user field. Save the reply as `outline.json`. It freezes scene
|
||||
count, ids, durations, beats, verbatim dialogue distribution, and the `style_and_cast` block
|
||||
so later turns cannot drift. You may hand-edit it before Stage 2 — the scene agents follow
|
||||
the edited skeleton.
|
||||
|
||||
**Stage 2 — One scene per turn.** Put PROMPT B in the system field and paste this turn
|
||||
template as the user message:
|
||||
|
||||
```text
|
||||
STORY: <the full story idea>
|
||||
STYLE AND CAST: <paste the "style_and_cast" object from the outline>
|
||||
OUTLINE: <paste the "scenes" array from the outline>
|
||||
WRITE SCENE: 2
|
||||
PREVIOUS HANDOFF: <paste the previous scene's "_handoff" object — or: This is scene 1.>
|
||||
```
|
||||
|
||||
Save each reply as `scene_NN.json` (zero-padded). Each fragment carries the native H3
|
||||
three-line prompt (`integrated_multimodal_description: [Shot 1] …` / `overall_soundscape: …`
|
||||
/ `non_diegetic_music: …`), the duration-tiered word budget, and a truthful `_handoff`
|
||||
object for the next turn. Optional gate after each turn:
|
||||
|
||||
```sh
|
||||
python3 h3-plan-gate/verify_plan_rules.py fragment scene_02.json --index 2 --prev scene_01.json
|
||||
```
|
||||
|
||||
**Stage 3 — Assembly (deterministic, preferred):**
|
||||
|
||||
```sh
|
||||
python3 h3-plan-gate/build_plan.py outline.json scene_01.json scene_02.json scene_03.json -o plan.json
|
||||
```
|
||||
|
||||
The merger validates every fragment in the `_handoff` chain (against the outline when
|
||||
present), then validates the merged plan — only clean JSON is written. Do **not** edit
|
||||
fragment prose by hand during assembly; if you want a scene changed, re-run its Stage 2
|
||||
turn and re-merge. Use the LLM assembler prompt only in a pure-chat setup with no script
|
||||
execution, and diff its output against the fragments if you do (small models transcribe
|
||||
long strings unreliably; `build_plan.py` is byte-exact by construction).
|
||||
|
||||
### Validating
|
||||
|
||||
```sh
|
||||
python3 h3-plan-gate/verify_plan_rules.py # embedded pass/fail suite
|
||||
python3 h3-plan-gate/verify_plan_rules.py plan plan.json # node-rule replica on a final plan
|
||||
python3 h3-plan-gate/build_plan.py --check plan.json # same checks + frame/duration report
|
||||
```
|
||||
|
||||
Smoke test with the shipped examples:
|
||||
|
||||
```sh
|
||||
python3 h3-plan-gate/build_plan.py --check h3-plan-gate/h3_agent_workflow_examples/plan.json
|
||||
# expect: PLAN OK — 1042 delivered frames = 43.42s
|
||||
```
|
||||
|
||||
### Wiring the result
|
||||
|
||||
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 and
|
||||
receives identical normalization/validation. 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
|
||||
|
||||
- `build_plan.py` and `verify_plan_rules.py`: Python 3 stdlib only.
|
||||
- `count_prompt_tokens.py`: needs `tiktoken`.
|
||||
- LLM settings: temperature 0.3–0.7; enable `response_format: {"type": "json_object"}` or
|
||||
grammar-constrained JSON if the server supports it. Each scene turn is ≈5k tokens, so
|
||||
ctx 16384 is comfortable; 128k runs the whole workflow many times over.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user