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

langfuse_prompt_library/manager.py

@@ -0,0 +1,663 @@
+"""
+Core Langfuse manager for handling prompts, tracing, and LLM calls.
+"""
+
+import time
+import atexit
+from typing import Optional, Dict, Any, Literal
+from langfuse import Langfuse, get_client
+from langfuse.openai import OpenAI
+
+from .config import LangfuseConfig
+from .models import LLMResponse
+from utils.logger import get_logger
+from .exceptions import (
+    ProviderError,
+    PromptNotFoundError,
+    APITimeoutError,
+    TracingError,
+    ConfigurationError
+)
+from utils.utility import (
+    ThreadSafeCache,
+    retry_with_backoff,
+    validate_prompt_name,
+    validate_model_name,
+    validate_temperature,
+    validate_max_tokens,
+    sanitize_user_input
+)
+
+# Try to import Anthropic (optional dependency)
+try:
+    from anthropic import Anthropic
+    ANTHROPIC_AVAILABLE = True
+except ImportError:
+    ANTHROPIC_AVAILABLE = False
+    Anthropic = None
+
+
+class LangfuseManager:
+    """Main entry point for Langfuse library.
+
+    Provides a high-level API for fetching prompts, calling LLMs,
+    and automatic tracing/observability.
+
+    Example:
+        >>> 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)
+    """
+
+    def __init__(self, config: Optional[LangfuseConfig] = None):
+        """Initialize LangfuseManager.
+
+        Args:
+            config: Optional LangfuseConfig. If None, loads from environment.
+
+        Raises:
+            ConfigurationError: If required configuration is missing
+        """
+        # Load and validate configuration
+        self._config = config or LangfuseConfig.from_env()
+        self._config.validate()
+
+        # Initialize logger
+        self._logger = get_logger("langfuse_prompt_library", self._config.log_level)
+
+        self._logger.info("Initializing LangfuseManager", debug_mode=self._config.debug)
+
+        # Initialize Langfuse client
+        try:
+            self._langfuse = Langfuse(
+                secret_key=self._config.secret_key,
+                public_key=self._config.public_key,
+                host=self._config.host
+            )
+            self._logger.debug("Langfuse client initialized", host=self._config.host)
+        except Exception as e:
+            self._logger.error("Failed to initialize Langfuse client", exc_info=True)
+            raise ConfigurationError(f"Failed to initialize Langfuse client: {str(e)}")
+
+        # Initialize OpenAI client with Langfuse integration (if API key provided)
+        self._openai = None
+        if self._config.openai_api_key:
+            try:
+                self._openai = OpenAI(api_key=self._config.openai_api_key)
+                self._logger.debug("OpenAI client initialized")
+            except Exception as e:
+                self._logger.warning(f"Failed to initialize OpenAI client: {str(e)}")
+
+        # Initialize Anthropic client (if API key provided and library available)
+        self._anthropic = None
+        if self._config.anthropic_api_key and ANTHROPIC_AVAILABLE:
+            try:
+                self._anthropic = Anthropic(api_key=self._config.anthropic_api_key)
+                self._logger.debug("Anthropic client initialized")
+            except Exception as e:
+                self._logger.warning(f"Failed to initialize Anthropic client: {str(e)}")
+
+        # Initialize thread-safe prompt cache
+        self._prompt_cache = ThreadSafeCache(
+            default_ttl=self._config.cache_ttl
+        ) if self._config.enable_caching else None
+
+        # Register cleanup handler
+        if self._config.flush_at_shutdown:
+            atexit.register(self._cleanup)
+            self._logger.debug("Registered cleanup handler for shutdown")
+
+    def get_prompt(
+        self,
+        name: str,
+        version: Optional[int] = None,
+        label: Optional[str] = None,
+        cache: bool = True
+    ):
+        """Fetch a prompt from Langfuse with optional caching.
+
+        Args:
+            name: Prompt name
+            version: Specific version number (optional)
+            label: Prompt label like "production" (optional)
+            cache: Whether to use cache (default: True)
+
+        Returns:
+            Langfuse prompt object
+
+        Raises:
+            PromptNotFoundError: If prompt is not found
+            ValidationError: If parameters are invalid
+
+        Example:
+            >>> prompt = lf.get_prompt("my_prompt", label="production")
+            >>> messages = prompt.compile(user_input="Hello")
+        """
+        # Validate inputs
+        validate_prompt_name(name)
+
+        # Build cache key
+        cache_key = f"{name}:{version or label or 'latest'}"
+
+        # Check cache if enabled
+        if cache and self._prompt_cache is not None:
+            cached_prompt = self._prompt_cache.get(cache_key)
+            if cached_prompt is not None:
+                self._logger.debug("Using cached prompt", prompt_name=name, cache_key=cache_key)
+                return cached_prompt
+
+        # Fetch from Langfuse with retry logic
+        try:
+            self._logger.debug(
+                "Fetching prompt from Langfuse",
+                prompt_name=name,
+                version=version,
+                label=label
+            )
+
+            if version is not None:
+                prompt = self._langfuse.get_prompt(name, version=version)
+            elif label:
+                prompt = self._langfuse.get_prompt(name, label=label)
+            else:
+                prompt = self._langfuse.get_prompt(name)
+
+            self._logger.info(
+                "Fetched prompt from Langfuse",
+                prompt_name=name,
+                version=prompt.version
+            )
+
+            # Update cache if enabled
+            if cache and self._prompt_cache is not None:
+                self._prompt_cache.set(cache_key, prompt)
+
+            return prompt
+
+        except Exception as e:
+            self._logger.error(
+                "Failed to fetch prompt",
+                exc_info=True,
+                prompt_name=name,
+                version=version,
+                label=label
+            )
+            raise PromptNotFoundError(name, version, label)
+
+    def compile_prompt(self, prompt, **variables) -> list:
+        """Compile a prompt with variables.
+
+        Args:
+            prompt: Langfuse prompt object
+            **variables: Variables to substitute in the prompt
+
+        Returns:
+            List of compiled messages ready for LLM call
+
+        Example:
+            >>> prompt = lf.get_prompt("assistant")
+            >>> messages = lf.compile_prompt(prompt, user_input="Hello")
+        """
+        return prompt.compile(**variables)
+
+    def _detect_provider(self, model: str) -> Literal["openai", "anthropic"]:
+        """Detect provider from model name.
+
+        Args:
+            model: Model name
+
+        Returns:
+            Provider name ("openai" or "anthropic")
+        """
+        model_lower = model.lower()
+
+        # Anthropic models
+        if any(name in model_lower for name in ["claude", "anthropic"]):
+            return "anthropic"
+
+        # Default to OpenAI (gpt-*, etc.)
+        return "openai"
+
+    @retry_with_backoff(max_retries=3, initial_delay=1.0)
+    def call_llm(
+        self,
+        prompt_name: str,
+        user_input: str,
+        prompt_version: Optional[int] = None,
+        prompt_label: Optional[str] = None,
+        model: str = "gpt-3.5-turbo",
+        provider: Optional[Literal["openai", "anthropic"]] = None,
+        temperature: float = 0.7,
+        max_tokens: int = 500,
+        **kwargs
+    ) -> LLMResponse:
+        """High-level method to fetch prompt, call LLM, and handle tracing.
+
+        This method automatically:
+        - Validates all inputs
+        - Fetches the prompt from Langfuse
+        - Compiles it with user_input
+        - Creates trace and generation observations
+        - Calls LLM API (OpenAI or Anthropic) with retry logic
+        - Tracks tokens and metadata
+        - Handles errors gracefully
+
+        Args:
+            prompt_name: Name of the Langfuse prompt
+            user_input: User's query/input to be substituted in prompt
+            prompt_version: Optional specific version number
+            prompt_label: Optional prompt label (e.g., "production")
+            model: Model name (e.g., "gpt-3.5-turbo" or "claude-sonnet-4")
+            provider: LLM provider ("openai" or "anthropic"). Auto-detected if None
+            temperature: Model temperature (default: 0.7)
+            max_tokens: Maximum tokens in response (default: 500)
+            **kwargs: Additional parameters for LLM API
+
+        Returns:
+            LLMResponse with content, usage, and metadata
+
+        Raises:
+            ProviderError: If provider is not configured or encounters an error
+            ValidationError: If input validation fails
+            PromptNotFoundError: If prompt is not found
+            Exception: Re-raises any errors after logging to Langfuse
+
+        Example (OpenAI):
+            >>> response = lf.call_llm(
+            ...     prompt_name="assistant",
+            ...     user_input="What is Python?",
+            ...     model="gpt-3.5-turbo"
+            ... )
+
+        Example (Anthropic):
+            >>> response = lf.call_llm(
+            ...     prompt_name="assistant",
+            ...     user_input="What is Python?",
+            ...     model="claude-sonnet-4"
+            ... )
+        """
+        # Validate inputs
+        validate_prompt_name(prompt_name)
+        validate_model_name(model)
+        validate_temperature(temperature)
+        validate_max_tokens(max_tokens)
+        user_input = sanitize_user_input(user_input)
+
+        self._logger.info(
+            "Starting LLM call",
+            prompt_name=prompt_name,
+            model=model,
+            temperature=temperature,
+            max_tokens=max_tokens
+        )
+
+        # Step 1: Determine provider
+        detected_provider = provider or self._detect_provider(model)
+
+        # Validate provider is configured
+        if detected_provider == "openai" and not self._openai:
+            raise ProviderError(
+                "openai",
+                "OpenAI provider not configured. Please set OPENAI_API_KEY environment variable."
+            )
+        if detected_provider == "anthropic":
+            if not ANTHROPIC_AVAILABLE:
+                raise ProviderError(
+                    "anthropic",
+                    "Anthropic library not installed. Install with: pip install anthropic"
+                )
+            if not self._anthropic:
+                raise ProviderError(
+                    "anthropic",
+                    "Anthropic provider not configured. Please set ANTHROPIC_API_KEY environment variable."
+                )
+
+        # Step 2: Fetch prompt
+        prompt = self.get_prompt(
+            prompt_name,
+            version=prompt_version,
+            label=prompt_label
+        )
+
+        # Step 3: Compile prompt with user input
+        messages = prompt.compile(user_input=user_input)
+
+        # Step 4: Get Langfuse client for tracing
+        lf_client = get_client()
+
+        # Step 5: Update trace metadata
+        lf_client.update_current_trace(
+            metadata={
+                "prompt_name": prompt_name,
+                "prompt_version": prompt.version,
+                "user_query": user_input,
+                "model": model,
+                "provider": detected_provider
+            }
+        )
+
+        # Step 6: Call appropriate provider
+        if detected_provider == "openai":
+            return self._call_openai(
+                lf_client, messages, model, temperature, max_tokens,
+                prompt_name, prompt.version, **kwargs
+            )
+        else:  # anthropic
+            return self._call_anthropic(
+                lf_client, messages, model, temperature, max_tokens,
+                prompt_name, prompt.version, **kwargs
+            )
+
+    def flush(self) -> None:
+        """Flush pending traces to Langfuse.
+
+        Call this before application shutdown to ensure all traces are sent.
+
+        Example:
+            >>> lf = LangfuseManager()
+            >>> # ... make LLM calls ...
+            >>> lf.flush()  # Ensure all traces are sent
+        """
+        try:
+            self._logger.info("Flushing traces to Langfuse")
+            self._langfuse.flush()
+            self._logger.info("Successfully flushed traces")
+        except Exception as e:
+            self._logger.error("Failed to flush traces", exc_info=True)
+            raise TracingError("Failed to flush traces", e)
+
+    def _cleanup(self) -> None:
+        """Cleanup handler called at shutdown."""
+        try:
+            self._logger.info("Running cleanup at shutdown")
+
+            # Log cache statistics if caching is enabled
+            if self._prompt_cache is not None:
+                stats = self._prompt_cache.get_stats()
+                self._logger.info("Cache statistics", **stats)
+
+            # Flush traces
+            self.flush()
+
+            self._logger.info("Cleanup completed successfully")
+        except Exception as e:
+            self._logger.error("Error during cleanup", exc_info=True)
+
+    def _call_openai(
+        self,
+        lf_client,
+        messages: list,
+        model: str,
+        temperature: float,
+        max_tokens: int,
+        prompt_name: str,
+        prompt_version: int,
+        **kwargs
+    ) -> LLMResponse:
+        """Call OpenAI API with Langfuse tracing and error handling."""
+        self._logger.debug("Calling OpenAI API", model=model)
+
+        with lf_client.start_as_current_observation(
+            as_type="generation",
+            name=f"{model}-call",
+            model=model,
+            model_parameters={
+                "temperature": temperature,
+                "max_tokens": max_tokens,
+                **kwargs
+            },
+            input=messages
+        ) as generation:
+            try:
+                response = self._openai.chat.completions.create(
+                    model=model,
+                    messages=messages,
+                    temperature=temperature,
+                    max_tokens=max_tokens,
+                    timeout=self._config.request_timeout,
+                    **kwargs
+                )
+
+                content = response.choices[0].message.content
+                usage = self._extract_openai_usage(response)
+
+                self._logger.info(
+                    "OpenAI API call successful",
+                    model=model,
+                    tokens_used=usage["total"]
+                )
+
+                generation.update(
+                    output=content,
+                    usage_details={
+                        "input": usage["input"],
+                        "output": usage["output"],
+                        "total": usage["total"]
+                    }
+                )
+
+                return LLMResponse(
+                    content=content,
+                    model=model,
+                    usage=usage,
+                    metadata={
+                        "prompt_name": prompt_name,
+                        "prompt_version": prompt_version,
+                        "provider": "openai",
+                        "temperature": temperature,
+                        "max_tokens": max_tokens
+                    },
+                    raw_response=response
+                )
+
+            except Exception as e:
+                self._logger.error(
+                    "OpenAI API call failed",
+                    exc_info=True,
+                    model=model,
+                    error=str(e)
+                )
+                generation.update(level="ERROR", status_message=str(e))
+                raise ProviderError("openai", str(e), e)
+
+    def _call_anthropic(
+        self,
+        lf_client,
+        messages: list,
+        model: str,
+        temperature: float,
+        max_tokens: int,
+        prompt_name: str,
+        prompt_version: int,
+        **kwargs
+    ) -> LLMResponse:
+        """Call Anthropic API with Langfuse tracing and error handling."""
+        self._logger.debug("Calling Anthropic API", model=model)
+
+        with lf_client.start_as_current_observation(
+            as_type="generation",
+            name=f"{model}-call",
+            model=model,
+            model_parameters={
+                "temperature": temperature,
+                "max_tokens": max_tokens,
+                **kwargs
+            },
+            input=messages
+        ) as generation:
+            try:
+                # Convert OpenAI format to Anthropic format
+                system_message = next((m["content"] for m in messages if m["role"] == "system"), "")
+                user_messages = [m for m in messages if m["role"] != "system"]
+
+                response = self._anthropic.messages.create(
+                    model=model,
+                    system=system_message,
+                    messages=user_messages,
+                    temperature=temperature,
+                    max_tokens=max_tokens,
+                    timeout=self._config.request_timeout,
+                    **kwargs
+                )
+
+                content = response.content[0].text
+                usage = self._extract_anthropic_usage(response)
+
+                self._logger.info(
+                    "Anthropic API call successful",
+                    model=model,
+                    tokens_used=usage["total"]
+                )
+
+                generation.update(
+                    output=content,
+                    usage_details={
+                        "input": usage["input"],
+                        "output": usage["output"],
+                        "total": usage["total"]
+                    }
+                )
+
+                return LLMResponse(
+                    content=content,
+                    model=model,
+                    usage=usage,
+                    metadata={
+                        "prompt_name": prompt_name,
+                        "prompt_version": prompt_version,
+                        "provider": "anthropic",
+                        "temperature": temperature,
+                        "max_tokens": max_tokens
+                    },
+                    raw_response=response
+                )
+
+            except Exception as e:
+                self._logger.error(
+                    "Anthropic API call failed",
+                    exc_info=True,
+                    model=model,
+                    error=str(e)
+                )
+                generation.update(level="ERROR", status_message=str(e))
+                raise ProviderError("anthropic", str(e), e)
+
+    def _extract_openai_usage(self, response) -> Dict[str, int]:
+        """Extract token usage from OpenAI response."""
+        return {
+            "input": response.usage.prompt_tokens,
+            "output": response.usage.completion_tokens,
+            "total": response.usage.total_tokens
+        }
+
+    def _extract_anthropic_usage(self, response) -> Dict[str, int]:
+        """Extract token usage from Anthropic response."""
+        return {
+            "input": response.usage.input_tokens,
+            "output": response.usage.output_tokens,
+            "total": response.usage.input_tokens + response.usage.output_tokens
+        }
+
+
+    def get_prompt_by_version_and_label(
+        self,
+        name: str,
+        version: int,
+        expected_label: str,
+        cache: bool = True
+    ):
+        """Get prompt by version and validate it has the expected label.
+
+        This method fetches a specific prompt version and validates that it has
+        the expected label. Raises an error if the validation fails.
+
+        Args:
+            name: Prompt name
+            version: Specific version number
+            expected_label: Label that the version must have
+            cache: Whether to use cache (default: True)
+
+        Returns:
+            Langfuse prompt object if validation passes
+
+        Raises:
+            ValidationError: If the version doesn't have the expected label
+            PromptNotFoundError: If prompt is not found
+
+        Example:
+            >>> lf = LangfuseManager()
+            >>> prompt = lf.get_prompt_by_version_and_label(
+            ...     name="customer_support_agent",
+            ...     version=3,
+            ...     expected_label="production"
+            ... )
+        """
+        from .exceptions import ValidationError
+
+        # Get prompt by version
+        prompt = self.get_prompt(name=name, version=version, cache=cache)
+
+        # Validate it has the expected label
+        if expected_label not in prompt.labels:
+            error_msg = (
+                f"Validation failed: Version {version} of '{name}' does not have label '{expected_label}'. "
+                f"Available labels: {prompt.labels}"
+            )
+            self._logger.error(error_msg, prompt_name=name, version=version)
+            raise ValidationError("prompt_label", error_msg)
+
+        self._logger.info(
+            "Validation passed",
+            prompt_name=name,
+            version=version,
+            label=expected_label
+        )
+
+        return prompt
+
+    def get_cache_stats(self) -> Optional[Dict[str, Any]]:
+        """Get cache statistics.
+
+        Returns:
+            Dictionary with cache statistics or None if caching is disabled
+        """
+        if self._prompt_cache is not None:
+            return self._prompt_cache.get_stats()
+        return None
+
+    def clear_cache(self) -> None:
+        """Clear the prompt cache."""
+        if self._prompt_cache is not None:
+            self._prompt_cache.clear()
+            self._logger.info("Prompt cache cleared")
+
+    @property
+    def config(self) -> LangfuseConfig:
+        """Get current configuration.
+
+        Returns:
+            LangfuseConfig instance
+        """
+        return self._config
+
+    @property
+    def langfuse_client(self) -> Langfuse:
+        """Get underlying Langfuse client for advanced usage.
+
+        Returns:
+            Langfuse client instance
+        """
+        return self._langfuse
+
+    @property
+    def openai_client(self) -> OpenAI:
+        """Get underlying OpenAI client for advanced usage.
+
+        Returns:
+            OpenAI client instance
+        """
+        return self._openai

langfuse_prompt_library/models.py

@@ -0,0 +1,42 @@
+"""
+Data models for Langfuse library responses.
+"""
+
+from dataclasses import dataclass
+from typing import Dict, Any, Optional
+
+
+@dataclass
+class LLMResponse:
+    """Normalized response from LLM providers.
+
+    Attributes:
+        content: The text content of the LLM response
+        model: The model name used for the generation
+        usage: Token usage information (input, output, total)
+        metadata: Additional metadata about the generation
+        raw_response: The raw response object from the provider (optional)
+    """
+
+    content: str
+    model: str
+    usage: Dict[str, int]
+    metadata: Optional[Dict[str, Any]] = None
+    raw_response: Optional[Any] = None
+
+    def __str__(self) -> str:
+        """String representation showing the content."""
+        return self.content
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert response to dictionary.
+
+        Returns:
+            Dictionary representation of the response
+        """
+        return {
+            "content": self.content,
+            "model": self.model,
+            "usage": self.usage,
+            "metadata": self.metadata
+        }