tokenmeter-sdk 0.2.0__py3-none-any.whl

tokenmeter_sdk-0.2.0.dist-info/METADATA

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: tokenmeter-sdk
+Version: 0.2.0
+Summary: Token Meter Python SDK: wraps OpenAI/Anthropic/Gemini/Bedrock/Azure clients and meters token usage
+Author: Saqlain Rashid
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/SaqlainRashed/token-meter
+Project-URL: Repository, https://github.com/SaqlainRashed/token-meter
+Project-URL: Changelog, https://github.com/SaqlainRashed/token-meter/blob/main/sdks/python/CHANGELOG.md
+Keywords: llm,tokens,usage,metering,observability,openai,anthropic,vercel-ai-gateway
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.30; extra == "anthropic"
+Provides-Extra: gemini
+Requires-Dist: google-genai>=0.1; extra == "gemini"
+Provides-Extra: bedrock
+Requires-Dist: boto3>=1.34; extra == "bedrock"
+Provides-Extra: azure
+Requires-Dist: openai>=1.0; extra == "azure"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# token-meter (Python SDK)
+
+## Read usage data
+
+Create a separate read-only key under **Settings → API keys → Read API keys**. It cannot submit usage events.
+
+```python
+import os
+from tokenmeter import TokenMeterReadClient
+
+read_api = TokenMeterReadClient(os.environ["TOKEN_METER_READ_KEY"], os.environ["TOKEN_METER_DASHBOARD_URL"])
+page = read_api.list_daily_usage("2026-10-01", "2026-10-31")
+```
+
+This returns daily **metered** usage/spend summaries, not provider invoice data. See [`docs/openapi.yaml`](../../docs/openapi.yaml) for pagination, fields, and limits.
+
+In-process LLM usage capture for Python. `tokenmeter.wrap(client)` wraps a
+provider client you already have, reads token usage out of the response
+object it already returns (no extra network hop), normalizes it to a
+canonical disjoint counter shape, and ships batches to the Token Meter Ingest
+API in the background.
+
+## Install
+
+```sh
+pip install tokenmeter-sdk
+```
+
+**Note:** the PyPI distribution is named `tokenmeter-sdk` (like the npm
+package `@tokenmeter/sdk`), but the import name is `tokenmeter`:
+`import tokenmeter`. Distribution and import names are allowed to differ;
+the unrelated PyPI project `tokenmeter` blocks the shorter names.
+
+The SDK is public and installable by anyone — it does nothing without a
+`tl_live_` ingest key; rate limits, tier caps, and soft-lock are all
+enforced server-side at the ingest door.
+
+## Quick start
+
+```python
+import tokenmeter
+from openai import OpenAI
+
+tokenmeter.init(ingest_key="tl_live_...")
+client = tokenmeter.wrap(OpenAI())
+
+with tokenmeter.action("generate-report", customer_id="acme", feature="reports"):
+    client.chat.completions.create(model="gpt-4o-mini", messages=[...])
+    # usage for this call is captured automatically, tagged with
+    # customer_ref=acme, feature=reports, and a shared trace_id.
+```
+
+`wrap()` detects the client shape structurally (no hard dependency on any
+provider's package) and is idempotent — wrapping an already-wrapped client or
+method is a no-op.
+
+### Optimization measurements for agents
+
+Enable local prompt-prefix fingerprinting once with
+`tokenmeter.init(ingest_key=key, optimization={"prompt_caching": True})`.
+Declare delay tolerance only for suitable background tasks with
+`tokenmeter.action("report", optimization={"max_completion_delay_ms": 86400000})`.
+The SDK includes metadata in its normal usage events; users do not add HTTP
+headers. Both settings are optional and default to off/absent. An inner action
+can disable them with `"prompt_caching": False` and
+`"max_completion_delay_ms": None`. See
+[integration and deployment details](../../docs/SDK_OPTIMIZATION_TELEMETRY.md)
+for supported agents, privacy behavior and detector requirements.
+
+### Prompt topics
+
+Label each call with what it is about, for Analytics > Use cases, without sending any prompt text:
+
+```python
+tokenmeter.init(ingest_key=key, optimization={"topic_classifier": tokenmeter.keyword_topic_classifier})
+```
+
+The classifier runs in your process on the latest user message and returns a topic key (such as `debugging` or
+`legal_review`); only that key is sent, as `tags["prompt_topic"]`. Anything that is not a key
+(`^[a-z][a-z0-9_]{1,39}$`) is dropped. Supply your own synchronous function for better labels; an async one, or one
+that raises, is ignored and the call is untouched. Turn it off for one action with
+`optimization={"topic_classifier": None}`. Set it in `init()`: a classifier in an `action()` does not survive
+`TraceContext.to_dict()` across a queue.
+
+For an OpenAI-compatible client pointed at xAI, Mistral, Fireworks, Together
+AI, DeepInfra, OpenRouter, or Vercel AI Gateway (`"vercel_gateway"`), preserve
+the billable provider explicitly:
+
+```python
+client = tokenmeter.wrap_openai_compatible(
+    OpenAI(api_key="...", base_url="https://api.together.xyz/v1"), "together"
+)
+```
+
+## Provider support matrix
+
+| Provider | Client | Paths wrapped | Streaming | Normalization confidence |
+|---|---|---|---|---|
+| OpenAI | `openai.OpenAI` / `AsyncOpenAI` | `chat.completions.create`, `responses.create` | Yes (both) | **Proven live** — `prompt_tokens` held constant at 2107 across cached/uncached calls (`docs/spikes/openai-billing.md`) |
+| Anthropic | `anthropic.Anthropic` / `AsyncAnthropic` | `messages.create` | Yes | Doc-stated; cache reads reported separately, passthrough only |
+| Azure OpenAI | `openai.AzureOpenAI` / `AsyncAzureOpenAI` | `chat.completions.create`, `responses.create` | Yes (both) | **Doc-inferred only, NOT empirically verified.** Same field shape as OpenAI, so the same subtraction rule is assumed to apply — but the 5-call cache probe that proved OpenAI's rule has not been replayed against a real Azure deployment. Treat as provisional until that probe runs (`docs/spikes/provider-shapes.md` §2.1, §7) |
+| Google Gemini | `google.genai.Client` | `models.generate_content`, `models.generate_content_stream` | Yes (separate method, not a `stream=True` kwarg) | Doc-verified (`docs/spikes/provider-shapes.md` §3) — mixed rule: cached tokens ARE a subset of prompt (subtract), thinking tokens are NOT a subset of output (do not subtract). Streaming "last chunk is complete" behavior is community-observed, not doc-confirmed |
+| AWS Bedrock — `Converse`/`ConverseStream` | `boto3` `bedrock-runtime` client | `converse`, `converse_stream` | Yes | Doc-verified disjoint (`docs/spikes/provider-shapes.md` §1.1) — the primary, normalized path across model families |
+| AWS Bedrock — `InvokeModel` (Anthropic body) | same | `invoke_model` | No | Doc-verified — reuses native Anthropic semantics |
+| AWS Bedrock — `InvokeModel` (Amazon Nova body) | same | `invoke_model` | No | Doc-verified shape; cache-counter key **casing** is unconfirmed (AWS's own docs disagree) — both spellings are probed defensively |
+| AWS Bedrock — `InvokeModel` (other families / headers fallback) | same | `invoke_model` | No | Input/output only, via `x-amzn-bedrock-*-token-count` response headers; no cache/reasoning split. **Mistral bodies carry no usage at all** — this is the only source for them |
+| AWS Bedrock — `InvokeModelWithResponseStream` | same | `invoke_model_with_response_stream` | Yes | Reads `amazon-bedrock-invocationMetrics` from the terminal chunk; input/output only, no cache split |
+
+Not covered: async `google-genai` (`client.aio.models`), `aioboto3`, and
+`InvokeModel` body parsers for Meta Llama beyond the documented
+`prompt_token_count`/`generation_token_count` shape. Add as needed — the
+header fallback already covers these families with reduced granularity.
+
+**A provider integration is not "done" until its CI fixture exists** (PRD
+§7.1) — see `tests/test_normalize_*.py`, one file per provider, each pinning
+the exact per-provider arithmetic against a recorded fixture in
+`tests/fixtures/`.
+
+## The normalization arithmetic, per provider
+
+Every provider is converted to the same disjoint canonical shape
+(`input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_write_tokens`,
+`reasoning_tokens`, each independently nullable) so that
+`sum(class_count * class_price)` is correct downstream by construction. The
+arithmetic that gets there is **not** the same across providers — two of them
+invert the OpenAI reflex:
+
+- **OpenAI / Azure OpenAI**: `input = prompt_tokens − cached_tokens`,
+  `output = completion_tokens − reasoning_tokens`. Both are subsets and must
+  be subtracted out.
+- **Anthropic**: cache reads/writes are reported **separately** from
+  `input_tokens` already — passthrough, no subtraction. Subtracting would
+  double-count them as missing.
+- **AWS Bedrock (`Converse`)**: `input = inputTokens` **as-is** — it already
+  excludes cache reads/writes (`total input = inputTokens + cacheReadInputTokens
+  + cacheWriteInputTokens`, doc-verified). Subtracting cache reads here would
+  **double-discount**. `reasoning_tokens` is always `null` — no such field
+  exists; Claude thinking tokens are billed inside `outputTokens`.
+- **Google Gemini**: `input = promptTokenCount − cachedContentTokenCount`
+  (cached **is** a subset, subtract — same direction as OpenAI), but
+  `output = candidatesTokenCount` **as-is** — `thoughtsTokenCount` is
+  **separate**, not a subset. Subtracting it would silently **undercount**
+  the most expensive (reasoning-heavy) traffic.
+
+See `src/tokenmeter/_normalize.py` for the implementation and
+`docs/spikes/provider-shapes.md` for the full citations.
+
+## Azure: the deployment-name landmine
+
+Azure's Responses API returns the **deployment name**, not the canonical
+model id — a deployment named `prod-summarizer` matches nothing in the
+pricing catalog. Pass an optional deployment → model id map to `wrap()`:
+
+```python
+client = tokenmeter.wrap(
+    AzureOpenAI(...),
+    model_map={"prod-summarizer": "gpt-5-2025-08-07"},
+)
+```
+
+Unmapped deployments pass through unresolved and land in the unpriced
+quarantine rather than silently mispricing. `model_map` is ignored for every
+other provider.
+
+## Streaming and failure contracts (all providers)
+
+- **Never throws into host code.** Only tokenmeter's own bookkeeping is
+  try/except'd; the real provider call and its real exceptions pass through
+  untouched — proven for the transport, the buffer, and every wrapper's
+  success/error/stream paths in `tests/test_transport_never_throws.py` and
+  the per-provider `test_wrap_*.py` files.
+- **Never adds latency.** Capture is post-hoc from the response object the
+  provider already returned — no network I/O on the metering path. The one
+  exception worth naming: Bedrock `InvokeModel`'s response body is read
+  in-memory to extract usage and then replayed via a fresh in-memory stream
+  so the host's own `response["body"].read()` still works — this adds
+  in-memory work, never a network hop.
+- **A stream that aborts before its terminal usage frame** (or a provider
+  response with no usage at all) is recorded `usage_complete=false` with
+  every token field `null` — never estimated from partial deltas.
+- **Context propagation** (`trace_id`/`action`/`customer_ref`/...) is
+  snapshotted at call time and threaded through every wrapper, including
+  streams handed off to be iterated later — see
+  `tests/test_context_propagation.py` and the context-propagation cases in
+  each `test_wrap_*.py`.

tokenmeter_sdk-0.2.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+tokenmeter/__init__.py,sha256=3YZ8_n55Rf2taZoaX3ZYH8zNVwWk5mARraV-eK5QmDw,1394
+tokenmeter/_buffer.py,sha256=0w-ln8r1Vnf1vN0LCYd31nVMfwVmGRD44E0StCaaUuQ,8601
+tokenmeter/_client.py,sha256=qxmhjl9n7jLf_ToJcQWXkygS_rO82p0UblALD85nB5I,2556
+tokenmeter/_context.py,sha256=E40ZUisb9ibIQCaiQraIKUQrBD7zupdKsSWYGycwLY4,5272
+tokenmeter/_diagnose.py,sha256=9x6NRfvl02Xkv5Nkw8iosU2RmPIyRrsQcLfLNeBfnZ4,3088
+tokenmeter/_ids.py,sha256=AapWpP9T4rFsddRJ1tSu8W8lc6ekDM2wTptdR6LHA0Q,1653
+tokenmeter/_normalize.py,sha256=pba2ULse1ulY_C2r7BVlntJv-T7Hc8m1wzSoKjU4QmE,10420
+tokenmeter/_optimization.py,sha256=laG-nlAxac6VU4L17RQiugU9hlkLoIQU-bVHMdwx93c,4117
+tokenmeter/_preflight.py,sha256=CR-bjnKBd9Zri6siR2ZZdoxTJ4W8sYsAy8TCd47Cu_k,7540
+tokenmeter/_read_api.py,sha256=zsmxxd5MIPc2QVQl7QhJFb6XA1PAaMNAsgFSIPsJOrk,2132
+tokenmeter/_topic.py,sha256=2-hDvQ9uj9vPgMPp6h6ipskU88THVjhMe03Rvp14nYk,4591
+tokenmeter/_transport.py,sha256=pqDSgggQ_kZdYW0VndfWc1Hj68s16pzGuj8FNJlQW_8,3425
+tokenmeter/_wrap.py,sha256=Iu3H2_dkJkXdXvAToGxZMbCbOfCrOuWQreSNooTI_xo,37231
+tokenmeter_sdk-0.2.0.dist-info/licenses/LICENSE,sha256=4Bo5yCSg2wD8laNyw-MejzE-MS-zpxE8OU4cz5ZtKJA,1092
+tokenmeter_sdk-0.2.0.dist-info/METADATA,sha256=IbwfC70xnT6ESpDVTe56TebQp1lc0y9nRf2PwkPsMOQ,12050
+tokenmeter_sdk-0.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+tokenmeter_sdk-0.2.0.dist-info/top_level.txt,sha256=VBoi9Vy7-LSAISqogxfAY1AX-MT_dwwKjaNLWK-ZHfw,11
+tokenmeter_sdk-0.2.0.dist-info/RECORD,,

tokenmeter_sdk-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

tokenmeter_sdk-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Saqlain Rashid
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tokenmeter_sdk-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+tokenmeter