Metadata-Version: 2.5
Name: tokentriage
Version: 1.0.0rc1
Summary: Zero-dependency instrumentation SDK for the TokenTriage proxy — forwards x-tt-* recipes and reads back the receipt the server stamped. It forwards and reads; it never computes.
Project-URL: Homepage, https://github.com/tokentriage/tokentriage
Project-URL: Source, https://github.com/tokentriage/tokentriage/tree/main/sdk/python
Project-URL: Changelog, https://github.com/tokentriage/tokentriage/blob/main/sdk/python/CHANGELOG.md
Author: TokenTriage
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: instrumentation,llm,observability,proxy,tokentriage,tracing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: crewai
Requires-Dist: crewai>=0.30; extra == 'crewai'
Provides-Extra: dev
Requires-Dist: hypothesis>=6; extra == 'dev'
Requires-Dist: opentelemetry-api>=1.0; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: pyyaml>=6; extra == 'dev'
Provides-Extra: httpx
Requires-Dist: httpx>=0.27; extra == 'httpx'
Provides-Extra: langchain
Requires-Dist: langchain-core>=1.0; extra == 'langchain'
Requires-Dist: langchain-openai>=1.0; extra == 'langchain'
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.0; extra == 'otel'
Provides-Extra: requests
Requires-Dist: requests>=2.31; extra == 'requests'
Description-Content-Type: text/markdown

# tokentriage — Python instrumentation SDK

The zero-dependency, never-throws, no-phone-home helper for the
[TokenTriage](https://github.com/tokentriage/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.

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

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