Metadata-Version: 2.4
Name: traket-sdk
Version: 0.1.0
Summary: Server-side SDK for Traket AI usage metering.
Author: Traket
Project-URL: Documentation, https://traket.ai/docs/sdk
Keywords: ai,usage,metering,openai,costs
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Traket Python SDK

Server-side AI usage metering for Traket. The SDK sends model, token, cost,
feature, and customer attribution to the Traket ingest API without sending
prompts, outputs, provider headers, API keys, or full provider responses.

## Install

```bash
pip install traket-sdk
```

## Quickstart

```python
import os

from traket import create_margins

margins = create_margins(
    write_key=os.environ["TRAKET_WRITE_KEY"],
    endpoint=os.getenv("TRAKET_ENDPOINT"),
)

margins.track(
    {
        "provider": "openai",
        "external_customer_id": "user_123",
        "feature": "generate_blog_post",
        "model": "gpt-5.4-mini",
        "cost": {
            "amount": 0.0042,
            "currency": "usd",
            "source": "manual_override",
        },
    }
)

margins.flush()
```

`TRAKET_ENDPOINT` is optional for hosted Traket and defaults to
`https://traket.ai/api/v1/usage/events`.

## Wrap OpenAI calls

```python
response = margins.openai.track(
    lambda: client.responses.create(model="gpt-5.4-mini", input=user_input),
    {
        "external_customer_id": user_id,
        "environment": "production",
        "feature": "generate_blog_post",
        "prompt_type": "blog_post",
    },
)
```

The wrapper returns the original response. It records request IDs, response ID,
model, duration, status, and OpenAI usage fields when those values are present.
If the provider call raises, it records an error event without the error message
payload and re-raises the original exception.

## Batch tracking

```python
margins.track_batch(
    events=[
        {
            "provider": row["provider"],
            "model": row["model"],
            "external_customer_id": row["user_id"],
            "feature": row["feature"],
        }
        for row in rows
    ]
)
```

The ingest API accepts 1 to 100 events per batch. `capture_usage` is kept as an
alias for `track`.

## Privacy contract

Only send scalar operational metadata such as region, route, tenant tier, or
experiment name. Never send prompts, messages, model outputs, images, files,
tool arguments, provider response bodies, provider headers, API keys,
authorization headers, passwords, secrets, or tokens.

The SDK strips metadata keys that look sensitive, but caller code should still
pass an allowlist.

## Upload to PyPI

From the repository root:

```bash
python -m pip install --upgrade build twine
cd packages/sdk-python
python -m build
python -m twine upload dist/*
```

For TestPyPI first:

```bash
python -m twine upload --repository testpypi dist/*
python -m pip install --index-url https://test.pypi.org/simple/ traket-sdk
```

Use an API token, not your PyPI password:

```bash
set TWINE_USERNAME=__token__
set TWINE_PASSWORD=pypi-...
```

On PowerShell:

```powershell
$env:TWINE_USERNAME = "__token__"
$env:TWINE_PASSWORD = "pypi-..."
```
