LlmCall.Provider (llm_call v0.1.0)

Copy Markdown View Source

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

build(provider, opts \\ [])

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