Jido.AI.Keyring (Jido AI v0.5.2)

View Source

A GenServer that manages environment variables and application configuration.

This module serves as the source of truth for configuration values, with a hierarchical loading priority:

  1. Session values (per-process overrides)
  2. Environment variables (via Dotenvy)
  3. Application environment (under :jido_ai, :keyring)
  4. Default values

The keyring supports both global environment values and process-specific session values, allowing for flexible configuration management in different contexts.

Usage 

# Get a value (checks session then environment)
value = Keyring.get(:my_key, "default")

# Set a session-specific override
Keyring.set_session_value(:my_key, "override")

# Clear session values
Keyring.clear_session_value(:my_key)
Keyring.clear_all_session_values()

Summary

Functions

child_spec(init_arg)

Returns the child specification for starting the keyring under a supervisor.

clear_all_session_values(server \\ Jido.AI.Keyring, pid \\ self())

Clears all session-specific values for the specified process.

clear_session_value(server \\ Jido.AI.Keyring, key, pid \\ self())

Clears a session-specific value for the specified process.

get(server \\ Jido.AI.Keyring, key, default \\ nil, pid \\ self())

Gets a value from the keyring, checking session values first, then environment values.

get_env_value(server \\ Jido.AI.Keyring, key, default \\ nil)

Gets a value from the environment-level storage, also checking for LiveBook prefixed keys as fallback.

get_env_var(key, default \\ nil)

Gets an environment variable with a default value.

get_session_value(server \\ Jido.AI.Keyring, key, pid \\ self())

Gets a session-specific value for the specified process.

has_value?(value)

Checks if a value exists and is non-empty.

list(server \\ Jido.AI.Keyring)

Lists all available keys in the keyring.

set_session_value(server \\ Jido.AI.Keyring, key, value, pid \\ self())

Sets a session-specific value that will override the environment value for the specified process.

start_link(opts \\ [])

Starts the keyring process.

Functions

child_spec(init_arg)

@spec child_spec(keyword()) :: Supervisor.child_spec()

Returns the child specification for starting the keyring under a supervisor.

clear_all_session_values(server \\ Jido.AI.Keyring, pid \\ self())

@spec clear_all_session_values(GenServer.server(), pid()) :: :ok

Clears all session-specific values for the specified process.

Parameters

  • server - The server to query (default: Elixir.Jido.AI.Keyring)
  • pid - The process ID to clear all values for (default: current process)

Returns :ok.

clear_session_value(server \\ Jido.AI.Keyring, key, pid \\ self())

@spec clear_session_value(GenServer.server(), atom(), pid()) :: :ok

Clears a session-specific value for the specified process.

Parameters

  • server - The server to query (default: Elixir.Jido.AI.Keyring)
  • key - The key to clear (as an atom)
  • pid - The process ID to clear the value for (default: current process)

Returns :ok.

get(server \\ Jido.AI.Keyring, key, default \\ nil, pid \\ self())

@spec get(GenServer.server(), atom(), term(), pid()) :: term()

Gets a value from the keyring, checking session values first, then environment values.

Parameters

  • server - The server to query (default: Elixir.Jido.AI.Keyring)
  • key - The key to look up (as an atom)
  • default - The default value if key is not found
  • pid - The process ID to check session values for (default: current process)

Returns the value if found, otherwise returns the default value.

get_env_value(server \\ Jido.AI.Keyring, key, default \\ nil)

@spec get_env_value(GenServer.server(), atom(), term()) :: term()

Gets a value from the environment-level storage, also checking for LiveBook prefixed keys as fallback.

Parameters

  • server - The server to query (default: Elixir.Jido.AI.Keyring)
  • key - The key to look up (as an atom)
  • default - The default value if key is not found

Returns the environment value if found, otherwise returns the default value.

get_env_var(key, default \\ nil)

@spec get_env_var(String.t(), term()) :: String.t() | term()

Gets an environment variable with a default value.

Parameters

  • key - The environment variable name
  • default - The default value if not found

Returns the environment variable value if found, otherwise returns the default value.

get_session_value(server \\ Jido.AI.Keyring, key, pid \\ self())

@spec get_session_value(GenServer.server(), atom(), pid()) :: term() | nil

Gets a session-specific value for the specified process.

Parameters

  • server - The server to query (default: Elixir.Jido.AI.Keyring)
  • key - The key to look up (as an atom)
  • pid - The process ID to get the value for (default: current process)

Returns the session value if found, otherwise returns nil.

has_value?(value)

@spec has_value?(term()) :: boolean()

Checks if a value exists and is non-empty.

Returns true if the value is a non-empty string, false otherwise.

list(server \\ Jido.AI.Keyring)

@spec list(GenServer.server()) :: [atom()]

Lists all available keys in the keyring.

Returns a list of atoms representing the available environment-level keys. Does not include session-specific overrides.

set_session_value(server \\ Jido.AI.Keyring, key, value, pid \\ self())

@spec set_session_value(GenServer.server(), atom(), term(), pid()) :: :ok

Sets a session-specific value that will override the environment value for the specified process.

Parameters

  • server - The server to query (default: Elixir.Jido.AI.Keyring)
  • key - The key to set (as an atom)
  • value - The value to store
  • pid - The process ID to associate with this value (default: current process)

Returns :ok.

start_link(opts \\ [])

@spec start_link(keyword()) :: GenServer.on_start()

Starts the keyring process.

Options

  • :name - The name to register the process under (default: Elixir.Jido.AI.Keyring)
  • :registry - The name for the ETS registry table (default: jido_ai_keyring_sessions)