TypeSafe.Question (TypeSafe v0.2.2)

Questions asked about a piece of state in a TypeSafe.system_one/4 request.

There are three question primitives, each with its own struct and a constructor here:

noul/1 — a yes/no question. See the noul primitive.
choice/1 — selects one of several named labels. See the choice primitive.
score/1 — rates the state against an ordered rubric. See the score primitive.

Each accepts a keyword list. :instructions is always optional and may be a string, a map, or a list. choice/1 and score/1 require :criteria.

iex> TypeSafe.Question.noul(instructions: "Is this message spam?")
%TypeSafe.Question.Noul{type: "noul", instructions: "Is this message spam?", criteria: nil}

iex> TypeSafe.Question.choice(instructions: "What is the tone?", criteria: %{"angry" => nil})
%TypeSafe.Question.Choice{type: "choice", instructions: "What is the tone?", criteria: %{"angry" => nil}}

iex> TypeSafe.Question.score(instructions: "How urgent?", criteria: ["low", "high"])
%TypeSafe.Question.Score{type: "score", instructions: "How urgent?", criteria: ["low", "high"]}

A question may also be supplied as a raw map with a "type" key (or :type) as an escape hatch for fields the API supports before this SDK models them; such maps are passed through untouched and validated by the API.

Summary

Types

content()

Text, a JSON object, or a JSON array.

t()

A question struct or a raw map passed straight through to the API.

Functions

choice(opts)

Build a choice question that selects one of the labels in :criteria.

normalize(questions)

Validate a questions map before it is sent.

noul(opts \\ [])

Build a yes/no (noul) question.

score(opts)

Build a score question that rates the state against the ordered rubric in :criteria.

Types

content()

@type content() :: String.t() | map() | list()

Text, a JSON object, or a JSON array.

t()

@type t() ::
  TypeSafe.Question.Noul.t()
  | TypeSafe.Question.Choice.t()
  | TypeSafe.Question.Score.t()
  | map()

A question struct or a raw map passed straight through to the API.

Functions

choice(opts)

@spec choice(keyword()) :: TypeSafe.Question.Choice.t()

Build a choice question that selects one of the labels in :criteria.

Options:

:criteria (required) — a map of label => description (or nil for an undescribed label).
:instructions — what to decide; optional.

Raises TypeSafe.ConfigError when :criteria is missing.

normalize(questions)

@spec normalize(map()) :: {:ok, map()} | {:error, TypeSafe.ConfigError.t()}

Validate a questions map before it is sent.

Returns {:ok, questions} unchanged, or {:error, %TypeSafe.ConfigError{}} when the map is empty or a score question is missing/has empty criteria. Struct questions built with the constructors are always valid; raw maps are only lightly checked, leaving full validation to the API.

noul(opts \\ [])

@spec noul(keyword()) :: TypeSafe.Question.Noul.t()

Build a yes/no (noul) question.

Options:

:instructions — the question or statement to evaluate; optional.
:criteria — an optional map describing the yes/no outcomes, e.g. %{true: "unsolicited ad", false: "a real conversation"}.

score(opts)

@spec score(keyword()) :: TypeSafe.Question.Score.t()

Build a score question that rates the state against the ordered rubric in :criteria.

Options:

:criteria (required) — a non-empty, ordered list of level descriptions; the first is score 0.
:instructions — what to rate; optional.

Raises TypeSafe.ConfigError when :criteria is missing or empty.