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
endDecoding 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
@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.
@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"
@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.
@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
@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}
@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}]}
@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]}