revenium-python-sdk 0.5.0__tar.gz → 0.6.0__tar.gz

{revenium_python_sdk-0.5.0 → revenium_python_sdk-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: revenium-python-sdk
-Version: 0.5.0
+Version: 0.6.0
 Summary: The official Revenium Python SDK — unified AI metering middleware for OpenAI, Anthropic, Google, Ollama, LiteLLM, Perplexity, and fal.ai.
 Author-email: Revenium <support@revenium.io>
 License: MIT
@@ -214,6 +214,52 @@ print(response.choices[0].message.content)
 
 ---
 
+## Metering Error Visibility
+
+Metering runs in background threads and never raises into your code path — a
+metering failure will never break your AI calls. To make failures observable
+anyway, the SDK provides two mechanisms:
+
+**Subscribe to failures** with a callback:
+
+```python
+import revenium_middleware
+
+@revenium_middleware.on_metering_error
+def alert_on_metering_failure(event):
+    # event.error      -- the exception (e.g. an HTTP 401/500 from Revenium)
+    # event.operation  -- "completion", "image", "tool", ... (may be None)
+    # event.timestamp  -- UTC datetime of the failure
+    my_monitoring.notify(f"Revenium metering failed: {event.error}")
+```
+
+Callbacks run on the background metering thread; exceptions they raise are
+suppressed and logged, so they can never disrupt your application.
+
+Authentication headers (`x-api-key`, `authorization`) on any HTTP
+request/response attached to the exception are redacted before the error is
+exposed to callbacks or `last_error`.
+
+**Poll the status counters:**
+
+```python
+status = revenium_middleware.get_metering_status()
+print(status.success_count)   # events delivered successfully
+print(status.error_count)     # delivery failures
+print(status.last_error)      # most recent exception, or None
+print(status.last_error_at)   # UTC datetime of the most recent failure
+```
+
+`reset_metering_status()` zeroes the counters and clears registered
+callbacks; `remove_metering_error_callback(cb)` unsubscribes a single one.
+
+Failures are also logged at **ERROR** level on the `revenium_middleware`
+logger, including HTTP 4xx/5xx responses, a missing
+`REVENIUM_METERING_API_KEY`, and a provider middleware that fails to import
+when the provider's SDK is installed.
+
+---
+
 ## Agentic Outcomes (Outcome-Based Metering)
 
 Emit per-agent terminal outcomes (`CONVERTED`, `DEFLECTED`, `ESCALATED`) alongside completion and tool-event records, so dashboards show business value next to AI cost.
@@ -1075,6 +1121,12 @@ Enhanced observability fields for tracking AI operations across environments, re
 | `transaction_name` | `REVENIUM_TRANSACTION_NAME` | Human-friendly operation name | Label operations (e.g., `"Generate Response"`, `"Analyze Sentiment"`) |
 | `retry_number` | `REVENIUM_RETRY_NUMBER` | Retry attempt number (0 = first attempt) | Track retry attempts for failed operations |
 | `ticket_id` | `REVENIUM_TICKET_ID` | External ticket or issue ID (e.g., Jira, Linear) (max 256 chars) | Attribute AI costs to individual tickets or issues |
+| `skill_name` | `REVENIUM_SKILL_NAME` | Name of the agent skill that produced the call (max 256 chars) | Attribute AI costs to the skill that generated them |
+| `skill_source` | `REVENIUM_SKILL_SOURCE` | Where the skill was loaded from — accepted values: `bundled`, `projectSettings`, `userSettings`, `plugin` (case-sensitive) | Classify skill origin in the shared skill catalog |
+| `skill_kind` | `REVENIUM_SKILL_KIND` | Kind of skill invoked — accepted value: `workflow` (omit otherwise) | Distinguish workflow skills in reporting |
+| `skill_plugin_name` | `REVENIUM_SKILL_PLUGIN_NAME` | Plugin providing the skill, when `skill_source` is `plugin` (max 256 chars) | Attribute costs to a specific plugin |
+| `skill_marketplace_name` | `REVENIUM_SKILL_MARKETPLACE_NAME` | Marketplace the skill or plugin was installed from (max 256 chars) | Track marketplace-sourced skill usage |
+| `skill_invocation_trigger` | `REVENIUM_SKILL_INVOCATION_TRIGGER` | What triggered the skill (max 32 chars; common values: `user-slash`, `claude-proactive`, `nested-skill`) | Separate user-invoked from proactive skill usage |
 
 **Note:** `operation_type` (e.g., `CHAT`, `EMBED`, `TOOL_CALL`) and `operation_subtype` (e.g., `function_call`, `streaming`) are automatically detected by the middleware and cannot be overridden.
 

{revenium_python_sdk-0.5.0 → revenium_python_sdk-0.6.0}/README.md

@@ -117,6 +117,52 @@ print(response.choices[0].message.content)
 
 ---
 
+## Metering Error Visibility
+
+Metering runs in background threads and never raises into your code path — a
+metering failure will never break your AI calls. To make failures observable
+anyway, the SDK provides two mechanisms:
+
+**Subscribe to failures** with a callback:
+
+```python
+import revenium_middleware
+
+@revenium_middleware.on_metering_error
+def alert_on_metering_failure(event):
+    # event.error      -- the exception (e.g. an HTTP 401/500 from Revenium)
+    # event.operation  -- "completion", "image", "tool", ... (may be None)
+    # event.timestamp  -- UTC datetime of the failure
+    my_monitoring.notify(f"Revenium metering failed: {event.error}")
+```
+
+Callbacks run on the background metering thread; exceptions they raise are
+suppressed and logged, so they can never disrupt your application.
+
+Authentication headers (`x-api-key`, `authorization`) on any HTTP
+request/response attached to the exception are redacted before the error is
+exposed to callbacks or `last_error`.
+
+**Poll the status counters:**
+
+```python
+status = revenium_middleware.get_metering_status()
+print(status.success_count)   # events delivered successfully
+print(status.error_count)     # delivery failures
+print(status.last_error)      # most recent exception, or None
+print(status.last_error_at)   # UTC datetime of the most recent failure
+```
+
+`reset_metering_status()` zeroes the counters and clears registered
+callbacks; `remove_metering_error_callback(cb)` unsubscribes a single one.
+
+Failures are also logged at **ERROR** level on the `revenium_middleware`
+logger, including HTTP 4xx/5xx responses, a missing
+`REVENIUM_METERING_API_KEY`, and a provider middleware that fails to import
+when the provider's SDK is installed.
+
+---
+
 ## Agentic Outcomes (Outcome-Based Metering)
 
 Emit per-agent terminal outcomes (`CONVERTED`, `DEFLECTED`, `ESCALATED`) alongside completion and tool-event records, so dashboards show business value next to AI cost.
@@ -978,6 +1024,12 @@ Enhanced observability fields for tracking AI operations across environments, re
 | `transaction_name` | `REVENIUM_TRANSACTION_NAME` | Human-friendly operation name | Label operations (e.g., `"Generate Response"`, `"Analyze Sentiment"`) |
 | `retry_number` | `REVENIUM_RETRY_NUMBER` | Retry attempt number (0 = first attempt) | Track retry attempts for failed operations |
 | `ticket_id` | `REVENIUM_TICKET_ID` | External ticket or issue ID (e.g., Jira, Linear) (max 256 chars) | Attribute AI costs to individual tickets or issues |
+| `skill_name` | `REVENIUM_SKILL_NAME` | Name of the agent skill that produced the call (max 256 chars) | Attribute AI costs to the skill that generated them |
+| `skill_source` | `REVENIUM_SKILL_SOURCE` | Where the skill was loaded from — accepted values: `bundled`, `projectSettings`, `userSettings`, `plugin` (case-sensitive) | Classify skill origin in the shared skill catalog |
+| `skill_kind` | `REVENIUM_SKILL_KIND` | Kind of skill invoked — accepted value: `workflow` (omit otherwise) | Distinguish workflow skills in reporting |
+| `skill_plugin_name` | `REVENIUM_SKILL_PLUGIN_NAME` | Plugin providing the skill, when `skill_source` is `plugin` (max 256 chars) | Attribute costs to a specific plugin |
+| `skill_marketplace_name` | `REVENIUM_SKILL_MARKETPLACE_NAME` | Marketplace the skill or plugin was installed from (max 256 chars) | Track marketplace-sourced skill usage |
+| `skill_invocation_trigger` | `REVENIUM_SKILL_INVOCATION_TRIGGER` | What triggered the skill (max 32 chars; common values: `user-slash`, `claude-proactive`, `nested-skill`) | Separate user-invoked from proactive skill usage |
 
 **Note:** `operation_type` (e.g., `CHAT`, `EMBED`, `TOOL_CALL`) and `operation_subtype` (e.g., `function_call`, `streaming`) are automatically detected by the middleware and cannot be overridden.
 

{revenium_python_sdk-0.5.0 → revenium_python_sdk-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "revenium-python-sdk"
-version = "0.5.0"
+version = "0.6.0"
 description = "The official Revenium Python SDK — unified AI metering middleware for OpenAI, Anthropic, Google, Ollama, LiteLLM, Perplexity, and fal.ai."
 readme = "README.md"
 requires-python = ">=3.8"
@@ -124,6 +124,7 @@ dev = [
 ]
 
 [tool.pytest.ini_options]
+testpaths = ["tests"]
 markers = [
     "unit: Unit tests (fast, no external dependencies)",
     "e2e: end-to-end tests requiring live services",

{revenium_python_sdk-0.5.0 → revenium_python_sdk-0.6.0}/revenium_middleware/__init__.py

@@ -160,6 +160,16 @@ from ._core import (  # noqa: E402
     is_selective_metering_enabled,
 )
 
+# Metering error visibility (BACK-778): status counters + failure callbacks
+from ._core.metering_status import (  # noqa: E402
+    MeteringErrorEvent,
+    MeteringStatus,
+    get_metering_status,
+    on_metering_error,
+    remove_metering_error_callback,
+    reset_metering_status,
+)
+
 # Re-export tool metering utilities from the in-package metering module (BACK-2151)
 from ._metering import meter_tool, report_tool_call, configure  # noqa: E402
 
@@ -202,6 +212,13 @@ __all__ = [
     "set_idempotency_key",
     # Config exports
     "is_selective_metering_enabled",
+    # Metering error visibility exports (BACK-778)
+    "MeteringErrorEvent",
+    "MeteringStatus",
+    "get_metering_status",
+    "on_metering_error",
+    "remove_metering_error_callback",
+    "reset_metering_status",
     # Tool metering exports
     "meter_tool",
     "report_tool_call",

{revenium_python_sdk-0.5.0 → revenium_python_sdk-0.6.0}/revenium_middleware/_core/config.py

@@ -63,6 +63,13 @@ class Config:
     ENV_REVENIUM_AGENTIC_JOB_NAME: str = "REVENIUM_AGENTIC_JOB_NAME"
     ENV_REVENIUM_AGENTIC_JOB_TYPE: str = "REVENIUM_AGENTIC_JOB_TYPE"
     ENV_REVENIUM_AGENTIC_JOB_VERSION: str = "REVENIUM_AGENTIC_JOB_VERSION"
+    # Skill attribution environment variables
+    ENV_REVENIUM_SKILL_INVOCATION_TRIGGER: str = "REVENIUM_SKILL_INVOCATION_TRIGGER"
+    ENV_REVENIUM_SKILL_KIND: str = "REVENIUM_SKILL_KIND"
+    ENV_REVENIUM_SKILL_MARKETPLACE_NAME: str = "REVENIUM_SKILL_MARKETPLACE_NAME"
+    ENV_REVENIUM_SKILL_NAME: str = "REVENIUM_SKILL_NAME"
+    ENV_REVENIUM_SKILL_PLUGIN_NAME: str = "REVENIUM_SKILL_PLUGIN_NAME"
+    ENV_REVENIUM_SKILL_SOURCE: str = "REVENIUM_SKILL_SOURCE"
     ENV_REVENIUM_OUTCOME_API_KEY: str = "REVENIUM_OUTCOME_API_KEY"
     ENV_REVENIUM_PROFITSTREAM_BASE_URL: str = "REVENIUM_PROFITSTREAM_BASE_URL"
 

{revenium_python_sdk-0.5.0 → revenium_python_sdk-0.6.0}/revenium_middleware/_core/fields.py

@@ -30,6 +30,26 @@ _AGENTIC_JOB_ENV_MAP = {
     "agenticJobVersion": Config.ENV_REVENIUM_AGENTIC_JOB_VERSION,
 }
 
+# Keys are the typed snake_case params on create_completion; values are the
+# accepted usage_metadata aliases in precedence order.
+SKILL_FIELD_MAP = {
+    "skill_invocation_trigger": ("skill_invocation_trigger", "skillInvocationTrigger"),
+    "skill_kind": ("skill_kind", "skillKind"),
+    "skill_marketplace_name": ("skill_marketplace_name", "skillMarketplaceName"),
+    "skill_name": ("skill_name", "skillName"),
+    "skill_plugin_name": ("skill_plugin_name", "skillPluginName"),
+    "skill_source": ("skill_source", "skillSource"),
+}
+
+_SKILL_ENV_MAP = {
+    "skill_invocation_trigger": Config.ENV_REVENIUM_SKILL_INVOCATION_TRIGGER,
+    "skill_kind": Config.ENV_REVENIUM_SKILL_KIND,
+    "skill_marketplace_name": Config.ENV_REVENIUM_SKILL_MARKETPLACE_NAME,
+    "skill_name": Config.ENV_REVENIUM_SKILL_NAME,
+    "skill_plugin_name": Config.ENV_REVENIUM_SKILL_PLUGIN_NAME,
+    "skill_source": Config.ENV_REVENIUM_SKILL_SOURCE,
+}
+
 
 def extract_field_with_fallback(
     source: Mapping[str, Any],
@@ -129,6 +149,28 @@ def extract_agentic_job_fields(source: Mapping[str, Any]) -> Dict[str, Any]:
     return result
 
 
+def extract_skill_fields(source: Mapping[str, Any]) -> Dict[str, Any]:
+    """Resolve skill attribution fields with per-field precedence:
+
+    explicit source metadata (snake then camel alias) >
+    ``REVENIUM_SKILL_*`` env var. Each field resolves independently and
+    absent fields are omitted entirely (never emitted as None). Returns
+    snake_case keys matching the typed create_completion parameters.
+    """
+    result = {}
+    for param_name, aliases in SKILL_FIELD_MAP.items():
+        value = None
+        for alias in aliases:
+            value = source.get(alias)
+            if value is not None:
+                break
+        if value is None:
+            value = os.getenv(_SKILL_ENV_MAP[param_name]) or None
+        if value is not None:
+            result[param_name] = value
+    return result
+
+
 def merge_extra_body(existing: Optional[Dict[str, Any]], agentic_fields: Dict[str, Any]) -> Optional[Dict[str, Any]]:
     if not agentic_fields:
         return existing if existing else None

revenium_python_sdk-0.6.0/revenium_middleware/_core/load_diagnostics.py

@@ -0,0 +1,68 @@
+"""Log-level policy for provider middleware load failures.
+
+Every provider package guards its middleware import with ``except
+ImportError`` so that optional providers can be absent. That guard used to
+log at DEBUG unconditionally, which hid real breakage: a customer with the
+provider SDK installed whose middleware failed to import (missing ``wrapt``,
+a broken internal import, a version conflict) got zero metering with no
+visible signal.
+
+The policy here distinguishes the two cases:
+
+- Provider SDK **installed** but middleware import failed → ERROR, including
+  the underlying exception. Metering was expected to work and silently won't.
+- Provider SDK **absent** → DEBUG. The provider simply isn't in use (e.g.
+  ``revenium_middleware.griptape`` imports several provider middlewares
+  eagerly and most installs only have one provider SDK).
+"""
+from __future__ import annotations
+
+import importlib.util
+import logging
+from typing import Tuple
+
+logger = logging.getLogger("revenium_middleware")
+
+
+def _package_installed(package: str) -> bool:
+    try:
+        return importlib.util.find_spec(package) is not None
+    except ModuleNotFoundError:
+        # find_spec("google.genai") raises when the parent package is absent.
+        return False
+    except Exception:
+        # Any other spec-lookup failure means the package exists but is
+        # broken — fail toward visibility.
+        return True
+
+
+def log_middleware_load_failure(
+    provider_label: str,
+    exc: BaseException,
+    required_packages: Tuple[str, ...],
+) -> None:
+    """Log a provider middleware import failure at the appropriate level.
+
+    Args:
+        provider_label: Human-readable provider name for the log message.
+        exc: The ImportError (or subclass) that aborted the middleware load.
+        required_packages: Import names of the provider's own SDK package(s).
+            If any of them is installed, the failure is unexpected and logged
+            at ERROR; if none are, the provider is not in use and the failure
+            is logged at DEBUG.
+    """
+    if any(_package_installed(pkg) for pkg in required_packages):
+        logger.error(
+            "Revenium %s middleware could not load: %s. "
+            "Metering will NOT be active for %s calls.",
+            provider_label,
+            exc,
+            provider_label,
+        )
+    else:
+        logger.debug(
+            "%s SDK not installed (%s); Revenium %s middleware not loaded",
+            provider_label,
+            exc,
+            provider_label,
+        )

{revenium_python_sdk-0.5.0 → revenium_python_sdk-0.6.0}/revenium_middleware/_core/metering.py

@@ -22,7 +22,8 @@ def _build_metering_client(
 ) -> Optional[ReveniumMetering]:
     """Construct a ReveniumMetering client from raw env-var inputs.
 
-    Returns ``None`` when the API key is missing/empty (logs a warning).
+    Returns ``None`` when the API key is missing/empty (logs an error --
+    metering silently disabled is the failure mode this SDK must surface).
     Raises ``ValueError`` when the API key is present but malformed.
     Falls back to the library default when ``base_url_raw`` is set but not
     a valid http(s) URL.
@@ -40,7 +41,10 @@ def _build_metering_client(
             )
 
     if not api_key:
-        logger.warning("Metering API key not set -- metering is disabled")
+        logger.error(
+            "REVENIUM_METERING_API_KEY environment variable is not set. "
+            "Metering is disabled and no usage data will be sent to Revenium."
+        )
         return None
 
     validate_api_key(api_key)
@@ -86,10 +90,11 @@ def initialize_metering(api_key: Optional[str] = None, base_url: Optional[str] =
     settings hooks) or to reconfigure at runtime. Explicit arguments take
     precedence over ``REVENIUM_METERING_API_KEY`` / ``REVENIUM_METERING_BASE_URL``.
 
-    Returns True when metering is enabled after the call. Raises ``ValueError``
-    for a malformed API key -- explicit configuration fails loudly, unlike the
-    lazy ``get_client()`` path, which logs a warning and leaves metering
-    disabled (best-effort by design).
+    Returns True when metering is enabled after the call; a missing/empty key
+    logs an ERROR and leaves metering disabled. Raises ``ValueError`` for a
+    malformed API key -- explicit configuration fails loudly, unlike the lazy
+    ``get_client()`` path, which logs a warning once for a malformed env key
+    and leaves metering disabled.
     """
     global client
     key = api_key if api_key is not None else os.environ.get("REVENIUM_METERING_API_KEY")
@@ -107,8 +112,9 @@ def get_client() -> Optional[ReveniumMetering]:
     ``REVENIUM_METERING_API_KEY`` appears, the next metering event builds the
     client instead of silently no-opping forever.
 
-    Best-effort by design: a malformed env key is logged once and metering
-    stays disabled, whereas the explicit ``initialize_metering()`` raises
+    A missing/unset key is logged at ERROR level by the build path; a
+    malformed env key is logged once as a warning and metering stays
+    disabled, whereas the explicit ``initialize_metering()`` raises
     ``ValueError`` so programmatic misconfiguration fails loudly.
     """
     global _last_failed_key
@@ -240,8 +246,10 @@ class MeteringThread(threading.Thread):
             # Log errors unless it's during shutdown
             if not shutdown_event.is_set():
                 self.error = e
+                from revenium_middleware._core.metering_status import record_metering_error
+                record_metering_error(e)
                 # Use exc_info=True to include traceback in the log
-                logger.warning(f"Error in metering thread {self.name}: {str(e)}", exc_info=True)
+                logger.error(f"Error in metering thread {self.name}: {str(e)}", exc_info=True)
             else:
                 logger.debug(f"Exception ignored in metering thread {self.name} during shutdown: {str(e)}")
         finally:

{revenium_python_sdk-0.5.0 → revenium_python_sdk-0.6.0}/revenium_middleware/_core/metering_buffer.py

@@ -13,10 +13,15 @@ import os
 import threading
 import time
 from collections import deque
-from typing import Any, Callable, Deque, Dict, Optional
+from typing import Any, Callable, Deque, Dict, List, Optional, Tuple
 
 import httpx
 
+from revenium_middleware._core.metering_status import (
+    record_metering_error,
+    record_metering_success,
+)
+
 logger = logging.getLogger("revenium_middleware")
 
 DEFAULT_MAX_SIZE = 1000
@@ -196,12 +201,18 @@ class MeteringBuffer:
         """
         sent = expired = discarded = 0
         started = time.monotonic()
+        # Status recording is deferred until _flush_lock is released:
+        # record_metering_error() runs subscriber callbacks synchronously, and
+        # a callback that calls back into this buffer would self-deadlock on
+        # the non-reentrant lock.
+        deferred_outcomes: List[Optional[Tuple[BaseException, str]]] = []
 
         with self._flush_lock:
             while True:
                 if deadline_seconds is not None and time.monotonic() - started >= deadline_seconds:
                     break
 
+                expired_kind: Optional[str] = None
                 with self._lock:
                     if not self._events:
                         break
@@ -210,7 +221,19 @@ class MeteringBuffer:
                         self._events.popleft()
                         self._total_expired += 1
                         expired += 1
-                        continue
+                        expired_kind = event.kind
+                if expired_kind is not None:
+                    # Expiry is a terminal failure with no delivery exception
+                    # in hand; synthesize one so status counters and
+                    # on_metering_error subscribers still get the signal.
+                    deferred_outcomes.append((
+                        TimeoutError(
+                            f"buffered {expired_kind} metering event expired after "
+                            f"{self._max_age_seconds:.0f}s without successful replay"
+                        ),
+                        expired_kind,
+                    ))
+                    continue
 
                 # Cap each replay call so a single slow network call cannot
                 # blow through the flush deadline (e.g. the shutdown budget).
@@ -232,16 +255,23 @@ class MeteringBuffer:
                     # Only count the discard if the event is still at the
                     # front; a concurrent push at capacity may have evicted
                     # (and counted) it already.
+                    discarded_here = False
                     with self._lock:
                         if self._events and self._events[0] is event:
                             self._events.popleft()
                             self._total_discarded += 1
                             discarded += 1
+                            discarded_here = True
+                    if discarded_here:
+                        # Terminal failure: the event is gone for good, so
+                        # surface it to status counters and subscribers.
+                        deferred_outcomes.append((exc, event.kind))
                     logger.debug("Discarded buffered event after permanent failure: %s", exc)
                     continue
 
                 # Same identity guard: only count the replay if we actually
                 # popped this event (not concurrently evicted-and-counted).
+                replayed_here = False
                 with self._lock:
                     if self._events and self._events[0] is event:
                         self._events.popleft()
@@ -249,6 +279,16 @@ class MeteringBuffer:
                         if len(self._events) < self._max_size:
                             self._was_full = False
                         sent += 1
+                        replayed_here = True
+                if replayed_here:
+                    deferred_outcomes.append(None)
+
+        for outcome in deferred_outcomes:
+            if outcome is None:
+                record_metering_success()
+            else:
+                error, kind = outcome
+                record_metering_error(error, operation=kind)
 
         remaining = self.stats()["size"]
         if sent or expired or discarded:

revenium_python_sdk-0.6.0/revenium_middleware/_core/metering_status.py

@@ -0,0 +1,172 @@
+"""Metering error visibility: status counters and subscriber callbacks.
+
+Metering runs in background threads and must never raise into the customer's
+code path, so failures were historically visible only as log lines. This
+module gives customers two ways to learn about metering failures
+programmatically:
+
+- ``on_metering_error(callback)`` — subscribe to failures as they happen.
+- ``get_metering_status()`` — poll a snapshot of success/error counters and
+  the most recent error.
+
+Both are re-exported from the top-level ``revenium_middleware`` package.
+"""
+from __future__ import annotations
+
+import logging
+import threading
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Callable, List, Optional
+
+logger = logging.getLogger("revenium_middleware")
+
+
+@dataclass(frozen=True)
+class MeteringErrorEvent:
+    """A single metering delivery failure, passed to error callbacks."""
+
+    error: BaseException
+    operation: Optional[str]
+    timestamp: datetime
+
+
+@dataclass(frozen=True)
+class MeteringStatus:
+    """Point-in-time snapshot of metering delivery health."""
+
+    error_count: int
+    success_count: int
+    last_error: Optional[BaseException]
+    last_error_at: Optional[datetime]
+
+
+_lock = threading.Lock()
+_error_count = 0
+_success_count = 0
+_last_error: Optional[BaseException] = None
+_last_error_at: Optional[datetime] = None
+_error_callbacks: List[Callable[[MeteringErrorEvent], None]] = []
+
+
+def get_metering_status() -> MeteringStatus:
+    """Return a snapshot of metering success/error counters."""
+    with _lock:
+        return MeteringStatus(
+            error_count=_error_count,
+            success_count=_success_count,
+            last_error=_last_error,
+            last_error_at=_last_error_at,
+        )
+
+
+def on_metering_error(
+    callback: Callable[[MeteringErrorEvent], None],
+) -> Callable[[MeteringErrorEvent], None]:
+    """Subscribe to metering failures.
+
+    The callback receives a :class:`MeteringErrorEvent` for every recorded
+    failure. Callbacks run on the (background) thread that detected the
+    failure; exceptions they raise are logged and suppressed so they can
+    never disrupt the customer's AI calls. Returns the callback, so it can
+    be used as a decorator.
+    """
+    with _lock:
+        _error_callbacks.append(callback)
+    return callback
+
+
+def remove_metering_error_callback(
+    callback: Callable[[MeteringErrorEvent], None],
+) -> None:
+    """Unsubscribe a callback previously registered via ``on_metering_error``."""
+    with _lock:
+        try:
+            _error_callbacks.remove(callback)
+        except ValueError:
+            pass
+
+
+def reset_metering_status() -> None:
+    """Reset counters, last error, and registered callbacks."""
+    global _error_count, _success_count, _last_error, _last_error_at
+    with _lock:
+        _error_count = 0
+        _success_count = 0
+        _last_error = None
+        _last_error_at = None
+        _error_callbacks.clear()
+
+
+def record_metering_success() -> None:
+    """Record one successfully delivered metering event."""
+    global _success_count
+    with _lock:
+        _success_count += 1
+
+
+_SENSITIVE_HEADERS = ("x-api-key", "authorization")
+
+
+def _redact_sensitive_headers(error: BaseException) -> None:
+    """Redact auth headers on any HTTP request/response attached to ``error``.
+
+    HTTP client exceptions (e.g. ``APIStatusError``) expose the live
+    ``httpx.Request``/``httpx.Response`` as public attributes, and httpx does
+    not redact the ``x-api-key`` header the SDK authenticates with. Overwrite
+    ``x-api-key`` and ``authorization`` (case-insensitive, only if already
+    present) in place before the error reaches callbacks or ``last_error``.
+    Never raises, and each target is attempted independently: httpx's
+    ``Response.request`` property raises ``RuntimeError`` (not
+    ``AttributeError``) when no request was attached, and a failure on one
+    lookup must not defeat redaction of the objects that are reachable.
+    """
+    targets = []
+    for owner, attr in ((error, "request"), (error, "response")):
+        try:
+            targets.append(getattr(owner, attr, None))
+        except Exception:
+            targets.append(None)
+    try:
+        targets.append(getattr(targets[1], "request", None))
+    except Exception:
+        pass
+    for obj in targets:
+        try:
+            headers = getattr(obj, "headers", None)
+            if headers is None:
+                continue
+            for name in _SENSITIVE_HEADERS:
+                if name in headers:
+                    headers[name] = "[REDACTED]"
+        except Exception:
+            continue
+
+
+def record_metering_error(
+    error: BaseException, operation: Optional[str] = None
+) -> None:
+    """Record a metering delivery failure and notify subscribers.
+
+    Auth headers on any HTTP request/response carried by ``error`` are
+    redacted in place before the error is stored or fanned out. Never
+    raises: subscriber exceptions are logged and suppressed so error
+    reporting cannot disrupt the customer's code path.
+    """
+    global _error_count, _last_error, _last_error_at
+    _redact_sensitive_headers(error)
+    event = MeteringErrorEvent(
+        error=error, operation=operation, timestamp=datetime.now(timezone.utc)
+    )
+    with _lock:
+        _error_count += 1
+        _last_error = error
+        _last_error_at = event.timestamp
+        callbacks = list(_error_callbacks)
+    for callback in callbacks:
+        try:
+            callback(event)
+        except Exception:
+            logger.warning(
+                "Metering error callback %r raised; ignoring", callback, exc_info=True
+            )