Omni.Dialect.Decision behaviour (Omni v2.0.0)

Copy Markdown View Source

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 (Omni.Dialect.auth/0, 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.

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.

Summary

Callbacks

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

Returns the URL path for the given model and options.

Reads a decoded response body into the decision.

Returns a Peri schema map for dialect-specific options.

Functions

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

Decodes wire answers into a keyword list aligned with questions.

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

Callbacks

handle_body(t, t, map)

@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 Omni.Provider.modify_body/4 before being sent as JSON.

handle_path(t, map)

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

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

handle_response(body, t, t)

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

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

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

Functions

choice_key(options, wire)

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

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

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

decode_answers(questions, by_name, decode)

@spec decode_answers(
  [{atom(), Omni.Question.t()}],
  %{required(String.t()) => map()},
  (Omni.Question.t(), map() -> {: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).

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(options, wire, by)

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

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