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

Behaviour for decision dialects.

A decision dialect turns an `Omni.Decision` (shared state plus typed
questions) into one JSON request, and reads the JSON response back into
answers and usage. There is no streaming: the whole response arrives at
once. Declare it with `use Omni.Dialect, :decision`, which also sets the
base `Omni.Dialect` behaviour (`c:Omni.Dialect.auth/0`,
`c:Omni.Dialect.compat_schema/0`).

## Implementing a decision dialect

Like text dialects, decision dialects are stateless and pure: no HTTP, no
configuration, no side effects.

```elixir
defmodule MyApp.Dialects.CustomDecisions do
  use Omni.Dialect, :decision

  alias Omni.{Answer, Decision, Question, Usage}
  alias Omni.Content.{Data, Text}

  @impl true
  def option_schema, do: %{}

  @impl true
  def compat_schema, do: %{}

  @impl true
  def auth, do: :bearer

  @impl true
  def handle_path(_model, _opts), do: "/decide"

  @impl true
  def handle_body(model, %Decision{} = decision, _opts) do
    %{
      "model" => model.id,
      "input" => Enum.map(decision.state, &encode_part/1),
      "questions" => Enum.map(decision.questions, &encode_question/1)
    }
  end

  defp encode_part(%Text{text: text}), do: text
  defp encode_part(%Data{data: data}), do: data

  @impl true
  def handle_response(%{"answers" => answers} = body, %Decision{} = decision, _model) do
    with {:ok, answers} <-
           Omni.Dialect.Decision.decode_answers(decision.questions, answers, &decode_answer/2) do
      usage = Usage.new(input_tokens: body["usage"]["input_tokens"])
      {:ok, %{decision | answers: answers, usage: usage}}
    end
  end

  defp decode_answer(%Question.Predicate{}, %{"probability" => p}) when is_number(p),
    do: {:ok, Answer.Predicate.new(probability: p * 1.0)}

  defp decode_answer(%Question.Choice{choices: choices}, answer) do
    with {:ok, choice} <- Omni.Dialect.Decision.choice_key(choices, answer["choice"]),
         {:ok, probabilities} <-
           Omni.Dialect.Decision.probabilities(choices, answer["probabilities"], :key) do
      {:ok, Answer.Choice.new(choice: choice, probabilities: probabilities)}
    end
  end

  defp decode_answer(_question, _answer), do: :error
end
```

## Decoding answers

`decode_answers/3` applies the strict rule every decision dialect follows:
each question has exactly one answer of its type, and no answer is for a
question that wasn't asked. Index the wire answers by question name and
decode one at a time; `choice_key/2` and `probabilities/3` map wire values
back to the caller's option keys, in the caller's order. Numbers come back
as floats, since hosts send `1` and `0` as JSON integers.

# `handle_body`

```elixir
@callback handle_body(Omni.Model.t(), Omni.Decision.t(), map()) :: map()
```

Builds the request body from a model, a decision, and validated options.

The decision has been validated: its state and every question's
instructions are non-empty lists of `Omni.Content.Text` and
`Omni.Content.Data` parts, it has at least one question, and every choice
or score question has at least two options. Encode each question under a
name the response can be matched back by. The returned map may be further
adjusted by the provider module's `c:Omni.Provider.modify_body/4` before
being sent as JSON.

# `handle_path`

```elixir
@callback handle_path(Omni.Model.t(), map()) :: String.t()
```

Returns the URL path for the given model and options.

The path is the API's resource path, appended to the base URL of the
provider's endpoint for the dialect:

```elixir
def handle_path(_model, _opts), do: "/systemone"
```

# `handle_response`

```elixir
@callback handle_response(body :: map(), Omni.Decision.t(), Omni.Model.t()) ::
  {:ok, Omni.Decision.t()} | {:error, term()}
```

Reads a decoded response body into the decision.

Fills `:answers` (a keyword list aligned with `decision.questions`, one
`Omni.Answer` struct per question) and `:usage` (an `Omni.Usage` with
token counts only; Omni computes costs from the model's pricing). Return
`{:error, {:invalid_answer, name}}` when an answer is missing, unexpected,
or of the wrong type for its question.

# `option_schema`

```elixir
@callback option_schema() :: Peri.map_schema()
```

Returns a Peri schema map for dialect-specific options.

The returned schema is merged with Omni's config options (`:api_key`,
`:host`, `:headers`, `:timeout`, ...) and validated in a single pass. Text
generation options such as `:max_tokens` are not part of a decision
request. Return an empty map if the dialect has no options:

```elixir
def option_schema, do: %{safety_identifier: :string}
```

# `choice_key`

```elixir
@spec choice_key([Omni.Question.option()], term()) ::
  {:ok, Omni.Question.key()} | :error
```

Returns the caller's key for a wire choice string.

```elixir
Omni.Dialect.Decision.choice_key([yes: nil, no: nil], "no")
#=> {:ok, :no}
```

# `decode_answers`

```elixir
@spec decode_answers(
  [{atom(), Omni.Question.t()}],
  %{required(String.t()) =&gt; map()},
  (Omni.Question.t(), map() -&gt; {:ok, Omni.Answer.t()} | :error)
) ::
  {:ok, [{atom(), Omni.Answer.t()}]}
  | {:error, {:invalid_answer, atom() | String.t()}}
```

Decodes wire answers into a keyword list aligned with `questions`.

`by_name` maps each question name, as a string, to its wire answer;
`decode` turns one question and its wire answer into `{:ok, answer}` or
`:error`. Returns `{:error, {:invalid_answer, name}}` for the first
question without a decodable answer, or for an answer to a question that
wasn't asked (named by its wire string).

```elixir
Omni.Dialect.Decision.decode_answers(
  [ok?: %Omni.Question.Predicate{instructions: []}],
  %{"ok?" => %{"probability" => 1}},
  fn _question, %{"probability" => p} -> {:ok, Omni.Answer.Predicate.new(probability: p * 1.0)} end
)
#=> {:ok, [ok?: %Omni.Answer.Predicate{probability: 1.0}]}
```

# `probabilities`

```elixir
@spec probabilities([Omni.Question.option()], term(), :key | :index) ::
  {:ok, [{Omni.Question.key(), float()}]} | :error
```

Returns `{key, probability}` for every option, in the caller's order.

The wire map is keyed by each option's key as a string (`:key`) or by its
index as a string (`:index`). Every option must have a number.

```elixir
Omni.Dialect.Decision.probabilities([yes: nil, no: nil], %{"yes" => 1, "no" => 0}, :key)
#=> {:ok, [yes: 1.0, no: 0.0]}

Omni.Dialect.Decision.probabilities([low: nil, high: nil], %{"0" => 0.2, "1" => 0.8}, :index)
#=> {:ok, [low: 0.2, high: 0.8]}
```

---

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