pdd-cli 0.0.90__py3-none-any.whl → 0.0.121__py3-none-any.whl

pdd/llm_invoke.py

@@ -84,11 +84,11 @@ from pathlib import Path
 from typing import Optional, Dict, List, Any, Type, Union, Tuple
 from pydantic import BaseModel, ValidationError
 import openai  # Import openai for exception handling as LiteLLM maps to its types
-from langchain_core.prompts import PromptTemplate
 import warnings
 import time as time_module # Alias to avoid conflict with 'time' parameter
 # Import the default model constant
 from pdd import DEFAULT_LLM_MODEL
+from pdd.path_resolution import get_default_resolver
 
 # Opt-in to future pandas behavior regarding downcasting
 try:
@@ -98,6 +98,310 @@ except pd._config.config.OptionError:
     pass
 
 
+# --- Custom Exceptions ---
+
+class SchemaValidationError(Exception):
+    """Raised when LLM response fails Pydantic/JSON schema validation.
+
+    This exception triggers model fallback when caught at the outer exception
+    handler level, allowing the next candidate model to be tried.
+
+    Issue #168: Previously, validation errors only logged an error and continued
+    to the next batch item, never triggering model fallback.
+    """
+
+    def __init__(self, message: str, raw_response: Any = None, item_index: int = 0):
+        super().__init__(message)
+        self.raw_response = raw_response
+        self.item_index = item_index
+
+
+class CloudFallbackError(Exception):
+    """Raised when cloud execution fails and should fall back to local.
+
+    This exception is caught internally and triggers fallback to local execution
+    when cloud is unavailable (network errors, timeouts, auth failures).
+    """
+    pass
+
+
+class CloudInvocationError(Exception):
+    """Raised when cloud invocation fails with a non-recoverable error.
+
+    This exception indicates a cloud error that should not fall back to local,
+    such as validation errors returned by the cloud endpoint.
+    """
+    pass
+
+
+class InsufficientCreditsError(Exception):
+    """Raised when user has insufficient credits for cloud execution.
+
+    This exception is raised when the cloud returns 402 (Payment Required)
+    and should NOT fall back to local execution - the user needs to know.
+    """
+    pass
+
+
+# --- Cloud Execution Helpers ---
+
+def _ensure_all_properties_required(schema: Dict[str, Any]) -> Dict[str, Any]:
+    """Recursively ensure ALL properties are in the required array (OpenAI strict mode).
+
+    OpenAI's strict mode requires that all properties at ALL levels of a JSON schema
+    are listed in the 'required' array. Pydantic's model_json_schema() only includes
+    fields without default values in 'required', which causes OpenAI to reject the schema.
+
+    This function walks the entire schema tree and ensures every object type has all
+    its properties in the 'required' array.
+
+    Args:
+        schema: A JSON schema dictionary
+
+    Returns:
+        The schema with all properties added to 'required' at all nesting levels
+    """
+    if not isinstance(schema, dict):
+        return schema
+
+    # If this is an object with properties, make all properties required
+    if schema.get('type') == 'object' and 'properties' in schema:
+        schema['required'] = list(schema['properties'].keys())
+        # Recurse into each property
+        for prop_schema in schema['properties'].values():
+            _ensure_all_properties_required(prop_schema)
+
+    # Handle array items
+    if schema.get('type') == 'array' and 'items' in schema:
+        _ensure_all_properties_required(schema['items'])
+
+    # Handle anyOf/oneOf/allOf
+    for key in ('anyOf', 'oneOf', 'allOf'):
+        if key in schema:
+            for sub_schema in schema[key]:
+                _ensure_all_properties_required(sub_schema)
+
+    # Handle $defs
+    if '$defs' in schema:
+        for def_schema in schema['$defs'].values():
+            _ensure_all_properties_required(def_schema)
+
+    return schema
+
+
+def _add_additional_properties_false(schema: Dict[str, Any]) -> Dict[str, Any]:
+    """Recursively add additionalProperties: false to all object schemas.
+
+    OpenAI's strict mode requires additionalProperties: false on ALL object
+    schemas, including nested ones. This function walks the schema tree and
+    adds the property to every object type.
+
+    Args:
+        schema: A JSON schema dictionary
+
+    Returns:
+        The schema with additionalProperties: false on all objects
+    """
+    if not isinstance(schema, dict):
+        return schema
+
+    # If this is an object type, add additionalProperties: false
+    if schema.get('type') == 'object':
+        schema['additionalProperties'] = False
+        # Recursively process properties
+        if 'properties' in schema:
+            for prop_name, prop_schema in schema['properties'].items():
+                _add_additional_properties_false(prop_schema)
+
+    # Handle arrays - process items schema
+    if schema.get('type') == 'array' and 'items' in schema:
+        _add_additional_properties_false(schema['items'])
+
+    # Handle anyOf, oneOf, allOf
+    for key in ('anyOf', 'oneOf', 'allOf'):
+        if key in schema:
+            for sub_schema in schema[key]:
+                _add_additional_properties_false(sub_schema)
+
+    # Handle $defs (Pydantic's reference definitions)
+    if '$defs' in schema:
+        for def_name, def_schema in schema['$defs'].items():
+            _add_additional_properties_false(def_schema)
+
+    return schema
+
+
+def _pydantic_to_json_schema(pydantic_class: Type[BaseModel]) -> Dict[str, Any]:
+    """Convert a Pydantic model class to JSON Schema for cloud transport.
+
+    Args:
+        pydantic_class: A Pydantic BaseModel subclass
+
+    Returns:
+        JSON Schema dictionary that can be serialized and sent to cloud
+    """
+    schema = pydantic_class.model_json_schema()
+    # Ensure all properties are in required array (OpenAI strict mode requirement)
+    _ensure_all_properties_required(schema)
+    # Include class name for debugging/logging purposes
+    schema['__pydantic_class_name__'] = pydantic_class.__name__
+    return schema
+
+
+def _validate_with_pydantic(
+    result: Any,
+    pydantic_class: Type[BaseModel]
+) -> BaseModel:
+    """Validate cloud response using original Pydantic class.
+
+    Args:
+        result: The result from cloud (dict or JSON string)
+        pydantic_class: The Pydantic model to validate against
+
+    Returns:
+        Validated Pydantic model instance
+
+    Raises:
+        ValidationError: If validation fails
+    """
+    if isinstance(result, dict):
+        return pydantic_class.model_validate(result)
+    elif isinstance(result, str):
+        return pydantic_class.model_validate_json(result)
+    elif isinstance(result, pydantic_class):
+        # Already validated
+        return result
+    raise ValueError(f"Cannot validate result type {type(result)} with Pydantic model")
+
+
+def _llm_invoke_cloud(
+    prompt: Optional[str],
+    input_json: Optional[Union[Dict[str, Any], List[Dict[str, Any]]]],
+    strength: float,
+    temperature: float,
+    verbose: bool,
+    output_pydantic: Optional[Type[BaseModel]],
+    output_schema: Optional[Dict[str, Any]],
+    time: float,
+    use_batch_mode: bool,
+    messages: Optional[Union[List[Dict[str, str]], List[List[Dict[str, str]]]]],
+    language: Optional[str],
+) -> Dict[str, Any]:
+    """Execute llm_invoke via cloud endpoint.
+
+    Args:
+        All parameters match llm_invoke signature
+
+    Returns:
+        Dictionary with 'result', 'cost', 'model_name', 'thinking_output'
+
+    Raises:
+        CloudFallbackError: For recoverable errors (network, timeout, auth)
+        InsufficientCreditsError: For 402 Payment Required
+        CloudInvocationError: For non-recoverable cloud errors
+    """
+    import requests
+    from rich.console import Console
+
+    # Lazy import to avoid circular dependency
+    from pdd.core.cloud import CloudConfig
+
+    console = Console()
+    CLOUD_TIMEOUT = 300  # 5 minutes
+
+    # Get JWT token
+    jwt_token = CloudConfig.get_jwt_token(verbose=verbose)
+    if not jwt_token:
+        raise CloudFallbackError("Could not authenticate with cloud")
+
+    # Prepare payload
+    payload: Dict[str, Any] = {
+        "strength": strength,
+        "temperature": temperature,
+        "time": time,
+        "verbose": verbose,
+        "useBatchMode": use_batch_mode,
+    }
+
+    if language:
+        payload["language"] = language
+
+    # Add prompt/messages
+    if messages:
+        payload["messages"] = messages
+    else:
+        payload["prompt"] = prompt
+        payload["inputJson"] = input_json
+
+    # Handle output schema
+    if output_pydantic:
+        payload["outputSchema"] = _pydantic_to_json_schema(output_pydantic)
+    elif output_schema:
+        payload["outputSchema"] = output_schema
+
+    # Make request
+    headers = {
+        "Authorization": f"Bearer {jwt_token}",
+        "Content-Type": "application/json"
+    }
+
+    cloud_url = CloudConfig.get_endpoint_url("llmInvoke")
+
+    if verbose:
+        logger.debug(f"Cloud llm_invoke request to: {cloud_url}")
+
+    try:
+        response = requests.post(
+            cloud_url,
+            json=payload,
+            headers=headers,
+            timeout=CLOUD_TIMEOUT
+        )
+
+        if response.status_code == 200:
+            data = response.json()
+            result = data.get("result")
+
+            # Validate with Pydantic if specified
+            if output_pydantic and result:
+                try:
+                    result = _validate_with_pydantic(result, output_pydantic)
+                except (ValidationError, ValueError) as e:
+                    logger.warning(f"Cloud response validation failed: {e}")
+                    # Return raw result if validation fails
+                    pass
+
+            return {
+                "result": result,
+                "cost": data.get("totalCost", 0.0),
+                "model_name": data.get("modelName", "cloud_model"),
+                "thinking_output": data.get("thinkingOutput"),
+            }
+
+        elif response.status_code == 402:
+            error_msg = response.json().get("error", "Insufficient credits")
+            raise InsufficientCreditsError(error_msg)
+
+        elif response.status_code in (401, 403):
+            error_msg = response.json().get("error", f"Authentication failed ({response.status_code})")
+            raise CloudFallbackError(error_msg)
+
+        elif response.status_code >= 500:
+            error_msg = response.json().get("error", f"Server error ({response.status_code})")
+            raise CloudFallbackError(error_msg)
+
+        else:
+            error_msg = response.json().get("error", f"HTTP {response.status_code}")
+            raise CloudInvocationError(f"Cloud llm_invoke failed: {error_msg}")
+
+    except requests.exceptions.Timeout:
+        raise CloudFallbackError("Cloud request timed out")
+    except requests.exceptions.ConnectionError as e:
+        raise CloudFallbackError(f"Cloud connection failed: {e}")
+    except requests.exceptions.RequestException as e:
+        raise CloudFallbackError(f"Cloud request failed: {e}")
+
+
 def _is_wsl_environment() -> bool:
     """
     Detect if we're running in WSL (Windows Subsystem for Linux) environment.
@@ -170,49 +474,26 @@ def _get_environment_info() -> Dict[str, str]:
 
 # --- Constants and Configuration ---
 
-# Determine project root: 1. PDD_PATH env var, 2. Search upwards from script, 3. CWD
-PROJECT_ROOT = None
+# Determine project root: use PathResolver to ignore package-root PDD_PATH values.
 PDD_PATH_ENV = os.getenv("PDD_PATH")
-
 if PDD_PATH_ENV:
-    _path_from_env = Path(PDD_PATH_ENV)
-    if _path_from_env.is_dir():
-        PROJECT_ROOT = _path_from_env.resolve()
-        logger.debug(f"Using PROJECT_ROOT from PDD_PATH: {PROJECT_ROOT}")
-    else:
-        warnings.warn(f"PDD_PATH environment variable ('{PDD_PATH_ENV}') is set but not a valid directory. Attempting auto-detection.")
-
-if PROJECT_ROOT is None: # If PDD_PATH wasn't set or was invalid
     try:
-        # Start from the current working directory (where user is running PDD)
-        current_dir = Path.cwd().resolve()
-        # Look for project markers (e.g., .git, pyproject.toml, data/, .env)
-        # Go up a maximum of 5 levels to prevent infinite loops
-        for _ in range(5):
-            has_git = (current_dir / ".git").exists()
-            has_pyproject = (current_dir / "pyproject.toml").exists()
-            has_data = (current_dir / "data").is_dir()
-            has_dotenv = (current_dir / ".env").exists()
-
-            if has_git or has_pyproject or has_data or has_dotenv:
-                PROJECT_ROOT = current_dir
-                logger.debug(f"Determined PROJECT_ROOT by marker search from CWD: {PROJECT_ROOT}")
-                break
-
-            parent_dir = current_dir.parent
-            if parent_dir == current_dir: # Reached filesystem root
-                break
-            current_dir = parent_dir
+        _path_from_env = Path(PDD_PATH_ENV).expanduser().resolve()
+        if not _path_from_env.is_dir():
+            warnings.warn(
+                f"PDD_PATH environment variable ('{PDD_PATH_ENV}') is set but not a valid directory. Attempting auto-detection."
+            )
+    except Exception as e:
+        warnings.warn(f"Error validating PDD_PATH environment variable: {e}")
 
-    except Exception as e: # Catch potential permission errors etc.
-        warnings.warn(f"Error during project root auto-detection from current working directory: {e}")
+resolver = get_default_resolver()
+PROJECT_ROOT = resolver.resolve_project_root()
+PROJECT_ROOT_FROM_ENV = resolver.pdd_path_env is not None and PROJECT_ROOT == resolver.pdd_path_env
+logger.debug(f"Using PROJECT_ROOT: {PROJECT_ROOT}")
 
-if PROJECT_ROOT is None: # Fallback to CWD if no method succeeded
-    PROJECT_ROOT = Path.cwd().resolve()
-    warnings.warn(f"Could not determine project root automatically. Using current working directory: {PROJECT_ROOT}. Ensure this is the intended root or set the PDD_PATH environment variable.")
 
+# ENV_PATH is set after _is_env_path_package_dir is defined (see below)
 
-ENV_PATH = PROJECT_ROOT / ".env"
 # --- Determine LLM_MODEL_CSV_PATH ---
 # Prioritize ~/.pdd/llm_model.csv, then a project .pdd from the current CWD,
 # then PROJECT_ROOT (which may be set from PDD_PATH), else fall back to package.
@@ -272,11 +553,19 @@ def _is_env_path_package_dir(env_path: Path) -> bool:
     except Exception:
         return False
 
+# ENV_PATH: Use CWD-based project root when PDD_PATH points to package directory
+# This ensures .env is written to the user's project, not the installed package location
+if _is_env_path_package_dir(PROJECT_ROOT):
+    ENV_PATH = project_root_from_cwd / ".env"
+    logger.debug(f"PDD_PATH points to package; using ENV_PATH from CWD: {ENV_PATH}")
+else:
+    ENV_PATH = PROJECT_ROOT / ".env"
+
 # Selection order
 if user_model_csv_path.is_file():
     LLM_MODEL_CSV_PATH = user_model_csv_path
     logger.info(f"Using user-specific LLM model CSV: {LLM_MODEL_CSV_PATH}")
-elif (not _is_env_path_package_dir(PROJECT_ROOT)) and project_csv_from_env.is_file():
+elif PROJECT_ROOT_FROM_ENV and project_csv_from_env.is_file():
     # Honor an explicitly-set PDD_PATH pointing to a real project directory
     LLM_MODEL_CSV_PATH = project_csv_from_env
     logger.info(f"Using project-specific LLM model CSV (from PDD_PATH): {LLM_MODEL_CSV_PATH}")
@@ -787,6 +1076,45 @@ def _sanitize_api_key(key_value: str) -> str:
     return sanitized
 
 
+def _save_key_to_env_file(key_name: str, value: str, env_path: Path) -> None:
+    """Save or update a key in the .env file.
+
+    - Replaces existing key in-place (no comment + append)
+    - Removes old commented versions of the same key (Issue #183)
+    - Preserves all other content
+    """
+    lines = []
+    if env_path.exists():
+        with open(env_path, 'r') as f:
+            lines = f.readlines()
+
+    new_lines = []
+    key_replaced = False
+    prefix = f"{key_name}="
+    prefix_spaced = f"{key_name} ="
+
+    for line in lines:
+        stripped = line.strip()
+        # Skip old commented versions of this key (cleanup accumulation)
+        if stripped.startswith(f"# {prefix}") or stripped.startswith(f"# {prefix_spaced}"):
+            continue
+        elif stripped.startswith(prefix) or stripped.startswith(prefix_spaced):
+            # Replace in-place
+            new_lines.append(f'{key_name}="{value}"\n')
+            key_replaced = True
+        else:
+            new_lines.append(line)
+
+    # Add key if not found
+    if not key_replaced:
+        if new_lines and not new_lines[-1].endswith('\n'):
+            new_lines.append('\n')
+        new_lines.append(f'{key_name}="{value}"\n')
+
+    with open(env_path, 'w') as f:
+        f.writelines(new_lines)
+
+
 def _ensure_api_key(model_info: Dict[str, Any], newly_acquired_keys: Dict[str, bool], verbose: bool) -> bool:
     """Checks for API key in env, prompts user if missing, and updates .env."""
     key_name = model_info.get('api_key')
@@ -807,6 +1135,12 @@ def _ensure_api_key(model_info: Dict[str, Any], newly_acquired_keys: Dict[str, b
         return True
     else:
         logger.warning(f"API key environment variable '{key_name}' for model '{model_info.get('model')}' is not set.")
+
+        # Skip prompting if --force flag is set (non-interactive mode)
+        if os.environ.get('PDD_FORCE'):
+            logger.error(f"API key '{key_name}' not set. In --force mode, skipping interactive prompt.")
+            return False
+
         try:
             # Interactive prompt
             user_provided_key = input(f"Please enter the API key for {key_name}: ").strip()
@@ -824,39 +1158,7 @@ def _ensure_api_key(model_info: Dict[str, Any], newly_acquired_keys: Dict[str, b
 
             # Update .env file
             try:
-                lines = []
-                if ENV_PATH.exists():
-                    with open(ENV_PATH, 'r') as f:
-                        lines = f.readlines()
-
-                new_lines = []
-                # key_updated = False
-                prefix = f"{key_name}="
-                prefix_spaced = f"{key_name} =" # Handle potential spaces
-
-                for line in lines:
-                    stripped_line = line.strip()
-                    if stripped_line.startswith(prefix) or stripped_line.startswith(prefix_spaced):
-                        # Comment out the old key
-                        new_lines.append(f"# {line}")
-                        # key_updated = True # Indicates we found an old line to comment
-                    elif stripped_line.startswith(f"# {prefix}") or stripped_line.startswith(f"# {prefix_spaced}"):
-                         # Keep already commented lines as they are
-                         new_lines.append(line)
-                    else:
-                        new_lines.append(line)
-
-                # Append the new key, ensuring quotes for robustness
-                new_key_line = f'{key_name}="{user_provided_key}"\n'
-                # Add newline before if file not empty and doesn't end with newline
-                if new_lines and not new_lines[-1].endswith('\n'):
-                     new_lines.append('\n')
-                new_lines.append(new_key_line)
-
-
-                with open(ENV_PATH, 'w') as f:
-                    f.writelines(new_lines)
-
+                _save_key_to_env_file(key_name, user_provided_key, ENV_PATH)
                 logger.info(f"API key '{key_name}' saved to {ENV_PATH}.")
                 logger.warning("SECURITY WARNING: The API key has been saved to your .env file. "
                        "Ensure this file is kept secure and is included in your .gitignore.")
@@ -878,7 +1180,6 @@ def _ensure_api_key(model_info: Dict[str, Any], newly_acquired_keys: Dict[str, b
 def _format_messages(prompt: str, input_data: Union[Dict[str, Any], List[Dict[str, Any]]], use_batch_mode: bool) -> Union[List[Dict[str, str]], List[List[Dict[str, str]]]]:
     """Formats prompt and input into LiteLLM message format."""
     try:
-        prompt_template = PromptTemplate.from_template(prompt)
         if use_batch_mode:
             if not isinstance(input_data, list):
                 raise ValueError("input_json must be a list of dictionaries when use_batch_mode is True.")
@@ -886,16 +1187,16 @@ def _format_messages(prompt: str, input_data: Union[Dict[str, Any], List[Dict[st
             for item in input_data:
                 if not isinstance(item, dict):
                      raise ValueError("Each item in input_json list must be a dictionary for batch mode.")
-                formatted_prompt = prompt_template.format(**item)
+                formatted_prompt = prompt.format(**item)
                 all_messages.append([{"role": "user", "content": formatted_prompt}])
             return all_messages
         else:
             if not isinstance(input_data, dict):
                 raise ValueError("input_json must be a dictionary when use_batch_mode is False.")
-            formatted_prompt = prompt_template.format(**input_data)
+            formatted_prompt = prompt.format(**input_data)
             return [{"role": "user", "content": formatted_prompt}]
     except KeyError as e:
-        raise ValueError(f"Prompt formatting error: Missing key {e} in input_json for prompt template.") from e
+        raise ValueError(f"Prompt formatting error: Missing key {e} in input_json for prompt string.") from e
     except Exception as e:
         raise ValueError(f"Error formatting prompt: {e}") from e
 
@@ -956,6 +1257,31 @@ def _looks_like_python_code(s: str) -> bool:
     return any(indicator in s for indicator in code_indicators)
 
 
+# Field names known to contain prose text, not Python code
+# These are skipped during syntax validation to avoid false positives
+_PROSE_FIELD_NAMES = frozenset({
+    'reasoning',           # PromptAnalysis - completeness reasoning
+    'explanation',         # TrimResultsOutput, FixerOutput - prose explanations
+    'analysis',            # DiffAnalysis, CodePatchResult - analysis text
+    'change_instructions', # ChangeInstruction, ConflictChange - instructions
+    'change_description',  # DiffAnalysis - description of changes
+    'planned_modifications', # CodePatchResult - modification plans
+    'details',             # VerificationOutput - issue details
+    'description',         # General prose descriptions
+    'focus',               # Focus descriptions
+    'file_summary',        # FileSummary - prose summaries of file contents
+})
+
+
+def _is_prose_field_name(field_name: str) -> bool:
+    """Check if a field name indicates it contains prose, not code.
+
+    Used to skip syntax validation on prose fields that may contain
+    Python keywords (like 'return' or 'import') but are not actual code.
+    """
+    return field_name.lower() in _PROSE_FIELD_NAMES
+
+
 def _repair_python_syntax(code: str) -> str:
     """
     Validate Python code syntax and attempt repairs if invalid.
@@ -1222,15 +1548,19 @@ def _unescape_code_newlines(obj: Any) -> Any:
     return obj
 
 
-def _has_invalid_python_code(obj: Any) -> bool:
+def _has_invalid_python_code(obj: Any, field_name: str = "") -> bool:
     """
     Check if any code-like string fields have invalid Python syntax.
 
     This is used after _unescape_code_newlines to detect if repair failed
     and we should retry with cache disabled.
 
+    Skips fields in _PROSE_FIELD_NAMES to avoid false positives on prose
+    text that mentions code patterns (e.g., "ends on a return statement").
+
     Args:
         obj: A Pydantic model, dict, list, or primitive value
+        field_name: The name of the field being validated (used to skip prose)
 
     Returns:
         True if there are invalid code fields that couldn't be repaired
@@ -1241,6 +1571,9 @@ def _has_invalid_python_code(obj: Any) -> bool:
         return False
 
     if isinstance(obj, str):
+        # Skip validation for known prose fields
+        if _is_prose_field_name(field_name):
+            return False
         if _looks_like_python_code(obj):
             try:
                 ast.parse(obj)
@@ -1250,21 +1583,22 @@ def _has_invalid_python_code(obj: Any) -> bool:
         return False
 
     if isinstance(obj, BaseModel):
-        for field_name in obj.model_fields:
-            value = getattr(obj, field_name)
-            if _has_invalid_python_code(value):
+        for name in obj.model_fields:
+            value = getattr(obj, name)
+            if _has_invalid_python_code(value, field_name=name):
                 return True
         return False
 
     if isinstance(obj, dict):
-        for value in obj.values():
-            if _has_invalid_python_code(value):
+        for key, value in obj.items():
+            fname = key if isinstance(key, str) else ""
+            if _has_invalid_python_code(value, field_name=fname):
                 return True
         return False
 
     if isinstance(obj, list):
         for item in obj:
-            if _has_invalid_python_code(item):
+            if _has_invalid_python_code(item, field_name=field_name):
                 return True
         return False
 
@@ -1281,9 +1615,11 @@ def llm_invoke(
     verbose: bool = False,
     output_pydantic: Optional[Type[BaseModel]] = None,
     output_schema: Optional[Dict[str, Any]] = None,
-    time: float = 0.25,
+    time: Optional[float] = 0.25,
     use_batch_mode: bool = False,
     messages: Optional[Union[List[Dict[str, str]], List[List[Dict[str, str]]]]] = None,
+    language: Optional[str] = None,
+    use_cloud: Optional[bool] = None,
 ) -> Dict[str, Any]:
     """
     Runs a prompt with given input using LiteLLM, handling model selection,
@@ -1301,6 +1637,7 @@ def llm_invoke(
         time: Relative thinking time (0-1, default 0.25).
         use_batch_mode: Use batch completion if True.
         messages: Pre-formatted list of messages (or list of lists for batch). If provided, ignores prompt and input_json.
+        use_cloud: None=auto-detect (cloud if enabled, local if PDD_FORCE_LOCAL=1), True=force cloud, False=force local.
 
     Returns:
         Dictionary containing 'result', 'cost', 'model_name', 'thinking_output'.
@@ -1309,6 +1646,7 @@ def llm_invoke(
         ValueError: For invalid inputs or prompt formatting errors.
         FileNotFoundError: If llm_model.csv is missing.
         RuntimeError: If all candidate models fail.
+        InsufficientCreditsError: If cloud execution fails due to insufficient credits.
         openai.*Error: If LiteLLM encounters API errors after retries.
     """
     # Set verbose logging if requested
@@ -1325,6 +1663,58 @@ def llm_invoke(
         logger.debug(f"  time: {time}")
         logger.debug(f"  use_batch_mode: {use_batch_mode}")
         logger.debug(f"  messages: {'provided' if messages else 'None'}")
+        logger.debug(f"  use_cloud: {use_cloud}")
+
+    # --- 0. Cloud Execution Path ---
+    # Determine cloud usage: explicit param > environment > default (local)
+    if use_cloud is None:
+        # Check environment for cloud preference
+        # PDD_FORCE_LOCAL=1 forces local execution
+        force_local = os.environ.get("PDD_FORCE_LOCAL", "").lower() in ("1", "true", "yes")
+        if force_local:
+            use_cloud = False
+        else:
+            # Try to use cloud if credentials are configured
+            try:
+                from pdd.core.cloud import CloudConfig
+                use_cloud = CloudConfig.is_cloud_enabled()
+            except ImportError:
+                use_cloud = False
+
+    if use_cloud:
+        from rich.console import Console
+        console = Console()
+
+        if verbose:
+            logger.debug("Attempting cloud execution...")
+
+        try:
+            return _llm_invoke_cloud(
+                prompt=prompt,
+                input_json=input_json,
+                strength=strength,
+                temperature=temperature,
+                verbose=verbose,
+                output_pydantic=output_pydantic,
+                output_schema=output_schema,
+                time=time,
+                use_batch_mode=use_batch_mode,
+                messages=messages,
+                language=language,
+            )
+        except CloudFallbackError as e:
+            # Notify user and fall back to local execution
+            console.print(f"[yellow]Cloud execution failed ({e}), falling back to local execution...[/yellow]")
+            logger.warning(f"Cloud fallback: {e}")
+            # Continue to local execution below
+        except InsufficientCreditsError:
+            # Re-raise credit errors - user needs to know
+            raise
+        except CloudInvocationError as e:
+            # Non-recoverable cloud error - notify and fall back
+            console.print(f"[yellow]Cloud error ({e}), falling back to local execution...[/yellow]")
+            logger.warning(f"Cloud invocation error: {e}")
+            # Continue to local execution below
 
     # --- 1. Load Environment & Validate Inputs ---
     # .env loading happens at module level
@@ -1349,6 +1739,10 @@ def llm_invoke(
     else:
         raise ValueError("Either 'messages' or both 'prompt' and 'input_json' must be provided.")
 
+    # Handle None time (means "no reasoning requested")
+    if time is None:
+        time = 0.0
+
     if not (0.0 <= strength <= 1.0):
         raise ValueError("'strength' must be between 0.0 and 1.0.")
     if not (0.0 <= temperature <= 2.0): # Common range for temperature
@@ -1454,6 +1848,8 @@ def llm_invoke(
                 "messages": formatted_messages,
                 # Use a local adjustable temperature to allow provider-specific fallbacks
                 "temperature": current_temperature,
+                # Retry on transient network errors (APIError, TimeoutError, ServiceUnavailableError)
+                "num_retries": 2,
             }
 
             api_key_name_from_csv = model_info.get('api_key') # From CSV
@@ -1586,11 +1982,20 @@ def llm_invoke(
                     if output_pydantic:
                         if verbose:
                             logger.info(f"[INFO] Requesting structured output (Pydantic: {output_pydantic.__name__}) for {model_name_litellm}")
-                        # Use explicit json_object format with response_schema for better Gemini/Vertex AI compatibility
-                        # Passing Pydantic class directly may not trigger native structured output for all providers
+                        # Use json_schema with strict=True to enforce ALL required fields are present
+                        # This prevents LLMs from omitting required fields when they think they're not needed
+                        schema = output_pydantic.model_json_schema()
+                        # Ensure all properties are in required array (OpenAI strict mode requirement)
+                        _ensure_all_properties_required(schema)
+                        # Add additionalProperties: false recursively for strict mode (required by OpenAI)
+                        _add_additional_properties_false(schema)
                         response_format = {
-                            "type": "json_object",
-                            "response_schema": output_pydantic.model_json_schema()
+                            "type": "json_schema",
+                            "json_schema": {
+                                "name": output_pydantic.__name__,
+                                "schema": schema,
+                                "strict": True
+                            }
                         }
                     else: # output_schema is set
                         if verbose:
@@ -1608,7 +2013,11 @@ def llm_invoke(
                                 "strict": False
                             }
                         }
-                    
+                        # Ensure all properties are in required array (OpenAI strict mode requirement)
+                        _ensure_all_properties_required(response_format["json_schema"]["schema"])
+                        # Add additionalProperties: false recursively for strict mode (required by OpenAI)
+                        _add_additional_properties_false(response_format["json_schema"]["schema"])
+
                     litellm_kwargs["response_format"] = response_format
 
                     # LM Studio requires "json_schema" format, not "json_object"
@@ -1792,8 +2201,10 @@ def llm_invoke(
                                     schema = output_schema
                                     name = "response"
 
-                                # Add additionalProperties: false for strict mode (required by OpenAI)
-                                schema['additionalProperties'] = False
+                                # Ensure all properties are in required array (OpenAI strict mode requirement)
+                                _ensure_all_properties_required(schema)
+                                # Add additionalProperties: false recursively for strict mode (required by OpenAI)
+                                _add_additional_properties_false(schema)
 
                                 # Use text.format with json_schema for structured output
                                 text_block = {
@@ -1941,6 +2352,12 @@ def llm_invoke(
                 if verbose:
                     logger.info(f"[SUCCESS] Invocation successful for {model_name_litellm} (took {end_time - start_time:.2f}s)")
 
+                # Build retry kwargs with provider credentials from litellm_kwargs
+                # Issue #185: Retry calls were missing vertex_location, vertex_project, etc.
+                retry_provider_kwargs = {k: v for k, v in litellm_kwargs.items()
+                                         if k in ('vertex_credentials', 'vertex_project', 'vertex_location',
+                                                  'api_key', 'base_url', 'api_base')}
+
                 # --- 7. Process Response ---
                 results = []
                 thinking_outputs = []
@@ -1991,7 +2408,8 @@ def llm_invoke(
                                         messages=retry_messages,
                                         temperature=current_temperature,
                                         response_format=response_format,
-                                        **time_kwargs
+                                        **time_kwargs,
+                                        **retry_provider_kwargs  # Issue #185: Pass Vertex AI credentials
                                     )
                                     # Re-enable cache - restore original configured cache (restore to original state, even if None)
                                     litellm.cache = configured_cache
@@ -2030,7 +2448,8 @@ def llm_invoke(
                                         messages=retry_messages,
                                         temperature=current_temperature,
                                         response_format=response_format,
-                                        **time_kwargs
+                                        **time_kwargs,
+                                        **retry_provider_kwargs  # Issue #185: Pass Vertex AI credentials
                                     )
                                     # Re-enable cache
                                     litellm.cache = original_cache
@@ -2237,16 +2656,22 @@ def llm_invoke(
                                 logger.error(f"[ERROR] Failed to parse response into {target_name} for item {i}: {parse_error}")
                                 # Use the string that was last attempted for parsing in the error message
                                 error_content = json_string_to_parse if json_string_to_parse is not None else raw_result
-                                logger.error("[ERROR] Content attempted for parsing: %s", repr(error_content)) # CORRECTED (or use f-string)
-                                results.append(f"ERROR: Failed to parse structured output. Raw: {repr(raw_result)}")
-                                continue # Skip appending result below if parsing failed
+                                logger.error("[ERROR] Content attempted for parsing: %s", repr(error_content))
+                                # Issue #168: Raise SchemaValidationError to trigger model fallback
+                                # Previously this used `continue` which only skipped to the next batch item
+                                raise SchemaValidationError(
+                                    f"Failed to parse response into {target_name}: {parse_error}",
+                                    raw_response=raw_result,
+                                    item_index=i
+                                ) from parse_error
 
                             # Post-process: unescape newlines and repair Python syntax
                             _unescape_code_newlines(parsed_result)
 
                             # Check if code fields still have invalid Python syntax after repair
                             # If so, retry without cache to get a fresh response
-                            if _has_invalid_python_code(parsed_result):
+                            # Skip validation for non-Python languages to avoid false positives
+                            if language in (None, "python") and _has_invalid_python_code(parsed_result):
                                 logger.warning(f"[WARNING] Detected invalid Python syntax in code fields for item {i} after repair. Retrying with cache bypass...")
                                 if not use_batch_mode and prompt and input_json is not None:
                                     # Add a small variation to bypass cache
@@ -2261,7 +2686,8 @@ def llm_invoke(
                                             messages=retry_messages,
                                             temperature=current_temperature,
                                             response_format=response_format,
-                                            **time_kwargs
+                                            **time_kwargs,
+                                            **retry_provider_kwargs  # Issue #185: Pass Vertex AI credentials
                                         )
                                         # Re-enable cache
                                         litellm.cache = original_cache
@@ -2377,6 +2803,14 @@ def llm_invoke(
                     logger.warning(f"[AUTH ERROR] Authentication failed for {model_name_litellm} using existing key '{api_key_name}'. Trying next model.")
                     break # Break inner loop, try next model candidate
 
+            except SchemaValidationError as e:
+                # Issue #168: Schema validation failures now trigger model fallback
+                last_exception = e
+                logger.warning(f"[SCHEMA ERROR] Validation failed for {model_name_litellm}: {e}. Trying next model.")
+                if verbose:
+                    logger.debug(f"Raw response that failed validation: {repr(e.raw_response)}")
+                break  # Break inner loop, try next model candidate
+
             except (openai.RateLimitError, openai.APITimeoutError, openai.APIConnectionError,
                     openai.APIStatusError, openai.BadRequestError, openai.InternalServerError,
                     Exception) as e: # Catch generic Exception last