@spec capabilities(atom() | module()) :: map()

Returns the capabilities map for a provider.

ExAthena.capabilities(:mock)
#=> %{streaming: true, native_tool_calls: true, …}

@spec confine_default?() :: boolean()

Whether first-party hosts (the web UI and TUI) should confine a run to its working directory by default. On unless EX_ATHENA_CONFINE is 0/false/no.

Library consumers calling run/2 directly are unaffected — they opt in with confine: true or allowed_roots: [...].

@spec embed(
  String.t() | [String.t()],
  keyword()
) :: {:ok, ExAthena.Embedding.t()} | {:error, term()}

Embed text. Accepts a single string or a list of strings and returns one vector per input, in input order.

Batch calls are a single provider round-trip — indexing jobs embed hundreds of chunks per run, and one request per chunk would dominate their runtime.

ExAthena.embed(["def foo", "def bar"], provider: :ollama)
#=> {:ok, %ExAthena.Embedding{embeddings: [[0.1, …], [0.2, …]], …}}

Options

• :provider — as query/2. Must implement the optional embed/2 callback; feature-detect with capabilities(provider)[:embeddings].
• :model — the embedding model. Defaults to the provider's embedding_model: config, then the top-level :embedding_model config. The provider's chat model: is never used — embedding models are a separate population (e.g. nomic-embed-text).
• :timeout_ms, :provider_opts, :queue, :queue_timeout — as query/2.

Configure a default embedding model alongside the chat model:

config :ex_athena, :ollama,
  base_url: "http://localhost:11434",
  model: "qwen3-coder",
  embedding_model: "nomic-embed-text"

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

One-shot structured extraction. Returns a validated JSON map.

Accepts :queue and :queue_timeout options (see query/2).

See ExAthena.Structured.extract/2 for the full option list.

@spec list_models(
  atom() | module() | nil,
  keyword()
) :: {:ok, [ExAthena.Model.t()]} | {:error, term()}

List the models a provider can serve, as ExAthena.Model structs.

ExAthena.list_models(:ollama)
#=> {:ok, [%Model{id: "qwen3-coder:30b", context_window: nil, …}]}

Every backend answers this question in its own dialect — Ollama's /api/tags, an OpenAI-compatible /v1/models, or nothing at all (Anthropic and Google are read from the llm_db catalog). Hosts building a model picker get one shape regardless, and Model.id is exactly what to pass back as model: on the next query/2.

Results are cached for five minutes in the shared model-discovery cache, so reopening a picker costs nothing; pass cache: false to force a refetch (what a user-facing "reload models" control should do).

Providers that cannot enumerate their models return a :capability error — feature-detect ahead of time with capabilities(provider)[:model_listing] and fall back to a free-text model field.

Options

• :base_url, :api_key — as query/2; default to the provider's config.
• :cache — false to bypass the TTL cache for this call.
• :include_cloud — Ollama only: also list the ollama.com catalogue, each entry suffixed -cloud so it is invocable through a signed-in local daemon. Off by default because it reaches out to the internet.

@spec query(
  String.t() | nil,
  keyword()
) :: {:ok, ExAthena.Response.t()} | {:error, term()}

One-shot inference. Returns the final Response struct with the full text.

Options

• :provider — provider atom (:ollama, :openai_compatible, :claude, :gemini, :mock), a module that implements ExAthena.Provider, or a string matching a JSON-defined provider loaded from ~/.config/ex_athena/providers/ (see the Providers guide). Defaults to Application.get_env(:ex_athena, :default_provider).
• :model — model name string. Defaults to the provider's configured model.
• :system_prompt — optional system prompt string.
• :messages — list of canonical messages; prompt is prepended as a user message if given.
• :max_tokens, :temperature, :top_p, :stop — optional sampling knobs.
• :timeout_ms — request timeout (default 300_000). The 5-minute default is deliberate: local backends spend minutes prompt-processing a large agent transcript before the first byte comes back.
• :provider_opts — escape hatch keyword list passed through to the underlying provider.
• :images — list of image maps to attach to the trailing user message. Each entry is %{data: binary(), media_type: String.t()} for inline images or %{url: String.t()} for remote image URLs. Merged into the user message created from prompt, or the last user message in :messages when no prompt is given.
• :queue — set to false to bypass the request queue for this call (default true). Has no effect when the request queue is not enabled.
• :queue_timeout — milliseconds to wait for a queue slot before returning {:error, :request_queue_timeout} (default 5_000).

@spec run(
  String.t() | nil,
  keyword()
) :: {:ok, ExAthena.Result.t()} | {:error, term()}

Run a multi-turn agent loop: infer → tool call → execute → replay → repeat.

Queueing happens inside the loop at per-provider-call granularity (one slot per inference call, released between iterations) — never one slot for the whole run, which would starve or deadlock concurrent loops on single-slot local providers. Accepts :queue (default true) and :queue_timeout (default :infinity — the run's own timeout_ms and budget caps bound total time).

See ExAthena.Loop.run/2 for the full option list.

@spec stream(String.t() | nil, function(), keyword()) ::
  {:ok, ExAthena.Response.t()} | {:error, term()}

Streaming inference. Calls callback with each ExAthena.Streaming.Event as tokens arrive, and returns the final Response when the stream completes.

callback receives one argument — an %ExAthena.Streaming.Event{} struct — and its return value is ignored. Callbacks must not block the caller; if you need to do expensive work per-delta, hand off to a Task.

Options are the same as query/2, including :images, :queue, :queue_timeout, and the :provider string form for JSON-defined providers. When the request queue is enabled, the slot is held for the full duration of the stream and released on every exit path (success, error, or callback exception).

@spec supports_multimodal?() :: true

Returns true if the library forwards multimodal content parts (image / image_url / file) to the underlying provider.

Callers can use this to decide whether to build ExAthena.Messages.ContentPart image or file parts, rather than falling back to text-only prompts.

See ExAthena.Messages.ContentPart.