tokenmeter-sdk 0.2.0__tar.gz

tokenmeter_sdk-0.2.0/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/MANIFEST.in

@@ -0,0 +1,3 @@
+prune tests
+prune .pytest_cache
+global-exclude __pycache__ *.py[cod]

tokenmeter_sdk-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,185 @@
+# 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/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "tokenmeter-sdk"
+version = "0.2.0"
+description = "Token Meter Python SDK: wraps OpenAI/Anthropic/Gemini/Bedrock/Azure clients and meters token usage"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "Saqlain Rashid" }]
+keywords = ["llm", "tokens", "usage", "metering", "observability", "openai", "anthropic", "vercel-ai-gateway"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/SaqlainRashed/token-meter"
+Repository = "https://github.com/SaqlainRashed/token-meter"
+Changelog = "https://github.com/SaqlainRashed/token-meter/blob/main/sdks/python/CHANGELOG.md"
+
+[project.optional-dependencies]
+openai = ["openai>=1.0"]
+anthropic = ["anthropic>=0.30"]
+gemini = ["google-genai>=0.1"]
+bedrock = ["boto3>=1.34"]
+azure = ["openai>=1.0"]
+dev = ["pytest>=8"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]

tokenmeter_sdk-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tokenmeter_sdk-0.2.0/src/tokenmeter/__init__.py

@@ -0,0 +1,49 @@
+"""TokenMeter Python SDK.
+
+    import tokenmeter
+    tokenmeter.init(ingest_key="tl_live_...")
+    client = tokenmeter.wrap(OpenAI())
+
+    with tokenmeter.action("generate-report", customer_id="acme", feature="reports"):
+        client.chat.completions.create(...)
+"""
+from ._client import init
+from ._context import TraceContext, action, attach, current
+from ._diagnose import diagnose
+from ._preflight import GovernanceDenied, GovernanceUnavailable, PreflightDecision, governed, preflight
+from ._wrap import wrap, wrap_openai_compatible
+from ._read_api import ReadApiClient, ReadApiError, TokenMeterReadClient
+from ._topic import keyword_topic_classifier, latest_user_text
+
+__all__ = [
+    "init",
+    "wrap",
+    "wrap_openai_compatible",
+    "action",
+    "current",
+    "attach",
+    "TraceContext",
+    "diagnose",
+    "flush",
+    "preflight",
+    "governed",
+    "PreflightDecision",
+    "GovernanceDenied",
+    "GovernanceUnavailable",
+    "ReadApiClient",
+    "TokenMeterReadClient",
+    "ReadApiError",
+    "keyword_topic_classifier",
+    "latest_user_text",
+]
+
+__version__ = "0.2.0"
+
+
+def flush(deadline_s: float = 2.0) -> None:
+    """Best-effort synchronous flush. Never raises."""
+    from ._client import get_state
+
+    state = get_state()
+    if state is not None:
+        state.flusher.flush_best_effort(deadline_s=deadline_s)