LlmCall (llm_call v0.1.0)

Copy Markdown View Source

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.

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

capture_raw()

@type capture_raw() :: :none | :response | :all

modality()

@type modality() :: :text | :image | :video

model()

@type model() :: String.t()

stop_reason()

@type stop_reason() ::
  :end_turn
  | :tool_calls
  | :max_tokens
  | :stop_sequence
  | :content_filter
  | :error
  | :unknown

wire_value()

@type wire_value() ::
  nil
  | boolean()
  | number()
  | String.t()
  | [wire_value()]
  | %{optional(String.t()) => wire_value()}

Functions

capabilities(codec, request, config \\ Config.new())

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

complete(client, request, opts \\ [])

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

decode_error(codec, term, config \\ Config.new())

@spec decode_error(module(), wire_value(), LlmCall.Config.t()) ::
  LlmCall.Error.t() | {:error, LlmCall.Error.t()}

Normalizes a provider error payload.

decode_media(codec, term, config \\ Config.new())

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

decode_operation(codec, term, config \\ Config.new())

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

decode_response(codec, term, config \\ Config.new())

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

decode_stream_event(codec, term, config, state)

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

encode(codec, request, config \\ Config.new())

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

encode_media(codec, request, config \\ Config.new())

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

execute(client, encoded)

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

fetch(client, encoded)

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

finish_stream(codec, state, config \\ Config.new())

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

generate(client, request, opts \\ [])

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.

init_stream(codec, request, config \\ Config.new())

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

media_capabilities(codec, request, config \\ Config.new())

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

poll(client, operation_or_encoded, opts \\ [])

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.

stream(client, request, opts \\ [])

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

validate_media(codec, request, config \\ Config.new())

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

validate_request(codec, request, config \\ Config.new())

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