karaoke-gen 0.81.1__py3-none-any.whl → 0.86.5__py3-none-any.whl

lyrics_transcriber/correction/agentic/providers/response_parser.py

@@ -51,22 +51,34 @@ class ResponseParser:
     
     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)
         """
+        import re
+
+        # Fix 0: Strip markdown code fences (```json ... ``` or ``` ... ```)
+        # Models often wrap JSON in markdown code blocks
+        fixed = content.strip()
+        if fixed.startswith("```"):
+            # Remove opening fence (with optional language identifier)
+            fixed = re.sub(r'^```\w*\s*\n?', '', fixed)
+            # Remove closing fence
+            fixed = re.sub(r'\n?```\s*$', '', fixed)
+            fixed = fixed.strip()
+            logger.debug("🤖 Stripped markdown code fences from response")
+
         # Fix 1: Replace invalid escape sequences like \' with '
         # (JSON only allows \", \\, \/, \b, \f, \n, \r, \t)
-        fixed = content.replace("\\'", "'")
-        
+        fixed = fixed.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]]:

lyrics_transcriber/correction/agentic/router.py

@@ -6,6 +6,7 @@ from typing import Dict, Any
 from .providers.config import ProviderConfig
 
 # Default model for cloud deployments - Gemini 3 Flash via Vertex AI
+# Note: Gemini 3 models require 'global' location (not regional like us-central1)
 DEFAULT_CLOUD_MODEL = "vertexai/gemini-3-flash-preview"
 
 
@@ -33,7 +34,7 @@ class ModelRouter:
         if self._config.privacy_mode:
             return "ollama/llama3.2:latest"
 
-        # Default to Gemini 3 Flash for all cases (fast, cost-effective)
+        # Default to Gemini 3 Flash for all cases (fast, cost-effective, latest capabilities)
         return DEFAULT_CLOUD_MODEL
 
 

lyrics_transcriber/correction/corrector.py

@@ -4,9 +4,9 @@ from pathlib import Path
 from copy import deepcopy
 import os
 import shortuuid
+import time
 
 from lyrics_transcriber.correction.handlers.levenshtein import LevenshteinHandler
-from lyrics_transcriber.correction.handlers.llm import LLMHandler
 from lyrics_transcriber.correction.handlers.no_space_punct_match import NoSpacePunctuationMatchHandler
 from lyrics_transcriber.correction.handlers.relaxed_word_count_match import RelaxedWordCountMatchHandler
 from lyrics_transcriber.correction.handlers.repeat import RepeatCorrectionHandler
@@ -27,7 +27,6 @@ from lyrics_transcriber.correction.anchor_sequence import AnchorSequenceFinder
 from lyrics_transcriber.correction.handlers.base import GapCorrectionHandler
 from lyrics_transcriber.correction.handlers.extend_anchor import ExtendAnchorHandler
 from lyrics_transcriber.utils.word_utils import WordUtils
-from lyrics_transcriber.correction.handlers.llm_providers import OllamaProvider, OpenAIProvider
 
 
 class LyricsCorrector:
@@ -57,60 +56,18 @@ class LyricsCorrector:
         ]
 
         # Create all handlers but respect enabled_handlers if provided
+        # Note: Legacy LLMHandler removed - use AgenticCorrector via USE_AGENTIC_AI=1 instead
         all_handlers = [
             ("ExtendAnchorHandler", ExtendAnchorHandler(logger=self.logger)),
             ("WordCountMatchHandler", WordCountMatchHandler(logger=self.logger)),
             ("SyllablesMatchHandler", SyllablesMatchHandler(logger=self.logger)),
             ("RelaxedWordCountMatchHandler", RelaxedWordCountMatchHandler(logger=self.logger)),
             ("NoSpacePunctuationMatchHandler", NoSpacePunctuationMatchHandler(logger=self.logger)),
-            (
-                "LLMHandler_Ollama_R17B",
-                LLMHandler(
-                    provider=OllamaProvider(model="deepseek-r1:7b", logger=self.logger),
-                    name="LLMHandler_Ollama_R17B",
-                    logger=self.logger,
-                    cache_dir=self._cache_dir,
-                ),
-            ),
             ("RepeatCorrectionHandler", RepeatCorrectionHandler(logger=self.logger)),
             ("SoundAlikeHandler", SoundAlikeHandler(logger=self.logger)),
             ("LevenshteinHandler", LevenshteinHandler(logger=self.logger)),
         ]
 
-        # Add OpenRouter handlers only if API key is available
-        if os.getenv("OPENROUTER_API_KEY"):
-            openrouter_handlers = [
-                (
-                    "LLMHandler_OpenRouter_Sonnet",
-                    LLMHandler(
-                        provider=OpenAIProvider(
-                            model="anthropic/claude-3-sonnet",
-                            api_key=os.getenv("OPENROUTER_API_KEY"),
-                            base_url="https://openrouter.ai/api/v1",
-                            logger=self.logger,
-                        ),
-                        name="LLMHandler_OpenRouter_Sonnet",
-                        logger=self.logger,
-                        cache_dir=self._cache_dir,
-                    ),
-                ),
-                (
-                    "LLMHandler_OpenRouter_R1",
-                    LLMHandler(
-                        provider=OpenAIProvider(
-                            model="deepseek/deepseek-r1",
-                            api_key=os.getenv("OPENROUTER_API_KEY"),
-                            base_url="https://openrouter.ai/api/v1",
-                            logger=self.logger,
-                        ),
-                        name="LLMHandler_OpenRouter_R1",
-                        logger=self.logger,
-                        cache_dir=self._cache_dir,
-                    ),
-                ),
-            ]
-            all_handlers.extend(openrouter_handlers)
-
         # Store all handler information
         self.all_handlers = [
             {
@@ -151,8 +108,24 @@ class LyricsCorrector:
         transcription_results: List[TranscriptionResult],
         lyrics_results: Dict[str, LyricsData],
         metadata: Optional[Dict[str, Any]] = None,
+        agentic_deadline: Optional[float] = None,
     ) -> CorrectionResult:
-        """Execute the correction process."""
+        """Execute the correction process.
+
+        Args:
+            transcription_results: List of transcription results to correct.
+            lyrics_results: Dictionary of lyrics data from various sources.
+            metadata: Optional metadata including artist, title, audio file hash.
+            agentic_deadline: Optional Unix timestamp (from time.time()). If agentic
+                correction is still running after this time, it will abort and return
+                uncorrected results for human review.
+
+        Note:
+            The deadline is checked between gap iterations, not during LLM processing.
+            A single long-running LLM call may exceed the deadline. The caller should
+            wrap this method with an outer timeout (e.g., asyncio.wait_for) as a safety
+            net for hung operations.
+        """
         # Optional agentic routing flag from environment; default off for safety
         agentic_enabled = os.getenv("USE_AGENTIC_AI", "").lower() in {"1", "true", "yes"}
         self.logger.info(f"🤖 AGENTIC MODE: {'ENABLED' if agentic_enabled else 'DISABLED'} (USE_AGENTIC_AI={os.getenv('USE_AGENTIC_AI', 'NOT_SET')})")
@@ -176,9 +149,9 @@ class LyricsCorrector:
         # Store anchor sequences for use in correction handlers
         self._anchor_sequences = anchor_sequences
 
-        # Process corrections with metadata
+        # Process corrections with metadata and optional deadline for agentic timeout
         corrections, corrected_segments, correction_steps, word_id_map, segment_id_map = self._process_corrections(
-            primary_transcription.segments, gap_sequences, metadata=metadata
+            primary_transcription.segments, gap_sequences, metadata=metadata, deadline=agentic_deadline
         )
 
         # Calculate correction ratio
@@ -222,10 +195,22 @@ class LyricsCorrector:
         return leading_space + new_word.strip() + trailing_space
 
     def _process_corrections(
-        self, segments: List[LyricsSegment], gap_sequences: List[GapSequence], metadata: Optional[Dict[str, Any]] = None
+        self, segments: List[LyricsSegment], gap_sequences: List[GapSequence], metadata: Optional[Dict[str, Any]] = None,
+        deadline: Optional[float] = None
     ) -> Tuple[List[WordCorrection], List[LyricsSegment], List[CorrectionStep], Dict[str, str], Dict[str, str]]:
         """Process corrections using handlers.
 
+        Args:
+            segments: List of lyrics segments to process.
+            gap_sequences: List of gap sequences to correct.
+            metadata: Optional metadata including artist, title, audio file hash.
+            deadline: Optional Unix timestamp (from time.time()). When agentic mode is
+                enabled and this deadline is exceeded, remaining gaps are skipped and
+                the method returns with whatever corrections have been made (likely none).
+
+        Returns:
+            Tuple of (corrections, corrected_segments, correction_steps, word_id_map, segment_id_map).
+
         The correction flow works as follows:
         1. First pass: Process all gaps
            - Iterate through each gap sequence
@@ -459,6 +444,16 @@ class LyricsCorrector:
         # === END TEMPORARY CODE ===
 
         for i, gap in enumerate(gap_sequences, 1):
+            # Check deadline before processing each gap (agentic mode only)
+            # This allows us to abort early and return uncorrected results for human review
+            if deadline and use_agentic_env and time.time() > deadline:
+                self.logger.warning(
+                    f"⏰ AGENTIC TIMEOUT: Deadline exceeded after processing {i-1}/{len(gap_sequences)} gaps. "
+                    "Skipping remaining gaps - human review will correct any issues."
+                )
+                # Break out of loop - continue with whatever corrections we have (likely none)
+                break
+
             self.logger.info(f"Processing gap {i}/{len(gap_sequences)} at position {gap.transcription_position}")
 
             # Get the actual words for logging

lyrics_transcriber/correction/handlers/llm.py

@@ -1,293 +0,0 @@
-from typing import List, Optional, Tuple, Dict, Any, Union
-import logging
-import json
-from datetime import datetime
-from pathlib import Path
-
-from lyrics_transcriber.types import GapSequence, WordCorrection
-from lyrics_transcriber.correction.handlers.base import GapCorrectionHandler
-from lyrics_transcriber.correction.handlers.word_operations import WordOperations
-from lyrics_transcriber.correction.handlers.llm_providers import LLMProvider
-
-
-class LLMHandler(GapCorrectionHandler):
-    """Uses an LLM to analyze and correct gaps by comparing with reference lyrics."""
-
-    def __init__(
-        self, provider: LLMProvider, name: str, logger: Optional[logging.Logger] = None, cache_dir: Optional[Union[str, Path]] = None
-    ):
-        super().__init__(logger)
-        self.logger = logger or logging.getLogger(__name__)
-        self.provider = provider
-        self.name = name
-        self.cache_dir = Path(cache_dir) if cache_dir else None
-
-    def _format_prompt(self, gap: GapSequence, data: Optional[Dict[str, Any]] = None) -> str:
-        """Format the prompt for the LLM with context about the gap and reference lyrics."""
-        word_map = data.get("word_map", {})
-        metadata = data.get("metadata", {}) if data else {}
-
-        if not word_map:
-            self.logger.error("No word_map provided in data")
-            return ""
-
-        # Format transcribed words with their IDs
-        transcribed_words = [{"id": word_id, "text": word_map[word_id].text} for word_id in gap.transcribed_word_ids if word_id in word_map]
-
-        prompt = (
-            "You are a lyrics correction expert. You will be given transcribed lyrics that may contain errors "
-            "and reference lyrics from multiple sources. Your task is to analyze each word in the transcribed text "
-            "and suggest specific corrections based on the reference lyrics.\n\n"
-            "Each word has a unique ID. When suggesting corrections, you must specify the ID of the word being corrected. "
-            "This ensures accuracy in applying your corrections.\n\n"
-            "For each correction, specify:\n"
-            "1. The word ID being corrected\n"
-            "2. The correction type ('replace', 'split', 'combine', or 'delete')\n"
-            "3. The corrected text\n"
-            "4. Your confidence level\n"
-            "5. The reason for the correction\n\n"
-        )
-
-        # Add song context if available
-        if metadata and metadata.get("artist") and metadata.get("title"):
-            prompt += f"Song: {metadata['title']}\nArtist: {metadata['artist']}\n\n"
-
-        # Format transcribed words with IDs
-        prompt += "Transcribed words:\n"
-        for word in transcribed_words:
-            prompt += f"- ID: {word['id']}, Text: '{word['text']}'\n"
-
-        prompt += "\nReference lyrics from different sources:\n"
-
-        # Add each reference source with words and their IDs
-        for source, word_ids in gap.reference_word_ids.items():
-            reference_words = [{"id": word_id, "text": word_map[word_id].text} for word_id in word_ids if word_id in word_map]
-            prompt += f"\n{source} immediate context:\n"
-            for word in reference_words:
-                prompt += f"- ID: {word['id']}, Text: '{word['text']}'\n"
-
-            # Add full lyrics if available
-            if metadata and metadata.get("full_reference_texts", {}).get(source):
-                prompt += f"\nFull {source} lyrics:\n{metadata['full_reference_texts'][source]}\n"
-
-        # Add context about surrounding anchors if available
-        if gap.preceding_anchor_id:
-            preceding_anchor = next((a.anchor for a in data.get("anchor_sequences", []) if a.anchor.id == gap.preceding_anchor_id), None)
-            if preceding_anchor:
-                anchor_words = [
-                    {"id": word_id, "text": word_map[word_id].text}
-                    for word_id in preceding_anchor.transcribed_word_ids
-                    if word_id in word_map
-                ]
-                prompt += "\nPreceding correct words:\n"
-                for word in anchor_words:
-                    prompt += f"- ID: {word['id']}, Text: '{word['text']}'\n"
-
-        prompt += (
-            "\nProvide corrections in the following JSON format:\n"
-            "{\n"
-            '  "corrections": [\n'
-            "    {\n"
-            '      "word_id": "id_of_word_to_correct",\n'
-            '      "type": "replace|split|combine|delete",\n'
-            '      "corrected_text": "new text",\n'
-            '      "reference_word_id": "id_from_reference_lyrics",  // Optional, use when matching a specific reference word\n'
-            '      "confidence": 0.9,\n'
-            '      "reason": "explanation of correction"\n'
-            "    }\n"
-            "  ]\n"
-            "}\n\n"
-            "Important rules:\n"
-            "1. Always include the word_id for each correction\n"
-            "2. For 'split' type, corrected_text should contain the space-separated words\n"
-            "3. For 'combine' type, word_id should be the first word to combine\n"
-            "4. Include reference_word_id when the correction matches a specific reference word\n"
-            "5. Only suggest corrections when you're confident they improve the lyrics\n"
-            "6. Preserve any existing words that match the reference lyrics\n"
-            "7. Respond ONLY with the JSON object, no other text"
-        )
-
-        return prompt
-
-    def can_handle(self, gap: GapSequence, data: Optional[Dict[str, Any]] = None) -> Tuple[bool, Dict[str, Any]]:
-        """LLM handler can attempt to handle any gap with reference words."""
-        if not gap.reference_word_ids:
-            self.logger.debug("No reference words available")
-            return False, {}
-
-        return True, {}
-
-    def _write_debug_info(self, prompt: str, response: str, gap_index: int, audio_file_hash: Optional[str] = None) -> None:
-        """Write prompt and response to debug files."""
-        if not self.cache_dir:
-            self.logger.warning("No cache directory provided, skipping LLM debug output")
-            return
-
-        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
-        debug_dir = self.cache_dir / "llm_debug"
-        debug_dir.mkdir(exist_ok=True, parents=True)
-
-        hash_prefix = f"{audio_file_hash}_" if audio_file_hash else ""
-        filename = debug_dir / f"llm_debug_{hash_prefix}{gap_index}_{timestamp}.txt"
-
-        debug_content = "=== LLM PROMPT ===\n" f"{prompt}\n\n" "=== LLM RESPONSE ===\n" f"{response}\n"
-
-        try:
-            with open(filename, "w", encoding="utf-8") as f:
-                f.write(debug_content)
-        except IOError as e:
-            self.logger.error(f"Failed to write LLM debug file: {e}")
-
-    def handle(self, gap: GapSequence, data: Optional[Dict[str, Any]] = None) -> List[WordCorrection]:
-        """Process the gap using the LLM and create corrections based on its response."""
-        if not data or "word_map" not in data:
-            self.logger.error("No word_map provided in data")
-            return []
-
-        word_map = data["word_map"]
-        transcribed_words = [word_map[word_id].text for word_id in gap.transcribed_word_ids if word_id in word_map]
-
-        # Calculate reference positions using the centralized method
-        reference_positions = (
-            WordOperations.calculate_reference_positions(gap, anchor_sequences=data.get("anchor_sequences", [])) or {}
-        )  # Ensure empty dict if None
-
-        prompt = self._format_prompt(gap, data)
-        if not prompt:
-            return []
-
-        # Get a unique index for this gap based on its position
-        gap_index = gap.transcription_position
-
-        try:
-            self.logger.debug(f"Processing gap words: {transcribed_words}")
-            self.logger.debug(f"Reference word IDs: {gap.reference_word_ids}")
-
-            response = self.provider.generate_response(prompt)
-
-            # Write debug info to files
-            self._write_debug_info(prompt, response, gap_index, audio_file_hash=data.get("audio_file_hash"))
-
-            try:
-                corrections_data = json.loads(response)
-            except json.JSONDecodeError as e:
-                self.logger.error(f"Failed to parse LLM response as JSON: {e}")
-                self.logger.error(f"Raw response content: {response}")
-                return []
-
-            # Check if corrections exist and are non-empty
-            if not corrections_data.get("corrections"):
-                self.logger.debug("No corrections suggested by LLM")
-                return []
-
-            corrections = []
-            for correction in corrections_data["corrections"]:
-                # Validate word_id exists in gap
-                if correction["word_id"] not in gap.transcribed_word_ids:
-                    self.logger.error(f"LLM suggested correction for word_id {correction['word_id']} which is not in the gap")
-                    continue
-
-                # Get original word from word map
-                original_word = word_map[correction["word_id"]]
-                position = gap.transcription_position + gap.transcribed_word_ids.index(correction["word_id"])
-
-                self.logger.debug(f"Processing correction: {correction}")
-
-                if correction["type"] == "replace":
-                    self.logger.debug(
-                        f"Creating replacement: '{original_word.text}' -> '{correction['corrected_text']}' " f"at position {position}"
-                    )
-                    corrections.append(
-                        WordOperations.create_word_replacement_correction(
-                            original_word=original_word.text,
-                            corrected_word=correction["corrected_text"],
-                            original_position=position,
-                            source="LLM",
-                            confidence=correction["confidence"],
-                            reason=correction["reason"],
-                            handler=self.name,
-                            reference_positions=reference_positions,
-                            original_word_id=correction["word_id"],
-                            corrected_word_id=correction.get("reference_word_id"),
-                        )
-                    )
-                elif correction["type"] == "split":
-                    split_words = correction["corrected_text"].split()
-                    self.logger.debug(f"Creating split: '{original_word.text}' -> {split_words} " f"at position {position}")
-
-                    # Get reference word IDs if provided
-                    reference_word_ids = correction.get("reference_word_ids", [None] * len(split_words))
-
-                    corrections.extend(
-                        WordOperations.create_word_split_corrections(
-                            original_word=original_word.text,
-                            reference_words=split_words,
-                            original_position=position,
-                            source="LLM",
-                            confidence=correction["confidence"],
-                            reason=correction["reason"],
-                            handler=self.name,
-                            reference_positions=reference_positions,
-                            original_word_id=correction["word_id"],
-                            corrected_word_ids=reference_word_ids,
-                        )
-                    )
-                elif correction["type"] == "combine":
-                    # Get all word IDs to combine
-                    word_ids_to_combine = []
-                    current_idx = gap.transcribed_word_ids.index(correction["word_id"])
-                    words_needed = len(correction["corrected_text"].split())
-
-                    if current_idx + words_needed <= len(gap.transcribed_word_ids):
-                        word_ids_to_combine = gap.transcribed_word_ids[current_idx : current_idx + words_needed]
-                    else:
-                        self.logger.error(f"Not enough words available to combine at position {position}")
-                        continue
-
-                    words_to_combine = [word_map[word_id].text for word_id in word_ids_to_combine]
-
-                    self.logger.debug(
-                        f"Creating combine: {words_to_combine} -> '{correction['corrected_text']}' " f"at position {position}"
-                    )
-
-                    corrections.extend(
-                        WordOperations.create_word_combine_corrections(
-                            original_words=words_to_combine,
-                            reference_word=correction["corrected_text"],
-                            original_position=position,
-                            source="LLM",
-                            confidence=correction["confidence"],
-                            combine_reason=correction["reason"],
-                            delete_reason=f"Part of combining words: {correction['reason']}",
-                            handler=self.name,
-                            reference_positions=reference_positions,
-                            original_word_ids=word_ids_to_combine,
-                            corrected_word_id=correction.get("reference_word_id"),
-                        )
-                    )
-                elif correction["type"] == "delete":
-                    self.logger.debug(f"Creating deletion: '{original_word.text}' at position {position}")
-                    corrections.append(
-                        WordCorrection(
-                            original_word=original_word.text,
-                            corrected_word="",
-                            segment_index=0,
-                            original_position=position,
-                            confidence=correction["confidence"],
-                            source="LLM",
-                            reason=correction["reason"],
-                            alternatives={},
-                            is_deletion=True,
-                            handler=self.name,
-                            reference_positions=reference_positions,
-                            word_id=correction["word_id"],
-                            corrected_word_id=None,
-                        )
-                    )
-
-            self.logger.debug(f"Created {len(corrections)} corrections: {[f'{c.original_word}->{c.corrected_word}' for c in corrections]}")
-            return corrections
-
-        except Exception as e:
-            self.logger.error(f"Unexpected error in LLM handler: {e}")
-            return []

lyrics_transcriber/correction/handlers/llm_providers.py

@@ -1,60 +0,0 @@
-from abc import ABC, abstractmethod
-from typing import Optional
-import logging
-from ollama import chat as ollama_chat
-import openai
-
-
-class LLMProvider(ABC):
-    """Abstract base class for LLM providers."""
-
-    def __init__(self, logger: Optional[logging.Logger] = None):
-        self.logger = logger or logging.getLogger(__name__)
-
-    @abstractmethod
-    def generate_response(self, prompt: str, **kwargs) -> str:
-        """Generate a response from the LLM.
-
-        Args:
-            prompt: The prompt to send to the LLM
-            **kwargs: Additional provider-specific parameters
-
-        Returns:
-            str: The LLM's response
-        """
-        pass
-
-
-class OllamaProvider(LLMProvider):
-    """Provider for local Ollama models."""
-
-    def __init__(self, model: str, logger: Optional[logging.Logger] = None):
-        super().__init__(logger)
-        self.model = model
-
-    def generate_response(self, prompt: str, **kwargs) -> str:
-        try:
-            response = ollama_chat(model=self.model, messages=[{"role": "user", "content": prompt}], format="json")
-            return response.message.content
-        except Exception as e:
-            self.logger.error(f"Error generating Ollama response: {e}")
-            raise
-
-
-class OpenAIProvider(LLMProvider):
-    """Provider for OpenAI-compatible APIs (including OpenRouter)."""
-
-    def __init__(self, model: str, api_key: str, base_url: Optional[str] = None, logger: Optional[logging.Logger] = None):
-        super().__init__(logger)
-        self.model = model
-        self.client = openai.OpenAI(api_key=api_key, base_url=base_url)
-
-    def generate_response(self, prompt: str, **kwargs) -> str:
-        try:
-            response = self.client.chat.completions.create(
-                model=self.model, messages=[{"role": "user", "content": prompt}], response_format={"type": "json_object"}, **kwargs
-            )
-            return response.choices[0].message.content
-        except Exception as e:
-            self.logger.error(f"Error generating OpenAI response: {e}")
-            raise