revenium-python-sdk 0.1.10__tar.gz → 0.2.0__tar.gz

{revenium_python_sdk-0.1.10/revenium_python_sdk.egg-info → revenium_python_sdk-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: revenium-python-sdk
-Version: 0.1.10
+Version: 0.2.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
@@ -1316,6 +1316,44 @@ See [`examples/openai/openai_blocking_demo.py`](examples/openai/openai_blocking_
 |----------|-------------|
 | `REVENIUM_METERING_API_KEY` | Your Revenium API key (starts with `hak_` or `rev_`) |
 
+### Configuring After Import
+
+The metering client is normally built from the environment when
+`revenium_middleware` is first imported. If your credentials only become
+available later (a secrets-vault bootstrap, framework settings hooks, import
+ordering), you don't need to restart: as soon as `REVENIUM_METERING_API_KEY`
+appears in the environment, the next metered call picks it up automatically.
+You can also configure programmatically at any time:
+
+```python
+import revenium_middleware
+
+revenium_middleware.initialize_metering(
+    api_key="hak_your_key",                    # defaults to REVENIUM_METERING_API_KEY
+    base_url="https://api.revenium.ai",        # defaults to REVENIUM_METERING_BASE_URL
+)
+```
+
+`initialize_metering()` returns `True` when metering is enabled after the
+call; invoke it with no arguments to re-read the environment.
+
+### Delivery Resilience (Store-and-Forward)
+
+Metering events that still fail after the client's own retries (network
+outages, 5xx, rate limiting) are not lost: they are held in a bounded
+in-memory buffer and replayed automatically in the background every 30
+seconds, reusing each event's original `Idempotency-Key` so replays can
+never double-bill. Permanent failures (401/403/404/422) are never buffered.
+The buffer holds up to 1000 events (oldest evicted first) for at most 24
+hours, and is drained on graceful shutdown. Inspect it programmatically:
+
+```python
+from revenium_middleware import get_buffer_stats
+
+print(get_buffer_stats())
+# {'size': 0, 'max_size': 1000, 'total_buffered': 3, 'total_replayed': 3, ...}
+```
+
 ### Optional Environment Variables
 
 | Variable | Default | Description |
@@ -1334,6 +1372,8 @@ See [`examples/openai/openai_blocking_demo.py`](examples/openai/openai_blocking_
 | `REVENIUM_TRANSACTION_NAME` | - | Human-friendly operation name |
 | `REVENIUM_RETRY_NUMBER` | - | Retry attempt number |
 | `REVENIUM_BEDROCK_DISABLE` | - | Set to `1` to disable Bedrock auto-detection |
+| `REVENIUM_BUFFER_MAX_SIZE` | `1000` | Store-and-forward buffer capacity (oldest events evicted when full) |
+| `REVENIUM_BUFFER_FLUSH_INTERVAL` | `30` | Seconds between automatic replay attempts for buffered events |
 
 ### Provider-Specific Environment Variables
 

{revenium_python_sdk-0.1.10 → revenium_python_sdk-0.2.0}/README.md

@@ -1223,6 +1223,44 @@ See [`examples/openai/openai_blocking_demo.py`](examples/openai/openai_blocking_
 |----------|-------------|
 | `REVENIUM_METERING_API_KEY` | Your Revenium API key (starts with `hak_` or `rev_`) |
 
+### Configuring After Import
+
+The metering client is normally built from the environment when
+`revenium_middleware` is first imported. If your credentials only become
+available later (a secrets-vault bootstrap, framework settings hooks, import
+ordering), you don't need to restart: as soon as `REVENIUM_METERING_API_KEY`
+appears in the environment, the next metered call picks it up automatically.
+You can also configure programmatically at any time:
+
+```python
+import revenium_middleware
+
+revenium_middleware.initialize_metering(
+    api_key="hak_your_key",                    # defaults to REVENIUM_METERING_API_KEY
+    base_url="https://api.revenium.ai",        # defaults to REVENIUM_METERING_BASE_URL
+)
+```
+
+`initialize_metering()` returns `True` when metering is enabled after the
+call; invoke it with no arguments to re-read the environment.
+
+### Delivery Resilience (Store-and-Forward)
+
+Metering events that still fail after the client's own retries (network
+outages, 5xx, rate limiting) are not lost: they are held in a bounded
+in-memory buffer and replayed automatically in the background every 30
+seconds, reusing each event's original `Idempotency-Key` so replays can
+never double-bill. Permanent failures (401/403/404/422) are never buffered.
+The buffer holds up to 1000 events (oldest evicted first) for at most 24
+hours, and is drained on graceful shutdown. Inspect it programmatically:
+
+```python
+from revenium_middleware import get_buffer_stats
+
+print(get_buffer_stats())
+# {'size': 0, 'max_size': 1000, 'total_buffered': 3, 'total_replayed': 3, ...}
+```
+
 ### Optional Environment Variables
 
 | Variable | Default | Description |
@@ -1241,6 +1279,8 @@ See [`examples/openai/openai_blocking_demo.py`](examples/openai/openai_blocking_
 | `REVENIUM_TRANSACTION_NAME` | - | Human-friendly operation name |
 | `REVENIUM_RETRY_NUMBER` | - | Retry attempt number |
 | `REVENIUM_BEDROCK_DISABLE` | - | Set to `1` to disable Bedrock auto-detection |
+| `REVENIUM_BUFFER_MAX_SIZE` | `1000` | Store-and-forward buffer capacity (oldest events evicted when full) |
+| `REVENIUM_BUFFER_FLUSH_INTERVAL` | `30` | Seconds between automatic replay attempts for buffered events |
 
 ### Provider-Specific Environment Variables
 

{revenium_python_sdk-0.1.10 → revenium_python_sdk-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "revenium-python-sdk"
-version = "0.1.10"
+version = "0.2.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"

{revenium_python_sdk-0.1.10 → revenium_python_sdk-0.2.0}/revenium_middleware/__init__.py

@@ -138,6 +138,9 @@ logger.propagate = True
 # Existing imports like `from revenium_middleware import client` keep working.
 from ._core import (  # noqa: E402
     client,
+    get_buffer_stats,
+    get_client,
+    initialize_metering,
     run_async_in_thread,
     shutdown_event,
     revenium_meter,
@@ -166,6 +169,9 @@ from .agentic_outcomes import AgenticOutcomeClient, AgenticOutcomeSettings  # no
 __all__ = [
     # Metering exports
     "client",
+    "get_buffer_stats",
+    "get_client",
+    "initialize_metering",
     "run_async_in_thread",
     "shutdown_event",
     # Decorator exports

{revenium_python_sdk-0.1.10 → revenium_python_sdk-0.2.0}/revenium_middleware/_core/__init__.py

@@ -5,7 +5,8 @@ This subpackage contains the foundational components shared across all
 provider-specific middleware implementations.
 """
 
-from .metering import run_async_in_thread, shutdown_event, client
+from .metering import run_async_in_thread, shutdown_event, client, get_client, initialize_metering
+from .metering_buffer import get_buffer_stats
 from .metering_submission import submit_ai_event
 from .exceptions import BudgetExceededError
 from .enforcement import check_enforcement, is_circuit_breaker_enabled, stop_polling
@@ -50,6 +51,9 @@ from .trace_fields import (
 __all__ = [
     # Metering
     "client",
+    "get_client",
+    "initialize_metering",
+    "get_buffer_stats",
     "run_async_in_thread",
     "shutdown_event",
     "submit_ai_event",

{revenium_python_sdk-0.1.10 → revenium_python_sdk-0.2.0}/revenium_middleware/_core/enforcement.py

@@ -10,11 +10,13 @@ Opt-in via ``REVENIUM_CIRCUIT_BREAKER_ENABLED``. Disabled by default so the
 SDK stays no-op for callers who haven't enrolled in cost controls.
 """
 
+import datetime
 import json
 import logging
 import os
 import threading
 import time
+from email.utils import parsedate_to_datetime
 from typing import List, Optional, Tuple
 from urllib.parse import quote, urlparse
 
@@ -27,6 +29,14 @@ logger = logging.getLogger("revenium_middleware.extension")
 
 _DEFAULT_POLL_INTERVAL = 60      # seconds between background refreshes
 _CACHE_TTL = 120                  # seconds before a cached rule is considered stale
+
+# Retry posture for the rule fetch (fleet backoff consistency): transient
+# failures ride out a spike instead of leaving spend controls on stale
+# limits until the next poll interval.
+_FETCH_MAX_ATTEMPTS = 5
+_FETCH_BACKOFF_INITIAL = 0.5      # seconds; doubles per attempt
+_FETCH_BACKOFF_CAP = 8.0          # seconds; also clamps Retry-After
+_FETCH_RETRYABLE_STATUS = frozenset({408, 429})  # plus any 5xx
 _RULES_CACHE_FILENAME = "revenium_enforcement_rules.json"
 
 _cached_rules: List[dict] = []
@@ -142,6 +152,37 @@ def _persist_cache_to_disk(rules: list) -> None:
         logger.debug("Failed to write enforcement cache to %s", path, exc_info=True)
 
 
+def _sleep(seconds: float) -> bool:
+    """Backoff wait, interruptible by shutdown so the poller exits promptly.
+
+    Returns True when shutdown was signalled, so callers can abort their
+    retry loop instead of burning the remaining attempts with zero delay.
+    """
+    return _stop_event.wait(seconds)
+
+
+def _is_retryable_status(status_code: int) -> bool:
+    return status_code in _FETCH_RETRYABLE_STATUS or status_code >= 500
+
+
+def _retry_after_seconds(response: "httpx.Response") -> Optional[float]:
+    """Parse Retry-After (delta-seconds or HTTP-date), clamped to the cap."""
+    raw = response.headers.get("Retry-After")
+    if not raw:
+        return None
+    try:
+        delay = float(raw)
+    except ValueError:
+        try:
+            when = parsedate_to_datetime(raw)
+            if when.tzinfo is None:
+                when = when.replace(tzinfo=datetime.timezone.utc)
+            delay = (when - datetime.datetime.now(datetime.timezone.utc)).total_seconds()
+        except Exception:
+            return None
+    return max(0.0, min(delay, _FETCH_BACKOFF_CAP))
+
+
 def _fetch_rules() -> Optional[list]:
     """Fetch current enforcement rules from the Revenium API.
 
@@ -170,29 +211,56 @@ def _fetch_rules() -> Optional[list]:
     # containing '/', '..', or '?' cannot retarget the request to a
     # different endpoint on the same origin.
     safe_team_id = quote(team_id, safe="")
-    try:
-        response = httpx.get(
-            f"{base_url}/v2/api/ai/enforcement-rules/{safe_team_id}",
-            headers={"x-api-key": api_key},
-            timeout=10,
-        )
-        # 204 No Content == no rules configured for this team; cache empty list
-        if response.status_code == 204:
-            return []
-        response.raise_for_status()
-        data = response.json()
-        # Server currently returns ``{"rules": [...], "compiledAt": ...}`` but
-        # accept a bare list too so a future schema change does not silently
-        # AttributeError its way into a stale cache.
-        if isinstance(data, list):
-            return data
-        if isinstance(data, dict):
-            return data.get("rules", [])
-        logger.warning("Unexpected enforcement response shape: %r", type(data).__name__)
-        return None
-    except Exception:
-        logger.debug("Failed to fetch enforcement rules, falling open", exc_info=True)
-        return None
+    url = f"{base_url}/v2/api/ai/enforcement-rules/{safe_team_id}"
+    for attempt in range(_FETCH_MAX_ATTEMPTS):
+        backoff = min(_FETCH_BACKOFF_INITIAL * (2 ** attempt), _FETCH_BACKOFF_CAP)
+        try:
+            response = httpx.get(url, headers={"x-api-key": api_key}, timeout=10)
+        except (httpx.TimeoutException, httpx.TransportError):
+            if attempt == _FETCH_MAX_ATTEMPTS - 1:
+                break
+            if _sleep(backoff):
+                break
+            continue
+        except Exception:
+            logger.debug("Failed to fetch enforcement rules, falling open", exc_info=True)
+            return None
+
+        if _is_retryable_status(response.status_code):
+            if attempt == _FETCH_MAX_ATTEMPTS - 1:
+                break
+            delay = _retry_after_seconds(response)
+            if _sleep(delay if delay is not None else backoff):
+                break
+            continue
+
+        try:
+            # 204 No Content == no rules configured for this team; cache empty list
+            if response.status_code == 204:
+                return []
+            response.raise_for_status()
+            data = response.json()
+            # Server currently returns ``{"rules": [...], "compiledAt": ...}`` but
+            # accept a bare list too so a future schema change does not silently
+            # AttributeError its way into a stale cache.
+            if isinstance(data, list):
+                return data
+            if isinstance(data, dict):
+                return data.get("rules", [])
+            logger.warning("Unexpected enforcement response shape: %r", type(data).__name__)
+            return None
+        except Exception:
+            logger.debug("Failed to fetch enforcement rules, falling open", exc_info=True)
+            return None
+
+    # Deliberate fail-open: an enforcement-refresh outage must never become a
+    # customer traffic outage. The caller preserves the previous cache and the
+    # next poll cycle tries again.
+    logger.warning(
+        "Enforcement rule fetch exhausted %d attempts; failing open on the previous cache",
+        _FETCH_MAX_ATTEMPTS,
+    )
+    return None
 
 
 def _refresh_cache() -> None:

revenium_python_sdk-0.2.0/revenium_middleware/_core/log_sanitize.py

@@ -0,0 +1,100 @@
+"""
+Shared log sanitization for all Revenium provider middlewares.
+
+Debug logging must never emit raw request kwargs: auth material (API keys,
+bearer tokens, headers) and prompt/message content (potential PII) are
+redacted before anything hits application logs.
+
+Usage:
+    logger.debug("Calling wrapped function with args: %s, kwargs: %s",
+                 sanitize_for_logging(args), sanitize_for_logging(kwargs))
+"""
+
+from typing import Any
+
+__all__ = ["sanitize_for_logging"]
+
+# Maximum recursion depth when sanitizing nested structures.
+MAX_SANITIZATION_DEPTH: int = 8
+
+# Strings longer than this are truncated (they may embed sensitive data).
+MAX_LOG_STRING_LENGTH: int = 100
+
+# Case-insensitive substring markers: any dict key containing one of these
+# has its value replaced with "[REDACTED]".
+SENSITIVE_KEY_MARKERS = frozenset(
+    {
+        "api_key",
+        "apikey",
+        "api-key",
+        "secret",
+        "token",
+        "password",
+        "credential",
+        "authorization",
+        "auth",
+        "bearer",
+        "private",
+    }
+)
+
+# Case-insensitive exact-match keys whose values carry prompt/message content
+# (potential PII). Values are summarized without recursing into them.
+CONTENT_FIELD_NAMES = frozenset(
+    {
+        "messages",
+        "prompt",
+        "system",
+        "input",
+        "contents",
+    }
+)
+
+_REDACTED = "[REDACTED]"
+
+
+def _summarize_content(value: Any) -> str:
+    """Summarize prompt/message content without exposing (or recursing into) it."""
+    if isinstance(value, (list, tuple)):
+        return f"[REDACTED: {len(value)} items]"
+    return _REDACTED
+
+
+def sanitize_for_logging(data: Any, max_depth: int = MAX_SANITIZATION_DEPTH) -> Any:
+    """
+    Sanitize data for secure logging.
+
+    - Values under keys containing a sensitive marker (api_key, token,
+      authorization, ...) are replaced with "[REDACTED]".
+    - Values under prompt/message content keys (messages, prompt, system,
+      input, contents) are summarized without recursing into them.
+    - Long strings are truncated to avoid leaking embedded payloads.
+
+    Args:
+        data: Data to sanitize (dict, list/tuple, or primitive)
+        max_depth: Maximum recursion depth to prevent runaway recursion
+
+    Returns:
+        Sanitized data safe for logging
+    """
+    if max_depth <= 0:
+        return "[MAX_DEPTH_REACHED]"
+
+    if isinstance(data, dict):
+        sanitized = {}
+        for key, value in data.items():
+            key_lower = str(key).lower()
+            if key_lower in CONTENT_FIELD_NAMES:
+                sanitized[key] = _summarize_content(value)
+            elif any(marker in key_lower for marker in SENSITIVE_KEY_MARKERS):
+                sanitized[key] = _REDACTED
+            else:
+                sanitized[key] = sanitize_for_logging(value, max_depth - 1)
+        return sanitized
+    elif isinstance(data, (list, tuple)):
+        return [sanitize_for_logging(item, max_depth - 1) for item in data]
+    elif isinstance(data, str) and len(data) > MAX_LOG_STRING_LENGTH:
+        # Truncate very long strings that might contain sensitive data
+        return data[:MAX_LOG_STRING_LENGTH] + "...[TRUNCATED]"
+    else:
+        return data

{revenium_python_sdk-0.1.10 → revenium_python_sdk-0.2.0}/revenium_middleware/_core/metering.py

@@ -55,6 +55,73 @@ api_key = os.environ.get("REVENIUM_METERING_API_KEY")
 _base_url_raw = os.environ.get("REVENIUM_METERING_BASE_URL")
 client = _build_metering_client(api_key, _base_url_raw)
 
+# Remembers a malformed env key so the lazy path doesn't re-raise per call.
+_last_failed_key: Optional[str] = None
+
+
+def _sync_client_reexports(new_client: Optional[ReveniumMetering]) -> None:
+    """Point the well-known re-export attributes at ``new_client``.
+
+    Takes the client explicitly (rather than reading the module-level global)
+    so concurrent rebuilds cannot interleave and leave the re-exports pointing
+    at a different instance than the caller just assigned. Dynamic readers
+    (``revenium_middleware.client``, ``revenium_middleware._core.client``)
+    observe the new client. Modules that bound the name via
+    ``from revenium_middleware import client`` at import time keep their
+    snapshot -- code paths that matter resolve through ``get_client()``
+    instead.
+    """
+    import sys
+    for module_name in ("revenium_middleware", "revenium_middleware._core"):
+        module = sys.modules.get(module_name)
+        if module is not None and hasattr(module, "client"):
+            module.client = new_client
+
+
+def initialize_metering(api_key: Optional[str] = None, base_url: Optional[str] = None) -> bool:
+    """(Re)build the metering client from explicit values or the environment.
+
+    Call this when credentials only become available after the first
+    ``revenium_middleware`` import (vault/parameter-store bootstraps, framework
+    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).
+    """
+    global client
+    key = api_key if api_key is not None else os.environ.get("REVENIUM_METERING_API_KEY")
+    url = base_url if base_url is not None else os.environ.get("REVENIUM_METERING_BASE_URL")
+    new_client = _build_metering_client(key, url)
+    client = new_client
+    _sync_client_reexports(new_client)
+    return new_client is not None
+
+
+def get_client() -> Optional[ReveniumMetering]:
+    """Return the metering client, retrying the environment when unset.
+
+    Covers env vars populated after import: as soon as
+    ``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
+    ``ValueError`` so programmatic misconfiguration fails loudly.
+    """
+    global _last_failed_key
+    if client is None:
+        env_key = os.environ.get("REVENIUM_METERING_API_KEY")
+        if env_key and env_key != _last_failed_key:
+            try:
+                initialize_metering()
+            except ValueError as e:
+                logger.warning("Deferred metering initialization failed: %s", e)
+                _last_failed_key = env_key
+    return client
+
 _threads_lock = threading.Lock()
 active_threads = []
 shutdown_event = threading.Event()
@@ -78,6 +145,16 @@ def handle_exit(signum=None, frame=None):
         shutdown_event.set()
 
 
+    # Drain the store-and-forward buffer (bounded) before joining metering
+    # threads, so events that already exhausted retries get a final attempt.
+    try:
+        from revenium_middleware._core import metering_buffer
+
+        if metering_buffer._buffer is not None:
+            metering_buffer._buffer.flush(deadline_seconds=5.0)
+    except Exception as e:
+        logger.debug("Metering buffer drain during shutdown failed: %s", e)
+
     with _threads_lock:
         threads_to_join = list(active_threads)
     for thread in threads_to_join: