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

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