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

langfuse_prompt_library/__init__.py

@@ -0,0 +1,54 @@
+"""
+Langfuse Library - A production-ready wrapper for Langfuse prompts and tracing.
+
+This library provides a robust, enterprise-grade interface for:
+- Fetching and managing prompts from Langfuse with caching
+- Calling LLMs with automatic tracing and retry logic
+- Token tracking and observability
+- Error handling and validation
+- Performance metrics
+
+Example:
+    >>> from langfuse_prompt_library import LangfuseManager
+    >>>
+    >>> lf = LangfuseManager()
+    >>> response = lf.call_llm(
+    ...     prompt_name="customer_support_agent",
+    ...     user_input="How do I reset my password?",
+    ...     prompt_label="production"
+    ... )
+    >>> print(response.content)
+"""
+
+from .manager import LangfuseManager
+from .models import LLMResponse
+from .config import LangfuseConfig
+from utils.logger import get_logger
+from .exceptions import (
+    LangfuseLibraryError,
+    ConfigurationError,
+    PromptNotFoundError,
+    ProviderError,
+    APITimeoutError,
+    RateLimitError,
+    CacheError,
+    ValidationError,
+    TracingError
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "LangfuseManager",
+    "LLMResponse",
+    "LangfuseConfig",
+    "get_logger",
+    "LangfuseLibraryError",
+    "ConfigurationError",
+    "PromptNotFoundError",
+    "ProviderError",
+    "APITimeoutError",
+    "RateLimitError",
+    "CacheError",
+    "ValidationError",
+    "TracingError"
+]

langfuse_prompt_library/config.py

@@ -0,0 +1,153 @@
+"""
+Configuration management for Langfuse library.
+"""
+
+import os
+import logging
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class LangfuseConfig:
+    """Configuration for Langfuse client.
+
+    Attributes:
+        secret_key: Langfuse secret key (required)
+        public_key: Langfuse public key (required)
+        host: Langfuse host URL (required)
+        openai_api_key: OpenAI API key (optional)
+        anthropic_api_key: Anthropic API key (optional)
+        enable_caching: Enable prompt caching (default: True)
+        cache_ttl: Cache time-to-live in seconds (default: 300)
+        debug: Enable debug logging (default: False)
+        log_level: Logging level (default: INFO)
+        request_timeout: Default timeout for API requests in seconds (default: 30)
+        max_retries: Maximum number of retries for failed API calls (default: 3)
+        retry_delay: Initial delay between retries in seconds (default: 1)
+        enable_metrics: Enable performance metrics collection (default: False)
+        flush_at_shutdown: Automatically flush traces at shutdown (default: True)
+        connection_pool_size: Max connections in pool (default: 10)
+        validate_prompts: Validate prompt compilation (default: True)
+    """
+
+    secret_key: Optional[str] = None
+    public_key: Optional[str] = None
+    host: Optional[str] = None
+    openai_api_key: Optional[str] = None
+    anthropic_api_key: Optional[str] = None
+    enable_caching: bool = True
+    cache_ttl: int = 300
+    debug: bool = False
+    log_level: int = logging.INFO
+    request_timeout: float = 30.0
+    max_retries: int = 3
+    retry_delay: float = 1.0
+    enable_metrics: bool = False
+    flush_at_shutdown: bool = True
+    connection_pool_size: int = 10
+    validate_prompts: bool = True
+
+    @classmethod
+    def from_env(cls) -> 'LangfuseConfig':
+        """Load configuration from environment variables.
+
+        Environment variables:
+            LANGFUSE_SECRET_KEY: Langfuse secret key
+            LANGFUSE_PUBLIC_KEY: Langfuse public key
+            LANGFUSE_BASE_URL: Langfuse host URL
+            OPENAI_API_KEY: OpenAI API key (optional)
+            ANTHROPIC_API_KEY: Anthropic API key (optional)
+            LANGFUSE_ENABLE_CACHE: Enable caching (default: "true")
+            LANGFUSE_CACHE_TTL: Cache TTL in seconds (default: "300")
+            LANGFUSE_DEBUG: Enable debug mode (default: "false")
+            LANGFUSE_LOG_LEVEL: Logging level (default: "INFO")
+            LANGFUSE_REQUEST_TIMEOUT: Request timeout in seconds (default: "30")
+            LANGFUSE_MAX_RETRIES: Max retry attempts (default: "3")
+            LANGFUSE_RETRY_DELAY: Initial retry delay in seconds (default: "1")
+            LANGFUSE_ENABLE_METRICS: Enable metrics collection (default: "false")
+            LANGFUSE_FLUSH_AT_SHUTDOWN: Auto-flush at shutdown (default: "true")
+            LANGFUSE_CONNECTION_POOL_SIZE: Connection pool size (default: "10")
+            LANGFUSE_VALIDATE_PROMPTS: Validate prompts (default: "true")
+
+        Returns:
+            LangfuseConfig instance with values from environment
+        """
+        # Parse log level from string
+        log_level_str = os.getenv("LANGFUSE_LOG_LEVEL", "INFO").upper()
+        log_level = getattr(logging, log_level_str, logging.INFO)
+
+        return cls(
+            secret_key=os.getenv("LANGFUSE_SECRET_KEY"),
+            public_key=os.getenv("LANGFUSE_PUBLIC_KEY"),
+            host=os.getenv("LANGFUSE_BASE_URL"),
+            openai_api_key=os.getenv("OPENAI_API_KEY"),
+            anthropic_api_key=os.getenv("ANTHROPIC_API_KEY"),
+            enable_caching=os.getenv("LANGFUSE_ENABLE_CACHE", "true").lower() == "true",
+            cache_ttl=int(os.getenv("LANGFUSE_CACHE_TTL", "300")),
+            debug=os.getenv("LANGFUSE_DEBUG", "false").lower() == "true",
+            log_level=log_level,
+            request_timeout=float(os.getenv("LANGFUSE_REQUEST_TIMEOUT", "30")),
+            max_retries=int(os.getenv("LANGFUSE_MAX_RETRIES", "3")),
+            retry_delay=float(os.getenv("LANGFUSE_RETRY_DELAY", "1")),
+            enable_metrics=os.getenv("LANGFUSE_ENABLE_METRICS", "false").lower() == "true",
+            flush_at_shutdown=os.getenv("LANGFUSE_FLUSH_AT_SHUTDOWN", "true").lower() == "true",
+            connection_pool_size=int(os.getenv("LANGFUSE_CONNECTION_POOL_SIZE", "10")),
+            validate_prompts=os.getenv("LANGFUSE_VALIDATE_PROMPTS", "true").lower() == "true"
+        )
+
+    def validate(self, require_provider: bool = True) -> None:
+        """Validate that all required configuration fields are set.
+
+        Args:
+            require_provider: If True, requires at least one provider API key
+
+        Raises:
+            ValueError: If any required field is missing or invalid
+        """
+        from .exceptions import ConfigurationError
+
+        # Always required: Langfuse keys
+        required_fields = {
+            "secret_key": self.secret_key,
+            "public_key": self.public_key,
+            "host": self.host
+        }
+
+        missing_fields = [
+            field for field, value in required_fields.items()
+            if not value
+        ]
+
+        if missing_fields:
+            raise ConfigurationError(
+                f"Missing required Langfuse configuration: {', '.join(missing_fields)}. "
+                f"Please set the corresponding environment variables."
+            )
+
+        # Validate numeric ranges
+        if self.cache_ttl < 0:
+            raise ConfigurationError("cache_ttl must be non-negative")
+
+        if self.request_timeout <= 0:
+            raise ConfigurationError("request_timeout must be positive")
+
+        if self.max_retries < 0:
+            raise ConfigurationError("max_retries must be non-negative")
+
+        if self.retry_delay < 0:
+            raise ConfigurationError("retry_delay must be non-negative")
+
+        if self.connection_pool_size <= 0:
+            raise ConfigurationError("connection_pool_size must be positive")
+
+        # Check for at least one provider if required
+        if require_provider:
+            has_openai = bool(self.openai_api_key)
+            has_anthropic = bool(self.anthropic_api_key)
+
+            if not (has_openai or has_anthropic):
+                raise ConfigurationError(
+                    "No LLM provider configured. "
+                    "Please set OPENAI_API_KEY or ANTHROPIC_API_KEY environment variable."
+                )

langfuse_prompt_library/exceptions.py

@@ -0,0 +1,95 @@
+"""
+Custom exceptions for Langfuse library.
+
+Provides specific exception types for better error handling and debugging.
+"""
+
+
+class LangfuseLibraryError(Exception):
+    """Base exception for all Langfuse library errors."""
+    pass
+
+
+class ConfigurationError(LangfuseLibraryError):
+    """Raised when configuration is invalid or missing."""
+    pass
+
+
+class PromptNotFoundError(LangfuseLibraryError):
+    """Raised when a requested prompt is not found."""
+
+    def __init__(self, prompt_name: str, version: str = None, label: str = None):
+        self.prompt_name = prompt_name
+        self.version = version
+        self.label = label
+
+        msg = f"Prompt '{prompt_name}' not found"
+        if version:
+            msg += f" (version: {version})"
+        if label:
+            msg += f" (label: {label})"
+
+        super().__init__(msg)
+
+
+class ProviderError(LangfuseLibraryError):
+    """Raised when LLM provider encounters an error."""
+
+    def __init__(self, provider: str, message: str, original_error: Exception = None):
+        self.provider = provider
+        self.original_error = original_error
+
+        msg = f"{provider} provider error: {message}"
+        if original_error:
+            msg += f" | Original error: {str(original_error)}"
+
+        super().__init__(msg)
+
+
+class APITimeoutError(LangfuseLibraryError):
+    """Raised when an API call times out."""
+
+    def __init__(self, operation: str, timeout: float):
+        self.operation = operation
+        self.timeout = timeout
+        super().__init__(f"{operation} timed out after {timeout} seconds")
+
+
+class RateLimitError(LangfuseLibraryError):
+    """Raised when rate limit is exceeded."""
+
+    def __init__(self, provider: str, retry_after: int = None):
+        self.provider = provider
+        self.retry_after = retry_after
+
+        msg = f"Rate limit exceeded for {provider}"
+        if retry_after:
+            msg += f" | Retry after {retry_after} seconds"
+
+        super().__init__(msg)
+
+
+class CacheError(LangfuseLibraryError):
+    """Raised when cache operations fail."""
+    pass
+
+
+class ValidationError(LangfuseLibraryError):
+    """Raised when input validation fails."""
+
+    def __init__(self, field: str, message: str):
+        self.field = field
+        super().__init__(f"Validation error for '{field}': {message}")
+
+
+class TracingError(LangfuseLibraryError):
+    """Raised when tracing operations fail."""
+
+    def __init__(self, message: str, original_error: Exception = None):
+        self.original_error = original_error
+
+        msg = f"Tracing error: {message}"
+        if original_error:
+            msg += f" | Original error: {str(original_error)}"
+
+        super().__init__(msg)