tokenmeter-sdk 0.2.0__py3-none-any.whl

tokenmeter/_normalize.py

@@ -0,0 +1,239 @@
+"""Disjoint canonical token-counter normalization (PRD §7.1 / DECISIONS §B3).
+
+Every provider must be converted to the SAME disjoint shape so that
+sum(class_count * class_price) is correct by construction downstream:
+
+    input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, reasoning_tokens
+
+Each field is nullable and a null means "provider didn't report this", never a
+guessed zero. A provider-reported explicit 0 stays 0.
+
+OpenAI: `cached_tokens` is a SUBSET of `prompt_tokens`, and `reasoning_tokens` is a
+SUBSET of `completion_tokens` -- both must be subtracted out.
+
+Anthropic: cache reads/writes are reported SEPARATELY from `input_tokens` already
+(Anthropic's own billing counts them apart) -- the normalizer here is a straight
+field rename/passthrough, no arithmetic, which is itself the thing the fixture
+proves (a naive implementer's instinct is to subtract, which would double-subtract
+and undercount).
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+_NULL = {
+    "input_tokens": None,
+    "output_tokens": None,
+    "cache_read_tokens": None,
+    "cache_write_tokens": None,
+    "reasoning_tokens": None,
+}
+
+
+def _get(d: Optional[dict], *path):
+    cur = d
+    for key in path:
+        if cur is None:
+            return None
+        cur = cur.get(key)
+    return cur
+
+
+def normalize_openai_usage(usage: dict) -> dict:
+    """Accepts either the chat/completions `CompletionUsage` shape
+    (prompt_tokens/completion_tokens/{prompt,completion}_tokens_details) or the
+    Responses API shape (input_tokens/output_tokens/{input,output}_tokens_details).
+    """
+    if usage is None:
+        return {
+            "input_tokens": None,
+            "output_tokens": None,
+            "cache_read_tokens": None,
+            "cache_write_tokens": None,
+            "reasoning_tokens": None,
+        }
+
+    prompt_total = usage.get("prompt_tokens", usage.get("input_tokens"))
+    completion_total = usage.get("completion_tokens", usage.get("output_tokens"))
+    prompt_details = usage.get("prompt_tokens_details", usage.get("input_tokens_details"))
+    completion_details = usage.get("completion_tokens_details", usage.get("output_tokens_details"))
+
+    cached = _get(prompt_details, "cached_tokens")
+    reasoning = _get(completion_details, "reasoning_tokens")
+
+    input_tokens = None if prompt_total is None else prompt_total - (cached or 0)
+    output_tokens = None if completion_total is None else completion_total - (reasoning or 0)
+
+    return {
+        "input_tokens": input_tokens,
+        "output_tokens": output_tokens,
+        "cache_read_tokens": cached,          # subset already extracted above; report as-is
+        "cache_write_tokens": None,             # OpenAI chat/responses do not report cache writes
+        "reasoning_tokens": reasoning,
+    }
+
+
+def normalize_anthropic_usage(usage: dict) -> dict:
+    """Anthropic Messages API `usage` object. Cache fields are already disjoint
+    from `input_tokens` -- passthrough only, no subtraction.
+    """
+    if usage is None:
+        return {
+            "input_tokens": None,
+            "output_tokens": None,
+            "cache_read_tokens": None,
+            "cache_write_tokens": None,
+            "reasoning_tokens": None,
+        }
+
+    return {
+        "input_tokens": usage.get("input_tokens"),
+        "output_tokens": usage.get("output_tokens"),
+        "cache_read_tokens": usage.get("cache_read_input_tokens"),
+        "cache_write_tokens": usage.get("cache_creation_input_tokens"),
+        # ponytail: Anthropic's Messages API usage object has no distinct reasoning
+        # counter for extended-thinking today; upgrade when/if they add one.
+        "reasoning_tokens": None,
+    }
+
+
+# Azure OpenAI's `usage` shape is byte-identical to OpenAI's (doc-verified,
+# docs/spikes/provider-shapes.md §2.1). Subset semantics (cached subset of
+# prompt, reasoning subset of completion) are INFERRED from that identity,
+# NOT empirically probed the way OpenAI's were -- the M4 cache-probe replay
+# against a real Azure deployment is still outstanding (spike §7.1). Reusing
+# the OpenAI normalizer verbatim is therefore a documented inference, not a
+# second implementation to keep in sync.
+normalize_azure_openai_usage = normalize_openai_usage
+
+
+def normalize_bedrock_converse_usage(usage: Optional[dict]) -> dict:
+    """Bedrock `Converse`/`ConverseStream` `usage` (TokenUsage). Doc-verified
+    ALREADY DISJOINT: AWS's prompt-caching guide states verbatim that
+    `inputTokens` excludes cache reads/writes and
+    `total = inputTokens + cacheReadInputTokens + cacheWriteInputTokens`.
+    Passthrough only -- subtracting cache reads here would DOUBLE-DISCOUNT,
+    the inverse of OpenAI's trap on the same underlying models.
+
+    No reasoning field exists in TokenUsage: Claude thinking content comes
+    back as `reasoningContent` blocks but is counted INSIDE `outputTokens`
+    with no split, so `reasoning_tokens` is always null on Bedrock (never 0 --
+    0 would claim "we know there was no reasoning", which we don't).
+    """
+    if usage is None:
+        return dict(_NULL)
+    return {
+        "input_tokens": usage.get("inputTokens"),
+        "output_tokens": usage.get("outputTokens"),
+        "cache_read_tokens": usage.get("cacheReadInputTokens"),
+        "cache_write_tokens": usage.get("cacheWriteInputTokens"),
+        "reasoning_tokens": None,
+    }
+
+
+def normalize_bedrock_nova_usage(usage: Optional[dict]) -> dict:
+    """Amazon Nova `InvokeModel` body `usage`. Already disjoint like Converse,
+    but AWS's own docs disagree on cache-counter key casing
+    (`cacheReadInputTokenCount` vs `CacheReadInputTokens`) -- spike §1.2,
+    unresolved without a live call. Probe both spellings defensively rather
+    than pin one and silently drop cache counts the day AWS's docs turn out
+    to match the other casing.
+    """
+    if usage is None:
+        return dict(_NULL)
+
+    def first(*keys):
+        for k in keys:
+            if k in usage:
+                return usage[k]
+        return None
+
+    return {
+        "input_tokens": usage.get("inputTokens"),
+        "output_tokens": usage.get("outputTokens"),
+        "cache_read_tokens": first("cacheReadInputTokenCount", "CacheReadInputTokens", "cacheReadInputTokens"),
+        "cache_write_tokens": first("cacheWriteInputTokenCount", "CacheWriteInputTokens", "cacheWriteInputTokens"),
+        "reasoning_tokens": None,
+    }
+
+
+def normalize_bedrock_invoke_model(body: Optional[dict], headers: Optional[dict]) -> tuple[dict, bool]:
+    """`InvokeModel` usage is model-native and varies per family (spike §1.2).
+    Tries, in order: Anthropic-native body (identical shape to the Anthropic
+    Messages API -- delegates to normalize_anthropic_usage, already disjoint),
+    Amazon Nova body, Meta Llama body, then the
+    `x-amzn-bedrock-{input,output}-token-count` HTTP headers (the only source
+    for Mistral-style bodies, which return NO usage in the body at all --
+    input/output only, no cache/reasoning split). Returns
+    (norm, usage_complete); if nothing is parseable this records
+    usage_complete=False with an all-null norm rather than guessing.
+    """
+    body = body or {}
+    headers = headers or {}
+
+    anthropic_usage = body.get("usage")
+    if isinstance(anthropic_usage, dict) and "input_tokens" in anthropic_usage:
+        return normalize_anthropic_usage(anthropic_usage), True
+
+    nova_usage = anthropic_usage if isinstance(anthropic_usage, dict) else body
+    if isinstance(nova_usage, dict) and "inputTokens" in nova_usage:
+        return normalize_bedrock_nova_usage(nova_usage), True
+
+    if "prompt_token_count" in body and "generation_token_count" in body:
+        return {
+            "input_tokens": body["prompt_token_count"],
+            "output_tokens": body["generation_token_count"],
+            "cache_read_tokens": None,
+            "cache_write_tokens": None,
+            "reasoning_tokens": None,
+        }, True
+
+    in_hdr = headers.get("x-amzn-bedrock-input-token-count")
+    out_hdr = headers.get("x-amzn-bedrock-output-token-count")
+    if in_hdr is not None or out_hdr is not None:
+        return {
+            "input_tokens": int(in_hdr) if in_hdr is not None else None,
+            "output_tokens": int(out_hdr) if out_hdr is not None else None,
+            "cache_read_tokens": None,
+            "cache_write_tokens": None,
+            "reasoning_tokens": None,
+        }, True
+
+    # Mistral (and anything else unrecognized): no usage anywhere in the
+    # response. usage_complete=False, not a guessed zero.
+    return dict(_NULL), False
+
+
+def normalize_gemini_usage(usage: Optional[dict]) -> dict:
+    """google-genai `usage_metadata` (`UsageMetadata`). MIXED semantics --
+    the trap this function exists to prevent:
+
+      cached_content_token_count is a SUBSET of prompt_token_count (subtract,
+      OpenAI-style; doc-verified: "even when cachedContent is set, [prompt] is
+      still the TOTAL effective prompt size, INCLUDING cached content tokens").
+
+      thoughts_token_count is SEPARATE from candidates_token_count (do NOT
+      subtract, Anthropic-style; doc-verified: total = prompt + thoughts +
+      candidates). Subtracting it would silently UNDERCOUNT reasoning-heavy
+      traffic -- exactly the traffic that costs the most.
+
+    Accepts either snake_case (SDK dataclass `.model_dump()`) or camelCase
+    (raw REST JSON) keys.
+    """
+    if usage is None:
+        return dict(_NULL)
+
+    prompt = usage.get("prompt_token_count", usage.get("promptTokenCount"))
+    candidates = usage.get("candidates_token_count", usage.get("candidatesTokenCount"))
+    cached = usage.get("cached_content_token_count", usage.get("cachedContentTokenCount"))
+    reasoning = usage.get("thoughts_token_count", usage.get("thoughtsTokenCount"))
+
+    input_tokens = None if prompt is None else prompt - (cached or 0)
+
+    return {
+        "input_tokens": input_tokens,
+        "output_tokens": candidates,          # AS-IS -- thoughts are NOT inside this
+        "cache_read_tokens": cached,
+        "cache_write_tokens": None,            # explicit-cache creation bills as storage, not per-call
+        "reasoning_tokens": reasoning,
+    }

tokenmeter/_optimization.py

@@ -0,0 +1,97 @@
+"""Optional local measurements. No prompt text or key is emitted."""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+from typing import Optional
+
+from ._topic import topic_tag
+
+MAX_PREFIX_CHARS = 8_000
+
+
+def _text(value) -> Optional[str]:
+    if isinstance(value, str):
+        return value
+    if not isinstance(value, list) or len(value) > 100:
+        return None
+    parts = []
+    total = 0
+    for part in value:
+        if not isinstance(part, dict) or part.get("type") not in ("text", "input_text") or not isinstance(part.get("text"), str):
+            return None
+        total += len(part["text"]) + (1 if parts else 0)
+        if total > MAX_PREFIX_CHARS:
+            return None
+        parts.append(part["text"])
+    return "\n".join(parts)
+
+
+def _prefix(params: dict):
+    parts = []
+    total = 0
+
+    def add(role, value):
+        nonlocal total
+        content = _text(value)
+        if content is None or len(content) > MAX_PREFIX_CHARS:
+            return False
+        if content:
+            total += len(content) + (1 if parts else 0)
+            if total > MAX_PREFIX_CHARS:
+                return False
+            parts.append([role, content])
+        return True
+
+    if "system" in params and not add("system", params["system"]):
+        return None
+    if "instructions" in params and not add("system", params["instructions"]):
+        return None
+    messages = params.get("messages", params.get("input", params.get("prompt")))
+    if isinstance(messages, list):
+        leading = 0
+        for message in messages:
+            if not isinstance(message, dict) or message.get("role") not in ("system", "developer"):
+                break
+            leading += 1
+            if leading > 100 or not add(message["role"], message.get("content")):
+                return None
+    content = "\n".join(part[1] for part in parts)
+    if not 128 <= len(content) <= MAX_PREFIX_CHARS:
+        return None
+    return json.dumps(parts, ensure_ascii=False, separators=(",", ":")), len(content), len(content.encode("utf-8"))
+
+
+def optimization_tags(ingest_key: str, params, options=None) -> dict:
+    """Same HMAC domain and encoding as the TypeScript SDK; fail open for telemetry."""
+    try:
+        options = options if isinstance(options, dict) else {}
+        tags = {}
+        delay = options.get("max_completion_delay_ms")
+        if type(delay) is int and 1_000 <= delay <= 86_400_000:
+            tags["batch_optimization"] = {"version": 1, "source": "sdk-v1", "max_completion_delay_ms": delay}
+        if options.get("prompt_caching") is True and isinstance(ingest_key, str) and len(ingest_key) >= 16 and isinstance(params, dict):
+            value = _prefix(params)
+            if value:
+                encoded, chars, byte_count = value
+                estimate = ((byte_count + 2) // 3 + 128) // 2
+                tags["prompt_cache_telemetry"] = {
+                    "version": 1, "source": "sdk-v1",
+                    "prefix_hmac": hmac.new(ingest_key.encode("utf-8"), ("tokenmeter-sdk-prefix-v1\n" + encoded).encode("utf-8"), hashlib.sha256).hexdigest(),
+                    "prefix_length_bucket": "128-511" if chars < 512 else "512-2047" if chars < 2_048 else "2048-7999" if chars < 8_000 else "8000",
+                    "prefix_token_estimate_bucket": "128-511" if estimate < 512 else "512-2047" if estimate < 2_048 else "2048-7999" if estimate < 8_000 else "8000+",
+                }
+        # Local topic labelling (_topic.py): only a topic key leaves the process, never the text.
+        topic = topic_tag(options.get("topic_classifier"), params)
+        if topic:
+            tags["prompt_topic"] = topic
+        return tags
+    except Exception:
+        return {}
+
+
+def enrich_tags(tags: dict, optimization: dict) -> dict:
+    """Leave space for JSONB overhead and preserve existing attribution tags."""
+    combined = {**tags, **optimization}
+    return combined if len(json.dumps(combined, ensure_ascii=False).encode("utf-8")) <= 1792 else tags

tokenmeter/_preflight.py

@@ -0,0 +1,182 @@
+"""Governance preflight for direct provider calls (TS SDK: src/preflight.ts).
+
+    tokenmeter.init(ingest_key="tl_live_...", router_url="https://router.example.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)
+
+`governed()` asks the TokenMeter router's control plane whether the call is
+allowed -- the same model, provider, data-classification, token and cost policy
+a routed call gets -- before the block runs. Usage captured inside the block
+carries the decision id (tags.preflight_id), which is what lets TokenMeter report
+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
+GovernanceUnavailable when the control plane cannot be reached and
+fail_mode is "closed" (default). stdlib only, like _transport.py.
+"""
+from __future__ import annotations
+
+import contextvars
+import json
+import logging
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field
+from typing import List, Optional, Sequence, Union
+
+from ._context import current
+
+logger = logging.getLogger("tokenmeter")
+
+_preflight_id: "contextvars.ContextVar[Optional[str]]" = contextvars.ContextVar("tokenmeter_preflight_id", default=None)
+
+
+@dataclass
+class _Config:
+    ingest_key: Optional[str] = None
+    router_url: Optional[str] = None
+    mode: str = "enforce"
+    fail_mode: str = "closed"
+    timeout_s: float = 2.0
+
+
+_config = _Config()
+
+
+def configure(ingest_key: str, router_url: Optional[str], *, mode: str = "enforce", fail_mode: str = "closed", timeout_s: float = 2.0) -> None:
+    if mode not in ("enforce", "advisory"):
+        raise ValueError("governance mode must be 'enforce' or 'advisory'")
+    if fail_mode not in ("closed", "open"):
+        raise ValueError("governance fail_mode must be 'closed' or 'open'")
+    global _config
+    _config = _Config(ingest_key=ingest_key, router_url=router_url.rstrip("/") if router_url else None,
+                      mode=mode, fail_mode=fail_mode, timeout_s=timeout_s)
+
+
+def active_preflight_id() -> Optional[str]:
+    return _preflight_id.get()
+
+
+@dataclass
+class PreflightDecision:
+    allowed: bool
+    preflight_id: Optional[str] = None
+    expires_at: Optional[str] = None
+    violations: List[dict] = field(default_factory=list)
+    data_classes: List[str] = field(default_factory=list)
+    estimated_total_tokens: Optional[int] = None
+    estimated_max_cost_usd: Optional[float] = None
+    failed_open: bool = False
+
+
+class GovernanceDenied(Exception):
+    def __init__(self, decision: PreflightDecision) -> None:
+        reasons = "; ".join(str(v.get("reason", "")) for v in decision.violations) or "policy violation"
+        super().__init__(f"TokenMeter governance denied this call: {reasons}")
+        self.decision = decision
+
+
+class GovernanceUnavailable(Exception):
+    pass
+
+
+def _unavailable(detail: str) -> PreflightDecision:
+    if _config.fail_mode == "closed":
+        raise GovernanceUnavailable(f"TokenMeter governance preflight unavailable ({detail}); failing closed")
+    logger.warning("tokenmeter: governance preflight unavailable (%s); proceeding unprotected (fail_mode=open)", detail)
+    return PreflightDecision(allowed=True, failed_open=True)
+
+
+def preflight(
+    provider: str,
+    model: str,
+    *,
+    team: Optional[str] = None,
+    environment: Optional[str] = None,
+    data_classification: Union[str, Sequence[str], None] = None,
+    content: Optional[str] = None,
+    estimated_input_tokens: Optional[int] = None,
+    max_output_tokens: Optional[int] = None,
+) -> PreflightDecision:
+    """Ask for a decision. Raises only GovernanceUnavailable (fail_mode='closed')."""
+    if not _config.router_url or not _config.ingest_key:
+        return _unavailable("router_url not configured -- pass router_url to tokenmeter.init()")
+    ctx = current()
+    body = {
+        "provider": provider,
+        "model": model,
+        "team": team if team is not None else (ctx.team if ctx else None),
+        "environment": environment if environment is not None else (ctx.environment if ctx else None),
+        "data_classification": list(data_classification) if isinstance(data_classification, (list, tuple)) else data_classification,
+        "content": content,
+        "estimated_input_tokens": estimated_input_tokens,
+        "max_output_tokens": max_output_tokens,
+    }
+    req = urllib.request.Request(
+        _config.router_url + "/v1/governance/preflight",
+        data=json.dumps({k: v for k, v in body.items() if v is not None}).encode("utf-8"),
+        method="POST",
+        headers={"Authorization": f"Bearer {_config.ingest_key}", "Content-Type": "application/json"},
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=_config.timeout_s) as resp:
+            if resp.status != 200:
+                return _unavailable(f"HTTP {resp.status}")
+            data = json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        return _unavailable(f"HTTP {e.code}")
+    except Exception as e:  # network, timeout, bad JSON
+        return _unavailable(type(e).__name__)
+    if not isinstance(data, dict) or not isinstance(data.get("allowed"), bool):
+        return _unavailable("malformed response")
+    return PreflightDecision(
+        allowed=data["allowed"],
+        preflight_id=data.get("preflight_id") if isinstance(data.get("preflight_id"), str) else None,
+        expires_at=data.get("expires_at") if isinstance(data.get("expires_at"), str) else None,
+        violations=[v for v in data.get("violations") or [] if isinstance(v, dict)],
+        data_classes=[str(c) for c in data.get("data_classes") or []],
+        estimated_total_tokens=data.get("estimated_total_tokens"),
+        estimated_max_cost_usd=data.get("estimated_max_cost_usd"),
+    )
+
+
+class governed:
+    """Context manager: preflight on enter, preflight id attached to usage captured inside.
+
+    Works with `with` and `async with`. The preflight request itself is a
+    blocking HTTP call (stdlib), bounded by timeout_s.
+    """
+
+    def __init__(self, provider: str, model: str, **kwargs) -> None:
+        self.provider = provider
+        self.model = model
+        self.kwargs = kwargs
+        self.decision: Optional[PreflightDecision] = None
+        self._token: Optional[contextvars.Token] = None
+
+    def __enter__(self) -> PreflightDecision:
+        decision = preflight(self.provider, self.model, **self.kwargs)
+        self.decision = decision
+        if not decision.allowed and not decision.failed_open and _config.mode == "enforce":
+            raise GovernanceDenied(decision)
+        if decision.preflight_id:
+            self._token = _preflight_id.set(decision.preflight_id)
+        return decision
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        if self._token is not None:
+            _preflight_id.reset(self._token)
+            self._token = None
+        return None
+
+    async def __aenter__(self) -> PreflightDecision:
+        return self.__enter__()
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        self.__exit__(exc_type, exc, tb)
+
+
+def _reset_for_tests() -> None:
+    global _config
+    _config = _Config()

tokenmeter/_read_api.py

@@ -0,0 +1,50 @@
+"""Read-only Token Meter warehouse API client (standard library only)."""
+from __future__ import annotations
+
+import json
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+from typing import Any, Optional
+
+
+class ReadApiError(RuntimeError):
+    def __init__(self, message: str, status: int, code: Optional[str] = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+
+
+class TokenMeterReadClient:
+    """Read daily organization usage using a dedicated ``tl_admin_`` read key."""
+
+    def __init__(self, api_key: str, base_url: str, timeout: float = 20.0) -> None:
+        if not api_key.startswith("tl_admin_"):
+            raise ValueError("ReadApiClient requires a read API key (tl_admin_…).")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def list_daily_usage(self, start: str, end: str, *, limit: int = 100, cursor: Optional[str] = None) -> dict[str, Any]:
+        query = {"start": start, "end": end, "limit": str(limit)}
+        if cursor is not None:
+            query["cursor"] = cursor
+        request = Request(
+            f"{self.base_url}/api/v1/usage/daily?{urlencode(query)}",
+            headers={"Authorization": f"Bearer {self.api_key}", "Accept": "application/json"},
+        )
+        try:
+            with urlopen(request, timeout=self.timeout) as response:
+                return json.loads(response.read().decode("utf-8"))
+        except HTTPError as exc:
+            try:
+                body = json.loads(exc.read().decode("utf-8"))
+                error = body.get("error", {})
+            except (ValueError, AttributeError):
+                error = {}
+            raise ReadApiError(error.get("message", f"Token Meter read API returned HTTP {exc.code}."), exc.code, error.get("code")) from exc
+        except URLError as exc:
+            raise ReadApiError(f"Could not reach Token Meter read API: {exc.reason}", 0) from exc
+
+
+ReadApiClient = TokenMeterReadClient

tokenmeter/_topic.py

@@ -0,0 +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"