# `LlmCall.Provider`
[🔗](https://github.com/gilbertwong96/llm_call/blob/main/lib/llm_call/provider.ex#L1)

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.

# `build`

```elixir
@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:`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
