tokentriage — Python instrumentation SDK

The zero-dependency, never-throws, no-phone-home helper for the TokenTriage proxy. It forwards and reads; it never computes. Every x-tt-* recipe is a one-liner, and every number on display is server-truth — a value the server did not disclose is a first-class absent, never $0.00, never a client-side estimate.

• Zero runtime dependencies (dependencies = [], enforced in CI).
• Never throws on the host path — every public entry is shielded; render-time inputs coerce-or-drop, never raise.
• No phone-home — the core opens no sockets; the optional ledger module (SDK2) talks only to your own admin plane.

import tokentriage as tt

tt.init(base_url="http://127.0.0.1:8787")

with tt.trace(agent="triage", user="u-42", tenant="acme", feature="chat"):
    with tt.step(step_class="user_turn"):
        headers = tt.headers(tags={"env": "prod"})   # the wire artifact
        resp = your_llm_client.post(..., headers=headers)
        rcpt = tt.receipt(resp)                       # typed, read-only
        print(rcpt.mode, rcpt.decision, rcpt.cost_display)
        print(rcpt.dashboard_url())                   # deep link to the ledger record

The honest dollar lives in the ledger row keyed by rcpt.request_id (cost_display points you there); the SDK never fabricates one inline.

Status

The full v1 surface is implemented and gated. That is: context/identity, the wire layer (header render + receipt parse), the closed three-state Cost, config/diagnostics/shield; the transport adapters (httpx/requests) and the LangChain/CrewAI adapters; the ledger pull (ledger.fetch/fetch_trace) and the feedback write (ledger.feedback); the first-run doctor tt.check(); the OpenTelemetry bridge; and the adopter test kit — all against a byte-equality conformance corpus shared with the TypeScript binding.

Pre-1.0: the two bindings are being brought to a single shape before the surface freezes, so a few names are still moving. See the CHANGELOG's [Unreleased] section.

Development

python -m venv .venv && . .venv/Scripts/activate   # Scripts/ on Windows, bin/ on POSIX
pip install -e ".[dev]"
pytest -q            # unit + conformance + properties (+ e2e when Go is present)

Licensed under Apache-2.0. See LICENSE and NOTICE.