@spec ask(
  term(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Convenience helper that returns extracted response text.

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

Thin facade for ReqLLM.Generation.generate_object/4.

opts has the same behavior as generate_text/2.

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

Thin facade for ReqLLM.Generation.generate_text/3.

opts supports:

• :model - model alias or direct model spec
• :system_prompt - optional system prompt
• :max_tokens, :temperature, :timeout
• Any other ReqLLM options (e.g. :tools, :tool_choice) as pass-through options

@spec get_strategy_config(Jido.Agent.t()) :: map()

Returns the strategy config from an agent struct.

Convenience for reading strategy config without reaching into internal state.

@spec get_strategy_context(Jido.Agent.t()) :: map() | nil

Returns the active context (conversation history) from the strategy state.

Prefers :run_context while a request is in flight, otherwise falls back to materialized :context. Returns nil if neither exists.

@spec has_tool?(Jido.Agent.t() | GenServer.server(), String.t()) ::
  boolean() | {:ok, boolean()} | {:error, term()}

Checks if a specific tool is registered with an agent.

Can be called with either an agent struct or an agent server (PID/name).

Examples

# With agent struct
true = Jido.AI.has_tool?(agent, "calculator")

# With agent server
{:ok, true} = Jido.AI.has_tool?(agent_pid, "calculator")

@spec inject(GenServer.server(), String.t(), keyword()) ::
  {:ok, Jido.Agent.t()} | {:error, term()}

Compatibility wrapper for Jido.AI.Reasoning.ReAct.inject/3.

@spec list_tools(Jido.Agent.t() | GenServer.server()) ::
  [module()] | {:ok, [module()]} | {:error, term()}

Lists all currently registered tools for an agent.

Can be called with either an agent struct or an agent server (PID/name).

Examples

# With agent struct
tools = Jido.AI.list_tools(agent)

# With agent server
{:ok, tools} = Jido.AI.list_tools(agent_pid)

@spec llm_defaults() :: %{required(llm_kind()) => llm_generation_opts()}

Returns configured LLM generation defaults merged with built-in defaults.

Configure under config :jido_ai, :llm_defaults.

@spec llm_defaults(llm_kind()) :: llm_generation_opts()

Returns defaults for a specific generation kind: :text, :object, or :stream.

@spec model_aliases() :: %{required(model_alias()) => model_spec()}

Returns all configured model aliases merged with defaults.

User overrides from config :jido_ai, :model_aliases are merged on top of built-in defaults.

Examples

iex> aliases = Jido.AI.model_aliases()
iex> is_binary(aliases[:fast])
true

@spec model_label(model_input()) :: String.t()

Returns a stable human-readable label for a model input.

@spec register_tool(GenServer.server(), module(), keyword()) ::
  {:ok, Jido.Agent.t()} | {:error, term()}

Registers a tool module with a running agent.

The tool must implement the Jido.Action behaviour (have name/0, schema/0, and run/2).

Options

• :timeout - Call timeout in milliseconds (default: 5000)
• :validate - Validate tool implements required callbacks (default: true)

Examples

{:ok, agent} = Jido.AI.register_tool(agent_pid, MyApp.Tools.Calculator)
{:error, :not_a_tool} = Jido.AI.register_tool(agent_pid, NotATool)

@spec resolve_model(model_input()) :: resolved_model_input()

Resolves a model alias or passes through a direct ReqLLM model input.

Model aliases are atoms like :fast, :capable, :reasoning that map to full ReqLLM model specifications. Direct model inputs are passed through unchanged and may be strings, ReqLLM tuples, inline maps, or %LLMDB.Model{} structs.

Arguments

• model - Either a model alias atom or a direct ReqLLM model input

Returns

A resolved ReqLLM model input.

Examples

iex> String.contains?(Jido.AI.resolve_model(:fast), ":")
true

iex> Jido.AI.resolve_model("openai:gpt-4")
"openai:gpt-4"

iex> Jido.AI.resolve_model({:openai, "gpt-4.1", []})
{:openai, "gpt-4.1", []}

Jido.AI.resolve_model(:unknown_alias)
# raises ArgumentError with unknown alias message

@spec set_system_prompt(GenServer.server(), String.t(), keyword()) ::
  {:ok, Jido.Agent.t()} | {:error, term()}

Updates the base ReAct system prompt for a running agent.

Options

• :timeout - Call timeout in milliseconds (default: 5000)

@spec set_system_prompt_direct(Jido.Agent.t(), String.t()) :: Jido.Agent.t()

Sets the system prompt directly on the agent's strategy config.

This is the struct-level equivalent of set_system_prompt/3 — safe to call from within the agent process (e.g., on_before_cmd).

Also updates the system prompt in :context and :run_context if they exist, so resumed conversations pick up the new prompt.

@spec steer(GenServer.server(), String.t(), keyword()) ::
  {:ok, Jido.Agent.t()} | {:error, term()}

Compatibility wrapper for Jido.AI.Reasoning.ReAct.steer/3.

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

Thin facade for ReqLLM.stream_text/3.

Returns ReqLLM stream response directly.

@spec unregister_tool(GenServer.server(), String.t(), keyword()) ::
  {:ok, Jido.Agent.t()} | {:error, term()}

Unregisters a tool from a running agent by name.

Options

• :timeout - Call timeout in milliseconds (default: 5000)

Examples

{:ok, agent} = Jido.AI.unregister_tool(agent_pid, "calculator")

@spec update_context_entries(Jido.Agent.t(), list()) :: Jido.Agent.t()

Updates the active context entries (conversation messages) in the strategy state.

If :run_context exists, it is treated as authoritative for the in-flight turn and updated in isolation. Otherwise, updates materialized :context.