Configuration

Python SDK

VaaniObserver(
    endpoint=None,
    api_key=None,
    spool_directory=None,
    capture=None,
    instrumentations=None,
    endpoints=None,
    upload=None,
    strict=False,
)

Node.js SDK

new VaaniObserver({
  endpoint: undefined,
  apiKey: undefined,
  spoolDirectory: undefined,
  capture: undefined,
  instrumentations: undefined,
  endpoints: undefined,
  upload: undefined,
  strict: false,
});

Identical shape in camelCase. instrumentations uses { fetch, websocket } rather than { http, websocket }.

capture

endpoints

{"id": "llm", "type": "llm", "url": "https://api.openai.com/v1", "match": "path"}

An unknown match raises TypeError. A URL matching more than one rule at the same scheme precedence raises Ambiguous Vaani endpoint rules for …. See Endpoints and instrumentation.

upload

The environment column is Python only. The Node SDK accepts the same three transport options as camelCase constructor keys — { retries, timeoutMs, minThroughputBps } — with the same defaults (3, 30000, 131072). It does not compress.

The environment column matters because from_env() — the constructor every integration guide shows — builds the observer itself. Until these variables existed, a value set from this table was silently discarded. An explicit upload={...} argument still wins over the environment.

upload_package(finalized, timeout=...) provides an overall upload budget across objects and retries. It is not a delivery or durability guarantee: finalization, local file work and the host's shutdown deadline also matter. Digests describe the uncompressed object, never the transfer encoding. A failed upload normally leaves its package on the spool; retry from persistent storage with python -m vaani_observer.drain.

Development-checkout uploader hardening

The current checkout adds streamed object uploads, an inventory at session creation, per-object upload headers, bounded retries that respect Retry-After, and a 300-second default overall upload budget. These changes are available in the pinned hosted source previews in the Python and Node.js quickstarts. Both revisions were installed in clean environments. Registry publication and public service admission remain separate; check your installed revision before relying on this behavior.

In Python, configure the constructor with upload={"total_timeout_s": 300}; in Node.js use upload: { totalTimeoutMs: 300000 }. Omitting the per-call override (or passing Python timeout=None) uses the configured total budget. Node's second argument is a number of milliseconds, not an options object. Total budgets must be finite and positive. This is distinct from Python timeout_s or Node.js timeoutMs, which are base per-request budgets. Hashing, compression where applicable, requests and retries share the overall budget.

Python total_timeout_s is a constructor setting only; no new environment variable is provided. VAANI_UPLOAD_TIMEOUT_S continues to configure the per-request base, not the overall budget. Eligible retry statuses are 408, 425, 429, 500, 502, 503 and 504. Named quota, validation and limit errors remain permanent even on 429; ordinary 401/403 responses are not retried. An explicit expired-object-capability response can refresh the idempotent create once, without resetting the total budget.

Refresh requires an explicit expiry code or message. The hosted development backend uses 401 with detail.code: "upload_expired". An elapsed expires_at alone does not permit refreshing a generic 401 or 403: invalid, tampered or wrong-object credentials remain permanent failures. Hosted 429 responses with detail.code: "monthly_quota_exhausted" or "storage_quota_exhausted" are also permanent, not transient retry signals.

For a create response with upload URLs, the SDK repeats PUTs and completion, while the hosted development backend verifies identical content without replacing accepted objects.

If the initial create or refresh explicitly returns status: "accepted" with upload_urls: {}, the checkout SDKs skip object uploads and repeat completion with the unchanged inventory. Missing URLs without the explicit accepted status are not a success shortcut. The current hosted development backend uses this accepted-replay response, also returning empty upload_headers and the same session/upload identity. Different manifests or inventories fail with 409 before the shortcut. The compatible SDK handling is included in those pinned source previews; older or unqualified Git revisions may not support this backend contract. See HTTP API.

Streaming limits object buffering, but hashing and optional Python gzip scratch files still consume I/O, CPU and disk. A retry reopens the stream rather than making failed delivery durable. HTTPS or loopback HTTP is required, redirects are rejected, and an HTTPS ingest cannot downgrade to an HTTP object upload. Only allowed object headers are applied without forwarding the ingest bearer token. See HTTP API for the additive protocol fields; local backwards compatibility does not imply hosted acceptance.

Python custom transport overrides have additional limits: legacy four-argument callables cannot be forcibly interrupted. Unmarked overrides receive byte bodies only up to 1 MiB; larger uploads require supports_streaming=True. Adapters must enforce timeouts and reject redirects themselves. The native Python transport ignores proxy environment variables, while Node sends raw uncompressed objects. System DNS resolution and stalled filesystem work also prevent a universal hard wall-clock guarantee. See the SDK's upload documentation before replacing its transport.

strict

LiveKit integration environment

Read by VaaniLiveKitRecorder.from_env().

from_env() never raises: on failure it returns an inert recorder whose methods are no-ops and whose enabled is False. Check recorder.enabled at startup if you want a misconfiguration to be visible; recorder.last_error carries the reason. When VAANI_ENABLED is set but recording ends up off, the reason is also logged at ERROR — silence there was a bug, not a design.

When VAANI_ENDPOINTS is empty, HTTP and WebSocket instrumentation is not installed at all: patching clients with no rules to match is pure cost.

Dashboard

Fixed limits, not configurable:

These limits describe the localhost app.main:app path, not the separate hosted beta under construction. The local entrypoint refuses hosted-environment startup except for explicitly configured curated demo operation. Do not expose it behind a key as a tenant-safe service.

External evaluation requires the current consent_version from GET /v1/evaluation-policy on every confirmed run. It sends full recorded caller audio to ElevenLabs and transcript comparison content to OpenAI when judging is configured. The local policy supplies no cost estimate or allowance (null); provider billing and a global spend cap are not managed by this path.

Recommended postures

Next