portia.plan

Plan primitives used to define and execute runs.

This module defines the core objects that represent the plan for executing a PlanRun. The Plan class is the main structure that holds a series of steps (Step) to be executed by an agent in response to a query. Each step can have inputs, an associated tool, and an output. Variables can be used within steps to reference other parts of the plan or constants.

Classes in this file include:

• Variable: A variable used in the plan, referencing outputs of previous steps or constants.
• Step: Defines a single task that an agent will execute, including inputs and outputs.
• ReadOnlyStep: A read-only version of a Step used for passing steps to agents.
• PlanContext: Provides context about the plan, including the original query and available tools.
• Plan: Represents the entire series of steps required to execute a query.

These classes facilitate the definition of runs that can be dynamically adjusted based on the tools, inputs, and outputs defined in the plan.

PlanBuilder Objects

class PlanBuilder()

A builder for creating plans.

This class provides an interface for constructing plans step by step. Requires a step to be added to the plan before building it.

Example:

plan = PlanBuilder() .step("Step 1", "tool_id_1", "output_1") .step("Step 2", "tool_id_2", "output_2") .input("input_1", "value_1") .build()

__init__

def __init__(query: str | None = None) -> None

Initialize the builder with the plan query.

Arguments:

• query str - The original query given by the user.

step

def step(task: str,
         tool_id: str | None = None,
         output: str | None = None,
         inputs: list[Variable] | None = None,
         condition: str | None = None) -> PlanBuilder

Add a step to the plan.

Arguments:

• task str - The task to be completed by the step.
• tool_id str | None - The ID of the tool used in this step, if applicable.
• output str | None - The unique output ID for the result of this step.
• inputs list[Variable] | None - The inputs to the step
• condition str | None - A human readable condition which controls if the step should run or not.

Returns:

• PlanBuilder - The builder instance with the new step added.

input

def input(name: str,
          value: Any | None = None,
          description: str | None = None,
          step_index: int | None = None) -> PlanBuilder

Add an input variable to the chosen step in the plan (default is the last step).

Arguments:

• name str - The name of the input.
• value Any | None - The value of the input.
• description str | None - The description of the input.
• step_index int | None - The index of the step to add the input to. If not provided, the input will be added to the last step.

Returns:

• PlanBuilder - The builder instance with the new input added.

condition

def condition(condition: str, step_index: int | None = None) -> PlanBuilder

Add a condition to the chosen step in the plan (default is the last step).

Arguments:

• condition str - The condition to be added to the chosen step.
• step_index int | None - The index of the step to add the condition to. If not provided, the condition will be added to the last step.

Returns:

• PlanBuilder - The builder instance with the new condition added.

build

def build() -> Plan

Build the plan.

Returns:

• Plan - The built plan.

Variable Objects

class Variable(BaseModel)

A variable in the plan.

A variable is a way of referencing other parts of the plan, usually either another step's output or a constant input variable.

Arguments:

• name str - The name of the variable starting with '$'. The variable should be the output of another step, or be a constant.
• value Any - The value of the variable, which may be set by other preceding steps if not defined.
• description str - A description of the variable.

Step Objects

class Step(BaseModel)

A step in a PlanRun.

A step represents a task in the run to be executed. It contains inputs (variables) and outputs, and may reference a tool to complete the task.

Arguments:

• task str - The task that needs to be completed by this step.
• inputs list[Variable] - The input to the step, which can include constants and variables.
• tool_id str | None - The ID of the tool used in this step, if applicable.
• output str - The unique output ID for the result of this step.

ReadOnlyStep Objects

class ReadOnlyStep(Step)

A read-only copy of a step, passed to agents for reference.

This class creates an immutable representation of a step, which is used to ensure agents do not modify the original plan during execution.

Arguments:

• step Step - A step object from which to create a read-only version.

from_step

@classmethod
def from_step(cls, step: Step) -> ReadOnlyStep

Create a read-only step from a normal step.

Arguments:

• step Step - The step to be converted to read-only.

Returns:

• ReadOnlyStep - A new read-only step.

PlanContext Objects

class PlanContext(BaseModel)

Context for a plan.

The plan context contains information about the original query and the tools available for the planning agent to use when generating the plan.

Arguments:

• query str - The original query given by the user.
• tool_ids list[str] - A list of tool IDs available to the planning agent.

serialize_tool_ids

@field_serializer("tool_ids")
def serialize_tool_ids(tool_ids: list[str]) -> list[str]

Serialize the tool_ids to a sorted list.

Returns:

• list[str] - The tool_ids as a sorted list.

Plan Objects

class Plan(BaseModel)

A plan represents a series of steps that an agent should follow to execute the query.

A plan defines the entire sequence of steps required to process a query and generate a result. It also includes the context in which the plan was created.

Arguments:

• id PlanUUID - A unique ID for the plan.
• plan_context PlanContext - The context for when the plan was created.
• steps list[Step] - The set of steps that make up the plan.

__str__

def __str__() -> str

Return the string representation of the plan.

Returns:

• str - A string representation of the plan's ID, context, and steps.

validate_plan

@model_validator(mode="after")
def validate_plan() -> Plan

Validate the plan.

Checks that all outputs + conditions are unique.

Returns:

• Plan - The validated plan.

ReadOnlyPlan Objects

class ReadOnlyPlan(Plan)

A read-only copy of a plan, passed to agents for reference.

This class provides a non-modifiable view of a plan instance, ensuring that agents can access plan details without altering them.

from_plan

@classmethod
def from_plan(cls, plan: Plan) -> ReadOnlyPlan

Create a read-only plan from a normal plan.

Arguments:

• plan Plan - The original plan instance to create a read-only copy from.

Returns:

• ReadOnlyPlan - A new read-only instance of the provided plan.