tokenmeter-sdk 0.2.0__tar.gz → 0.2.1__tar.gz

{tokenmeter_sdk-0.2.0/src/tokenmeter_sdk.egg-info → tokenmeter_sdk-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tokenmeter-sdk
-Version: 0.2.0
+Version: 0.2.1
 Summary: Token Meter Python SDK: wraps OpenAI/Anthropic/Gemini/Bedrock/Azure clients and meters token usage
 Author: Saqlain Rashid
 License-Expression: MIT
@@ -36,20 +36,6 @@ 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
@@ -128,6 +114,38 @@ client = tokenmeter.wrap_openai_compatible(
 )
 ```
 
+## 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. Rows use camelCase keys (`pricedCostUsd`, `nextCursor`). See the [API reference](https://timewastevc.com/docs/reference#read-api) for pagination and fields.
+
+## Governance preflight
+
+For calls made to a provider directly (not through the Token Meter router), ask the router's control plane first
+whether the call is allowed:
+
+```python
+tokenmeter.init(ingest_key="tl_live_...", router_url="https://router.timewastevc.com")
+
+with tokenmeter.governed(provider="openai", model="gpt-4o", content=prompt, max_output_tokens=800):
+    client.chat.completions.create(model="gpt-4o", messages=messages, max_tokens=800)
+```
+
+Unlike metering, this is on the request path: it adds one HTTP call to the router (2 s timeout), raises
+`tokenmeter.GovernanceDenied` on a denial (`governance_mode="advisory"` only records it), and raises
+`tokenmeter.GovernanceUnavailable` when the router can't be reached (`governance_fail_mode="open"` proceeds
+unprotected). A wrong or revoked ingest key (401, 403) or a malformed request (400) always raises
+`tokenmeter.GovernanceRejected`, whatever the fail mode is: it is not an outage. See the [API reference](https://timewastevc.com/docs/reference#preflight).
+
 ## Provider support matrix
 
 | Provider | Client | Paths wrapped | Streaming | Normalization confidence |

{tokenmeter_sdk-0.2.0 → tokenmeter_sdk-0.2.1}/README.md

@@ -1,19 +1,5 @@
 # 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
@@ -92,6 +78,38 @@ client = tokenmeter.wrap_openai_compatible(
 )
 ```
 
+## 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. Rows use camelCase keys (`pricedCostUsd`, `nextCursor`). See the [API reference](https://timewastevc.com/docs/reference#read-api) for pagination and fields.
+
+## Governance preflight
+
+For calls made to a provider directly (not through the Token Meter router), ask the router's control plane first
+whether the call is allowed:
+
+```python
+tokenmeter.init(ingest_key="tl_live_...", router_url="https://router.timewastevc.com")
+
+with tokenmeter.governed(provider="openai", model="gpt-4o", content=prompt, max_output_tokens=800):
+    client.chat.completions.create(model="gpt-4o", messages=messages, max_tokens=800)
+```
+
+Unlike metering, this is on the request path: it adds one HTTP call to the router (2 s timeout), raises
+`tokenmeter.GovernanceDenied` on a denial (`governance_mode="advisory"` only records it), and raises
+`tokenmeter.GovernanceUnavailable` when the router can't be reached (`governance_fail_mode="open"` proceeds
+unprotected). A wrong or revoked ingest key (401, 403) or a malformed request (400) always raises
+`tokenmeter.GovernanceRejected`, whatever the fail mode is: it is not an outage. See the [API reference](https://timewastevc.com/docs/reference#preflight).
+
 ## Provider support matrix
 
 | Provider | Client | Paths wrapped | Streaming | Normalization confidence |

{tokenmeter_sdk-0.2.0 → tokenmeter_sdk-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tokenmeter-sdk"
-version = "0.2.0"
+version = "0.2.1"
 description = "Token Meter Python SDK: wraps OpenAI/Anthropic/Gemini/Bedrock/Azure clients and meters token usage"
 readme = "README.md"
 license = "MIT"

{tokenmeter_sdk-0.2.0 → tokenmeter_sdk-0.2.1}/src/tokenmeter/__init__.py

@@ -10,7 +10,7 @@
 from ._client import init
 from ._context import TraceContext, action, attach, current
 from ._diagnose import diagnose
-from ._preflight import GovernanceDenied, GovernanceUnavailable, PreflightDecision, governed, preflight
+from ._preflight import GovernanceDenied, GovernanceRejected, 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
@@ -29,6 +29,7 @@ __all__ = [
     "governed",
     "PreflightDecision",
     "GovernanceDenied",
+    "GovernanceRejected",
     "GovernanceUnavailable",
     "ReadApiClient",
     "TokenMeterReadClient",
@@ -37,7 +38,7 @@ __all__ = [
     "latest_user_text",
 ]
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"
 
 
 def flush(deadline_s: float = 2.0) -> None:

{tokenmeter_sdk-0.2.0 → tokenmeter_sdk-0.2.1}/src/tokenmeter/_buffer.py

@@ -17,11 +17,23 @@ logger = logging.getLogger("tokenmeter")
 DEFAULT_MAXSIZE = 10_000
 DEFAULT_FLUSH_INTERVAL_S = 2.0
 DEFAULT_FLUSH_BATCH_SIZE = 500
+# Ingest refuses a batch with more events than this (413 batch_too_large, QUOTAS.EVENTS_PER_BATCH). The TypeScript
+# SDK clamps to the same number (MAX_EVENTS_PER_BATCH in client.ts).
+MAX_EVENTS_PER_BATCH = 1_000
 # DECISIONS.md §8: sustained rate limiting must be LOUD, not a silent spin.
 # 5 consecutive 429s at the default 2s flush interval is ~10s of sustained
 # rejection -- past one unlucky fixed-window boundary straddle, short of
 # letting the ~10k-event ring buffer fill silently.
 CONSECUTIVE_429_WARN_THRESHOLD = 5
+# After a failure that may pass (429, 5xx, network), wait before the next attempt: 1s, doubling to 60s, as the
+# TypeScript SDK does. A 429's Retry-After is used instead when the server sends one.
+BACKOFF_INITIAL_S = 1.0
+BACKOFF_MAX_S = 60.0
+RETRY_AFTER_MAX_S = 300.0
+# Answers that will be the same however often the batch is re-sent. 401/403: the ingest key is wrong or revoked.
+# 400: the batch itself is malformed. Retrying them is the bug this list exists to prevent.
+_PERMANENT_STATUSES = (400, 401, 403)
+_AUTH_STATUSES = (401, 403)
 
 
 class RingBuffer:
@@ -80,6 +92,13 @@ class RingBuffer:
         with self._lock:
             self._dropped = max(0, self._dropped - n)
 
+    def count_dropped(self, n: int) -> None:
+        """Add n events the flusher gave up on (a batch the server will never
+        accept) to the pending drop count, so the loss is reported with the
+        next batch that is accepted instead of disappearing."""
+        with self._lock:
+            self._dropped += n
+
     def requeue(self, events: List[dict]) -> None:
         """Put a drained-but-unsent batch back, oldest-first, for a failed
         send -- mirrors the TypeScript SDK's unshiftMany(). Without this,
@@ -99,7 +118,17 @@ class RingBuffer:
 
 
 class Flusher:
-    """Background thread: flush when len(buffer) >= batch_size OR every interval_s."""
+    """Background thread: flush when len(buffer) >= batch_size OR every interval_s.
+
+    One request carries at most `batch_size` events, never more than ingest accepts (MAX_EVENTS_PER_BATCH); a backlog
+    goes out as several requests. What happens after a failed request depends on why it failed:
+
+    - 401 / 403 / 400: the answer will not change. The batch is dropped and counted, and a rejected key is reported
+      once, loudly.
+    - 413: the batch is too large in bytes. It is put back and the next request carries half as many events; one
+      event that is too large by itself is dropped and counted.
+    - 429, 5xx, a network error: the batch is put back and the next attempt waits (Retry-After, or 1s doubling to 60s).
+    """
 
     def __init__(
         self,
@@ -112,13 +141,18 @@ class Flusher:
         self._buffer = buffer
         self._send = send
         self._interval_s = interval_s
-        self._batch_size = batch_size
+        self._batch_size = max(1, min(int(batch_size), MAX_EVENTS_PER_BATCH))
         self._wake = threading.Event()
         self._stop = threading.Event()
         self._thread = threading.Thread(target=self._run, name="tokenmeter-flusher", daemon=True)
         self._atexit_registered = False
         self._consecutive_429s = 0
         self._warned_sustained_429 = False
+        self._warned_rejected_key = False
+        # Set after a 413: the next request carries at most this many events. Cleared by the next accepted batch.
+        self._split_limit: Optional[int] = None
+        self._backoff_s = 0.0
+        self._retry_at = 0.0  # time.monotonic() before which the background thread does not try again
 
     def start(self) -> None:
         self._thread.start()
@@ -126,21 +160,40 @@ class Flusher:
             atexit.register(self.flush_best_effort, deadline_s=2.0)
             self._atexit_registered = True
 
+    def backoff_remaining_s(self) -> float:
+        """Seconds until the background thread tries again after a failure; 0 when it is not waiting."""
+        return max(0.0, self._retry_at - time.monotonic())
+
     def notify(self) -> None:
-        """Called on every append; wakes the flusher early once batch_size is hit."""
-        if len(self._buffer) >= self._batch_size:
+        """Called on every append; wakes the flusher early once batch_size is hit.
+
+        Not while it is backing off: the buffer stays full for as long as sends fail, so every emit would otherwise
+        turn the wait into an immediate retry."""
+        if len(self._buffer) >= self._batch_size and self.backoff_remaining_s() == 0:
             self._wake.set()
 
     def _run(self) -> None:
         while not self._stop.is_set():
             self._wake.wait(timeout=self._interval_s)
             self._wake.clear()
-            self._flush_once()
+            # A wake that was already set when the failure happened must not cut the backoff short.
+            remaining = self.backoff_remaining_s()
+            if remaining > 0 and self._stop.wait(timeout=remaining):
+                break
+            self._flush_all()
+
+    def _flush_all(self) -> None:
+        """Send batch after batch until the buffer is empty or a request fails."""
+        while self._flush_once() and len(self._buffer) > 0:
+            pass
 
-    def _flush_once(self) -> None:
-        events = self._buffer.drain()
+    def _flush_once(self) -> bool:
+        """Send one batch. True when it is worth sending the next one straight away: the batch was accepted, or it
+        was refused for its size and the next one will be smaller."""
+        limit = self._batch_size if self._split_limit is None else min(self._batch_size, self._split_limit)
+        events = self._buffer.drain(limit)
         if not events:
-            return
+            return False
         # Peek, don't consume: the count is only "communicated" once the
         # server actually acknowledges it. take_dropped() used to be called
         # unconditionally here, BEFORE knowing whether send() would even
@@ -152,16 +205,69 @@ class Flusher:
         try:
             self._send(events, dropped)
         except Exception as exc:  # SDK NEVER throws into host code -- swallow, log, move on.
-            # drain() already removed these from the buffer; without putting
-            # them back, a failed send silently discarded the whole batch --
-            # not just under-counted drops, an actual data-loss bug.
-            self._buffer.requeue(events)
-            self._note_failure(exc)
             logger.debug("tokenmeter: flush failed", exc_info=True)
-            return
+            return self._after_failure(events, exc)
         self._buffer.release_dropped(dropped)
         self._consecutive_429s = 0
         self._warned_sustained_429 = False
+        self._warned_rejected_key = False
+        self._split_limit = None
+        self._backoff_s = 0.0
+        self._retry_at = 0.0
+        return True
+
+    def _after_failure(self, events: List[dict], exc: Exception) -> bool:
+        code = getattr(exc, "code", None)
+        if code in _PERMANENT_STATUSES:
+            # drain() already removed these; they are not put back, because re-sending gets the same answer.
+            self._buffer.count_dropped(len(events))
+            self._note_failure(exc)
+            if code in _AUTH_STATUSES:
+                self._warn_rejected_key(code, len(events))
+                self._back_off(exc)  # the next batch gets the same answer: do not hammer the endpoint with them
+            else:
+                logger.warning("tokenmeter: ingest refused a batch of %d events as malformed (HTTP 400); they were dropped.", len(events))
+            return False
+        if code == 413:
+            self._note_failure(exc)
+            if len(events) == 1:
+                self._buffer.count_dropped(1)
+                self._split_limit = None
+                logger.warning("tokenmeter: one event is larger than ingest accepts (HTTP 413); it was dropped.")
+                return True
+            self._buffer.requeue(events)
+            self._split_limit = max(1, len(events) // 2)
+            return True
+        # 429, 5xx, a network error: drain() already removed these from the buffer; without putting
+        # them back, a failed send silently discarded the whole batch.
+        self._buffer.requeue(events)
+        self._note_failure(exc)
+        self._back_off(exc)
+        return False
+
+    def _back_off(self, exc: Exception) -> None:
+        retry_after = _retry_after_s(exc) if getattr(exc, "code", None) == 429 else None
+        if retry_after is not None:
+            wait = retry_after
+        else:
+            self._backoff_s = BACKOFF_INITIAL_S if self._backoff_s == 0 else min(self._backoff_s * 2, BACKOFF_MAX_S)
+            wait = self._backoff_s
+        self._retry_at = time.monotonic() + wait
+
+    def _warn_rejected_key(self, code: int, lost: int) -> None:
+        """A wrong or revoked key is the host's to fix, and nothing is recorded until it is: say so once per
+        incident, where it will be seen (print + log, never raise -- as the 429 warning does)."""
+        if self._warned_rejected_key:
+            return
+        self._warned_rejected_key = True
+        reason = "is not a valid key" if code == 401 else "has been revoked or has expired"
+        msg = (
+            f"tokenmeter: ingest rejected this SDK's ingest key (HTTP {code}): it {reason}. "
+            f"{lost} events were dropped and nothing will be recorded until the key is replaced "
+            "(TOKEN_METER_KEY, or the ingest_key passed to tokenmeter.init). Run tokenmeter.diagnose() for more detail."
+        )
+        logger.warning(msg)
+        print("[tokenmeter] WARNING: " + msg)
 
     def _note_failure(self, exc: Exception) -> None:
         """DECISIONS.md §8: sustained 429s must be loud, not a silent retry
@@ -188,14 +294,35 @@ class Flusher:
             print("[tokenmeter] WARNING: " + msg)
 
     def flush_best_effort(self, deadline_s: float = 2.0) -> None:
-        """Synchronous, best-effort, capped flush -- used by atexit and public flush()."""
+        """Synchronous, best-effort, capped flush -- used by atexit and public flush().
+
+        Sends batch after batch until the buffer is empty, the deadline passes, or a request fails. It stops at the
+        first failure: re-sending to an endpoint that just failed, in a tight loop until the deadline, delivers
+        nothing and holds the host's exit for the whole deadline. What is left stays buffered for the next flush."""
         deadline = time.monotonic() + deadline_s
         try:
             while len(self._buffer) > 0 and time.monotonic() < deadline:
-                self._flush_once()
+                if not self._flush_once():
+                    break
         except Exception:
             logger.debug("tokenmeter: atexit flush failed", exc_info=True)
 
     def stop(self) -> None:
         self._stop.set()
         self._wake.set()
+
+
+def _retry_after_s(exc: Exception) -> Optional[float]:
+    """The Retry-After of a 429, in seconds, when the server sent a usable one (urllib's HTTPError carries the
+    response headers). Capped, so a wrong header cannot park the flusher for hours."""
+    headers = getattr(exc, "headers", None)
+    try:
+        raw = headers.get("Retry-After") if headers is not None else None
+        if raw is None:
+            return None
+        value = float(raw)
+    except (AttributeError, TypeError, ValueError):
+        return None
+    if value != value or value < 0:  # NaN or negative
+        return None
+    return min(max(value, BACKOFF_INITIAL_S), RETRY_AFTER_MAX_S)

{tokenmeter_sdk-0.2.0 → tokenmeter_sdk-0.2.1}/src/tokenmeter/_diagnose.py

@@ -14,8 +14,8 @@ from ._client import DEFAULT_ENDPOINT, get_state
 from ._transport import Transport
 
 _STATUS_HINTS = {
-    401: "invalid_key: the ingest key is wrong, revoked, or malformed. Check tokenmeter.init(ingest_key=...).",
-    403: "key_revoked: this key (or its org) was revoked/purged. Issue a new key from the dashboard.",
+    401: "invalid_key: the ingest key is wrong or malformed. Check tokenmeter.init(ingest_key=...).",
+    403: "key_revoked: this key was revoked or has expired, or its workspace was deleted. Issue a new key under Governance > Keys.",
     413: "batch_too_large: unrelated to diagnose() itself -- your real traffic is sending oversized batches.",
     429: "rate_limited: traffic looks abuse-shaped (well over the plan quota), not ordinary overage -- ordinary overage is accepted (DECISIONS.md §8). A single 429 is retried and not data loss; SUSTAINED 429s can be, since this SDK's local buffer is bounded -- watch for the sustained-429 warning this SDK logs.",
     503: "unavailable: TokenMeter ingest is temporarily down. Events buffer locally and retry.",

{tokenmeter_sdk-0.2.0 → tokenmeter_sdk-0.2.1}/src/tokenmeter/_preflight.py

@@ -1,6 +1,6 @@
 """Governance preflight for direct provider calls (TS SDK: src/preflight.ts).
 
-    tokenmeter.init(ingest_key="tl_live_...", router_url="https://router.example.com")
+    tokenmeter.init(ingest_key="tl_live_...", router_url="https://router.timewastevc.com")
     with tokenmeter.governed(provider="openai", model="gpt-4o", content=prompt, max_output_tokens=800):
         client.chat.completions.create(model="gpt-4o", messages=..., max_tokens=800)
 
@@ -11,9 +11,11 @@ carries the decision id (tags.preflight_id), which is what lets TokenMeter repor
 the call as preflight-protected instead of detected after the fact.
 
 Unlike telemetry, this IS on the request path, so it is allowed to raise:
-GovernanceDenied for a denial in "enforce" mode (default), and
+GovernanceDenied for a denial in "enforce" mode (default),
 GovernanceUnavailable when the control plane cannot be reached and
-fail_mode is "closed" (default). stdlib only, like _transport.py.
+fail_mode is "closed" (default), and GovernanceRejected, whatever fail_mode
+is, when the control plane refuses the ingest key (401, 403) or the request
+(400). stdlib only, like _transport.py.
 """
 from __future__ import annotations
 
@@ -81,6 +83,37 @@ class GovernanceUnavailable(Exception):
     pass
 
 
+class GovernanceRejected(Exception):
+    """The control plane answered, and refused the request itself: the ingest key is wrong (401) or revoked (403),
+    or the request is malformed (400). Not an outage, so fail_mode does not apply: a rejected key under
+    fail_mode="open" would otherwise let every call run unprotected for as long as the key stayed bad."""
+
+    def __init__(self, status: int, code: Optional[str]) -> None:
+        what = (
+            "the ingest key is not a valid key" if status == 401
+            else "the ingest key has been revoked or has expired" if status == 403
+            else "the preflight request is malformed"
+        )
+        super().__init__(f"TokenMeter governance preflight was rejected (HTTP {status}{' ' + code if code else ''}): {what}")
+        self.status = status
+        self.code = code
+
+
+def _rejection_code(error: urllib.error.HTTPError) -> Optional[str]:
+    """The router's error code from a refusal body ({"error_code": ..., "error": {"code": ...}}), if it sent one."""
+    try:
+        data = json.loads(error.read().decode("utf-8"))
+    except Exception:
+        return None
+    if not isinstance(data, dict):
+        return None
+    code = data.get("error_code")
+    if not isinstance(code, str):
+        nested = data.get("error")
+        code = nested.get("code") if isinstance(nested, dict) else nested
+    return code if isinstance(code, str) else None
+
+
 def _unavailable(detail: str) -> PreflightDecision:
     if _config.fail_mode == "closed":
         raise GovernanceUnavailable(f"TokenMeter governance preflight unavailable ({detail}); failing closed")
@@ -99,7 +132,8 @@ def preflight(
     estimated_input_tokens: Optional[int] = None,
     max_output_tokens: Optional[int] = None,
 ) -> PreflightDecision:
-    """Ask for a decision. Raises only GovernanceUnavailable (fail_mode='closed')."""
+    """Ask for a decision. Raises GovernanceUnavailable (fail_mode='closed') when the control plane cannot be
+    reached, and GovernanceRejected, whatever fail_mode is, when it refuses the key or the request."""
     if not _config.router_url or not _config.ingest_key:
         return _unavailable("router_url not configured -- pass router_url to tokenmeter.init()")
     ctx = current()
@@ -125,6 +159,10 @@ def preflight(
                 return _unavailable(f"HTTP {resp.status}")
             data = json.loads(resp.read().decode("utf-8"))
     except urllib.error.HTTPError as e:
+        # 400/401/403 are answers, not an outage: the same request gets the same answer until the key or the
+        # request is fixed.
+        if e.code in (400, 401, 403):
+            raise GovernanceRejected(e.code, _rejection_code(e)) from None
         return _unavailable(f"HTTP {e.code}")
     except Exception as e:  # network, timeout, bad JSON
         return _unavailable(type(e).__name__)

{tokenmeter_sdk-0.2.0 → tokenmeter_sdk-0.2.1}/src/tokenmeter/_topic.py

@@ -1,91 +1,91 @@
-"""SDK-side prompt topics (docs/PROMPT_INTELLIGENCE_AND_BUSINESS_UNITS_PLAN.md A-5). Same contract as the TypeScript
-SDK's topic.ts.
-
-Opt-in: pass ``optimization={"topic_classifier": fn}`` to ``tokenmeter.init`` (or ``action``) and each call is labelled
-with ``tags["prompt_topic"]``, a topic KEY your classifier returns. The prompt text never leaves your process: the
-classifier runs locally, and only a key matching ``^[a-z][a-z0-9_]{1,39}$`` is sent (anything else is dropped here,
-and again at ingest).
-
-The classifier must be synchronous and fast: it runs on the call path. A classifier that returns a coroutine, raises,
-or returns something that is not a key is ignored and the call proceeds untouched. ``keyword_topic_classifier`` is a
-small built-in one for the standard topic list (keywords only, no model).
-"""
-from __future__ import annotations
-
-import inspect
-import re
-from typing import Any, Callable, Optional
-
-TOPIC_KEY_RE = re.compile(r"^[a-z][a-z0-9_]{1,39}$")
-TOPIC_TEXT_CHARS = 2_000
-
-TopicClassifier = Callable[[str], Optional[str]]
-
-
-def _parts_text(value: Any) -> Optional[str]:
-    if isinstance(value, str):
-        return value
-    if not isinstance(value, list):
-        return None
-    parts = [p["text"] for p in value if isinstance(p, dict) and p.get("type") in ("text", "input_text") and isinstance(p.get("text"), str)]
-    return "\n".join(parts) if parts else None
-
-
-def latest_user_text(params: Any) -> Optional[str]:
-    """The last user message of a chat / messages / responses request, or a plain prompt string."""
-    if not isinstance(params, dict):
-        return None
-    messages = params.get("messages", params.get("input"))
-    if isinstance(messages, str):
-        return messages
-    if isinstance(messages, list):
-        for message in reversed(messages):
-            if isinstance(message, dict) and message.get("role") == "user":
-                text = _parts_text(message.get("content"))
-                if text and text.strip():
-                    return text
-        return None
-    prompt = params.get("prompt")
-    return prompt if isinstance(prompt, str) else None
-
-
-def topic_tag(classifier: Any, params: Any) -> Optional[str]:
-    """Runs the caller's classifier defensively; returns a valid key or None."""
-    if not callable(classifier):
-        return None
-    text = latest_user_text(params)
-    if not text or not text.strip():
-        return None
-    try:
-        key = classifier(text[:TOPIC_TEXT_CHARS])
-    except Exception:
-        return None
-    if inspect.isawaitable(key):
-        # An async classifier would add latency; it is ignored (and closed so it does not warn).
-        close = getattr(key, "close", None)
-        if callable(close):
-            close()
-        return None
-    return key if isinstance(key, str) and TOPIC_KEY_RE.match(key) else None
-
-
-# Order matters: the first rule that matches wins (an error report about code is debugging, not code generation).
-_KEYWORD_RULES = [
-    ("debugging", re.compile(r"\b(error|exception|stack ?trace|traceback|bug|crash(es|ed)?|failing|fails|broken|typeerror|nullpointer|segfault|doesn'?t work)\b", re.I)),
-    ("translation", re.compile(r"\b(translat(e|ion|ing)|in (french|spanish|german|italian|portuguese|japanese|chinese|korean|arabic|hindi|dutch))\b", re.I)),
-    ("summarisation", re.compile(r"\b(summar(y|ise|ize|ising|izing)|tl;?dr|condense|key points|recap)\b", re.I)),
-    ("data_extraction", re.compile(r"\b(extract|parse|pull out)\b[\s\S]{0,80}\b(fields?|json|table|entit(y|ies)|names?|dates?|values?|data)\b", re.I)),
-    ("classification", re.compile(r"\b(classif(y|ication)|categori[sz]e|sentiment|label (this|these|each)|which category)\b", re.I)),
-    ("customer_support", re.compile(r"\b(customer|ticket|refund|complaint|support request|reply to (this|the) (customer|user))\b", re.I)),
-    ("content_writing", re.compile(r"\b(blog|article|newsletter|tagline|headline|marketing copy|social (media )?post|write an? (email|post|story))\b", re.I)),
-    ("code_generation", re.compile(r"```|\b(write|implement|create|generate|build)\b[\s\S]{0,60}\b(function|class|script|code|query|sql|regex|component|endpoint|api|test)\b", re.I)),
-    ("analysis_qa", re.compile(r"\b(explain|why|how (does|do|can)|what (is|are)|compare|analy[sz]e|pros and cons)\b|\?\s*$", re.I)),
-]
-
-
-def keyword_topic_classifier(text: str) -> str:
-    """A keyword-only classifier for the standard topics. Coarse by design; supply your own for better labels."""
-    for key, pattern in _KEYWORD_RULES:
-        if pattern.search(text):
-            return key
-    return "other"
+"""SDK-side prompt topics (docs/PROMPT_INTELLIGENCE_AND_BUSINESS_UNITS_PLAN.md A-5). Same contract as the TypeScript
+SDK's topic.ts.
+
+Opt-in: pass ``optimization={"topic_classifier": fn}`` to ``tokenmeter.init`` (or ``action``) and each call is labelled
+with ``tags["prompt_topic"]``, a topic KEY your classifier returns. The prompt text never leaves your process: the
+classifier runs locally, and only a key matching ``^[a-z][a-z0-9_]{1,39}$`` is sent (anything else is dropped here,
+and again at ingest).
+
+The classifier must be synchronous and fast: it runs on the call path. A classifier that returns a coroutine, raises,
+or returns something that is not a key is ignored and the call proceeds untouched. ``keyword_topic_classifier`` is a
+small built-in one for the standard topic list (keywords only, no model).
+"""
+from __future__ import annotations
+
+import inspect
+import re
+from typing import Any, Callable, Optional
+
+TOPIC_KEY_RE = re.compile(r"^[a-z][a-z0-9_]{1,39}$")
+TOPIC_TEXT_CHARS = 2_000
+
+TopicClassifier = Callable[[str], Optional[str]]
+
+
+def _parts_text(value: Any) -> Optional[str]:
+    if isinstance(value, str):
+        return value
+    if not isinstance(value, list):
+        return None
+    parts = [p["text"] for p in value if isinstance(p, dict) and p.get("type") in ("text", "input_text") and isinstance(p.get("text"), str)]
+    return "\n".join(parts) if parts else None
+
+
+def latest_user_text(params: Any) -> Optional[str]:
+    """The last user message of a chat / messages / responses request, or a plain prompt string."""
+    if not isinstance(params, dict):
+        return None
+    messages = params.get("messages", params.get("input"))
+    if isinstance(messages, str):
+        return messages
+    if isinstance(messages, list):
+        for message in reversed(messages):
+            if isinstance(message, dict) and message.get("role") == "user":
+                text = _parts_text(message.get("content"))
+                if text and text.strip():
+                    return text
+        return None
+    prompt = params.get("prompt")
+    return prompt if isinstance(prompt, str) else None
+
+
+def topic_tag(classifier: Any, params: Any) -> Optional[str]:
+    """Runs the caller's classifier defensively; returns a valid key or None."""
+    if not callable(classifier):
+        return None
+    text = latest_user_text(params)
+    if not text or not text.strip():
+        return None
+    try:
+        key = classifier(text[:TOPIC_TEXT_CHARS])
+    except Exception:
+        return None
+    if inspect.isawaitable(key):
+        # An async classifier would add latency; it is ignored (and closed so it does not warn).
+        close = getattr(key, "close", None)
+        if callable(close):
+            close()
+        return None
+    return key if isinstance(key, str) and TOPIC_KEY_RE.match(key) else None
+
+
+# Order matters: the first rule that matches wins (an error report about code is debugging, not code generation).
+_KEYWORD_RULES = [
+    ("debugging", re.compile(r"\b(error|exception|stack ?trace|traceback|bug|crash(es|ed)?|failing|fails|broken|typeerror|nullpointer|segfault|doesn'?t work)\b", re.I)),
+    ("translation", re.compile(r"\b(translat(e|ion|ing)|in (french|spanish|german|italian|portuguese|japanese|chinese|korean|arabic|hindi|dutch))\b", re.I)),
+    ("summarisation", re.compile(r"\b(summar(y|ise|ize|ising|izing)|tl;?dr|condense|key points|recap)\b", re.I)),
+    ("data_extraction", re.compile(r"\b(extract|parse|pull out)\b[\s\S]{0,80}\b(fields?|json|table|entit(y|ies)|names?|dates?|values?|data)\b", re.I)),
+    ("classification", re.compile(r"\b(classif(y|ication)|categori[sz]e|sentiment|label (this|these|each)|which category)\b", re.I)),
+    ("customer_support", re.compile(r"\b(customer|ticket|refund|complaint|support request|reply to (this|the) (customer|user))\b", re.I)),
+    ("content_writing", re.compile(r"\b(blog|article|newsletter|tagline|headline|marketing copy|social (media )?post|write an? (email|post|story))\b", re.I)),
+    ("code_generation", re.compile(r"```|\b(write|implement|create|generate|build)\b[\s\S]{0,60}\b(function|class|script|code|query|sql|regex|component|endpoint|api|test)\b", re.I)),
+    ("analysis_qa", re.compile(r"\b(explain|why|how (does|do|can)|what (is|are)|compare|analy[sz]e|pros and cons)\b|\?\s*$", re.I)),
+]
+
+
+def keyword_topic_classifier(text: str) -> str:
+    """A keyword-only classifier for the standard topics. Coarse by design; supply your own for better labels."""
+    for key, pattern in _KEYWORD_RULES:
+        if pattern.search(text):
+            return key
+    return "other"

{tokenmeter_sdk-0.2.0 → tokenmeter_sdk-0.2.1}/src/tokenmeter/_transport.py

@@ -15,7 +15,7 @@ from ._ids import uuid7_str
 logger = logging.getLogger("tokenmeter")
 
 SDK_NAME = "python"
-SDK_VERSION = "0.2.0"
+SDK_VERSION = "0.2.1"
 SCHEMA_HASH = "v1"  # ponytail: bump when the wire event shape changes; not computed, just pinned
 
 

{tokenmeter_sdk-0.2.0 → tokenmeter_sdk-0.2.1/src/tokenmeter_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tokenmeter-sdk
-Version: 0.2.0
+Version: 0.2.1
 Summary: Token Meter Python SDK: wraps OpenAI/Anthropic/Gemini/Bedrock/Azure clients and meters token usage
 Author: Saqlain Rashid
 License-Expression: MIT
@@ -36,20 +36,6 @@ 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
@@ -128,6 +114,38 @@ client = tokenmeter.wrap_openai_compatible(
 )
 ```
 
+## 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. Rows use camelCase keys (`pricedCostUsd`, `nextCursor`). See the [API reference](https://timewastevc.com/docs/reference#read-api) for pagination and fields.
+
+## Governance preflight
+
+For calls made to a provider directly (not through the Token Meter router), ask the router's control plane first
+whether the call is allowed:
+
+```python
+tokenmeter.init(ingest_key="tl_live_...", router_url="https://router.timewastevc.com")
+
+with tokenmeter.governed(provider="openai", model="gpt-4o", content=prompt, max_output_tokens=800):
+    client.chat.completions.create(model="gpt-4o", messages=messages, max_tokens=800)
+```
+
+Unlike metering, this is on the request path: it adds one HTTP call to the router (2 s timeout), raises
+`tokenmeter.GovernanceDenied` on a denial (`governance_mode="advisory"` only records it), and raises
+`tokenmeter.GovernanceUnavailable` when the router can't be reached (`governance_fail_mode="open"` proceeds
+unprotected). A wrong or revoked ingest key (401, 403) or a malformed request (400) always raises
+`tokenmeter.GovernanceRejected`, whatever the fail mode is: it is not an outage. See the [API reference](https://timewastevc.com/docs/reference#preflight).
+
 ## Provider support matrix
 
 | Provider | Client | Paths wrapped | Streaming | Normalization confidence |