LLM.Adapter behaviour (LLM v0.2.0)

Behaviour for wire format translation between normalized messages and provider APIs.

Each adapter handles:

Encoding LLM.Context into provider-specific JSON request bodies
Providing the streaming endpoint path and extra headers
Decoding full responses back into LLM.Response.t()
Decoding SSE chunks back into normalized stream structs

Built-in adapters:

Module	Provider API
`LLM.Adapter.OpenAI`	OpenAI Chat Completions
`LLM.Adapter.OpenAIResponse`	OpenAI Responses API
`LLM.Adapter.Anthropic`	Anthropic Messages API
`LLM.Adapter.Gemini`	Google Gemini API

Implementing a custom adapter

Implement all required callbacks plus any optional ones your provider needs:

defmodule MyApp.Adapter do
  @behaviour LLM.Adapter

  @impl true
  def build_request(context, opts) do
    %{
      "model" => Keyword.fetch!(opts, :model),
      "messages" => encode_messages(context)
    }
  end

  @impl true
  def decode_response(%{"choices" => [choice | _]} = raw) do
    {:ok,
     %LLM.Response{
       message: %LLM.Message{role: :assistant, content: choice["text"]},
       raw: raw
     }}
  end

  @impl true
  def stream_path, do: "/v1/chat/completions"

  @impl true
  def stream_headers(_opts), do: [{"content-type", "application/json"}]

  @impl true
  def decode_chunk("data: [DONE]", _state), do: {:done, %{}}
  def decode_chunk("data: " <> json, state) do
    # Parse SSE data and return normalized chunks
    {[%LLM.Stream.Chunk{text: text}], state}
  end
end

Summary

Types

chunk_type()

model_info()

Callbacks

auth_headers(map, keyword)

Return authentication headers for the provider.

build_request(t, keyword)

Build the request body from a context and options.

decode_chunk(t)

Decode a single SSE event (stateless variant).

decode_chunk(t, map)

Decode a single SSE event into stream chunks.

decode_response(map)

Decode a full (non-streaming) response from the provider.

init_stream_state()

Initialize the adapter state for a new streaming request.

list_models(map)

List available models from the provider.

non_stream_path()

Return the non-streaming endpoint path.

normalize_thinking(term)

Normalize a thinking/reasoning option to the provider's expected format.

stream_headers(keyword)

Return extra HTTP headers needed for the streaming request.

stream_path()

Return the streaming endpoint path (e.g., "/v1/chat/completions").

Functions

extract_schema(schema)

Extract the name and schema from a structured output spec.

Types

chunk_type()

@type chunk_type() ::
  LLM.Stream.Chunk.t()
  | LLM.Stream.ToolCall.t()
  | LLM.Stream.Thinking.t()
  | LLM.Stream.Stop.t()
  | LLM.Stream.Error.t()

model_info()

@type model_info() :: %{
  id: String.t(),
  name: String.t() | nil,
  description: String.t() | nil,
  context_window: non_neg_integer() | nil,
  max_output: non_neg_integer() | nil,
  capabilities: [atom()] | nil
}

Callbacks

auth_headers(map, keyword)

(optional)

@callback auth_headers(
  map(),
  keyword()
) :: [{String.t(), String.t()}]

Return authentication headers for the provider.

Receives the provider config map and options. Returns a list of header tuples.

build_request(t, keyword)

@callback build_request(
  LLM.Context.t(),
  keyword()
) :: map()

Build the request body from a context and options.

Receives an LLM.Context.t() and a keyword list of options (including :model). Returns a map suitable for Jason.encode!/1.

decode_chunk(t)

(optional)

@callback decode_chunk(String.t()) :: [chunk_type()] | :done

Decode a single SSE event (stateless variant).

Used by adapters that don't need to track state across chunks.

decode_chunk(t, map)

@callback decode_chunk(String.t(), map()) :: {[chunk_type()] | :done, map()}

Decode a single SSE event into stream chunks.

Receives the raw SSE data string and adapter state. Returns a tuple of {chunks, new_state} where chunks is a list of stream structs or :done, or {:done, new_state} to signal end of stream.

decode_response(map)

@callback decode_response(map()) :: {:ok, LLM.Response.t()} | {:error, term()}

Decode a full (non-streaming) response from the provider.

Receives the decoded JSON response body. Returns {:ok, LLM.Response.t()} or {:error, reason}.

init_stream_state()

(optional)

@callback init_stream_state() :: map()

Initialize the adapter state for a new streaming request.

Called once when a stream starts. The state is passed to decode_chunk/2.

list_models(map)

(optional)

@callback list_models(map()) :: {:ok, [model_info()]} | {:error, term()}

List available models from the provider.

Returns {:ok, [model_info()]} or {:error, reason}. Not all providers support this — implement as a no-op if unsupported.

non_stream_path()

(optional)

@callback non_stream_path() :: String.t()

Return the non-streaming endpoint path.

If unimplemented, defaults to the streaming path. May contain {model} which is replaced with the actual model name.

normalize_thinking(term)

(optional)

@callback normalize_thinking(term()) :: term()

Normalize a thinking/reasoning option to the provider's expected format.

Maps atoms like :low, :medium, :high to provider-specific values.

stream_headers(keyword)

@callback stream_headers(keyword()) :: [{String.t(), String.t()}]

Return extra HTTP headers needed for the streaming request.

Content-Type and auth headers are added separately by LLM.Stream.

stream_path()

@callback stream_path() :: String.t()

Return the streaming endpoint path (e.g., "/v1/chat/completions").

May contain {model} which is replaced with the actual model name.

Functions

extract_schema(schema)

@spec extract_schema(map()) :: {String.t(), map()}

Extract the name and schema from a structured output spec.

Handles three shapes:

%{name: name, schema: schema} (atom keys)
%{"name" => name, "schema" => schema} (string keys)
A bare schema map (defaults to name "output")