> For the complete documentation index, see [llms.txt](/llms.txt). Every page on this site is also available as markdown at `<path>.md`.

# Plans

Typed plan declarations. `define_plan(...)` accepts JSON Schema, Pydantic
models, or a `{name: type}` shorthand and produces a frozen
[`PlanSpec`](#flowai_harness.plans.PlanSpec).

<span id="flowai_harness.plans.define_plan"></span>

## `define_plan`

`define_plan(name: 'str', schema: 'Any', display_aliases: 'Mapping[str, str] | Iterable[PlanDisplayAlias | Mapping[str, str]]' = ()) -> 'PlanSpec'`

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>name</code></td>
<td><code>str</code></td>
<td>required</td>
</tr>
<tr>
<td><code>schema</code></td>
<td><code>Any</code></td>
<td>required</td>
</tr>
<tr>
<td><code>display_aliases</code></td>
<td><code>Mapping[str, str] | Iterable[PlanDisplayAlias | Mapping[str, str]]</code></td>
<td><code>()</code></td>
</tr>
</tbody>
</table>

<p><strong>Returns:</strong> <code>PlanSpec</code></p>

Create a validated Flow AI plan spec.

Args:
    name: Unique plan name within the runtime spec.
    schema: Action schema for plan items: a JSON Schema mapping, a
        Pydantic model class, a simple type map, or any type hint
        Pydantic can export.
    display_aliases: Display names for fixed plan lifecycle statuses,
        either a ``{status: alias}`` mapping or an iterable of
        ``PlanDisplayAlias`` / mappings. Statuses are limited to
        ``draft``, ``approved``, ``executing``, ``executed``, and
        ``failed``.

Returns:
    A frozen, validated ``PlanSpec``.

Raises:
    ValueError: If a display alias names an unsupported status.
    TypeError: If the schema input cannot be normalized to JSON Schema.

<span id="flowai_harness.plans.PlanSpec"></span>

## `PlanSpec`

`PlanSpec(*, name: str, schema: dict[str, typing.Any], displayAliases: list[PlanDisplayAlias] = <factory>) -> None`

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>name</code></td>
<td><code>str</code></td>
<td>required</td>
</tr>
<tr>
<td><code>schema</code></td>
<td><code>dict</code></td>
<td>required</td>
</tr>
<tr>
<td><code>displayAliases</code></td>
<td><code>list</code></td>
<td><code>&lt;factory&gt;</code></td>
</tr>
</tbody>
</table>

<p><strong>Returns:</strong> <code>None</code></p>

Plan declaration compiled by `flowai-runtime` to Plan&lt;HarnessAction&gt;.

<span id="flowai_harness.plans.PlanDisplayAlias"></span>

## `PlanDisplayAlias`

`PlanDisplayAlias(*, status: Literal['draft', 'approved', 'executing', 'executed', 'failed'], alias: str) -> None`

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>status</code></td>
<td><code>typing.Literal</code></td>
<td>required</td>
</tr>
<tr>
<td><code>alias</code></td>
<td><code>str</code></td>
<td>required</td>
</tr>
</tbody>
</table>

<p><strong>Returns:</strong> <code>None</code></p>

Display alias for one fixed Flow AI plan lifecycle status.