@spec choice(TypeSafeAPI.Question.instructions(), [
  TypeSafeAPI.Question.Choice.option() | TypeSafeAPI.Keys.key()
]) :: TypeSafeAPI.Question.Choice.t()

Pick one option from criteria, a keyword list (or list of pairs) of option key to description; nil when the key speaks for itself. A bare list of option names works too, and means the same as pairing each with nil. Order is preserved. instructions is optional and may be nil. See TypeSafeAPI.Question.Choice.

@spec evaluate(
  TypeSafeAPI.Client.t(),
  TypeSafeAPI.SystemOne.state(),
  TypeSafeAPI.Question.input() | TypeSafeAPI.SystemOne.Prepared.t(),
  keyword()
) :: {:ok, TypeSafeAPI.Result.t()} | {:error, TypeSafeAPI.Error.t()}

Evaluates state against questions and returns a TypeSafeAPI.Result.

state is a string or JSON-shaped map or list — a struct, tuple, keyword list or charlist is a :validation error, since none of them has the JSON representation the API is being sent. questions is a keyword list (or list of {id, question} pairs); question order is preserved, so a map is not accepted. A TypeSafeAPI.SystemOne.Prepared from prepare/1 is also accepted, and is used as-is rather than validated and encoded again.

Nothing on this path raises. A malformed question, a state that cannot be encoded, and an option not in the list below all return {:error, %TypeSafeAPI.Error{type: :validation}} with no request sent. A response this library cannot decode against the questions it asked — an answer missing, a probability that is not a number, an option or level the question never declared — is {:error, %TypeSafeAPI.Error{type: :unexpected}} carrying the response's request_id and the body.

Options

• :model (String.t/0) - Model for this call; defaults to the client's model.

• :timeout (pos_integer/0) - Timeout in milliseconds for this call.

• :retry - Retry policy for this call; see TypeSafeAPI.Retry.new/1.

• :req_options (keyword/0) - Extra Req options for this call.

• :telemetry (map/0) - Extra metadata merged into telemetry events.

@spec evaluate!(
  TypeSafeAPI.Client.t(),
  TypeSafeAPI.SystemOne.state(),
  TypeSafeAPI.Question.input(),
  keyword()
) :: TypeSafeAPI.Result.t()

Like evaluate/4 but returns the result or raises the TypeSafeAPI.Error.

This is the only one of the two that raises, and it raises for every failure alike: a validation mistake caught locally, an HTTP error, and a response that would not decode all arrive as the same TypeSafeAPI.Error exception.

@spec evaluate_many(
  TypeSafeAPI.Client.t(),
  Enumerable.t(),
  TypeSafeAPI.Question.input() | TypeSafeAPI.SystemOne.Prepared.t(),
  keyword()
) :: [TypeSafeAPI.FanOut.outcome()] | {:error, TypeSafeAPI.Error.t()}

Evaluates many states against one question set, concurrently, and returns one outcome per state in input order. See TypeSafeAPI.FanOut for how errors, timeouts and exhausted retries surface.

questions may also be a %TypeSafeAPI.SystemOne.Prepared{} from TypeSafeAPI.SystemOne.prepare/1, already validated and encoded.

An invalid question set fails before anything is sent, so it comes back as a bare {:error, error} rather than a list of outcomes; on_error: :raise raises it instead.

Options

• :max_concurrency (pos_integer/0) - Maximum number of in-flight requests. A guess; see the module docs. The default value is 8.

• :task_timeout - Cap in milliseconds on one state's whole task, covering every retry and delay. Defaults to the retry budget plus one attempt timeout, or 60 000 when the budget is disabled. Not to be confused with :timeout, which is one HTTP attempt, as in TypeSafeAPI.evaluate/4.

• :ordered (boolean/0) - Return results in input order. false yields them as they finish. The default value is true.

• :on_error - :collect returns error tuples in place; :raise raises the first error. The default value is :collect.

Every other option is passed through to each individual call, so :model, :timeout, :retry, :req_options and :telemetry mean exactly what they mean in evaluate/4. :timeout is still one HTTP attempt; the cap on a whole state, retries included, is :task_timeout above.

@spec models(TypeSafeAPI.Client.t(), keyword()) ::
  {:ok, [TypeSafeAPI.Model.t()]} | {:error, TypeSafeAPI.Error.t()}

Lists the models available to the account.

An entry this library cannot decode is logged and skipped rather than failing the list. See TypeSafeAPI.Models.list/2 for the per-call options.

@spec models!(TypeSafeAPI.Client.t(), keyword()) :: [TypeSafeAPI.Model.t()]

Like models/2 but returns the list or raises the TypeSafeAPI.Error.

@spec new(keyword()) :: TypeSafeAPI.Client.t()

Builds a TypeSafeAPI.Client.

With no options, configuration comes from application config and the TYPESAFE_API_KEY, TYPESAFE_BASE_URL, and TYPESAFE_DEFAULT_MODEL environment variables. See TypeSafeAPI.Client.new/1 for all options.

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

A yes/no judgment on a question ("Does this convey urgency?") or a statement ("This message contains unsolicited advertising."). instructions is optional, as are the true: and false: descriptions that say what each answer means. Criteria alone are enough: noul(true: "spam", false: "legit") reads the keyword list as criteria, not as instructions. See TypeSafeAPI.Question.Noul.

@spec prepare(TypeSafeAPI.Question.input()) ::
  {:ok, TypeSafeAPI.SystemOne.Prepared.t()} | {:error, TypeSafeAPI.Error.t()}

Validates and encodes a question set once, for reuse across many calls.

Returns a TypeSafeAPI.SystemOne.Prepared, which holds the normalized questions, their wire bytes and the key registry that maps answers back to the ids you used. Preparing at boot (in a module attribute, or in a GenServer's state) turns a malformed question set into a startup failure instead of a per-request one, and keeps the encoding cost out of the request path:

{:ok, prepared} = TypeSafeAPI.prepare(urgent: TypeSafeAPI.noul("Urgent?"))
TypeSafeAPI.SystemOne.evaluate_prepared(client, "the ticket text", prepared)

Treat the result as opaque: it is four fields that must agree with each other, and nothing revalidates them if you rewrite one.

@spec score(TypeSafeAPI.Question.instructions(), [TypeSafeAPI.Question.Score.level()]) ::
  TypeSafeAPI.Question.Score.t()

Rate the state along levels, an ordered list of two to ten level descriptions from low to high. instructions is optional and may be nil. See TypeSafeAPI.Question.Score.