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

{karaoke_gen-0.81.1.dist-info → karaoke_gen-0.82.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: karaoke-gen
-Version: 0.81.1
+Version: 0.82.0
 Summary: Generate karaoke videos with synchronized lyrics. Handles the entire process from downloading audio and lyrics to creating the final video with title screens.
 License: MIT
 License-File: LICENSE
@@ -42,7 +42,7 @@ Requires-Dist: kbputils (>=0.0.16,<0.0.17)
 Requires-Dist: langchain (>=0.3.0)
 Requires-Dist: langchain-anthropic (>=0.2.0)
 Requires-Dist: langchain-core (>=0.3.0)
-Requires-Dist: langchain-google-vertexai (>=2.0.0)
+Requires-Dist: langchain-google-vertexai (>=3.1.1)
 Requires-Dist: langchain-ollama (>=0.2.0)
 Requires-Dist: langchain-openai (>=0.2.0)
 Requires-Dist: langfuse (>=3.0.0)

{karaoke_gen-0.81.1.dist-info → karaoke_gen-0.82.0.dist-info}/RECORD

@@ -75,29 +75,30 @@ lyrics_transcriber/correction/agentic/models/observability_metrics.py,sha256=xGd
 lyrics_transcriber/correction/agentic/models/schemas.py,sha256=skWXqGkJnv9NvmvjktBqrH_4Ohyzg2x0ZMsVINbXKdg,2141
 lyrics_transcriber/correction/agentic/models/utils.py,sha256=tX7flxCB4aLrgZWkHuEt7Gr8kaLkMsXzTdWSec6Xsts,580
 lyrics_transcriber/correction/agentic/observability/__init__.py,sha256=RuaepVsltWdaF1aF_YmNVJTJ6_bbNDFo3Sp-ruBvyHA,85
-lyrics_transcriber/correction/agentic/observability/langfuse_integration.py,sha256=GvgisZyy5_tDeC7Hd8SDWbd-9aAqYnMTd52uNeQ2p-I,1221
+lyrics_transcriber/correction/agentic/observability/langfuse_integration.py,sha256=5oBfoFT-QExZttD2wlIzXRhgSglNElFFwz8Et36vZos,7014
 lyrics_transcriber/correction/agentic/observability/metrics.py,sha256=Js_m6ljdI6Xgd9X9eHtboCsf9gjYsN1zOv3_XSwjgKk,1907
 lyrics_transcriber/correction/agentic/observability/performance.py,sha256=ekjzgL65gfs1SpKR_befu1wdWZU9xDlcafJm8htSvks,328
-lyrics_transcriber/correction/agentic/prompts/__init__.py,sha256=YPgEN82oygmT_pfIj2RpZM-WOLoFv6rBAPKeIRstXuI,48
-lyrics_transcriber/correction/agentic/prompts/classifier.py,sha256=pKbL4Cyj0-c_Ot9IxfKBOL7PnL0ZfUvKPLZwOMr-NDo,9730
+lyrics_transcriber/correction/agentic/prompts/__init__.py,sha256=riiZ-f4jlvq4QjtyCpmv-sSzfcLy7O99pMBwV1H5Usc,605
+lyrics_transcriber/correction/agentic/prompts/classifier.py,sha256=FwUSL59Y-5q9J1CDW8iyzyiajcy4-uq5MzfWu0If_Yo,11899
+lyrics_transcriber/correction/agentic/prompts/langfuse_prompts.py,sha256=hjQhyY_GBuZt_oY9DacutXvA9dJCZksRY2fKmveJm_A,10898
 lyrics_transcriber/correction/agentic/providers/__init__.py,sha256=PS7C4sKDfa6S9lSo33GXIRamCLsv0Jn7u0GtXuhiRD4,95
 lyrics_transcriber/correction/agentic/providers/base.py,sha256=bExuntMLLInMmWWNzN81_ScWQJhNYbtlF3wZYhlX-qw,1059
 lyrics_transcriber/correction/agentic/providers/circuit_breaker.py,sha256=D3Jg4YHqvy4gzlxfkALa7PztyYQpJb8NwJAonMS0TSI,4694
-lyrics_transcriber/correction/agentic/providers/config.py,sha256=2dy9zynj8hU3LdRkb2RmKSOztsX4_Ay23EU-RfUGCrM,3206
-lyrics_transcriber/correction/agentic/providers/constants.py,sha256=aDIEsDvNQLEGlGk8klAaRxJmdldGBDFqwYLuCmlYoNM,692
+lyrics_transcriber/correction/agentic/providers/config.py,sha256=w6-fkapEy3BgoFIsRfZ44XUCV4zuicFSNoSoVAe5lYE,3282
+lyrics_transcriber/correction/agentic/providers/constants.py,sha256=cXLzKTyFVt9q6wQd_gWcv3EZ5Sm27AOAz6NyPapcess,695
 lyrics_transcriber/correction/agentic/providers/health.py,sha256=F8pHY5BQYvylGRDGXUHplcAJooAyiqVLRhBl4kHC1H8,710
-lyrics_transcriber/correction/agentic/providers/langchain_bridge.py,sha256=hderNRLrSZn49LrGBrgdCvBP5E7tPAugjaw7TFbb0JY,7957
-lyrics_transcriber/correction/agentic/providers/model_factory.py,sha256=iKbpMEeTyhPN8n9abVf645TfovnFEz3ia1g6XLHqp4s,8613
+lyrics_transcriber/correction/agentic/providers/langchain_bridge.py,sha256=H3C3BNjAixfkOJojxWXv-P-svlgj5rJEJdk0zPIjh7E,8540
+lyrics_transcriber/correction/agentic/providers/model_factory.py,sha256=CeVDblf1HdphtUHVn3Cgl07YAeUuSxTjEHHFJN8Frj0,8257
 lyrics_transcriber/correction/agentic/providers/response_cache.py,sha256=Byr7fQJsgUMFlsvHeVCxTiFjjnbsg3KIlEmEEtAo-Gw,7047
 lyrics_transcriber/correction/agentic/providers/response_parser.py,sha256=a8pdUYKBS5X72gck3u1ndFYB__UN0UijAdxNhbHp8ZQ,3809
 lyrics_transcriber/correction/agentic/providers/retry_executor.py,sha256=hX21Zwy2cSECAw7k13ndEinWRqwjo4xYoSCQ2B2CUf0,3912
-lyrics_transcriber/correction/agentic/router.py,sha256=_JtnXgcIdui6qeN9x0EawThDGZavAwfpbtEJAYVlQTY,1334
+lyrics_transcriber/correction/agentic/router.py,sha256=akP28A0lftmsnSyMOW6k7iTC1pv4LEgilXhIkcfJzlE,1437
 lyrics_transcriber/correction/agentic/workflows/__init__.py,sha256=OsBExAbIIKxJgX6FKXFOgcUjIG9AWJQV_fESZVdO8mo,77
 lyrics_transcriber/correction/agentic/workflows/consensus_workflow.py,sha256=gMuLTUxkgYaciMsI4yrZSC3wi--7V_PgaDNE-Vd6FE8,575
 lyrics_transcriber/correction/agentic/workflows/correction_graph.py,sha256=kgZKnz0h9cG1EfhW7BSSl-kSpQtJrRM_S86kAniXfE4,1815
 lyrics_transcriber/correction/agentic/workflows/feedback_workflow.py,sha256=KsKLD3AP66YYmXfUn-mVZjERYLtU1Zs4a-7CB2zDfas,596
 lyrics_transcriber/correction/anchor_sequence.py,sha256=5tl4Cjiw5UlLbEb1Oy-g3ebKCinXSwohdaCB9-rTMtI,43798
-lyrics_transcriber/correction/corrector.py,sha256=e8N7Yys6MCmz8PbHkkl7KuxH1m3MWlH1vwCa1r3YcqA,40223
+lyrics_transcriber/correction/corrector.py,sha256=qW6GwOOLM8zxYtYMmGy9Rzk_4mJzdpGiCXW3LQFXn14,38362
 lyrics_transcriber/correction/feedback/__init__.py,sha256=i1gd0Vb4qvlzZQ3lqA3fJjt288YP7f-MBPwOzZ7Rjh4,68
 lyrics_transcriber/correction/feedback/schemas.py,sha256=OiF_WUqcqiEKIoburYM8kWAIundy82PQE7ImsdP8UCk,4416
 lyrics_transcriber/correction/feedback/store.py,sha256=T4IDzf1eRA9n-wdLLrLyAW1ELYgXwK9RikJgX_B3fN8,8788
@@ -105,8 +106,6 @@ lyrics_transcriber/correction/handlers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JC
 lyrics_transcriber/correction/handlers/base.py,sha256=ZXYMFgbCmlD62dpqdFwFPlcePdHKEFrABffnG_Mu5mI,1687
 lyrics_transcriber/correction/handlers/extend_anchor.py,sha256=IADgdPmEMokUQhh6mP-wQWLYf6GfWTvJbBjOk08A-aw,6384
 lyrics_transcriber/correction/handlers/levenshtein.py,sha256=hMERQHVgiUDSHtamYrAjqZ3qMMok4VmQ_MYM2-nrX6w,7864
-lyrics_transcriber/correction/handlers/llm.py,sha256=ufqHtohdU5dUXE3DikzbloAWGVgMu1wnw6P4WHRmpdk,14580
-lyrics_transcriber/correction/handlers/llm_providers.py,sha256=MV-KCRseccg-DEimMS0D2bXJ2xhy59r2n8UZjICUoEY,2067
 lyrics_transcriber/correction/handlers/no_space_punct_match.py,sha256=jY2fa547Qc8B63xIhF9VyWMaq5jds6E6wBqyVq6KANw,7057
 lyrics_transcriber/correction/handlers/relaxed_word_count_match.py,sha256=x4k__6gav4-STk_TycLcg5Sw4x2vUFAj5fWmOv7Yd_w,3911
 lyrics_transcriber/correction/handlers/repeat.py,sha256=1PJADW44egYh7N9D2fN-gDIusWVglFjGHrCZuTQYNpA,4313
@@ -287,8 +286,8 @@ lyrics_transcriber/transcribers/whisper.py,sha256=YcCB1ic9H6zL1GS0jD0emu8-qlcH0Q
 lyrics_transcriber/types.py,sha256=UJjaxhVd2o14AG4G8ToU598p0JeYdiTFjpG38jGCoYQ,27917
 lyrics_transcriber/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 lyrics_transcriber/utils/word_utils.py,sha256=-cMGpj9UV4F6IsoDKAV2i1aiqSO8eI91HMAm_igtVMk,958
-karaoke_gen-0.81.1.dist-info/METADATA,sha256=zA3O3rRKeXu_LX28aeN3knlhx3WcpXD8Ozf4s_LT2C0,23077
-karaoke_gen-0.81.1.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-karaoke_gen-0.81.1.dist-info/entry_points.txt,sha256=xIyLe7K84ZyjO8L0_AmNectz93QjGSs5AkApMtlAd4g,160
-karaoke_gen-0.81.1.dist-info/licenses/LICENSE,sha256=81R_4XwMZDODHD7JcZeUR8IiCU8AD7Ajl6bmwR9tYDk,1074
-karaoke_gen-0.81.1.dist-info/RECORD,,
+karaoke_gen-0.82.0.dist-info/METADATA,sha256=k51l0dhnVIM5kn6lFbTCLi1oKbcV_2iSulloMXVkU0Q,23077
+karaoke_gen-0.82.0.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+karaoke_gen-0.82.0.dist-info/entry_points.txt,sha256=xIyLe7K84ZyjO8L0_AmNectz93QjGSs5AkApMtlAd4g,160
+karaoke_gen-0.82.0.dist-info/licenses/LICENSE,sha256=81R_4XwMZDODHD7JcZeUR8IiCU8AD7Ajl6bmwR9tYDk,1074
+karaoke_gen-0.82.0.dist-info/RECORD,,

lyrics_transcriber/correction/agentic/observability/langfuse_integration.py

@@ -1,28 +1,115 @@
-from typing import Optional, Dict, Any
+"""LangFuse integration for agentic correction observability and prompt management.
+
+This module provides:
+- Client initialization with fail-fast behavior when configured
+- Metrics recording for observability
+- Prompt fetching for dynamic prompt management
+- Dataset fetching for few-shot examples
+"""
+
+from typing import Optional, Dict, Any, List
 import os
-import threading
+import logging
+
+logger = logging.getLogger(__name__)
+
+# Module-level client singleton
+_langfuse_client: Optional[Any] = None
+_client_initialized: bool = False
+
+
+class LangFuseConfigError(Exception):
+    """Raised when LangFuse is configured but initialization fails."""
+    pass
+
 
+def is_langfuse_configured() -> bool:
+    """Check if LangFuse credentials are configured in environment."""
+    public_key = os.getenv("LANGFUSE_PUBLIC_KEY")
+    secret_key = os.getenv("LANGFUSE_SECRET_KEY")
+    return bool(public_key and secret_key)
 
-def setup_langfuse(client_name: str = "agentic-corrector") -> Optional[object]:
+
+def setup_langfuse() -> 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.
+
+    Note: This function does NOT fail fast - use get_langfuse_client() for
+    fail-fast behavior when LangFuse is required.
     """
     secret = os.getenv("LANGFUSE_SECRET_KEY")
     public = os.getenv("LANGFUSE_PUBLIC_KEY")
-    host = os.getenv("LANGFUSE_HOST", "https://cloud.langfuse.com")
+    host = os.getenv("LANGFUSE_HOST", "https://us.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)
+        client = Langfuse(secret_key=secret, public_key=public, host=host)
         return client
     except Exception:
         return None
 
 
+def get_langfuse_client() -> Optional[Any]:
+    """Get or create the LangFuse client singleton.
+
+    Unlike setup_langfuse(), this function implements fail-fast behavior:
+    if LangFuse keys are configured but initialization fails, it raises
+    an exception rather than returning None.
+
+    Returns:
+        Langfuse client instance, or None if not configured
+
+    Raises:
+        LangFuseConfigError: If keys are set but initialization fails
+    """
+    global _langfuse_client, _client_initialized
+
+    if _client_initialized:
+        return _langfuse_client
+
+    secret = os.getenv("LANGFUSE_SECRET_KEY")
+    public = os.getenv("LANGFUSE_PUBLIC_KEY")
+    host = os.getenv("LANGFUSE_HOST", "https://us.cloud.langfuse.com")
+
+    if not (secret and public):
+        logger.debug("LangFuse keys not configured, client disabled")
+        _client_initialized = True
+        return None
+
+    try:
+        from langfuse import Langfuse
+
+        _langfuse_client = Langfuse(
+            secret_key=secret,
+            public_key=public,
+            host=host,
+        )
+        _client_initialized = True
+        logger.info(f"LangFuse client initialized (host: {host})")
+        return _langfuse_client
+
+    except Exception as e:
+        # Fail fast - if keys are set, we expect LangFuse to work
+        raise LangFuseConfigError(
+            f"LangFuse keys are set but initialization failed: {e}\n"
+            f"Check:\n"
+            f"  - LANGFUSE_PUBLIC_KEY: {public[:10] if public else 'not set'}...\n"
+            f"  - LANGFUSE_SECRET_KEY: {'set' if secret else 'not set'}\n"
+            f"  - LANGFUSE_HOST: {host}"
+        ) from e
+
+
+def reset_langfuse_client() -> None:
+    """Reset the global LangFuse client (for testing)."""
+    global _langfuse_client, _client_initialized
+    _langfuse_client = None
+    _client_initialized = False
+
+
 def record_metrics(client: Optional[object], name: str, metrics: Dict[str, Any]) -> None:
     """Record custom metrics to Langfuse if initialized."""
     if client is None:
@@ -33,3 +120,89 @@ def record_metrics(client: Optional[object], name: str, metrics: Dict[str, Any])
     except Exception:
         # Swallow observability errors to never impact core flow
         pass
+
+
+def fetch_prompt(name: str, client: Optional[Any] = None, label: Optional[str] = "production") -> Any:
+    """Fetch a prompt template from LangFuse.
+
+    Args:
+        name: The prompt name in LangFuse
+        client: Optional pre-initialized client. If None, uses get_langfuse_client()
+        label: Prompt label to fetch (default: "production"). If the labeled version
+               is not found, falls back to version 1.
+
+    Returns:
+        LangFuse prompt object
+
+    Raises:
+        LangFuseConfigError: If LangFuse is not configured
+        RuntimeError: If prompt fetch fails
+    """
+    if client is None:
+        client = get_langfuse_client()
+
+    if client is None:
+        raise LangFuseConfigError(
+            f"Cannot fetch prompt '{name}': LangFuse is not configured. "
+            f"Set LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY."
+        )
+
+    try:
+        # Try to fetch with the specified label (default: production)
+        prompt = client.get_prompt(name, label=label)
+        logger.debug(f"Fetched prompt '{name}' (label={label}) from LangFuse")
+        return prompt
+    except Exception as label_error:
+        # If labeled version not found, try fetching version 1 as fallback
+        # This handles newly created prompts that haven't been promoted yet
+        try:
+            prompt = client.get_prompt(name, version=1)
+            logger.warning(
+                f"Prompt '{name}' label '{label}' not found, using version 1. "
+                f"Consider promoting this prompt in LangFuse UI."
+            )
+            return prompt
+        except Exception as version_error:
+            raise RuntimeError(
+                f"Failed to fetch prompt '{name}' from LangFuse: "
+                f"Label '{label}' error: {label_error}, "
+                f"Version 1 fallback error: {version_error}"
+            ) from version_error
+
+
+def fetch_dataset(name: str, client: Optional[Any] = None) -> List[Dict[str, Any]]:
+    """Fetch a dataset from LangFuse and return its items.
+
+    Args:
+        name: The dataset name in LangFuse
+        client: Optional pre-initialized client. If None, uses get_langfuse_client()
+
+    Returns:
+        List of dataset item inputs (the actual example data)
+
+    Raises:
+        LangFuseConfigError: If LangFuse is not configured
+        RuntimeError: If dataset fetch fails
+    """
+    if client is None:
+        client = get_langfuse_client()
+
+    if client is None:
+        raise LangFuseConfigError(
+            f"Cannot fetch dataset '{name}': LangFuse is not configured. "
+            f"Set LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY."
+        )
+
+    try:
+        dataset = client.get_dataset(name)
+        items = []
+        for item in dataset.items:
+            if hasattr(item, 'input') and item.input:
+                items.append(item.input)
+
+        logger.debug(f"Fetched {len(items)} items from dataset '{name}'")
+        return items
+    except Exception as e:
+        raise RuntimeError(
+            f"Failed to fetch dataset '{name}' from LangFuse: {e}"
+        ) from e

lyrics_transcriber/correction/agentic/prompts/__init__.py

@@ -1,2 +1,25 @@
 """Prompt templates for agentic correction."""
 
+from .classifier import (
+    build_classification_prompt,
+    build_classification_prompt_hardcoded,
+    get_hardcoded_examples,
+)
+from .langfuse_prompts import (
+    LangFusePromptService,
+    LangFusePromptError,
+    LangFuseDatasetError,
+    get_prompt_service,
+    reset_prompt_service,
+)
+
+__all__ = [
+    "build_classification_prompt",
+    "build_classification_prompt_hardcoded",
+    "get_hardcoded_examples",
+    "LangFusePromptService",
+    "LangFusePromptError",
+    "LangFuseDatasetError",
+    "get_prompt_service",
+    "reset_prompt_service",
+]

lyrics_transcriber/correction/agentic/prompts/classifier.py

@@ -1,23 +1,35 @@
-"""Gap classification prompt builder for agentic correction."""
+"""Gap classification prompt builder for agentic correction.
+
+This module provides two modes of operation:
+1. LangFuse mode: Prompts and examples fetched from LangFuse for dynamic iteration
+2. Hardcoded mode: Fallback for local development when LangFuse is not configured
+
+The main entry point is `build_classification_prompt()` which automatically
+selects the appropriate mode based on LangFuse configuration.
+"""
 
 from typing import Dict, List, Optional
 import yaml
 import os
+import logging
 from pathlib import Path
 
+logger = logging.getLogger(__name__)
+
 
 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:
+    except Exception as e:
+        logger.warning(f"Failed to load examples.yaml, using hardcoded examples: {e}")
         return get_hardcoded_examples()
 
 
@@ -122,7 +134,12 @@ def build_classification_prompt(
     gap_id: Optional[str] = None
 ) -> str:
     """Build a prompt for classifying a gap in the transcription.
-    
+
+    This function automatically selects between LangFuse and hardcoded prompts:
+    - If LangFuse is configured (LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY set),
+      fetches the prompt template and examples from LangFuse.
+    - Otherwise, uses hardcoded prompts for local development.
+
     Args:
         gap_text: The text of the gap that needs classification
         preceding_words: Text immediately before the gap
@@ -131,7 +148,50 @@ def build_classification_prompt(
         artist: Song artist name for context
         title: Song title for context
         gap_id: Identifier for the gap
-    
+
+    Returns:
+        Formatted prompt string for the LLM
+
+    Raises:
+        LangFusePromptError: If LangFuse is configured but prompt fetch fails
+    """
+    from .langfuse_prompts import get_prompt_service
+
+    service = get_prompt_service()
+    return service.get_classification_prompt(
+        gap_text=gap_text,
+        preceding_words=preceding_words,
+        following_words=following_words,
+        reference_contexts=reference_contexts,
+        artist=artist,
+        title=title,
+        gap_id=gap_id
+    )
+
+
+def build_classification_prompt_hardcoded(
+    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 using hardcoded templates.
+
+    This is the fallback implementation used when LangFuse is not configured.
+    It is also used as the source of truth for migrating prompts to LangFuse.
+
+    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
     """

lyrics_transcriber/correction/agentic/prompts/langfuse_prompts.py

@@ -0,0 +1,298 @@
+"""LangFuse prompt management for agentic correction.
+
+This module provides prompt fetching from LangFuse, enabling dynamic prompt
+iteration without code redeployment.
+"""
+
+from typing import Dict, List, Optional, Any
+import logging
+import os
+
+logger = logging.getLogger(__name__)
+
+
+class LangFusePromptError(Exception):
+    """Raised when LangFuse prompt fetching fails."""
+    pass
+
+
+class LangFuseDatasetError(Exception):
+    """Raised when LangFuse dataset fetching fails."""
+    pass
+
+
+class LangFusePromptService:
+    """Fetches prompts and datasets from LangFuse for agentic correction.
+
+    This service handles:
+    - Fetching prompt templates from LangFuse
+    - Fetching few-shot examples from LangFuse datasets
+    - Compiling prompts with dynamic variables
+    - Fail-fast behavior when LangFuse is configured but unavailable
+
+    When LangFuse keys are not configured, falls back to hardcoded prompts
+    for local development.
+    """
+
+    # Prompt and dataset names in LangFuse
+    CLASSIFIER_PROMPT_NAME = "gap-classifier"
+    EXAMPLES_DATASET_NAME = "gap-classifier-examples"
+
+    def __init__(self, client: Optional[Any] = None):
+        """Initialize the prompt service.
+
+        Args:
+            client: Optional pre-initialized Langfuse client (for testing).
+                   If None, will initialize from environment variables.
+        """
+        self._client = client
+        self._initialized = False
+        self._use_langfuse = self._should_use_langfuse()
+
+        if self._use_langfuse and client is None:
+            self._init_client()
+
+    def _should_use_langfuse(self) -> bool:
+        """Check if LangFuse credentials are configured."""
+        public_key = os.getenv("LANGFUSE_PUBLIC_KEY")
+        secret_key = os.getenv("LANGFUSE_SECRET_KEY")
+        return bool(public_key and secret_key)
+
+    def _init_client(self) -> None:
+        """Initialize the Langfuse client using the shared singleton."""
+        from ..observability.langfuse_integration import get_langfuse_client, LangFuseConfigError
+
+        try:
+            self._client = get_langfuse_client()
+            if self._client:
+                self._initialized = True
+                logger.info("LangFuse prompt service initialized")
+            else:
+                logger.debug("LangFuse keys not configured, will use hardcoded prompts")
+        except LangFuseConfigError as e:
+            # Re-raise as RuntimeError for consistent error handling
+            raise RuntimeError(str(e)) from e
+
+    def get_classification_prompt(
+        self,
+        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:
+        """Fetch and compile the gap classification prompt.
+
+        If LangFuse is configured, fetches the prompt template and examples
+        from LangFuse. Otherwise, falls back to hardcoded prompts.
+
+        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:
+            Compiled prompt string ready for LLM
+
+        Raises:
+            LangFusePromptError: If LangFuse is configured but prompt fetch fails
+        """
+        if not self._use_langfuse:
+            # Fall back to hardcoded prompt for development
+            from .classifier import build_classification_prompt_hardcoded
+            return build_classification_prompt_hardcoded(
+                gap_text=gap_text,
+                preceding_words=preceding_words,
+                following_words=following_words,
+                reference_contexts=reference_contexts,
+                artist=artist,
+                title=title,
+                gap_id=gap_id
+            )
+
+        # Fetch from LangFuse
+        try:
+            prompt_template = self._fetch_prompt(self.CLASSIFIER_PROMPT_NAME)
+            examples = self._fetch_examples()
+
+            # Build component strings
+            song_context = self._build_song_context(artist, title)
+            examples_text = self._format_examples(examples)
+            references_text = self._format_references(reference_contexts)
+
+            # Compile the prompt with variables
+            compiled = prompt_template.compile(
+                song_context=song_context,
+                examples_text=examples_text,
+                gap_id=gap_id or "unknown",
+                preceding_words=preceding_words,
+                gap_text=gap_text,
+                following_words=following_words,
+                references_text=references_text
+            )
+
+            logger.debug(f"Compiled LangFuse prompt for gap {gap_id}")
+            return compiled
+
+        except Exception as e:
+            raise LangFusePromptError(
+                f"Failed to fetch/compile prompt from LangFuse: {e}"
+            ) from e
+
+    def _fetch_prompt(self, name: str, label: str = "production") -> Any:
+        """Fetch a prompt template from LangFuse.
+
+        Args:
+            name: The prompt name in LangFuse
+            label: Prompt label to fetch (default: "production"). Falls back to
+                   version 1 if labeled version not found.
+
+        Returns:
+            LangFuse prompt object
+
+        Raises:
+            LangFusePromptError: If fetch fails
+        """
+        if not self._client:
+            raise LangFusePromptError("LangFuse client not initialized")
+
+        try:
+            # Try to fetch with the specified label (default: production)
+            prompt = self._client.get_prompt(name, label=label)
+            logger.debug(f"Fetched prompt '{name}' (label={label}) from LangFuse")
+            return prompt
+        except Exception as label_error:
+            # If labeled version not found, try fetching version 1 as fallback
+            # This handles newly created prompts that haven't been promoted yet
+            try:
+                prompt = self._client.get_prompt(name, version=1)
+                logger.warning(
+                    f"Prompt '{name}' label '{label}' not found, using version 1. "
+                    f"Consider promoting this prompt in LangFuse UI."
+                )
+                return prompt
+            except Exception as version_error:
+                raise LangFusePromptError(
+                    f"Failed to fetch prompt '{name}' from LangFuse: "
+                    f"Label '{label}' error: {label_error}, "
+                    f"Version 1 fallback error: {version_error}"
+                ) from version_error
+
+    def _fetch_examples(self) -> List[Dict[str, Any]]:
+        """Fetch few-shot examples from LangFuse dataset.
+
+        Returns:
+            List of example dictionaries
+
+        Raises:
+            LangFuseDatasetError: If fetch fails
+        """
+        if not self._client:
+            raise LangFuseDatasetError("LangFuse client not initialized")
+
+        try:
+            dataset = self._client.get_dataset(self.EXAMPLES_DATASET_NAME)
+            examples = []
+            for item in dataset.items:
+                # Dataset items have 'input' field with the example data
+                if hasattr(item, 'input') and item.input:
+                    examples.append(item.input)
+
+            logger.debug(f"Fetched {len(examples)} examples from LangFuse dataset")
+            return examples
+        except Exception as e:
+            raise LangFuseDatasetError(
+                f"Failed to fetch dataset '{self.EXAMPLES_DATASET_NAME}' from LangFuse: {e}"
+            ) from e
+
+    def _build_song_context(self, artist: Optional[str], title: Optional[str]) -> str:
+        """Build song context section for the prompt."""
+        if artist and title:
+            return (
+                f"\n## Song Context\n\n"
+                f"**Artist:** {artist}\n"
+                f"**Title:** {title}\n\n"
+                f"Note: The song title and artist name may help identify proper nouns "
+                f"or unusual words that could be mis-heard.\n"
+            )
+        return ""
+
+    def _format_examples(self, examples: List[Dict[str, Any]]) -> str:
+        """Format few-shot examples for inclusion in prompt.
+
+        Args:
+            examples: List of example dictionaries from LangFuse dataset
+
+        Returns:
+            Formatted examples string
+        """
+        if not examples:
+            return ""
+
+        # Group examples by category
+        examples_by_category: Dict[str, List[Dict]] = {}
+        for ex in examples:
+            category = ex.get("category", "unknown")
+            if category not in examples_by_category:
+                examples_by_category[category] = []
+            examples_by_category[category].append(ex)
+
+        # Build formatted text
+        text = "## Example Classifications\n\n"
+        for category, category_examples in examples_by_category.items():
+            text += f"### {category.upper().replace('_', ' ')}\n\n"
+            for ex in category_examples[:2]:  # Limit to 2 examples per category
+                text += f"**Gap:** {ex.get('gap_text', '')}\n"
+                text += f"**Context:** ...{ex.get('preceding', '')}... [GAP] ...{ex.get('following', '')}...\n"
+                if 'reference' in ex:
+                    text += f"**Reference:** {ex['reference']}\n"
+                text += f"**Reasoning:** {ex.get('reasoning', '')}\n"
+                text += f"**Action:** {ex.get('action', '')}\n\n"
+
+        return text
+
+    def _format_references(self, reference_contexts: Dict[str, str]) -> str:
+        """Format reference lyrics for inclusion in prompt.
+
+        Args:
+            reference_contexts: Dictionary of reference lyrics from each source
+
+        Returns:
+            Formatted references string
+        """
+        if not reference_contexts:
+            return ""
+
+        text = "## Available Reference Lyrics\n\n"
+        for source, context in reference_contexts.items():
+            text += f"**{source.upper()}:** {context}\n\n"
+
+        return text
+
+
+# Module-level singleton for convenience
+_prompt_service: Optional[LangFusePromptService] = None
+
+
+def get_prompt_service() -> LangFusePromptService:
+    """Get or create the global prompt service instance.
+
+    Returns:
+        LangFusePromptService singleton instance
+    """
+    global _prompt_service
+    if _prompt_service is None:
+        _prompt_service = LangFusePromptService()
+    return _prompt_service
+
+
+def reset_prompt_service() -> None:
+    """Reset the global prompt service instance (for testing)."""
+    global _prompt_service
+    _prompt_service = None

lyrics_transcriber/correction/agentic/providers/config.py

@@ -19,8 +19,9 @@ class ProviderConfig:
     cache_dir: str
 
     # GCP/Vertex AI settings
+    # Note: Gemini 3 models require 'global' location (not regional like us-central1)
     gcp_project_id: Optional[str] = None
-    gcp_location: str = "us-central1"
+    gcp_location: str = "global"
 
     request_timeout_seconds: float = 30.0
     max_retries: int = 2
@@ -51,7 +52,7 @@ class ProviderConfig:
             privacy_mode=os.getenv("PRIVACY_MODE", "false").lower() in {"1", "true", "yes"},
             cache_dir=cache_dir,
             gcp_project_id=os.getenv("GOOGLE_CLOUD_PROJECT") or os.getenv("GCP_PROJECT_ID"),
-            gcp_location=os.getenv("GCP_LOCATION", "us-central1"),
+            gcp_location=os.getenv("GCP_LOCATION", "global"),
             request_timeout_seconds=float(os.getenv("AGENTIC_TIMEOUT_SECONDS", "30.0")),
             max_retries=int(os.getenv("AGENTIC_MAX_RETRIES", "2")),
             retry_backoff_base_seconds=float(os.getenv("AGENTIC_BACKOFF_BASE_SECONDS", "0.2")),

lyrics_transcriber/correction/agentic/providers/constants.py

@@ -8,7 +8,7 @@ RESPONSE_LOG_LENGTH = 500  # Characters to log from responses
 MODEL_SPEC_FORMAT = "provider/model"  # Expected format for model identifiers
 
 # Default Langfuse host
-DEFAULT_LANGFUSE_HOST = "https://cloud.langfuse.com"
+DEFAULT_LANGFUSE_HOST = "https://us.cloud.langfuse.com"
 
 # Raw response indicator
 RAW_RESPONSE_KEY = "raw"  # Key used to wrap unparsed responses

lyrics_transcriber/correction/agentic/providers/langchain_bridge.py

@@ -187,26 +187,41 @@ class LangChainBridge(BaseAIProvider):
     
     def _invoke_model(self, prompt: str) -> str:
         """Invoke the chat model with a prompt.
-        
+
         This is a simple wrapper that can be passed to the retry executor.
-        
+
         Args:
             prompt: The prompt to send
-            
+
         Returns:
             Response content as string
-            
+
         Raises:
             Exception: Any error from the model invocation
         """
         from langchain_core.messages import HumanMessage
-        
+
         # Prepare config with session_id in metadata (Langfuse format)
         config = {}
         if hasattr(self, '_session_id') and self._session_id:
             config["metadata"] = {"langfuse_session_id": self._session_id}
             logger.debug(f"🤖 [LangChain] Invoking with session_id: {self._session_id}")
-        
+
         response = self._chat_model.invoke([HumanMessage(content=prompt)], config=config)
-        return response.content
+        content = response.content
+
+        # Handle multimodal response format from Gemini 3+ models
+        # Response can be a list of content parts: [{'type': 'text', 'text': '...'}]
+        if isinstance(content, list):
+            # Extract text from the first text content part
+            for part in content:
+                if isinstance(part, dict) and part.get('type') == 'text':
+                    return part.get('text', '')
+            # Fallback: concatenate all text parts
+            return ''.join(
+                part.get('text', '') if isinstance(part, dict) else str(part)
+                for part in content
+            )
+
+        return content
 

lyrics_transcriber/correction/agentic/providers/model_factory.py

@@ -100,19 +100,10 @@ class ModelFactory:
             return
         
         try:
-            from langfuse import Langfuse
             from langfuse.langchain import CallbackHandler
-            
-            # Initialize Langfuse client first (this is required!)
-            langfuse_client = Langfuse(
-                public_key=public_key,
-                secret_key=secret_key,
-                host=os.getenv("LANGFUSE_HOST", "https://cloud.langfuse.com"),
-            )
-            
-            # Then create callback handler with the same public_key
-            # The handler will use the initialized client
-            self._langfuse_handler = CallbackHandler(public_key=public_key)
+
+            # CallbackHandler auto-discovers credentials from environment variables
+            self._langfuse_handler = CallbackHandler()
             logger.info(f"🤖 Langfuse callback handler initialized for {model_spec}")
         except Exception as e:
             # If Langfuse keys are set, we MUST fail fast
@@ -224,6 +215,7 @@ class ModelFactory:
             model=model_name,
             project=config.gcp_project_id,
             location=config.gcp_location,
+            timeout=config.request_timeout_seconds,
             max_retries=config.max_retries,
             callbacks=callbacks,
         )

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

@@ -6,7 +6,6 @@ import os
 import shortuuid
 
 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 +26,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 +55,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 = [
             {

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