README: end-to-end example from story idea to final output
Walks the shipped greenhouse example through all six steps: the Cline request, smoke test, outline.json (full JSON), one-file-at-a-time scene validation, build_plan.py merge with real output (1042 frames = 43.42s), and rendering via plan_json_input incl. the revise-one-scene loop. All command blocks aligned to the Windows venv form (.venv\\Scripts\\python.exe) with one macOS/Linux note, matching SKILL.md.
This commit is contained in:
parent
b308dd77e1
commit
a804088d72
124
README.md
Normal file → Executable file
124
README.md
Normal file → Executable file
@ -47,13 +47,16 @@ three-line prompt (`integrated_multimodal_description: [Shot 1] …` / `overall_
|
|||||||
object for the next turn. Optional gate after each turn:
|
object for the next turn. Optional gate after each turn:
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
python3 h3-plan-gate/verify_plan_rules.py fragment scene_02.json --index 2 --prev scene_01.json
|
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py fragment scene_02.json --index 2 --prev scene_01.json
|
||||||
```
|
```
|
||||||
|
|
||||||
|
(All command blocks below use the Windows venv form; on macOS/Linux replace
|
||||||
|
`.venv\Scripts\python.exe` with `python3`.)
|
||||||
|
|
||||||
**Stage 3 — Assembly (deterministic, preferred):**
|
**Stage 3 — Assembly (deterministic, preferred):**
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
python3 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 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
|
The merger validates every fragment in the `_handoff` chain (against the outline when
|
||||||
@ -63,18 +66,123 @@ turn and re-merge. Use the LLM assembler prompt only in a pure-chat setup with n
|
|||||||
execution, and diff its output against the fragments if you do (small models transcribe
|
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).
|
long strings unreliably; `build_plan.py` is byte-exact by construction).
|
||||||
|
|
||||||
|
## Example: story idea → final output
|
||||||
|
|
||||||
|
The complete run of the shipped example (`h3_agent_workflow_examples/`) — the same files
|
||||||
|
your agent should produce for any story.
|
||||||
|
|
||||||
|
**1. Give Cline the story idea.** With the skill installed, the whole request is:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Use the h3-plan-gate skill. Story: a courier delivers a package to a greenhouse in the
|
||||||
|
rain, three shots. When he reaches the table he says exactly: Package for the greenhouse,
|
||||||
|
right on time.
|
||||||
|
```
|
||||||
|
|
||||||
|
**2. The agent runs the smoke test** — proving the toolchain before writing anything:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py
|
||||||
|
.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`.
|
||||||
|
|
||||||
|
**3. The agent writes `outline.json`** — the skeleton that freezes cast, style, ids,
|
||||||
|
durations, and dialogue so later scenes cannot drift:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"title": "greenhouse_courier",
|
||||||
|
"defaults": { "duration_seconds": 15, "steps": 20 },
|
||||||
|
"style_and_cast": {
|
||||||
|
"subjects": ["<Subject 1> — 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."] }
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**4. The agent writes the scenes one file at a time**, validating each before moving on:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py fragment scene_01.json --index 1 --total 3
|
||||||
|
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py fragment scene_02.json --index 2 --total 3 --prev scene_01.json
|
||||||
|
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py fragment scene_03.json --index 3 --total 3 --prev scene_02.json
|
||||||
|
```
|
||||||
|
|
||||||
|
Each fragment carries the three-line H3 prompt and a truthful `_handoff`. Scene 3
|
||||||
|
(description elided — the real file carries ~237 words of action, camera, wardrobe, and
|
||||||
|
lighting detail):
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": "greenhouse_delivery",
|
||||||
|
"duration_seconds": 15,
|
||||||
|
"prompt": [
|
||||||
|
"integrated_multimodal_description: [Shot 1] Continue the same forward stride … He stands silently with mouth closed, then speaks. <d>[English] Package for the greenhouse, right on time.</d> He falls silently with mouth closed … End on the calm wide composition as the delivery completes.",
|
||||||
|
"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": "…", "soundscape": "…", "dialogue_used": ["Package for the greenhouse, right on time."] }
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**5. The agent merges and checks** — never writing the 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
|
||||||
|
.venv\Scripts\python.exe h3-plan-gate/build_plan.py --check plan.json
|
||||||
|
```
|
||||||
|
|
||||||
|
Output:
|
||||||
|
|
||||||
|
```text
|
||||||
|
outline: outline.json (3 scenes)
|
||||||
|
fragment 1/3 … fragment 2/3 … fragment 3/3 …
|
||||||
|
Merged plan:
|
||||||
|
shot 1 id='greenhouse_arrival' raw=362 delivered=362 steps=20
|
||||||
|
shot 2 id='greenhouse_aisle' raw=362 delivered=340 steps=20
|
||||||
|
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
|
||||||
|
```
|
||||||
|
|
||||||
|
`plan.json` is the final artifact — `"prompt_prefix": [""]`, `"defaults"`, and three shots
|
||||||
|
with their three-line prompts and durations (full file:
|
||||||
|
`h3_agent_workflow_examples/plan.json`).
|
||||||
|
|
||||||
|
**6. Render.** Paste the full contents of `plan.json` into the Production Plan node's
|
||||||
|
`plan_json_input` (a non-empty connected value overrides the visual editor's plan for that
|
||||||
|
run), set the Plan node's width/height widgets, and wire the width/height outputs into the
|
||||||
|
conditioning node and sampler latent. You get three 15-second scenes — the first plays in
|
||||||
|
full, each later scene loses ~1 second to overlap trimming — 1042 delivered frames ≈ 43.4 s
|
||||||
|
at 24 fps. 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.
|
||||||
|
|
||||||
### Validating
|
### Validating
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
python3 h3-plan-gate/verify_plan_rules.py # embedded pass/fail suite
|
.venv\Scripts\python.exe 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
|
.venv\Scripts\python.exe 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
|
.venv\Scripts\python.exe h3-plan-gate/build_plan.py --check plan.json # same checks + frame/duration report
|
||||||
```
|
```
|
||||||
|
|
||||||
Smoke test with the shipped examples:
|
Smoke test with the shipped examples:
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
python3 h3-plan-gate/build_plan.py --check h3-plan-gate/h3_agent_workflow_examples/plan.json
|
.venv\Scripts\python.exe h3-plan-gate/build_plan.py --check h3-plan-gate/h3_agent_workflow_examples/plan.json
|
||||||
# expect: PLAN OK — 1042 delivered frames = 43.42s
|
# expect: PLAN OK — 1042 delivered frames = 43.42s
|
||||||
```
|
```
|
||||||
|
|
||||||
@ -89,7 +197,9 @@ node and sampler latent to avoid square output).
|
|||||||
|
|
||||||
### Requirements
|
### Requirements
|
||||||
|
|
||||||
- `build_plan.py` and `verify_plan_rules.py`: Python 3 stdlib only.
|
- `build_plan.py` and `verify_plan_rules.py`: Python 3 stdlib only — no venv packages
|
||||||
|
needed; the `.venv\Scripts\python.exe` form just matches a typical Windows project
|
||||||
|
layout, and plain `python` / `python3` works anywhere.
|
||||||
- `count_prompt_tokens.py`: needs `tiktoken`.
|
- `count_prompt_tokens.py`: needs `tiktoken`.
|
||||||
- LLM settings: temperature 0.3–0.7; enable `response_format: {"type": "json_object"}` or
|
- 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
|
grammar-constrained JSON if the server supports it. Each scene turn is ≈5k tokens, so
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user