karaoke-gen 0.103.1__py3-none-any.whl → 0.107.0__py3-none-any.whl

lyrics_transcriber/correction/agentic/agent.py

@@ -13,6 +13,7 @@ from .models.schemas import CorrectionProposal, GapClassification, GapCategory
 from .workflows.correction_graph import build_correction_graph
 from .prompts.classifier import build_classification_prompt
 from .handlers.registry import HandlerRegistry
+from lyrics_transcriber.utils.tracing import create_span, add_span_attribute
 
 logger = logging.getLogger(__name__)
 
@@ -211,72 +212,94 @@ class AgenticCorrector:
         Returns:
             List of CorrectionProposal objects
         """
-        # Step 1: Classify the gap
-        gap_text = ' '.join(w.get('text', '') for w in gap_words)
-        classification = self.classify_gap(
-            gap_id=gap_id,
-            gap_text=gap_text,
-            preceding_words=preceding_words,
-            following_words=following_words,
-            reference_contexts=reference_contexts,
-            artist=artist,
-            title=title
-        )
-        
-        if not classification:
-            # Classification failed, flag for human review
-            logger.warning(f"🤖 Classification failed for gap {gap_id}, flagging for review")
-            return [CorrectionProposal(
-                word_ids=[w['id'] for w in gap_words],
-                action="Flag",
-                confidence=0.0,
-                reason="Classification failed - unable to categorize gap",
-                requires_human_review=True,
-                artist=artist,
-                title=title
-            )]
-        
-        # Step 2: Route to appropriate handler based on category
-        try:
-            handler = HandlerRegistry.get_handler(
-                category=classification.category,
-                artist=artist,
-                title=title
-            )
-            
-            proposals = handler.handle(
+        with create_span("agentic.propose_for_gap", {
+            "gap_id": gap_id,
+            "word_count": len(gap_words),
+        }) as span:
+            # Step 1: Classify the gap
+            gap_text = ' '.join(w.get('text', '') for w in gap_words)
+            classification = self.classify_gap(
                 gap_id=gap_id,
-                gap_words=gap_words,
+                gap_text=gap_text,
                 preceding_words=preceding_words,
                 following_words=following_words,
                 reference_contexts=reference_contexts,
-                classification_reasoning=classification.reasoning
-            )
-            
-            # Add classification metadata to proposals
-            for proposal in proposals:
-                if not proposal.gap_category:
-                    proposal.gap_category = classification.category
-                if not proposal.artist:
-                    proposal.artist = artist
-                if not proposal.title:
-                    proposal.title = title
-            
-            return proposals
-            
-        except Exception as e:
-            logger.error(f"🤖 Handler failed for gap {gap_id} (category: {classification.category}): {e}")
-            # Handler failed, flag for human review
-            return [CorrectionProposal(
-                word_ids=[w['id'] for w in gap_words],
-                action="Flag",
-                confidence=0.0,
-                reason=f"Handler error for category {classification.category}: {str(e)}",
-                gap_category=classification.category,
-                requires_human_review=True,
                 artist=artist,
                 title=title
-            )]
+            )
+
+            if not classification:
+                # Classification failed, flag for human review
+                logger.warning(f"🤖 Classification failed for gap {gap_id}, flagging for review")
+                if span:
+                    span.set_attribute("classification_failed", True)
+                # Safely extract word IDs, filtering out any missing/None values
+                word_ids = [w.get('id') for w in gap_words if w.get('id') is not None]
+                return [CorrectionProposal(
+                    word_ids=word_ids,
+                    action="Flag",
+                    confidence=0.0,
+                    reason="Classification failed - unable to categorize gap",
+                    requires_human_review=True,
+                    artist=artist,
+                    title=title
+                )]
+
+            if span:
+                span.set_attribute("gap_category", classification.category.value if hasattr(classification.category, 'value') else str(classification.category))
+
+            # Step 2: Route to appropriate handler based on category
+            try:
+                handler = HandlerRegistry.get_handler(
+                    category=classification.category,
+                    artist=artist,
+                    title=title
+                )
+
+                proposals = handler.handle(
+                    gap_id=gap_id,
+                    gap_words=gap_words,
+                    preceding_words=preceding_words,
+                    following_words=following_words,
+                    reference_contexts=reference_contexts,
+                    classification_reasoning=classification.reasoning
+                )
+
+                # Add classification metadata to proposals
+                for proposal in proposals:
+                    if not proposal.gap_category:
+                        proposal.gap_category = classification.category
+                    if not proposal.artist:
+                        proposal.artist = artist
+                    if not proposal.title:
+                        proposal.title = title
+
+                if span:
+                    span.set_attribute("proposal_count", len(proposals))
+
+                return proposals
+
+            except Exception as e:
+                # Sanitize error message - use exception class name and truncated message
+                error_type = type(e).__name__
+                error_msg_truncated = str(e)[:50] if str(e) else "Unknown error"
+                sanitized_error = f"{error_type}: {error_msg_truncated}"
+                logger.error(f"🤖 Handler failed for gap {gap_id} (category: {classification.category}): {sanitized_error}")
+                if span:
+                    span.set_attribute("handler_error", sanitized_error)
+                # Safely extract word IDs, filtering out any missing/None values
+                word_ids = [w.get('id') for w in gap_words if w.get('id') is not None]
+                # Handler failed, flag for human review
+                return [CorrectionProposal(
+                    word_ids=word_ids,
+                    action="Flag",
+                    confidence=0.0,
+                    reason=f"Handler error for category {classification.category} ({error_type})",
+                    gap_category=classification.category,
+                    requires_human_review=True,
+                    artist=artist,
+                    title=title
+                )]
 
     def propose(self, prompt: str) -> List[CorrectionProposal]:
         """Generate correction proposals using LangGraph + LangChain.

lyrics_transcriber/correction/anchor_sequence.py

@@ -8,6 +8,9 @@ from pathlib import Path
 import json
 import hashlib
 
+# Tracing utilities (optional - gracefully handles missing dependency)
+from lyrics_transcriber.utils.tracing import create_span, add_span_attribute, add_span_event
+
 from lyrics_transcriber.types import LyricsData, PhraseScore, PhraseType, AnchorSequence, GapSequence, ScoredAnchor, TranscriptionResult, Word
 from lyrics_transcriber.correction.phrase_analyzer import PhraseAnalyzer
 from lyrics_transcriber.correction.text_utils import clean_text
@@ -381,7 +384,24 @@ class AnchorSequenceFinder:
     ) -> List[ScoredAnchor]:
         """Find anchor sequences that appear in both transcription and references with timeout protection."""
         start_time = time.time()
-        
+
+        # Wrap entire operation in a tracing span
+        with create_span("anchor_search.find_anchors", {
+            "transcription.text_length": len(transcribed),
+            "reference.source_count": len(references),
+            "timeout_seconds": self.timeout_seconds,
+        }) as span:
+            return self._find_anchors_impl(transcribed, references, transcription_result, start_time, span)
+
+    def _find_anchors_impl(
+        self,
+        transcribed: str,
+        references: Dict[str, LyricsData],
+        transcription_result: TranscriptionResult,
+        start_time: float,
+        span,
+    ) -> List[ScoredAnchor]:
+        """Internal implementation of find_anchors wrapped in tracing span."""
         try:
             self.logger.info(f"🔍 ANCHOR SEARCH: Starting find_anchors with timeout {self.timeout_seconds}s")
             self.logger.info(f"🔍 ANCHOR SEARCH: Transcribed text length: {len(transcribed)}")
@@ -395,6 +415,10 @@ class AnchorSequenceFinder:
             self.logger.info(f"🔍 ANCHOR SEARCH: Checking cache at {cache_path}")
             if cached_data := self._load_from_cache(cache_path):
                 self.logger.info("🔍 ANCHOR SEARCH: ✅ Cache hit! Loading anchors from cache")
+                if span:
+                    span.set_attribute("cache_hit", True)
+                    span.set_attribute("cached_anchors", len(cached_data))
+                    span.set_attribute("duration_seconds", time.time() - start_time)
                 try:
                     # Convert cached_data to dictionary before logging
                     if cached_data:
@@ -504,10 +528,24 @@ class AnchorSequenceFinder:
                     }
 
                     completed = 0
+                    last_progress_log_time = time.time()
+                    progress_log_interval = 30  # Log every 30 seconds
+
                     for future in as_completed(future_to_n):
                         n = future_to_n[future]
                         completed += 1
 
+                        # Time-based progress logging (every 30 seconds)
+                        current_time = time.time()
+                        if current_time - last_progress_log_time >= progress_log_interval:
+                            elapsed = current_time - start_time
+                            progress_pct = (completed / len(n_gram_lengths)) * 100
+                            self.logger.info(
+                                f"🔍 ANCHOR SEARCH: Progress {completed}/{len(n_gram_lengths)} "
+                                f"({progress_pct:.1f}%) - {elapsed:.1f}s elapsed"
+                            )
+                            last_progress_log_time = current_time
+
                         # Check timeout periodically
                         if self.timeout_seconds > 0:
                             elapsed_time = time.time() - start_time
@@ -577,7 +615,14 @@ class AnchorSequenceFinder:
             
             total_time = time.time() - start_time
             self.logger.info(f"🔍 ANCHOR SEARCH: 🎉 Anchor sequence computation completed successfully in {total_time:.1f}s")
-            
+
+            # Add span attributes for metrics
+            if span:
+                span.set_attribute("candidate_anchors", len(candidate_anchors))
+                span.set_attribute("filtered_anchors", len(filtered_anchors))
+                span.set_attribute("duration_seconds", total_time)
+                span.set_attribute("cache_hit", False)
+
             return filtered_anchors
             
         except AnchorSequenceTimeoutError:
@@ -592,7 +637,7 @@ class AnchorSequenceFinder:
             self.logger.error(f"🔍 ANCHOR SEARCH: Traceback: {traceback.format_exc()}")
             raise
         finally:
-            # No cleanup needed for time-based timeout checks
+            # No cleanup needed - span is managed by context manager in find_anchors()
             pass
 
     def _score_sequence(self, words: List[str], context: str) -> PhraseScore:

lyrics_transcriber/correction/corrector.py

@@ -27,6 +27,7 @@ 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.utils.tracing import create_span, add_span_attribute, add_span_event
 
 
 class LyricsCorrector:
@@ -126,66 +127,91 @@ class LyricsCorrector:
             wrap this method with an outer timeout (e.g., asyncio.wait_for) as a safety
             net for hung operations.
         """
+        start_time = time.time()
+
         # 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')})")
-        if not transcription_results:
-            self.logger.error("No transcription results available")
-            raise ValueError("No primary transcription data available")
-
-        # Store reference lyrics for use in word map
-        self.reference_lyrics = lyrics_results
-
-        # Get primary transcription
-        primary_transcription_result = sorted(transcription_results, key=lambda x: x.priority)[0]
-        primary_transcription = primary_transcription_result.result
-        transcribed_text = " ".join(" ".join(w.text for w in segment.words) for segment in primary_transcription.segments)
-
-        # Find anchor sequences and gaps
-        self.logger.debug("Finding anchor sequences and gaps")
-        anchor_sequences = self.anchor_finder.find_anchors(transcribed_text, lyrics_results, primary_transcription_result)
-        gap_sequences = self.anchor_finder.find_gaps(transcribed_text, anchor_sequences, lyrics_results, primary_transcription_result)
-
-        # Store anchor sequences for use in correction handlers
-        self._anchor_sequences = anchor_sequences
-
-        # 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, deadline=agentic_deadline
-        )
-
-        # Calculate correction ratio
-        total_words = sum(len(segment.words) for segment in corrected_segments)
-        corrections_made = len(corrections)
-        correction_ratio = 1 - (corrections_made / total_words if total_words > 0 else 0)
-
-        # Get the currently enabled handler IDs using the handler's name attribute if available
-        enabled_handlers = [getattr(handler, "name", handler.__class__.__name__) for handler in self.handlers]
-
-        result = CorrectionResult(
-            original_segments=primary_transcription.segments,
-            corrected_segments=corrected_segments,
-            corrections=corrections,
-            corrections_made=corrections_made,
-            confidence=correction_ratio,
-            reference_lyrics=lyrics_results,
-            anchor_sequences=anchor_sequences,
-            resized_segments=[],
-            gap_sequences=gap_sequences,
-            metadata={
-                "anchor_sequences_count": len(anchor_sequences),
-                "gap_sequences_count": len(gap_sequences),
-                "total_words": total_words,
-                "correction_ratio": correction_ratio,
-                "available_handlers": self.all_handlers,
-                "enabled_handlers": enabled_handlers,
-                "agentic_routing": "agentic" if agentic_enabled else "rule-based",
-            },
-            correction_steps=correction_steps,
-            word_id_map=word_id_map,
-            segment_id_map=segment_id_map,
-        )
-        return result
+
+        with create_span("lyrics_corrector.run", {
+            "agentic_enabled": agentic_enabled,
+            "reference_sources": len(lyrics_results),
+            "transcription_count": len(transcription_results),
+        }) as span:
+            self.logger.info(f"🤖 AGENTIC MODE: {'ENABLED' if agentic_enabled else 'DISABLED'} (USE_AGENTIC_AI={os.getenv('USE_AGENTIC_AI', 'NOT_SET')})")
+            if not transcription_results:
+                self.logger.error("No transcription results available")
+                raise ValueError("No primary transcription data available")
+
+            # Store reference lyrics for use in word map
+            self.reference_lyrics = lyrics_results
+
+            # Get primary transcription
+            primary_transcription_result = sorted(transcription_results, key=lambda x: x.priority)[0]
+            primary_transcription = primary_transcription_result.result
+            transcribed_text = " ".join(" ".join(w.text for w in segment.words) for segment in primary_transcription.segments)
+
+            # Find anchor sequences and gaps
+            self.logger.debug("Finding anchor sequences and gaps")
+            with create_span("lyrics_corrector.find_anchors_and_gaps") as anchor_span:
+                anchor_sequences = self.anchor_finder.find_anchors(transcribed_text, lyrics_results, primary_transcription_result)
+                gap_sequences = self.anchor_finder.find_gaps(transcribed_text, anchor_sequences, lyrics_results, primary_transcription_result)
+                if anchor_span:
+                    anchor_span.set_attribute("anchor_count", len(anchor_sequences))
+                    anchor_span.set_attribute("gap_count", len(gap_sequences))
+
+            # Store anchor sequences for use in correction handlers
+            self._anchor_sequences = anchor_sequences
+
+            # Process corrections with metadata and optional deadline for agentic timeout
+            with create_span("lyrics_corrector.process_corrections", {
+                "gap_count": len(gap_sequences),
+                "agentic_enabled": agentic_enabled,
+            }) as process_span:
+                corrections, corrected_segments, correction_steps, word_id_map, segment_id_map = self._process_corrections(
+                    primary_transcription.segments, gap_sequences, metadata=metadata, deadline=agentic_deadline
+                )
+                if process_span:
+                    process_span.set_attribute("corrections_count", len(corrections))
+
+            # Calculate correction ratio
+            total_words = sum(len(segment.words) for segment in corrected_segments)
+            corrections_made = len(corrections)
+            correction_ratio = 1 - (corrections_made / total_words if total_words > 0 else 0)
+
+            # Get the currently enabled handler IDs using the handler's name attribute if available
+            enabled_handlers = [getattr(handler, "name", handler.__class__.__name__) for handler in self.handlers]
+
+            # Add final span attributes
+            if span:
+                span.set_attribute("total_words", total_words)
+                span.set_attribute("corrections_made", corrections_made)
+                span.set_attribute("correction_ratio", correction_ratio)
+                span.set_attribute("duration_seconds", time.time() - start_time)
+
+            result = CorrectionResult(
+                original_segments=primary_transcription.segments,
+                corrected_segments=corrected_segments,
+                corrections=corrections,
+                corrections_made=corrections_made,
+                confidence=correction_ratio,
+                reference_lyrics=lyrics_results,
+                anchor_sequences=anchor_sequences,
+                resized_segments=[],
+                gap_sequences=gap_sequences,
+                metadata={
+                    "anchor_sequences_count": len(anchor_sequences),
+                    "gap_sequences_count": len(gap_sequences),
+                    "total_words": total_words,
+                    "correction_ratio": correction_ratio,
+                    "available_handlers": self.all_handlers,
+                    "enabled_handlers": enabled_handlers,
+                    "agentic_routing": "agentic" if agentic_enabled else "rule-based",
+                },
+                correction_steps=correction_steps,
+                word_id_map=word_id_map,
+                segment_id_map=segment_id_map,
+            )
+            return result
 
     def _preserve_formatting(self, original: str, new_word: str) -> str:
         """Preserve original word's formatting when applying correction."""
@@ -465,6 +491,9 @@ class LyricsCorrector:
             # Get parallel processing config
             _config = ProviderConfig.from_env()
             max_workers = _config.max_parallel_gaps
+
+            # Wrap agentic processing in a tracing span
+            add_span_event("agentic_processing_started", {"gap_count": len(gap_sequences), "max_workers": max_workers})
             self.logger.info(f"🤖 Processing {len(gap_sequences)} gaps in parallel (max_workers={max_workers})")
 
             # Pre-compute shared data structures once (not per-gap)
@@ -585,6 +614,11 @@ class LyricsCorrector:
                         self.logger.info(f"🤖 Gap {result['index']}/{len(gap_sequences)} completed ({proposal_count} proposals)")
 
             self.logger.info(f"🤖 Parallel processing complete: {completed_count}/{len(gap_sequences)} gaps processed")
+            add_span_event("agentic_processing_completed", {
+                "gaps_processed": completed_count,
+                "gaps_total": len(gap_sequences),
+                "errors": len(errors),
+            })
 
             # If any errors occurred, fail fast
             if errors: