Cite.Provider.TypeSafe (Cite v0.2.0)

TypeSafe System One over HTTP (POST /v1/systemone).

Options

For Cite.client/2:

:api_key - Required. The TypeSafe API key.
:model (String.t/0) - The Jev model that answers. The default value is "jev-1.13.0".
:base_url (String.t/0) - The API's base URL. The default value is "https://api.typesafe.ai".
:max_retry_delay (non_neg_integer/0) - The cap on any one retry wait, in milliseconds, Retry-After included. The default value is 30000.
:req_options (keyword/0) - Req options, merged over the ones the adapter sets. See "Req options" below. The default value is [].

Retries

Rate limits (429), overloads (529), server errors (500–504), and connection failures are retried up to three times. Retries honour Retry-After, with any one wait capped at max_retry_delay (30 seconds by default). Timeouts are not retried: a 120-second call retried is eight minutes, and a slow success would be billed twice.

Req options

The adapter builds its Req client with these options. Anything in req_options overrides them, key by key, as Req.new/1 merges. The app's Req.default_options/0 applies beneath both.

Option	Set to	To change it
`base_url`	the `base_url` option	use `base_url`
`auth`	`{:bearer, api_key}`	use `api_key`
`receive_timeout`	`120_000`	`req_options: [receive_timeout: ms]`
`retry`	the adapter's retry, above	`req_options: [retry: ...]`, which replaces it
`max_retries`	`3`	`req_options: [max_retries: n]`
`redirect`	`false`	`req_options: [redirect: true]`
`pool_timeout`	`:infinity`, unless set	`req_options: [finch: [pool_timeout: ms]]`

Every other Req option passes through as Req documents it. The common ones:

Tests: req_options: [plug: {Req.Test, MyApp.TypeSafeStub}].
A larger connection pool: req_options: [finch: [size: 100]], which Req starts and supervises, or finch: [name: MyFinch] for a Finch you run.
A proxy, custom CA certificates, or HTTP/2: connect_options: [...]. Req refuses it beside finch:. With finch:, set them as Finch pool options.

One combination is refused when the client is built: a :retry_delay, in req_options or the app's defaults, without a :retry in req_options. The adapter's retry sets its own delays, and Req would raise on the pair only at the first retry. Other Req options are Req's to check.

Connections

Requests go through Req's default Finch pool, 50 connections per host. Past that, a request waits for a connection with no time limit, so concurrency above 50 queues inside Finch instead of sending more at once. A pool_timeout under finch:, in req_options or the app's defaults, sets a limit instead. A request still waiting when it runs out raises Finch's error, which ends the run. Leave it unset unless that is what you want.

The size cap

A request over the model's token cap comes back as a 400 whose body names the failure: {"detail": {"error_type": "max_tokens_exceeded"}}. This provider reports it as :request_too_large, the error that makes Cite.judge/4 halve round-1 windows. That name is observed behaviour, checked against the live API on 2026-09-26. TypeSafe's docs do not list it. If TypeSafe renames it, oversized windows will be recorded as bad requests instead of halved.

Summary

Types

error()

t()

Types

error()

@type error() ::
  :request_too_large
  | :unauthorized
  | :server_error
  | {:bad_request, String.t()}
  | {:malformed_reply, String.t()}
  | {:rate_limited, non_neg_integer() | nil}
  | {:api_error, pos_integer(), String.t()}
  | {:request_error, Exception.t()}

t()

@type t() :: %Cite.Provider.TypeSafe{http_client: Req.Request.t(), model: String.t()}