LlmComposer.Provider behaviour (llm_composer v0.19.3)

Copy Markdown View Source

Behaviour for provider modules used by LlmComposer.

A provider is responsible for:

Required callbacks

  • name/0: returns the provider atom (for example, :open_ai, :google).
  • run/3: executes one completion request.

run/3 receives:

  • messages: user/assistant/tool messages,
  • system_message: system prompt message (or nil),
  • opts: provider options (model, credentials, request params, stream flag, etc.).

It must return:

  • {:ok, %LlmComposer.LlmResponse{}} on success,
  • {:error, reason} on failure.

Minimal implementation shape

defmodule LlmComposer.Providers.MyProvider do
  @behaviour LlmComposer.Provider

  @impl LlmComposer.Provider
  def name, do: :my_provider

  @impl LlmComposer.Provider
  def run(messages, system_message, opts) do
    # 1) validate required opts (for example, :model / auth)
    # 2) build provider request from messages + system_message
    # 3) call API and map result into {:ok, %{response: body}} | {:error, reason}
    # 4) normalize through your ProviderResponse adapter
  end
end

For consistency with built-in providers, implement a LlmComposer.ProviderResponse.* adapter so provider-specific payloads are parsed into LlmComposer.LlmResponse. If streaming is supported, also add a LlmComposer.ProviderStreamChunk.* adapter.

Summary

Callbacks

name()

Returns the atom that uniquely identifies this provider (e.g. :open_ai, :google).

run(list, arg2, keyword)

Executes a single completion request.

Callbacks

name()

@callback name() :: atom()

Returns the atom that uniquely identifies this provider (e.g. :open_ai, :google).

run(list, arg2, keyword)

@callback run([LlmComposer.Message.t()], LlmComposer.Message.t() | nil, keyword()) ::
  {:ok, LlmComposer.LlmResponse.t()} | {:error, term()}

Executes a single completion request.

Receives normalized messages and returns a normalized response or an error.

  • messages — list of LlmComposer.Message structs (user/assistant/tool turns).
  • system_message — system prompt as a LlmComposer.Message, or nil.
  • opts — keyword list of provider options (:model, credentials, :stream_response, etc.).