Documentation
¶
Overview ¶
Package planner defines the Plan/PlanStep structured-output contract and the whole-plan pre-execution validation logic used in Plan-and-Execute mode. An invalid plan is rejected wholesale before any step executes (TAD §11.3).
See TAD §11.2–§11.3 and PRD §27 for the full specification. Implemented in Phase 8.
Package planner implements the Plan-and-Execute planning contract (TAD §11.3): the structured Plan/PlanStep output the LLM produces under a constrained ResponseFormat, and whole-plan validation against the projected ToolTemplate schemas before any step executes.
The validation guarantee is the load-bearing one: an invalid Plan — an unknown Operation, a missing required field, a DependsOn cycle — is rejected wholesale and returned to the LLM as a single correction turn, never partially executed. This is what prevents a plan with a bad step 3 from having already executed steps 1–2 with real side effects (TAD §11.3, Plan Phase 8 completion criterion).
Index ¶
Constants ¶
const RefPrefix = "ref:"
RefPrefix is the in-argument reference marker the executor uses to resolve one step's Args from a prior step's result (TAD §11.2 step c: "feeding each result into the next step's argument resolution"). A string value of "ref:0" is replaced by step 0's result when the step runs. The same marker is what the mode classifier scans for in ReAct tool-call arguments to detect a data dependency (§11.2 step 2).
Variables ¶
This section is empty.
Functions ¶
func Format ¶
func Format() *llm.JSONSchemaFormat
Format returns the JSON Schema format constraining the LLM to emit a Plan (TAD §11.3). Pass it as llm.ChatRequest.ResponseFormat in Plan-and-Execute mode; providers that lack SupportsStructuredOutput() ignore it.
func SortedOperations ¶
SortedOperations returns the known operation names sorted, for stable messages and tests.
func Validate ¶
Validate performs whole-plan pre-execution validation (TAD §11.3) against the projected tool schemas for this turn: every Operation must exist in schemas (keyed by tool name), every step's Args must satisfy its operation's JSON Schema (required presence, type, enum), and DependsOn must reference strictly earlier steps (cycles/self-references are rejected).
The validation is intentionally a JSON Schema subset — full schema validation lives in the Document Engine — but it is strong enough to catch the failure modes TAD §11.3 names (unknown operation, missing required field, dependency cycle). Any non-nil return means zero steps have executed.
func ValidateArgs ¶
ValidateArgs validates a single step's (already resolved) args against one tool's projected JSON Schema. The Executor re-validates after reference resolution and before the step runs (TAD §11.2 step c / §11.3) so a resolved value never reaches the Document Engine's transaction boundary with a missing required field.
Types ¶
type Plan ¶
type Plan struct {
Steps []PlanStep `json:"steps"`
}
Plan is the structured output of Plan-and-Execute mode (TAD §11.3).
type PlanStep ¶
type PlanStep struct {
Operation string `json:"operation"`
Args map[string]any `json:"args"`
DependsOn []int `json:"depends_on,omitempty"`
}
PlanStep is one unit of a Plan. Operation is a tool name from this turn's ForIdentity() result; DependsOn holds the indices of prior steps whose results this step's Args reference.
Source Files