PtcRunner.Lisp.Eval.Context (PtcRunner v0.5.1)

View Source

Evaluation context for the Lisp interpreter.

Bundles the parameters that flow through recursive evaluation:

  • ctx: External data (read-only)
  • user_ns: User namespace (mutable bindings from def)
  • env: Lexical environment (variable bindings)
  • tool_exec: Tool executor function
  • turn_history: Previous turn results for multi-turn loops

Limits

FieldDefaultHard CapPurpose
loop_limit1,00010,000Max loop/recursion iterations
max_print_length2,000—Max chars per println call

Summary

Types

t()
tool_call()

Tool call record for tracing.

Functions

append_print(context, message)

Appends a print message to the context.

append_tool_call(context, tool_call)

Appends a tool call record to the context.

increment_iteration(context)

Increments the iteration count and checks against the limit.

merge(ctx1, ctx2)

Merges two contexts, specifically combining prints and tool calls. Used to merge results from parallel execution branches (pmap, pcalls).

merge_env(context, bindings)

Merges new bindings into the environment.

new(ctx, user_ns, env, tool_exec, turn_history, opts \\ [])

Creates a new evaluation context.

set_loop_limit(context, new_limit)

Sets a new loop limit, respecting the hard maximum.

update_user_ns(context, new_user_ns)

Updates the user namespace in the context.

Types

t()

@type t() :: %PtcRunner.Lisp.Eval.Context{
  ctx: map(),
  env: map(),
  iteration_count: integer(),
  loop_limit: integer(),
  max_print_length: pos_integer(),
  prints: [String.t()],
  tool_calls: [tool_call()],
  tool_exec: (String.t(), map() -> term()),
  turn_history: list(),
  user_ns: map()
}

tool_call()

@type tool_call() :: %{
  name: String.t(),
  args: map(),
  result: term(),
  error: String.t() | nil,
  timestamp: DateTime.t(),
  duration_ms: non_neg_integer()
}

Tool call record for tracing.

Fields:

  • name: Tool name
  • args: Arguments passed to tool
  • result: Tool result
  • error: Error message if tool failed
  • timestamp: When tool was called
  • duration_ms: How long tool took

Functions

append_print(context, message)

@spec append_print(t(), String.t()) :: t()

Appends a print message to the context.

Long messages are truncated to max_print_length characters (default: 2000).

append_tool_call(context, tool_call)

@spec append_tool_call(t(), tool_call()) :: t()

Appends a tool call record to the context.

increment_iteration(context)

@spec increment_iteration(t()) :: {:ok, t()} | {:error, :loop_limit_exceeded}

Increments the iteration count and checks against the limit.

merge(ctx1, ctx2)

@spec merge(t(), t()) :: t()

Merges two contexts, specifically combining prints and tool calls. Used to merge results from parallel execution branches (pmap, pcalls).

merge_env(context, bindings)

@spec merge_env(t(), map()) :: t()

Merges new bindings into the environment.

new(ctx, user_ns, env, tool_exec, turn_history, opts \\ [])

@spec new(map(), map(), map(), (String.t(), map() -> term()), list(), keyword()) ::
  t()

Creates a new evaluation context.

Options

  • :max_print_length - Max characters per println call (default: 2000)

Examples

iex> ctx = PtcRunner.Lisp.Eval.Context.new(%{}, %{}, %{}, fn _, _ -> nil end, [])
iex> ctx.user_ns
%{}

iex> ctx = PtcRunner.Lisp.Eval.Context.new(%{}, %{}, %{}, fn _, _ -> nil end, [], max_print_length: 500)
iex> ctx.max_print_length
500

set_loop_limit(context, new_limit)

@spec set_loop_limit(t(), integer()) :: t()

Sets a new loop limit, respecting the hard maximum.

update_user_ns(context, new_user_ns)

@spec update_user_ns(t(), map()) :: t()

Updates the user namespace in the context.