ostruct-cli 0.7.2__py3-none-any.whl → 0.8.0__py3-none-any.whl

ostruct/cli/errors.py

@@ -4,6 +4,8 @@ import json
 import logging
 from typing import Any, Dict, List, Optional
 
+from openai import OpenAIError
+
 from .base_errors import CLIError, OstructFileNotFoundError
 from .exit_codes import ExitCode
 from .security.base import SecurityErrorBase
@@ -30,6 +32,27 @@ class VariableValueError(VariableError):
     pass
 
 
+class DuplicateFileMappingError(VariableError):
+    """Raised when duplicate file mappings are detected."""
+
+    def __init__(
+        self,
+        message: str,
+        context: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Initialize error.
+
+        Args:
+            message: Error message
+            context: Additional error context
+        """
+        super().__init__(
+            message,
+            context=context,
+            exit_code=ExitCode.USAGE_ERROR,
+        )
+
+
 class InvalidJSONError(CLIError):
     """Error raised when JSON is invalid."""
 
@@ -426,12 +449,89 @@ class InvalidResponseFormatError(CLIError):
         )
 
 
-class OpenAIClientError(CLIError):
-    """Exception raised when there's an error with the OpenAI client.
+# Tool-specific error classes (T3.1)
 
-    This is a wrapper around openai_structured's OpenAIClientError to maintain
-    compatibility with our CLI error handling.
-    """
+
+class FileSearchError(CLIError):
+    """File Search tool failures with retry guidance."""
+
+    def __init__(
+        self,
+        message: str,
+        exit_code: ExitCode = ExitCode.API_ERROR,
+        context: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(message, exit_code=exit_code, context=context)
+
+
+class FileSearchUploadError(FileSearchError):
+    """File upload to vector store failed."""
+
+    pass
+
+
+class MCPConnectionError(CLIError):
+    """MCP server connection failures."""
+
+    def __init__(
+        self,
+        message: str,
+        exit_code: ExitCode = ExitCode.API_ERROR,
+        context: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(message, exit_code=exit_code, context=context)
+
+
+class ContainerExpiredError(CLIError):
+    """Code Interpreter container expired (20-minute limit)."""
+
+    def __init__(
+        self,
+        message: str,
+        exit_code: ExitCode = ExitCode.API_ERROR,
+        context: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(message, exit_code=exit_code, context=context)
+
+
+class UnattendedOperationTimeoutError(CLIError):
+    """Operation timed out during unattended execution."""
+
+    def __init__(
+        self,
+        message: str,
+        exit_code: ExitCode = ExitCode.OPERATION_TIMEOUT,
+        context: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(message, exit_code=exit_code, context=context)
+
+
+class PromptTooLargeError(CLIError):
+    """Prompt exceeds context window limits."""
+
+    def __init__(
+        self,
+        message: str,
+        exit_code: ExitCode = ExitCode.VALIDATION_ERROR,
+        context: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(message, exit_code=exit_code, context=context)
+
+
+class AuthenticationError(CLIError):
+    """API authentication failures."""
+
+    def __init__(
+        self,
+        message: str,
+        exit_code: ExitCode = ExitCode.API_ERROR,
+        context: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(message, exit_code=exit_code, context=context)
+
+
+class RateLimitError(CLIError):
+    """API rate limiting errors."""
 
     def __init__(
         self,
@@ -442,6 +542,133 @@ class OpenAIClientError(CLIError):
         super().__init__(message, exit_code=exit_code, context=context)
 
 
+class APIError(CLIError):
+    """Generic API errors."""
+
+    def __init__(
+        self,
+        message: str,
+        exit_code: ExitCode = ExitCode.API_ERROR,
+        context: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(message, exit_code=exit_code, context=context)
+
+
+# API Error Mapping (T3.1)
+
+
+class APIErrorMapper:
+    """Maps OpenAI SDK errors to ostruct-specific errors with actionable guidance."""
+
+    @staticmethod
+    def map_openai_error(error: OpenAIError) -> CLIError:
+        """Map OpenAI SDK errors to ostruct errors (validated patterns).
+
+        Args:
+            error: OpenAI SDK error to map
+
+        Returns:
+            Appropriate ostruct error with actionable guidance
+        """
+        error_msg = str(error).lower()
+
+        # Context window errors (confirmed pattern)
+        if (
+            "context_length_exceeded" in error_msg
+            or "maximum context length" in error_msg
+        ):
+            return PromptTooLargeError(
+                f"Prompt exceeds model context window (128,000 token limit). "
+                f"Tip: Use explicit file routing (-fc for code, -fs for docs, -ft for config). "
+                f"Original error: {error}"
+            )
+
+        # Authentication errors (confirmed pattern)
+        if "invalid_api_key" in error_msg or "incorrect api key" in error_msg:
+            return AuthenticationError(
+                f"Invalid OpenAI API key. Please check your OPENAI_API_KEY environment variable. "
+                f"Original error: {error}"
+            )
+
+        # Rate limiting (standard pattern)
+        if "rate_limit" in error_msg:
+            return RateLimitError(
+                f"OpenAI API rate limit exceeded. Please wait and try again. "
+                f"Original error: {error}"
+            )
+
+        # Schema validation errors (Responses API specific)
+        if "invalid schema for response_format" in error_msg:
+            return SchemaValidationError(
+                f"Schema validation failed for Responses API. "
+                f"Ensure your schema is compatible with strict mode. "
+                f"Original error: {error}"
+            )
+
+        # Container expiration errors (Code Interpreter specific)
+        if "container" in error_msg and (
+            "expired" in error_msg or "timeout" in error_msg
+        ):
+            return ContainerExpiredError(
+                f"Code Interpreter container expired (20-minute runtime limit, 2-minute idle timeout). "
+                f"Please retry your request. Original error: {error}"
+            )
+
+        # File Search errors
+        if "vector_store" in error_msg or "file_search" in error_msg:
+            return FileSearchError(
+                f"File Search operation failed. This can be intermittent - consider retrying. "
+                f"Original error: {error}"
+            )
+
+        # MCP connection errors
+        if "mcp" in error_msg or "model context protocol" in error_msg:
+            return MCPConnectionError(
+                f"MCP server connection failed. Check server URL and network connectivity. "
+                f"Original error: {error}"
+            )
+
+        # Generic API error
+        return APIError(f"OpenAI API error: {error}")
+
+    @staticmethod
+    def map_tool_error(tool_name: str, error: Exception) -> CLIError:
+        """Map tool-specific errors to ostruct errors.
+
+        Args:
+            tool_name: Name of the tool that failed
+            error: The original error
+
+        Returns:
+            Appropriate ostruct error with tool-specific guidance
+        """
+        error_msg = str(error).lower()
+
+        if tool_name == "file-search":
+            if "upload" in error_msg or "vector_store" in error_msg:
+                return FileSearchUploadError(
+                    f"File Search upload failed: {error}. "
+                    f"This can be intermittent - retry with --file-search-retry-count option."
+                )
+            return FileSearchError(f"File Search error: {error}")
+
+        elif tool_name == "code-interpreter":
+            if "container" in error_msg:
+                return ContainerExpiredError(
+                    f"Code Interpreter container error: {error}. "
+                    f"Container has 20-minute runtime and 2-minute idle limits."
+                )
+            return APIError(f"Code Interpreter error: {error}")
+
+        elif tool_name == "mcp":
+            return MCPConnectionError(
+                f"MCP server error: {error}. "
+                f"Check server connectivity and require_approval='never' setting."
+            )
+
+        return APIError(f"{tool_name} error: {error}")
+
+
 class SchemaValidationError(ModelCreationError):
     """Raised when schema validation fails."""
 
@@ -503,9 +730,86 @@ class SchemaValidationError(ModelCreationError):
         super().__init__(final_message, context=context, exit_code=exit_code)
 
 
+def handle_error(e: Exception) -> None:
+    """Handle CLI errors and display appropriate messages.
+
+    Maintains specific error type handling while reducing duplication.
+    Provides enhanced debug logging for CLI errors.
+    """
+    import sys
+
+    import click
+
+    # 1. Determine error type and message
+    if isinstance(e, SchemaValidationError):
+        msg = str(e)  # Already formatted in SchemaValidationError
+        exit_code = e.exit_code
+    elif isinstance(e, ModelCreationError):
+        # Unwrap ModelCreationError that might wrap SchemaValidationError
+        if isinstance(e.__cause__, SchemaValidationError):
+            return handle_error(e.__cause__)
+        msg = f"Model creation error: {str(e)}"
+        exit_code = ExitCode.SCHEMA_ERROR
+    elif isinstance(e, click.UsageError):
+        msg = f"Usage error: {str(e)}"
+        exit_code = ExitCode.USAGE_ERROR
+    elif isinstance(e, SchemaFileError):
+        msg = str(e)  # Use existing __str__ formatting
+        exit_code = ExitCode.SCHEMA_ERROR
+    elif isinstance(e, (InvalidJSONError, json.JSONDecodeError)):
+        msg = f"Invalid JSON error: {str(e)}"
+        exit_code = ExitCode.DATA_ERROR
+    elif isinstance(e, CLIError):
+        msg = str(e)  # Use existing __str__ formatting
+        exit_code = ExitCode(e.exit_code)  # Convert int to ExitCode
+    else:
+        msg = f"Unexpected error: {str(e)}"
+        exit_code = ExitCode.INTERNAL_ERROR
+
+    # 2. Debug logging
+    if isinstance(e, CLIError) and logger.isEnabledFor(logging.DEBUG):
+        # Format context fields with lowercase keys and simple values
+        context_str = ""
+        if hasattr(e, "context") and e.context:
+            for key, value in sorted(e.context.items()):
+                if key not in {
+                    "timestamp",
+                    "host",
+                    "version",
+                    "python_version",
+                }:
+                    if isinstance(value, dict):
+                        context_str += (
+                            f"{key.lower()}:\n{json.dumps(value, indent=2)}\n"
+                        )
+                    else:
+                        context_str += f"{key.lower()}: {value}\n"
+
+            logger.debug(
+                f"Error details:\nType: {type(e).__name__}\n{context_str.rstrip()}"
+            )
+    elif not isinstance(
+        e,
+        (
+            click.UsageError,
+            DuplicateFileMappingError,
+            VariableNameError,
+            VariableValueError,
+        ),
+    ):
+        logger.error(msg, exc_info=True)
+
+    # 3. User output
+    click.secho(msg, fg="red", err=True)
+    sys.exit(exit_code)
+
+
 # Export public API
 __all__ = [
     "VariableError",
+    "VariableNameError",
+    "VariableValueError",
+    "DuplicateFileMappingError",
     "PathError",
     "PathSecurityError",
     "OstructFileNotFoundError",
@@ -522,5 +826,5 @@ __all__ = [
     "APIResponseError",
     "EmptyResponseError",
     "InvalidResponseFormatError",
-    "OpenAIClientError",
+    "handle_error",
 ]

ostruct/cli/exit_codes.py

@@ -16,3 +16,4 @@ class ExitCode(IntEnum):
     UNKNOWN_ERROR = 7
     SECURITY_ERROR = 8
     FILE_ERROR = 9
+    OPERATION_TIMEOUT = 10