Capsera SDK

Capsera attributes LLM spend to the agent, team, session, and line of code that produced it. It can also block or downgrade a call before it reaches the provider.

pip install capsera

import capsera

capsera.init(api_key="cap-...")

init() patches the provider clients installed in your environment. After it runs, every call through them is recorded, whether you wrote the call directly or a framework made it for you. Calls outside a decorated scope are still recorded and attributed to unknown.

What the SDK adds over a billing dashboard

Capsera runs inside the process making the calls. Two things are only knowable there.

Which agent spent the money. A gateway or billing export sees requests from one API key. Nothing in an HTTP request identifies the planner node rather than the summarizer. The SDK reads it from the call stack.

Whether to allow the call. Budget checks run before the provider call, so a blocking budget prevents spend instead of reporting it afterwards.

A complete integration

import capsera

capsera.init(api_key="cap-...")

@capsera.agent("researcher", team="core")
def research(question: str) -> str:
    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        messages=[{"role": "user", "content": question}],
    )
    return response.content[0].text

The decorator is the entire attribution API for most applications. There is no wrapper client to construct and no call sites to change.

Design guarantees

Calls never block on Capsera. Events go to a bounded in-memory queue that a background thread drains. If the backend is slow or unreachable, the emitter retries, opens a circuit breaker, and drops events. Your application does not wait.

Failures stay inside the SDK. Every interception path is wrapped. A bug or an unexpected response shape produces missing telemetry, not an exception in your code. The one exception the SDK raises deliberately is BudgetExceededError, and only when a blocking budget stops a call.

Prompts are never transmitted. Optional prompt analysis records structure such as token estimates, message counts, and a hash of the system prompt. It never records content. A test plants canary strings in prompts and fails the build if one appears in any emitted payload.

Where to go next

If you are starting out, read Install, then Quickstart, then Verify it works.

For attribution, see Agents for the decorator and Tags and sessions for per-request and per-conversation attribution.

For coverage, see Providers for the support matrix and Frameworks for how framework calls are captured.

For signatures, defaults, and every field on a recorded event, see the API reference.

Requires Python 3.11 or later. The only runtime dependency is httpx.