marginal-sdk

Marginal SDK for Python — send AI cost events and see where your AI spend goes, sliced by customer, feature, environment, model, or any field you define.

pip install marginal-sdk

Python 3.9+, stdlib only (zero dependencies).

Quickstart

One call per LLM request: name the provider, paste the response's model and usage — Marginal detects the provider's usage shape and computes the cost server-side against its model price catalog.

import os
from marginal import Marginal

marginal = Marginal(api_key=os.environ["MARGINAL_API_KEY"])

response = client.chat.completions.create(...)

marginal.track(
    provider="openai",
    model=response.model,
    usage=response.usage.model_dump(),
    fields={"customer": "acme-corp", "feature": "support-bot"},
)

For non-LLM spend (voice, images, pre-computed costs), send dollars directly:

marginal.track(cost=0.05, fields={"customer": "acme-corp"})

track() is synchronous and never raises: events are buffered and flushed by a daemon worker thread (every 5 s or at 100 events), with retries on network errors, 429s, and 5xx. Errors are reported to an on_error callback (a warning print by default). Buffered events are flushed automatically at interpreter exit; call marginal.flush() to force one earlier. Fork-safe: the worker restarts in the child after os.fork().

Delivery guarantees

Best-effort, at-most-once. Events are buffered in memory (no disk persistence), so a hard crash — kill -9, OOM, an unhandled exception — loses what's still buffered: at most ~5 seconds or 100 events with the defaults. On a clean interpreter exit the remaining events are flushed via atexit (disable with flush_on_exit=False). Note that atexit does not run on an unhandled SIGTERM — call marginal.shutdown() from your own signal handler if you need that. A batch whose retries are exhausted is dropped and reported through on_error — the SDK never blocks or crashes your app to save an event. Retries carry no idempotency keys yet, so a batch whose response was lost after the server accepted it can, rarely, land twice.

Options

Marginal(
    api_key="mgl_...",         # required — server-side only
    on_error=lambda err: ...,  # delivery/validation errors (never raised)
    flush_on_exit=True,        # default; False disables the atexit flush
    base_url="https://api.marginalhq.com",  # default
)

Docs

• Quickstart
• Event shape & API
• Integrations cookbook — OpenAI, Anthropic, Gemini, Bedrock, streaming
• llms.txt — paste into your coding assistant to instrument a codebase automatically