Agentic.LLM.Provider behaviour (agentic v0.2.2)

Copy Markdown

Behaviour describing one LLM service provider.

Each provider is a small module that declares which transport it uses, points at a base URL, declares env vars for credentials, and optionally implements catalog and usage fetchers.

Required callbacks

  • id/0 — unique atom identifying this provider
  • label/0 — human-readable name
  • transport/0 — the transport module to use
  • default_base_url/0 — base URL for API calls
  • env_vars/0 — env var names in priority order
  • default_models/0 — static seed of known models
  • request_headers/1 — extra headers given resolved credentials
  • supports/0 — MapSet of capability atoms

Optional callbacks

  • fetch_catalog/1 — dynamic model discovery
  • fetch_usage/1 — quota / usage endpoint
  • classify_http_error/3 — provider-specific error overrides

Summary

Callbacks

classify_http_error(arg1, term, term)
default_base_url()
default_models()
env_vars()
fetch_catalog(t)
fetch_usage(t)
id()
label()
request_headers(t)
supports()
transport()

Functions

chat(provider, params, opts \\ [])

Call a provider's chat via its declared transport.

stream_chat(provider, params, opts \\ [])

Streaming variant of chat/3.

Callbacks

classify_http_error(arg1, term, term)

(optional) 
@callback classify_http_error(non_neg_integer() | nil, term(), term()) ::
  {atom(), non_neg_integer() | nil} | :default

default_base_url()

@callback default_base_url() :: String.t() | nil

default_models()

@callback default_models() :: [Agentic.LLM.Model.t()]

env_vars()

@callback env_vars() :: [String.t()]

fetch_catalog(t)

(optional) 
@callback fetch_catalog(Agentic.LLM.Credentials.t()) ::
  {:ok, [Agentic.LLM.Model.t()]} | {:error, term()} | :not_supported

fetch_usage(t)

(optional) 
@callback fetch_usage(Agentic.LLM.Credentials.t()) :: {:ok, term()} | :not_supported

id()

@callback id() :: atom()

label()

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

request_headers(t)

@callback request_headers(Agentic.LLM.Credentials.t()) :: [{String.t(), String.t()}]

supports()

@callback supports() :: MapSet.t(atom())

transport()

@callback transport() :: module()

Functions

chat(provider, params, opts \\ [])

@spec chat(provider :: module(), params :: map(), opts :: keyword()) ::
  {:ok, Agentic.LLM.Transport.request()} | {:error, term()}

Call a provider's chat via its declared transport.

Builds the canonical params, resolves credentials, delegates to the transport for request building and response parsing, and performs the HTTP call.

stream_chat(provider, params, opts \\ [])

Streaming variant of chat/3.

Calls the provider with stream: true and invokes on_chunk.(text_delta) for each text chunk received. Returns the complete {:ok, Response.t()} at the end, same as chat/3.

The on_chunk callback in opts receives each text delta as a binary.