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

lyrics_transcriber/correction/agentic/handlers/extra_words.py

@@ -0,0 +1,74 @@
+"""Handler for extra filler words at sentence starts."""
+
+from typing import List, Dict, Any
+from .base import BaseHandler
+from ..models.schemas import CorrectionProposal, GapCategory
+
+
+class ExtraWordsHandler(BaseHandler):
+    """Handles gaps with extra filler words like 'And', 'But', 'Well'."""
+    
+    # Common filler words that are often incorrectly added by transcription
+    FILLER_WORDS = {'and', 'but', 'well', 'so', 'or', 'then', 'now'}
+    
+    @property
+    def category(self) -> GapCategory:
+        return GapCategory.EXTRA_WORDS
+    
+    def handle(
+        self,
+        gap_id: str,
+        gap_words: List[Dict[str, Any]],
+        preceding_words: str,
+        following_words: str,
+        reference_contexts: Dict[str, str],
+        classification_reasoning: str = ""
+    ) -> List[CorrectionProposal]:
+        """Propose deletion of filler words."""
+        
+        if not gap_words:
+            return []
+        
+        proposals = []
+        
+        # Look for filler words at the start of the gap
+        for i, word in enumerate(gap_words):
+            text = word.get('text', '').strip().lower().rstrip(',.!?;:')
+            
+            if text in self.FILLER_WORDS:
+                # Check if this is likely at a sentence/line start
+                # (either it's the first word or preceded by punctuation)
+                is_sentence_start = (
+                    i == 0 or 
+                    gap_words[i-1].get('text', '').strip()[-1:] in '.!?'
+                )
+                
+                if is_sentence_start:
+                    proposal = CorrectionProposal(
+                        word_id=word['id'],
+                        action="DeleteWord",
+                        confidence=0.80,
+                        reason=f"Extra filler word '{word.get('text')}' at sentence start not in reference. {classification_reasoning}",
+                        gap_category=self.category,
+                        requires_human_review=False,
+                        artist=self.artist,
+                        title=self.title
+                    )
+                    proposals.append(proposal)
+        
+        # If no filler words found, flag for review
+        if not proposals:
+            proposal = CorrectionProposal(
+                word_ids=[w['id'] for w in gap_words],
+                action="Flag",
+                confidence=0.5,
+                reason=f"Classified as extra words but no obvious fillers found. {classification_reasoning}",
+                gap_category=self.category,
+                requires_human_review=True,
+                artist=self.artist,
+                title=self.title
+            )
+            proposals.append(proposal)
+        
+        return proposals
+

lyrics_transcriber/correction/agentic/handlers/no_error.py

@@ -0,0 +1,42 @@
+"""Handler for gaps where transcription matches at least one reference source."""
+
+from typing import List, Dict, Any
+from .base import BaseHandler
+from ..models.schemas import CorrectionProposal, GapCategory
+
+
+class NoErrorHandler(BaseHandler):
+    """Handles gaps where the transcription is correct (matches a reference source)."""
+    
+    @property
+    def category(self) -> GapCategory:
+        return GapCategory.NO_ERROR
+    
+    def handle(
+        self,
+        gap_id: str,
+        gap_words: List[Dict[str, Any]],
+        preceding_words: str,
+        following_words: str,
+        reference_contexts: Dict[str, str],
+        classification_reasoning: str = ""
+    ) -> List[CorrectionProposal]:
+        """Return NO_ACTION since transcription is correct."""
+        
+        if not gap_words:
+            return []
+        
+        # Create a single NO_ACTION proposal
+        proposal = CorrectionProposal(
+            word_ids=[w['id'] for w in gap_words],
+            action="NoAction",
+            confidence=0.99,
+            reason=f"Transcription matches at least one reference source. {classification_reasoning}",
+            gap_category=self.category,
+            requires_human_review=False,
+            artist=self.artist,
+            title=self.title
+        )
+        
+        return [proposal]
+

lyrics_transcriber/correction/agentic/handlers/punctuation.py

@@ -0,0 +1,44 @@
+"""Handler for punctuation-only differences."""
+
+from typing import List, Dict, Any
+from .base import BaseHandler
+from ..models.schemas import CorrectionProposal, GapCategory
+
+
+class PunctuationHandler(BaseHandler):
+    """Handles gaps where only punctuation/capitalization differs."""
+    
+    @property
+    def category(self) -> GapCategory:
+        return GapCategory.PUNCTUATION_ONLY
+    
+    def handle(
+        self,
+        gap_id: str,
+        gap_words: List[Dict[str, Any]],
+        preceding_words: str,
+        following_words: str,
+        reference_contexts: Dict[str, str],
+        classification_reasoning: str = ""
+    ) -> List[CorrectionProposal]:
+        """Return NO_ACTION for punctuation-only differences."""
+        # For punctuation differences, we don't need to make any changes
+        # The transcription is correct, just styled differently
+        
+        if not gap_words:
+            return []
+        
+        # Create a single NO_ACTION proposal for the entire gap
+        proposal = CorrectionProposal(
+            word_ids=[w['id'] for w in gap_words],
+            action="NoAction",
+            confidence=0.95,
+            reason=f"Punctuation/style difference only. {classification_reasoning}",
+            gap_category=self.category,
+            requires_human_review=False,
+            artist=self.artist,
+            title=self.title
+        )
+        
+        return [proposal]
+

lyrics_transcriber/correction/agentic/handlers/registry.py

@@ -0,0 +1,60 @@
+"""Registry for mapping gap categories to handlers."""
+
+from typing import Dict, Type
+from .base import BaseHandler
+from .punctuation import PunctuationHandler
+from .sound_alike import SoundAlikeHandler
+from .background_vocals import BackgroundVocalsHandler
+from .extra_words import ExtraWordsHandler
+from .repeated_section import RepeatedSectionHandler
+from .complex_multi_error import ComplexMultiErrorHandler
+from .ambiguous import AmbiguousHandler
+from .no_error import NoErrorHandler
+from ..models.schemas import GapCategory
+
+
+class HandlerRegistry:
+    """Registry for mapping gap categories to their handler classes."""
+    
+    _handlers: Dict[GapCategory, Type[BaseHandler]] = {
+        GapCategory.PUNCTUATION_ONLY: PunctuationHandler,
+        GapCategory.SOUND_ALIKE: SoundAlikeHandler,
+        GapCategory.BACKGROUND_VOCALS: BackgroundVocalsHandler,
+        GapCategory.EXTRA_WORDS: ExtraWordsHandler,
+        GapCategory.REPEATED_SECTION: RepeatedSectionHandler,
+        GapCategory.COMPLEX_MULTI_ERROR: ComplexMultiErrorHandler,
+        GapCategory.AMBIGUOUS: AmbiguousHandler,
+        GapCategory.NO_ERROR: NoErrorHandler,
+    }
+    
+    @classmethod
+    def get_handler(cls, category: GapCategory, artist: str = None, title: str = None) -> BaseHandler:
+        """Get a handler instance for the given category.
+        
+        Args:
+            category: Gap category
+            artist: Song artist name
+            title: Song title
+        
+        Returns:
+            Handler instance for the category
+        
+        Raises:
+            ValueError: If category is not registered
+        """
+        handler_class = cls._handlers.get(category)
+        if not handler_class:
+            raise ValueError(f"No handler registered for category: {category}")
+        
+        return handler_class(artist=artist, title=title)
+    
+    @classmethod
+    def register_handler(cls, category: GapCategory, handler_class: Type[BaseHandler]):
+        """Register a custom handler for a category.
+        
+        Args:
+            category: Gap category
+            handler_class: Handler class to register
+        """
+        cls._handlers[category] = handler_class
+

lyrics_transcriber/correction/agentic/handlers/repeated_section.py

@@ -0,0 +1,44 @@
+"""Handler for repeated sections (chorus, verse repetitions)."""
+
+from typing import List, Dict, Any
+from .base import BaseHandler
+from ..models.schemas import CorrectionProposal, GapCategory
+
+
+class RepeatedSectionHandler(BaseHandler):
+    """Handles gaps where transcription includes repeated sections not in condensed references."""
+    
+    @property
+    def category(self) -> GapCategory:
+        return GapCategory.REPEATED_SECTION
+    
+    def handle(
+        self,
+        gap_id: str,
+        gap_words: List[Dict[str, Any]],
+        preceding_words: str,
+        following_words: str,
+        reference_contexts: Dict[str, str],
+        classification_reasoning: str = ""
+    ) -> List[CorrectionProposal]:
+        """Flag repeated sections for human review."""
+        
+        if not gap_words:
+            return []
+        
+        # Repeated sections need audio verification - always flag for review
+        gap_text = ' '.join(w.get('text', '') for w in gap_words)
+        
+        proposal = CorrectionProposal(
+            word_ids=[w['id'] for w in gap_words],
+            action="Flag",
+            confidence=0.5,
+            reason=f"Repeated section detected: '{gap_text[:100]}...'. Reference lyrics may be condensed. Requires audio verification. {classification_reasoning}",
+            gap_category=self.category,
+            requires_human_review=True,
+            artist=self.artist,
+            title=self.title
+        )
+        
+        return [proposal]
+

lyrics_transcriber/correction/agentic/handlers/sound_alike.py

@@ -0,0 +1,126 @@
+"""Handler for sound-alike transcription errors."""
+
+from typing import List, Dict, Any, Optional
+from .base import BaseHandler
+from ..models.schemas import CorrectionProposal, GapCategory
+import re
+
+
+class SoundAlikeHandler(BaseHandler):
+    """Handles gaps with sound-alike errors (homophones, similar-sounding phrases)."""
+    
+    @property
+    def category(self) -> GapCategory:
+        return GapCategory.SOUND_ALIKE
+    
+    def _extract_replacement_from_references(
+        self,
+        gap_words: List[Dict[str, Any]],
+        reference_contexts: Dict[str, str],
+        preceding_words: str,
+        following_words: str
+    ) -> Optional[str]:
+        """Try to extract the correct text from reference lyrics.
+        
+        Args:
+            gap_words: Words in the gap
+            reference_contexts: Reference lyrics from each source
+            preceding_words: Words before gap
+            following_words: Words after gap
+        
+        Returns:
+            Replacement text if found, None otherwise
+        """
+        if not reference_contexts:
+            return None
+        
+        # Normalize preceding and following for matching
+        preceding_norm = self._normalize_text(preceding_words)
+        following_norm = self._normalize_text(following_words)
+        
+        # Take last few words of preceding and first few words of following
+        preceding_tokens = preceding_norm.split()[-5:] if preceding_norm else []
+        following_tokens = following_norm.split()[:5] if following_norm else []
+        
+        # Try to find the context in each reference
+        for source, ref_text in reference_contexts.items():
+            ref_norm = self._normalize_text(ref_text)
+            
+            # Try to find the preceding context
+            if preceding_tokens:
+                preceding_pattern = ' '.join(preceding_tokens)
+                if preceding_pattern in ref_norm:
+                    # Found the context, now extract what comes after
+                    start_idx = ref_norm.index(preceding_pattern) + len(preceding_pattern)
+                    remaining = ref_norm[start_idx:].strip()
+                    
+                    # Find where following context starts
+                    if following_tokens:
+                        following_pattern = ' '.join(following_tokens)
+                        if following_pattern in remaining:
+                            end_idx = remaining.index(following_pattern)
+                            replacement = remaining[:end_idx].strip()
+                            if replacement:
+                                return replacement
+        
+        return None
+    
+    def _normalize_text(self, text: str) -> str:
+        """Normalize text for comparison (lowercase, remove punctuation)."""
+        # Remove punctuation except apostrophes in contractions
+        text = re.sub(r'[^\w\s\']', ' ', text.lower())
+        # Normalize whitespace
+        text = ' '.join(text.split())
+        return text
+    
+    def handle(
+        self,
+        gap_id: str,
+        gap_words: List[Dict[str, Any]],
+        preceding_words: str,
+        following_words: str,
+        reference_contexts: Dict[str, str],
+        classification_reasoning: str = ""
+    ) -> List[CorrectionProposal]:
+        """Propose replacement based on reference lyrics."""
+        
+        if not gap_words:
+            return []
+        
+        # Try to extract the correct replacement from references
+        replacement_text = self._extract_replacement_from_references(
+            gap_words,
+            reference_contexts,
+            preceding_words,
+            following_words
+        )
+        
+        if replacement_text:
+            # Found a replacement in reference lyrics
+            proposal = CorrectionProposal(
+                word_ids=[w['id'] for w in gap_words],
+                action="ReplaceWord",
+                replacement_text=replacement_text,
+                confidence=0.75,
+                reason=f"Sound-alike error. Reference suggests: '{replacement_text}'. {classification_reasoning}",
+                gap_category=self.category,
+                requires_human_review=False,
+                artist=self.artist,
+                title=self.title
+            )
+            return [proposal]
+        else:
+            # Could not extract replacement, flag for human review
+            gap_text = ' '.join(w.get('text', '') for w in gap_words)
+            proposal = CorrectionProposal(
+                word_ids=[w['id'] for w in gap_words],
+                action="Flag",
+                confidence=0.6,
+                reason=f"Sound-alike error detected for '{gap_text}' but could not extract replacement from references. {classification_reasoning}",
+                gap_category=self.category,
+                requires_human_review=True,
+                artist=self.artist,
+                title=self.title
+            )
+            return [proposal]
+

lyrics_transcriber/correction/agentic/models/__init__.py

@@ -0,0 +1,5 @@
+"""Models and schemas for agentic correction (to be implemented via TDD)."""
+
+__all__ = []
+
+

lyrics_transcriber/correction/agentic/models/ai_correction.py

@@ -0,0 +1,31 @@
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Optional
+
+from .enums import CorrectionType
+
+
+@dataclass
+class AICorrection:
+    id: str
+    original_text: str
+    corrected_text: str
+    confidence_score: float
+    reasoning: str
+    model_used: str
+    correction_type: CorrectionType
+    processing_time_ms: int
+    tokens_used: int
+    created_at: datetime
+    word_position: int
+    session_id: str
+
+    def validate(self) -> None:
+        if not (0.0 <= self.confidence_score <= 1.0):
+            raise ValueError("confidence_score must be between 0.0 and 1.0")
+        if self.original_text == self.corrected_text:
+            raise ValueError("original_text and corrected_text must differ")
+        if self.processing_time_ms <= 0:
+            raise ValueError("processing_time_ms must be positive")
+
+

lyrics_transcriber/correction/agentic/models/correction_session.py

@@ -0,0 +1,30 @@
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Optional, Dict
+
+from .enums import SessionType, SessionStatus
+
+
+@dataclass
+class CorrectionSession:
+    id: str
+    audio_file_hash: str
+    session_type: SessionType
+    ai_model_config: Dict[str, object]
+    total_corrections: int
+    accepted_corrections: int
+    human_modifications: int
+    session_duration_ms: int
+    accuracy_improvement: float
+    started_at: datetime
+    completed_at: Optional[datetime]
+    status: SessionStatus
+
+    def validate(self) -> None:
+        # Basic validations per data-model
+        if any(v < 0 for v in (self.total_corrections, self.accepted_corrections, self.human_modifications)):
+            raise ValueError("correction counts must be non-negative")
+        if self.completed_at is not None and self.completed_at < self.started_at:
+            raise ValueError("completed_at must be after started_at")
+
+

lyrics_transcriber/correction/agentic/models/enums.py

@@ -0,0 +1,38 @@
+from enum import Enum
+
+
+class CorrectionType(str, Enum):
+    WORD_SUBSTITUTION = "WORD_SUBSTITUTION"
+    WORD_INSERTION = "WORD_INSERTION"
+    WORD_DELETION = "WORD_DELETION"
+    PUNCTUATION = "PUNCTUATION"
+    TIMING_ADJUSTMENT = "TIMING_ADJUSTMENT"
+    LINGUISTIC_IMPROVEMENT = "LINGUISTIC_IMPROVEMENT"
+
+
+class ReviewerAction(str, Enum):
+    ACCEPT = "ACCEPT"
+    REJECT = "REJECT"
+    MODIFY = "MODIFY"
+
+
+class FeedbackCategory(str, Enum):
+    AI_CORRECT = "AI_CORRECT"
+    AI_INCORRECT = "AI_INCORRECT"
+    AI_SUBOPTIMAL = "AI_SUBOPTIMAL"
+    CONTEXT_NEEDED = "CONTEXT_NEEDED"
+    SUBJECTIVE_PREFERENCE = "SUBJECTIVE_PREFERENCE"
+
+
+class SessionType(str, Enum):
+    FULL_CORRECTION = "FULL_CORRECTION"
+    PARTIAL_REVIEW = "PARTIAL_REVIEW"
+    REPROCESSING = "REPROCESSING"
+
+
+class SessionStatus(str, Enum):
+    IN_PROGRESS = "IN_PROGRESS"
+    COMPLETED = "COMPLETED"
+    FAILED = "FAILED"
+
+

lyrics_transcriber/correction/agentic/models/human_feedback.py

@@ -0,0 +1,30 @@
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Optional
+
+from .enums import ReviewerAction, FeedbackCategory
+
+
+@dataclass
+class HumanFeedback:
+    id: str
+    ai_correction_id: str
+    reviewer_action: ReviewerAction
+    final_text: Optional[str]
+    reason_category: FeedbackCategory
+    reason_detail: Optional[str]
+    reviewer_confidence: float
+    review_time_ms: int
+    reviewer_id: Optional[str]
+    created_at: datetime
+    session_id: str
+
+    def validate(self) -> None:
+        if self.reviewer_action == ReviewerAction.MODIFY and not self.final_text:
+            raise ValueError("final_text required when action is MODIFY")
+        if self.reviewer_confidence is not None and not (0.0 <= self.reviewer_confidence <= 1.0):
+            raise ValueError("reviewer_confidence must be between 0.0 and 1.0")
+        if self.review_time_ms <= 0:
+            raise ValueError("review_time_ms must be positive")
+
+

lyrics_transcriber/correction/agentic/models/learning_data.py

@@ -0,0 +1,26 @@
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import Dict
+
+
+@dataclass
+class LearningData:
+    id: str
+    session_id: str
+    error_patterns: Dict[str, int]
+    correction_strategies: Dict[str, int]
+    model_performance: Dict[str, float]
+    feedback_trends: Dict[str, int]
+    improvement_metrics: Dict[str, float]
+    data_quality_score: float
+    created_at: datetime
+    expires_at: datetime
+
+    def validate(self) -> None:
+        if not (0.0 <= self.data_quality_score <= 1.0):
+            raise ValueError("data_quality_score must be between 0.0 and 1.0")
+        # Note: exact 3-year check depends on business rule; enforce >= 3 years
+        if (self.expires_at - self.created_at).days < 365 * 3:
+            raise ValueError("expires_at must be at least 3 years from created_at")
+
+

lyrics_transcriber/correction/agentic/models/observability_metrics.py

@@ -0,0 +1,28 @@
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Dict
+
+
+@dataclass
+class ObservabilityMetrics:
+    id: str
+    session_id: str
+    ai_correction_accuracy: float
+    processing_time_breakdown: Dict[str, int]
+    human_review_duration: int
+    model_response_times: Dict[str, int]
+    error_reduction_percentage: float
+    cost_tracking: Dict[str, float]
+    system_health_indicators: Dict[str, float]
+    improvement_trends: Dict[str, float]
+    recorded_at: datetime
+
+    def validate(self) -> None:
+        if not (0.0 <= self.ai_correction_accuracy <= 100.0):
+            raise ValueError("ai_correction_accuracy must be 0-100")
+        if not (0.0 <= self.error_reduction_percentage <= 100.0):
+            raise ValueError("error_reduction_percentage must be 0-100")
+        if self.human_review_duration < 0:
+            raise ValueError("human_review_duration must be non-negative")
+
+

lyrics_transcriber/correction/agentic/models/schemas.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from typing import Optional, List
+from pydantic import BaseModel, Field, conint, confloat
+from enum import Enum
+
+
+class GapCategory(str, Enum):
+    """Categories for gap classification in transcription correction."""
+    PUNCTUATION_ONLY = "PUNCTUATION_ONLY"
+    SOUND_ALIKE = "SOUND_ALIKE"
+    BACKGROUND_VOCALS = "BACKGROUND_VOCALS"
+    EXTRA_WORDS = "EXTRA_WORDS"
+    REPEATED_SECTION = "REPEATED_SECTION"
+    COMPLEX_MULTI_ERROR = "COMPLEX_MULTI_ERROR"
+    AMBIGUOUS = "AMBIGUOUS"
+    NO_ERROR = "NO_ERROR"
+
+
+class GapClassification(BaseModel):
+    """Classification result for a gap in the transcription."""
+    gap_id: str = Field(..., description="Unique identifier for the gap")
+    category: GapCategory = Field(..., description="Classification category")
+    confidence: confloat(ge=0.0, le=1.0) = Field(..., description="Confidence in classification (0-1)")
+    reasoning: str = Field(..., description="Explanation for the classification")
+    suggested_handler: Optional[str] = Field(None, description="Recommended handler for this gap")
+
+
+class CorrectionProposal(BaseModel):
+    word_id: Optional[str] = Field(None, description="ID of the word to correct")
+    word_ids: Optional[List[str]] = Field(None, description="IDs of multiple words when applicable")
+    action: str = Field(..., description="ReplaceWord|SplitWord|DeleteWord|AdjustTiming|NoAction|Flag")
+    replacement_text: Optional[str] = Field(None, description="Text to insert/replace with")
+    timing_delta_ms: Optional[conint(ge=-1000, le=1000)] = None
+    confidence: confloat(ge=0.0, le=1.0) = 0.0
+    reason: str = Field(..., description="Short rationale for the proposal")
+    gap_category: Optional[GapCategory] = Field(None, description="Classification category of the gap")
+    requires_human_review: bool = Field(False, description="Whether this proposal needs human review")
+    artist: Optional[str] = Field(None, description="Song artist for context")
+    title: Optional[str] = Field(None, description="Song title for context")
+
+
+class CorrectionProposalList(BaseModel):
+    proposals: List[CorrectionProposal]
+
+

lyrics_transcriber/correction/agentic/models/utils.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from dataclasses import asdict, is_dataclass
+from typing import Any, Dict
+
+
+def to_serializable_dict(obj: Any) -> Dict[str, Any]:
+    """Serialize dataclass or dict-like object to a plain dict for JSON.
+
+    This avoids pulling in runtime deps for Pydantic here; enforcement occurs in
+    workflow layers using Instructor/pydantic-ai as per guidance.
+    """
+    if is_dataclass(obj):
+        return asdict(obj)
+    if isinstance(obj, dict):
+        return obj
+    raise TypeError(f"Unsupported object type for serialization: {type(obj)!r}")
+
+

lyrics_transcriber/correction/agentic/observability/__init__.py

@@ -0,0 +1,5 @@
+"""Observability hooks and initialization for agentic correction."""
+
+__all__ = []
+
+