Metadata-Version: 2.5
Name: marginal-sdk
Version: 0.1.1
Summary: Marginal SDK for Python — send AI cost events to Marginal.
Project-URL: Homepage, https://marginalhq.com/docs
License-Expression: MIT
License-File: LICENSE
Keywords: ai,analytics,anthropic,cost,llm,marginal,openai,tracking
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# marginal-sdk

[Marginal](https://marginalhq.com) 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.

```bash
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.

```python
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:

```python
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

```python
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](https://marginalhq.com/docs)
- [Event shape & API](https://marginalhq.com/docs/events)
- [Integrations cookbook](https://marginalhq.com/docs/integrations) — OpenAI,
  Anthropic, Gemini, Bedrock, streaming
- [llms.txt](https://marginalhq.com/llms.txt) — paste into your coding
  assistant to instrument a codebase automatically
