PtcRunner (PtcRunner v0.2.0)

View Source

A BEAM-native Programmatic Tool Calling (PTC) runner.

PtcRunner enables LLMs to write safe programs that orchestrate tools and transform data inside a sandboxed environment.

Examples

iex> program = ~s({"program": {"op": "literal", "value": 42}})
iex> {:ok, result, _metrics} = PtcRunner.run(program)
iex> result
42

Summary

Types

error()

Error types returned by PtcRunner operations.

metrics()

Execution metrics for a program run.

Functions

format_error(other)

Formats an error into a human-readable message suitable for LLM feedback.

run(program, opts \\ [])

Runs a PTC program and returns the result with metrics.

run!(program, opts \\ [])

Runs a PTC program, raising on error.

Types

error()

@type error() ::
  {:parse_error, String.t()}
  | {:validation_error, String.t()}
  | {:execution_error, String.t()}
  | {:timeout, non_neg_integer()}
  | {:memory_exceeded, non_neg_integer()}

Error types returned by PtcRunner operations.

metrics()

@type metrics() :: %{duration_ms: integer(), memory_bytes: integer()}

Execution metrics for a program run.

Functions

format_error(other)

@spec format_error(error() | any()) :: String.t()

Formats an error into a human-readable message suitable for LLM feedback.

This function converts internal error tuples into clear, actionable messages that help LLMs understand what went wrong and how to fix their programs.

Examples

iex> PtcRunner.format_error({:parse_error, "unexpected token"})
"ParseError: unexpected token"

iex> PtcRunner.format_error({:validation_error, "unknown operation"})
"ValidationError: unknown operation"

run(program, opts \\ [])

@spec run(
  String.t() | map(),
  keyword()
) :: {:ok, any(), metrics()} | {:error, error()}

Runs a PTC program and returns the result with metrics.

Arguments

  • program: JSON string or parsed map representing the program
  • opts: Execution options

Options

  • :context - Map of pre-bound variables (default: %{})
  • :tools - Tool registry (default: %{})
  • :timeout - Timeout in milliseconds (default: 1000)
  • :max_heap - Max heap size in words (default: 1_250_000)

Returns

  • {:ok, result, metrics} on success
  • {:error, reason} on failure

Examples

iex> {:ok, result, _metrics} = PtcRunner.run(~s({"program": {"op": "literal", "value": 42}}))
iex> result
42

run!(program, opts \\ [])

@spec run!(
  String.t() | map(),
  keyword()
) :: any()

Runs a PTC program, raising on error.

Arguments

  • program: JSON string or parsed map representing the program
  • opts: Execution options (same as run/2)

Returns

  • The result value (metrics are discarded)

Raises

  • Raises an error if parsing, validation, or execution fails

Examples

iex> result = PtcRunner.run!(~s({"program": {"op": "literal", "value": 42}}))
iex> result
42