typesafe_api

# TypeSafe cheatsheet

## Client
{: .col-2}

### Build once, pass around

```elixir
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

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

## Questions
{: .col-2}

### Noul (yes/no)

Instructions may be a question or a statement to evaluate.

```elixir
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)

```elixir
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)

```elixir
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:

```elixir
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`.

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

### Validate eagerly

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

## Evaluate
{: .col-2}

### One state

```elixir
{: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

```elixir
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

```elixir
{: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.

## Answers
{: .col-2}

### Shapes

```elixir
%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

```elixir
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
```

## Errors
{: .col-2}

### Match on type

```elixir
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

| status / type   | when                                   |
| --------------- | -------------------------------------- |
| 401             | `:auth`                                |
| 400             | caller error, `:validation`            |
| 422             | `:validation`, or caught locally (`status: nil`) |
| 429             | `:rate_limited` after retries          |
| 529 / 503       | `:overloaded` after retries            |
| other 5xx       | `:server_error` after retries          |
| 408             | retried, then `:timeout`               |
| n/a             | `:timeout` (no response in time), `:connection` (could not reach the server) |
| anything else   | `:unexpected` (a response nothing could read) |

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

## Testing
{: .col-2}

### Stub by question id

```elixir
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

```elixir
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

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

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

JSON Lines, one response per line, errors included.

## Raw layer and telemetry
{: .col-2}

### Maps in, maps out

```elixir
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

```elixir
# [: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()
```

## Limits
{: .col-2}

### 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`).

| limit                    | our validator | spec                                         | source                                    |
| ------------------------- | -------------- | --------------------------------------------- | ------------------------------------------ |
| Choice options, min        | 1              | no bound (`ChoiceQuestion.criteria` unconstrained) | local policy — an empty option set asks nothing |
| Choice options, max        | 255            | no bound                                       | local policy — matches a live-API 400 observed at 256 |
| Score levels, min           | 2              | `ScoreQuestion.criteria` `minItems: 1`         | local policy — a one-level score is meaningless |
| Score levels, max           | 10             | no bound                                       | local policy — matches a live-API 400 observed at 11 |
| questions per request, min | 1              | `SystemOneRequest.questions` `minProperties: 1` | spec — this library just surfaces it as a `:validation` error |
| `instructions`              | optional everywhere | optional everywhere (nullable/omittable on every question type) | spec |

`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.