TypeSafe.Question (typesafe_ai v0.1.1)

Copy Markdown View Source

A question about the request's shared state.

Use TypeSafe.choice/2, TypeSafe.score/2, or TypeSafe.noul/2 to construct questions. Instructions and descriptions accept strings, maps, or lists. Choice descriptions may also be nil when the label needs no explanation. Question IDs are string keys and are not used by the model for inference.

Helpers only construct data; validation happens in TypeSafe.system_one/2. The :type field is :choice, :score, or :noul. :instructions describes the evaluation and must not be nil. :criteria depends on the type:

  • Choice: a map with 1–255 non-empty string labels.
  • Score: a list with 2–10 entries in ascending level order.
  • Noul: nil, or a map containing exactly "true" and "false".

Use descriptive strings or structured JSON data for criteria. The local representation also accepts nil descriptions; service-side validation may impose further constraints. Nested values must be encodable by native JSON.

Summary

Types

entry()

An instruction or criterion value; nil is allowed only as a criterion.

t()

Question data constructed by the public helpers.

Advanced integration

to_wire(questions)

Validates question shapes and converts them to their wire representation.

Types

entry()

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

An instruction or criterion value; nil is allowed only as a criterion.

t()

@type t() :: %TypeSafe.Question{
  criteria: term(),
  instructions: entry(),
  type: :choice | :score | :noul
}

Question data constructed by the public helpers.

Advanced integration

to_wire(questions)

@spec to_wire(term()) :: {:ok, map()} | {:error, TypeSafe.Error.t()}

Validates question shapes and converts them to their wire representation.

This is useful for integrations that also call TypeSafe.Response.decode/2. Normal callers use TypeSafe.system_one/2, which performs this step and JSON validation automatically. This function alone does not validate every nested value's JSON encoding.

Returns {:ok, schema} with string question IDs and atom field keys, or {:error, %TypeSafe.Error{kind: :validation}}.

Examples

iex> TypeSafe.Question.to_wire(%{"refund" => TypeSafe.noul("Refund requested?")})
{:ok, %{"refund" => %{type: "noul", instructions: "Refund requested?"}}}