# `Omni.Dialect`
[🔗](https://github.com/aaronrussell/omni/blob/v2.0.0/lib/omni/dialect.ex#L1)

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 (`c:auth/0`) and the compat flags it understands
(`c: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](providers-and-models.md)). 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 format
- `Omni.Dialects.AnthropicMessages` - Anthropic Messages format
- `Omni.Dialects.GoogleGenerateContent` - Gemini API `generateContent` format
- `Omni.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 others
- `Omni.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
`c: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:

```elixir
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.

# `auth`

```elixir
@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:

```elixir
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`

```elixir
@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:

```elixir
def compat_schema do
  %{max_tokens_field: :string, omit: {:list, {:enum, [:cache]}}}
end
```

Return an empty map if the dialect has no flags.

# `capability`

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

```elixir
Omni.Dialect.capability(Omni.Dialects.AnthropicMessages)  #=> :text
Omni.Dialect.capability(Omni.Dialects.TypeSafeSystemOne)  #=> :decision
```

# `compat`

```elixir
@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):

```elixir
compat = Omni.Dialect.compat(model, __MODULE__)
field = Map.get(compat, :max_tokens_field, "max_completion_tokens")
```

# `get`

```elixir
@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!`

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

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*
