BeamAgent.Artifacts (beam_agent_ex v0.1.0)

Copy Markdown View Source

Canonical artifact and context store for BeamAgent.

Artifacts are durable runtime outputs such as plans, diffs, reviews, summaries, approval packets, benchmark reports, and transcript snapshots. They are stored independently of live session processes and can be linked to sessions, threads, runs, and other typed references.

This is the Elixir facade over the Erlang :beam_agent_artifacts public module. The implementation is ETS-backed and process-free, following the same BeamAgent pattern used by the runs and control stores.

Summary

Types

artifact()

Canonical artifact record.

artifact_filter()

Exact-match filter accepted by list/1 and search/2.

artifact_input()

Input map accepted by put/1,2.

scope()

Scope passed to put/2.

source_ref()

Source reference stored on an artifact.

Functions

attach(artifact_id, ref_type, ref_id)

Attach a typed source reference to an existing artifact.

clear()

Clear all artifacts.

delete(artifact_id)

Delete an artifact by id.

ensure_tables()

Ensure the artifacts ETS table exists.

get(artifact_id)

Fetch an artifact by id.

list()

List all artifacts without filters.

list(filter)

List artifacts with exact-match filters.

put(artifact)

Insert or update an artifact using embedded scope.

put(scope, artifact)

Insert or update an artifact with explicit scope.

search(query)

Search artifacts with a case-insensitive tokenized query.

search(query, filter)

Search artifacts with a query plus exact-match filters.

Types

artifact()

@type artifact() :: %{
  :artifact_id => binary(),
  :kind => atom() | binary(),
  :title => binary(),
  :body => term(),
  :format => atom() | binary(),
  :source_refs => [source_ref()],
  :metadata => map(),
  :created_at => integer(),
  :updated_at => integer(),
  optional(:session_id) => binary(),
  optional(:thread_id) => binary(),
  optional(:run_id) => binary()
}

Canonical artifact record.

artifact_filter()

@type artifact_filter() :: %{
  optional(:artifact_id) => binary(),
  optional(:kind) => atom() | binary(),
  optional(:format) => atom() | binary(),
  optional(:title) => binary(),
  optional(:session_id) => binary(),
  optional(:thread_id) => binary(),
  optional(:run_id) => binary(),
  optional(:source_ref_type) => atom() | binary(),
  optional(:source_ref_id) => binary(),
  optional(:limit) => pos_integer(),
  optional(:since) => integer()
}

Exact-match filter accepted by list/1 and search/2.

artifact_input()

@type artifact_input() :: %{
  optional(:artifact_id) => binary(),
  optional(:kind) => atom() | binary(),
  optional(:title) => binary(),
  optional(:body) => term(),
  optional(:format) => atom() | binary(),
  optional(:source_refs) => [source_ref()],
  optional(:metadata) => map(),
  optional(:session_id) => binary(),
  optional(:thread_id) => binary(),
  optional(:run_id) => binary()
}

Input map accepted by put/1,2.

scope()

@type scope() ::
  binary()
  | %{
      optional(:session_id) => binary(),
      optional(:thread_id) => binary(),
      optional(:run_id) => binary()
    }

Scope passed to put/2.

Use either a binary session id or a map containing any of :session_id, :thread_id, and :run_id.

source_ref()

@type source_ref() :: %{
  :type => atom() | binary(),
  :id => binary(),
  optional(:metadata) => map()
}

Source reference stored on an artifact.

Functions

attach(artifact_id, ref_type, ref_id)

@spec attach(binary(), atom() | binary(), binary()) ::
  :ok
  | {:error,
     :inconsistent_run_scope
     | :inconsistent_scope
     | :not_found
     | :run_not_found
     | :session_id_required_for_thread}

Attach a typed source reference to an existing artifact.

clear()

@spec clear() :: :ok

Clear all artifacts.

delete(artifact_id)

@spec delete(binary()) :: :ok | {:error, :not_found}

Delete an artifact by id.

ensure_tables()

@spec ensure_tables() :: :ok

Ensure the artifacts ETS table exists.

get(artifact_id)

@spec get(binary()) :: {:ok, artifact()} | {:error, :not_found}

Fetch an artifact by id.

list()

@spec list() :: {:ok, [artifact()]}

List all artifacts without filters.

list(filter)

@spec list(artifact_filter()) :: {:ok, [artifact()]} | {:error, term()}

List artifacts with exact-match filters.

put(artifact)

@spec put(artifact_input()) :: {:ok, artifact()} | {:error, term()}

Insert or update an artifact using embedded scope.

put(scope, artifact)

@spec put(scope(), artifact_input()) :: {:ok, artifact()} | {:error, term()}

Insert or update an artifact with explicit scope.

search(query)

@spec search(binary()) :: {:ok, [artifact()]}

Search artifacts with a case-insensitive tokenized query.

search(query, filter)

@spec search(binary(), artifact_filter()) :: {:ok, [artifact()]} | {:error, term()}

Search artifacts with a query plus exact-match filters.