karaoke-gen 0.81.1__py3-none-any.whl → 0.86.5__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

@@ -19,16 +19,27 @@ 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
+    # 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.
@@ -51,13 +62,15 @@ 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"),
-            request_timeout_seconds=float(os.getenv("AGENTIC_TIMEOUT_SECONDS", "30.0")),
+            gcp_location=os.getenv("GCP_LOCATION", "global"),
+            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/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

@@ -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(
@@ -187,26 +233,85 @@ 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
+
+    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.
@@ -100,19 +107,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
@@ -212,21 +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 Application Default Credentials (ADC) for authentication.
-        In Cloud Run, this uses the service account automatically.
-        Locally, run: gcloud auth application-default login
+        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
+
+        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,
-            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