Declares a provider: where it lives, how it authenticates, and which codecs it serves.
defmodule MyApp.OpenAI do
use LlmCall.Provider,
base_url: "https://api.openai.com",
auth: :bearer,
codecs: [
chat: LlmCall.Dialect.OpenAI.Chat,
images: LlmCall.Media.Dialect.OpenAI.Images
]
end
client = MyApp.OpenAI.client(api_key: System.fetch_env!("OPENAI_API_KEY"))
LlmCall.complete(client, request)A provider is a user module, not a catalog entry: the library ships no provider
list. auth describes the shape of authentication, never the key; the key is
always passed in.
base_url is the origin: every codec path starts with its own version segment
(/v1/chat/completions, /v1beta/models/...), so a provider whose base URL
already ends in /v1 would produce /v1/v1/....
query adds parameters to every request URL, which is how a vendor that keys
on a URL parameter is configured — MiniMax's GroupId, Azure OpenAI's
api-version:
use LlmCall.Provider,
base_url: "https://api.minimax.io",
auth: :bearer,
query: %{"GroupId" => "1234567890"},
codecs: [video: LlmCall.Media.Dialect.MiniMax.Video]A query already present in base_url (https://…/openai?api-version=1) is folded
into query when the client is built, so it reaches the provider as a parameter
instead of being glued in front of the codec path; an explicit query: wins on
the same key.
Like every declaration value it must be a literal; pass a runtime value to
client/1 instead (MyProvider.client(api_key: key, query: %{"GroupId" => id})).
A codec's own parameter wins over the client's on the same key, because it is a
protocol fact (Gemini's alt=sse); everything else is merged in.
Declaration values are literals: use receives its options before the module
body runs, so base_url: @url or base_url: Application.fetch_env!(...) is a
compile error. Read a dynamic value where it is known instead —
MyProvider.client(api_key: key, base_url: System.fetch_env!("OPENAI_URL")) —
or set config :llm_call, ....
Resolution
http_opts and timeout may be declared here, and each resolves call option →
provider → config :llm_call, ... → built-in default. A declaration that omits
them leaves the value nil, so the application setting still applies.
http_opts accepts :name (the Finch pool), :pool_timeout,
:request_timeout, and :pool_strategy; anything else is an ArgumentError,
because the client would drop it. The read timeout is timeout:, not
http_opts: [receive_timeout: ...].
timeout is per chunk, not per call: it becomes Finch's :receive_timeout, so
a slow trickle can outlast it. Pair it with http_opts: [request_timeout: ...]
when you need a wall-clock cap.
query resolves call option → provider → %{}; it deliberately has no
application-wide default, since a URL parameter is vendor-specific.
json_library resolves call option → provider → the compile-time application
default (Application.compile_env(:llm_call, :json_library, JSON)). It is
written into the client's %LlmCall.Config{}, so the codecs use the same
implementation as the transport. A config: call option supplies the base
config; a json_library: call option still wins over it, and the declaration's
json_library: applies only when the caller passes neither.
capture_raw is not a provider option; it comes from %LlmCall.Config{},
whose default is Application.compile_env(:llm_call, :capture_raw, :none).
Pass config: LlmCall.Config.new(capture_raw: ...) to override it per client.
Summary
Functions
Builds a %LlmCall.Client{} from a provider module's declaration and options.
Functions
@spec build(module(), keyword()) :: LlmCall.Client.t()
Builds a %LlmCall.Client{} from a provider module's declaration and options.
Options: api_key:, base_url:, headers:, query:, http_opts:,
timeout:, json_library:, config:.