smartify-ai 0.1.0__py3-none-any.whl

smartify/api/errors.py

@@ -0,0 +1,380 @@
+"""Smartify API Error Taxonomy.
+
+Provides consistent error codes, response models, and exception handlers
+for SDK-friendly error responses.
+"""
+
+from enum import Enum
+from typing import Any, Dict, List, Optional
+from datetime import datetime, timezone
+
+from fastapi import Request, status
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, Field, ConfigDict
+
+
+# ============================================================================
+# Error Codes
+# ============================================================================
+
+class ErrorCode(str, Enum):
+    """Typed error codes for SDK consumption.
+    
+    Naming convention: RESOURCE_ACTION_REASON
+    """
+    
+    # Validation errors (400)
+    VALIDATION_FAILED = "VALIDATION_FAILED"
+    INVALID_YAML = "INVALID_YAML"
+    INVALID_GRID_SPEC = "INVALID_GRID_SPEC"
+    INVALID_INPUT = "INVALID_INPUT"
+    MISSING_REQUIRED_FIELD = "MISSING_REQUIRED_FIELD"
+    
+    # Resource errors (404)
+    GRID_NOT_FOUND = "GRID_NOT_FOUND"
+    NODE_NOT_FOUND = "NODE_NOT_FOUND"
+    RUN_NOT_FOUND = "RUN_NOT_FOUND"
+    APPROVAL_NOT_FOUND = "APPROVAL_NOT_FOUND"
+    
+    # State/lifecycle errors (409)
+    GRID_INVALID_STATE = "GRID_INVALID_STATE"
+    GRID_ALREADY_RUNNING = "GRID_ALREADY_RUNNING"
+    GRID_NOT_RUNNING = "GRID_NOT_RUNNING"
+    GRID_ALREADY_COMPLETED = "GRID_ALREADY_COMPLETED"
+    NODE_ALREADY_COMPLETED = "NODE_ALREADY_COMPLETED"
+    
+    # Limit/guardrail errors (429)
+    BREAKER_TRIPPED = "BREAKER_TRIPPED"
+    RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED"
+    TOKEN_LIMIT_EXCEEDED = "TOKEN_LIMIT_EXCEEDED"
+    COST_LIMIT_EXCEEDED = "COST_LIMIT_EXCEEDED"
+    TIME_LIMIT_EXCEEDED = "TIME_LIMIT_EXCEEDED"
+    
+    # Auth errors (401/403)
+    UNAUTHORIZED = "UNAUTHORIZED"
+    INVALID_API_KEY = "INVALID_API_KEY"
+    FORBIDDEN = "FORBIDDEN"
+    INSUFFICIENT_PERMISSIONS = "INSUFFICIENT_PERMISSIONS"
+    
+    # Execution errors (500)
+    EXECUTION_FAILED = "EXECUTION_FAILED"
+    LLM_ADAPTER_ERROR = "LLM_ADAPTER_ERROR"
+    TOOL_EXECUTION_ERROR = "TOOL_EXECUTION_ERROR"
+    CHECKPOINT_ERROR = "CHECKPOINT_ERROR"
+    WEBHOOK_DELIVERY_FAILED = "WEBHOOK_DELIVERY_FAILED"
+    
+    # External service errors (502/503)
+    LLM_SERVICE_UNAVAILABLE = "LLM_SERVICE_UNAVAILABLE"
+    LLM_RATE_LIMITED = "LLM_RATE_LIMITED"
+    EXTERNAL_SERVICE_ERROR = "EXTERNAL_SERVICE_ERROR"
+    
+    # Internal errors (500)
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+    NOT_IMPLEMENTED = "NOT_IMPLEMENTED"
+
+
+# ============================================================================
+# Retryability
+# ============================================================================
+
+# Errors that are safe to retry (typically transient)
+RETRYABLE_ERRORS = {
+    ErrorCode.LLM_SERVICE_UNAVAILABLE,
+    ErrorCode.LLM_RATE_LIMITED,
+    ErrorCode.EXTERNAL_SERVICE_ERROR,
+    ErrorCode.WEBHOOK_DELIVERY_FAILED,
+    ErrorCode.RATE_LIMIT_EXCEEDED,
+}
+
+# Errors that should NOT be retried (permanent failures)
+NON_RETRYABLE_ERRORS = {
+    ErrorCode.VALIDATION_FAILED,
+    ErrorCode.INVALID_YAML,
+    ErrorCode.INVALID_GRID_SPEC,
+    ErrorCode.INVALID_INPUT,
+    ErrorCode.MISSING_REQUIRED_FIELD,
+    ErrorCode.GRID_NOT_FOUND,
+    ErrorCode.NODE_NOT_FOUND,
+    ErrorCode.UNAUTHORIZED,
+    ErrorCode.INVALID_API_KEY,
+    ErrorCode.FORBIDDEN,
+    ErrorCode.INSUFFICIENT_PERMISSIONS,
+}
+
+
+def is_retryable(code: ErrorCode) -> bool:
+    """Check if an error code indicates a retryable condition."""
+    return code in RETRYABLE_ERRORS
+
+
+# ============================================================================
+# Error Response Models
+# ============================================================================
+
+class ErrorDetail(BaseModel):
+    """Additional error context."""
+    field: Optional[str] = Field(None, description="Field that caused the error")
+    value: Optional[Any] = Field(None, description="Invalid value")
+    constraint: Optional[str] = Field(None, description="Constraint that was violated")
+    suggestion: Optional[str] = Field(None, description="Suggested fix")
+
+
+class ErrorResponse(BaseModel):
+    """Standard error response for all API errors.
+    
+    SDK clients can rely on this consistent structure.
+    """
+    error: str = Field(..., description="Error code from ErrorCode enum")
+    message: str = Field(..., description="Human-readable error message")
+    retryable: bool = Field(..., description="Whether this error is safe to retry")
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    request_id: Optional[str] = Field(None, description="Request tracking ID")
+    details: Optional[List[ErrorDetail]] = Field(None, description="Additional error context")
+    
+    # For breaker/limit errors
+    retry_after: Optional[int] = Field(None, description="Seconds to wait before retry (for rate limits)")
+    
+    # For debugging (only in non-production)
+    debug: Optional[Dict[str, Any]] = Field(None, description="Debug info (dev only)")
+    
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "error": "GRID_NOT_FOUND",
+                "message": "Grid with ID 'abc123' not found",
+                "retryable": False,
+                "timestamp": "2026-02-02T04:30:00Z",
+                "request_id": "req_xyz789",
+                "details": None,
+                "retry_after": None
+            }
+        }
+    )
+
+
+# ============================================================================
+# API Exception Classes
+# ============================================================================
+
+class SmartifyAPIError(Exception):
+    """Base exception for Smartify API errors."""
+    
+    def __init__(
+        self,
+        code: ErrorCode,
+        message: str,
+        status_code: int = 500,
+        details: Optional[List[ErrorDetail]] = None,
+        retry_after: Optional[int] = None,
+        debug: Optional[Dict[str, Any]] = None,
+    ):
+        self.code = code
+        self.message = message
+        self.status_code = status_code
+        self.details = details
+        self.retry_after = retry_after
+        self.debug = debug
+        super().__init__(message)
+    
+    def to_response(self, request_id: Optional[str] = None, include_debug: bool = False) -> ErrorResponse:
+        """Convert to ErrorResponse model."""
+        return ErrorResponse(
+            error=self.code.value,
+            message=self.message,
+            retryable=is_retryable(self.code),
+            request_id=request_id,
+            details=self.details,
+            retry_after=self.retry_after,
+            debug=self.debug if include_debug else None,
+        )
+
+
+# Convenience exception classes for common error types
+
+class ValidationError(SmartifyAPIError):
+    """Raised for validation failures."""
+    def __init__(self, message: str, details: Optional[List[ErrorDetail]] = None):
+        super().__init__(
+            code=ErrorCode.VALIDATION_FAILED,
+            message=message,
+            status_code=status.HTTP_400_BAD_REQUEST,
+            details=details,
+        )
+
+
+class GridNotFoundError(SmartifyAPIError):
+    """Raised when a grid is not found."""
+    def __init__(self, grid_id: str):
+        super().__init__(
+            code=ErrorCode.GRID_NOT_FOUND,
+            message=f"Grid with ID '{grid_id}' not found",
+            status_code=status.HTTP_404_NOT_FOUND,
+        )
+
+
+class NodeNotFoundError(SmartifyAPIError):
+    """Raised when a node is not found."""
+    def __init__(self, grid_id: str, node_id: str):
+        super().__init__(
+            code=ErrorCode.NODE_NOT_FOUND,
+            message=f"Node '{node_id}' not found in grid '{grid_id}'",
+            status_code=status.HTTP_404_NOT_FOUND,
+        )
+
+
+class GridStateError(SmartifyAPIError):
+    """Raised for invalid state transitions."""
+    def __init__(self, message: str, current_state: str, expected_states: List[str]):
+        super().__init__(
+            code=ErrorCode.GRID_INVALID_STATE,
+            message=message,
+            status_code=status.HTTP_409_CONFLICT,
+            details=[
+                ErrorDetail(
+                    field="state",
+                    value=current_state,
+                    constraint=f"Expected one of: {', '.join(expected_states)}",
+                )
+            ],
+        )
+
+
+class BreakerTrippedError(SmartifyAPIError):
+    """Raised when a breaker/guardrail is tripped."""
+    def __init__(
+        self,
+        breaker_type: str,
+        limit: float,
+        current: float,
+        retry_after: Optional[int] = None,
+    ):
+        code_map = {
+            "tokens": ErrorCode.TOKEN_LIMIT_EXCEEDED,
+            "cost": ErrorCode.COST_LIMIT_EXCEEDED,
+            "time": ErrorCode.TIME_LIMIT_EXCEEDED,
+        }
+        super().__init__(
+            code=code_map.get(breaker_type, ErrorCode.BREAKER_TRIPPED),
+            message=f"{breaker_type.title()} limit exceeded: {current:.2f} / {limit:.2f}",
+            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+            retry_after=retry_after,
+            details=[
+                ErrorDetail(
+                    field=breaker_type,
+                    value=current,
+                    constraint=f"Maximum: {limit}",
+                )
+            ],
+        )
+
+
+class RateLimitError(SmartifyAPIError):
+    """Raised when API rate limit is exceeded."""
+    def __init__(self, retry_after: int = 60):
+        super().__init__(
+            code=ErrorCode.RATE_LIMIT_EXCEEDED,
+            message="API rate limit exceeded",
+            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+            retry_after=retry_after,
+        )
+
+
+class AuthenticationError(SmartifyAPIError):
+    """Raised for authentication failures."""
+    def __init__(self, message: str = "Invalid or missing API key"):
+        super().__init__(
+            code=ErrorCode.INVALID_API_KEY,
+            message=message,
+            status_code=status.HTTP_401_UNAUTHORIZED,
+        )
+
+
+class ExecutionError(SmartifyAPIError):
+    """Raised when grid execution fails."""
+    def __init__(self, message: str, node_id: Optional[str] = None):
+        details = None
+        if node_id:
+            details = [ErrorDetail(field="node_id", value=node_id)]
+        super().__init__(
+            code=ErrorCode.EXECUTION_FAILED,
+            message=message,
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            details=details,
+        )
+
+
+class LLMServiceError(SmartifyAPIError):
+    """Raised when LLM service is unavailable."""
+    def __init__(self, provider: str, message: str, retry_after: Optional[int] = 30):
+        super().__init__(
+            code=ErrorCode.LLM_SERVICE_UNAVAILABLE,
+            message=f"{provider} service error: {message}",
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            retry_after=retry_after,
+            details=[ErrorDetail(field="provider", value=provider)],
+        )
+
+
+# ============================================================================
+# Exception Handlers
+# ============================================================================
+
+def get_request_id(request: Request) -> Optional[str]:
+    """Extract request ID from headers or generate one."""
+    return request.headers.get("X-Request-ID") or request.headers.get("X-Correlation-ID")
+
+
+async def smartify_error_handler(request: Request, exc: SmartifyAPIError) -> JSONResponse:
+    """Handle SmartifyAPIError exceptions."""
+    request_id = get_request_id(request)
+    include_debug = request.app.debug if hasattr(request.app, 'debug') else False
+    
+    response = exc.to_response(request_id=request_id, include_debug=include_debug)
+    
+    headers = {}
+    if exc.retry_after:
+        headers["Retry-After"] = str(exc.retry_after)
+    
+    return JSONResponse(
+        status_code=exc.status_code,
+        content=response.model_dump(mode="json", exclude_none=True),
+        headers=headers,
+    )
+
+
+async def generic_error_handler(request: Request, exc: Exception) -> JSONResponse:
+    """Handle unexpected exceptions."""
+    import traceback
+    import logging
+    
+    logger = logging.getLogger(__name__)
+    logger.exception(f"Unhandled exception: {exc}")
+    
+    request_id = get_request_id(request)
+    include_debug = request.app.debug if hasattr(request.app, 'debug') else False
+    
+    debug_info = None
+    if include_debug:
+        debug_info = {
+            "exception_type": type(exc).__name__,
+            "traceback": traceback.format_exc(),
+        }
+    
+    response = ErrorResponse(
+        error=ErrorCode.INTERNAL_ERROR.value,
+        message="An unexpected error occurred",
+        retryable=False,
+        request_id=request_id,
+        debug=debug_info,
+    )
+    
+    return JSONResponse(
+        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        content=response.model_dump(mode="json", exclude_none=True),
+    )
+
+
+def register_error_handlers(app):
+    """Register exception handlers with FastAPI app."""
+    app.add_exception_handler(SmartifyAPIError, smartify_error_handler)
+    # Don't override all exceptions - let FastAPI handle validation errors etc.