PtcRunner.Session (PtcRunner v0.12.0)

Copy Markdown View Source

Stateful PTC-Lisp session for embedding applications.

A session owns only the REPL state that PtcRunner.Lisp.run/2 already understands: explicit (def ...) memory and the bounded *1/*2/*3 turn history. Durable chat messages, user identity, persistence, and tool configuration stay with the embedding application. Runtime options can be stored as session defaults or passed per evaluation.

Examples

iex> session = PtcRunner.Session.new(timeout: 1_000)
iex> {{:ok, step}, session} = PtcRunner.Session.eval(session, "(def x 41)")
iex> step.memory["x"]
41
iex> {{:ok, step}, _session} = PtcRunner.Session.eval(session, "(inc x)")
iex> step.return
42

iex> session = PtcRunner.Session.new(history_depth: 2)
iex> {{:ok, _}, session} = PtcRunner.Session.eval(session, "1")
iex> {{:ok, _}, session} = PtcRunner.Session.eval(session, "2")
iex> {{:ok, step}, _session} = PtcRunner.Session.eval(session, "*1")
iex> step.return
2

Summary

Types

eval_result()

Result of eval/3: the normal PtcRunner.Lisp.run/2 result paired with the session state to use for the next turn.

t()

Functions

eval(session, source, opts \\ [])

Evaluate PTC-Lisp source with this session's memory and turn history.

new(opts \\ [])

Create a new stateful PTC-Lisp session.

Types

eval_result()

@type eval_result() :: {{:ok, PtcRunner.Step.t()} | {:error, PtcRunner.Step.t()}, t()}

Result of eval/3: the normal PtcRunner.Lisp.run/2 result paired with the session state to use for the next turn.

t()

@type t() :: %PtcRunner.Session{
  history_depth: non_neg_integer(),
  memory: map(),
  run_opts: keyword(),
  turn_history: [term()],
  upstream_runtime: struct() | pid() | nil
}

Functions

eval(session, source, opts \\ [])

@spec eval(t(), String.t(), keyword()) :: eval_result()

Evaluate PTC-Lisp source with this session's memory and turn history.

Session default options and per-call opts are passed through to PtcRunner.Lisp.run/2, then the session's :memory and :turn_history are applied. This lets embedding callers pass normal runtime options such as :tools, :context, :timeout, or upstream options while the session remains the owner of REPL state. If the session was created with :upstream_runtime, evaluation goes through PtcRunner.Upstream.Runtime.

On success, the returned session stores step.memory and appends step.return to the bounded history. On error, the returned session is the original session, preserving the prior memory and history.

new(opts \\ [])

@spec new(keyword()) :: t()

Create a new stateful PTC-Lisp session.

Options

  • :memory - initial Lisp memory map (default: %{})
  • :turn_history - initial result history, oldest first (default: [])
  • :history_depth - maximum stored result count for *1, *2, *3 references (default: 3)
  • :upstream_runtime - optional PtcRunner.Upstream.Runtime handle used to evaluate programs through configured upstream MCP/OpenAPI tools

Any other options are stored as default PtcRunner.Lisp.run/2 options and merged with per-eval options.