# `TypeSafeAPI.Question.Noul`
[🔗](https://github.com/typesend/typesafe_ai/blob/v0.1.0-alpha.3/lib/typesafe_api/question/noul.ex#L1)

A yes/no judgment. The instructions may be a question ("Does this convey
urgency?") or a statement to evaluate ("This message contains unsolicited
advertising."); the answer is the probability that the answer is yes, or
that the statement holds.

    TypeSafeAPI.noul("Does this convey urgency?",
      true: "Explicitly time-sensitive",
      false: "No urgency expressed"
    )

TypeSafe's advice: ask for one snap judgment per question. If the
instructions need an "and" or a "but", split them into two Nouls.

Both `instructions` and `criteria` are optional; the API requires only the
question's type. `criteria`, when given, describes what a yes and a no mean;
either description may be a string, map, or list (the API accepts JSON
structure everywhere a description goes), or `nil` when that side of the
judgment speaks for itself.

The criteria keys may be the atoms `true`/`false` or the strings
`"true"`/`"false"` (the shape the API itself uses); both are normalized to
atoms by `new/2` and reach the wire as the JSON keys `"true"` and `"false"`.

`TypeSafeAPI.noul()` builds a Noul with neither instructions nor criteria. It is
a valid request — the API requires only the type — but it asks the model
nothing in particular, so it is almost never what you want. Criteria alone
are enough, though: `TypeSafeAPI.noul(true: "spam", false: "legitimate")` reads
the keyword list as criteria rather than as instructions.

# `t`

```elixir
@type t() :: %TypeSafeAPI.Question.Noul{
  criteria:
    %{
      optional(true) => TypeSafeAPI.Question.description(),
      optional(false) => TypeSafeAPI.Question.description()
    }
    | nil,
  instructions: TypeSafeAPI.Question.instructions()
}
```

# `new`

```elixir
@spec new(TypeSafeAPI.Question.instructions() | keyword(), keyword() | map() | nil) ::
  t()
```

Builds a Noul question.

`instructions` is optional and may be omitted or `nil`, which sends a Noul
carrying only its type (and its criteria, if any).

## Options

  * `:true` - what a yes (value near 1) means
  * `:false` - what a no (value near 0) means

Either key may also be given as the string `"true"` or `"false"`; both forms
are normalized to atoms. A `nil` description means that side speaks for
itself.

When `criteria` is omitted and `instructions` is a keyword list whose keys
are only `true` and `false`, it is read as the criteria — so
`new(true: "yes", false: "no")` means what it looks like, rather than binding
a keyword list to `instructions`.

Like every constructor here, `new/2` does not validate; a misspelled key is
reported as a `:validation` error by `TypeSafeAPI.evaluate/4`, or raised by
`TypeSafeAPI.Question.validate!/1` when you want to fail early.

# `wire_type`

```elixir
@spec wire_type() :: String.t()
```

The `type` tag this question and its answer carry on the wire.

---

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