ExAgent.Store behaviour (ExAgent v0.4.0)

Copy Markdown View Source

Behaviour for persisting ExAgent.Server.Snapshots (and, in Phase 3, session snapshots).

ExAgent never owns a database: the store is a pluggable behaviour. The default ExAgent.Store.ETS keeps snapshots in an in-process ETS table (dev/test); a future ExAgent.Store.Postgres will implement the same contract for durable, multi-node persistence.

The contract (what a store must do)

Portability rule

Implementations MUST round-trip snapshots through a portable encoding (JSON for the ETS impl), never term_to_binary of arbitrary terms. This guarantees the same data can land in Postgres later without redesign, and refuses to persist non-serializable state (pids, secrets, closures).

A store is referenced as {module, config} where config is opaque to ExAgent (e.g. an ETS table name). normalize/1 turns friendly forms into that tuple; nil means "no store" (the default — one-shot friendly).

Summary

Types

agent_snapshot()
session_snapshot()

Callbacks

delete_agent_snapshot(config, agent_id)

Delete an agent snapshot by agent_id.

delete_session_snapshot(config, session_id)

Delete a session snapshot by session_id (Phase 3).

list_agent_snapshots(config)

List every persisted agent snapshot.

load_agent_snapshot(config, agent_id)

Load an agent snapshot by agent_id, or {:error, :not_found}.

load_session_snapshot(config, session_id)

Load a session snapshot by session_id (Phase 3).

save_agent_snapshot(config, snapshot)

Persist an agent snapshot, keyed by its agent_id.

save_session_snapshot(config, snapshot)

Persist a session snapshot, keyed by session_id (Phase 3).

Functions

delete_agent_snapshot(arg, agent_id)

Delete an agent snapshot via the resolved tuple.

list_agent_snapshots(arg)

List agent snapshots via the resolved tuple.

load_agent_snapshot(arg, agent_id)

Load an agent snapshot via the resolved tuple.

normalize(mod)

Resolve a store option into a {module, config} tuple, or nil for "no store".

save_agent_snapshot(arg, snapshot)

Persist an agent snapshot via the resolved {module, config} tuple.

Types

agent_snapshot()

@type agent_snapshot() :: ExAgent.Server.Snapshot.t()

session_snapshot()

@type session_snapshot() :: term()

Callbacks

delete_agent_snapshot(config, agent_id)

@callback delete_agent_snapshot(config :: term(), agent_id :: String.t()) :: :ok

Delete an agent snapshot by agent_id.

delete_session_snapshot(config, session_id)

(optional) 
@callback delete_session_snapshot(config :: term(), session_id :: String.t()) :: :ok

Delete a session snapshot by session_id (Phase 3).

list_agent_snapshots(config)

@callback list_agent_snapshots(config :: term()) :: [agent_snapshot()]

List every persisted agent snapshot.

load_agent_snapshot(config, agent_id)

@callback load_agent_snapshot(config :: term(), agent_id :: String.t()) ::
  {:ok, agent_snapshot()} | {:error, :not_found | term()}

Load an agent snapshot by agent_id, or {:error, :not_found}.

load_session_snapshot(config, session_id)

(optional) 
@callback load_session_snapshot(config :: term(), session_id :: String.t()) ::
  {:ok, session_snapshot()} | {:error, :not_found | term()}

Load a session snapshot by session_id (Phase 3).

save_agent_snapshot(config, snapshot)

@callback save_agent_snapshot(config :: term(), snapshot :: agent_snapshot()) ::
  :ok | {:error, term()}

Persist an agent snapshot, keyed by its agent_id.

save_session_snapshot(config, snapshot)

(optional) 
@callback save_session_snapshot(config :: term(), snapshot :: session_snapshot()) ::
  :ok | {:error, term()}

Persist a session snapshot, keyed by session_id (Phase 3).

Functions

delete_agent_snapshot(arg, agent_id)

@spec delete_agent_snapshot(
  {module(), term()},
  String.t()
) :: :ok

Delete an agent snapshot via the resolved tuple.

list_agent_snapshots(arg)

@spec list_agent_snapshots({module(), term()}) :: [ExAgent.Server.Snapshot.t()]

List agent snapshots via the resolved tuple.

load_agent_snapshot(arg, agent_id)

@spec load_agent_snapshot(
  {module(), term()},
  String.t()
) :: {:ok, ExAgent.Server.Snapshot.t()} | {:error, term()}

Load an agent snapshot via the resolved tuple.

normalize(mod)

@spec normalize(term()) :: {module(), term()} | nil

Resolve a store option into a {module, config} tuple, or nil for "no store".

  • nil → nil (no persistence — default).
  • :ets → {ExAgent.Store.ETS, ExAgent.Store.ETS} (default table).
  • {mod, cfg} → as-is.
  • mod → {mod, []}.

save_agent_snapshot(arg, snapshot)

@spec save_agent_snapshot(
  {module(), term()},
  ExAgent.Server.Snapshot.t()
) :: :ok | {:error, term()}

Persist an agent snapshot via the resolved {module, config} tuple.