agents.planning.models.base¶

Base models for the unified planning system.

This module provides the foundation for a flexible planning system that can support various planning patterns including Plan-and-Execute, ReWOO, LLM Compiler, FLARE RAG, and recursive planning capabilities.

Key Design Principles: 1. Composable: Different planning patterns can mix and match components 2. Extensible: Easy to add new step types and planning patterns 3. Type-safe: Comprehensive validation and type checking 4. Resource-aware: Built-in support for resource tracking and constraints

Classes¶

`ActionStep`	Step that performs a specific action or tool call.
`AdaptivePlan`	Plan that can adapt during execution (FLARE style).
`BasePlan`	Base class for all planning patterns.
`BaseStep`	Base class for all planning steps.
`ConditionalStep`	Step with conditional execution paths.
`DAGPlan`	Plan with explicit DAG structure (LLM Compiler style).
`Dependency`	Represents a dependency between steps.
`DependencyType`	Type of dependency between steps.
`ExecutionMode`	How a step should be executed.
`ParallelStep`	Container for steps that can execute in parallel.
`RecursiveStep`	Step that can spawn sub-plans recursively.
`ResearchStep`	Step for information gathering and research.
`SequentialPlan`	Traditional sequential execution plan.
`StepMetadata`	Metadata for tracking step execution and debugging.
`StepStatus`	Universal status for any plan step.
`StepType`	Type of plan step - extensible for different planning patterns.

Module Contents¶

class agents.planning.models.base.ActionStep(/, **data)¶

Bases: BaseStep

Step that performs a specific action or tool call.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:: data (Any)

class agents.planning.models.base.AdaptivePlan(/, **data)¶

Bases: BasePlan

Plan that can adapt during execution (FLARE style).

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:: data (Any)

adapt(context)¶

Adapt plan based on execution context.

Parameters:: context (dict[str, Any])
Return type:: None

should_adapt(context)¶

Check if plan should adapt based on context.

Parameters:: context (dict[str, Any])
Return type:: bool

class agents.planning.models.base.BasePlan(/, **data)¶

Bases: pydantic.BaseModel

Base class for all planning patterns.

This provides core planning functionality while allowing different planning strategies to extend and customize behavior.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:: data (Any)

add_step(step)¶

Add a step to the plan.

Parameters:: step (AnyStep)
Return type:: None

get_execution_order()¶

Get steps organized by execution order (batches for parallel execution).

Return type:: list[list[AnyStep]]

get_step(step_id)¶

Get step by ID.

Parameters:: step_id (str)
Return type:: AnyStep | None

to_mermaid()¶

Generate Mermaid diagram of plan.

Return type:: str

to_prompt_format()¶

Format plan for inclusion in prompts.

Return type:: str

update_ready_steps()¶

Update and return steps that are ready to execute.

Return type:: list[AnyStep]

property completed_steps: list[AnyStep]¶

Get completed steps.

Return type:: list[AnyStep]

property failed_steps: list[AnyStep]¶

Get failed steps.

Return type:: list[AnyStep]

property has_failures: bool¶

Check if any steps failed.

Return type:: bool

property is_complete: bool¶

Check if plan is complete.

Return type:: bool

model_config¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property pending_steps: list[AnyStep]¶

Get pending steps.

Return type:: list[AnyStep]

property progress_percentage: float¶

Calculate completion percentage.

Return type:: float

property ready_steps: list[AnyStep]¶

Get steps ready to execute.

Return type:: list[AnyStep]

property total_steps: int¶

Total number of steps.

Return type:: int

class agents.planning.models.base.BaseStep(/, **data)¶

Bases: pydantic.BaseModel

Base class for all planning steps.

This provides the core functionality that all step types share, while being flexible enough to support various planning patterns.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:: data (Any)

add_dependency(step_id, dependency_type=DependencyType.HARD, condition=None, required_output=None)¶

Add a dependency to this step.

Parameters:

step_id (str)
dependency_type (DependencyType)
condition (str | None)
required_output (str | None)

Return type:

None

is_ready(completed_steps)¶

Check if all dependencies are satisfied.

Parameters:: completed_steps (dict[str, Any])
Return type:: bool

mark_completed(output=None)¶

Mark step as completed.

Parameters:: output (dict[str, Any] | None)
Return type:: None

mark_failed(error)¶

Mark step as failed.

Parameters:: error (str)
Return type:: None

mark_in_progress()¶

Mark step as in progress.

Return type:: None

mark_ready()¶

Mark step as ready to execute.

Return type:: None

to_prompt_format()¶

Format step for inclusion in prompts.

Return type:: str

classmethod validate_unique_dependencies(v)¶

Ensure no duplicate dependencies.

Parameters:: v (list[Dependency])
Return type:: list[Dependency]

model_config¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agents.planning.models.base.ConditionalStep(/, **data)¶

Bases: BaseStep

Step with conditional execution paths.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:: data (Any)

class agents.planning.models.base.DAGPlan(/, **data)¶

Bases: BasePlan

Plan with explicit DAG structure (LLM Compiler style).

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:: data (Any)

validate_dag()¶

Validate that plan forms a valid DAG (no cycles).

Return type:: bool

class agents.planning.models.base.Dependency(/, **data)¶

Bases: pydantic.BaseModel

Represents a dependency between steps.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:: data (Any)

is_satisfied(step_results)¶

Check if this dependency is satisfied.

Parameters:: step_results (dict[str, Any])
Return type:: bool

class agents.planning.models.base.DependencyType¶

Bases: str, enum.Enum

Type of dependency between steps.

Initialize self. See help(type(self)) for accurate signature.

class agents.planning.models.base.ExecutionMode¶

Bases: str, enum.Enum

How a step should be executed.

Initialize self. See help(type(self)) for accurate signature.

class agents.planning.models.base.ParallelStep(/, **data)¶

Bases: BaseStep

Container for steps that can execute in parallel.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:: data (Any)

class agents.planning.models.base.RecursiveStep(/, **data)¶

Bases: BaseStep

Step that can spawn sub-plans recursively.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:: data (Any)

class agents.planning.models.base.ResearchStep(/, **data)¶

Bases: BaseStep

Step for information gathering and research.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:: data (Any)

class agents.planning.models.base.SequentialPlan(/, **data)¶

Bases: BasePlan

Traditional sequential execution plan.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:: data (Any)

add_sequential_step(step, depends_on_previous=True)¶

Add step with automatic dependency on previous step.

Parameters:

step (AnyStep)
depends_on_previous (bool)

Return type:

None

class agents.planning.models.base.StepMetadata(/, **data)¶

Bases: pydantic.BaseModel

Metadata for tracking step execution and debugging.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:: data (Any)

property execution_time: float | None¶

Calculate execution time in seconds.

Return type:: float | None

class agents.planning.models.base.StepStatus¶

Bases: str, enum.Enum

Universal status for any plan step.

Initialize self. See help(type(self)) for accurate signature.

class agents.planning.models.base.StepType¶

Bases: str, enum.Enum

Type of plan step - extensible for different planning patterns.

Initialize self. See help(type(self)) for accurate signature.