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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: revenium-python-sdk
-Version: 0.4.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
@@ -36,6 +36,9 @@ Provides-Extra: langchain
 Requires-Dist: langchain>=0.1.16; extra == "langchain"
 Requires-Dist: langchain-openai>=0.1.0; extra == "langchain"
 Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
+Provides-Extra: griptape
+Requires-Dist: griptape<2.0.0,>=1.0.0; python_version >= "3.10" and extra == "griptape"
+Requires-Dist: requests>=2.25.0; extra == "griptape"
 Provides-Extra: perplexity
 Requires-Dist: wrapt>=1.14.0; extra == "perplexity"
 Requires-Dist: python-dotenv>=0.19.0; extra == "perplexity"
@@ -89,6 +92,7 @@ Requires-Dist: python-dotenv>=0.19.0; extra == "dev"
 Requires-Dist: anthropic>=0.30.0; extra == "dev"
 Requires-Dist: boto3; extra == "dev"
 Requires-Dist: ollama>=0.3.0; extra == "dev"
+Requires-Dist: griptape<2.0.0,>=1.0.0; python_version >= "3.10" and extra == "dev"
 Dynamic: license-file
 
 # Revenium Python SDK
@@ -132,6 +136,7 @@ The official Revenium Python SDK — unified AI metering middleware for deeply a
 | Perplexity (Native SDK) | `perplexity-native` | `pip install revenium-python-sdk[perplexity-native]` |
 | fal.ai | `fal` | `pip install revenium-python-sdk[fal]` |
 | LangChain | `langchain` | `pip install revenium-python-sdk[langchain]` |
+| Griptape | `griptape` | `pip install revenium-python-sdk[griptape]` |
 
 ## Feature Matrix
 
@@ -147,6 +152,7 @@ The official Revenium Python SDK — unified AI metering middleware for deeply a
 | Terminal Summary | Yes | Yes | Yes | Yes | Yes | - | - |
 | Azure / Bedrock | Azure | Bedrock | Vertex AI | - | All | - | - |
 | LangChain Integration | Yes | - | - | - | - | - | - |
+| Griptape Integration | Yes | Yes | - | Yes | Yes | - | - |
 | CrewAI Integration | - | - | - | - | Yes | - | - |
 | Proxy Mode | - | - | - | - | Yes | - | - |
 
@@ -208,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.
@@ -959,6 +1011,49 @@ Credentials come from the standard environment variables (`REVENIUM_METERING_API
 
 ---
 
+### Griptape
+
+Metered prompt and embedding drivers for [Griptape](https://github.com/griptape-ai/griptape) applications. Requires Python 3.10+.
+
+```bash
+pip install "revenium-python-sdk[griptape,openai]"     # OpenAI
+pip install "revenium-python-sdk[griptape,anthropic]"  # Anthropic
+pip install "revenium-python-sdk[griptape,ollama]"     # Ollama
+pip install "revenium-python-sdk[griptape,litellm,litellm-proxy]"  # 100+ providers via LiteLLM
+```
+
+`ReveniumDriver` auto-detects the provider from the model name (`gpt-*` → OpenAI, `claude-*` → Anthropic, `llama`/`mistral`/... → Ollama, anything else → LiteLLM) and wraps the matching Griptape prompt driver with Revenium metering:
+
+```python
+import os
+from griptape.structures import Agent
+from revenium_middleware.griptape import ReveniumDriver
+
+os.environ["REVENIUM_METERING_API_KEY"] = "your_revenium_key"
+
+agent = Agent(prompt_driver=ReveniumDriver(
+    model="gpt-4o-mini",
+    usage_metadata={"task_type": "demo"},
+))
+agent.run("Hello!")
+```
+
+Force a provider with `force_provider="litellm"`, or wrap an existing driver with `ReveniumDriver(base_driver=...)`.
+
+**Embeddings:**
+
+```python
+from revenium_middleware.griptape import ReveniumEmbeddingDriver
+
+driver = ReveniumEmbeddingDriver(model="text-embedding-3-large")
+```
+
+**Provider-specific drivers:** for direct control, use `ReveniumOpenAiDriver`, `ReveniumAnthropicDriver`, `ReveniumOllamaDriver`, `ReveniumLiteLLMDriver` or `ReveniumOpenAiEmbeddingDriver` — each subclasses the corresponding Griptape driver and accepts a `usage_metadata` dict (see [Metadata Fields](#metadata-fields)).
+
+**Migrating from `revenium-griptape`:** the standalone package is deprecated — install the `griptape` extra and change `from revenium_griptape import ReveniumDriver` to `from revenium_middleware.griptape import ReveniumDriver`. All driver class names are unchanged. One behaviour difference: the old package called `load_dotenv()` automatically at import time; the SDK never mutates your environment on import, so if you keep credentials in a `.env` file, call `load_dotenv()` yourself before creating a driver.
+
+---
+
 ## Metadata Fields
 
 Add business context to any API call by passing a `usage_metadata` dictionary. All fields are optional.
@@ -1026,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.4.0 → revenium_python_sdk-0.6.0}/README.md

@@ -39,6 +39,7 @@ The official Revenium Python SDK — unified AI metering middleware for deeply a
 | Perplexity (Native SDK) | `perplexity-native` | `pip install revenium-python-sdk[perplexity-native]` |
 | fal.ai | `fal` | `pip install revenium-python-sdk[fal]` |
 | LangChain | `langchain` | `pip install revenium-python-sdk[langchain]` |
+| Griptape | `griptape` | `pip install revenium-python-sdk[griptape]` |
 
 ## Feature Matrix
 
@@ -54,6 +55,7 @@ The official Revenium Python SDK — unified AI metering middleware for deeply a
 | Terminal Summary | Yes | Yes | Yes | Yes | Yes | - | - |
 | Azure / Bedrock | Azure | Bedrock | Vertex AI | - | All | - | - |
 | LangChain Integration | Yes | - | - | - | - | - | - |
+| Griptape Integration | Yes | Yes | - | Yes | Yes | - | - |
 | CrewAI Integration | - | - | - | - | Yes | - | - |
 | Proxy Mode | - | - | - | - | Yes | - | - |
 
@@ -115,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.
@@ -866,6 +914,49 @@ Credentials come from the standard environment variables (`REVENIUM_METERING_API
 
 ---
 
+### Griptape
+
+Metered prompt and embedding drivers for [Griptape](https://github.com/griptape-ai/griptape) applications. Requires Python 3.10+.
+
+```bash
+pip install "revenium-python-sdk[griptape,openai]"     # OpenAI
+pip install "revenium-python-sdk[griptape,anthropic]"  # Anthropic
+pip install "revenium-python-sdk[griptape,ollama]"     # Ollama
+pip install "revenium-python-sdk[griptape,litellm,litellm-proxy]"  # 100+ providers via LiteLLM
+```
+
+`ReveniumDriver` auto-detects the provider from the model name (`gpt-*` → OpenAI, `claude-*` → Anthropic, `llama`/`mistral`/... → Ollama, anything else → LiteLLM) and wraps the matching Griptape prompt driver with Revenium metering:
+
+```python
+import os
+from griptape.structures import Agent
+from revenium_middleware.griptape import ReveniumDriver
+
+os.environ["REVENIUM_METERING_API_KEY"] = "your_revenium_key"
+
+agent = Agent(prompt_driver=ReveniumDriver(
+    model="gpt-4o-mini",
+    usage_metadata={"task_type": "demo"},
+))
+agent.run("Hello!")
+```
+
+Force a provider with `force_provider="litellm"`, or wrap an existing driver with `ReveniumDriver(base_driver=...)`.
+
+**Embeddings:**
+
+```python
+from revenium_middleware.griptape import ReveniumEmbeddingDriver
+
+driver = ReveniumEmbeddingDriver(model="text-embedding-3-large")
+```
+
+**Provider-specific drivers:** for direct control, use `ReveniumOpenAiDriver`, `ReveniumAnthropicDriver`, `ReveniumOllamaDriver`, `ReveniumLiteLLMDriver` or `ReveniumOpenAiEmbeddingDriver` — each subclasses the corresponding Griptape driver and accepts a `usage_metadata` dict (see [Metadata Fields](#metadata-fields)).
+
+**Migrating from `revenium-griptape`:** the standalone package is deprecated — install the `griptape` extra and change `from revenium_griptape import ReveniumDriver` to `from revenium_middleware.griptape import ReveniumDriver`. All driver class names are unchanged. One behaviour difference: the old package called `load_dotenv()` automatically at import time; the SDK never mutates your environment on import, so if you keep credentials in a `.env` file, call `load_dotenv()` yourself before creating a driver.
+
+---
+
 ## Metadata Fields
 
 Add business context to any API call by passing a `usage_metadata` dictionary. All fields are optional.
@@ -933,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.4.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.4.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"
@@ -51,6 +51,10 @@ langchain = [
     "langchain-openai>=0.1.0",
     "langchain-core>=0.1.0",
 ]
+griptape = [
+    "griptape>=1.0.0,<2.0.0; python_version >= '3.10'",
+    "requests>=2.25.0",
+]
 perplexity = [
     "wrapt>=1.14.0",
     "python-dotenv>=0.19.0",
@@ -116,9 +120,11 @@ dev = [
     "anthropic>=0.30.0",
     "boto3",
     "ollama>=0.3.0",
+    "griptape>=1.0.0,<2.0.0; python_version >= '3.10'",
 ]
 
 [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.4.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.4.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.4.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.4.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.4.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: