Providers

BeamWeaver calls provider APIs directly. Seven integrations generate chat; TypeSafe supplies typed decisions. OpenAI also supplies decisions and embeddings. Choose the operation first, then a model that supports the tools, media and output contract your application needs.

Start with a real call

The OpenAI and Google guides begin with configuration and an executed request. The Quickstart puts the same model behind an agent module. Each provider guide separates its implemented endpoints from native services that require your own executor or resource-management code.

With the OpenAI key configured as in Installation, initialize and invoke a model directly:

model = BeamWeaver.Models.init_chat_model!("openai:gpt-5.4-mini", max_tokens: 128, timeout: 60_000)
{:ok, reply} = BeamWeaver.Core.ChatModel.invoke(model, "Explain a tracking number briefly.")
true = byte_size(BeamWeaver.Core.Message.text(reply)) > 0

Supported providers

This table describes checked-in model profiles. Counts include aliases and snapshots; they are not distinct-model counts or a statement of your account's access. mix beam_weaver.models.profiles prints the local registry. Actual availability is established by an authenticated call.

Model strings

Use an explicit provider:model identifier. Model initialization resolves an adapter and validates local options; it does not authenticate or send an inference request. Some bare names are recognized, but explicit prefixes avoid ambiguity. Known discontinued IDs fail with replacement guidance rather than silently changing models.

Model profiles describe API capabilities. Behavioral capability profiles tune agent prompts/tools. These are different concepts; see Models and Capability Profiles .

Credentials

Configure only the providers your application uses in its own runtime config. An explicit model key overrides its provider's configured key. Missing keys fail before HTTP execution. The library does not automatically read a consumer's .env; repository example scripts have their own credential loader.

Configuration lists provider groups and connection fields. Keep credentials out of source, trace fields and sandbox environments. A custom endpoint must receive credentials intended for that endpoint, not an accidentally inherited production provider key.

Options for every provider

An endpoint: usually means a full request URL; Google treats it as an API root. Reasoning, caching, tool choice and metadata differ by endpoint/model. Consult the dedicated guide before moving options between providers.

Switching and fallback

Change the model identifier and review provider-specific options. Native reasoning blocks are replayed only to compatible provider endpoints; preserving full message objects lets codecs retain the information they need.

ModelFallback changes the model after failure and uses its own credentials. ModelRetry adds bounded retries for failed calls. Gemini Argon also resumes interrupted long-decode hops internally; see Argon continuation . A fallback success does not establish that the primary integration worked. Built-in Middleware explains ordering and budgets.

Run the same provider-neutral request with two actual integrations. Configure both keys before this block:

for spec <- ["openai:gpt-5.4-mini", "google:gemini-3.5-flash"] do
  model = BeamWeaver.Models.init_chat_model!(spec, max_tokens: 256, timeout: 60_000)
  {:ok, reply} = BeamWeaver.Core.ChatModel.invoke(model, "Define parcel tracking in one sentence.")
  true = byte_size(BeamWeaver.Core.Message.text(reply)) > 0
  IO.puts("#{spec}: #{BeamWeaver.Core.Message.text(reply)}")
end

OpenAI-compatible servers

Use BeamWeaver.OpenAI.chat_completions_model/1 for a server implementing that contract. Set the exact endpoint, explicit credentials for that server and a profile describing capabilities you have verified. A server accepting chat does not necessarily support tools, media or native schema output.

Do not send your configured OpenAI key to a third-party endpoint by accident. For an unauthenticated local server, the adapter still needs a nonempty explicit placeholder key. Exercise a real server before claiming its integration works; an HTTP fixture proves only request/response plumbing.

This executable example uses the real OpenAI Chat Completions endpoint explicitly. For a different compatible server, replace all three of endpoint, credentials and model with that server’s values:

model =
  BeamWeaver.OpenAI.chat_completions_model(
    model: "gpt-5.4-mini",
    endpoint: "https://api.openai.com/v1/chat/completions",
    api_key: System.fetch_env!("OPENAI_API_KEY"),
    max_tokens: 128,
    timeout: 60_000
  )

{:ok, reply} = BeamWeaver.Core.ChatModel.invoke(model, "Say hello briefly.")
true = byte_size(BeamWeaver.Core.Message.text(reply)) > 0

Adding a provider

Implement the chat, embedding or decision behavior and a Provider.Adapter that resolves its model modules and profiles. Register the adapter at startup through application configuration or Provider.Registry. Each supported operation needs a real implementation; declaring a prefix or profile does not create an API capability.

Use provider-native error/outcome contracts, preserve replay-critical content, and implement streaming cancellation correctly. Test controlled adapter cases and actual live calls separately. Testing describes those boundaries.

This complete adapter registers an application prefix and forwards to the actual OpenAI implementation. It demonstrates registry dispatch without inventing a remote model or returning a canned answer:

defmodule MyApp.ChatAdapter do
  @behaviour BeamWeaver.Provider.Adapter
  @impl true
  def provider, do: :app_openai
  @impl true
  def chat_model(_opts), do: {:ok, BeamWeaver.OpenAI.ChatModel}
  @impl true
  def profile(id), do: BeamWeaver.Models.ProfileRegistry.fetch(:openai, id)
end

:ok = BeamWeaver.Provider.Registry.register(:app_openai, MyApp.ChatAdapter)

try do
  {:ok, model} = BeamWeaver.Models.init_chat_model("app_openai:gpt-5.4-mini", max_tokens: 128, timeout: 60_000)
  {:ok, reply} = BeamWeaver.Core.ChatModel.invoke(model, "Say hello briefly.")
  true = byte_size(BeamWeaver.Core.Message.text(reply)) > 0
after
  BeamWeaver.Provider.Registry.unregister(:app_openai)
end