Omni.Dialect behaviour (Omni v2.0.0)

Copy Markdown View Source

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:

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:

Decision:

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
end

A 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

auth()

@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.

compat_schema()

@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]}}}
end

Return an empty map if the dialect has no flags.

Functions

capability(module)

@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

compat(model, dialect)

@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")

get(name)

@spec get(String.t()) :: {:ok, module()} | {:error, {:unknown_dialect, String.t()}}

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".

get!(name)

@spec get!(String.t()) :: module()

Resolves a dialect's string id to its module, raising if there is none.