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

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](decisions.md) guide is the place to start.

```elixir
{: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](#module-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`).

```elixir
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`.

# `input`

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

The `{state, questions}` shorthand for a decision.

# `part`

```elixir
@type part() :: Omni.Content.Text.t() | Omni.Content.Data.t()
```

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

# `parts_input`

```elixir
@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`

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

# `new`

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

```elixir
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](#module-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.

---

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