PromptRunner (PromptRunnerSDK v0.12.1)

Copy Markdown View Source

Public API for building plans and executing prompt runs.

Summary

Functions

plan(input, opts \\ [])
preflight(input, opts \\ [])
repair(input, opts \\ [])
run(input, opts \\ [])

Builds a plan from input and runs it.

run_prompt(prompt_text, opts \\ [])
scaffold(input, opts \\ [])
status(input)
validate(input, opts \\ [])
version()

Returns the Prompt Runner version.

Functions

plan(input, opts \\ [])

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

preflight(input, opts \\ [])

@spec preflight(
  term(),
  keyword()
) :: {:ok, map()} | {:error, term()}

repair(input, opts \\ [])

@spec repair(
  term(),
  keyword()
) :: {:ok, PromptRunner.Run.t()} | {:error, term()}

run(input, opts \\ [])

@spec run(
  term(),
  keyword()
) :: {:ok, PromptRunner.Run.t()} | {:error, term()}

Builds a plan from input and runs it.

Selecting what runs

Exactly one of these decides the targets; the first that applies wins.

  • prompts: ["02", "03"] — run exactly these, in this order. An id naming no prompt is an error rather than a shorter run.
  • phase: 2 — run one phase
  • remaining: true — run every prompt whose recorded status is not completed, in order, including prompts earlier than the furthest one that finished. A prompt with no record is remaining. A missing progress store means a new run; an existing unreadable or malformed store is an error rather than permission to re-run the packet.
  • continue: true — resume from last_completed + 1. This steps over an earlier prompt that failed or never ran; when it does, the skipped prompts are named.
  • all: true — run everything

Pre-flight verification

verify_first: true evaluates a prompt's verify contract before invoking the provider and, if it already passes, marks the prompt completed with no session and records that no session ran. It defaults on under remaining: true and off for explicitly named prompts, since naming a prompt is a request to run it. A contract with no evaluable clause, and one containing changed_paths_only, are never pre-flighted — both would pass vacuously.

keep_going: true records prompt-local errors, attempts the rest of the selected prompts, and returns all failures at the end. The default remains fail-fast for dependent prompt chains.

run_prompt(prompt_text, opts \\ [])

@spec run_prompt(
  String.t(),
  keyword()
) :: {:ok, PromptRunner.Run.t()} | {:error, term()}

scaffold(input, opts \\ [])

@spec scaffold(
  term(),
  keyword()
) :: {:ok, map()} | {:error, term()}

status(input)

@spec status(term()) :: {:ok, map()} | {:error, term()}

validate(input, opts \\ [])

@spec validate(
  term(),
  keyword()
) :: :ok | {:error, term()}

version()

@spec version() :: String.t()

Returns the Prompt Runner version.

This is the single source of truth for every version string Prompt Runner emits, including the CLI banner, generated packet manifests, and the run_prompts.exs install entry.