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

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

@@ -18,6 +18,11 @@ class ProviderConfig:
     privacy_mode: bool
     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 = "global"
+
     request_timeout_seconds: float = 30.0
     max_retries: int = 2
     retry_backoff_base_seconds: float = 0.2
@@ -46,6 +51,8 @@ class ProviderConfig:
             openrouter_api_key=os.getenv("OPENROUTER_API_KEY"),
             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", "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
@@ -155,6 +146,8 @@ class ModelFactory:
                 return self._create_openai_model(model_name, callbacks, config)
             elif provider == "anthropic":
                 return self._create_anthropic_model(model_name, callbacks, config)
+            elif provider in ("vertexai", "google"):
+                return self._create_vertexai_model(model_name, callbacks, config)
             else:
                 raise ValueError(f"Unsupported provider: {provider}")
         except ImportError as e:
@@ -197,7 +190,7 @@ class ModelFactory:
     ) -> Any:
         """Create ChatAnthropic model."""
         from langchain_anthropic import ChatAnthropic
-        
+
         model = ChatAnthropic(
             model=model_name,
             timeout=config.request_timeout_seconds,
@@ -207,3 +200,25 @@ class ModelFactory:
         logger.debug(f"🤖 Created Anthropic model: {model_name}")
         return model
 
+    def _create_vertexai_model(
+        self, model_name: str, callbacks: List[Any], config: ProviderConfig
+    ) -> Any:
+        """Create ChatVertexAI model for Google Gemini via Vertex AI.
+
+        Uses Application Default Credentials (ADC) for authentication.
+        In Cloud Run, this uses the service account automatically.
+        Locally, run: gcloud auth application-default login
+        """
+        from langchain_google_vertexai import ChatVertexAI
+
+        model = ChatVertexAI(
+            model=model_name,
+            project=config.gcp_project_id,
+            location=config.gcp_location,
+            timeout=config.request_timeout_seconds,
+            max_retries=config.max_retries,
+            callbacks=callbacks,
+        )
+        logger.debug(f"🤖 Created Vertex AI model: {model_name} (project={config.gcp_project_id})")
+        return model
+

lyrics_transcriber/correction/agentic/router.py

@@ -5,6 +5,10 @@ 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"
+
 
 class ModelRouter:
     """Rules-based routing by gap type/length/uncertainty (scaffold)."""
@@ -14,22 +18,23 @@ class ModelRouter:
 
     def choose_model(self, gap_type: str, uncertainty: float) -> str:
         """Choose appropriate model based on gap characteristics.
-        
+
         Returns model identifier in format "provider/model" for LangChain:
-        - "ollama/gpt-oss:latest" for local Ollama models
-        - "openai/gpt-4" for OpenAI models  
+        - "vertexai/gemini-3-flash-preview" for Gemini via Vertex AI (default)
+        - "ollama/llama3.2:latest" for local Ollama models
+        - "openai/gpt-4" for OpenAI models
         - "anthropic/claude-3-sonnet-20240229" for Anthropic models
         """
-        # Simple baseline per technical guidance
+        # Check for explicit model override from environment
+        env_model = os.getenv("AGENTIC_AI_MODEL")
+        if env_model:
+            return env_model
+
+        # Privacy mode: use local Ollama
         if self._config.privacy_mode:
-            # Use the actual model from env, or default to a common Ollama model
-            return os.getenv("AGENTIC_AI_MODEL", "ollama/gpt-oss:latest")
-        
-        # For high-uncertainty gaps, use Claude (best reasoning)
-        if uncertainty > 0.5:
-            return "anthropic/claude-3-sonnet-20240229"
-        
-        # Default to GPT-4 for general cases
-        return "openai/gpt-4"
+            return "ollama/llama3.2:latest"
+
+        # 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/frontend/.gitignore

@@ -21,3 +21,4 @@ dist-ssr
 *.njsproj
 *.sln
 *.sw?
+test-results/