karaoke-gen 0.81.1__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.81.1.dist-info → karaoke_gen-0.86.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: karaoke-gen
-Version: 0.81.1
+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 (>=2.0.0)
+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.81.1.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
@@ -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=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=hderNRLrSZn49LrGBrgdCvBP5E7tPAugjaw7TFbb0JY,7957
-lyrics_transcriber/correction/agentic/providers/model_factory.py,sha256=iKbpMEeTyhPN8n9abVf645TfovnFEz3ia1g6XLHqp4s,8613
+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=_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=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
@@ -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.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/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
     """