Planning
Ask read-only editorial questions and compile grounded, timed edit plans.
answer = planner.ask(question, name="planner-answer")
plan = planner.compile(prompt, tools=(), name="plan")
# Or use a read-only answer as planning context:
plan = planner.compile(answer, prompt, tools=(), name="plan")planner.ask returns a plain string and cannot write files, compute new
analysis, create source assets, or change the timeline. Its answer is cached
against the prompt and current source/timeline state.
Compile reads the current source_brief.json from the run directory, grounds it
against manifest.json, and fingerprints both files so either source selection
or generated-source changes invalidate a cached plan. It returns a structured
plan with a canvas, total duration, ordered sections, and grounded source
windows. You do not pass the Source Work artifact into this call.
Pass tools=[transcribe] when compilation itself needs transcript evidence,
or tools=[detect_events] when it must watch a clip and ground events that an
earlier pass did not establish. Grant tools=[masking] when compilation should
precompute a reusable matte; planning never places it or writes a
timeline mask contract. Every grant is fail-closed and applies only to that
planning call. See
Agent-only capabilities.
Use its prompt to define the edit's architecture:
- target duration and orientation;
- section order and approximate timing;
- which audio is the narrative spine;
- when B-roll should cover dialogue;
- montage rhythm or beat relationship;
- where titles, captions, or visual breathing room are needed;
- required opening and closing behavior.
Avoid vague requests such as make it cinematic. Say what cinematic means for
this piece: perhaps slow establishing shots, longer holds, low transition
density, natural sound at scene changes, and no animated text.