traket-sdk 0.1.0

Server-side SDK for Traket AI usage metering.

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

pip install traket-sdk

Quickstart

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

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

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:

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

For TestPyPI first:

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:

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

On PowerShell:

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