LemonCore.Introspection (lemon_core v0.1.0)

View Source

Canonical introspection event API.

Events are persisted through LemonCore.IntrospectionStore in :introspection_log with the following contract:

  • :event_id - stable unique identifier
  • :event_type - event taxonomy name
  • :ts_ms - wall clock timestamp in milliseconds
  • :run_id - run identifier when available
  • :session_key - session identifier when available
  • :agent_id - agent identifier when available
  • :parent_run_id - lineage link when available
  • :engine - engine name when available

  • :provenance - :direct | :inferred | :unavailable

  • :payload - redacted event-specific metadata

Redaction Defaults

  • Prompt/response and obvious secret fields are removed.
  • Tool argument payloads are redacted by default (capture_tool_args: false).
  • Result previews are kept by default and truncated.

Summary

Types

event()
provenance()

Functions

build_event(event_type, payload, opts \\ [])

Build a canonical introspection event without persisting it.

enabled?()

Returns whether persistence is currently enabled.

list(opts \\ [])

List introspection events through the store query API.

record(event_type, payload \\ %{}, opts \\ [])

Build and persist an introspection event.

Types

event()

@type event() :: %{
  :event_id => binary(),
  :event_type => atom() | binary(),
  :ts_ms => non_neg_integer(),
  :provenance => provenance(),
  :payload => map(),
  optional(:run_id) => binary() | nil,
  optional(:session_key) => binary() | nil,
  optional(:agent_id) => binary() | nil,
  optional(:parent_run_id) => binary() | nil,
  optional(:engine) => binary() | nil
}

provenance()

@type provenance() :: :direct | :inferred | :unavailable

Functions

build_event(event_type, payload, opts \\ [])

@spec build_event(atom() | binary(), map(), keyword()) ::
  {:ok, event()} | {:error, term()}

Build a canonical introspection event without persisting it.

enabled?()

@spec enabled?() :: boolean()

Returns whether persistence is currently enabled.

list(opts \\ [])

@spec list(keyword()) :: [event()]

List introspection events through the store query API.

record(event_type, payload \\ %{}, opts \\ [])

@spec record(atom() | binary(), map(), keyword()) :: :ok | {:error, term()}

Build and persist an introspection event.