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

Returns the capabilities map for a provider.

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

@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 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 60_000).
• :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, map()} | {:error, term()}

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

Accepts :queue and :queue_timeout options (see query/2). The slot is held for the entire loop run.

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.