karaoke-gen 0.57.0__py3-none-any.whl → 0.71.23__py3-none-any.whl

lyrics_transcriber/correction/agentic/providers/langchain_bridge.py

@@ -0,0 +1,212 @@
+"""Refactored LangChain-based provider bridge using composition.
+
+This is a much cleaner version that delegates to specialized components:
+- ModelFactory: Creates ChatModels
+- CircuitBreaker: Manages failure state
+- ResponseParser: Parses responses
+- RetryExecutor: Handles retry logic
+- ResponseCache: Caches LLM responses to avoid redundant calls
+
+Each component has a single responsibility and is independently testable.
+"""
+from __future__ import annotations
+
+import logging
+import os
+from typing import List, Dict, Any, Optional
+from datetime import datetime
+
+from .base import BaseAIProvider
+from .config import ProviderConfig
+from .model_factory import ModelFactory
+from .circuit_breaker import CircuitBreaker
+from .response_parser import ResponseParser
+from .retry_executor import RetryExecutor
+from .response_cache import ResponseCache
+from .constants import (
+    PROMPT_LOG_LENGTH,
+    RESPONSE_LOG_LENGTH,
+    CIRCUIT_OPEN_ERROR,
+    MODEL_INIT_ERROR,
+    PROVIDER_ERROR,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class LangChainBridge(BaseAIProvider):
+    """Provider bridge using LangChain ChatModels with reliability patterns.
+    
+    This bridge is now much simpler - it delegates to specialized components
+    rather than handling everything itself. This follows the Single 
+    Responsibility Principle and makes the code more testable.
+    
+    Components:
+        - ModelFactory: Creates and configures ChatModels
+        - CircuitBreaker: Protects against cascading failures
+        - ResponseParser: Handles JSON/raw response parsing
+        - RetryExecutor: Implements exponential backoff
+    """
+    
+    def __init__(
+        self,
+        model: str,
+        config: ProviderConfig | None = None,
+        model_factory: ModelFactory | None = None,
+        circuit_breaker: CircuitBreaker | None = None,
+        response_parser: ResponseParser | None = None,
+        retry_executor: RetryExecutor | None = None,
+        response_cache: ResponseCache | None = None,
+    ):
+        """Initialize the bridge with components (dependency injection).
+        
+        Args:
+            model: Model identifier in format "provider/model"
+            config: Provider configuration (creates default if None)
+            model_factory: Factory for creating ChatModels (creates default if None)
+            circuit_breaker: Circuit breaker instance (creates default if None)
+            response_parser: Response parser instance (creates default if None)
+            retry_executor: Retry executor instance (creates default if None)
+            response_cache: Response cache instance (creates default if None)
+        """
+        self._model = model
+        self._config = config or ProviderConfig.from_env()
+        
+        # Dependency injection with sensible defaults
+        self._factory = model_factory or ModelFactory()
+        self._circuit_breaker = circuit_breaker or CircuitBreaker(self._config)
+        self._parser = response_parser or ResponseParser()
+        self._executor = retry_executor or RetryExecutor(self._config)
+        
+        # Initialize cache (enabled by default, can be disabled via DISABLE_LLM_CACHE=1)
+        cache_enabled = os.getenv("DISABLE_LLM_CACHE", "0").lower() not in {"1", "true", "yes"}
+        self._cache = response_cache or ResponseCache(
+            cache_dir=self._config.cache_dir,
+            enabled=cache_enabled
+        )
+        
+        # Lazy-initialized chat model
+        self._chat_model: Optional[Any] = None
+    
+    def name(self) -> str:
+        """Return provider name for logging."""
+        return f"langchain:{self._model}"
+    
+    def generate_correction_proposals(
+        self, 
+        prompt: str, 
+        schema: Dict[str, Any],
+        session_id: str | None = None
+    ) -> List[Dict[str, Any]]:
+        """Generate correction proposals using LangChain ChatModel.
+        
+        This method is now much simpler - it orchestrates the components
+        rather than implementing all the logic itself.
+        
+        Args:
+            prompt: The correction prompt
+            schema: Pydantic schema for structured output (for future use)
+            session_id: Optional Langfuse session ID for grouping traces
+            
+        Returns:
+            List of correction proposal dictionaries, or error dicts on failure
+        """
+        # Store session_id for use in _invoke_model
+        self._session_id = session_id
+        
+        # Step 0: Check cache first
+        cached_response = self._cache.get(prompt, self._model)
+        if cached_response:
+            # Parse cached response and return
+            parsed = self._parser.parse(cached_response)
+            logger.debug(f"🎯 Using cached response ({len(parsed)} items)")
+            return parsed
+        
+        # Step 1: Check circuit breaker
+        if self._circuit_breaker.is_open(self._model):
+            open_until = self._circuit_breaker.get_open_until(self._model)
+            return [{
+                "error": CIRCUIT_OPEN_ERROR,
+                "until": open_until
+            }]
+        
+        # Step 2: Get or create chat model
+        if not self._chat_model:
+            try:
+                self._chat_model = self._factory.create_chat_model(
+                    self._model, 
+                    self._config
+                )
+            except Exception as e:
+                self._circuit_breaker.record_failure(self._model)
+                logger.error(f"🤖 Failed to initialize chat model: {e}")
+                return [{
+                    "error": MODEL_INIT_ERROR,
+                    "message": str(e)
+                }]
+        
+        # Step 3: Execute with retry logic
+        logger.debug(
+            f"🤖 [LangChain] Sending prompt to {self._model}: "
+            f"{prompt[:PROMPT_LOG_LENGTH]}..."
+        )
+        
+        result = self._executor.execute_with_retry(
+            operation=lambda: self._invoke_model(prompt),
+            operation_name=f"invoke_{self._model}"
+        )
+        
+        # Step 4: Handle result and update circuit breaker
+        if result.success:
+            self._circuit_breaker.record_success(self._model)
+            
+            logger.info(
+                f"🤖 [LangChain] Got response from {self._model}: "
+                f"{result.value[:RESPONSE_LOG_LENGTH]}..."
+            )
+            
+            # Step 5: Cache the raw response for future use
+            self._cache.set(
+                prompt=prompt,
+                model=self._model,
+                response=result.value,
+                metadata={
+                    "session_id": session_id,
+                    "timestamp": datetime.utcnow().isoformat()
+                }
+            )
+            
+            # Step 6: Parse response
+            return self._parser.parse(result.value)
+        else:
+            self._circuit_breaker.record_failure(self._model)
+            return [{
+                "error": PROVIDER_ERROR,
+                "message": result.error or "unknown"
+            }]
+    
+    def _invoke_model(self, prompt: str) -> str:
+        """Invoke the chat model with a prompt.
+        
+        This is a simple wrapper that can be passed to the retry executor.
+        
+        Args:
+            prompt: The prompt to send
+            
+        Returns:
+            Response content as string
+            
+        Raises:
+            Exception: Any error from the model invocation
+        """
+        from langchain_core.messages import HumanMessage
+        
+        # Prepare config with session_id in metadata (Langfuse format)
+        config = {}
+        if hasattr(self, '_session_id') and self._session_id:
+            config["metadata"] = {"langfuse_session_id": self._session_id}
+            logger.debug(f"🤖 [LangChain] Invoking with session_id: {self._session_id}")
+        
+        response = self._chat_model.invoke([HumanMessage(content=prompt)], config=config)
+        return response.content
+

lyrics_transcriber/correction/agentic/providers/model_factory.py

@@ -0,0 +1,209 @@
+"""Factory for creating LangChain ChatModels with Langfuse callbacks."""
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any, Optional, List
+
+from .config import ProviderConfig
+
+logger = logging.getLogger(__name__)
+
+
+class ModelFactory:
+    """Creates and configures LangChain ChatModels with observability.
+    
+    This factory handles:
+    - Parsing model specifications ("provider/model" format)
+    - Creating Langfuse callbacks when configured
+    - Instantiating the appropriate ChatModel for each provider
+    
+    Single Responsibility: Model creation only, no execution or state management.
+    """
+    
+    def __init__(self):
+        self._langfuse_handler: Optional[Any] = None
+        self._langfuse_initialized = False
+    
+    def create_chat_model(self, model_spec: str, config: ProviderConfig) -> Any:
+        """Create a ChatModel from a model specification.
+        
+        Args:
+            model_spec: Model identifier in format "provider/model" 
+                       e.g. "ollama/gpt-oss:latest", "openai/gpt-4"
+            config: Provider configuration with timeouts, retries, etc.
+            
+        Returns:
+            Configured LangChain ChatModel instance
+            
+        Raises:
+            ValueError: If model_spec format is invalid or provider unsupported
+        """
+        provider, model_name = self._parse_model_spec(model_spec)
+        callbacks = self._create_callbacks(model_spec)
+        return self._instantiate_model(provider, model_name, callbacks, config)
+    
+    def _parse_model_spec(self, spec: str) -> tuple[str, str]:
+        """Parse model specification into provider and model name.
+        
+        Args:
+            spec: Model spec in format "provider/model"
+            
+        Returns:
+            Tuple of (provider, model_name)
+            
+        Raises:
+            ValueError: If format is invalid
+        """
+        parts = spec.split("/", 1)
+        if len(parts) != 2:
+            raise ValueError(
+                f"Model spec must be in format 'provider/model', got: {spec}"
+            )
+        return parts[0], parts[1]
+    
+    def _create_callbacks(self, model_spec: str) -> List[Any]:
+        """Create Langfuse callback handlers if configured.
+        
+        Args:
+            model_spec: Model specification for logging
+            
+        Returns:
+            List of callback handlers (may be empty)
+        """
+        # Only initialize Langfuse once
+        if not self._langfuse_initialized:
+            self._initialize_langfuse(model_spec)
+            self._langfuse_initialized = True
+        
+        return [self._langfuse_handler] if self._langfuse_handler else []
+    
+    def _initialize_langfuse(self, model_spec: str) -> None:
+        """Initialize Langfuse callback handler if keys are present.
+        
+        Langfuse reads credentials from environment variables automatically:
+        - LANGFUSE_PUBLIC_KEY
+        - LANGFUSE_SECRET_KEY  
+        - LANGFUSE_HOST (optional)
+        
+        Args:
+            model_spec: Model specification for logging
+            
+        Raises:
+            RuntimeError: If Langfuse keys are set but initialization fails
+        """
+        public_key = os.getenv("LANGFUSE_PUBLIC_KEY")
+        secret_key = os.getenv("LANGFUSE_SECRET_KEY")
+        
+        if not (public_key and secret_key):
+            logger.debug("🤖 Langfuse keys not found, tracing disabled")
+            return
+        
+        try:
+            from langfuse import Langfuse
+            from langfuse.langchain import CallbackHandler
+            
+            # Initialize Langfuse client first (this is required!)
+            langfuse_client = Langfuse(
+                public_key=public_key,
+                secret_key=secret_key,
+                host=os.getenv("LANGFUSE_HOST", "https://cloud.langfuse.com"),
+            )
+            
+            # Then create callback handler with the same public_key
+            # The handler will use the initialized client
+            self._langfuse_handler = CallbackHandler(public_key=public_key)
+            logger.info(f"🤖 Langfuse callback handler initialized for {model_spec}")
+        except Exception as e:
+            # If Langfuse keys are set, we MUST fail fast
+            raise RuntimeError(
+                f"Langfuse keys are set but initialization failed: {e}\n"
+                f"This indicates a configuration or dependency problem.\n"
+                f"Check:\n"
+                f"  - LANGFUSE_PUBLIC_KEY: {public_key[:10]}...\n"
+                f"  - LANGFUSE_SECRET_KEY: {'set' if secret_key else 'not set'}\n"
+                f"  - LANGFUSE_HOST: {os.getenv('LANGFUSE_HOST', 'default')}\n"
+                f"  - langfuse package version: pip show langfuse"
+            ) from e
+    
+    def _instantiate_model(
+        self, 
+        provider: str, 
+        model_name: str, 
+        callbacks: List[Any], 
+        config: ProviderConfig
+    ) -> Any:
+        """Instantiate the appropriate ChatModel for the provider.
+        
+        Args:
+            provider: Provider name (ollama, openai, anthropic)
+            model_name: Model name within that provider
+            callbacks: List of callback handlers
+            config: Provider configuration
+            
+        Returns:
+            Configured ChatModel instance
+            
+        Raises:
+            ValueError: If provider is not supported
+            ImportError: If provider package is not installed
+        """
+        try:
+            if provider == "ollama":
+                return self._create_ollama_model(model_name, callbacks, config)
+            elif provider == "openai":
+                return self._create_openai_model(model_name, callbacks, config)
+            elif provider == "anthropic":
+                return self._create_anthropic_model(model_name, callbacks, config)
+            else:
+                raise ValueError(f"Unsupported provider: {provider}")
+        except ImportError as e:
+            raise ImportError(
+                f"Failed to import {provider} provider. "
+                f"Install with: pip install langchain-{provider}"
+            ) from e
+    
+    def _create_ollama_model(
+        self, model_name: str, callbacks: List[Any], config: ProviderConfig
+    ) -> Any:
+        """Create ChatOllama model."""
+        from langchain_ollama import ChatOllama
+        
+        model = ChatOllama(
+            model=model_name,
+            timeout=config.request_timeout_seconds,
+            callbacks=callbacks,
+        )
+        logger.debug(f"🤖 Created Ollama model: {model_name}")
+        return model
+    
+    def _create_openai_model(
+        self, model_name: str, callbacks: List[Any], config: ProviderConfig
+    ) -> Any:
+        """Create ChatOpenAI model."""
+        from langchain_openai import ChatOpenAI
+        
+        model = ChatOpenAI(
+            model=model_name,
+            timeout=config.request_timeout_seconds,
+            max_retries=config.max_retries,
+            callbacks=callbacks,
+        )
+        logger.debug(f"🤖 Created OpenAI model: {model_name}")
+        return model
+    
+    def _create_anthropic_model(
+        self, model_name: str, callbacks: List[Any], config: ProviderConfig
+    ) -> Any:
+        """Create ChatAnthropic model."""
+        from langchain_anthropic import ChatAnthropic
+        
+        model = ChatAnthropic(
+            model=model_name,
+            timeout=config.request_timeout_seconds,
+            max_retries=config.max_retries,
+            callbacks=callbacks,
+        )
+        logger.debug(f"🤖 Created Anthropic model: {model_name}")
+        return model
+

lyrics_transcriber/correction/agentic/providers/response_cache.py

@@ -0,0 +1,218 @@
+"""Response caching for LLM calls to avoid redundant API requests."""
+
+from __future__ import annotations
+
+import json
+import hashlib
+import logging
+from pathlib import Path
+from typing import Optional, Dict, Any
+from datetime import datetime
+
+logger = logging.getLogger(__name__)
+
+
+class ResponseCache:
+    """Caches LLM responses based on prompt hash.
+    
+    This allows reusing responses when iterating on frontend/UI changes
+    without re-running expensive LLM inference calls.
+    
+    Cache Structure:
+        {
+            "prompt_hash": {
+                "prompt": "full prompt text",
+                "response": "llm response",
+                "timestamp": "iso datetime",
+                "model": "model identifier",
+                "metadata": {...}
+            }
+        }
+    """
+    
+    def __init__(self, cache_dir: str = "cache", enabled: bool = True):
+        """Initialize response cache.
+        
+        Args:
+            cache_dir: Directory to store cache file
+            enabled: Whether caching is enabled (can be disabled via env var)
+        """
+        self.cache_dir = Path(cache_dir)
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        self.cache_file = self.cache_dir / "llm_response_cache.json"
+        self.enabled = enabled
+        self._cache: Dict[str, Dict[str, Any]] = {}
+        self._load_cache()
+    
+    def _load_cache(self) -> None:
+        """Load cache from disk."""
+        if not self.cache_file.exists():
+            self._cache = {}
+            return
+        
+        try:
+            with open(self.cache_file, 'r', encoding='utf-8') as f:
+                self._cache = json.load(f)
+            logger.debug(f"📦 Loaded {len(self._cache)} cached responses")
+        except Exception as e:
+            logger.warning(f"Failed to load cache: {e}")
+            self._cache = {}
+    
+    def _save_cache(self) -> None:
+        """Save cache to disk."""
+        try:
+            with open(self.cache_file, 'w', encoding='utf-8') as f:
+                json.dump(self._cache, f, indent=2, ensure_ascii=False)
+            logger.debug(f"💾 Saved {len(self._cache)} cached responses")
+        except Exception as e:
+            logger.warning(f"Failed to save cache: {e}")
+    
+    def _compute_hash(self, prompt: str, model: str) -> str:
+        """Compute hash for prompt + model combination.
+        
+        Args:
+            prompt: The full prompt text
+            model: Model identifier
+        
+        Returns:
+            SHA256 hash as hex string
+        """
+        # Include both prompt and model in hash
+        combined = f"{model}::{prompt}"
+        return hashlib.sha256(combined.encode('utf-8')).hexdigest()
+    
+    def get(self, prompt: str, model: str) -> Optional[str]:
+        """Get cached response for prompt if available.
+        
+        Args:
+            prompt: The prompt text
+            model: Model identifier
+        
+        Returns:
+            Cached response string or None if not found
+        """
+        if not self.enabled:
+            return None
+        
+        prompt_hash = self._compute_hash(prompt, model)
+        
+        if prompt_hash in self._cache:
+            cached = self._cache[prompt_hash]
+            logger.info(f"🎯 Cache HIT for {model} (hash: {prompt_hash[:8]}...)")
+            logger.debug(f"   Cached at: {cached.get('timestamp')}")
+            return cached.get('response')
+        
+        logger.debug(f"📭 Cache MISS for {model} (hash: {prompt_hash[:8]}...)")
+        return None
+    
+    def set(
+        self,
+        prompt: str,
+        model: str,
+        response: str,
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> None:
+        """Store response in cache.
+        
+        Args:
+            prompt: The prompt text
+            model: Model identifier
+            response: The LLM response
+            metadata: Optional metadata to store with cache entry
+        """
+        if not self.enabled:
+            return
+        
+        prompt_hash = self._compute_hash(prompt, model)
+        
+        self._cache[prompt_hash] = {
+            "prompt": prompt[:500] + "..." if len(prompt) > 500 else prompt,  # Truncate for readability
+            "response": response,
+            "timestamp": datetime.utcnow().isoformat(),
+            "model": model,
+            "metadata": metadata or {}
+        }
+        
+        # Save to disk immediately (for persistence across runs)
+        self._save_cache()
+        logger.debug(f"💾 Cached response for {model} (hash: {prompt_hash[:8]}...)")
+    
+    def clear(self) -> int:
+        """Clear all cached responses.
+        
+        Returns:
+            Number of entries cleared
+        """
+        count = len(self._cache)
+        self._cache = {}
+        self._save_cache()
+        logger.info(f"🗑️ Cleared {count} cached responses")
+        return count
+    
+    def get_stats(self) -> Dict[str, Any]:
+        """Get cache statistics.
+        
+        Returns:
+            Dictionary with cache statistics
+        """
+        if not self._cache:
+            return {
+                "total_entries": 0,
+                "cache_file": str(self.cache_file),
+                "enabled": self.enabled
+            }
+        
+        # Count by model
+        by_model = {}
+        for entry in self._cache.values():
+            model = entry.get('model', 'unknown')
+            by_model[model] = by_model.get(model, 0) + 1
+        
+        # Find oldest and newest
+        timestamps = [
+            datetime.fromisoformat(entry['timestamp'])
+            for entry in self._cache.values()
+            if 'timestamp' in entry
+        ]
+        
+        return {
+            "total_entries": len(self._cache),
+            "by_model": by_model,
+            "oldest": min(timestamps).isoformat() if timestamps else None,
+            "newest": max(timestamps).isoformat() if timestamps else None,
+            "cache_file": str(self.cache_file),
+            "enabled": self.enabled
+        }
+    
+    def prune_old_entries(self, days: int = 30) -> int:
+        """Remove cache entries older than specified days.
+        
+        Args:
+            days: Remove entries older than this many days
+        
+        Returns:
+            Number of entries removed
+        """
+        from datetime import timedelta
+        
+        cutoff = datetime.utcnow() - timedelta(days=days)
+        
+        to_remove = []
+        for prompt_hash, entry in self._cache.items():
+            if 'timestamp' in entry:
+                try:
+                    entry_time = datetime.fromisoformat(entry['timestamp'])
+                    if entry_time < cutoff:
+                        to_remove.append(prompt_hash)
+                except Exception:
+                    pass
+        
+        for prompt_hash in to_remove:
+            del self._cache[prompt_hash]
+        
+        if to_remove:
+            self._save_cache()
+            logger.info(f"🗑️ Pruned {len(to_remove)} old cache entries (older than {days} days)")
+        
+        return len(to_remove)
+