A supervised TypeSafe AI client with bounded concurrency and queues.

Reuses Mint HTTP connections with optional pooling, request deadlines, configurable retries, and telemetry.

Add this module to your application's supervision tree and use TypeSafe.system_one/2 to evaluate state. Connections are opened lazily: starting a client validates configuration but does not authenticate with the service or require network access.

children = [
  {TypeSafe.Client,
   name: MyApp.TypeSafe,
   api_key: System.fetch_env!("TYPESAFE_API_KEY")}
]

The application retrieves the key. This library does not read environment variables or Keychain automatically. Use separate clients for separate keys; see the configuration guide for multiple child IDs.

Connection lifecycle

By default the client owns one connection. Set :pool_size above one to start a supervisor with independent connection workers behind the same client name or PID. Requests are distributed round robin, without sending their payloads through a central dispatcher. Each worker opens its connection lazily.

HTTP/1 runs one request at a time per connection. HTTP/2 multiplexes up to the configured and server-advertised stream limits on each connection. Each worker bounds outstanding network work, including backoff waits, by the current protocol capacity plus :max_queue. Before negotiation the active capacity is conservatively one. Excess calls return :overloaded after all workers reject admission. A full worker is skipped; accepted work stays with its worker for its entire retry lifecycle. There is no global FIFO queue or work stealing between workers.

Response decoding and validation run in the caller, after the worker releases its network slot. The deadline is checked before and after decoding. Bound caller concurrency as well as network capacity to control CPU and memory use.

Queueing, connecting, uploading, receiving, and retry waits share one request deadline. Socket sends have a one-second upper timeout; a blocked send or process scheduling may delay delivery of the timeout result.

Caller termination releases pending work. HTTP/1 cancellation closes the connection; HTTP/2 cancellation resets the individual stream. Healthy connections are reused, and subsequent work reconnects after a disconnect. A disconnect may happen after the remote evaluation was processed; see TypeSafe.Retry before enabling transport replay.

Tune :pool_size and :max_concurrency against your workload. More connections do not raise the service quota and may increase memory use and queueing. See the performance guide for measurement and tuning.

Response bodies are buffered up to :max_response_bytes. There is no public streaming API. Formatted process status is redacted, but privileged BEAM inspection can access actual process memory.