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

revenium_middleware/openai/azure_config.py

@@ -0,0 +1,169 @@
+"""
+Azure OpenAI configuration management.
+
+This module handles Azure-specific environment variables and configuration
+according to F2 requirements. Configuration is loaded lazily only when
+Azure mode is detected to avoid performance impact for non-Azure users.
+"""
+
+import os
+import logging
+from typing import Optional, Dict, Any
+
+logger = logging.getLogger("revenium_middleware.extension")
+
+
+class AzureConfig:
+    """
+    Azure OpenAI configuration manager.
+    
+    Handles Azure-specific environment variables and provides
+    configuration validation and header generation.
+    """
+    
+    def __init__(self):
+        """Initialize Azure configuration from environment variables."""
+        self.endpoint = os.environ.get('AZURE_OPENAI_ENDPOINT')
+        self.deployment = os.environ.get('AZURE_OPENAI_DEPLOYMENT')
+        self.api_version = os.environ.get('AZURE_OPENAI_API_VERSION', '2024-10-21')
+        self.api_key = os.environ.get('AZURE_OPENAI_API_KEY')
+        
+        # Future AAD support
+        self.tenant_id = os.environ.get('AZURE_OPENAI_TENANT_ID')
+        self.resource_group = os.environ.get('AZURE_OPENAI_RESOURCE_GROUP')
+        
+        logger.debug(f"Azure config initialized - endpoint: {self.endpoint}, "
+                    f"deployment: {self.deployment}, api_version: {self.api_version}")
+    
+    def is_valid(self) -> bool:
+        """
+        Check if the minimum required configuration is present.
+        
+        Returns:
+            True if configuration is valid for Azure OpenAI usage
+        """
+        # Minimum requirement is endpoint
+        is_valid = bool(self.endpoint)
+        
+        if not is_valid:
+            logger.debug("Azure config invalid - missing AZURE_OPENAI_ENDPOINT")
+        
+        return is_valid
+    
+    def get_headers(self, api_key: Optional[str] = None) -> Dict[str, str]:
+        """
+        Generate appropriate headers for Azure OpenAI requests.
+        
+        Args:
+            api_key: Optional API key override
+            
+        Returns:
+            Dictionary of headers for Azure OpenAI requests
+        """
+        headers = {}
+        
+        # Use provided key or fall back to config
+        key_to_use = api_key or self.api_key
+        
+        if key_to_use:
+            # Azure OpenAI uses 'api-key' header instead of 'Authorization'
+            headers['api-key'] = key_to_use
+            logger.debug("Added api-key header for Azure authentication")
+        else:
+            logger.warning("No API key available for Azure OpenAI authentication")
+        
+        return headers
+    
+    def get_base_url(self) -> Optional[str]:
+        """
+        Get the base URL for Azure OpenAI API calls.
+        
+        Returns:
+            Base URL or None if not configured
+        """
+        if self.endpoint:
+            # Ensure endpoint ends with /openai for API calls
+            base_url = self.endpoint.rstrip('/')
+            if not base_url.endswith('/openai'):
+                base_url += '/openai'
+            return base_url
+        return None
+    
+    def get_deployment_url(self, endpoint_path: str) -> Optional[str]:
+        """
+        Construct full deployment URL for Azure OpenAI API calls.
+        
+        Args:
+            endpoint_path: API endpoint path (e.g., '/chat/completions')
+            
+        Returns:
+            Full URL with deployment and API version
+        """
+        if not self.is_valid() or not self.deployment:
+            return None
+        
+        base_url = self.get_base_url()
+        if not base_url:
+            return None
+        
+        # Construct: https://resource.openai.azure.com/openai/deployments/{deployment}/chat/completions?api-version=2024-10-21
+        url = f"{base_url}/deployments/{self.deployment}{endpoint_path}?api-version={self.api_version}"
+        logger.debug(f"Constructed Azure deployment URL: {url}")
+        return url
+    
+    def validate_deployment(self) -> bool:
+        """
+        Validate that deployment name is configured.
+        
+        Returns:
+            True if deployment is configured
+        """
+        if not self.deployment:
+            logger.warning("AZURE_OPENAI_DEPLOYMENT not configured - this may cause API calls to fail")
+            return False
+        return True
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert configuration to dictionary (excluding sensitive data).
+        
+        Returns:
+            Configuration dictionary for logging/debugging
+        """
+        return {
+            'endpoint': self.endpoint,
+            'deployment': self.deployment,
+            'api_version': self.api_version,
+            'tenant_id': self.tenant_id,
+            'resource_group': self.resource_group,
+            'has_api_key': bool(self.api_key),
+            'is_valid': self.is_valid()
+        }
+
+
+# Global configuration instance - lazy loaded
+_azure_config: Optional[AzureConfig] = None
+
+
+def get_azure_config() -> AzureConfig:
+    """
+    Get or create Azure configuration instance.
+    
+    Lazy loading ensures non-Azure users don't pay any performance cost.
+    
+    Returns:
+        AzureConfig instance
+    """
+    global _azure_config
+    
+    if _azure_config is None:
+        _azure_config = AzureConfig()
+        logger.debug("Azure configuration loaded")
+    
+    return _azure_config
+
+
+def reset_azure_config():
+    """Reset Azure configuration cache. Useful for testing."""
+    global _azure_config
+    _azure_config = None

revenium_middleware/openai/azure_model_resolver.py

@@ -0,0 +1,219 @@
+"""
+Azure OpenAI model name resolution.
+
+This module maps Azure deployment names to LiteLLM-compatible model names
+for accurate pricing. Uses heuristic pattern matching with optional API fallback.
+
+The resolution is fire-and-forget - failures cannot break primary AI calls.
+"""
+
+import logging
+import threading
+import time
+from typing import Optional, Dict, Any
+import re
+
+from .config import Config
+from .exceptions import ModelResolutionError, handle_exception_safely
+
+logger = logging.getLogger("revenium_middleware.extension")
+
+# Global model name cache - deployment_name -> litellm_model_name
+_azure_model_cache: Dict[str, str] = {}
+_cache_lock = threading.Lock()
+
+
+def resolve_azure_model_name(deployment_name: str, base_url: Optional[str] = None, 
+                           headers: Optional[Dict[str, str]] = None, 
+                           use_api_fallback: bool = True) -> str:
+    """
+    Resolve Azure deployment name to LiteLLM-compatible model name.
+    
+    This function is fire-and-forget - it will never raise exceptions that
+    could break the primary AI call.
+    
+    Args:
+        deployment_name: Azure deployment name from API response
+        base_url: Azure endpoint URL (for API fallback)
+        headers: Request headers (for API fallback) 
+        use_api_fallback: Whether to attempt API resolution after heuristics
+        
+    Returns:
+        LiteLLM model name or original deployment_name if no match found
+    """
+    logger.debug(f"Resolving Azure model name for deployment: {deployment_name}")
+    
+    try:
+        # 1. Check in-memory cache first
+        with _cache_lock:
+            if deployment_name in _azure_model_cache:
+                cached_name = _azure_model_cache[deployment_name]
+                logger.debug(f"Found cached mapping: {deployment_name} -> {cached_name}")
+                return cached_name
+        
+        # 2. Try heuristic matching first (fast, reliable for common cases)
+        heuristic_name = _heuristic_model_mapping(deployment_name)
+        if heuristic_name:
+            logger.debug(f"Heuristic mapping successful: {deployment_name} -> {heuristic_name}")
+            with _cache_lock:
+                _azure_model_cache[deployment_name] = heuristic_name
+            return heuristic_name
+        
+        # 3. Log warning - heuristics failed
+        logger.warning(f"No heuristic match found for Azure deployment '{deployment_name}'. "
+                      f"This may result in pricing lookup failures on Revenium backend.")
+        
+        # 4. Try Azure API fallback if enabled
+        if use_api_fallback and base_url and headers:
+            logger.debug(f"Attempting Azure API resolution for deployment: {deployment_name}")
+            _async_resolve_model_name(deployment_name, base_url, headers)
+        
+        # 5. Return deployment name as fallback
+        logger.warning(f"Using deployment name '{deployment_name}' as model name. "
+                      f"Verify this matches LiteLLM pricing tables to ensure accurate cost calculation.")
+        return deployment_name
+        
+    except Exception as e:
+        # CRITICAL: Never let this break the main AI call
+        logger.warning(f"Azure model resolution failed for '{deployment_name}': {str(e)}. "
+                      f"Using deployment name as fallback.")
+        return deployment_name
+
+
+def _heuristic_model_mapping(deployment_name: str) -> Optional[str]:
+    """
+    Fast pattern matching for common Azure deployment naming patterns.
+    
+    Based on LiteLLM model names: azure_ai/gpt-4, azure_ai/gpt-35-turbo, etc.
+    
+    Args:
+        deployment_name: Azure deployment name
+        
+    Returns:
+        LiteLLM model name if pattern matched, None otherwise
+    """
+    # Normalize deployment name for pattern matching
+    name_lower = deployment_name.lower().replace('_', '-').replace('.', '-')
+    
+    # GPT-4o family patterns (highest priority - newest models)
+    if re.search(r'gpt-?4o', name_lower) or re.search(r'o4', name_lower):
+        if 'mini' in name_lower:
+            return 'gpt-4o-mini'
+        return 'gpt-4o'
+    
+    # GPT-4 family patterns
+    if re.search(r'gpt-?4', name_lower):
+        # Check for specific variants first
+        if any(variant in name_lower for variant in ['turbo', '1106', '0125', '0613']):
+            return 'gpt-4-turbo'
+        if any(variant in name_lower for variant in ['vision', 'v', 'preview']):
+            return 'gpt-4-vision-preview'
+        if '32k' in name_lower:
+            return 'gpt-4-32k'
+        # Default GPT-4
+        return 'gpt-4'
+    
+    # GPT-3.5 family patterns  
+    if any(pattern in name_lower for pattern in ['gpt-35', 'gpt-3-5', 'gpt3-5', 'gpt35']):
+        if '16k' in name_lower:
+            return 'gpt-3.5-turbo-16k'
+        if 'instruct' in name_lower:
+            return 'gpt-3.5-turbo-instruct'
+        return 'gpt-3.5-turbo'
+    
+    # Embedding model patterns
+    if 'embedding' in name_lower or 'embed' in name_lower:
+        if 'ada-002' in name_lower or 'ada002' in name_lower:
+            return 'text-embedding-ada-002'
+        if '3-large' in name_lower or 'large' in name_lower:
+            return 'text-embedding-3-large'
+        if '3-small' in name_lower or 'small' in name_lower:
+            return 'text-embedding-3-small'
+    
+    # DALL-E patterns
+    if 'dall' in name_lower or 'dalle' in name_lower:
+        if '3' in name_lower:
+            return 'dall-e-3'
+        if '2' in name_lower:
+            return 'dall-e-2'
+    
+    # Whisper patterns
+    if 'whisper' in name_lower:
+        return 'whisper-1'
+    
+    # TTS patterns
+    if 'tts' in name_lower:
+        if 'hd' in name_lower:
+            return 'tts-1-hd'
+        return 'tts-1'
+    
+    # No pattern matched
+    logger.debug(f"No heuristic pattern matched for deployment: {deployment_name}")
+    return None
+
+
+def _async_resolve_model_name(deployment_name: str, base_url: str, headers: Dict[str, str]):
+    """
+    Background Azure API resolution - never blocks main thread.
+    Updates cache if successful, silent failure otherwise.
+    
+    Args:
+        deployment_name: Azure deployment name
+        base_url: Azure endpoint URL
+        headers: Request headers for authentication
+    """
+    def background_resolve():
+        try:
+            # Import here to avoid dependency issues for non-Azure users
+            import requests
+            
+            # Construct Azure model info endpoint
+            # Format: https://resource.openai.azure.com/openai/deployments/{deployment}?api-version=2024-10-21
+            api_url = f"{base_url.rstrip('/')}/openai/deployments/{deployment_name}?api-version={Config.AZURE_API_VERSION_DEFAULT}"
+            
+            logger.debug(f"Attempting Azure API model resolution: {api_url}")
+            
+            # Make API call with timeout
+            response = requests.get(api_url, headers=headers, timeout=Config.AZURE_MODEL_RESOLUTION_TIMEOUT)
+            
+            if response.status_code == 200:
+                model_info = response.json()
+                actual_model = model_info.get('id', deployment_name)
+                
+                # Update cache
+                with _cache_lock:
+                    _azure_model_cache[deployment_name] = actual_model
+                
+                logger.debug(f"Azure API resolved: {deployment_name} -> {actual_model}")
+            else:
+                logger.debug(f"Azure API resolution failed for {deployment_name}: HTTP {response.status_code}")
+                
+        except Exception as e:
+            # Silent failure - heuristic result already used
+            logger.debug(f"Background Azure API resolution failed for {deployment_name}: {str(e)}")
+    
+    # Fire and forget - daemon thread won't block shutdown
+    thread = threading.Thread(target=background_resolve, daemon=True)
+    thread.start()
+
+
+def get_model_cache_stats() -> Dict[str, Any]:
+    """
+    Get statistics about the model name cache.
+    
+    Returns:
+        Dictionary with cache statistics
+    """
+    with _cache_lock:
+        return {
+            'cache_size': len(_azure_model_cache),
+            'cached_models': dict(_azure_model_cache),
+            'cache_hit_rate': 'N/A'  # Could be implemented with counters
+        }
+
+
+def clear_model_cache():
+    """Clear the model name cache. Useful for testing."""
+    with _cache_lock:
+        _azure_model_cache.clear()
+    logger.debug("Azure model cache cleared")

revenium_middleware/openai/config.py

@@ -0,0 +1,45 @@
+"""
+Configuration for Revenium OpenAI middleware.
+
+Extends shared core config with OpenAI and Azure-specific settings.
+"""
+
+from revenium_middleware._core.config import (  # noqa: F401
+    Config as _CoreConfig,
+    SecurityConfig,
+    SummaryFormat,
+    get_config_value,
+    is_debug_enabled,
+    get_timeout_config as _core_get_timeout_config,
+    parse_print_summary_value,
+    get_print_summary_config,
+    get_team_id,
+    get_base_url,
+)
+
+
+class Config(_CoreConfig):
+    """OpenAI-specific configuration extending core config."""
+
+    # Azure API settings
+    AZURE_API_VERSION_DEFAULT: str = "2024-10-21"
+    AZURE_MODEL_RESOLUTION_TIMEOUT: float = 5.0
+
+    # Provider-specific environment variables
+    ENV_OPENAI_API_KEY: str = "OPENAI_API_KEY"
+    ENV_AZURE_OPENAI_ENDPOINT: str = "AZURE_OPENAI_ENDPOINT"
+    ENV_AZURE_OPENAI_API_KEY: str = "AZURE_OPENAI_API_KEY"
+
+    # Region environment variables
+    ENV_AWS_REGION: str = "AWS_REGION"
+    ENV_AWS_DEFAULT_REGION: str = "AWS_DEFAULT_REGION"
+    ENV_AZURE_REGION: str = "AZURE_REGION"
+    ENV_GCP_REGION: str = "GCP_REGION"
+    ENV_GOOGLE_CLOUD_REGION: str = "GOOGLE_CLOUD_REGION"
+
+
+def get_timeout_config() -> dict:
+    """Get all timeout-related configuration, including Azure."""
+    config = _core_get_timeout_config()
+    config['azure_model_resolution'] = Config.AZURE_MODEL_RESOLUTION_TIMEOUT
+    return config

revenium_middleware/openai/exceptions.py

@@ -0,0 +1,115 @@
+"""
+Custom exceptions for Revenium middleware.
+
+This module defines a hierarchy of exceptions that provide better error handling
+and more specific error information for different failure scenarios.
+"""
+
+
+class ReveniumMiddlewareError(Exception):
+    """Base exception for all Revenium middleware errors."""
+
+    def __init__(self, message: str, original_error: Exception = None):
+        super().__init__(message)
+        self.original_error = original_error
+        self.message = message
+
+    def __str__(self):
+        if self.original_error:
+            return f"{self.message} (caused by: {self.original_error})"
+        return self.message
+
+
+class ConfigurationError(ReveniumMiddlewareError):
+    """Raised when there are configuration-related issues."""
+    pass
+
+
+class ValidationError(ReveniumMiddlewareError):
+    """Raised when input validation fails."""
+    pass
+
+
+class ProviderDetectionError(ReveniumMiddlewareError):
+    """Raised when provider detection fails."""
+    pass
+
+
+class MeteringError(ReveniumMiddlewareError):
+    """Raised when metering operations fail."""
+    pass
+
+
+class NetworkError(ReveniumMiddlewareError):
+    """Raised when network operations fail."""
+    pass
+
+
+class AuthenticationError(ReveniumMiddlewareError):
+    """Raised when authentication fails."""
+    pass
+
+
+class StreamingError(ReveniumMiddlewareError):
+    """Raised when streaming operations fail."""
+    pass
+
+
+class ModelResolutionError(ReveniumMiddlewareError):
+    """Raised when Azure model name resolution fails."""
+    pass
+
+
+def handle_exception_safely(func):
+    """
+    Decorator to handle exceptions safely without breaking the main application flow.
+
+    This decorator ensures that middleware errors never propagate to break
+    the user's application, following the principle of graceful degradation.
+    """
+    def wrapper(*args, **kwargs):
+        try:
+            return func(*args, **kwargs)
+        except ReveniumMiddlewareError as e:
+            # Log middleware-specific errors
+            import logging
+            logger = logging.getLogger("revenium_middleware.extension")
+            logger.error(f"Revenium middleware error in {func.__name__}: {e}")
+            return None
+        except Exception as e:
+            # Log unexpected errors
+            import logging
+            logger = logging.getLogger("revenium_middleware.extension")
+            logger.error(f"Unexpected error in {func.__name__}: {e}", exc_info=True)
+            return None
+
+    return wrapper
+
+
+def categorize_exception(exception: Exception) -> ReveniumMiddlewareError:
+    """
+    Categorize a generic exception into a more specific Revenium middleware exception.
+
+    Args:
+        exception: The original exception to categorize
+
+    Returns:
+        A more specific ReveniumMiddlewareError subclass
+    """
+    error_message = str(exception)
+    error_type = type(exception).__name__
+
+    # Network-related errors
+    if any(keyword in error_message.lower() for keyword in ['connection', 'timeout', 'network', 'dns']):
+        return NetworkError(f"Network error: {error_message}", exception)
+
+    # Authentication errors
+    if any(keyword in error_message.lower() for keyword in ['auth', 'unauthorized', 'forbidden', 'api key']):
+        return AuthenticationError(f"Authentication error: {error_message}", exception)
+
+    # Validation errors
+    if any(keyword in error_type.lower() for keyword in ['value', 'type', 'attribute']):
+        return ValidationError(f"Validation error: {error_message}", exception)
+
+    # Default to generic middleware error
+    return ReveniumMiddlewareError(f"Middleware error ({error_type}): {error_message}", exception)

revenium_middleware/openai/langchain/__init__.py

@@ -0,0 +1,114 @@
+"""
+LangChain integration for Revenium middleware OpenAI.
+
+This module provides zero-touch integration with LangChain applications through
+callback handlers that automatically track usage and costs.
+
+Usage:
+    from revenium_middleware.openai.langchain import wrap
+    from langchain_openai import ChatOpenAI
+    
+    llm = wrap(ChatOpenAI(model="gpt-4o-mini"))
+    response = llm.invoke("Hello Revenium!")
+
+Installation:
+    pip install revenium-python-sdk[openai,langchain]
+"""
+
+from typing import Any, TYPE_CHECKING
+
+# Only import types during type checking to avoid runtime dependencies
+if TYPE_CHECKING:
+    try:
+        # LangChain 1.0+ uses langchain_core
+        from langchain_core.language_models import BaseLanguageModel  # noqa: F401
+        from langchain_core.embeddings import Embeddings  # noqa: F401
+    except ImportError:
+        # LangChain 0.x uses langchain.schema and langchain.embeddings.base
+        from langchain.schema import BaseLanguageModel  # noqa: F401
+        from langchain.embeddings.base import Embeddings  # noqa: F401
+
+# Import our enhanced dependency checking utilities
+from ._utils import require_langchain_or_raise, is_langchain_available  # noqa: F401
+
+
+# Lazy loading implementation using __getattr__
+def __getattr__(name: str) -> Any:
+    """
+    Implement lazy loading for LangChain-dependent functionality.
+
+    This allows the module to be imported without LangChain installed,
+    but raises clear errors when trying to use LangChain-specific features.
+    """
+    if name in ("wrap", "attach_to"):
+        require_langchain_or_raise(f"the {name}() function")
+        # Import the unified handler and create wrapper functions
+        from .unified_handler import UnifiedReveniumCallbackHandler  # noqa: F401
+
+        def wrap(llm, **kwargs):
+            """Wrap a LangChain LLM with Revenium usage tracking."""
+            handler = UnifiedReveniumCallbackHandler(**kwargs)
+
+            # Attach handler to LLM
+            if hasattr(llm, 'callbacks'):
+                if llm.callbacks is None:
+                    llm.callbacks = [handler]
+                elif isinstance(llm.callbacks, list):
+                    llm.callbacks.append(handler)
+                else:
+                    # Convert to list if it's something else
+                    llm.callbacks = [llm.callbacks, handler]
+            else:
+                # Try to add callbacks attribute
+                try:
+                    llm.callbacks = [handler]
+                except Exception:
+                    # Some models don't support callbacks
+                    pass
+
+            return llm
+
+        def attach_to(llm, **kwargs):
+            """Attach Revenium usage tracking to an existing LangChain LLM in-place."""
+            return wrap(llm, **kwargs)
+
+        # Cache the functions in the module namespace
+        if name == "wrap":
+            globals()[name] = wrap
+            return wrap
+        else:  # attach_to
+            globals()[name] = attach_to
+            return attach_to
+
+    elif name in ("ReveniumCallbackHandler", "UnifiedReveniumCallbackHandler"):
+        require_langchain_or_raise(f"the {name} class")
+        from .unified_handler import UnifiedReveniumCallbackHandler  # noqa: F401
+
+        # Both names point to the same unified handler
+        globals()["ReveniumCallbackHandler"] = UnifiedReveniumCallbackHandler
+        globals()["UnifiedReveniumCallbackHandler"] = UnifiedReveniumCallbackHandler
+
+        return UnifiedReveniumCallbackHandler
+
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
+
+# Convenience function for checking availability
+def check_availability() -> bool:
+    """
+    Check if LangChain is available for use with this integration.
+
+    Returns:
+        True if LangChain is available, False otherwise
+    """
+    return is_langchain_available()
+
+
+# Define __all__ for explicit exports
+__all__ = [
+    "wrap",
+    "attach_to",
+    "ReveniumCallbackHandler",
+    "UnifiedReveniumCallbackHandler",
+    "check_availability",
+]