ExTypesafe.Question (ExTypesafe v0.2.0)

Copy Markdown View Source

Typed question structs for the TypeSafe API.

TypeSafe supports three question primitives that can be mixed freely in a single request:

Instructions and criterion descriptions can be strings, structured maps, or lists. This makes it possible to keep a question beside the data it references without interpolating that data into a string.

Example

questions = %{
  is_urgent: ExTypesafe.Question.noul("Does this convey urgency?"),
  department: ExTypesafe.Question.choice(
    "Which team should handle this?",
    %{billing: "Payments, invoicing, refunds", technical: "Bugs, outages, integrations"}
  ),
  frustration: ExTypesafe.Question.score(
    "How frustrated is the customer?",
    ["Calm", "Frustrated", "Very angry"]
  )
}

Summary

Types

entry()

A criterion description, including nil for undescribed entries.

instructions()

Question instructions — always required (nil is not accepted).

structured_value()

A JSON-compatible structured value accepted in question content.

t()

Functions

choice(instructions, criteria)

Builds a Choice question.

noul(instructions, criteria \\ nil)

Builds a Noul question (yes/no).

score(instructions, criteria)

Builds a Score question.

Types

entry()

@type entry() :: String.t() | map() | list() | nil

A criterion description, including nil for undescribed entries.

instructions()

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

Question instructions — always required (nil is not accepted).

structured_value()

@type structured_value() :: String.t() | number() | boolean() | nil | map() | list()

A JSON-compatible structured value accepted in question content.

t()

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

Functions

choice(instructions, criteria)

@spec choice(instructions(), map()) :: ExTypesafe.Question.Choice.t()

Builds a Choice question.

Parameters

  • instructions — What the model should decide. Can be a string, structured map, or list.
  • criteria — Map of option name to a rubric description. Use nil for an option needing no description; descriptions can also be structured maps or lists.

Examples

iex> ExTypesafe.Question.choice("Which team should handle this?", %{
...>   billing: "Payments, invoicing, refunds",
...>   technical: "Bugs, outages, integrations"
...> })
%ExTypesafe.Question.Choice{type: "choice", instructions: "Which team should handle this?", criteria: %{billing: "Payments, invoicing, refunds", technical: "Bugs, outages, integrations"}}

noul(instructions, criteria \\ nil)

@spec noul(instructions(), map() | nil) :: ExTypesafe.Question.Noul.t()

Builds a Noul question (yes/no).

Parameters

  • instructions — The yes/no question to evaluate. Can be a string, structured map, or list.
  • criteria — Optional map with :true and/or :false keys describing what each means.

Examples

iex> ExTypesafe.Question.noul("Does this convey urgency?")
%ExTypesafe.Question.Noul{type: "noul", instructions: "Does this convey urgency?", criteria: nil}

iex> ExTypesafe.Question.noul("Is this spam?", %{true: "Clearly promotional", false: "Legitimate message"})
%ExTypesafe.Question.Noul{type: "noul", instructions: "Is this spam?", criteria: %{true: "Clearly promotional", false: "Legitimate message"}}

score(instructions, criteria)

@spec score(instructions(), [entry()]) :: ExTypesafe.Question.Score.t()

Builds a Score question.

Parameters

  • instructions — What the model should rate. Can be a string, structured map, or list.
  • criteria — Ordered list of two to ten level descriptions, low to high. A level description can be a string, structured map, list, or nil.

Examples

iex> ExTypesafe.Question.score("How frustrated is the customer?", ["Calm", "Frustrated", "Very angry"])
%ExTypesafe.Question.Score{type: "score", instructions: "How frustrated is the customer?", criteria: ["Calm", "Frustrated", "Very angry"]}