Wire-protocol codec for LLM APIs.
LlmCall turns a provider-neutral request into the request body, path, and
protocol headers a provider expects, and turns provider response terms into a
provider-neutral response.
It ships a one-call client (complete/3, stream/3, generate/3, poll/3) on
top of Finch and a replaceable JSON layer, and keeps the encode/decode functions
for callers that already own a transport.
client = MyApp.Anthropic.client(api_key: System.fetch_env!("ANTHROPIC_API_KEY"))
{:ok, response} = LlmCall.complete(client, request)It still owns no model discovery, approvals, retries, or agent loop. A codec
returns JSON-compatible Elixir terms; the client performs the request and the
JSON encoding with the modules configured in LlmCall.Config and
LlmCall.Client.
See docs/design.md for the canonical IR contract and the list of protocol
adapters.
Summary
Functions
Describes what a completion codec supports.
Calls a provider: encode, send, decode.
Normalizes a provider error payload.
Decodes a media generation response, sync assets or an operation.
Decodes the next state of a long-running job.
Decodes one provider response term into a canonical response.
Decodes one provider stream event into zero or more normalized events.
Encodes a canonical request into one protocol's wire request.
Encodes a media generation request, or starts a long-running job.
Performs a request the caller already encoded.
Performs a request and returns the body bytes, without JSON decoding.
Flushes whatever the protocol does not emit itself when the stream ends.
Submits a media generation request.
Starts a stream, or returns a typed error when the codec has no streaming.
Describes the media surface a codec declares.
Advances a media operation.
Starts a streaming call.
Checks a media request against the fields a codec can represent.
Checks a request against the fields a codec can represent.
Types
@type capture_raw() :: :none | :response | :all
@type modality() :: :text | :image | :video
@type model() :: String.t()
@type stop_reason() ::
:end_turn
| :tool_calls
| :max_tokens
| :stop_sequence
| :content_filter
| :error
| :unknown
@type wire_value() :: nil | boolean() | number() | String.t() | [wire_value()] | %{optional(String.t()) => wire_value()}
Functions
@spec capabilities(module(), LlmCall.Request.t(), LlmCall.Config.t()) :: {:ok, LlmCall.Capabilities.t()} | {:error, LlmCall.Error.t()}
Describes what a completion codec supports.
Capabilities are protocol-level, not model-level; see
LlmCall.Capabilities. Returns a typed error when the module implements the
media behaviour instead.
@spec complete(LlmCall.Client.t(), LlmCall.Request.t(), keyword()) :: {:ok, LlmCall.Response.t()} | {:error, LlmCall.Error.t()}
Calls a provider: encode, send, decode.
opts: codec: names an entry in the provider's codecs map (:chat by
default). A request with stream: true is rejected — use stream/3.
Non-2xx responses are decoded by the codec and carry the HTTP status; a
body the configured JSON module cannot parse is :invalid_response; a network
failure is :transport.
@spec decode_error(module(), wire_value(), LlmCall.Config.t()) :: LlmCall.Error.t() | {:error, LlmCall.Error.t()}
Normalizes a provider error payload.
@spec decode_media(module(), wire_value(), LlmCall.Config.t()) :: {:ok, LlmCall.Media.Response.t()} | {:error, LlmCall.Error.t()}
Decodes a media generation response, sync assets or an operation.
@spec decode_operation(module(), wire_value(), LlmCall.Config.t()) :: {:ok, LlmCall.Operation.t()} | {:error, LlmCall.Error.t()}
Decodes the next state of a long-running job.
Returns a typed :validation error when the codec has no
decode_operation/2.
@spec decode_response(module(), wire_value(), LlmCall.Config.t()) :: {:ok, LlmCall.Response.t()} | {:error, LlmCall.Error.t()}
Decodes one provider response term into a canonical response.
@spec decode_stream_event( module(), wire_value(), LlmCall.Config.t(), LlmCall.StreamState.t() ) :: {:ok, [LlmCall.StreamEvent.t()], LlmCall.StreamState.t()} | {:done, LlmCall.StreamState.t()} | {:error, LlmCall.Error.t()}
Decodes one provider stream event into zero or more normalized events.
@spec encode(module(), LlmCall.Request.t(), LlmCall.Config.t()) :: {:ok, LlmCall.EncodedRequest.t()} | {:error, LlmCall.Error.t()}
Encodes a canonical request into one protocol's wire request.
@spec encode_media(module(), LlmCall.Media.Request.t(), LlmCall.Config.t()) :: {:ok, LlmCall.EncodedRequest.t()} | {:error, LlmCall.Error.t()}
Encodes a media generation request, or starts a long-running job.
The codec validates first; a knob it cannot express is a typed error.
@spec execute(LlmCall.Client.t(), LlmCall.EncodedRequest.t()) :: {:ok, %{status: non_neg_integer(), headers: list(), body: term()}} | {:error, LlmCall.Error.t()}
Performs a request the caller already encoded.
Transport-level: a 2xx body is JSON-decoded into body, anything else is
:transport with the status. Use complete/3 when you want the codec to decode
a provider error envelope.
@spec fetch(LlmCall.Client.t(), LlmCall.EncodedRequest.t() | LlmCall.Operation.t()) :: {:ok, %{status: non_neg_integer(), headers: list(), body: binary()}} | {:error, LlmCall.Error.t()}
Performs a request and returns the body bytes, without JSON decoding.
For Operation.next_kind: :asset, where the body is media.
A non-2xx status is a :transport error carrying the status. Redirects are
never followed, and %LlmCall.Error{} has no header field, so a 3xx hides
its Location. When you need it — a CDN or pre-signed asset URL that answers
302 — build an %LlmCall.HTTP.Request{} for the same URL and use
LlmCall.HTTP.request/2, which returns the whole response with headers.
@spec finish_stream(module(), LlmCall.StreamState.t(), LlmCall.Config.t()) :: {:ok, [LlmCall.StreamEvent.t()], LlmCall.StreamState.t()} | {:error, LlmCall.Error.t()}
Flushes whatever the protocol does not emit itself when the stream ends.
Gemini has no stream terminator, so its accumulated usage and :message_stop
arrive only here. Calling it more than once is safe.
@spec generate(LlmCall.Client.t(), LlmCall.Media.Request.t(), keyword()) :: {:ok, LlmCall.Media.Response.t()} | {:error, LlmCall.Error.t()}
Submits a media generation request.
codec: is required and names an entry in the provider's codecs map (for
example :images, :predict, :video). The codec validates and encodes the
submit, and decodes the response into %LlmCall.Media.Response{} — assets, or a
queued %LlmCall.Operation{} whose next is the request to run with poll/3.
@spec init_stream(module(), LlmCall.Request.t(), LlmCall.Config.t()) :: {:ok, LlmCall.StreamState.t()} | {:error, LlmCall.Error.t()}
Starts a stream, or returns a typed error when the codec has no streaming.
@spec media_capabilities(module(), LlmCall.Media.Request.t(), LlmCall.Config.t()) :: {:ok, LlmCall.Media.Capabilities.t()} | {:error, LlmCall.Error.t()}
Describes the media surface a codec declares.
Returns a typed error when the module implements the completion behaviour instead.
@spec poll( LlmCall.Client.t(), LlmCall.Operation.t() | LlmCall.EncodedRequest.t(), keyword() ) :: {:ok, LlmCall.Operation.t()} | {:error, LlmCall.Error.t()}
Advances a media operation.
Accepts a %LlmCall.Operation{} (its next is executed) or the
%LlmCall.EncodedRequest{} to run, decodes the body with the codec's
decode_operation/2, and returns the next operation state. codec: is
required, because an operation does not carry it.
@spec stream(LlmCall.Client.t(), LlmCall.Request.t(), keyword()) :: {:ok, LlmCall.Stream.t()} | {:error, LlmCall.Error.t()}
Starts a streaming call.
Encodes the request with stream: true and starts the codec's stream state
eagerly, so an invalid request is a tagged error; the HTTP request itself starts
when the returned %LlmCall.Stream{} is reduced.
codec: names an entry in the provider's codecs map (:chat by default).
Events are yielded as LlmCall.StreamEvent structs; a failure while reading the
body raises LlmCall.HTTP.Error, because an Enumerable cannot return a tuple.
on_event: takes a 1-arity function called for every event before the reducer
sees it, including events flushed by finish_stream/2. It observes only: the
return value is ignored, it cannot filter or replace events, and it is not
called after the reducer halts.
@spec validate_media(module(), LlmCall.Media.Request.t(), LlmCall.Config.t()) :: :ok | {:error, LlmCall.Error.t()}
Checks a media request against the fields a codec can represent.
@spec validate_request(module(), LlmCall.Request.t(), LlmCall.Config.t()) :: :ok | {:error, LlmCall.Error.t()}
Checks a request against the fields a codec can represent.