karaoke-gen 0.75.54__py3-none-any.whl

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__ = []
+
+

lyrics_transcriber/correction/agentic/observability/langfuse_integration.py

@@ -0,0 +1,35 @@
+from typing import Optional, Dict, Any
+import os
+import threading
+
+
+def setup_langfuse(client_name: str = "agentic-corrector") -> Optional[object]:
+    """Initialize Langfuse client if keys are present; return client or None.
+
+    This avoids hard dependency at import time; caller can check for None and
+    no-op if observability is not configured.
+    """
+    secret = os.getenv("LANGFUSE_SECRET_KEY")
+    public = os.getenv("LANGFUSE_PUBLIC_KEY")
+    host = os.getenv("LANGFUSE_HOST", "https://cloud.langfuse.com")
+    if not (secret and public):
+        return None
+    try:
+        from langfuse import Langfuse  # type: ignore
+
+        client = Langfuse(secret_key=secret, public_key=public, host=host, sdk_integration=client_name)
+        return client
+    except Exception:
+        return None
+
+
+def record_metrics(client: Optional[object], name: str, metrics: Dict[str, Any]) -> None:
+    """Record custom metrics to Langfuse if initialized."""
+    if client is None:
+        return
+    try:
+        # Minimal shape to avoid strict coupling; callers can extend
+        client.trace(name=name, metadata=metrics)
+    except Exception:
+        # Swallow observability errors to never impact core flow
+        pass

lyrics_transcriber/correction/agentic/observability/metrics.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, Any
+
+
+@dataclass
+class MetricsAggregator:
+    """In-memory metrics aggregator for agentic correction API."""
+
+    total_sessions: int = 0
+    total_processing_time_ms: int = 0
+    total_feedback: int = 0
+    model_counts: Dict[str, int] = field(default_factory=dict)
+    model_total_time_ms: Dict[str, int] = field(default_factory=dict)
+    fallback_count: int = 0
+
+    def record_session(self, model_id: str, processing_time_ms: int, fallback_used: bool) -> None:
+        self.total_sessions += 1
+        self.total_processing_time_ms += max(0, int(processing_time_ms))
+        if model_id:
+            self.model_counts[model_id] = self.model_counts.get(model_id, 0) + 1
+            self.model_total_time_ms[model_id] = self.model_total_time_ms.get(model_id, 0) + max(0, int(processing_time_ms))
+        if fallback_used:
+            self.fallback_count += 1
+
+    def record_feedback(self) -> None:
+        self.total_feedback += 1
+
+    def snapshot(self, time_range: str = "day", session_id: str | None = None) -> Dict[str, Any]:
+        avg_time = int(self.total_processing_time_ms / self.total_sessions) if self.total_sessions else 0
+        # Compute simple per-model avg latencies
+        per_model_avg = {m: int(self.model_total_time_ms.get(m, 0) / c) if c else 0 for m, c in self.model_counts.items()}
+        # Placeholders for accuracy/cost until we collect these
+        return {
+            "timeRange": time_range,
+            "totalSessions": self.total_sessions,
+            "averageAccuracy": 0.0,
+            "errorReduction": 0.0,
+            "averageProcessingTime": avg_time,
+            "modelPerformance": {"counts": self.model_counts, "avgLatencyMs": per_model_avg, "fallbacks": self.fallback_count},
+            "costSummary": {},
+            "userSatisfaction": 0.0,
+        }
+
+

lyrics_transcriber/correction/agentic/observability/performance.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import time
+from contextlib import contextmanager
+from typing import Iterator
+
+
+@contextmanager
+def timer() -> Iterator[float]:
+    start = time.time()
+    try:
+        yield start
+    finally:
+        pass
+
+def elapsed_ms(start: float) -> int:
+    return int((time.time() - start) * 1000)
+
+

lyrics_transcriber/correction/agentic/prompts/__init__.py

@@ -0,0 +1,2 @@
+"""Prompt templates for agentic correction."""
+

lyrics_transcriber/correction/agentic/prompts/classifier.py

@@ -0,0 +1,227 @@
+"""Gap classification prompt builder for agentic correction."""
+
+from typing import Dict, List, Optional
+import yaml
+import os
+from pathlib import Path
+
+
+def load_few_shot_examples() -> Dict[str, List[Dict]]:
+    """Load few-shot examples from examples.yaml if it exists."""
+    examples_path = Path(__file__).parent / "examples.yaml"
+    
+    if not examples_path.exists():
+        return get_hardcoded_examples()
+    
+    try:
+        with open(examples_path, 'r') as f:
+            data = yaml.safe_load(f)
+            return data.get('examples_by_category', {})
+    except Exception:
+        return get_hardcoded_examples()
+
+
+def get_hardcoded_examples() -> Dict[str, List[Dict]]:
+    """Hardcoded examples from gaps_review.yaml for initial training."""
+    return {
+        "sound_alike": [
+            {
+                "gap_text": "out, I'm starting over",
+                "preceding": "Oh no, was it worth it? Starting",
+                "following": "gonna sleep With the next person",
+                "reference": "Starting now I'm starting over",
+                "reasoning": "Transcription heard 'out' but reference lyrics show 'now' - common sound-alike error",
+                "action": "REPLACE 'out' with 'now'"
+            },
+            {
+                "gap_text": "And you said to watch it",
+                "preceding": "You're a time, uh, uh, uh",
+                "following": "just in time But to wreck",
+                "reference": "You set the watch You're just in time",
+                "reasoning": "Transcription heard 'And you said to watch it' but reference shows 'You set the watch You're' - sound-alike with extra word 'And'",
+                "action": "REPLACE with reference text"
+            }
+        ],
+        "background_vocals": [
+            {
+                "gap_text": "it? (Big business)",
+                "preceding": "Oh no, was it worth it? Was it worth",
+                "following": "Was it worth it? (Was it worth",
+                "reference": "was it worth what you did to big business?",
+                "reasoning": "Words in parentheses are background vocals not in reference lyrics",
+                "action": "DELETE words in parentheses"
+            },
+            {
+                "gap_text": "(Was it worth it?) Was",
+                "preceding": "it? (Big business) Was it worth it?",
+                "following": "it worth it? (Your friends)",
+                "reference": "Was it worth what you did to big business?",
+                "reasoning": "Parenthesized phrase is backing vocal repetition",
+                "action": "DELETE parenthesized words"
+            }
+        ],
+        "extra_words": [
+            {
+                "gap_text": "But to wreck my life",
+                "preceding": "said to watch it just in time",
+                "following": "To bring back what I left",
+                "reference": "You're just in time To wreck my life",
+                "reasoning": "Transcription adds filler word 'But' not in reference lyrics",
+                "action": "DELETE 'But'"
+            }
+        ],
+        "punctuation_only": [
+            {
+                "gap_text": "Tick- tock, you're",
+                "preceding": "They got no, they got no concept of time",
+                "following": "not a clock You're a time bomb",
+                "reference": "Tick tock, you're not a clock",
+                "reasoning": "Only difference is hyphen in 'Tick-tock' vs 'Tick tock' - stylistic",
+                "action": "NO_ACTION"
+            }
+        ],
+        "no_error": [
+            {
+                "gap_text": "you're telling lies Well,",
+                "preceding": "You swore together forever Now",
+                "following": "tell me your words They got",
+                "reference_genius": "Now you're telling lies",
+                "reference_lrclib": "Now you're telling me lies",
+                "reasoning": "Genius reference matches transcription exactly (without 'me'), so transcription is correct",
+                "action": "NO_ACTION"
+            }
+        ],
+        "repeated_section": [
+            {
+                "gap_text": "You're a time bomb, baby You're",
+                "preceding": "Tick-tock, you're not a clock",
+                "following": "a time bomb, baby, oh",
+                "reference": "You're a time bomb baby",
+                "reasoning": "Reference lyrics don't show repetition, but cannot confirm without audio",
+                "action": "FLAG for human review"
+            }
+        ],
+        "complex_multi_error": [
+            {
+                "gap_text": "Right here, did you dance for later? That's what you said? Well, here's an answer You're out in life You have to try",
+                "reference": "Five years and you fell for a waiter I'm sure he says he's an actor So you're acting like",
+                "reasoning": "50-word gap with multiple sound-alike errors throughout, too complex for automatic correction",
+                "action": "FLAG for human review"
+            }
+        ]
+    }
+
+
+def build_classification_prompt(
+    gap_text: str,
+    preceding_words: str,
+    following_words: str,
+    reference_contexts: Dict[str, str],
+    artist: Optional[str] = None,
+    title: Optional[str] = None,
+    gap_id: Optional[str] = None
+) -> str:
+    """Build a prompt for classifying a gap in the transcription.
+    
+    Args:
+        gap_text: The text of the gap that needs classification
+        preceding_words: Text immediately before the gap
+        following_words: Text immediately after the gap
+        reference_contexts: Dictionary of reference lyrics from each source
+        artist: Song artist name for context
+        title: Song title for context
+        gap_id: Identifier for the gap
+    
+    Returns:
+        Formatted prompt string for the LLM
+    """
+    examples = load_few_shot_examples()
+    
+    # Build few-shot examples section
+    examples_text = "## Example Classifications\n\n"
+    for category, category_examples in examples.items():
+        if category_examples:
+            examples_text += f"### {category.upper().replace('_', ' ')}\n\n"
+            for ex in category_examples[:2]:  # Limit to 2 examples per category
+                examples_text += f"**Gap:** {ex['gap_text']}\n"
+                examples_text += f"**Context:** ...{ex.get('preceding', '')}... [GAP] ...{ex.get('following', '')}...\n"
+                if 'reference' in ex:
+                    examples_text += f"**Reference:** {ex['reference']}\n"
+                examples_text += f"**Reasoning:** {ex['reasoning']}\n"
+                examples_text += f"**Action:** {ex['action']}\n\n"
+    
+    # Build reference lyrics section
+    references_text = ""
+    if reference_contexts:
+        references_text = "## Available Reference Lyrics\n\n"
+        for source, context in reference_contexts.items():
+            references_text += f"**{source.upper()}:** {context}\n\n"
+    
+    # Build song context
+    song_context = ""
+    if artist and title:
+        song_context = f"\n## Song Context\n\n**Artist:** {artist}\n**Title:** {title}\n\nNote: The song title and artist name may help identify proper nouns or unusual words that could be mis-heard.\n"
+    
+    prompt = f"""You are an expert at analyzing transcription errors in song lyrics. Your task is to classify gaps (mismatches between transcription and reference lyrics) into categories to determine the best correction approach.
+
+{song_context}
+
+## Categories
+
+Use these EXACT category names in your response:
+
+1. **PUNCTUATION_ONLY**: Only difference is punctuation, capitalization, or symbols (hyphens, quotes). No text changes needed.
+
+2. **SOUND_ALIKE**: Transcription mis-heard words that sound similar (e.g., "out" vs "now", "said to watch" vs "set the watch"). Common for homophones or similar-sounding phrases.
+
+3. **BACKGROUND_VOCALS**: Transcription includes backing vocals (usually in parentheses) that aren't in the main reference lyrics. Should typically be removed for karaoke.
+
+4. **EXTRA_WORDS**: Transcription adds common filler words like "And", "But", "Well" at sentence starts that aren't in reference lyrics.
+
+5. **REPEATED_SECTION**: Transcription shows repeated chorus/lyrics that may or may not appear in condensed reference lyrics. Often needs human verification via audio.
+
+6. **COMPLEX_MULTI_ERROR**: Large gaps (many words) with multiple different error types. Too complex for automatic correction.
+
+7. **NO_ERROR**: At least one reference source matches the transcription exactly, indicating the transcription is correct and other references are incomplete/wrong.
+
+8. **AMBIGUOUS**: Cannot determine correct action without listening to audio. Similar to repeated sections but less clear.
+
+{examples_text}
+
+## Gap to Classify
+
+**Gap ID:** {gap_id or 'unknown'}
+
+**Preceding Context:** {preceding_words}
+
+**Gap Text:** {gap_text}
+
+**Following Context:** {following_words}
+
+{references_text}
+
+## Important Guidelines
+
+- If ANY reference source matches the gap text exactly (ignoring punctuation), classify as **NO_ERROR**
+- Consider whether the song title/artist contains words that might appear in the gap
+- Parentheses in transcription usually indicate background vocals
+- Sound-alike errors are very common in song transcription
+- Flag for human review when uncertain
+
+## Your Task
+
+Analyze this gap and respond with a JSON object matching this schema:
+
+{{
+  "gap_id": "{gap_id or 'unknown'}",
+  "category": "<one of the 8 categories above>",
+  "confidence": <float between 0 and 1>,
+  "reasoning": "<detailed explanation for your classification>",
+  "suggested_handler": "<name of handler or null>"
+}}
+
+Provide ONLY the JSON response, no other text.
+"""
+    
+    return prompt
+

lyrics_transcriber/correction/agentic/providers/__init__.py

@@ -0,0 +1,6 @@
+"""AI provider scaffolding for agentic correction (config, health checks)."""
+
+__all__ = [
+]
+
+

lyrics_transcriber/correction/agentic/providers/base.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import List, Dict, Any
+
+
+class BaseAIProvider(ABC):
+    """Abstract provider interface for generating correction proposals.
+
+    Implementations should honor timeouts and retry policies according to
+    ProviderConfig and return structured proposals validated upstream.
+    """
+
+    @abstractmethod
+    def name(self) -> str:
+        raise NotImplementedError
+
+    @abstractmethod
+    def generate_correction_proposals(
+        self, 
+        prompt: str, 
+        schema: Dict[str, Any],
+        session_id: str | None = None
+    ) -> List[Dict[str, Any]]:
+        """Return a list of correction proposals as dictionaries matching `schema`.
+
+        The schema is provided so implementations can guide structured outputs.
+        
+        Args:
+            prompt: The correction prompt
+            schema: JSON schema for the expected output structure
+            session_id: Optional Langfuse session ID for grouping traces
+        """
+        raise NotImplementedError
+
+

lyrics_transcriber/correction/agentic/providers/circuit_breaker.py

@@ -0,0 +1,145 @@
+"""Circuit breaker pattern implementation for AI provider reliability."""
+from __future__ import annotations
+
+import time
+import logging
+from typing import Dict
+
+from .config import ProviderConfig
+
+logger = logging.getLogger(__name__)
+
+
+class CircuitBreaker:
+    """Circuit breaker for protecting against cascading failures.
+    
+    Tracks failures per model and temporarily stops requests when
+    failure threshold is exceeded. Automatically resets after a timeout.
+    
+    Single Responsibility: Failure tracking and circuit state management only.
+    """
+    
+    def __init__(self, config: ProviderConfig):
+        """Initialize circuit breaker with configuration.
+        
+        Args:
+            config: Provider configuration with thresholds and timeouts
+        """
+        self._config = config
+        self._failures: Dict[str, int] = {}
+        self._open_until: Dict[str, float] = {}
+    
+    def is_open(self, model: str) -> bool:
+        """Check if circuit breaker is open for this model.
+        
+        An open circuit means requests should be rejected immediately
+        to prevent cascading failures.
+        
+        Args:
+            model: Model identifier to check
+            
+        Returns:
+            True if circuit is open (reject requests), False if closed (allow)
+        """
+        now = time.time()
+        open_until = self._open_until.get(model, 0)
+        
+        if now < open_until:
+            remaining = int(open_until - now)
+            logger.debug(
+                f"🤖 Circuit breaker open for {model}, "
+                f"retry in {remaining}s"
+            )
+            return True
+        
+        # Circuit was open but timeout expired - close it
+        if model in self._open_until:
+            logger.info(f"🤖 Circuit breaker closed for {model} (timeout expired)")
+            del self._open_until[model]
+            self._failures[model] = 0
+        
+        return False
+    
+    def get_open_until(self, model: str) -> float:
+        """Get timestamp when circuit will close for this model.
+        
+        Args:
+            model: Model identifier
+            
+        Returns:
+            Unix timestamp when circuit will close, or 0 if not open
+        """
+        return self._open_until.get(model, 0)
+    
+    def record_failure(self, model: str) -> None:
+        """Record a failure for this model and maybe open the circuit.
+        
+        Args:
+            model: Model identifier that failed
+        """
+        self._failures[model] = self._failures.get(model, 0) + 1
+        failure_count = self._failures[model]
+        
+        logger.debug(
+            f"🤖 Recorded failure for {model}, "
+            f"total: {failure_count}"
+        )
+        
+        # Check if we should open the circuit
+        threshold = self._config.circuit_breaker_failure_threshold
+        if failure_count >= threshold:
+            self._open_circuit(model)
+    
+    def record_success(self, model: str) -> None:
+        """Record a successful call and reset failure count.
+        
+        Args:
+            model: Model identifier that succeeded
+        """
+        if model in self._failures and self._failures[model] > 0:
+            logger.debug(
+                f"🤖 Reset failure count for {model} "
+                f"(was {self._failures[model]})"
+            )
+        self._failures[model] = 0
+    
+    def _open_circuit(self, model: str) -> None:
+        """Open the circuit breaker for this model.
+        
+        Args:
+            model: Model identifier to open circuit for
+        """
+        open_seconds = self._config.circuit_breaker_open_seconds
+        self._open_until[model] = time.time() + open_seconds
+        
+        logger.warning(
+            f"🤖 Circuit breaker opened for {model} "
+            f"({self._failures[model]} failures >= "
+            f"{self._config.circuit_breaker_failure_threshold} threshold), "
+            f"will retry in {open_seconds}s"
+        )
+    
+    def reset(self, model: str) -> None:
+        """Manually reset circuit breaker for a model.
+        
+        Useful for testing or administrative reset.
+        
+        Args:
+            model: Model identifier to reset
+        """
+        self._failures[model] = 0
+        if model in self._open_until:
+            del self._open_until[model]
+        logger.info(f"🤖 Circuit breaker manually reset for {model}")
+    
+    def get_failure_count(self, model: str) -> int:
+        """Get current failure count for a model.
+        
+        Args:
+            model: Model identifier
+            
+        Returns:
+            Number of consecutive failures
+        """
+        return self._failures.get(model, 0)
+