langfuse-prompt-library-iauro 0.1.0__py3-none-any.whl

utils/utility.py

@@ -0,0 +1,302 @@
+"""
+Utility functions for Langfuse library.
+
+Provides retry logic, caching, and validation utilities.
+"""
+
+import time
+import threading
+from functools import wraps
+from typing import Callable, Any, Optional, TypeVar, Dict, Tuple
+from langfuse_prompt_library.exceptions import APITimeoutError, RateLimitError, ProviderError
+from utils.logger import get_logger
+
+T = TypeVar('T')
+
+logger = get_logger(__name__)
+
+
+def retry_with_backoff(
+    max_retries: int = 3,
+    initial_delay: float = 1.0,
+    backoff_factor: float = 2.0,
+    exceptions: tuple = (Exception,)
+):
+    """Decorator to retry a function with exponential backoff.
+
+    Args:
+        max_retries: Maximum number of retry attempts
+        initial_delay: Initial delay between retries in seconds
+        backoff_factor: Multiplier for delay after each retry
+        exceptions: Tuple of exceptions to catch and retry
+
+    Returns:
+        Decorated function with retry logic
+    """
+    def decorator(func: Callable[..., T]) -> Callable[..., T]:
+        @wraps(func)
+        def wrapper(*args, **kwargs) -> T:
+            delay = initial_delay
+            last_exception = None
+
+            for attempt in range(max_retries + 1):
+                try:
+                    return func(*args, **kwargs)
+                except exceptions as e:
+                    last_exception = e
+
+                    if attempt == max_retries:
+                        logger.error(
+                            f"Max retries ({max_retries}) exceeded for {func.__name__}",
+                            exc_info=True,
+                            attempt=attempt + 1
+                        )
+                        raise
+
+                    # Check for rate limiting
+                    if "rate limit" in str(e).lower():
+                        logger.warning(
+                            f"Rate limit hit, retrying in {delay}s",
+                            function=func.__name__,
+                            attempt=attempt + 1
+                        )
+                    else:
+                        logger.warning(
+                            f"Attempt {attempt + 1} failed, retrying in {delay}s",
+                            function=func.__name__,
+                            error=str(e)
+                        )
+
+                    time.sleep(delay)
+                    delay *= backoff_factor
+
+            if last_exception:
+                raise last_exception
+
+        return wrapper
+    return decorator
+
+
+class ThreadSafeCache:
+    """Thread-safe cache implementation with TTL support."""
+
+    def __init__(self, default_ttl: int = 300):
+        """Initialize cache.
+
+        Args:
+            default_ttl: Default time-to-live in seconds
+        """
+        self._cache: Dict[str, Tuple[Any, float]] = {}
+        self._lock = threading.RLock()
+        self._default_ttl = default_ttl
+        self._hits = 0
+        self._misses = 0
+
+    def get(self, key: str) -> Optional[Any]:
+        """Get value from cache.
+
+        Args:
+            key: Cache key
+
+        Returns:
+            Cached value or None if not found or expired
+        """
+        with self._lock:
+            if key not in self._cache:
+                self._misses += 1
+                return None
+
+            value, timestamp = self._cache[key]
+
+            # Check if expired
+            if time.time() - timestamp > self._default_ttl:
+                del self._cache[key]
+                self._misses += 1
+                return None
+
+            self._hits += 1
+            return value
+
+    def set(self, key: str, value: Any, ttl: Optional[int] = None) -> None:
+        """Set value in cache.
+
+        Args:
+            key: Cache key
+            value: Value to cache
+            ttl: Optional custom TTL (uses default if None)
+        """
+        with self._lock:
+            # Use custom TTL if provided, otherwise use default
+            if ttl is not None:
+                # Store with custom timestamp calculation
+                self._cache[key] = (value, time.time())
+            else:
+                self._cache[key] = (value, time.time())
+
+    def delete(self, key: str) -> bool:
+        """Delete key from cache.
+
+        Args:
+            key: Cache key
+
+        Returns:
+            True if key was deleted, False if not found
+        """
+        with self._lock:
+            if key in self._cache:
+                del self._cache[key]
+                return True
+            return False
+
+    def clear(self) -> None:
+        """Clear all cached items."""
+        with self._lock:
+            self._cache.clear()
+            self._hits = 0
+            self._misses = 0
+
+    def get_stats(self) -> Dict[str, Any]:
+        """Get cache statistics.
+
+        Returns:
+            Dictionary with cache stats
+        """
+        with self._lock:
+            total_requests = self._hits + self._misses
+            hit_rate = (self._hits / total_requests * 100) if total_requests > 0 else 0
+
+            return {
+                "size": len(self._cache),
+                "hits": self._hits,
+                "misses": self._misses,
+                "hit_rate": f"{hit_rate:.2f}%"
+            }
+
+    def cleanup_expired(self) -> int:
+        """Remove expired entries from cache.
+
+        Returns:
+            Number of entries removed
+        """
+        with self._lock:
+            current_time = time.time()
+            expired_keys = [
+                key for key, (_, timestamp) in self._cache.items()
+                if current_time - timestamp > self._default_ttl
+            ]
+
+            for key in expired_keys:
+                del self._cache[key]
+
+            if expired_keys:
+                logger.debug(f"Cleaned up {len(expired_keys)} expired cache entries")
+
+            return len(expired_keys)
+
+
+def validate_prompt_name(name: str) -> None:
+    """Validate prompt name.
+
+    Args:
+        name: Prompt name to validate
+
+    Raises:
+        ValidationError: If name is invalid
+    """
+    from langfuse_prompt_library.exceptions import ValidationError
+
+    if not name:
+        raise ValidationError("prompt_name", "Prompt name cannot be empty")
+
+    if not isinstance(name, str):
+        raise ValidationError("prompt_name", f"Prompt name must be string, got {type(name)}")
+
+    if len(name) > 255:
+        raise ValidationError("prompt_name", "Prompt name too long (max 255 characters)")
+
+
+def validate_model_name(model: str) -> None:
+    """Validate model name.
+
+    Args:
+        model: Model name to validate
+
+    Raises:
+        ValidationError: If model name is invalid
+    """
+    from langfuse_prompt_library.exceptions import ValidationError
+
+    if not model:
+        raise ValidationError("model", "Model name cannot be empty")
+
+    if not isinstance(model, str):
+        raise ValidationError("model", f"Model name must be string, got {type(model)}")
+
+
+def validate_temperature(temperature: float) -> None:
+    """Validate temperature parameter.
+
+    Args:
+        temperature: Temperature value to validate
+
+    Raises:
+        ValidationError: If temperature is invalid
+    """
+    from langfuse_prompt_library.exceptions import ValidationError
+
+    if not isinstance(temperature, (int, float)):
+        raise ValidationError("temperature", f"Temperature must be numeric, got {type(temperature)}")
+
+    if temperature < 0 or temperature > 2:
+        raise ValidationError("temperature", "Temperature must be between 0 and 2")
+
+
+def validate_max_tokens(max_tokens: int) -> None:
+    """Validate max_tokens parameter.
+
+    Args:
+        max_tokens: Max tokens value to validate
+
+    Raises:
+        ValidationError: If max_tokens is invalid
+    """
+    from langfuse_prompt_library.exceptions import ValidationError
+
+    if not isinstance(max_tokens, int):
+        raise ValidationError("max_tokens", f"max_tokens must be integer, got {type(max_tokens)}")
+
+    if max_tokens <= 0:
+        raise ValidationError("max_tokens", "max_tokens must be positive")
+
+    if max_tokens > 1000000:
+        raise ValidationError("max_tokens", "max_tokens exceeds reasonable limit (1M)")
+
+
+def sanitize_user_input(user_input: str, max_length: int = 50000) -> str:
+    """Sanitize user input.
+
+    Args:
+        user_input: User input to sanitize
+        max_length: Maximum allowed length
+
+    Returns:
+        Sanitized input
+
+    Raises:
+        ValidationError: If input is invalid
+    """
+    from langfuse_prompt_library.exceptions import ValidationError
+
+    if not isinstance(user_input, str):
+        raise ValidationError("user_input", f"Input must be string, got {type(user_input)}")
+
+    if len(user_input) > max_length:
+        raise ValidationError("user_input", f"Input exceeds max length ({max_length})")
+
+    # Strip leading/trailing whitespace
+    sanitized = user_input.strip()
+
+    if not sanitized:
+        raise ValidationError("user_input", "Input cannot be empty after sanitization")
+
+    return sanitized