Response Types

Package: github.com/therealbill/typesafe-go (import path typesafe).

Answer

type Answer interface {
    // AnswerType returns the wire "type" of the answer.
    AnswerType() string
}

Answer is one decoded answer: NoulAnswer, ChoiceAnswer, ScoreAnswer, or UnknownAnswer for types this package does not model.

Decode error determinism

Answers are decoded in sorted (alphabetical) key order, not Go’s randomized map iteration order. When a response has more than one malformed answer, decoding stops at the first one encountered in that sorted order, so the resulting *ResponseValidationError’s FieldPath is always the alphabetically first bad key, consistently across repeated runs.

NoulAnswer

type NoulAnswer struct {
    Noul float64
}

NoulAnswer is the probability, from 0 to 1, that the condition holds.

Wire shape:

{ "type": "noul", "noul": <float64> }

ChoiceAnswer

type ChoiceAnswer struct {
    Choice        string
    Confidence    float64
    Probabilities map[string]float64
}

ChoiceAnswer is the selected label with the probability of each label and the confidence, which summarizes how concentrated the distribution is.

Wire shape:

{
  "type": "choice",
  "choice": <string>,
  "confidence": <float64>,
  "probabilities": { "<label>": <float64>, ... }
}

When decoding, a missing "probabilities" field is populated as an empty map rather than nil.

ScoreAnswer

type ScoreAnswer struct {
    Score         float64
    Confidence    float64
    Legend        map[string]JSONContent
    Probabilities map[string]float64
}

ScoreAnswer is the probability-weighted score with the rubric legend, the probability of each level keyed by its index as a string, and confidence.

Wire shape:

{
  "type": "score",
  "score": <float64>,
  "confidence": <float64>,
  "legend": { "<index>": <JSONContent>, ... },
  "probabilities": { "<index>": <float64>, ... }
}

When decoding, a missing "legend" or "probabilities" field is populated as an empty map rather than nil.

UnknownAnswer

type UnknownAnswer struct {
    Type string
    Raw  json.RawMessage
}

UnknownAnswer preserves an answer whose type this package does not know.

MarshalJSON behavior: if Raw is empty, it returns {"type": <Type>}; otherwise it returns Raw unchanged. Because UnmarshalJSON stores the input bytes unchanged in Raw, decoding an UnknownAnswer and then re-marshaling it round-trips byte-for-byte.

Usage

type Usage struct {
    InputTokens  *int `json:"input_tokens"`
    OutputTokens *int `json:"output_tokens"`
}

Usage is the token usage reported by the API. Fields are nil when absent.

RawResponse

type RawResponse struct {
    Status int
    Header http.Header
    Body   []byte
}

RawResponse is the HTTP response behind a decoded result.

SystemOneResponse

type SystemOneResponse struct {
    Model     string            `json:"model"`
    Answers   map[string]Answer `json:"answers"`
    Usage     Usage             `json:"usage"`
    RequestID string            `json:"request_id,omitempty"`
    Raw       *RawResponse      `json:"-"`
}

SystemOneResponse is the decoded result of a SystemOne call.

ListModelsResponse

type ListModelsResponse struct {
    Models    []ModelMetadata `json:"models"`
    RequestID string          `json:"request_id,omitempty"`
    Raw       *RawResponse    `json:"-"`
}

ListModelsResponse is the decoded result of a ListModels call.

ModelMetadata

type ModelMetadata struct {
    Name        string `json:"name"`
    Description string `json:"description"`
    ReleaseDate string `json:"release_date"`
}

ModelMetadata describes one model available to the account.

Response size limit

A response body over 16 MiB is not decoded. SystemOne and ListModels return &typesafe.ResponseValidationError{FieldPath: "", Err: errors.New("response exceeds 16 MiB")} instead. The check (in transport.go) reads one byte past the 16 MiB cap to detect an oversized body rather than silently truncating it into malformed JSON. This error carries no HTTP status: the underlying *http.Response is not returned to the caller, so it is never seen as an *APIError.

SystemOneAs

func SystemOneAs[T any](ctx context.Context, c *Client, state any, questions Questions, opts ...RequestOption) (T, *SystemOneResponse, error)

SystemOneAs calls SystemOne and decodes the answers into T, a struct whose fields are NoulAnswer, ChoiceAnswer, or ScoreAnswer (or pointers to them) tagged with the question identifiers:

type Triage struct {
    Billing typesafe.NoulAnswer   `json:"billing"`
    Tone    typesafe.ChoiceAnswer `json:"tone"`
}

The full response is returned alongside T, carrying the usage and request ID. On a request error the response is nil. On a decode error the response is returned with the error.