Omni.Decision (Omni v2.0.0)

Copy Markdown View Source

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 of Omni.Question structs. The key names the question, and the list's order is kept
  • :answers - a keyword list aligned with :questions, one Omni.Answer struct per question; nil until answered
  • :usage - the request's Omni.Usage; nil until answered
  • :model - the Omni.Model that answered; nil until answered
  • :raw - the {%Req.Request{}, %Req.Response{}} pair when decide/3 is called with raw: true, else nil

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.

t()

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

input()

@type input() :: {state :: parts_input(), questions :: [{atom(), Omni.Question.t()}]}

The {state, questions} shorthand for a decision.

part()

A part of the state or of a question's instructions.

parts_input()

@type parts_input() :: String.t() | map() | part() | [String.t() | map() | part()]

Parts as given to a constructor: a string, a map, a part, or a list of them.

t()

@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

new(decision)

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