Gateway entry points

capsera.gateways.install_litellm(), install_portkey(), and the litellm_proxy handler — signatures, return values, and the environment variables the proxy reads.

Three entry points under capsera.gateways. The two installers run automatically; the proxy handler is the one thing you wire up by hand.

Added in 0.4.0. The capsera.gateways package does not exist in 0.3.x, and neither does the gateway field on an event. Check capsera.__version__ before reaching for anything on this page.

For which gateways are covered and how a call is tagged, see LiteLLM and gateways.

install_litellm()

from capsera.gateways import install_litellm

install_litellm() -> bool

Registers Capsera's logger in litellm.callbacks and wraps litellm.completion, acompletion, embedding, and aembedding with the pre-call budget check.

Returns True on success, and False when litellm is absent or registration failed. The return value matters more than it looks: registration also switches on suppression of the inner provider SDKs, because litellm drives the OpenAI SDK and boto3 internally and both would otherwise record the same call a second time. When it returns False, suppression stays off, so the inner patches keep capturing and you still get the call — attributed to the provider rather than the gateway.

Idempotent. capsera.init() calls it for you whenever litellm is importable, so call it directly only if you are constructing the integration by hand.

Attribution metadata it reads from, and injects into, a litellm call:

capsera_agent_id      capsera_session_id
capsera_team_id       capsera_customer_id
capsera_task_type     capsera_cost_center

A live scope from a decorator or tag() wins over metadata on the call.

install_portkey()

from capsera.gateways import install_portkey

install_portkey() -> bool

Patches the portkey_ai chat and embeddings surfaces. Returns False when portkey_ai is absent or the import fails. Idempotent, and also called by init().

A call made with stream=True returns unwrapped, so a streamed Portkey call records no usage. A failure raised by the call itself is still recorded.

capsera_handler

For a LiteLLM Proxy — the server, not the Python SDK — the integration is a handler the proxy loads by path. There is no function to call:

# proxy config.yaml
litellm_settings:
  callbacks: ["capsera.gateways.litellm_proxy.capsera_handler"]

It captures every request the proxy serves, and rejects over-budget requests with HTTP 429 in the proxy's pre-call hook, which makes the gateway itself the enforcement point for any language that talks to it.

The handler configures itself from the environment. These are the only environment variables the SDK reads anywhere:

Variable	Default	Notes
`CAPSERA_API_KEY`	—	Required. Without it the handler logs a warning and events cannot be attributed.
`CAPSERA_ENDPOINT`	`https://api.capsera.ai`	Backend base URL.
`CAPSERA_ENV`	`production`	Environment label. Note the default differs from `init()`, which defaults to `development`.
`CAPSERA_ENFORCE_BUDGETS`	`true`	Set to `false` for capture-only, with no blocking.

Attribution comes from capsera_* metadata on the request, falling back to the proxy key alias — the proxy has no Python scope to read, so whatever the caller sends is all there is.

Gateway and provider are separate fields

An event carries both. A call through litellm to Anthropic records provider="anthropic" and gateway="litellm". A direct call records gateway=None.

Gateways the SDK recognises by host — OpenRouter, Portkey, Helicone, Cloudflare AI Gateway, a local LiteLLM proxy — need no code at all: point your OpenAI or Anthropic client's base_url at them and the existing patches capture the call with the gateway tagged. For a self-hosted gateway on a host the SDK cannot recognise, declare it once:

capsera.init(api_key=..., gateway="bifrost")