agentscope-runtime 1.0.1__py3-none-any.whl → 1.0.3__py3-none-any.whl

agentscope_runtime/engine/schemas/exception.py

@@ -0,0 +1,604 @@
+# -*- coding: utf-8 -*-
+"""
+Business System Exception Definitions
+Provides a three-level exception structure:
+Base Class -> HTTP Status Exceptions -> Business Exceptions
+"""
+
+from typing import Any, Dict, Optional
+
+
+class AppBaseException(Exception):
+    """
+    Business exception base class
+
+    Attributes:
+        status: HTTP status code, aligned with standard HTTP status codes
+        code: Business error code, used for business logic distinction
+        message: Error message
+        details: Additional error details
+    """
+
+    def __init__(
+        self,
+        status: int,
+        code: str,
+        message: str,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        """
+        Initialize the exception
+
+        Args:
+            status: HTTP status code
+            code: Business error code
+            message: Error message
+            details: Additional details
+        """
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+        self.details = details or {}
+
+    def __str__(self) -> str:
+        """String representation"""
+        return f"[{self.status}] {self.code}: {self.message}"
+
+    def __repr__(self) -> str:
+        """Detailed representation"""
+        return (
+            f"{self.__class__.__name__}(status={self.status}, code="
+            f"'{self.code}', message='{self.message}')"
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to a dictionary"""
+        return {
+            "status": self.status,
+            "code": self.code,
+            "message": self.message,
+            "details": self.details,
+        }
+
+
+# ==================== HTTP Status Exceptions ====================
+
+
+class BadRequestException(AppBaseException):
+    """400 Bad Request - Client request error"""
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(400, code, message, details)
+
+
+class UnauthorizedException(AppBaseException):
+    """401 Unauthorized"""
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(401, code, message, details)
+
+
+class ForbiddenException(AppBaseException):
+    """403 Forbidden - Access denied"""
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(403, code, message, details)
+
+
+class NotFoundException(AppBaseException):
+    """404 Not Found - Resource does not exist"""
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(404, code, message, details)
+
+
+class MethodNotAllowedException(AppBaseException):
+    """405 Method Not Allowed"""
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(405, code, message, details)
+
+
+class ConflictException(AppBaseException):
+    """409 Conflict"""
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(409, code, message, details)
+
+
+class UnprocessableEntityException(AppBaseException):
+    """422 Unprocessable Entity"""
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(422, code, message, details)
+
+
+class TooManyRequestsException(AppBaseException):
+    """429 Too Many Requests"""
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(429, code, message, details)
+
+
+class InternalServerErrorException(AppBaseException):
+    """500 Internal Server Error"""
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(500, code, message, details)
+
+
+class BadGatewayException(AppBaseException):
+    """502 Bad Gateway"""
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(502, code, message, details)
+
+
+class ServiceUnavailableException(AppBaseException):
+    """503 Service Unavailable"""
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(503, code, message, details)
+
+
+class GatewayTimeoutException(AppBaseException):
+    """504 Gateway Timeout"""
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(504, code, message, details)
+
+
+# ==================== Business Exceptions ====================
+
+
+# Authentication-related exceptions
+class AuthenticationException(UnauthorizedException):
+    """Authentication failed"""
+
+    def __init__(
+        self,
+        message: str = "Authentication failed",
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__("AUTH_FAILED", message, details)
+
+
+class TokenExpiredException(UnauthorizedException):
+    """Token expired"""
+
+    def __init__(
+        self,
+        message: str = "Token has expired",
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__("TOKEN_EXPIRED", message, details)
+
+
+class InvalidTokenException(UnauthorizedException):
+    """Invalid token"""
+
+    def __init__(
+        self,
+        message: str = "Invalid token",
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__("INVALID_TOKEN", message, details)
+
+
+# Permission-related exceptions
+class PermissionDeniedException(ForbiddenException):
+    """Permission denied"""
+
+    def __init__(
+        self,
+        message: str = "Permission denied",
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__("PERMISSION_DENIED", message, details)
+
+
+class AccessDeniedException(ForbiddenException):
+    """Access denied"""
+
+    def __init__(
+        self,
+        message: str = "Access denied",
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__("ACCESS_DENIED", message, details)
+
+
+# Resource-related exceptions
+class ResourceNotFoundException(NotFoundException):
+    """Resource not found"""
+
+    def __init__(
+        self,
+        resource_type: str,
+        resource_id: str,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        message = f"{resource_type} not found: {resource_id}"
+        super().__init__("RESOURCE_NOT_FOUND", message, details)
+
+
+class UserNotFoundException(NotFoundException):
+    """User not found"""
+
+    def __init__(self, user_id: str, details: Optional[Dict[str, Any]] = None):
+        message = f"User not found: {user_id}"
+        super().__init__("USER_NOT_FOUND", message, details)
+
+
+class TaskNotFoundException(NotFoundException):
+    """Task not found"""
+
+    def __init__(self, task_id: str, details: Optional[Dict[str, Any]] = None):
+        message = f"Task not found: {task_id}"
+        super().__init__("TASK_NOT_FOUND", message, details)
+
+
+# Parameter-related exceptions
+class InvalidParameterException(BadRequestException):
+    """Invalid parameter"""
+
+    def __init__(
+        self,
+        parameter: str,
+        message: str = None,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        if message is None:
+            message = f"Invalid parameter: {parameter}"
+        super().__init__("INVALID_PARAMETER", message, details)
+
+
+class MissingParameterException(BadRequestException):
+    """Missing parameter"""
+
+    def __init__(
+        self,
+        parameter: str,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        message = f"Missing required parameter: {parameter}"
+        super().__init__("MISSING_PARAMETER", message, details)
+
+
+class ParameterValidationException(BadRequestException):
+    """Parameter validation error"""
+
+    def __init__(
+        self,
+        parameter: str,
+        validation_error: str,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        message = (
+            f"Parameter validation failed: {parameter} - {validation_error}"
+        )
+        super().__init__("PARAMETER_VALIDATION", message, details)
+
+
+# Rate limit-related exceptions
+class RateLimitExceededException(TooManyRequestsException):
+    """Rate limit exceeded"""
+
+    def __init__(
+        self,
+        operation: str,
+        retry_after: int = 60,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        message = (
+            f"Operation {operation} is too frequent, please retry "
+            f"after {retry_after} seconds"
+        )
+        super().__init__("RATE_LIMIT_EXCEEDED", message, details)
+
+
+# Business logic exceptions
+class BusinessLogicException(UnprocessableEntityException):
+    """Business logic exception"""
+
+
+class WorkflowException(BusinessLogicException):
+    """Workflow error"""
+
+    def __init__(self, message: str, details: Optional[Dict[str, Any]] = None):
+        super().__init__("WORKFLOW_ERROR", message, details)
+
+
+class AgentException(BusinessLogicException):
+    """Agent error"""
+
+    def __init__(self, message: str, details: Optional[Dict[str, Any]] = None):
+        super().__init__("AGENT_ERROR", message, details)
+
+
+class ResponseException(BusinessLogicException):
+    """Response error"""
+
+    def __init__(self, message: str, details: Optional[Dict[str, Any]] = None):
+        super().__init__("RESPONSE_ERROR", message, details)
+
+
+# System-related exceptions
+class SystemException(InternalServerErrorException):
+    """System exception"""
+
+
+class DatabaseException(SystemException):
+    """Database error"""
+
+    def __init__(self, message: str, details: Optional[Dict[str, Any]] = None):
+        super().__init__("DATABASE_ERROR", message, details)
+
+
+class RedisException(SystemException):
+    """Redis error"""
+
+    def __init__(self, message: str, details: Optional[Dict[str, Any]] = None):
+        super().__init__("REDIS_ERROR", message, details)
+
+
+class ExternalServiceException(SystemException):
+    """External service error"""
+
+    def __init__(
+        self,
+        service_name: str,
+        message: str,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        full_message = f"External service {service_name} error: {message}"
+        super().__init__("EXTERNAL_SERVICE_ERROR", full_message, details)
+
+
+# Configuration-related exceptions
+class ConfigurationException(InternalServerErrorException):
+    """Configuration error"""
+
+    def __init__(
+        self,
+        config_key: str,
+        message: str = None,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        if message is None:
+            message = f"Configuration error: {config_key}"
+        super().__init__("CONFIGURATION_ERROR", message, details)
+
+
+# Network-related exceptions
+class NetworkException(ServiceUnavailableException):
+    """Network error"""
+
+    def __init__(self, message: str, details: Optional[Dict[str, Any]] = None):
+        super().__init__("NETWORK_ERROR", message, details)
+
+
+class TimeoutException(GatewayTimeoutException):
+    """Timeout error"""
+
+    def __init__(
+        self,
+        operation: str,
+        timeout: int,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        message = (
+            f"Operation {operation} timed out, timeout limit:"
+            f" {timeout} seconds"
+        )
+        super().__init__("TIMEOUT", message, details)
+
+
+# ==================== Agent runtime related Exceptions ====================
+class AgentRuntimeErrorException(BusinessLogicException):
+    """
+    Base class for agent runtime error exceptions (HTTP 422 - Unprocessable
+    Entity)
+    """
+
+
+class ToolExecutionException(AgentRuntimeErrorException):
+    """Error occurred during tool execution"""
+
+    def __init__(self, details: Optional[Dict[str, Any]] = None):
+        super().__init__(
+            "TOOL_EXECUTION_FAILED",
+            "Error occurred during tool execution",
+            details,
+        )
+
+
+class ToolNotFoundException(AgentRuntimeErrorException):
+    """Specified tool not found"""
+
+    def __init__(
+        self,
+        tool_name: str,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        message = f"Tool not found: {tool_name}"
+        super().__init__("TOOL_NOT_FOUND", message, details)
+
+
+class MCPConnectionException(AgentRuntimeErrorException):
+    """Failed to connect to MCP service"""
+
+    def __init__(self, details: Optional[Dict[str, Any]] = None):
+        super().__init__(
+            "MCP_CONNECTION_FAILED",
+            "Failed to connect to MCP service",
+            details,
+        )
+
+
+class MCPProtocolException(AgentRuntimeErrorException):
+    """Invalid MCP protocol message format"""
+
+    def __init__(self, details: Optional[Dict[str, Any]] = None):
+        super().__init__(
+            "MCP_PROTOCOL_ERROR",
+            "Invalid MCP protocol message format",
+            details,
+        )
+
+
+class ModelExecutionException(AgentRuntimeErrorException):
+    """Error occurred during model execution"""
+
+    def __init__(
+        self,
+        model_name: str,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        message = f"Error occurred during execution of model: {model_name}"
+        super().__init__("MODEL_EXECUTION_FAILED", message, details)
+
+
+class ModelTimeoutException(AgentRuntimeErrorException):
+    """Model inference timed out"""
+
+    def __init__(
+        self,
+        model_name: str,
+        timeout: int,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        message = (
+            f"Model inference timed out: {model_name}, timeout limit:"
+            f" {timeout} seconds"
+        )
+        super().__init__("MODEL_TIMEOUT", message, details)
+
+
+class ModelNotFoundException(AgentRuntimeErrorException):
+    """Specified model not found"""
+
+    def __init__(
+        self,
+        model_name: str,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        message = f"Model not found: {model_name}"
+        super().__init__("MODEL_NOT_FOUND", message, details)
+
+
+class UnauthorizedModelAccessException(AgentRuntimeErrorException):
+    """Unauthorized access to model"""
+
+    def __init__(
+        self,
+        model_name: str,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        message = f"Unauthorized access to model: {model_name}"
+        super().__init__("MODEL_UNAUTHORIZED_ACCESS", message, details)
+
+
+class UnknownAgentException(AgentRuntimeErrorException):
+    """Generic agent error with no specific classification"""
+
+    def __init__(
+        self,
+        original_exception: Optional[Exception] = None,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        message = "Unknown agent error" + (
+            f": {type(original_exception).__name__}: {str(original_exception)}"
+            if original_exception is not None
+            else ""
+        )
+        super().__init__(
+            "AGENT_UNKNOWN_ERROR",
+            message,
+            details,
+        )
+
+
+class ModelQuotaExceededException(AgentRuntimeErrorException):
+    """Model quota exceeded"""
+
+    def __init__(
+        self,
+        model_name: str,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        message = f"Model quota exceeded: {model_name}"
+        super().__init__("MODEL_QUOTA_EXCEEDED", message, details)
+
+
+class ModelContextLengthExceededException(AgentRuntimeErrorException):
+    """Model context length exceeded"""
+
+    def __init__(
+        self,
+        model_name: str,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        message = f"Model context length exceeded: {model_name}"
+        super().__init__("MODEL_CONTEXT_LENGTH_EXCEEDED", message, details)

agentscope_runtime/engine/services/agent_state/redis_state_service.py

@@ -21,29 +21,68 @@ class RedisStateService(StateService):
         self,
         redis_url: str = "redis://localhost:6379/0",
         redis_client: Optional[aioredis.Redis] = None,
+        socket_timeout: Optional[float] = 5.0,
+        socket_connect_timeout: Optional[float] = 5.0,
+        max_connections: Optional[int] = 50,
+        retry_on_timeout: bool = True,
+        ttl_seconds: Optional[int] = 3600,  # 1 hour in seconds
+        health_check_interval: Optional[float] = 30.0,
+        socket_keepalive: bool = True,
     ):
+        """
+        Initialize RedisStateService.
+
+        Args:
+            redis_url: Redis connection URL
+            redis_client: Optional pre-configured Redis client
+            socket_timeout: Socket timeout in seconds (default: 5.0)
+            socket_connect_timeout: Socket connect timeout in seconds
+            (default: 5.0)
+            max_connections: Maximum number of connections in the pool
+            (default: 50)
+            retry_on_timeout: Whether to retry on timeout (default: True)
+            ttl_seconds: Time-to-live in seconds for state data. If None,
+            data never expires (default: 3600, i.e., 1 hour)
+            health_check_interval: Interval in seconds for health checks on
+            idle connections (default: 30.0).
+                Connections idle longer than this will be checked before reuse.
+                Set to 0 to disable.
+            socket_keepalive: Enable TCP keepalive to prevent
+            silent disconnections (default: True)
+        """
         self._redis_url = redis_url
         self._redis = redis_client
-        self._health = False
+        self._socket_timeout = socket_timeout
+        self._socket_connect_timeout = socket_connect_timeout
+        self._max_connections = max_connections
+        self._retry_on_timeout = retry_on_timeout
+        self._ttl_seconds = ttl_seconds
+        self._health_check_interval = health_check_interval
+        self._socket_keepalive = socket_keepalive
 
     async def start(self) -> None:
-        """Initialize the Redis connection."""
+        """Starts the Redis connection with proper timeout and connection
+        pool settings."""
         if self._redis is None:
             self._redis = aioredis.from_url(
                 self._redis_url,
                 decode_responses=True,
+                socket_timeout=self._socket_timeout,
+                socket_connect_timeout=self._socket_connect_timeout,
+                max_connections=self._max_connections,
+                retry_on_timeout=self._retry_on_timeout,
+                health_check_interval=self._health_check_interval,
+                socket_keepalive=self._socket_keepalive,
             )
-        self._health = True
 
     async def stop(self) -> None:
-        """Close the Redis connection."""
+        """Closes the Redis connection."""
         if self._redis:
-            await self._redis.close()
+            await self._redis.aclose()
             self._redis = None
-        self._health = False
 
     async def health(self) -> bool:
-        """Service health check."""
+        """Checks the health of the service."""
         if not self._redis:
             return False
         try:
@@ -81,6 +120,11 @@ class RedisStateService(StateService):
                 round_id = 1
 
         await self._redis.hset(key, round_id, json.dumps(state))
+
+        # Set TTL for the state key if configured
+        if self._ttl_seconds is not None:
+            await self._redis.expire(key, self._ttl_seconds)
+
         return round_id
 
     async def export_state(
@@ -110,4 +154,13 @@ class RedisStateService(StateService):
 
         if state_json is None:
             return None
-        return json.loads(state_json)
+
+        # Refresh TTL when accessing the state
+        if self._ttl_seconds is not None:
+            await self._redis.expire(key, self._ttl_seconds)
+
+        try:
+            return json.loads(state_json)
+        except json.JSONDecodeError:
+            # Return None for corrupted state data instead of raising exception
+            return None