revenium-python-sdk 0.1.0__py3-none-any.whl

revenium_middleware/perplexity/perplexity_sdk.py

@@ -0,0 +1,256 @@
+"""
+Middleware for native Perplexity SDK.
+
+This module provides metering support for the native perplexity-py SDK.
+"""
+import datetime
+import logging
+from typing import Dict, Any
+
+import wrapt
+from revenium_middleware import (
+    client,
+    run_async_in_thread,
+    shutdown_event,
+    merge_metadata,
+)
+
+from .provider import get_provider_metadata, Provider
+from .trace_fields import (
+    get_environment,
+    get_region,
+    get_credential_alias,
+    get_trace_type,
+    get_trace_name,
+    get_parent_transaction_id,
+    get_transaction_name,
+    get_retry_number
+)
+from .middleware import (
+    OperationType,
+    get_stop_reason,
+    extract_token_usage,
+    build_trace_fields
+)
+
+logger = logging.getLogger("revenium_middleware.perplexity.sdk")
+
+
+def perplexity_create_wrapper(wrapped, instance, args, kwargs):
+    """
+    Wrapper for perplexity.chat.completions.create to add Revenium metering.
+
+    This wrapper intercepts calls to the native Perplexity SDK and sends
+    usage data to Revenium.
+    """
+    logger.debug("Native Perplexity SDK chat completion wrapper called")
+
+    # Get usage_metadata from extra_body if present
+    extra_body = kwargs.get('extra_body', {})
+    api_metadata = extra_body.pop('usage_metadata', {}) if isinstance(extra_body, dict) else {}
+
+    # Merge with decorator metadata (API metadata takes precedence)
+    usage_metadata = merge_metadata(api_metadata)
+
+    # Get model from kwargs
+    model = kwargs.get('model', 'sonar')
+
+    # Check if streaming
+    is_streaming = kwargs.get('stream', False)
+
+    # Record request time
+    request_time_dt = datetime.datetime.now(datetime.timezone.utc)
+
+    # Generate transaction ID
+    transaction_id = f"perplexity-sdk-{request_time_dt.timestamp()}"
+
+    # Call original method
+    logger.debug(
+        f"Calling original Perplexity SDK create with model: {model}, "
+        f"streaming: {is_streaming}"
+    )
+    response = wrapped(*args, **kwargs)
+
+    # Handle response based on streaming
+    if is_streaming:
+        # For streaming, wrap the iterator
+        logger.debug("Wrapping streaming response")
+        return PerplexityStreamWrapper(
+            response,
+            model,
+            request_time_dt,
+            transaction_id,
+            usage_metadata
+        )
+    else:
+        # For non-streaming, send metering data
+        logger.debug("Sending metering data for non-streaming response")
+        run_async_in_thread(
+            send_perplexity_metering_data(
+                response=response,
+                model=model,
+                request_time_dt=request_time_dt,
+                transaction_id=transaction_id,
+                usage_metadata=usage_metadata,
+                is_streaming=False
+            )
+        )
+
+        return response
+
+
+class PerplexityStreamWrapper:
+    """Wrapper for Perplexity streaming responses to track usage."""
+
+    def __init__(self, stream, model, request_time_dt, transaction_id, usage_metadata):
+        self.stream = stream
+        self.model = model
+        self.request_time_dt = request_time_dt
+        self.transaction_id = transaction_id
+        self.usage_metadata = usage_metadata
+        self.chunks = []
+        self.last_chunk = None
+
+    def __iter__(self):
+        """Iterate over stream chunks and collect usage data."""
+        for chunk in self.stream:
+            self.chunks.append(chunk)
+            self.last_chunk = chunk
+            yield chunk
+
+        # After stream completes, send metering data
+        logger.debug("Stream completed, sending metering data")
+        run_async_in_thread(
+            send_perplexity_metering_data(
+                response=self.last_chunk,
+                model=self.model,
+                request_time_dt=self.request_time_dt,
+                transaction_id=self.transaction_id,
+                usage_metadata=self.usage_metadata,
+                is_streaming=True,
+                chunks=self.chunks
+            )
+        )
+
+
+async def send_perplexity_metering_data(
+    response,
+    model: str,
+    request_time_dt: datetime.datetime,
+    transaction_id: str,
+    usage_metadata: Dict[str, Any],
+    is_streaming: bool,
+    chunks=None
+):
+    """
+    Send metering data to Revenium for native Perplexity SDK.
+
+    This function extracts usage information from the Perplexity response
+    and sends it to Revenium's metering API.
+    """
+    try:
+        # Extract usage data from response
+        if hasattr(response, 'usage') and response.usage:
+            usage = response.usage
+            input_tokens = getattr(usage, 'prompt_tokens', 0)
+            output_tokens = getattr(usage, 'completion_tokens', 0)
+            total_tokens = getattr(usage, 'total_tokens', input_tokens + output_tokens)
+        else:
+            logger.warning("No usage data found in response")
+            input_tokens = 0
+            output_tokens = 0
+            total_tokens = 0
+
+        # Get finish reason
+        finish_reason = None
+        if hasattr(response, 'choices') and response.choices:
+            finish_reason = getattr(response.choices[0], 'finish_reason', None)
+
+        # Map to Revenium stop reason
+        stop_reason = get_stop_reason(finish_reason)
+
+        # Calculate duration
+        response_time_dt = datetime.datetime.now(datetime.timezone.utc)
+        duration_ms = int((response_time_dt - request_time_dt).total_seconds() * 1000)
+
+        # Get provider metadata
+        provider_metadata = get_provider_metadata(Provider.PERPLEXITY)
+
+        # Build trace fields
+        trace_fields = build_trace_fields()
+
+        # Detect operation type (native Perplexity SDK only supports chat)
+        operation_type = OperationType.CHAT
+
+        # Build completion args matching middleware.py schema
+        completion_args = {
+            "model": model,
+            "provider": provider_metadata["provider"],
+            "operation_type": operation_type.value,
+            "input_token_count": input_tokens,
+            "output_token_count": output_tokens,
+            "total_token_count": total_tokens,
+            "stop_reason": stop_reason,
+            "request_time": request_time_dt.strftime("%Y-%m-%dT%H:%M:%SZ"),
+            "response_time": response_time_dt.strftime("%Y-%m-%dT%H:%M:%SZ"),
+            "completion_start_time": response_time_dt.strftime("%Y-%m-%dT%H:%M:%SZ"),
+            "request_duration": duration_ms,
+            "transaction_id": transaction_id,
+            "is_streamed": is_streaming,
+            "cost_type": "AI",
+            "cache_creation_token_count": 0,
+            "cache_read_token_count": 0,
+            "reasoning_token_count": 0,
+        }
+
+        # Add optional fields from usage_metadata if they have values
+        if usage_metadata.get("trace_id"):
+            completion_args["trace_id"] = usage_metadata.get("trace_id")
+        if usage_metadata.get("task_type"):
+            completion_args["task_type"] = usage_metadata.get("task_type")
+        if usage_metadata.get("organization_id"):
+            completion_args["organization_id"] = usage_metadata.get("organization_id")
+        if usage_metadata.get("subscription_id"):
+            completion_args["subscription_id"] = usage_metadata.get("subscription_id")
+        if usage_metadata.get("product_id"):
+            completion_args["product_id"] = usage_metadata.get("product_id")
+        if usage_metadata.get("agent"):
+            completion_args["agent"] = usage_metadata.get("agent")
+        if usage_metadata.get("subscriber"):
+            completion_args["subscriber"] = usage_metadata.get("subscriber")
+
+        # Add custom metadata fields (service, step, service_name, etc.)
+        # These are additional fields that may be used for tracing/tracking
+        custom_fields = ["service", "step", "service_name"]
+        for field in custom_fields:
+            if usage_metadata.get(field):
+                completion_args[field] = usage_metadata.get(field)
+
+        # Add trace visualization fields from trace_fields
+        for key, value in trace_fields.items():
+            if value is not None:
+                completion_args[key] = value
+
+        # Send to Revenium
+        logger.debug(f"Sending metering data to Revenium: {completion_args}")
+        result = client.ai.create_completion(**completion_args)
+        logger.debug(f"Metering call result: {result}")
+
+    except Exception as e:
+        if not shutdown_event.is_set():
+            logger.warning(f"Error in metering call: {str(e)}")
+
+
+# Try to patch the Perplexity SDK if it's installed
+try:
+    import perplexity.resources.chat.completions  # noqa: F401
+
+    # Apply the wrapper
+    wrapt.wrap_function_wrapper(
+        'perplexity.resources.chat.completions',
+        'Completions.create',
+        perplexity_create_wrapper
+    )
+    logger.debug("Successfully patched native Perplexity SDK")
+except (ImportError, AttributeError) as e:
+    logger.debug(f"Native Perplexity SDK not available or incompatible: {e}")

revenium_middleware/perplexity/provider.py

@@ -0,0 +1,84 @@
+"""
+Provider detection for Perplexity AI API.
+
+This module handles detection of Perplexity as the AI provider
+and provides metadata about the provider.
+"""
+import logging
+from enum import Enum
+from typing import Optional, Any, Dict
+
+logger = logging.getLogger("revenium_middleware.perplexity.provider")
+
+
+class Provider(str, Enum):
+    """Supported AI providers."""
+    PERPLEXITY = "PERPLEXITY"
+    OPENAI = "OPENAI"  # Fallback for OpenAI-compatible APIs
+
+
+def detect_provider(client: Optional[Any] = None, base_url: Optional[str] = None) -> Provider:
+    """
+    Detect which AI provider is being used based on available information.
+
+    Detection priority:
+    1. Base URL substring matching ("perplexity.ai")
+    2. Client base_url attribute
+    3. Default to PERPLEXITY (since this is Perplexity middleware)
+
+    Args:
+        client: OpenAI client instance
+        base_url: Base URL for API calls
+
+    Returns:
+        Provider enum indicating detected provider
+    """
+    logger.debug("Detecting AI provider...")
+
+    # 1. Check base URL for Perplexity substring
+    if base_url and "perplexity" in str(base_url).lower():
+        logger.debug(f"Perplexity provider detected via base_url: {base_url}")
+        return Provider.PERPLEXITY
+
+    # 2. Check for client base_url if not provided directly
+    if client and hasattr(client, 'base_url') and client.base_url:
+        if "perplexity" in str(client.base_url).lower():
+            logger.debug(f"Perplexity provider detected via client.base_url: {client.base_url}")
+            return Provider.PERPLEXITY
+
+    # 3. Default to Perplexity (this is Perplexity middleware)
+    logger.debug("Defaulting to Perplexity provider")
+    return Provider.PERPLEXITY
+
+
+def get_provider_metadata(provider: Provider) -> Dict[str, str]:
+    """
+    Get metadata for the detected provider.
+
+    Args:
+        provider: Provider enum value
+
+    Returns:
+        Dictionary with provider metadata
+    """
+    metadata = {
+        "provider": provider.value,
+        "model_source": provider.value,
+    }
+    
+    logger.debug(f"Provider metadata: {metadata}")
+    return metadata
+
+
+def is_perplexity_provider(provider: Provider) -> bool:
+    """
+    Check if the provider is Perplexity.
+
+    Args:
+        provider: Provider enum value
+
+    Returns:
+        True if provider is Perplexity, False otherwise
+    """
+    return provider == Provider.PERPLEXITY
+

revenium_middleware/perplexity/trace_fields.py

@@ -0,0 +1,25 @@
+"""
+Trace visualization fields for Perplexity AI API.
+
+This module handles extraction and validation of trace visualization fields
+for distributed tracing and analytics.
+
+All functions are imported from _core.trace_fields. Perplexity has no
+provider-specific trace field functions.
+"""
+
+from revenium_middleware._core.trace_fields import (  # noqa: F401 — re-exported
+    TRACE_TYPE_MAX_LENGTH,
+    TRACE_NAME_MAX_LENGTH,
+    TRACE_TYPE_PATTERN,
+    get_environment,
+    get_region,
+    get_credential_alias,
+    get_trace_type,
+    get_trace_name,
+    get_parent_transaction_id,
+    get_transaction_name,
+    get_retry_number,
+    validate_trace_type,
+    validate_trace_name,
+)

revenium_python_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,252 @@
+Metadata-Version: 2.4
+Name: revenium-python-sdk
+Version: 0.1.0
+Summary: The official Revenium Python SDK — unified AI metering middleware for OpenAI, Anthropic, Google, Ollama, LiteLLM, and Perplexity.
+Author-email: Revenium <support@revenium.io>
+License: MIT
+Project-URL: Homepage, https://github.com/revenium/revenium-python-sdk
+Project-URL: Bug Tracker, https://github.com/revenium/revenium-python-sdk/issues
+Project-URL: Documentation, https://docs.revenium.io
+Keywords: sdk,ai,llm,middleware,metering,revenium,openai,anthropic,google,ollama,litellm,perplexity
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: revenium_metering>=6.8.2
+Provides-Extra: openai
+Requires-Dist: wrapt; extra == "openai"
+Requires-Dist: openai>=1.0.0; extra == "openai"
+Requires-Dist: python-dotenv>=0.19.0; extra == "openai"
+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: perplexity
+Requires-Dist: wrapt; extra == "perplexity"
+Requires-Dist: python-dotenv>=0.19.0; extra == "perplexity"
+Provides-Extra: perplexity-openai
+Requires-Dist: wrapt; extra == "perplexity-openai"
+Requires-Dist: openai>=1.0.0; extra == "perplexity-openai"
+Requires-Dist: python-dotenv>=0.19.0; extra == "perplexity-openai"
+Provides-Extra: perplexity-native
+Requires-Dist: wrapt; extra == "perplexity-native"
+Requires-Dist: perplexityai>=0.1.0; extra == "perplexity-native"
+Requires-Dist: python-dotenv>=0.19.0; extra == "perplexity-native"
+Provides-Extra: google
+Requires-Dist: wrapt; extra == "google"
+Provides-Extra: google-genai
+Requires-Dist: wrapt; extra == "google-genai"
+Requires-Dist: google-genai>=0.1.0; extra == "google-genai"
+Requires-Dist: python-dotenv; extra == "google-genai"
+Provides-Extra: google-vertex
+Requires-Dist: wrapt; extra == "google-vertex"
+Requires-Dist: vertexai>=1.0.0; extra == "google-vertex"
+Requires-Dist: python-dotenv; extra == "google-vertex"
+Provides-Extra: anthropic
+Requires-Dist: wrapt; extra == "anthropic"
+Requires-Dist: anthropic; extra == "anthropic"
+Requires-Dist: python-dotenv>=0.19.0; extra == "anthropic"
+Provides-Extra: ollama
+Requires-Dist: wrapt; extra == "ollama"
+Requires-Dist: ollama; extra == "ollama"
+Provides-Extra: litellm
+Requires-Dist: wrapt; extra == "litellm"
+Requires-Dist: litellm; extra == "litellm"
+Provides-Extra: litellm-proxy
+Requires-Dist: wrapt; extra == "litellm-proxy"
+Requires-Dist: litellm[proxy]; extra == "litellm-proxy"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: freezegun; extra == "dev"
+Requires-Dist: openai-responses>=0.12.0; extra == "dev"
+Requires-Dist: requests; extra == "dev"
+Requires-Dist: wrapt; extra == "dev"
+Requires-Dist: python-dotenv>=0.19.0; extra == "dev"
+Requires-Dist: anthropic; extra == "dev"
+Requires-Dist: boto3; extra == "dev"
+Requires-Dist: ollama; extra == "dev"
+Dynamic: license-file
+
+# Revenium Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/revenium-python-sdk.svg)](https://pypi.org/project/revenium-python-sdk/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/revenium-python-sdk.svg)](https://pypi.org/project/revenium-python-sdk/)
+[![Documentation](https://img.shields.io/badge/docs-revenium.io-blue)](https://docs.revenium.io)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+The official Revenium Python SDK — unified AI metering middleware for deeply attributed AI usage metrics. Supports OpenAI, Anthropic, Google (Gemini/Vertex AI), Ollama, LiteLLM, and Perplexity.
+
+## Features
+
+- **Unified SDK**: Single package with middleware for all major AI providers
+- **Asynchronous Processing**: Background thread management for non-blocking metering operations
+- **Graceful Shutdown**: Ensures all metering data is properly sent even during application shutdown
+- **Decorator Support**: `@revenium_meter` and `@revenium_metadata` for easy integration
+- **Tool Metering**: Meter arbitrary tool/function calls alongside LLM API metering
+
+## Supported Providers
+
+| Provider | Extra | Install Command |
+|----------|-------|----------------|
+| OpenAI | `openai` | `pip install revenium-python-sdk[openai]` |
+| Anthropic | `anthropic` | `pip install revenium-python-sdk[anthropic]` |
+| Google Gemini | `google-genai` | `pip install revenium-python-sdk[google-genai]` |
+| Google Vertex AI | `google-vertex` | `pip install revenium-python-sdk[google-vertex]` |
+| Ollama | `ollama` | `pip install revenium-python-sdk[ollama]` |
+| LiteLLM | `litellm` | `pip install revenium-python-sdk[litellm]` |
+| LiteLLM Proxy | `litellm-proxy` | `pip install revenium-python-sdk[litellm-proxy]` |
+| Perplexity (OpenAI) | `perplexity-openai` | `pip install revenium-python-sdk[perplexity-openai]` |
+| Perplexity (Native) | `perplexity-native` | `pip install revenium-python-sdk[perplexity-native]` |
+| LangChain | `langchain` | `pip install revenium-python-sdk[langchain]` |
+
+## Installation
+
+```bash
+# Core SDK
+pip install revenium-python-sdk
+
+# With a specific provider
+pip install revenium-python-sdk[openai]
+
+# Multiple providers
+pip install revenium-python-sdk[openai,anthropic,ollama]
+```
+
+## Quick Start
+
+```python
+from revenium_middleware import client, run_async_in_thread, shutdown_event
+
+# Record usage directly
+client.record_usage(
+    model="gpt-4o",
+    prompt_tokens=500,
+    completion_tokens=200,
+    user_id="user123",
+    session_id="session456"
+)
+
+# Run async metering tasks in background threads
+async def async_metering_task():
+    await client.async_record_usage(
+        model="gpt-3.5-turbo",
+        prompt_tokens=300,
+        completion_tokens=150,
+        user_id="user789"
+    )
+
+thread = run_async_in_thread(async_metering_task())
+
+# Application continues while metering happens in background
+```
+
+## Provider-Specific Usage
+
+Each provider has its own middleware module. See the `examples/` directory for detailed usage:
+
+- `examples/openai/` — OpenAI and Azure OpenAI examples
+- `examples/anthropic/` — Anthropic and Bedrock examples
+- `examples/google/` — Google AI and Vertex AI examples
+- `examples/ollama/` — Ollama examples
+- `examples/litellm/` — LiteLLM client and proxy examples
+- `examples/perplexity/` — Perplexity examples
+
+## Tool Metering
+
+The `meter_tool` decorator lets you meter arbitrary tool/function calls (web scrapers, image generators, database lookups, etc.) alongside your LLM API metering. This is available via `revenium_metering` v6.8.2+.
+
+```python
+from revenium_middleware import meter_tool, configure
+
+# Configure the metering client
+configure(
+    metering_url="https://api.revenium.io/meter",
+    api_key="your-api-key",
+)
+
+# Decorate any tool function to automatically meter it
+@meter_tool("my-web-scraper", operation="scrape")
+def scrape_website(url):
+    # Your scraping logic here
+    return {"pages": 5, "data_mb": 2.3}
+
+# The decorator captures timing, success/failure, and reports to Revenium
+result = scrape_website("https://example.com")
+```
+
+You can also report tool calls manually:
+
+```python
+from revenium_middleware import report_tool_call
+
+report_tool_call(
+    tool_id="my-tool",
+    operation="fetch",
+    duration_ms=1234,
+    success=True,
+    usage_metadata={"records": 42},
+)
+```
+
+## Compatibility
+
+- Python 3.8+
+- Compatible with all supported AI providers
+
+## Logging
+
+This module uses Python's standard logging system. You can control the log level by setting the `REVENIUM_LOG_LEVEL` environment variable:
+
+```bash
+# Enable debug logging
+export REVENIUM_LOG_LEVEL=DEBUG
+
+# Or when running your script
+REVENIUM_LOG_LEVEL=DEBUG python your_script.py
+```
+
+Available log levels:
+- `DEBUG`: Detailed debugging information
+- `INFO`: General information (default)
+- `WARNING`: Warning messages only
+- `ERROR`: Error messages only
+- `CRITICAL`: Critical error messages only
+
+## Documentation
+
+For detailed documentation, visit [docs.revenium.io](https://docs.revenium.io)
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md)
+
+## Code of Conduct
+
+See [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)
+
+## Security
+
+See [SECURITY.md](./SECURITY.md)
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
+
+## Acknowledgments
+
+- Built by the Revenium team