Configuration

Create one Cave client for your service, agent label, and credential context. Pass configuration explicitly. The SDK reads CAVE_WORKFLOW as a workflow default; it does not automatically read your API key or base URL from environment variables.

Client options#

Validate required secrets in your app. Creating a client proves neither that its key works nor that an endpoint exists.

URLs and credentials#

Use a base URL without embedded credentials, query parameters, or fragments. Trailing slashes are normalized. Provider helpers add their own route prefix, so do not add /openai/v1 to the base URL for cave.openai().

Requests normally carry the service key as Authorization: Bearer …. Provider methods with an upstream key send it separately as x-cave-upstream-key. OTLP export uses x-cave-api-key. These are different authentication paths; a provider API key does not substitute for your service credential.

Run credential-bearing calls on your server. Do not put service or provider secrets in browser bundles. The user field is not hashed by the SDK: hash or otherwise pseudonymize a sensitive identifier before passing it.

Labels and retention#

Use a stable agent label such as support-agent and a workflow such as answer-question. An ambient CAVE_WORKFLOW is lowercased and accepted only when it matches [a-z0-9_-] with 1 to 96 characters. Invalid ambient values are ignored. An explicit workflow takes precedence.

retention is forwarded as x-cave-retention; it does not prevent the SDK from sending a payload needed by the operation. Compression sends the supplied string, context packing sends item text, and checkpoints send messages. Confirm the configured service's retention behavior before sending sensitive content.

TypeScript cancellation#

After the TypeScript quickstart import:

const controller = new AbortController();
const cancellable = new Cave({
  apiKey: process.env.CAVE_API_KEY!,
  baseURL: process.env.CAVE_BASE_URL!,
  agent: "support-agent",
  timeoutMs: 15_000,
  signal: controller.signal,
});
// Call controller.abort() when the owning operation is cancelled.

An aborted signal remains aborted. Use a fresh controller/client for a later independent operation. Compression handles request failure by returning the original payload; provider calls reject. Raw response bodies and streaming consumption also need an application-level lifecycle.

Python timeouts#

The core client uses urllib timeouts: 300 seconds for provider calls, compression, and shared-context requests; 30 seconds for tool search, packing, checkpoints, artifacts, policy refresh, and OTLP export. There is no timeout_ms constructor argument. Offload blocking calls with asyncio.to_thread when needed, and enforce workflow budgets in your application.

Service compatibility#

Check which APIs your deployment serves. Provider routes, /sdk/v1/compress, deferred tools, storage APIs, runtime policy, and /v1/traces are separate capabilities. The local proxy and framework middleware do not imply all connected SDK endpoints exist.

Do not use compress() as a health check: failure deliberately returns the original text. A successful authenticated provider call or your deployment's documented health check provides better evidence. No SDK option enables a missing service capability or grants additional access.