PtcRunner.Turn (PtcRunner v0.5.1)

View Source

Captures a single LLM interaction cycle in a SubAgent execution.

Each turn represents one complete cycle: LLM generates program → program executes → results captured. Turns are immutable snapshots; once created, they are never modified.

Fields

  • number - Turn sequence number (1-indexed)
  • raw_response - Full LLM output including reasoning (always captured per ARC-010)
  • program - Parsed PTC-Lisp program, or nil if parsing failed
  • result - Execution result value
  • prints - Captured println output
  • tool_calls - Tool invocations made during this turn
  • memory - Accumulated definitions after this turn
  • success? - Whether the turn succeeded
  • messages - Messages sent to the LLM for this turn (for debugging/verification)

Constructors

Use success/7 or failure/7 to create turns - don't construct the struct directly. The constructors ensure success? is set correctly.

Summary

Types

message()

A message sent to the LLM.

t()

Turn struct capturing one LLM interaction cycle.

tool_call()

A single tool invocation during a turn.

Functions

failure(number, raw_response, program, error, prints, tool_calls, memory, messages \\ nil)

Creates a failed turn.

success(number, raw_response, program, result, prints, tool_calls, memory, messages \\ nil)

Creates a successful turn.

Types

message()

@type message() :: %{role: :system | :user | :assistant, content: String.t()}

A message sent to the LLM.

Fields:

  • role: Message role (:system, :user, or :assistant)
  • content: Message content

t()

@type t() :: %PtcRunner.Turn{
  memory: map(),
  messages: [message()] | nil,
  number: pos_integer(),
  prints: [String.t()],
  program: String.t() | nil,
  raw_response: String.t(),
  result: term(),
  success?: boolean(),
  tool_calls: [tool_call()]
}

Turn struct capturing one LLM interaction cycle.

One of success? will be true or false:

  • Success: Turn executed without errors
  • Failure: Turn encountered an error (result contains error info)

tool_call()

@type tool_call() :: %{name: String.t(), args: map(), result: term()}

A single tool invocation during a turn.

Fields:

  • name: Tool name that was called
  • args: Arguments passed to the tool
  • result: Value returned by the tool

Functions

failure(number, raw_response, program, error, prints, tool_calls, memory, messages \\ nil)

@spec failure(
  pos_integer(),
  String.t(),
  String.t() | nil,
  term(),
  [String.t()],
  [tool_call()],
  map(),
  [message()] | nil
) :: t()

Creates a failed turn.

The error parameter contains error information (typically a map with :reason and :message).

Examples

iex> turn = PtcRunner.Turn.failure(2, "```ptc-lisp\n(/ 1 0)\n```", "(/ 1 0)", %{reason: :eval_error, message: "division by zero"}, [], [], %{x: 10})
iex> turn.success?
false
iex> turn.result
%{reason: :eval_error, message: "division by zero"}
iex> turn.memory
%{x: 10}

success(number, raw_response, program, result, prints, tool_calls, memory, messages \\ nil)

@spec success(
  pos_integer(),
  String.t(),
  String.t() | nil,
  term(),
  [String.t()],
  [tool_call()],
  map(),
  [message()] | nil
) :: t()

Creates a successful turn.

Examples

iex> turn = PtcRunner.Turn.success(1, "```ptc-lisp\n(+ 1 2)\n```", "(+ 1 2)", 3, [], [], %{})
iex> turn.success?
true
iex> turn.number
1
iex> turn.result
3