mmprompt/README.md
Z User 63a4469315 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.
2026-10-29 17:31:19 +00:00

96 lines
4.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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.