PtcRunner.MetaPlanner (PtcRunner v0.7.0)

Generate and repair execution plans for multi-agent workflows.

The MetaPlanner is responsible for:

Generating initial plans from mission descriptions
Repairing plans when tasks fail with :replan strategy

Initial Planning

Generate a plan from a natural language mission:

{:ok, plan} = MetaPlanner.plan("Research AAPL stock price and write a summary",
  llm: my_llm,
  available_tools: %{
    "search" => "Search the web for information",
    "fetch_price" => "Fetch current stock price for a symbol. Returns {price, currency}",
    "summarize" => "Summarize a list of documents into key points"
  }
)

Replanning (Tail Repair)

When a task fails verification with on_verification_failure: :replan, the MetaPlanner generates a "repair plan" that:

Preserves completed task IDs (so PlanRunner skips them)
Redesigns the failed task based on the diagnosis
May restructure downstream tasks

Example:

# Original execution failed at task "fetch_prices"
failure_context = %{
  task_id: "fetch_prices",
  task_output: %{"prices" => []},
  diagnosis: "Expected at least 5 price entries, got 0"
}

{:ok, repair_plan} = MetaPlanner.replan(
  "Compare stock prices for AAPL, GOOGL, MSFT",
  %{"fetch_symbols" => ["AAPL", "GOOGL", "MSFT"]},
  failure_context,
  llm: my_llm
)

# Execute repair plan with initial_results to skip completed tasks
PlanRunner.execute(repair_plan,
  llm: my_llm,
  initial_results: %{"fetch_symbols" => ["AAPL", "GOOGL", "MSFT"]}
)

Summary

Types

failure_context()

tool_descriptions()

Functions

format_trial_history(history)

Format trial history for inclusion in the replan prompt.

plan(mission, opts)

Generate an execution plan from a natural language mission.

replan(mission, completed_results, failure_context, opts)

Generate a repair plan after a task fails verification.

Types

failure_context()

@type failure_context() :: %{
  task_id: String.t(),
  task_output: term(),
  diagnosis: String.t()
}

tool_descriptions()

@type tool_descriptions() :: %{required(String.t()) => String.t()}

Functions

format_trial_history(history)

@spec format_trial_history([map()]) :: String.t()

Format trial history for inclusion in the replan prompt.

Returns an empty string for empty history, otherwise formats each attempt with approach, output, and diagnosis details plus a self-reflection section.

plan(mission, opts)

@spec plan(
  String.t(),
  keyword()
) :: {:ok, PtcRunner.Plan.t()} | {:error, term()}

Generate an execution plan from a natural language mission.

Takes a mission description and available tools, then generates a structured plan that can be executed by PlanRunner.

Parameters

mission - Natural language description of what to accomplish
opts - Options including :llm callback (required)

Options

llm - Required. LLM callback function
available_tools - Map of tool_name => description (recommended)
timeout - Timeout for plan generation (default: 30_000)
constraints - Optional string with additional constraints or guidelines
validation_errors - Optional. List of validation issues from a previous attempt (for self-correction)

Returns

{:ok, plan} - Parsed execution plan
{:error, reason} - Generation or parsing failed

Example

{:ok, plan} = MetaPlanner.plan("Research AAPL stock and summarize findings",
  llm: my_llm,
  available_tools: %{
    "search" => "Search the web. Input: query string. Output: list of results",
    "fetch_price" => "Get stock price. Input: symbol. Output: {price, change}",
    "summarize" => "Summarize text. Input: text. Output: summary string"
  }
)

replan(mission, completed_results, failure_context, opts)

@spec replan(String.t(), map(), failure_context(), keyword()) ::
  {:ok, PtcRunner.Plan.t()} | {:error, term()}

Generate a repair plan after a task fails verification.

The repair plan includes all task IDs (including completed ones) so that PlanRunner can use the initial_results option to skip already-completed tasks.

Parameters

mission - Original mission description
completed_results - Map of task_id => result for successful tasks
failure_context - Details about the failed task
opts - Options including :llm callback (required)

Options

llm - Required. LLM callback function
timeout - Timeout for plan generation (default: 30_000)
original_plan - Optional. The original plan that failed (for context)
constraints - Optional. Planning constraints to preserve during replanning
validation_errors - Optional. List of validation issues from a previous repair attempt

Returns

{:ok, plan} - Parsed repair plan
{:error, reason} - Generation or parsing failed