A decision: typed questions about a shared state, and their answers.
The same struct is the request and the result. Omni.decide/3 takes a
{state, questions} tuple, or a decision built with new/1, and returns
the decision with :answers, :usage and :model filled in. The
Decisions guide is the place to start.
{:ok, decision} =
Omni.decide({:openrouter, "typesafe/jev-1.14"}, {ticket_text, [
urgent: Omni.predicate("Does this need a reply within the hour?"),
team: Omni.choice("Which team owns this?", [:billing, :infra, :other])
]})
decision.answers[:urgent] #=> %Omni.Answer.Predicate{probability: 0.91}Struct fields
:state- the parts every question is asked about (see State):questions- a keyword list ofOmni.Questionstructs. The key names the question, and the list's order is kept:answers- a keyword list aligned with:questions, oneOmni.Answerstruct per question;niluntil answered:usage- the request'sOmni.Usage;niluntil answered:model- theOmni.Modelthat answered;niluntil answered:raw- the{%Req.Request{}, %Req.Response{}}pair whendecide/3is called withraw: true, elsenil
State
The state is the shared input every question is asked about: a list of
parts, each an Omni.Content.Text or Omni.Content.Data. new/1 builds
them from plain values, so the state can be given as
- a string, for one text part
- a map, for one data part, sent as JSON
- a list of strings, maps and parts, for a part each, in order
To send an array as data, put it in a map: %{readings: [3, 5, 8]}.
Question instructions are parts in the same way (see Omni.Question).
Decision.new({["Ticket from an enterprise customer:", %{subject: "Refund"}], questions})
#=> %Decision{state: [%Text{text: "Ticket from ..."}, %Data{data: %{"subject" => "Refund"}}], ...}Validation
Omni.decide/3 checks a decision before sending it. It needs a state, at
least one question, instructions for every question, and two or more
options for a choice or score. A decision that fails returns
{:error, reason} with no request made.
Providers set their own limits on how many questions and options a request may hold, and report them as HTTP errors.
Persist a decision with Omni.Codec, which stores everything but :raw.
Summary
Types
The {state, questions} shorthand for a decision.
A part of the state or of a question's instructions.
Parts as given to a constructor: a string, a map, a part, or a list of them.
A decision request, and once answered its result.
Functions
Creates a decision from a {state, questions} tuple, a keyword list or
map of fields, or an existing decision.
Types
@type input() :: {state :: parts_input(), questions :: [{atom(), Omni.Question.t()}]}
The {state, questions} shorthand for a decision.
@type part() :: Omni.Content.Text.t() | Omni.Content.Data.t()
A part of the state or of a question's instructions.
Parts as given to a constructor: a string, a map, a part, or a list of them.
@type t() :: %Omni.Decision{ answers: [{atom(), Omni.Answer.t()}] | nil, model: Omni.Model.t() | nil, questions: [{atom(), Omni.Question.t()}], raw: {Req.Request.t(), Req.Response.t()} | nil, state: [part()] | nil, usage: Omni.Usage.t() | nil }
A decision request, and once answered its result.
Functions
@spec new(t() | input() | Enumerable.t()) :: t()
Creates a decision from a {state, questions} tuple, a keyword list or
map of fields, or an existing decision.
Omni.Decision.new({"I was charged twice", [refund: Omni.predicate("Is this a refund request?")]})
Omni.Decision.new(state: %{subject: "Refund"}, questions: [...])The state and every question's instructions are built into parts (see
State), which is safe to repeat on an existing decision.
Raises if a map holds a value JSON can't encode (see
Omni.Content.Data.new/1). Does not validate; Omni.decide/3 does.