A configured TypeSafe API client.
Wraps Req to handle authentication, retries, JSON encoding/decoding, and response key
restoration. Create a client with new/1 and pass it to ExTypesafe.system_one/4.
Example
client = ExTypesafe.Client.new(api_key: "ts-...")
# or read from env:
client = ExTypesafe.Client.new()The client is a plain struct — it's safe to create once and reuse across requests.
Summary
Types
@type t() :: %ExTypesafe.Client{config: ExTypesafe.Config.t(), req: Req.Request.t()}
An opaque client struct. Treat as read-only.
Functions
@spec evaluate(t(), ExTypesafe.state(), ExTypesafe.questions(), keyword()) :: {:ok, ExTypesafe.Response.t()} | {:error, ExTypesafe.Error.t()}
Evaluates typed or raw questions against a state.
Returns {:ok, ExTypesafe.Response.t()} on success or {:error, ExTypesafe.Error.t()} on
failure, including local validation failures and exhausted retries.
This is the low-level function. Prefer ExTypesafe.system_one/4 for the public API.
Parameters
client— A client built withnew/1.state— The content to evaluate: a string, map, or list.questions— A non-empty map, or caller-defined struct, of string/atom keys to question structs or raw question maps. Struct containers are normalized without their__struct__field and omitnilfields. A singleQuestion.Noul,Question.Choice, orQuestion.Scoreis intentionally rejected: define a purpose-built container struct whose fields hold valid question values instead. Raw question maps remain forward-compatible. Response answer keys retain the same atom or string form supplied here.opts— Optional keyword list::model— Override the client's default model.:extra_body— Map of additional API request fields. Corestate,model, andquestionsfields always take precedence.:max_retries— Override the client's retry count for this call.:retry_delay_ms— Override the initial retry delay for this call.:max_retry_delay_ms— Override the maximum retry delay for this call.
Creates a new client.
Accepts the same options as ExTypesafe.Config.new/1. Falls back to environment variables.
Raises ArgumentError if no API key is configured.
Options
:api_key— TypeSafe API key. Falls back toTYPESAFE_API_KEYenv var. Required.:base_url— API root. Falls back toTYPESAFE_BASE_URLenv var (default:https://api.typesafe.ai).:model— Default model. Falls back toTYPESAFE_DEFAULT_MODELenv var (default:jev-latest).:max_retries— Retry attempts on 429/529 and transport failures (default: 3).:retry_delay_ms— Initial delay in ms, doubles each attempt (default: 500).:max_retry_delay_ms— Maximum exponential-backoff delay and acceptedRetry-Aftervalue in ms (default: 5000).:plug— Inject aReqplug for testing (e.g.{Req.Test, :typesafe}).