API Guide

Copy Markdown View Source

The public API is centered on four functions:

PromptRunner.plan/2
PromptRunner.validate/2
PromptRunner.run/2
PromptRunner.run_prompt/2

Input Shapes

PromptRunner.run/2 accepts:

  • a prompt directory
  • a legacy config path
  • a list of %PromptRunner.Prompt{}
  • a raw prompt string via run_prompt/2

Planning

{:ok, plan} =
  PromptRunner.plan("./prompts",
    target: "/path/to/repo",
    provider: :claude,
    model: "haiku"
  )

Useful fields on plan:

  • plan.prompts
  • plan.source
  • plan.runtime_store
  • plan.committer
  • plan.state_dir
  • plan.config

Running

{:ok, run} =
  PromptRunner.run("./prompts",
    target: "/path/to/repo",
    provider: :claude,
    model: "haiku"
  )

Single prompt:

{:ok, run} =
  PromptRunner.run_prompt(
    "Create hello.txt with a greeting.",
    target: "/path/to/repo",
    provider: :claude,
    model: "haiku"
  )

Defaults In API Mode

API mode defaults to:

  • in-memory runtime state
  • NoopCommitter
  • no implicit .prompt_runner/ directory

That makes it suitable for workers, web requests, and background jobs.

Observer Callbacks

Supported callbacks:

  • on_event
  • on_prompt_started
  • on_prompt_completed
  • on_prompt_failed
  • on_run_completed

Example:

{:ok, run} =
  PromptRunner.run("./prompts",
    target: "/repo",
    provider: :claude,
    model: "haiku",
    on_event: fn event -> IO.inspect(event.type) end
  )

Raw streaming events and PromptRunner lifecycle events are both delivered to on_event.

PubSub Bridge

callback = PromptRunner.Observer.PubSub.callback(MyApp.PubSub, "prompt_runner:runs")

{:ok, run} =
  PromptRunner.run("./prompts",
    target: "/repo",
    provider: :claude,
    model: "haiku",
    on_event: callback
  )

Explicit Prompt Structs

prompts = [
  %PromptRunner.Prompt{
    num: "01",
    phase: 1,
    sp: 3,
    name: "Schema",
    body: "Add the missing schema field.",
    commit_message: "feat: add missing schema field"
  }
]

{:ok, run} =
  PromptRunner.run(prompts,
    target: "/repo",
    provider: :claude,
    model: "haiku"
  )