@spec get(module(), atom(), keyword(), term()) :: term()

Look up a single configuration value for provider_module with the tiered resolution order. opts wins, then provider-specific config, then top-level config, then the supplied default.

The provider atom is derived from the module name: Providers.Ollama → :ollama.

@spec list_providers() :: [
  %{
    name: String.t(),
    display_name: String.t(),
    module: module(),
    source: :builtin | :registry
  }
]

Return all known providers: built-in atoms plus any specs loaded by ExAthena.ProviderRegistry.

Each entry is a map with:

• :name — string name of the provider
• :module — the implementing module
• :source — :builtin or :registry

@spec pop_provider!(keyword()) :: {module(), keyword()}

Pop :provider from opts and return {provider_module, remaining_opts}.

Raises ArgumentError if no provider is set in opts or in application env.

For registry-loaded providers the following spec fields are threaded into opts using Keyword.put_new/3 so per-call overrides always win:

• :req_llm_provider_tag — from spec.req_llm_provider_tag
• :base_url — from spec.base_url
• :extra_headers — from spec.extra_headers (non-empty maps only)
• :api_key — from spec.api_key, or resolved from spec.api_key_env

@spec provider_module(atom() | module()) :: module()

Resolve a provider atom (or module) to its implementing module.

Resolution order:

1. Built-in provider map (compile-time constant, fastest path).
2. ExAthena.ProviderRegistry — for providers loaded from JSON config files.
3. Module check — accepts any atom that is a loaded module implementing ExAthena.Provider.

@spec provider_opts(module(), keyword(), atom() | nil) :: keyword()

Build the keyword list passed to a provider's query/2 / stream/3 callback.

Flattens per-call overrides + application env for this provider into one keyword list. Providers use Keyword.get/3 on the result.

@spec provider_spec(atom() | String.t()) :: {:ok, ExAthena.ProviderSpec.t()} | :error

Resolve a provider's ProviderSpec. A user-registered JSON spec (loaded by ExAthena.ProviderRegistry) wins; otherwise a built-in spec (e.g. OpenRouter) is returned. Returns :error when neither exists.

@spec req_llm_provider_tag(atom() | module()) :: String.t() | nil

Translate an ExAthena provider atom into the req_llm provider tag used in "tag:model-id" specs. Returns nil when the atom doesn't map to req_llm (e.g. :mock, or a user-supplied module).

Resolution order: a registry-loaded JSON spec wins (its req_llm_provider_tag field), with the static built-in map as fallback when no spec is loaded for the atom or the spec's tag is unset. This matters when a JSON-defined provider's name collides with a built-in atom (e.g. :openrouter, which is also present in the built-in map for config.exs users) — the user's JSON file is authoritative.

@spec request_queue_enabled?() :: boolean()

Return true when the request queue feature is enabled.

Enabled by default — local inference servers (ollama / llama.cpp / exo) can only serve 1-3 concurrent requests, and the per-call gate is what keeps concurrent loops and subagents from overwhelming them. Disable with:

config :ex_athena, :request_queue, enabled: false

@spec request_queue_max_depth(atom()) :: pos_integer()

Return the maximum concurrent request depth for provider_atom.

Resolution order:

1. config :ex_athena, provider_atom, request_queue: [max_depth: N]
2. config :ex_athena, :request_queue, max_depth: N
3. Built-in per-provider default (local providers: 1, cloud: 10).
4. 10 for unrecognised providers.

@spec set_request_queue_max_depth(atom(), pos_integer()) ::
  :ok | {:error, :invalid_depth}

Set the per-provider concurrent-slot cap at runtime.

Hosts expose this next to their provider selector so users can raise a local provider's slots once their serving setup proves it can take more load (everything local defaults to 1). Merges into the provider's existing application env, preserving keys like base_url.

Takes effect on the next slot acquisition — in-flight holders and waiters are unaffected.