LlmCore.Agent (llm_core v0.3.0)

Agent struct representing a registered LLM provider with a human-friendly name.

Each agent encapsulates:

A name/alias for routing lookups
The underlying provider module or CLI config
Default configuration (model, temperature, etc.)

Agents are registered by the config loader from TOML [providers.*] blocks. They are keyed by the provider's aliases, not by agent.name.

Accessing Agents

# By alias (from TOML or runtime)
{:ok, agent} = LlmCore.Agent.Registry.get("claude")

# Get the dispatchable provider
provider = LlmCore.Agent.dispatch_provider(agent)

Summary

Types

t()

Functions

dispatch_provider(agent)

Returns the dispatchable provider value.

new(name, provider, config \\ %{})

Creates a new Agent struct with validation.

valid_name?(name)

Validates an agent name format.

Types

t()

@type t() :: %LlmCore.Agent{
  config: map(),
  name: String.t(),
  provider: module() | struct(),
  provider_struct: term(),
  registered_at: DateTime.t()
}

Functions

dispatch_provider(agent)

@spec dispatch_provider(t()) :: module() | struct()

Returns the dispatchable provider value.

For struct-based providers (CLIProvider, Appliance), returns the struct. For module-based providers, returns the module atom.

new(name, provider, config \\ %{})

@spec new(String.t(), module(), map()) :: {:ok, t()} | {:error, :invalid_name}

Creates a new Agent struct with validation.

Parameters

name - Human-friendly alias (lowercase alphanumeric with dashes/underscores)
provider - Module implementing LlmCore.LLM.Provider behaviour
config - Provider-specific configuration map (default: %{})

Returns

{:ok, Agent.t()} - Valid agent
{:error, :invalid_name} - Invalid name format

Examples

iex> Agent.new("steve", LlmCore.LLM.CLIProvider, %{model: "claude-3-opus"})
{:ok, %Agent{name: "steve", provider: LlmCore.LLM.CLIProvider, ...}}

iex> Agent.new("INVALID", LlmCore.LLM.CLIProvider, %{})
{:error, :invalid_name}

valid_name?(name)

@spec valid_name?(String.t()) :: boolean()

Validates an agent name format.

Valid names must:

Start with lowercase letter or number
Contain only lowercase letters, numbers, dashes, and underscores
Not be empty

Examples

iex> Agent.valid_name?("steve")
true

iex> Agent.valid_name?("claude-code")
true

iex> Agent.valid_name?("UPPERCASE")
false

iex> Agent.valid_name?("")
false