TypeSafeAPI.Result (TypeSafe AI v0.1.0-alpha.3)

A fully decoded response: every answer keyed by the caller's own question ids, plus usage and the raw decoded body for anything this layer doesn't expose yet.

Decoding is strict about the envelope (model must be present and a string, every question must have an answer, every answer must agree with its question) but permissive in two places: an answer the caller never asked for is dropped from answers and stays reachable through raw, and a missing or malformed usage decodes to a TypeSafeAPI.Usage with nil counts rather than failing a complete set of answers. The spec marks usage required with both token counts required, so the tolerance is defensive, not permission.

retry_count is how many retries the call burned before this response (0 when the first attempt succeeded). request_id is the x-typesafe-request-id response header, the value TypeSafe support asks for. TypeSafeAPI.Error carries the same field for failed calls, including for a body that failed to decode here.

raw holds the whole decoded body, so a result carries a second copy of everything answers already holds. inspect/1 elides it: read result.raw directly when you want it.

Summary

Types

t()

Functions

decode(body, questions, keys, request_id \\ nil)

Decodes a response body against the questions that were sent.

Types

t()

@type t() :: %TypeSafeAPI.Result{
  answers: %{required(TypeSafeAPI.Keys.key()) => TypeSafeAPI.Answer.t()},
  model: String.t(),
  raw: map(),
  request_id: String.t() | nil,
  retry_count: non_neg_integer(),
  usage: TypeSafeAPI.Usage.t()
}

Functions

decode(body, questions, keys, request_id \\ nil)

@spec decode(
  map(),
  [{TypeSafeAPI.Keys.key(), TypeSafeAPI.Question.t()}],
  TypeSafeAPI.Keys.t(),
  String.t() | nil
) :: {:ok, t()} | {:error, TypeSafeAPI.Error.t()}

Decodes a response body against the questions that were sent.

questions is the normalized [{id, question}] list (see TypeSafeAPI.Question.normalize/1) and keys is the TypeSafeAPI.Keys built from it, so answers come back keyed and valued under the caller's own ids.

request_id is the x-typesafe-request-id header of the response being decoded. It lands on the TypeSafeAPI.Result on success and on the TypeSafeAPI.Error on failure, so a decode mismatch — the one failure that needs a support ticket — can be quoted. decode/3 passes nil.