karaoke-gen 0.75.54__py3-none-any.whl

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)
+

lyrics_transcriber/correction/agentic/providers/response_parser.py

@@ -0,0 +1,111 @@
+"""Parser for LLM responses into structured correction proposals."""
+from __future__ import annotations
+
+import json
+import logging
+from typing import List, Dict, Any
+
+logger = logging.getLogger(__name__)
+
+
+class ResponseParser:
+    """Parses LLM responses into structured proposal dictionaries.
+    
+    Handles both JSON and raw text responses, providing consistent
+    output format for downstream processing.
+    
+    Single Responsibility: Response parsing only, no model invocation.
+    """
+    
+    def parse(self, content: str) -> List[Dict[str, Any]]:
+        """Parse response content into proposal dictionaries.
+        
+        Attempts to parse as JSON first. If that fails, tries to fix
+        common JSON issues and retries. Falls back to raw content.
+        
+        Args:
+            content: Raw response content from LLM
+            
+        Returns:
+            List of proposal dictionaries. On parse failure, returns
+            [{"raw": content}] to preserve the response.
+        """
+        # Try JSON parsing first
+        try:
+            data = json.loads(content)
+            return self._normalize_json_response(data)
+        except json.JSONDecodeError as e:
+            logger.debug(f"🤖 Response is not valid JSON: {e}")
+            
+            # Try to fix common issues
+            fixed_content = self._attempt_json_fix(content)
+            if fixed_content != content:
+                try:
+                    data = json.loads(fixed_content)
+                    logger.debug("🤖 Successfully parsed after JSON fix")
+                    return self._normalize_json_response(data)
+                except json.JSONDecodeError:
+                    pass  # Fall through to raw handling
+            
+            return self._handle_raw_response(content)
+    
+    def _attempt_json_fix(self, content: str) -> str:
+        """Attempt to fix common JSON formatting issues.
+        
+        Args:
+            content: Raw JSON string
+            
+        Returns:
+            Fixed JSON string (or original if no fixes applied)
+        """
+        # Fix 1: Replace invalid escape sequences like \' with '
+        # (JSON only allows \", \\, \/, \b, \f, \n, \r, \t)
+        fixed = content.replace("\\'", "'")
+        
+        # Fix 2: Remove any trailing commas before } or ]
+        import re
+        fixed = re.sub(r',\s*}', '}', fixed)
+        fixed = re.sub(r',\s*]', ']', fixed)
+        
+        return fixed
+    
+    def _normalize_json_response(self, data: Any) -> List[Dict[str, Any]]:
+        """Normalize JSON data into a list of dictionaries.
+        
+        Handles both single dict and list of dicts responses.
+        
+        Args:
+            data: Parsed JSON data
+            
+        Returns:
+            List of dictionaries
+        """
+        if isinstance(data, dict):
+            # Single proposal - wrap in list
+            return [data]
+        elif isinstance(data, list):
+            # Already a list - return as-is
+            return data
+        else:
+            # Unexpected type - wrap in error dict
+            logger.warning(f"🤖 Unexpected JSON type: {type(data)}")
+            return [{"error": "unexpected_type", "data": str(data)}]
+    
+    def _handle_raw_response(self, content: str) -> List[Dict[str, Any]]:
+        """Handle non-JSON responses.
+        
+        Wraps raw content in a dict for downstream handling.
+        The "raw" key indicates this needs manual processing.
+        
+        Args:
+            content: Raw response text
+            
+        Returns:
+            List with single dict containing raw content
+        """
+        logger.info(
+            f"🤖 Returning raw response (non-JSON): "
+            f"{content[:100]}{'...' if len(content) > 100 else ''}"
+        )
+        return [{"raw": content}]
+

lyrics_transcriber/correction/agentic/providers/retry_executor.py

@@ -0,0 +1,127 @@
+"""Retry execution logic with exponential backoff."""
+from __future__ import annotations
+
+import time
+import random
+import logging
+from typing import Callable, TypeVar, Generic
+from dataclasses import dataclass
+
+from .config import ProviderConfig
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar('T')
+
+
+@dataclass
+class ExecutionResult(Generic[T]):
+    """Result of a retry execution attempt.
+    
+    Attributes:
+        success: Whether execution succeeded
+        value: The return value if successful
+        error: Error message if failed
+        attempts: Number of attempts made
+    """
+    success: bool
+    value: T | None = None
+    error: str | None = None
+    attempts: int = 0
+
+
+class RetryExecutor:
+    """Executes operations with retry logic and exponential backoff.
+    
+    Implements exponential backoff with jitter to prevent thundering herd.
+    
+    Single Responsibility: Retry logic only, no model-specific behavior.
+    """
+    
+    def __init__(self, config: ProviderConfig):
+        """Initialize retry executor with configuration.
+        
+        Args:
+            config: Provider configuration with retry parameters
+        """
+        self._config = config
+    
+    def execute_with_retry(
+        self,
+        operation: Callable[[], T],
+        operation_name: str = "operation"
+    ) -> ExecutionResult[T]:
+        """Execute operation with retry logic.
+        
+        Args:
+            operation: Callable that performs the operation
+            operation_name: Name for logging purposes
+            
+        Returns:
+            ExecutionResult with success/failure status and value/error
+        """
+        max_attempts = max(1, self._config.max_retries + 1)
+        last_error: Exception | None = None
+        
+        for attempt in range(max_attempts):
+            try:
+                logger.debug(
+                    f"🤖 Executing {operation_name} "
+                    f"(attempt {attempt + 1}/{max_attempts})"
+                )
+                
+                result = operation()
+                
+                logger.debug(f"🤖 {operation_name} succeeded on attempt {attempt + 1}")
+                return ExecutionResult(
+                    success=True,
+                    value=result,
+                    attempts=attempt + 1
+                )
+                
+            except Exception as e:
+                last_error = e
+                logger.warning(
+                    f"🤖 {operation_name} failed on attempt {attempt + 1}: {e}"
+                )
+                
+                # Don't sleep after the last attempt
+                if attempt < max_attempts - 1:
+                    sleep_duration = self._calculate_backoff(attempt)
+                    logger.debug(f"🤖 Backing off for {sleep_duration:.2f}s")
+                    time.sleep(sleep_duration)
+        
+        # All attempts failed
+        error_msg = str(last_error) if last_error else "unknown error"
+        logger.error(
+            f"🤖 {operation_name} failed after {max_attempts} attempts: {error_msg}"
+        )
+        
+        return ExecutionResult(
+            success=False,
+            error=error_msg,
+            attempts=max_attempts
+        )
+    
+    def _calculate_backoff(self, attempt: int) -> float:
+        """Calculate backoff duration with exponential backoff and jitter.
+        
+        Formula: base * (factor ^ attempt) + random_jitter
+        
+        Args:
+            attempt: Current attempt number (0-indexed)
+            
+        Returns:
+            Sleep duration in seconds
+        """
+        base = self._config.retry_backoff_base_seconds
+        factor = self._config.retry_backoff_factor
+        
+        # Exponential backoff
+        backoff = base * (factor ** attempt)
+        
+        # Add jitter (0-50ms) to prevent thundering herd
+        jitter = random.uniform(0, 0.05)
+        
+        return backoff + jitter
+

lyrics_transcriber/correction/agentic/router.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import os
+from typing import Dict, Any
+
+from .providers.config import ProviderConfig
+
+
+class ModelRouter:
+    """Rules-based routing by gap type/length/uncertainty (scaffold)."""
+
+    def __init__(self, config: ProviderConfig | None = None):
+        self._config = config or ProviderConfig.from_env()
+
+    def choose_model(self, gap_type: str, uncertainty: float) -> str:
+        """Choose appropriate model based on gap characteristics.
+        
+        Returns model identifier in format "provider/model" for LangChain:
+        - "ollama/gpt-oss:latest" for local Ollama models
+        - "openai/gpt-4" for OpenAI models  
+        - "anthropic/claude-3-sonnet-20240229" for Anthropic models
+        """
+        # Simple baseline per technical guidance
+        if self._config.privacy_mode:
+            # Use the actual model from env, or default to a common Ollama model
+            return os.getenv("AGENTIC_AI_MODEL", "ollama/gpt-oss:latest")
+        
+        # For high-uncertainty gaps, use Claude (best reasoning)
+        if uncertainty > 0.5:
+            return "anthropic/claude-3-sonnet-20240229"
+        
+        # Default to GPT-4 for general cases
+        return "openai/gpt-4"
+
+

lyrics_transcriber/correction/agentic/workflows/__init__.py

@@ -0,0 +1,5 @@
+"""LangGraph workflows for agentic correction (scaffold)."""
+
+__all__ = []
+
+

lyrics_transcriber/correction/agentic/workflows/consensus_workflow.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import Any, Dict
+
+
+def build_consensus_workflow() -> Any:
+    """Return a minimal consensus workflow (scaffold).
+
+    Returns None if langgraph not installed to avoid hard dependency.
+    """
+    try:
+        from langgraph.graph import StateGraph  # type: ignore
+    except Exception:
+        return None
+
+    def merge_results(state: Dict[str, Any]) -> Dict[str, Any]:
+        return state
+
+    g = StateGraph(dict)
+    g.add_node("MergeResults", merge_results)
+    g.set_entry_point("MergeResults")
+    return g.compile()
+
+

lyrics_transcriber/correction/agentic/workflows/correction_graph.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from typing import Dict, Any, List, Annotated
+from typing_extensions import TypedDict
+
+
+class CorrectionState(TypedDict):
+    """State for the correction workflow.
+    
+    This is a minimal state for now, but can be expanded as we add
+    more sophisticated correction logic (e.g., multi-step reasoning,
+    validation loops, etc.)
+    """
+    prompt: str
+    proposals: List[Dict[str, Any]]
+
+
+def build_correction_graph(callbacks=None) -> Any:
+    """Build a LangGraph workflow for lyrics correction.
+    
+    Currently a simple pass-through, but structured to allow future
+    expansion with multi-step reasoning, validation loops, etc.
+    
+    Args:
+        callbacks: Optional callbacks (e.g., Langfuse handlers) to attach
+        
+    Returns:
+        Compiled LangGraph or None if LangGraph not installed
+    """
+    try:
+        from langgraph.graph import StateGraph, END
+    except ImportError:
+        return None
+
+    def correction_node(state: CorrectionState) -> CorrectionState:
+        """Main correction node - currently a pass-through.
+        
+        Future expansion: This could invoke sub-agents, do multi-step
+        reasoning, or implement validation loops.
+        """
+        # For now, just pass through - actual correction happens in provider
+        return state
+
+    # Build the graph
+    graph_builder = StateGraph(CorrectionState)
+    graph_builder.add_node("correct", correction_node)
+    graph_builder.set_entry_point("correct")
+    graph_builder.set_finish_point("correct")
+    
+    # Compile with optional callbacks
+    # Note: Per Langfuse docs, we can use .with_config() to add callbacks
+    compiled = graph_builder.compile()
+    
+    if callbacks:
+        return compiled.with_config({"callbacks": callbacks})
+    
+    return compiled
+
+

lyrics_transcriber/correction/agentic/workflows/feedback_workflow.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import Any, Dict
+
+
+def build_feedback_workflow() -> Any:
+    """Return a minimal feedback processing workflow (scaffold).
+
+    Returns None if langgraph not installed to avoid hard dependency.
+    """
+    try:
+        from langgraph.graph import StateGraph  # type: ignore
+    except Exception:
+        return None
+
+    def process_feedback(state: Dict[str, Any]) -> Dict[str, Any]:
+        return state
+
+    g = StateGraph(dict)
+    g.add_node("ProcessFeedback", process_feedback)
+    g.set_entry_point("ProcessFeedback")
+    return g.compile()
+
+