TypeSafe cheatsheet

Build once, pass around

client = TypeSafeAPI.new(api_key: "sk-...")

# from TYPESAFE_API_KEY / TYPESAFE_BASE_URL /
# TYPESAFE_DEFAULT_MODEL or config :typesafe_api
client = TypeSafeAPI.new()

client =
  TypeSafeAPI.new(
    api_key: "sk-...",
    model: "jev-latest",
    timeout: 10_000,
    connect_timeout: 5_000,
    retry: [max_retries: 2, budget: 30_000],
    req_options: [connect_options: [proxy: ...]]
  )

Environment variables

TYPESAFE_API_KEY=sk-...
TYPESAFE_BASE_URL=https://api.typesafe.ai
TYPESAFE_DEFAULT_MODEL=jev-latest
TYPESAFE_LOG_LEVEL=info   # read by TypeSafeAPI.Telemetry.attach_logger/1

Per-call options

TypeSafeAPI.evaluate(client, state, questions,
  model: "jev-2",
  timeout: 5_000,
  retry: [max_retries: 0],
  req_options: [headers: [x_trace: "abc"]],
  telemetry: %{tenant: "acme"}
)

Noul (yes/no)

Instructions may be a question or a statement to evaluate.

TypeSafeAPI.noul("Does this convey urgency?")

TypeSafeAPI.noul("This message contains unsolicited advertising.")

TypeSafeAPI.noul("Does this convey urgency?",
  true: "Explicitly time-sensitive",
  false: "No urgency expressed"
)

Choice (one of a set, 1 to 255 options)

TypeSafeAPI.choice("Which team should handle this?",
  billing: "Payments, invoicing, refunds",
  technical: "Bugs, outages, integrations",
  sales: nil
)

# string keys come back as strings
TypeSafeAPI.choice("Which?", [{"a", nil}, {"b", nil}])

# a bare list of names means the same as pairing each with nil
TypeSafeAPI.choice("Which team?", [:billing, :sales])

Score (ordered scale, 2 to 10 levels)

TypeSafeAPI.score("How frustrated is the customer?",
  ["Calm", "Frustrated", "Very angry"])

# {label, description} sends a structured level
# and gives you the label back in the answer
TypeSafeAPI.score("Severity?", [
  {"Low", "Cosmetic; no functional impact"},
  {"High", "Blocking; no workaround"}
])

Structured descriptions

Anywhere a string goes, a map or list works too:

TypeSafeAPI.choice(%{question: "Which team?", focus: "Primary request only"},
  billing: %{what: "Charges", not_for: "Delivery", examples: ["Charged twice"]}
)

Instructions are optional

Every type takes nil instructions; the key is then left out of the request rather than sent as null.

TypeSafeAPI.noul()
TypeSafeAPI.choice(nil, approve: "Ship it", reject: "Send it back")
TypeSafeAPI.score(nil, ["Calm", "Frustrated", "Very angry"])

Validate eagerly

@urgent TypeSafeAPI.Question.validate!(
          TypeSafeAPI.noul("Urgent?", true: "Explicitly time-sensitive")
        )
# raises ArgumentError at compile time if malformed; returns the question otherwise

One state

{:ok, result} = TypeSafeAPI.evaluate(client, state, questions)
result = TypeSafeAPI.evaluate!(client, state, questions)

result.model             #=> "jev-1.13.0"
result.usage.input_tokens                # nil if the API sent none
TypeSafeAPI.Usage.total_tokens(result.usage)   # nil counts as 0
TypeSafeAPI.Usage.add(total, result.usage)     # fold a batch
result.answers.dept      #=> %TypeSafeAPI.Answer.Choice{}
result.raw               #=> decoded JSON body
result.request_id        #=> the x-typesafe-request-id header, or nil

Many states

TypeSafeAPI.evaluate_many(client, states, questions,
  max_concurrency: 8,   # a guess; limits unpublished
  task_timeout: 40_000, # per-state, all retries
  timeout: 5_000,       # one HTTP attempt
  ordered: true,
  on_error: :collect    # or :raise
)
#=> [{:ok, %Result{}} | {:error, %Error{}}]

Models

{:ok, [%TypeSafeAPI.Model{name: "jev-1.13.0"} | _]} = TypeSafeAPI.models(client)
models = TypeSafeAPI.models!(client)

model.release_date       #=> ~D[2026-09-15], or nil
model.release_date_raw   #=> "2026-09-15T00:00:00Z"
model.raw                #=> the whole entry, unmodeled fields included

An entry this library cannot decode is logged and skipped, not fatal to the list.

Shapes

%TypeSafeAPI.Answer.Noul{id: :urgent, noul: 0.92,
  confidence: 0.92}   # max(noul, 1 - noul), never below 0.5

%TypeSafeAPI.Answer.Choice{id: :dept, choice: :technical,
  description: "Bugs, outages, integrations",
  probabilities: %{billing: 0.08, technical: 0.85, sales: 0.07},
  options: [{:billing, 0.08}, {:technical, 0.85}, {:sales, 0.07}],
  confidence: 0.82}

%TypeSafeAPI.Answer.Score{id: :anger, score: 1.6,
  level: 2, label: "Very angry", description: "Very angry",
  levels: [{"Calm", 0.05}, {"Frustrated", 0.3}, {"Very angry", 0.65}],
  probabilities: %{0 => 0.05, 1 => 0.3, 2 => 0.65},
  legend: %{0 => "Calm", ...}, confidence: 0.78}

Helpers

TypeSafeAPI.Answer.yes?(answers.urgent)          # noul >= 0.5 (Noul only)
TypeSafeAPI.Answer.yes?(answers.urgent, 0.7)
# yes?/2 on a Choice or Score raises ArgumentError
TypeSafeAPI.Answer.gate(answers.dept, act: 0.8, review: 0.5)
#=> :act | :review | :escalate
TypeSafeAPI.Answer.gate(answers.urgent, act: 0.8, review: 0.55)
# a Noul needs review > 0.5, or :escalate is unreachable (raises)
TypeSafeAPI.Answer.confidence(answer)            # what gate/2 uses
# Noul has no wire confidence; this library uses max(noul, 1 - noul)
TypeSafeAPI.Answer.Score.normalized(answers.anger) # score / top level

Match on type

case TypeSafeAPI.evaluate(client, state, questions) do
  {:ok, result} -> ...
  {:error, %TypeSafeAPI.Error{type: :rate_limited, retry_after_ms: ms}} -> ...
  {:error, %TypeSafeAPI.Error{type: :validation, message: msg}} -> ...
  {:error, %TypeSafeAPI.Error{type: type}} when type in [:timeout, :connection] -> ...
end

Types

TypeSafeAPI.Error.retryable?/1 says whether a given error was worth another try.

Stub by question id

setup :typesafe_stubs
def typesafe_stubs(ctx), do: TypeSafeAPI.Test.typesafe_stubs(ctx)

client =
  TypeSafeAPI.Test.client()
  |> TypeSafeAPI.Test.stub(
    urgent: {:noul, 0.3},
    dept: {:choice, :billing, 0.9},
    anger: {:score, 1, 0.8}
  )

Errors and models

TypeSafeAPI.Test.stub_error(client, 429, %{"error" => "slow"},
  headers: [{"retry-after", "1"}], times: 1)

TypeSafeAPI.Test.stub_models(client,
  [%{name: "jev-1", release_date: ~D[2026-01-01]}])

Helpers compose: models, answers and errors can all sit on one client. confidence must beat 1 / n. An unstubbed question is a 422, not a raise.

Record and replay

TypeSafeAPI.new()
|> TypeSafeAPI.Test.record("test/fixtures/t.jsonl")

TypeSafeAPI.Test.replay("test/fixtures/t.jsonl")

JSON Lines, one response per line, errors included.

Maps in, maps out

TypeSafeAPI.HTTP.post(client, "/v1/systemone", %{
  "state" => "...", "model" => "jev-latest",
  "questions" => %{"q" => %{"type" => "noul", "instructions" => "?"}}
})
TypeSafeAPI.HTTP.get(client, "/v1/models")

# unknown question types (e.g. "bounding_box"): post raw against
# TypeSafeAPI.SystemOne.path/0, read the decoded map back
TypeSafeAPI.HTTP.post(client, TypeSafeAPI.SystemOne.path(), %{
  "state" => "...", "model" => client.model,
  "questions" => %{"region" => %{"type" => "bounding_box"}}
})

Telemetry

# [:typesafe_api, :request, :start | :stop | :exception]
# start metadata:  model, question_count
# stop metadata:   + status, retry_count, input_tokens, output_tokens, error
# (error is a TypeSafeAPI.Error on failure, nil on success; API failures are
#  :stop events, not :exception — :exception only fires when code raises)
TypeSafeAPI.Telemetry.attach_logger(level: :info)
TypeSafeAPI.Telemetry.detach_logger()

What's ours vs. what's the spec's

priv/openapi.json is TypeSafe's OpenAPI document, API version 0.2.0. Most of the bounds this library enforces are local policy, not requirements the spec itself states; where they're stricter than the spec, that's because a live run against the real API rejected values the spec alone would have allowed (see DESIGN.md).

Choice.validate/1 and Score.validate/1 (in TypeSafeAPI.Question.Choice and TypeSafeAPI.Question.Score) are where the local bounds live; see their moduledocs for the same table alongside the code that enforces it.