View Source Jido.Discovery (Jido v1.0.0)

Discovery is the mechanism by which agents and sensors are discovered and registered with the system.

This module caches discovered components using :persistent_term for efficient lookups. The cache is initialized at application startup and can be manually refreshed if needed.

Summary

Types

cache_entry()

component_metadata()

component_type()

Functions

dbug(_, _ \\ [], _ \\ [])

error(_, _ \\ [], _ \\ [])

get_action_by_slug(slug)

Retrieves an Action by its slug.

get_agent_by_slug(slug)

Retrieves an Agent by its slug.

get_sensor_by_slug(slug)

Retrieves a Sensor by its slug.

init()

Initializes the discovery cache. Should be called during application startup.

last_updated()

Gets the last time the cache was updated.

list_actions(opts \\ [])

Lists all Actions with optional filtering and pagination.

list_agents(opts \\ [])

Lists all Agents with optional filtering and pagination.

list_sensors(opts \\ [])

Lists all Sensors with optional filtering and pagination.

refresh()

Forces a refresh of the discovery cache.

Types

cache_entry()

@type cache_entry() :: %{
  version: String.t(),
  last_updated: DateTime.t(),
  actions: [component_metadata()],
  sensors: [component_metadata()],
  agents: [component_metadata()]
}

component_metadata()

@type component_metadata() :: %{
  module: module(),
  name: String.t(),
  description: String.t(),
  slug: String.t(),
  category: atom() | nil,
  tags: [atom()] | nil
}

component_type()

@type component_type() :: :action | :sensor | :agent

Functions

dbug(_, _ \\ [], _ \\ [])

(macro)

error(_, _ \\ [], _ \\ [])

(macro)

get_action_by_slug(slug)

@spec get_action_by_slug(String.t()) :: component_metadata() | nil

Retrieves an Action by its slug.

Parameters

slug: A string representing the unique identifier of the Action.

Returns

The Action metadata if found, otherwise nil.

Examples

iex> Jido.get_action_by_slug("abc123de")
%{module: MyApp.SomeAction, name: "some_action", description: "Does something", slug: "abc123de"}

iex> Jido.get_action_by_slug("nonexistent")
nil

get_agent_by_slug(slug)

@spec get_agent_by_slug(String.t()) :: component_metadata() | nil

Retrieves an Agent by its slug.

Parameters

slug: A string representing the unique identifier of the Agent.

Returns

The Agent metadata if found, otherwise nil.

Examples

iex> Jido.get_agent_by_slug("ghi789jk")
%{module: MyApp.SomeAgent, name: "some_agent", description: "Represents an agent", slug: "ghi789jk"}

iex> Jido.get_agent_by_slug("nonexistent")
nil

get_sensor_by_slug(slug)

@spec get_sensor_by_slug(String.t()) :: component_metadata() | nil

Retrieves a Sensor by its slug.

Parameters

slug: A string representing the unique identifier of the Sensor.

Returns

The Sensor metadata if found, otherwise nil.

Examples

iex> Jido.get_sensor_by_slug("def456gh")
%{module: MyApp.SomeSensor, name: "some_sensor", description: "Monitors something", slug: "def456gh"}

iex> Jido.get_sensor_by_slug("nonexistent")
nil

init()

@spec init() :: :ok | {:error, term()}

Initializes the discovery cache. Should be called during application startup.

Returns

:ok if cache was initialized successfully
{:error, reason} if initialization failed

last_updated()

@spec last_updated() :: {:ok, DateTime.t()} | {:error, :not_initialized}

Gets the last time the cache was updated.

Returns

{:ok, datetime} with the last update time
{:error, :not_initialized} if cache hasn't been initialized

list_actions(opts \\ [])

@spec list_actions(keyword()) :: [component_metadata()]

Lists all Actions with optional filtering and pagination.

Parameters

opts: A keyword list of options for filtering and pagination. Available options:
- :limit: Maximum number of results to return.
- :offset: Number of results to skip before starting to return.
- :name: Filter Actions by name (partial match).
- :description: Filter Actions by description (partial match).
- :category: Filter Actions by category (exact match).
- :tag: Filter Actions by tag (must have the exact tag).

Returns

A list of Action metadata.

Examples

iex> Jido.list_actions(limit: 10, offset: 5, category: :utility)
[%{module: MyApp.SomeAction, name: "some_action", description: "Does something", slug: "abc123de", category: :utility}]

list_agents(opts \\ [])

@spec list_agents(keyword()) :: [component_metadata()]

Lists all Agents with optional filtering and pagination.

Parameters

opts: A keyword list of options for filtering and pagination. Available options:
- :limit: Maximum number of results to return.
- :offset: Number of results to skip before starting to return.
- :name: Filter Agents by name (partial match).
- :description: Filter Agents by description (partial match).
- :category: Filter Agents by category (exact match).
- :tag: Filter Agents by tag (must have the exact tag).

Returns

A list of Agent metadata.

Examples

iex> Jido.list_agents(limit: 10, offset: 5, category: :business)
[%{module: MyApp.SomeAgent, name: "some_agent", description: "Represents an agent", slug: "ghi789jk", category: :business}]

list_sensors(opts \\ [])

@spec list_sensors(keyword()) :: [component_metadata()]

Lists all Sensors with optional filtering and pagination.

Parameters

opts: A keyword list of options for filtering and pagination. Available options:
- :limit: Maximum number of results to return.
- :offset: Number of results to skip before starting to return.
- :name: Filter Sensors by name (partial match).
- :description: Filter Sensors by description (partial match).
- :category: Filter Sensors by category (exact match).
- :tag: Filter Sensors by tag (must have the exact tag).

Returns

A list of Sensor metadata.

Examples

iex> Jido.list_sensors(limit: 10, offset: 5, category: :monitoring)
[%{module: MyApp.SomeSensor, name: "some_sensor", description: "Monitors something", slug: "def456gh", category: :monitoring}]

refresh()

@spec refresh() :: :ok | {:error, term()}

Forces a refresh of the discovery cache.

Returns

:ok if cache was refreshed successfully
{:error, reason} if refresh failed