karaoke-gen 0.75.54__py3-none-any.whl

lyrics_transcriber/correction/agentic/providers/config.py

@@ -0,0 +1,73 @@
+from dataclasses import dataclass
+from typing import Optional
+import os
+
+
+@dataclass(frozen=True)
+class ProviderConfig:
+    """Centralized configuration for AI providers.
+
+    Values are loaded from environment variables to keep credentials out of code.
+    This module is safe to import during setup; it does not perform any network I/O.
+    """
+
+    openai_api_key: Optional[str]
+    anthropic_api_key: Optional[str]
+    google_api_key: Optional[str]
+    openrouter_api_key: Optional[str]
+    privacy_mode: bool
+    cache_dir: str
+
+    request_timeout_seconds: float = 30.0
+    max_retries: int = 2
+    retry_backoff_base_seconds: float = 0.2
+    retry_backoff_factor: float = 2.0
+    circuit_breaker_failure_threshold: int = 3
+    circuit_breaker_open_seconds: int = 60
+
+    @staticmethod
+    def from_env(cache_dir: Optional[str] = None) -> "ProviderConfig":
+        """Create config from environment variables.
+        
+        Args:
+            cache_dir: Cache directory path. If None, uses LYRICS_TRANSCRIBER_CACHE_DIR
+                      env var or defaults to ~/lyrics-transcriber-cache
+        """
+        if cache_dir is None:
+            cache_dir = os.getenv(
+                "LYRICS_TRANSCRIBER_CACHE_DIR",
+                os.path.join(os.path.expanduser("~"), "lyrics-transcriber-cache")
+            )
+        
+        return ProviderConfig(
+            openai_api_key=os.getenv("OPENAI_API_KEY"),
+            anthropic_api_key=os.getenv("ANTHROPIC_API_KEY"),
+            google_api_key=os.getenv("GOOGLE_API_KEY"),
+            openrouter_api_key=os.getenv("OPENROUTER_API_KEY"),
+            privacy_mode=os.getenv("PRIVACY_MODE", "false").lower() in {"1", "true", "yes"},
+            cache_dir=cache_dir,
+            request_timeout_seconds=float(os.getenv("AGENTIC_TIMEOUT_SECONDS", "30.0")),
+            max_retries=int(os.getenv("AGENTIC_MAX_RETRIES", "2")),
+            retry_backoff_base_seconds=float(os.getenv("AGENTIC_BACKOFF_BASE_SECONDS", "0.2")),
+            retry_backoff_factor=float(os.getenv("AGENTIC_BACKOFF_FACTOR", "2.0")),
+            circuit_breaker_failure_threshold=int(os.getenv("AGENTIC_CIRCUIT_THRESHOLD", "3")),
+            circuit_breaker_open_seconds=int(os.getenv("AGENTIC_CIRCUIT_OPEN_SECONDS", "60")),
+        )
+
+    def validate_environment(self, logger: Optional[object] = None) -> None:
+        """Log warnings if required keys are missing for non-privacy mode."""
+        def _log(msg: str) -> None:
+            try:
+                if logger is not None:
+                    logger.warning(msg)
+                else:
+                    print(msg)
+            except Exception:
+                pass
+
+        if self.privacy_mode:
+            return
+        if not any([self.openai_api_key, self.anthropic_api_key, self.google_api_key, self.openrouter_api_key]):
+            _log("No AI provider API keys configured; set PRIVACY_MODE=1 to avoid cloud usage or add provider keys.")
+
+

lyrics_transcriber/correction/agentic/providers/constants.py

@@ -0,0 +1,24 @@
+"""Constants for the agentic correction providers module."""
+
+# Logging constants
+PROMPT_LOG_LENGTH = 200  # Characters to log from prompts
+RESPONSE_LOG_LENGTH = 500  # Characters to log from responses
+
+# Model specification format
+MODEL_SPEC_FORMAT = "provider/model"  # Expected format for model identifiers
+
+# Default Langfuse host
+DEFAULT_LANGFUSE_HOST = "https://cloud.langfuse.com"
+
+# Raw response indicator
+RAW_RESPONSE_KEY = "raw"  # Key used to wrap unparsed responses
+
+# Error response keys
+ERROR_KEY = "error"
+ERROR_MESSAGE_KEY = "message"
+
+# Circuit breaker error types
+CIRCUIT_OPEN_ERROR = "circuit_open"
+MODEL_INIT_ERROR = "model_init_failed"
+PROVIDER_ERROR = "provider_error"
+

lyrics_transcriber/correction/agentic/providers/health.py

@@ -0,0 +1,28 @@
+from typing import List, Dict, Any
+
+
+def is_ollama_available() -> bool:
+    """Return True if a local Ollama server responds to a simple list() call.
+
+    This function is intentionally lightweight and safe to call during setup.
+    """
+    try:
+        import ollama  # type: ignore
+
+        _ = ollama.list()
+        return True
+    except Exception:
+        return False
+
+
+def get_ollama_models() -> List[Dict[str, Any]]:
+    """Return available local models from Ollama if available; otherwise empty list."""
+    try:
+        import ollama  # type: ignore
+
+        data = ollama.list() or {}
+        return data.get("models", []) if isinstance(data, dict) else []
+    except Exception:
+        return []
+
+

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
+