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().

Options

Marginal(
    api_key="mgl_...",         # required — server-side only
    on_error=lambda err: ...,  # delivery/validation errors (never raised)
    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