Behaviour for wire format translation between Omni types and provider APIs.
A dialect handles the pure data transformation layer: building request bodies from Omni structs and reading what the API sends back. Each dialect corresponds to one API format (e.g. Anthropic Messages, OpenAI Chat Completions) and serves one capability:
Omni.Dialect.Text- text generation, streamed (Omni.stream_text/3)Omni.Dialect.Decision- decisions: typed questions answered with probabilities (Omni.decide/3)
This module is the base every dialect shares: how the home API
authenticates (auth/0) and the compat flags it understands
(compat_schema/0), plus the registry and compat/2. The capability
behaviour adds the callbacks that build requests and read responses.
Most new integrations need a provider, not a dialect: a provider that speaks one of the formats below is a matter of config (see Providers and models). Write a dialect only for a wire format none of them cover.
Available dialects
Text:
Omni.Dialects.OpenAICompletions- OpenAI Chat Completions format, used by most third-party providers (Groq, Together, Fireworks, DeepSeek, etc.)Omni.Dialects.OpenAIResponses- OpenAI's newer Responses API formatOmni.Dialects.AnthropicMessages- Anthropic Messages formatOmni.Dialects.GoogleGenerateContent- Gemini APIgenerateContentformatOmni.Dialects.OllamaChat- Ollama native chat format (NDJSON streaming)
Decision:
Omni.Dialects.TypeSafeSystemOne- TypeSafe's System One format, served by TypeSafe, OpenRouter, OpenCode Zen, Ollama and othersOmni.Dialects.OpenAIDecisions- OpenAI's Decisions API
Dialect registry
Each built-in dialect has a string id, such as "anthropic_messages" or
"typesafe_system_one", for naming it in catalog data. get/1 and
get!/1 turn an id into its module. Model sources use them (see
Omni.Source.build_model/1).
Compat flags
Providers that speak a dialect with small deviations from its home API
describe them as compat flags, which the dialect declares in
compat_schema/0 and reads with compat/2 while it encodes. Flags are
set per endpoint (see Omni.Provider.Endpoint) and validated against the
schema when the provider loads. See
Omni.Dialects.OpenAICompletions for the flags it understands.
Implementing a dialect
use Omni.Dialect with the capability the dialect serves. It declares
both behaviours, this one and the capability's, and nothing more:
defmodule MyApp.Dialects.CustomFormat do
use Omni.Dialect, :text
@impl true
def auth, do: :bearer
@impl true
def compat_schema, do: %{}
# ...and the callbacks of Omni.Dialect.Text
endA dialect serves exactly one capability. A provider that serves two lists
a dialect for each. See Omni.Dialect.Text and Omni.Dialect.Decision
for the callbacks and full examples.
Summary
Callbacks
Returns how this dialect's home API expects the API key to be sent.
Returns a Peri schema map for the compat flags this dialect understands.
Functions
Returns the capability a dialect module serves.
Returns the compat flags a provider has set for a dialect.
Resolves a dialect's string id to its module.
Resolves a dialect's string id to its module, raising if there is none.
Callbacks
@callback auth() :: :bearer | {:header, String.t()}
Returns how this dialect's home API expects the API key to be sent.
Used for providers whose :auth is :dialect (the default). A provider
speaking a dialect then authenticates the way the dialect's own API does,
and a gateway serving several dialects authenticates each model
correctly:
def auth, do: {:header, "x-api-key"}Return :bearer for an Authorization: Bearer <key> header, or
{:header, name} to send the raw key on a named header.
@callback compat_schema() :: Peri.map_schema()
Returns a Peri schema map for the compat flags this dialect understands.
A provider's :compat flags for the dialect are validated against it when
the provider loads; unknown flags are a boot error. Each flag describes a
deviation from the dialect's home API, so an absent flag means home-API
behaviour:
def compat_schema do
%{max_tokens_field: :string, omit: {:list, {:enum, [:cache]}}}
endReturn an empty map if the dialect has no flags.
Functions
@spec capability(module()) :: :text | :decision | nil
Returns the capability a dialect module serves.
Read from the capability behaviour the module declares (see
use Omni.Dialect). Returns nil for a module that is not a dialect.
Omni.Dialect.capability(Omni.Dialects.AnthropicMessages) #=> :text
Omni.Dialect.capability(Omni.Dialects.TypeSafeSystemOne) #=> :decision
@spec compat(Omni.Model.t(), module()) :: map()
Returns the compat flags a provider has set for a dialect.
Reads the flags of the provider's endpoint for the dialect, returning %{}
when it sets none (or the model has no provider):
compat = Omni.Dialect.compat(model, __MODULE__)
field = Map.get(compat, :max_tokens_field, "max_completion_tokens")
Resolves a dialect's string id to its module.
The built-in ids: "anthropic_messages", "openai_completions",
"openai_responses", "google_generate_content", "ollama_chat",
"typesafe_system_one", "openai_decisions".
Resolves a dialect's string id to its module, raising if there is none.