Dsxir.History (dsxir v0.1.0)

ETS-backed inspect_history developer tool.

Supervised owner of the :dsxir_history ETS table. Creates the table at boot and holds it for the lifetime of the application; a telemetry handler attached via enable/0 writes entries on [:dsxir, :predictor, :stop].

The handler runs in the calling process (telemetry's design), so the GenServer never becomes a write bottleneck. Inserts use a monotonic unique integer key in an :ordered_set ETS table so the newest entry is always :ets.last/1.

Trim is driven by an :atomics-backed :counters reference. On every insert the counter is incremented; once it exceeds max_history_size + trim_batch_size any caller may attempt a trim of the oldest trim_batch_size rows. Trim is race-tolerant: deletes are idempotent, so concurrent attempts cannot corrupt the table. Transient overshoot of up to trim_batch_size rows is acceptable.

Configuration via Application.get_env(:dsxir, Dsxir.History, []):

:max_history_size (default 10_000)
:trim_batch_size (default 256)

Distinct from the multi-turn conversation value type Dsxir.Primitives.History (added separately by its own consumer). The name overlap is deliberate — each matches its DSPy counterpart (dspy.inspect_history debug helper vs. dspy.History value type).

Summary

Types

t()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

disable()

Detaches the telemetry handler. Idempotent.

enable()

Attaches the telemetry handler to [:dsxir, :predictor, :stop]. Idempotent — calling again replaces the existing attachment with the current configuration.

last(n)

Returns the last n entries, newest first.

last(n, opts)

Returns the last n entries, newest first.

start_link(opts \\ [])

Start the history owner as a named singleton.

table()

Returns the ETS table identifier for the dev-tool table. Stable across calls.

Types

t()

@type t() :: %Dsxir.History{
  counter_ref: :counters.counters_ref(),
  max_size: pos_integer(),
  trim_batch: pos_integer()
}

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

disable()

@spec disable() :: :ok

Detaches the telemetry handler. Idempotent.

enable()

@spec enable() :: :ok

Attaches the telemetry handler to [:dsxir, :predictor, :stop]. Idempotent — calling again replaces the existing attachment with the current configuration.

last(n)

@spec last(non_neg_integer()) :: [map()]

Returns the last n entries, newest first.

last(n, opts)

@spec last(
  non_neg_integer(),
  keyword()
) :: [map()]

Returns the last n entries, newest first.

When :file is supplied the rows are also written to disk as one JSON-encoded entry per line. The prediction field is rendered via inspect/1 so structs containing functions or PIDs do not break encoding.

start_link(opts \\ [])

@spec start_link(keyword()) :: GenServer.on_start()

Start the history owner as a named singleton.

table()

@spec table() :: atom()

Returns the ETS table identifier for the dev-tool table. Stable across calls.