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

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.

# `capture_raw`

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

# `modality`

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

# `model`

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

# `stop_reason`

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

# `wire_value`

```elixir
@type wire_value() ::
  nil
  | boolean()
  | number()
  | String.t()
  | [wire_value()]
  | %{optional(String.t()) =&gt; wire_value()}
```

# `capabilities`

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

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

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

Normalizes a provider error payload.

# `decode_media`

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

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

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

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

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

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

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

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

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

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

# `init_stream`

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

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

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

# `stream`

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

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

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

---

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