Jido.Action.Catalog (Jido Action v2.3.0)

A plain value-level catalog of local action-compatible modules.

This is intentionally not a process-backed registry. It gives callers a small, serializable structure for collecting action metadata and doing deterministic, LLM-free lookup and search.

Catalog entries point at local compiled modules. A module is action-compatible when it exports name/0, schema/0, and run/2; it does not have to depend on this package's use Jido.Action macro.

The catalog does not execute selected entries. Callers should route execution through their own runtime policy, such as Jido.Exec, Jido.Action.Tool, or a higher-level package.

Examples

{:ok, catalog} =
  Jido.Action.Catalog.from_modules(
    [MyApp.Actions.SearchUsers],
    id: "app-actions"
  )

{:ok, hits} = Jido.Action.Catalog.search(catalog, "users")
[%Jido.Action.Catalog.Hit{} | _] = hits

Summary

Functions

fetch(catalog, id_or_name)

Fetches an entry by id or unique action name.

fetch!(catalog, id_or_name)

Same as fetch/2, but raises on error.

from_modules(modules, attrs \\ [])

Builds a catalog from action modules.

from_modules!(modules, attrs \\ [])

Same as from_modules/2, but raises on error.

list(catalog)

Returns entries sorted by action name and id.

merge(left, right, attrs \\ [])

Merges two catalogs into a canonical catalog.

merge!(left, right, attrs \\ [])

Same as merge/3, but raises on error.

new(attrs \\ %{})

Builds an empty catalog.

new!(attrs \\ %{})

Same as new/1, but raises on error.

Registers an action module or prebuilt entry in a catalog.

Same as register/3, but raises on error.

schema()

Returns the Zoi schema used to validate catalogs.

search(catalog, query_or_attrs)

Searches entries with deterministic lexical scoring.

search!(catalog, query_or_attrs)

Same as search/2, but raises on error.

unregister(catalog, entry)

Removes an entry by id, unique action name, or entry value.

Types

entry_ref()

@type entry_ref() :: String.t() | Jido.Action.Catalog.Entry.t()

merge_attrs()

@type merge_attrs() :: map() | keyword()

t()

@type t() :: %Jido.Action.Catalog{
  description: binary(),
  entries: map(),
  id: binary(),
  metadata: map(),
  name: nil | binary(),
  version: nil | binary()
}

Functions

fetch(catalog, id_or_name)

@spec fetch(t(), String.t()) ::
  {:ok, Jido.Action.Catalog.Entry.t()} | {:error, term()}

Fetches an entry by id or unique action name.

fetch!(catalog, id_or_name)

@spec fetch!(t(), String.t()) :: Jido.Action.Catalog.Entry.t() | no_return()

Same as fetch/2, but raises on error.

from_modules(modules, attrs \\ [])

@spec from_modules([module()], map() | keyword()) ::
  {:ok, t()} | {:error, Exception.t()}

Builds a catalog from action modules.

from_modules!(modules, attrs \\ [])

@spec from_modules!([module()], map() | keyword()) :: t() | no_return()

Same as from_modules/2, but raises on error.

list(catalog)

@spec list(t()) :: [Jido.Action.Catalog.Entry.t()]

Returns entries sorted by action name and id.

merge(left, right, attrs \\ [])

@spec merge(t(), t(), merge_attrs()) :: {:ok, t()} | {:error, Exception.t()}

Merges two catalogs into a canonical catalog.

Entry ids are the merge key. Duplicate ids are accepted only when both entries are exactly equal; conflicting entries return an error instead of choosing a side. When no :id is supplied, the merged catalog id is deterministically derived from the sorted merged entry ids, making compatible merges order-independent and idempotent.

Optional attributes such as :id, :name, :description, :version, and :metadata are applied to the merged catalog. The merged entries always come from the input catalogs.

merge!(left, right, attrs \\ [])

@spec merge!(t(), t(), merge_attrs()) :: t() | no_return()

Same as merge/3, but raises on error.

new(attrs \\ %{})

@spec new(map() | keyword()) :: {:ok, t()} | {:error, Exception.t()}

Builds an empty catalog.

new!(attrs \\ %{})

@spec new!(map() | keyword()) :: t() | no_return()

Same as new/1, but raises on error.

register(catalog, entry, overrides \\ [])

@spec register(t(), module() | Jido.Action.Catalog.Entry.t(), map() | keyword()) ::
  {:ok, t()} | {:error, Exception.t()}

Registers an action module or prebuilt entry in a catalog.

register!(catalog, entry, overrides \\ [])

@spec register!(t(), module() | Jido.Action.Catalog.Entry.t(), map() | keyword()) ::
  t() | no_return()

Same as register/3, but raises on error.

schema()

@spec schema() :: term()

Returns the Zoi schema used to validate catalogs.

search(catalog, query_or_attrs)

@spec search(t(), Jido.Action.Catalog.Query.t() | map() | keyword() | String.t()) ::
  {:ok, [Jido.Action.Catalog.Hit.t()]} | {:error, Exception.t()}

Searches entries with deterministic lexical scoring.

search!(catalog, query_or_attrs)

@spec search!(t(), Jido.Action.Catalog.Query.t() | map() | keyword() | String.t()) ::
  [Jido.Action.Catalog.Hit.t()] | no_return()

Same as search/2, but raises on error.

unregister(catalog, entry)

@spec unregister(t(), entry_ref()) :: {:ok, t()} | {:error, term()}

Removes an entry by id, unique action name, or entry value.