revenium-python-sdk 0.1.3__tar.gz → 0.1.4__tar.gz

{revenium_python_sdk-0.1.3/revenium_python_sdk.egg-info → revenium_python_sdk-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: revenium-python-sdk
-Version: 0.1.3
+Version: 0.1.4
 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
@@ -1136,6 +1136,106 @@ Trace ID: abc-123
 
 ---
 
+## Cost Controls / Enforcement
+
+Block outbound provider requests client-side when a Revenium cost-limit rule trips. When the circuit breaker is enabled, the middleware polls enforcement rules from the Revenium API in a background daemon thread and raises `ReveniumCostLimitExceeded` **before** the upstream call, preventing spend beyond the configured limit.
+
+Currently wired for the OpenAI provider (other providers land via per-provider follow-on tickets).
+
+### Enable
+
+```bash
+pip install 'revenium-python-sdk[openai]'
+```
+
+```env
+REVENIUM_CIRCUIT_BREAKER_ENABLED=true
+REVENIUM_METERING_API_KEY=hak_your_key_here
+REVENIUM_TEAM_ID=your_hashed_team_id
+REVENIUM_ENFORCEMENT_BASE_URL=https://api.revenium.ai/profitstream  # optional
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `REVENIUM_CIRCUIT_BREAKER_ENABLED` | `false` | Master switch. `true` / `1` / `yes` / `on` to enable. |
+| `REVENIUM_BYPASS` | `false` | When `true`, every `check_enforcement` call short-circuits to a no-op. Useful for incident response. |
+| `REVENIUM_TEAM_ID` | — | Hashed team ID. Path component on rule fetches; required when the breaker is enabled. |
+| `REVENIUM_ENFORCEMENT_BASE_URL` | origin of `REVENIUM_METERING_BASE_URL` | Base URL for the enforcement API. Set when the enforcement API lives behind a context-path. |
+| `REVENIUM_CB_POLL_INTERVAL_SECONDS` | `60` | Background poll interval for rule refreshes. |
+| `REVENIUM_CB_FAIL_MODE` | `open` | `open` (default) lets calls through when no cache exists; `closed` raises `ReveniumCostLimitExceeded` until rules are loaded. |
+| `REVENIUM_CACHE_DIR` | — | When set, the rule cache is mirrored to `<dir>/revenium_enforcement_rules.json` so a restarted process doesn't fail-closed on the very first call. |
+
+### Public API
+
+Enforcement auto-initializes when the OpenAI middleware loads:
+
+```python
+import revenium_middleware.openai  # auto-instruments openai
+import openai
+
+client = openai.OpenAI()
+```
+
+The pre-call check fires before every chat / embeddings / responses call. When the circuit breaker is disabled, it is a no-op. When enabled:
+
+1. A daemon thread (`revenium-enforcement-poll`) starts on first use.
+2. It polls `GET {REVENIUM_ENFORCEMENT_BASE_URL}/v2/api/ai/enforcement-rules/{REVENIUM_TEAM_ID}` every `REVENIUM_CB_POLL_INTERVAL_SECONDS` with the `x-api-key` header.
+3. Rules are cached in-process (120 s TTL, refresh-on-stale with thundering-herd guard).
+4. `204 No Content` is treated as "no rules configured" — the cache is cleared.
+
+### Exception Contract
+
+```python
+from revenium_middleware.openai import ReveniumCostLimitExceeded
+```
+
+When a tripped rule matches the current request, the middleware raises before the OpenAI call is made. All structured fields are populated when the server provides them:
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `message` | `str` | Human-readable reason, e.g. `"Request blocked by Revenium enforcement rule: monthly-gpt4-cap"` |
+| `rule_name` | `str \| None` | Server-side rule name |
+| `current_value` | `float \| None` | Current metric value at the time of the block |
+| `threshold` | `float \| None` | Configured limit |
+| `resets_at` | `str \| None` | ISO-8601 timestamp the rule next resets |
+| `rule_id` | `str \| int \| None` | Server-side rule identifier |
+
+`ReveniumCostLimitExceeded` does **not** inherit from `ReveniumMiddlewareError`, so the OpenAI middleware's `handle_exception_safely` decorator never swallows it — it always reaches your `except` block.
+
+```python
+from revenium_middleware.openai import ReveniumCostLimitExceeded
+import openai
+
+client = openai.OpenAI()
+
+try:
+    response = client.chat.completions.create(
+        model="gpt-4o-mini",
+        messages=[{"role": "user", "content": "Summarize the meeting notes"}],
+    )
+except ReveniumCostLimitExceeded as exc:
+    print(f"Cost limit reached: {exc.message}")
+    print(f"Rule {exc.rule_name}: {exc.current_value} / {exc.threshold}; resets {exc.resets_at}")
+```
+
+### Fail-Open vs Fail-Closed
+
+By default (`REVENIUM_CB_FAIL_MODE=open`) enforcement failures never propagate to user code. If the rule fetch errors (network, 5xx, auth), the previous in-memory cache is preserved and a debug log line is emitted. If there is no cache yet, enforcement behaves as if no rules are configured and the request continues.
+
+Set `REVENIUM_CB_FAIL_MODE=closed` to refuse calls until at least one rule fetch (or `REVENIUM_CACHE_DIR` snapshot) succeeds. Pair with `REVENIUM_CACHE_DIR` so a process restart loads the last-known rules rather than blocking every call until the first poll completes.
+
+### Shadow Mode
+
+Rules with `shadowMode: true` are observe-and-log: they are skipped by `check_enforcement`. Use shadow mode on the server side to audit a rule before flipping it to enforce.
+
+### End-to-End Example
+
+See [`examples/openai/openai_blocking_demo.py`](examples/openai/openai_blocking_demo.py) for a runnable end-to-end demo using a seeded budget rule.
+
+---
+
 ## Configuration Reference
 
 ### Required Environment Variables
@@ -1238,6 +1338,12 @@ Available log levels:
 
 For detailed documentation, visit [docs.revenium.io](https://docs.revenium.io)
 
+### Server-Side Cost Controls
+
+Cost controls (spend limits, throttling, alerts) are managed server-side in Revenium, not in this SDK. The SDK reports usage; Revenium evaluates it against your configured cost controls.
+
+The cost-controls API endpoint is `/v2/api/ai/cost-controls`. This Python SDK does not call the endpoint directly — no SDK changes are required to use cost controls. If you manage cost controls via the Revenium API, HTTP client, or `curl`, see [docs.revenium.io](https://docs.revenium.io) for the current API reference.
+
 ## Contributing
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md)

{revenium_python_sdk-0.1.3 → revenium_python_sdk-0.1.4}/README.md

@@ -1048,6 +1048,106 @@ Trace ID: abc-123
 
 ---
 
+## Cost Controls / Enforcement
+
+Block outbound provider requests client-side when a Revenium cost-limit rule trips. When the circuit breaker is enabled, the middleware polls enforcement rules from the Revenium API in a background daemon thread and raises `ReveniumCostLimitExceeded` **before** the upstream call, preventing spend beyond the configured limit.
+
+Currently wired for the OpenAI provider (other providers land via per-provider follow-on tickets).
+
+### Enable
+
+```bash
+pip install 'revenium-python-sdk[openai]'
+```
+
+```env
+REVENIUM_CIRCUIT_BREAKER_ENABLED=true
+REVENIUM_METERING_API_KEY=hak_your_key_here
+REVENIUM_TEAM_ID=your_hashed_team_id
+REVENIUM_ENFORCEMENT_BASE_URL=https://api.revenium.ai/profitstream  # optional
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `REVENIUM_CIRCUIT_BREAKER_ENABLED` | `false` | Master switch. `true` / `1` / `yes` / `on` to enable. |
+| `REVENIUM_BYPASS` | `false` | When `true`, every `check_enforcement` call short-circuits to a no-op. Useful for incident response. |
+| `REVENIUM_TEAM_ID` | — | Hashed team ID. Path component on rule fetches; required when the breaker is enabled. |
+| `REVENIUM_ENFORCEMENT_BASE_URL` | origin of `REVENIUM_METERING_BASE_URL` | Base URL for the enforcement API. Set when the enforcement API lives behind a context-path. |
+| `REVENIUM_CB_POLL_INTERVAL_SECONDS` | `60` | Background poll interval for rule refreshes. |
+| `REVENIUM_CB_FAIL_MODE` | `open` | `open` (default) lets calls through when no cache exists; `closed` raises `ReveniumCostLimitExceeded` until rules are loaded. |
+| `REVENIUM_CACHE_DIR` | — | When set, the rule cache is mirrored to `<dir>/revenium_enforcement_rules.json` so a restarted process doesn't fail-closed on the very first call. |
+
+### Public API
+
+Enforcement auto-initializes when the OpenAI middleware loads:
+
+```python
+import revenium_middleware.openai  # auto-instruments openai
+import openai
+
+client = openai.OpenAI()
+```
+
+The pre-call check fires before every chat / embeddings / responses call. When the circuit breaker is disabled, it is a no-op. When enabled:
+
+1. A daemon thread (`revenium-enforcement-poll`) starts on first use.
+2. It polls `GET {REVENIUM_ENFORCEMENT_BASE_URL}/v2/api/ai/enforcement-rules/{REVENIUM_TEAM_ID}` every `REVENIUM_CB_POLL_INTERVAL_SECONDS` with the `x-api-key` header.
+3. Rules are cached in-process (120 s TTL, refresh-on-stale with thundering-herd guard).
+4. `204 No Content` is treated as "no rules configured" — the cache is cleared.
+
+### Exception Contract
+
+```python
+from revenium_middleware.openai import ReveniumCostLimitExceeded
+```
+
+When a tripped rule matches the current request, the middleware raises before the OpenAI call is made. All structured fields are populated when the server provides them:
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `message` | `str` | Human-readable reason, e.g. `"Request blocked by Revenium enforcement rule: monthly-gpt4-cap"` |
+| `rule_name` | `str \| None` | Server-side rule name |
+| `current_value` | `float \| None` | Current metric value at the time of the block |
+| `threshold` | `float \| None` | Configured limit |
+| `resets_at` | `str \| None` | ISO-8601 timestamp the rule next resets |
+| `rule_id` | `str \| int \| None` | Server-side rule identifier |
+
+`ReveniumCostLimitExceeded` does **not** inherit from `ReveniumMiddlewareError`, so the OpenAI middleware's `handle_exception_safely` decorator never swallows it — it always reaches your `except` block.
+
+```python
+from revenium_middleware.openai import ReveniumCostLimitExceeded
+import openai
+
+client = openai.OpenAI()
+
+try:
+    response = client.chat.completions.create(
+        model="gpt-4o-mini",
+        messages=[{"role": "user", "content": "Summarize the meeting notes"}],
+    )
+except ReveniumCostLimitExceeded as exc:
+    print(f"Cost limit reached: {exc.message}")
+    print(f"Rule {exc.rule_name}: {exc.current_value} / {exc.threshold}; resets {exc.resets_at}")
+```
+
+### Fail-Open vs Fail-Closed
+
+By default (`REVENIUM_CB_FAIL_MODE=open`) enforcement failures never propagate to user code. If the rule fetch errors (network, 5xx, auth), the previous in-memory cache is preserved and a debug log line is emitted. If there is no cache yet, enforcement behaves as if no rules are configured and the request continues.
+
+Set `REVENIUM_CB_FAIL_MODE=closed` to refuse calls until at least one rule fetch (or `REVENIUM_CACHE_DIR` snapshot) succeeds. Pair with `REVENIUM_CACHE_DIR` so a process restart loads the last-known rules rather than blocking every call until the first poll completes.
+
+### Shadow Mode
+
+Rules with `shadowMode: true` are observe-and-log: they are skipped by `check_enforcement`. Use shadow mode on the server side to audit a rule before flipping it to enforce.
+
+### End-to-End Example
+
+See [`examples/openai/openai_blocking_demo.py`](examples/openai/openai_blocking_demo.py) for a runnable end-to-end demo using a seeded budget rule.
+
+---
+
 ## Configuration Reference
 
 ### Required Environment Variables
@@ -1150,6 +1250,12 @@ Available log levels:
 
 For detailed documentation, visit [docs.revenium.io](https://docs.revenium.io)
 
+### Server-Side Cost Controls
+
+Cost controls (spend limits, throttling, alerts) are managed server-side in Revenium, not in this SDK. The SDK reports usage; Revenium evaluates it against your configured cost controls.
+
+The cost-controls API endpoint is `/v2/api/ai/cost-controls`. This Python SDK does not call the endpoint directly — no SDK changes are required to use cost controls. If you manage cost controls via the Revenium API, HTTP client, or `curl`, see [docs.revenium.io](https://docs.revenium.io) for the current API reference.
+
 ## Contributing
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md)

{revenium_python_sdk-0.1.3 → revenium_python_sdk-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "revenium-python-sdk"
-version = "0.1.3"
+version = "0.1.4"
 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.3 → revenium_python_sdk-0.1.4}/revenium_middleware/_core/__init__.py

@@ -6,6 +6,8 @@ provider-specific middleware implementations.
 """
 
 from .metering import run_async_in_thread, shutdown_event, client
+from .exceptions import ReveniumCostLimitExceeded
+from .enforcement import check_enforcement, is_circuit_breaker_enabled, stop_polling
 from .context import (
     is_inside_decorated_function,
     get_function_metadata,
@@ -46,6 +48,11 @@ __all__ = [
     "client",
     "run_async_in_thread",
     "shutdown_event",
+    # Enforcement / circuit breaker
+    "ReveniumCostLimitExceeded",
+    "check_enforcement",
+    "is_circuit_breaker_enabled",
+    "stop_polling",
     # Decorators
     "revenium_meter",
     "revenium_metadata",

{revenium_python_sdk-0.1.3 → revenium_python_sdk-0.1.4}/revenium_middleware/_core/config.py

@@ -74,6 +74,15 @@ class Config:
     SUMMARY_API_TIMEOUT: float = 5.0
     DEFAULT_BASE_URL: str = "https://api.revenium.ai"
 
+    # Enforcement / circuit breaker — see _core/enforcement.py.
+    # Taxonomy locked in BACK-1154 docs; keep in sync across SDKs.
+    ENV_REVENIUM_BYPASS: str = "REVENIUM_BYPASS"
+    ENV_CIRCUIT_BREAKER_ENABLED: str = "REVENIUM_CIRCUIT_BREAKER_ENABLED"
+    ENV_REVENIUM_ENFORCEMENT_BASE_URL: str = "REVENIUM_ENFORCEMENT_BASE_URL"
+    ENV_REVENIUM_CB_POLL_INTERVAL_SECONDS: str = "REVENIUM_CB_POLL_INTERVAL_SECONDS"
+    ENV_REVENIUM_CB_FAIL_MODE: str = "REVENIUM_CB_FAIL_MODE"
+    ENV_REVENIUM_CACHE_DIR: str = "REVENIUM_CACHE_DIR"
+
 
 class SecurityConfig:
     """Security-related configuration shared across all providers."""

revenium_python_sdk-0.1.4/revenium_middleware/_core/enforcement.py

@@ -0,0 +1,344 @@
+"""
+Enforcement engine for the Revenium circuit breaker.
+
+Polls cost-limit rules from the Revenium API in a daemon thread and caches
+them in memory. ``check_enforcement(...)`` is a pre-call hook that raises
+``ReveniumCostLimitExceeded`` when a tripped rule matches the current
+request, blocking the outbound provider call before any spend occurs.
+
+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 json
+import logging
+import os
+import threading
+import time
+from typing import List, Optional, Tuple
+from urllib.parse import quote, urlparse
+
+import httpx
+
+from .config import Config
+from .exceptions import ReveniumCostLimitExceeded
+
+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
+_RULES_CACHE_FILENAME = "revenium_enforcement_rules.json"
+
+_cached_rules: List[dict] = []
+_cache_lock = threading.Lock()
+_cache_timestamp = 0.0
+# True once any successful fetch (even an empty list / HTTP 204) or a disk
+# snapshot load has populated the cache. Distinguishes "server says no rules
+# apply" from "we have never heard back from the server" — fail-closed must
+# only block in the latter case.
+_cache_initialized = False
+
+_poll_thread: Optional[threading.Thread] = None
+_poll_lock = threading.Lock()
+_stop_event = threading.Event()
+
+# Serializes synchronous stale-cache refreshes to prevent thundering herd
+_refresh_lock = threading.Lock()
+
+# Single-shot warnings so misconfigured environments don't spam logs
+_team_id_warned = False
+_disk_load_attempted = False
+
+
+def _env_truthy(name: str) -> bool:
+    return os.environ.get(name, "").lower() in ("1", "true", "yes", "on")
+
+
+def is_circuit_breaker_enabled() -> bool:
+    """Return True when the operator has opted in to enforcement."""
+    return _env_truthy(Config.ENV_CIRCUIT_BREAKER_ENABLED)
+
+
+def is_bypass_enabled() -> bool:
+    """``REVENIUM_BYPASS=true`` short-circuits enforcement at every callsite."""
+    return _env_truthy(Config.ENV_REVENIUM_BYPASS)
+
+
+def _poll_interval_seconds() -> int:
+    raw = os.environ.get(Config.ENV_REVENIUM_CB_POLL_INTERVAL_SECONDS, "")
+    if not raw:
+        return _DEFAULT_POLL_INTERVAL
+    try:
+        value = int(raw)
+        return value if value > 0 else _DEFAULT_POLL_INTERVAL
+    except ValueError:
+        logger.debug("Invalid %s=%r, using default", Config.ENV_REVENIUM_CB_POLL_INTERVAL_SECONDS, raw)
+        return _DEFAULT_POLL_INTERVAL
+
+
+def _fail_mode_is_closed() -> bool:
+    """``REVENIUM_CB_FAIL_MODE=closed`` raises when no usable cache exists."""
+    return os.environ.get(Config.ENV_REVENIUM_CB_FAIL_MODE, "open").lower() == "closed"
+
+
+def _cache_file_path() -> Optional[str]:
+    cache_dir = os.environ.get(Config.ENV_REVENIUM_CACHE_DIR, "")
+    if not cache_dir:
+        return None
+    return os.path.join(cache_dir, _RULES_CACHE_FILENAME)
+
+
+def _get_enforcement_base_url() -> str:
+    """Base URL for enforcement API calls.
+
+    Prefers ``REVENIUM_ENFORCEMENT_BASE_URL`` so a context-path
+    (``http://localhost:8080/profitstream``) survives intact. Falls back to
+    the origin of the metering URL when unset.
+    """
+    explicit = os.environ.get(Config.ENV_REVENIUM_ENFORCEMENT_BASE_URL, "")
+    if explicit:
+        return explicit.rstrip("/")
+    metering_url = os.environ.get(Config.ENV_REVENIUM_BASE_URL, "https://api.revenium.ai/meter/")
+    parsed = urlparse(metering_url)
+    return f"{parsed.scheme}://{parsed.netloc}"
+
+
+def _load_cache_from_disk() -> None:
+    global _cached_rules, _cache_timestamp, _disk_load_attempted, _cache_initialized
+    # Check-and-set under _cache_lock so two cold-start callers can't both
+    # observe _disk_load_attempted=False and race on the snapshot read.
+    with _cache_lock:
+        if _disk_load_attempted:
+            return
+        _disk_load_attempted = True
+    path = _cache_file_path()
+    if not path or not os.path.exists(path):
+        return
+    try:
+        with open(path, "r", encoding="utf-8") as handle:
+            data = json.load(handle)
+        if isinstance(data, list):
+            with _cache_lock:
+                _cached_rules = data
+                # Treat as stale so the next call still triggers a refresh,
+                # but the disk snapshot prevents fail-closed from raising on
+                # the very first request after a process restart.
+                _cache_timestamp = 0.0
+                _cache_initialized = True
+            logger.debug("Loaded %d enforcement rule(s) from %s", len(data), path)
+    except Exception:
+        logger.debug("Failed to read enforcement cache from %s", path, exc_info=True)
+
+
+def _persist_cache_to_disk(rules: list) -> None:
+    path = _cache_file_path()
+    if not path:
+        return
+    try:
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(path, "w", encoding="utf-8") as handle:
+            json.dump(rules, handle)
+    except Exception:
+        logger.debug("Failed to write enforcement cache to %s", path, exc_info=True)
+
+
+def _fetch_rules() -> Optional[list]:
+    """Fetch current enforcement rules from the Revenium API.
+
+    Returns a list (possibly empty) on success, or ``None`` on failure so
+    the caller can preserve the previous cache.
+    """
+    global _team_id_warned
+
+    api_key = os.environ.get(Config.ENV_REVENIUM_API_KEY, "")
+    if not api_key:
+        logger.debug("No API key configured, skipping enforcement rule fetch")
+        return None
+
+    team_id = os.environ.get(Config.ENV_REVENIUM_TEAM_ID, "")
+    if not team_id:
+        if not _team_id_warned:
+            logger.warning(
+                "REVENIUM_TEAM_ID is not set — enforcement rule polling disabled. "
+                "Set this to your hashed team ID to enable cost-limit enforcement."
+            )
+            _team_id_warned = True
+        return None
+
+    base_url = _get_enforcement_base_url()
+    # Percent-encode the team_id path segment so a misconfigured value
+    # 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
+
+
+def _refresh_cache() -> None:
+    """Refresh the in-memory rule cache.
+
+    Only advances ``_cache_timestamp`` on a successful fetch — a transient
+    network error must not poison the stale-cache trigger and silently
+    suppress retries for the next ``_CACHE_TTL`` window. Disk persistence
+    happens outside ``_cache_lock`` so a slow filesystem write can't block
+    concurrent ``check_enforcement`` callers on the pre-call path.
+    """
+    global _cached_rules, _cache_timestamp, _cache_initialized
+    rules = _fetch_rules()
+    if rules is None:
+        return
+    with _cache_lock:
+        _cached_rules = rules
+        _cache_timestamp = time.monotonic()
+        _cache_initialized = True
+    _persist_cache_to_disk(rules)
+
+
+def _poll_loop() -> None:
+    interval = _poll_interval_seconds()
+    while not _stop_event.is_set():
+        _refresh_cache()
+        _stop_event.wait(interval)
+
+
+def _ensure_poller_running() -> None:
+    global _poll_thread
+    with _poll_lock:
+        if _poll_thread is not None and _poll_thread.is_alive():
+            return
+        _stop_event.clear()
+        _poll_thread = threading.Thread(
+            target=_poll_loop,
+            name="revenium-enforcement-poll",
+            daemon=True,
+        )
+        _poll_thread.start()
+
+
+def _get_rules() -> Tuple[list, bool]:
+    """Return cached rules and the initialized flag as a single snapshot.
+
+    Reading both fields under one ``_cache_lock`` acquisition prevents the
+    fail-closed path from torn-reading ``_cache_initialized`` against a
+    half-written ``_cached_rules`` from the background poller.
+    """
+    now = time.monotonic()
+    with _cache_lock:
+        age = now - _cache_timestamp
+        rules = list(_cached_rules)
+        initialized = _cache_initialized
+    if age > _CACHE_TTL:
+        if _refresh_lock.acquire(blocking=False):
+            try:
+                _refresh_cache()
+                with _cache_lock:
+                    rules = list(_cached_rules)
+                    initialized = _cache_initialized
+            finally:
+                _refresh_lock.release()
+    return rules, initialized
+
+
+def _coerce_float(value) -> Optional[float]:
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def check_enforcement(usage_metadata: Optional[dict] = None) -> None:
+    """Pre-call enforcement check.
+
+    Invoke before the upstream provider call. No-op when the circuit breaker
+    is disabled or no rules are tripped.
+
+    Raises:
+        ReveniumCostLimitExceeded: when a cost-limit rule blocks the call.
+            All structured fields (``rule_name``, ``current_value``,
+            ``threshold``, ``resets_at``, ``rule_id``) are populated when the
+            server provides them.
+    """
+    if is_bypass_enabled():
+        return
+    if not is_circuit_breaker_enabled():
+        return
+
+    _load_cache_from_disk()
+    _ensure_poller_running()
+    rules, initialized = _get_rules()
+
+    # Fail-closed mode: only block when the cache has *never* loaded. An
+    # empty list from a successful fetch (HTTP 204 = "no rules apply") is a
+    # valid initialized state and must pass through. Use the snapshot taken
+    # under _cache_lock so the decision can't see a torn write.
+    if _fail_mode_is_closed() and not initialized:
+        raise ReveniumCostLimitExceeded(
+            "Request blocked: enforcement cache is uninitialized and "
+            "REVENIUM_CB_FAIL_MODE=closed."
+        )
+
+    credential = (usage_metadata or {}).get("subscriber_credential", "")
+
+    for rule in rules:
+        if not isinstance(rule, dict):
+            continue
+        # A rule is tripped when the server marks it as ``breached`` (current
+        # nucleus schema) or ``blocked`` (legacy). Skip ``shadowMode`` rules
+        # even when breached — those are observe-and-log only.
+        is_tripped = rule.get("breached", False) or rule.get("blocked", False)
+        if not is_tripped:
+            continue
+        if rule.get("shadowMode", False):
+            continue
+
+        rule_credential = rule.get("credential", "")
+        if rule_credential and rule_credential != credential:
+            continue
+
+        rule_name = rule.get("name", "cost limit")
+        raise ReveniumCostLimitExceeded(
+            message=f"Request blocked by Revenium enforcement rule: {rule_name}",
+            rule_name=rule_name,
+            current_value=_coerce_float(rule.get("currentValue")),
+            threshold=_coerce_float(rule.get("threshold")),
+            resets_at=rule.get("resetsAt"),
+            rule_id=rule.get("ruleId") or rule.get("id"),
+        )
+
+
+def stop_polling() -> None:
+    """Gracefully stop the background polling thread.
+
+    Reads ``_poll_thread`` under ``_poll_lock`` to avoid a TOCTOU race with
+    ``_ensure_poller_running`` spinning the thread up on a concurrent first
+    request — without the lock, shutdown could observe ``None`` and skip the
+    ``join`` even though a poller is alive.
+    """
+    _stop_event.set()
+    with _poll_lock:
+        thread = _poll_thread
+    if thread is not None:
+        thread.join(timeout=5)

revenium_python_sdk-0.1.4/revenium_middleware/_core/exceptions.py

@@ -0,0 +1,35 @@
+"""
+Core exceptions shared across all Revenium middleware providers.
+
+The unified SDK ships ``ReveniumCostLimitExceeded`` from ``_core`` so every
+provider subpackage (openai, anthropic, google, …) raises the same exception
+type and downstream callers can ``except ReveniumCostLimitExceeded`` once.
+"""
+
+from typing import Optional, Union
+
+
+class ReveniumCostLimitExceeded(Exception):
+    """Raised when a Revenium enforcement rule blocks the outbound request.
+
+    Inherits directly from ``Exception`` (not from any middleware-error base)
+    so per-provider ``handle_exception_safely`` decorators never swallow it —
+    enforcement must always reach the caller.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        rule_name: Optional[str] = None,
+        current_value: Optional[float] = None,
+        threshold: Optional[float] = None,
+        resets_at: Optional[str] = None,
+        rule_id: Optional[Union[str, int]] = None,
+    ):
+        super().__init__(message)
+        self.message = message
+        self.rule_name = rule_name
+        self.current_value = current_value
+        self.threshold = threshold
+        self.resets_at = resets_at
+        self.rule_id = rule_id

{revenium_python_sdk-0.1.3 → revenium_python_sdk-0.1.4}/revenium_middleware/openai/__init__.py

@@ -10,6 +10,8 @@ Usage:
 """
 import logging
 
+from revenium_middleware._core.exceptions import ReveniumCostLimitExceeded
+
 logger = logging.getLogger(__name__)
 
 # Conditionally import middleware (requires wrapt + openai SDK)
@@ -20,4 +22,4 @@ except ImportError:
     logger.debug("OpenAI middleware dependencies not available, middleware not loaded")
     create_wrapper = None  # type: ignore
 
-__all__ = ["create_wrapper"]
+__all__ = ["create_wrapper", "ReveniumCostLimitExceeded"]

{revenium_python_sdk-0.1.3 → revenium_python_sdk-0.1.4}/revenium_middleware/openai/exceptions.py

@@ -5,6 +5,8 @@ This module defines a hierarchy of exceptions that provide better error handling
 and more specific error information for different failure scenarios.
 """
 
+from revenium_middleware._core.exceptions import ReveniumCostLimitExceeded  # noqa: F401
+
 
 class ReveniumMiddlewareError(Exception):
     """Base exception for all Revenium middleware errors."""
@@ -70,6 +72,9 @@ def handle_exception_safely(func):
     def wrapper(*args, **kwargs):
         try:
             return func(*args, **kwargs)
+        except ReveniumCostLimitExceeded:
+            # Enforcement exceptions must reach the caller — never swallow.
+            raise
         except ReveniumMiddlewareError as e:
             # Log middleware-specific errors
             import logging

{revenium_python_sdk-0.1.3 → revenium_python_sdk-0.1.4}/revenium_middleware/openai/middleware.py

@@ -7,6 +7,8 @@ from enum import Enum
 
 import wrapt
 from revenium_middleware import client, run_async_in_thread, shutdown_event, merge_metadata
+from revenium_middleware._core.enforcement import check_enforcement
+from revenium_middleware._core.exceptions import ReveniumCostLimitExceeded  # noqa: F401 — re-exported via openai.exceptions
 from revenium_middleware._core.subscriber import extract_subscriber_from_metadata
 from revenium_middleware._core.fields import extract_org_and_product, extract_common_metadata, extract_agentic_job_fields, merge_extra_body
 from revenium_middleware._core.config import is_selective_metering_enabled, is_capture_prompts_enabled
@@ -804,6 +806,10 @@ def embeddings_create_wrapper(wrapped, instance, args, kwargs):
 
     # Record request time
     request_time_dt = datetime.datetime.now(datetime.timezone.utc)
+
+    # Enforcement pre-call check — may raise ReveniumCostLimitExceeded
+    check_enforcement(usage_metadata)
+
     logger.debug(
         f"Calling wrapped embeddings function with args: {args}, "
         f"kwargs: {kwargs}"
@@ -890,6 +896,10 @@ def create_wrapper(wrapped, instance, args, kwargs):
             azure_config.validate_deployment()
 
     request_time_dt = datetime.datetime.now(datetime.timezone.utc)
+
+    # Enforcement pre-call check — may raise ReveniumCostLimitExceeded
+    check_enforcement(usage_metadata)
+
     logger.debug(
         f"Calling wrapped function with args: {args}, kwargs: {kwargs}"
     )
@@ -1239,6 +1249,10 @@ def responses_create_wrapper(wrapped, instance, args, kwargs):
 
     # Record request time
     request_time_dt = datetime.datetime.now(datetime.timezone.utc)
+
+    # Enforcement pre-call check — may raise ReveniumCostLimitExceeded
+    check_enforcement(usage_metadata)
+
     logger.debug(f"Calling wrapped responses function with args: {args}, kwargs: {kwargs}")
 
     # Call the original OpenAI function
@@ -1640,6 +1654,9 @@ def async_create_wrapper(wrapped, instance, args, kwargs):
 
     request_time_dt = datetime.datetime.now(datetime.timezone.utc)
 
+    # Enforcement pre-call check — may raise ReveniumCostLimitExceeded
+    check_enforcement(usage_metadata)
+
     async def _async_invoke():
         response = await wrapped(*args, **kwargs)
 
@@ -1703,6 +1720,9 @@ def async_embeddings_create_wrapper(wrapped, instance, args, kwargs):
 
     request_time_dt = datetime.datetime.now(datetime.timezone.utc)
 
+    # Enforcement pre-call check — may raise ReveniumCostLimitExceeded
+    check_enforcement(usage_metadata)
+
     async def _async_invoke():
         response = await wrapped(*args, **kwargs)
 

{revenium_python_sdk-0.1.3 → revenium_python_sdk-0.1.4/revenium_python_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: revenium-python-sdk
-Version: 0.1.3
+Version: 0.1.4
 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
@@ -1136,6 +1136,106 @@ Trace ID: abc-123
 
 ---
 
+## Cost Controls / Enforcement
+
+Block outbound provider requests client-side when a Revenium cost-limit rule trips. When the circuit breaker is enabled, the middleware polls enforcement rules from the Revenium API in a background daemon thread and raises `ReveniumCostLimitExceeded` **before** the upstream call, preventing spend beyond the configured limit.
+
+Currently wired for the OpenAI provider (other providers land via per-provider follow-on tickets).
+
+### Enable
+
+```bash
+pip install 'revenium-python-sdk[openai]'
+```
+
+```env
+REVENIUM_CIRCUIT_BREAKER_ENABLED=true
+REVENIUM_METERING_API_KEY=hak_your_key_here
+REVENIUM_TEAM_ID=your_hashed_team_id
+REVENIUM_ENFORCEMENT_BASE_URL=https://api.revenium.ai/profitstream  # optional
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `REVENIUM_CIRCUIT_BREAKER_ENABLED` | `false` | Master switch. `true` / `1` / `yes` / `on` to enable. |
+| `REVENIUM_BYPASS` | `false` | When `true`, every `check_enforcement` call short-circuits to a no-op. Useful for incident response. |
+| `REVENIUM_TEAM_ID` | — | Hashed team ID. Path component on rule fetches; required when the breaker is enabled. |
+| `REVENIUM_ENFORCEMENT_BASE_URL` | origin of `REVENIUM_METERING_BASE_URL` | Base URL for the enforcement API. Set when the enforcement API lives behind a context-path. |
+| `REVENIUM_CB_POLL_INTERVAL_SECONDS` | `60` | Background poll interval for rule refreshes. |
+| `REVENIUM_CB_FAIL_MODE` | `open` | `open` (default) lets calls through when no cache exists; `closed` raises `ReveniumCostLimitExceeded` until rules are loaded. |
+| `REVENIUM_CACHE_DIR` | — | When set, the rule cache is mirrored to `<dir>/revenium_enforcement_rules.json` so a restarted process doesn't fail-closed on the very first call. |
+
+### Public API
+
+Enforcement auto-initializes when the OpenAI middleware loads:
+
+```python
+import revenium_middleware.openai  # auto-instruments openai
+import openai
+
+client = openai.OpenAI()
+```
+
+The pre-call check fires before every chat / embeddings / responses call. When the circuit breaker is disabled, it is a no-op. When enabled:
+
+1. A daemon thread (`revenium-enforcement-poll`) starts on first use.
+2. It polls `GET {REVENIUM_ENFORCEMENT_BASE_URL}/v2/api/ai/enforcement-rules/{REVENIUM_TEAM_ID}` every `REVENIUM_CB_POLL_INTERVAL_SECONDS` with the `x-api-key` header.
+3. Rules are cached in-process (120 s TTL, refresh-on-stale with thundering-herd guard).
+4. `204 No Content` is treated as "no rules configured" — the cache is cleared.
+
+### Exception Contract
+
+```python
+from revenium_middleware.openai import ReveniumCostLimitExceeded
+```
+
+When a tripped rule matches the current request, the middleware raises before the OpenAI call is made. All structured fields are populated when the server provides them:
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `message` | `str` | Human-readable reason, e.g. `"Request blocked by Revenium enforcement rule: monthly-gpt4-cap"` |
+| `rule_name` | `str \| None` | Server-side rule name |
+| `current_value` | `float \| None` | Current metric value at the time of the block |
+| `threshold` | `float \| None` | Configured limit |
+| `resets_at` | `str \| None` | ISO-8601 timestamp the rule next resets |
+| `rule_id` | `str \| int \| None` | Server-side rule identifier |
+
+`ReveniumCostLimitExceeded` does **not** inherit from `ReveniumMiddlewareError`, so the OpenAI middleware's `handle_exception_safely` decorator never swallows it — it always reaches your `except` block.
+
+```python
+from revenium_middleware.openai import ReveniumCostLimitExceeded
+import openai
+
+client = openai.OpenAI()
+
+try:
+    response = client.chat.completions.create(
+        model="gpt-4o-mini",
+        messages=[{"role": "user", "content": "Summarize the meeting notes"}],
+    )
+except ReveniumCostLimitExceeded as exc:
+    print(f"Cost limit reached: {exc.message}")
+    print(f"Rule {exc.rule_name}: {exc.current_value} / {exc.threshold}; resets {exc.resets_at}")
+```
+
+### Fail-Open vs Fail-Closed
+
+By default (`REVENIUM_CB_FAIL_MODE=open`) enforcement failures never propagate to user code. If the rule fetch errors (network, 5xx, auth), the previous in-memory cache is preserved and a debug log line is emitted. If there is no cache yet, enforcement behaves as if no rules are configured and the request continues.
+
+Set `REVENIUM_CB_FAIL_MODE=closed` to refuse calls until at least one rule fetch (or `REVENIUM_CACHE_DIR` snapshot) succeeds. Pair with `REVENIUM_CACHE_DIR` so a process restart loads the last-known rules rather than blocking every call until the first poll completes.
+
+### Shadow Mode
+
+Rules with `shadowMode: true` are observe-and-log: they are skipped by `check_enforcement`. Use shadow mode on the server side to audit a rule before flipping it to enforce.
+
+### End-to-End Example
+
+See [`examples/openai/openai_blocking_demo.py`](examples/openai/openai_blocking_demo.py) for a runnable end-to-end demo using a seeded budget rule.
+
+---
+
 ## Configuration Reference
 
 ### Required Environment Variables
@@ -1238,6 +1338,12 @@ Available log levels:
 
 For detailed documentation, visit [docs.revenium.io](https://docs.revenium.io)
 
+### Server-Side Cost Controls
+
+Cost controls (spend limits, throttling, alerts) are managed server-side in Revenium, not in this SDK. The SDK reports usage; Revenium evaluates it against your configured cost controls.
+
+The cost-controls API endpoint is `/v2/api/ai/cost-controls`. This Python SDK does not call the endpoint directly — no SDK changes are required to use cost controls. If you manage cost controls via the Revenium API, HTTP client, or `curl`, see [docs.revenium.io](https://docs.revenium.io) for the current API reference.
+
 ## Contributing
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md)

{revenium_python_sdk-0.1.3 → revenium_python_sdk-0.1.4}/revenium_python_sdk.egg-info/SOURCES.txt

@@ -6,6 +6,8 @@ revenium_middleware/_core/__init__.py
 revenium_middleware/_core/config.py
 revenium_middleware/_core/context.py
 revenium_middleware/_core/decorators.py
+revenium_middleware/_core/enforcement.py
+revenium_middleware/_core/exceptions.py
 revenium_middleware/_core/fields.py
 revenium_middleware/_core/metering.py
 revenium_middleware/_core/patch_registry.py