PtcRunner.Json (PtcRunner v0.4.1)

View Source

Execute PTC programs written in JSON DSL.

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

See the PTC-JSON Specification for the complete DSL reference.

Tool Registration

Tools are functions that receive a map of arguments and return results:

tools = %{
  "get_user" => fn %{"id" => id} -> MyApp.Users.get(id) end,
  "search" => fn %{"query" => q, "limit" => n} -> MyApp.Search.run(q, limit: n) end
}

PtcRunner.Json.run(program, tools: tools)

Contract:

  • Receives: map() of arguments (may be empty %{})
  • Returns: Any Elixir term (maps, lists, primitives)
  • Should not raise (return {:error, reason} for errors)

Error Handling

Use format_error/1 to convert errors into LLM-friendly messages:

case PtcRunner.Json.run(program, tools: tools) do
  {:ok, result, _, _} -> handle_success(result)
  {:error, error} -> retry_with_feedback(format_error(error))
end

Examples

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

Summary

Types

error()

Error types returned by PtcRunner.Json 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 and memory.

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.Json 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.Json.format_error({:parse_error, "unexpected token"})
"ParseError: unexpected token"

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

run(program, opts \\ [])

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

Runs a PTC program and returns the result with metrics and memory.

Arguments

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

Options

  • :context - Map of external context data (default: %{})
  • :memory - Map of initial memory state (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, memory_delta, new_memory} on success
  • {:error, reason} on failure

The return format follows the memory contract:

  • If result is not a map: memory_delta is empty, new_memory is unchanged
  • If result is a map with "result" key: "result" value is returned, other keys merged to memory
  • If result is a map with :result key: :result value is returned, other keys merged to memory
  • If result is a map without "result" or :result: result is returned as-is, merged to memory

Examples

iex> {:ok, result, _memory_delta, _new_memory} = PtcRunner.Json.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 (memory is discarded)

Raises

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

Examples

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