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

karaoke_gen/instrumental_review/static/index.html

@@ -786,8 +786,8 @@
                 
                 if (waveformRes.ok) {
                     waveformData = await waveformRes.json();
-                    // API returns duration_seconds, not duration
-                    duration = waveformData.duration_seconds || 0;
+                    // API may return duration_seconds (cloud) or duration (local)
+                    duration = waveformData.duration_seconds || waveformData.duration || 0;
                 }
                 
                 // Set initial selection based on recommendation

karaoke_gen/lyrics_processor.py

@@ -3,6 +3,7 @@ import re
 import logging
 import shutil
 import json
+from typing import Optional
 from lyrics_transcriber import LyricsTranscriber, OutputConfig, TranscriberConfig, LyricsConfig
 from lyrics_transcriber.core.controller import LyricsControllerResult
 from dotenv import load_dotenv
@@ -252,10 +253,11 @@ class LyricsProcessor:
             "See README.md 'Transcription Providers' section for detailed setup instructions."
         )
 
-    def transcribe_lyrics(self, input_audio_wav, artist, title, track_output_dir, lyrics_artist=None, lyrics_title=None):
+    def transcribe_lyrics(self, input_audio_wav, artist, title, track_output_dir, lyrics_artist=None, lyrics_title=None,
+                          agentic_deadline: Optional[float] = None):
         """
         Transcribe lyrics for a track.
-        
+
         Args:
             input_audio_wav: Path to the audio file
             artist: Original artist name (used for filename generation)
@@ -263,7 +265,9 @@ class LyricsProcessor:
             track_output_dir: Output directory path
             lyrics_artist: Artist name for lyrics processing (defaults to artist if None)
             lyrics_title: Title for lyrics processing (defaults to title if None)
-            
+            agentic_deadline: Optional Unix timestamp. If agentic correction is still
+                running after this time, it will abort and return uncorrected results.
+
         Raises:
             ValueError: If transcription is enabled but no providers are configured
         """
@@ -423,8 +427,8 @@ class LyricsProcessor:
             logger=self.logger,
         )
 
-        # Process and get results
-        results: LyricsControllerResult = transcriber.process()
+        # Process and get results (pass deadline for agentic timeout)
+        results: LyricsControllerResult = transcriber.process(agentic_deadline=agentic_deadline)
         self.logger.info(f"Transcriber Results Filepaths:")
         for key, value in results.__dict__.items():
             if key.endswith("_filepath"):

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: karaoke-gen
-Version: 0.82.0
+Version: 0.86.5
 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 (>=3.1.1)
+Requires-Dist: langchain-google-genai (>=2.0.0)
 Requires-Dist: langchain-ollama (>=0.2.0)
 Requires-Dist: langchain-openai (>=0.2.0)
 Requires-Dist: langfuse (>=3.0.0)

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

@@ -8,12 +8,12 @@ karaoke_gen/instrumental_review/analyzer.py,sha256=Heg8TbrwM4g5IV7bavmO6EfVD4M0U
 karaoke_gen/instrumental_review/editor.py,sha256=_DGTjKMk5WhoGtLGtTvHzU522LJyQQ_DSY1r8fULuiA,11568
 karaoke_gen/instrumental_review/models.py,sha256=cUSb_JheJK0cGdKx9f59-9sRvRrhrgdTdKBzQN3lHto,5226
 karaoke_gen/instrumental_review/server.py,sha256=Ick90X77t2EeMRwtx2U08sSybadQyWH7G0tDG-4JqP4,19377
-karaoke_gen/instrumental_review/static/index.html,sha256=1lzo_W5B4HxNStWPiVaP4I6ctqDkXAABJkQmojvBDqc,63235
+karaoke_gen/instrumental_review/static/index.html,sha256=anhmEGAhL0rV25q5V8GEnWxs2RnF7qA3dADwvGWCd88,63277
 karaoke_gen/instrumental_review/waveform.py,sha256=Q6LBPZrJAD6mzZ7TmRf3Tf4gwYhUYTHumJKytLs3hSg,12940
 karaoke_gen/karaoke_finalise/__init__.py,sha256=HqZ7TIhgt_tYZ-nb_NNCaejWAcF_aK-7wJY5TaW_keM,46
 karaoke_gen/karaoke_finalise/karaoke_finalise.py,sha256=Wn1KcdRyINT63UxKUPT9uB-bsrFVih0Im_cjXtequS0,93534
 karaoke_gen/karaoke_gen.py,sha256=84n2SE0MixJr01_btLmm5cVdf35hJvp7W638b8TKR-Q,65734
-karaoke_gen/lyrics_processor.py,sha256=9BtL2uJa4Ekrodj2w_SXSeOraVKCB2kzYuHcGHTFpo8,23979
+karaoke_gen/lyrics_processor.py,sha256=jXEjkQVFauojKXhs3cXytnpfS2ig1o9iHON0-I8RwPw,24297
 karaoke_gen/metadata.py,sha256=SZW6TuUpkGGU98gRdjPfrR8F4vWXjnfCSGry2XD5_A4,6689
 karaoke_gen/pipeline/__init__.py,sha256=-MZnba4qobr1qGDamG9CieLl2pWCZMEB5_Yur62RKeM,2106
 karaoke_gen/pipeline/base.py,sha256=yg4LIm7Mc9ER0zCmZcUv4huEkotSSXK_0OAFio-TSNI,6235
@@ -45,11 +45,11 @@ lyrics_transcriber/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3
 lyrics_transcriber/cli/cli_main.py,sha256=F72ENLTj934bXjHAUbRm0toCK73qnuJhwEm9agBVKHQ,11596
 lyrics_transcriber/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 lyrics_transcriber/core/config.py,sha256=_X_d1wSYTJjSquqbODYCwPdOYpnSR9KERwvr_jkdYls,2056
-lyrics_transcriber/core/controller.py,sha256=dUJvnehr9_Mv3Syj_TWZQsQVsDD1w8AdF5_1xISA2cw,31661
+lyrics_transcriber/core/controller.py,sha256=zRjdxOrJEaa2depvzZvwVQiEFmf8Ew3Aek89O1HUEas,32223
 lyrics_transcriber/correction/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 lyrics_transcriber/correction/agentic/__init__.py,sha256=p7PHiebuvRs8RDlPDs-9gLZKzXG5KfWg3fFCdDhY6pE,222
 lyrics_transcriber/correction/agentic/adapter.py,sha256=Z0JBTAA7xlSdctCHqO9nBMl78C4XmqsLKKtS6BvNZNI,2912
-lyrics_transcriber/correction/agentic/agent.py,sha256=KZjAKaxv6HXkNFNGDc-hXM7He3ew5kp9Q_OR43SrfJo,12310
+lyrics_transcriber/correction/agentic/agent.py,sha256=GV6TkrIQBhibJllXDnp9zBBmaf_vnoSVuJZmm6WVhS0,12722
 lyrics_transcriber/correction/agentic/feedback/aggregator.py,sha256=323t8LDbE26ni83woyN7uVMSuSQhnqTgwJc-d-KuDbs,273
 lyrics_transcriber/correction/agentic/feedback/collector.py,sha256=HT-2cAP_bx7Iv-0-tpZv534do111g0FlTUt2XaKoUtA,415
 lyrics_transcriber/correction/agentic/feedback/retention.py,sha256=dUCUsKPCzHVQxiLLBXcdfAZ5NqiG25go0Z6GFXeK0vY,881
@@ -84,13 +84,13 @@ lyrics_transcriber/correction/agentic/prompts/langfuse_prompts.py,sha256=hjQhyY_
 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=w6-fkapEy3BgoFIsRfZ44XUCV4zuicFSNoSoVAe5lYE,3282
+lyrics_transcriber/correction/agentic/providers/config.py,sha256=NnGigthJSWMz_d99qh-ClQaVqjODRoYrwTHVftQOlR8,4156
 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=H3C3BNjAixfkOJojxWXv-P-svlgj5rJEJdk0zPIjh7E,8540
-lyrics_transcriber/correction/agentic/providers/model_factory.py,sha256=CeVDblf1HdphtUHVn3Cgl07YAeUuSxTjEHHFJN8Frj0,8257
+lyrics_transcriber/correction/agentic/providers/langchain_bridge.py,sha256=yX5JGGALDCFgji34gZ924GePsfjELOPqgxD6Cx7kKEg,12915
+lyrics_transcriber/correction/agentic/providers/model_factory.py,sha256=90EjVwoKTWo8jXTrroI7GXM9AU-_ACx9g_fHB4vnR2w,9919
 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/response_parser.py,sha256=c2KypM-yHbIXXakHV5s-qh8fl8FhssLPVo3pJbyAiG4,4301
 lyrics_transcriber/correction/agentic/providers/retry_executor.py,sha256=hX21Zwy2cSECAw7k13ndEinWRqwjo4xYoSCQ2B2CUf0,3912
 lyrics_transcriber/correction/agentic/router.py,sha256=akP28A0lftmsnSyMOW6k7iTC1pv4LEgilXhIkcfJzlE,1437
 lyrics_transcriber/correction/agentic/workflows/__init__.py,sha256=OsBExAbIIKxJgX6FKXFOgcUjIG9AWJQV_fESZVdO8mo,77
@@ -98,7 +98,7 @@ lyrics_transcriber/correction/agentic/workflows/consensus_workflow.py,sha256=gMu
 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=qW6GwOOLM8zxYtYMmGy9Rzk_4mJzdpGiCXW3LQFXn14,38362
+lyrics_transcriber/correction/corrector.py,sha256=2yVFUHzqEXZ7aeJjm6durF6WtrhYVTm6nqOQn-dtNI4,40545
 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
@@ -286,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.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,,
+karaoke_gen-0.86.5.dist-info/METADATA,sha256=Bv8ezXed1IakQYY4hFXnar8dOd31kb3RUjQUPkcdVzs,23074
+karaoke_gen-0.86.5.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+karaoke_gen-0.86.5.dist-info/entry_points.txt,sha256=xIyLe7K84ZyjO8L0_AmNectz93QjGSs5AkApMtlAd4g,160
+karaoke_gen-0.86.5.dist-info/licenses/LICENSE,sha256=81R_4XwMZDODHD7JcZeUR8IiCU8AD7Ajl6bmwR9tYDk,1074
+karaoke_gen-0.86.5.dist-info/RECORD,,

lyrics_transcriber/core/controller.py

@@ -289,8 +289,13 @@ class LyricsTranscriber:
         """Initialize output generation service."""
         return OutputGenerator(config=self.output_config, logger=self.logger)
 
-    def process(self) -> LyricsControllerResult:
-        """Main processing method that orchestrates the entire workflow."""
+    def process(self, agentic_deadline: Optional[float] = None) -> LyricsControllerResult:
+        """Main processing method that orchestrates the entire workflow.
+
+        Args:
+            agentic_deadline: Optional Unix timestamp. If agentic correction is still
+                running after this time, it will abort and return uncorrected results.
+        """
 
         self.logger.info(f"LyricsTranscriber controller beginning processing for {self.artist} - {self.title}")
 
@@ -390,7 +395,7 @@ class LyricsTranscriber:
 
         # Step 3: Process and correct lyrics if enabled AND we have transcription results
         if self.output_config.run_correction and self.results.transcription_results:
-            self.correct_lyrics()
+            self.correct_lyrics(agentic_deadline=agentic_deadline)
         elif self.output_config.run_correction:
             self.logger.info("Skipping lyrics correction - no transcription results available")
 
@@ -494,8 +499,13 @@ class LyricsTranscriber:
         else:
             self.logger.debug("  - LocalWhisper: DISABLED (enable_local_whisper=False)")
 
-    def correct_lyrics(self) -> None:
-        """Run lyrics correction using transcription and internet lyrics."""
+    def correct_lyrics(self, agentic_deadline: Optional[float] = None) -> None:
+        """Run lyrics correction using transcription and internet lyrics.
+
+        Args:
+            agentic_deadline: Optional Unix timestamp. If agentic correction is still
+                running after this time, it will abort and return uncorrected results.
+        """
         self.logger.info("Starting lyrics correction process")
 
         # Check if we have reference lyrics to work with
@@ -553,6 +563,7 @@ class LyricsTranscriber:
                 transcription_results=self.results.transcription_results,
                 lyrics_results=self.results.lyrics_results,
                 metadata=metadata,
+                agentic_deadline=agentic_deadline,
             )
 
             # Store corrected results

lyrics_transcriber/correction/agentic/agent.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import logging
 import os
 import json
+import time
 from typing import Dict, Any, List, Optional
 
 from .providers.base import BaseAIProvider
@@ -120,7 +121,7 @@ class AgenticCorrector:
         title: Optional[str] = None
     ) -> Optional[GapClassification]:
         """Classify a gap using the AI provider.
-        
+
         Args:
             gap_id: Unique identifier for the gap
             gap_text: The text of the gap
@@ -129,10 +130,13 @@ class AgenticCorrector:
             reference_contexts: Dictionary of reference lyrics from each source
             artist: Song artist name
             title: Song title
-        
+
         Returns:
             GapClassification object or None if classification fails
         """
+        logger.info(f"🤖 Classifying gap {gap_id} ({len(gap_text)} chars)")
+        start_time = time.time()
+
         # Build classification prompt
         prompt = build_classification_prompt(
             gap_text=gap_text,
@@ -143,7 +147,7 @@ class AgenticCorrector:
             title=title,
             gap_id=gap_id
         )
-        
+
         # Call AI provider to get classification
         try:
             data = self._provider.generate_correction_proposals(
@@ -151,17 +155,25 @@ class AgenticCorrector:
                 schema=GapClassification.model_json_schema(),
                 session_id=self._session_id
             )
-            
+
+            elapsed = time.time() - start_time
+
             # Extract first result
             if data and len(data) > 0:
                 item = data[0]
                 if isinstance(item, dict) and "error" not in item:
                     classification = GapClassification.model_validate(item)
-                    logger.debug(f"🤖 Classified gap {gap_id} as {classification.category} (confidence: {classification.confidence})")
+                    logger.info(
+                        f"🤖 Classified gap {gap_id} as {classification.category} "
+                        f"(confidence: {classification.confidence:.2f}) in {elapsed:.2f}s"
+                    )
                     return classification
+                else:
+                    logger.warning(f"🤖 Classification returned error for gap {gap_id}: {item}")
         except Exception as e:
-            logger.warning(f"🤖 Failed to classify gap {gap_id}: {e}")
-        
+            elapsed = time.time() - start_time
+            logger.warning(f"🤖 Failed to classify gap {gap_id} after {elapsed:.2f}s: {e}")
+
         return None
     
     def propose_for_gap(

lyrics_transcriber/correction/agentic/providers/config.py

@@ -23,13 +23,23 @@ class ProviderConfig:
     gcp_project_id: Optional[str] = None
     gcp_location: str = "global"
 
-    request_timeout_seconds: float = 30.0
+    # Timeout increased to 120s to handle Vertex AI connection establishment
+    # and potential network latency. The 499 "operation cancelled" errors seen
+    # at ~60s suggest internal timeouts; 120s provides headroom.
+    request_timeout_seconds: float = 120.0
     max_retries: int = 2
-    retry_backoff_base_seconds: float = 0.2
+    # Backoff increased from 0.2s to 2.0s base - if a request times out,
+    # retrying immediately is unlikely to help. Give the service time to recover.
+    retry_backoff_base_seconds: float = 2.0
     retry_backoff_factor: float = 2.0
     circuit_breaker_failure_threshold: int = 3
     circuit_breaker_open_seconds: int = 60
 
+    # Initialization timeouts - fail fast instead of hanging forever
+    # These are separate from request_timeout to catch connection establishment issues
+    initialization_timeout_seconds: float = 30.0  # Model creation + warm-up
+    warmup_timeout_seconds: float = 15.0  # Just the warm-up call
+
     @staticmethod
     def from_env(cache_dir: Optional[str] = None) -> "ProviderConfig":
         """Create config from environment variables.
@@ -53,12 +63,14 @@ class ProviderConfig:
             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")),
+            request_timeout_seconds=float(os.getenv("AGENTIC_TIMEOUT_SECONDS", "120.0")),
             max_retries=int(os.getenv("AGENTIC_MAX_RETRIES", "2")),
-            retry_backoff_base_seconds=float(os.getenv("AGENTIC_BACKOFF_BASE_SECONDS", "0.2")),
+            retry_backoff_base_seconds=float(os.getenv("AGENTIC_BACKOFF_BASE_SECONDS", "2.0")),
             retry_backoff_factor=float(os.getenv("AGENTIC_BACKOFF_FACTOR", "2.0")),
             circuit_breaker_failure_threshold=int(os.getenv("AGENTIC_CIRCUIT_THRESHOLD", "3")),
             circuit_breaker_open_seconds=int(os.getenv("AGENTIC_CIRCUIT_OPEN_SECONDS", "60")),
+            initialization_timeout_seconds=float(os.getenv("AGENTIC_INIT_TIMEOUT_SECONDS", "30.0")),
+            warmup_timeout_seconds=float(os.getenv("AGENTIC_WARMUP_TIMEOUT_SECONDS", "15.0")),
         )
 
     def validate_environment(self, logger: Optional[object] = None) -> None:

lyrics_transcriber/correction/agentic/providers/langchain_bridge.py

@@ -13,6 +13,8 @@ from __future__ import annotations
 
 import logging
 import os
+import time
+from concurrent.futures import ThreadPoolExecutor, TimeoutError as FuturesTimeoutError
 from typing import List, Dict, Any, Optional
 from datetime import datetime
 
@@ -33,6 +35,14 @@ from .constants import (
 
 logger = logging.getLogger(__name__)
 
+# Error constant for initialization timeout
+INIT_TIMEOUT_ERROR = "initialization_timeout"
+
+
+class InitializationTimeoutError(Exception):
+    """Raised when model initialization exceeds the configured timeout."""
+    pass
+
 
 class LangChainBridge(BaseAIProvider):
     """Provider bridge using LangChain ChatModels with reliability patterns.
@@ -87,6 +97,7 @@ class LangChainBridge(BaseAIProvider):
         
         # Lazy-initialized chat model
         self._chat_model: Optional[Any] = None
+        self._warmed_up: bool = False
     
     def name(self) -> str:
         """Return provider name for logging."""
@@ -130,13 +141,45 @@ class LangChainBridge(BaseAIProvider):
                 "until": open_until
             }]
         
-        # Step 2: Get or create chat model
+        # Step 2: Get or create chat model with initialization timeout
         if not self._chat_model:
+            timeout = self._config.initialization_timeout_seconds
+            logger.info(f"🤖 Initializing model {self._model} with {timeout}s timeout...")
+            init_start = time.time()
+
             try:
-                self._chat_model = self._factory.create_chat_model(
-                    self._model, 
-                    self._config
-                )
+                # Use ThreadPoolExecutor for cross-platform timeout
+                with ThreadPoolExecutor(max_workers=1) as executor:
+                    future = executor.submit(
+                        self._factory.create_chat_model,
+                        self._model,
+                        self._config
+                    )
+                    try:
+                        self._chat_model = future.result(timeout=timeout)
+                    except FuturesTimeoutError:
+                        raise InitializationTimeoutError(
+                            f"Model initialization timed out after {timeout}s. "
+                            f"This may indicate network issues or service unavailability."
+                        ) from None
+
+                init_elapsed = time.time() - init_start
+                logger.info(f"🤖 Model created in {init_elapsed:.2f}s, starting warm-up...")
+
+                # Warm up the model to establish connection before real work
+                self._warm_up_model()
+
+                total_elapsed = time.time() - init_start
+                logger.info(f"🤖 Model initialization complete in {total_elapsed:.2f}s")
+
+            except InitializationTimeoutError as e:
+                self._circuit_breaker.record_failure(self._model)
+                logger.exception("🤖 Model initialization timeout")
+                return [{
+                    "error": INIT_TIMEOUT_ERROR,
+                    "message": str(e),
+                    "timeout_seconds": timeout
+                }]
             except Exception as e:
                 self._circuit_breaker.record_failure(self._model)
                 logger.error(f"🤖 Failed to initialize chat model: {e}")
@@ -146,24 +189,27 @@ class LangChainBridge(BaseAIProvider):
                 }]
         
         # Step 3: Execute with retry logic
-        logger.debug(
-            f"🤖 [LangChain] Sending prompt to {self._model}: "
-            f"{prompt[:PROMPT_LOG_LENGTH]}..."
+        logger.info(
+            f"🤖 [LangChain] Sending prompt to {self._model} ({len(prompt)} chars)"
         )
-        
+        logger.debug(f"🤖 [LangChain] Prompt preview: {prompt[:PROMPT_LOG_LENGTH]}...")
+
+        invoke_start = time.time()
         result = self._executor.execute_with_retry(
             operation=lambda: self._invoke_model(prompt),
             operation_name=f"invoke_{self._model}"
         )
-        
+        invoke_elapsed = time.time() - invoke_start
+
         # Step 4: Handle result and update circuit breaker
         if result.success:
             self._circuit_breaker.record_success(self._model)
-            
+
             logger.info(
-                f"🤖 [LangChain] Got response from {self._model}: "
-                f"{result.value[:RESPONSE_LOG_LENGTH]}..."
+                f"🤖 [LangChain] Got response from {self._model} in {invoke_elapsed:.2f}s "
+                f"({len(result.value)} chars)"
             )
+            logger.debug(f"🤖 [LangChain] Response preview: {result.value[:RESPONSE_LOG_LENGTH]}...")
             
             # Step 5: Cache the raw response for future use
             self._cache.set(
@@ -225,3 +271,47 @@ class LangChainBridge(BaseAIProvider):
 
         return content
 
+    def _warm_up_model(self) -> None:
+        """Send a lightweight request to warm up the model connection.
+
+        This helps establish the REST connection and potentially warm up any
+        server-side resources before processing real correction requests.
+        The warm-up uses a timeout to fail fast if the service is unresponsive.
+        """
+        if self._warmed_up:
+            return
+
+        timeout = self._config.warmup_timeout_seconds
+        # Use print with flush=True for visibility when output is redirected
+        print(f"🔥 Warming up {self._model} connection (timeout: {timeout}s)...", flush=True)
+        logger.info(f"🔥 Warming up {self._model} connection (timeout: {timeout}s)...")
+
+        warmup_start = time.time()
+        try:
+            from langchain_core.messages import HumanMessage
+
+            # Minimal prompt that requires almost no processing
+            warm_up_prompt = 'Respond with exactly: {"status":"ready"}'
+
+            # Use ThreadPoolExecutor for timeout on warm-up call
+            with ThreadPoolExecutor(max_workers=1) as executor:
+                future = executor.submit(
+                    self._chat_model.invoke,
+                    [HumanMessage(content=warm_up_prompt)]
+                )
+                try:
+                    future.result(timeout=timeout)
+                except FuturesTimeoutError:
+                    raise TimeoutError(f"Warm-up timed out after {timeout}s") from None
+
+            elapsed = time.time() - warmup_start
+            self._warmed_up = True
+            print(f"🔥 Warm-up complete for {self._model} in {elapsed:.2f}s", flush=True)
+            logger.info(f"🔥 Warm-up complete for {self._model} in {elapsed:.2f}s")
+        except Exception as e:
+            elapsed = time.time() - warmup_start
+            # Don't fail the actual request if warm-up fails
+            # Just log and continue - the real request might still work
+            print(f"🔥 Warm-up failed for {self._model} after {elapsed:.2f}s: {e} (continuing anyway)", flush=True)
+            logger.warning(f"🔥 Warm-up failed for {self._model} after {elapsed:.2f}s: {e} (continuing anyway)")
+

lyrics_transcriber/correction/agentic/providers/model_factory.py

@@ -3,12 +3,19 @@ from __future__ import annotations
 
 import logging
 import os
+import time
 from typing import Any, Optional, List
 
 from .config import ProviderConfig
 
 logger = logging.getLogger(__name__)
 
+# Error message constant for TRY003 compliance
+GOOGLE_API_KEY_MISSING_ERROR = (
+    "GOOGLE_API_KEY environment variable is required for Google/Gemini models. "
+    "Get an API key from https://aistudio.google.com/app/apikey"
+)
+
 
 class ModelFactory:
     """Creates and configures LangChain ChatModels with observability.
@@ -203,22 +210,56 @@ class ModelFactory:
     def _create_vertexai_model(
         self, model_name: str, callbacks: List[Any], config: ProviderConfig
     ) -> Any:
-        """Create ChatVertexAI model for Google Gemini via Vertex AI.
+        """Create ChatGoogleGenerativeAI model for Google Gemini.
+
+        Uses the unified langchain-google-genai package which supports both:
+        - Vertex AI backend (service account / ADC auth) - when project is set
+        - Google AI Studio backend (API key auth) - when only api_key is set
 
-        Uses Application Default Credentials (ADC) for authentication.
-        In Cloud Run, this uses the service account automatically.
-        Locally, run: gcloud auth application-default login
+        On Cloud Run, ADC (Application Default Credentials) are used automatically
+        when the project parameter is provided, using the service account attached
+        to the Cloud Run service.
+
+        This is a REST-based API that avoids the gRPC connection issues
+        seen with the deprecated langchain-google-vertexai package.
         """
-        from langchain_google_vertexai import ChatVertexAI
+        from langchain_google_genai import ChatGoogleGenerativeAI
 
-        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})")
+        start_time = time.time()
+
+        # Determine authentication method
+        api_key = config.google_api_key
+        project = config.gcp_project_id
+
+        # Prefer Vertex AI (service account) if project is set, otherwise require API key
+        if not project and not api_key:
+            raise ValueError(GOOGLE_API_KEY_MISSING_ERROR)
+
+        if project:
+            logger.info(f"🤖 Creating Google Gemini model via Vertex AI (project={project}): {model_name}")
+        else:
+            logger.info(f"🤖 Creating Google Gemini model via AI Studio API: {model_name}")
+
+        # Build kwargs - only include api_key if set (otherwise ADC is used)
+        model_kwargs = {
+            "model": model_name,
+            "convert_system_message_to_human": True,  # Gemini doesn't support system messages
+            "max_retries": config.max_retries,
+            "timeout": config.request_timeout_seconds,
+            "callbacks": callbacks,
+        }
+
+        # Add project to trigger Vertex AI backend with ADC
+        if project:
+            model_kwargs["project"] = project
+
+        # Add API key if available (can be used with or without project)
+        if api_key:
+            model_kwargs["google_api_key"] = api_key
+
+        model = ChatGoogleGenerativeAI(**model_kwargs)
+
+        elapsed = time.time() - start_time
+        logger.info(f"🤖 Google Gemini model created in {elapsed:.2f}s: {model_name}")
         return model
 

lyrics_transcriber/correction/agentic/providers/response_parser.py

@@ -51,22 +51,34 @@ class ResponseParser:
     
     def _attempt_json_fix(self, content: str) -> str:
         """Attempt to fix common JSON formatting issues.
-        
+
         Args:
             content: Raw JSON string
-            
+
         Returns:
             Fixed JSON string (or original if no fixes applied)
         """
+        import re
+
+        # Fix 0: Strip markdown code fences (```json ... ``` or ``` ... ```)
+        # Models often wrap JSON in markdown code blocks
+        fixed = content.strip()
+        if fixed.startswith("```"):
+            # Remove opening fence (with optional language identifier)
+            fixed = re.sub(r'^```\w*\s*\n?', '', fixed)
+            # Remove closing fence
+            fixed = re.sub(r'\n?```\s*$', '', fixed)
+            fixed = fixed.strip()
+            logger.debug("🤖 Stripped markdown code fences from response")
+
         # Fix 1: Replace invalid escape sequences like \' with '
         # (JSON only allows \", \\, \/, \b, \f, \n, \r, \t)
-        fixed = content.replace("\\'", "'")
-        
+        fixed = fixed.replace("\\'", "'")
+
         # Fix 2: Remove any trailing commas before } or ]
-        import re
         fixed = re.sub(r',\s*}', '}', fixed)
         fixed = re.sub(r',\s*]', ']', fixed)
-        
+
         return fixed
     
     def _normalize_json_response(self, data: Any) -> List[Dict[str, Any]]:

lyrics_transcriber/correction/corrector.py

@@ -4,6 +4,7 @@ from pathlib import Path
 from copy import deepcopy
 import os
 import shortuuid
+import time
 
 from lyrics_transcriber.correction.handlers.levenshtein import LevenshteinHandler
 from lyrics_transcriber.correction.handlers.no_space_punct_match import NoSpacePunctuationMatchHandler
@@ -107,8 +108,24 @@ class LyricsCorrector:
         transcription_results: List[TranscriptionResult],
         lyrics_results: Dict[str, LyricsData],
         metadata: Optional[Dict[str, Any]] = None,
+        agentic_deadline: Optional[float] = None,
     ) -> CorrectionResult:
-        """Execute the correction process."""
+        """Execute the correction process.
+
+        Args:
+            transcription_results: List of transcription results to correct.
+            lyrics_results: Dictionary of lyrics data from various sources.
+            metadata: Optional metadata including artist, title, audio file hash.
+            agentic_deadline: Optional Unix timestamp (from time.time()). If agentic
+                correction is still running after this time, it will abort and return
+                uncorrected results for human review.
+
+        Note:
+            The deadline is checked between gap iterations, not during LLM processing.
+            A single long-running LLM call may exceed the deadline. The caller should
+            wrap this method with an outer timeout (e.g., asyncio.wait_for) as a safety
+            net for hung operations.
+        """
         # Optional agentic routing flag from environment; default off for safety
         agentic_enabled = os.getenv("USE_AGENTIC_AI", "").lower() in {"1", "true", "yes"}
         self.logger.info(f"🤖 AGENTIC MODE: {'ENABLED' if agentic_enabled else 'DISABLED'} (USE_AGENTIC_AI={os.getenv('USE_AGENTIC_AI', 'NOT_SET')})")
@@ -132,9 +149,9 @@ class LyricsCorrector:
         # Store anchor sequences for use in correction handlers
         self._anchor_sequences = anchor_sequences
 
-        # Process corrections with metadata
+        # Process corrections with metadata and optional deadline for agentic timeout
         corrections, corrected_segments, correction_steps, word_id_map, segment_id_map = self._process_corrections(
-            primary_transcription.segments, gap_sequences, metadata=metadata
+            primary_transcription.segments, gap_sequences, metadata=metadata, deadline=agentic_deadline
         )
 
         # Calculate correction ratio
@@ -178,10 +195,22 @@ class LyricsCorrector:
         return leading_space + new_word.strip() + trailing_space
 
     def _process_corrections(
-        self, segments: List[LyricsSegment], gap_sequences: List[GapSequence], metadata: Optional[Dict[str, Any]] = None
+        self, segments: List[LyricsSegment], gap_sequences: List[GapSequence], metadata: Optional[Dict[str, Any]] = None,
+        deadline: Optional[float] = None
     ) -> Tuple[List[WordCorrection], List[LyricsSegment], List[CorrectionStep], Dict[str, str], Dict[str, str]]:
         """Process corrections using handlers.
 
+        Args:
+            segments: List of lyrics segments to process.
+            gap_sequences: List of gap sequences to correct.
+            metadata: Optional metadata including artist, title, audio file hash.
+            deadline: Optional Unix timestamp (from time.time()). When agentic mode is
+                enabled and this deadline is exceeded, remaining gaps are skipped and
+                the method returns with whatever corrections have been made (likely none).
+
+        Returns:
+            Tuple of (corrections, corrected_segments, correction_steps, word_id_map, segment_id_map).
+
         The correction flow works as follows:
         1. First pass: Process all gaps
            - Iterate through each gap sequence
@@ -415,6 +444,16 @@ class LyricsCorrector:
         # === END TEMPORARY CODE ===
 
         for i, gap in enumerate(gap_sequences, 1):
+            # Check deadline before processing each gap (agentic mode only)
+            # This allows us to abort early and return uncorrected results for human review
+            if deadline and use_agentic_env and time.time() > deadline:
+                self.logger.warning(
+                    f"⏰ AGENTIC TIMEOUT: Deadline exceeded after processing {i-1}/{len(gap_sequences)} gaps. "
+                    "Skipping remaining gaps - human review will correct any issues."
+                )
+                # Break out of loop - continue with whatever corrections we have (likely none)
+                break
+
             self.logger.info(f"Processing gap {i}/{len(gap_sequences)} at position {gap.transcription_position}")
 
             # Get the actual words for logging