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

Typed questions for `Omni.decide/3`.

A decision asks one or more questions about a shared state. Each question
is a struct, and its type decides the shape of its answer. The
[Decisions](decisions.md#questions) guide introduces each type.

- `Omni.Question.Predicate` - yes or no, answered with a probability
- `Omni.Question.Choice` - one of a set of choices, answered with a
  probability for each
- `Omni.Question.Score` - a rating on an ordered scale, answered with a
  probability for each level and their weighted average

Build them with `Omni.predicate/2`, `Omni.choice/2` and `Omni.score/2`,
which delegate to each struct's `new/2`:

```elixir
[
  urgent: Omni.predicate("Does this need a reply within the hour?"),
  team: Omni.choice("Which team owns this?", billing: "Payments and refunds", infra: "Outages", other: nil),
  anger: Omni.score("How angry is the customer?", ["Calm", "Frustrated but civil", "Very angry"])
]
```

Choices and levels take a list of keys, or of `key: description` pairs, or
a mix of both. Keys may be atoms or strings, and the answer uses them as
given. Questions are validated when the decision is sent, not here (see
`Omni.Decision`).

## Instructions

Instructions are parts, like the state (see `Omni.Decision`): a string is
one text part, a map one data part sent as JSON, and a list gives a part
for each item. The constructors build them, so the struct holds
`[%Omni.Content.Text{}]` for a string.

```elixir
Omni.predicate(%{question: "Does the ticket report an outage?", field: "ticket.body"})
```

# `instructions`

```elixir
@type instructions() :: [Omni.Decision.part()]
```

Question instructions, as parts (see [Instructions](#module-instructions)).

# `instructions_input`

```elixir
@type instructions_input() :: Omni.Decision.parts_input()
```

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

# `key`

```elixir
@type key() :: atom() | String.t()
```

A choice or level key, as given by the caller.

# `option`

```elixir
@type option() :: {key(), String.t() | nil}
```

A choice or level: its key and an optional description.

# `t`

```elixir
@type t() ::
  Omni.Question.Predicate.t()
  | Omni.Question.Choice.t()
  | Omni.Question.Score.t()
```

A decision question.

---

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