portia.plan_run

Plan runs are executing instances of a Plan.

A plan run encapsulates all execution state, serving as the definitive record of its progress. As the run runs, its PlanRunState, current_step_index, and outputs evolve to reflect the current execution state.

The run also retains an ExecutionContext, which provides valuable insights for debugging and analytics, capturing contextual information relevant to the run's execution.

Key Components

• RunState: Tracks the current status of the run (e.g., NOT_STARTED, IN_PROGRESS).
• current_step_index: Represents the step within the plan currently being executed.
• outputs: Stores the intermediate and final results of the PlanRun.
• ExecutionContext: Provides contextual metadata useful for logging and performance analysis.

PlanRunState Objects

class PlanRunState(PortiaEnum)

The current state of the Plan Run.

Attributes:

• NOT_STARTED - The run has not been started yet.
• IN_PROGRESS - The run is currently in progress.
• NEED_CLARIFICATION - The run requires further clarification before proceeding.
• READY_TO_RESUME - The run is ready to resume after clarifications have been resolved.
• COMPLETE - The run has been successfully completed.
• FAILED - The run has encountered an error and failed.

PlanRunOutputs Objects

class PlanRunOutputs(BaseModel)

Outputs of a Plan Run including clarifications.

Attributes:

• clarifications ClarificationListType - Clarifications raised by this plan run.
• step_outputs dict[str, Output] - A dictionary containing outputs of individual steps. Outputs are indexed by the value given by the step.output field of the plan.
• final_output Output | None - The final consolidated output of the PlanRun if available.

PlanRun Objects

class PlanRun(BaseModel)

A plan run represents a running instance of a Plan.

Attributes:

• id PlanRunUUID - A unique ID for this plan_run.
• plan_id PlanUUID - The ID of the Plan this run uses.
• current_step_index int - The current step that is being executed.
• state PlanRunState - The current state of the PlanRun.
• outputs PlanRunOutputs - Outputs of the PlanRun including clarifications.
• plan_run_inputs dict[str, LocalDataValue] - Dict mapping plan input names to their values.

get_outstanding_clarifications

def get_outstanding_clarifications() -> ClarificationListType

Return all outstanding clarifications.

Returns:

• ClarificationListType - A list of outstanding clarifications that have not been resolved.

get_clarifications_for_step

def get_clarifications_for_step(
        step: int | None = None) -> ClarificationListType

Return clarifications for the given step.

Arguments:

• step int | None - the step to get clarifications for. Defaults to current step.

Returns:

• ClarificationListType - A list of clarifications for the given step.

get_clarification_for_step

def get_clarification_for_step(
        category: ClarificationCategory,
        step: int | None = None) -> Clarification | None

Return a clarification of the given category for the given step if it exists.

Arguments:

• step int | None - the step to get a clarification for. Defaults to current step.
• category ClarificationCategory | None - the category of the clarification to get.

get_potential_step_inputs

def get_potential_step_inputs() -> dict[str, Output]

Return a dictionary of potential step inputs for future steps.

__str__

def __str__() -> str

Return the string representation of the PlanRun.

Returns:

• str - A string representation containing key run attributes.

ReadOnlyPlanRun Objects

class ReadOnlyPlanRun(PlanRun)

A read-only copy of a Plan Run passed to agents for reference.

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

from_plan_run

@classmethod
def from_plan_run(cls, plan_run: PlanRun) -> ReadOnlyPlanRun

Create a read-only plan run from a normal PlanRun.

Arguments:

• plan_run PlanRun - The original run instance to create a read-only copy from.

Returns:

• ReadOnlyPlanRun - A new read-only instance of the provided PlanRun.