agentscope-runtime 1.0.0b2__py3-none-any.whl → 1.0.2__py3-none-any.whl

agentscope_runtime/engine/schemas/exception.py

@@ -0,0 +1,580 @@
+# -*- 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,
+        )

agentscope_runtime/engine/services/agent_state/__init__.py

@@ -5,6 +5,7 @@ from ....common.utils.lazy_loader import install_lazy_loader
 if TYPE_CHECKING:
     from .state_service import StateService, InMemoryStateService
     from .redis_state_service import RedisStateService
+    from .state_service_factory import StateServiceFactory
 
 install_lazy_loader(
     globals(),
@@ -12,5 +13,6 @@ install_lazy_loader(
         "StateService": ".state_service",
         "InMemoryStateService": ".state_service",
         "RedisStateService": ".redis_state_service",
+        "StateServiceFactory": ".state_service_factory",
     },
 )

agentscope_runtime/engine/services/agent_state/state_service_factory.py

@@ -0,0 +1,55 @@
+# -*- coding: utf-8 -*-
+
+from typing import Callable, Dict
+
+from ..service_factory import ServiceFactory
+from .state_service import StateService, InMemoryStateService
+from .redis_state_service import RedisStateService
+
+
+class StateServiceFactory(ServiceFactory[StateService]):
+    """
+    Factory for StateService, supports both environment variables and kwargs
+    parameters.
+
+    Usage examples:
+        1. Start with environment variables only:
+            export STATE_BACKEND=redis
+            export STATE_REDIS_REDIS_URL="redis://localhost:6379/5"
+            service = await StateServiceFactory.create()
+
+        2. Override environment variables with arguments:
+            export STATE_BACKEND=redis
+            export STATE_REDIS_REDIS_URL="redis://localhost:6379/5"
+            service = await StateServiceFactory.create(
+                redis_url="redis://otherhost:6379/1"
+            )
+
+        3. User-defined backend:
+            from my_backend import PostgresStateService
+            StateServiceFactory.register_backend(
+                "postgres",
+                PostgresStateService,
+            )
+            export STATE_BACKEND=postgres
+            export STATE_POSTGRES_DSN="postgresql://user:pass@localhost/db"
+            service = await StateServiceFactory.create()
+    """
+
+    _registry: Dict[str, Callable[..., StateService]] = {}
+    _env_prefix = "STATE_"
+    _default_backend = "in_memory"
+
+
+StateServiceFactory.register_backend(
+    "in_memory",
+    lambda **kwargs: InMemoryStateService(),
+)
+
+StateServiceFactory.register_backend(
+    "redis",
+    lambda **kwargs: RedisStateService(
+        redis_url=kwargs.get("redis_url", "redis://localhost:6379/0"),
+        redis_client=kwargs.get("redis_client"),
+    ),
+)

agentscope_runtime/engine/services/memory/__init__.py

@@ -9,6 +9,7 @@ if TYPE_CHECKING:
     from .reme_personal_memory_service import ReMePersonalMemoryService
     from .mem0_memory_service import Mem0MemoryService
     from .tablestore_memory_service import TablestoreMemoryService
+    from .memory_service_factory import MemoryServiceFactory
 
 install_lazy_loader(
     globals(),
@@ -20,5 +21,6 @@ install_lazy_loader(
         "ReMePersonalMemoryService": ".reme_personal_memory_service",
         "Mem0MemoryService": ".mem0_memory_service",
         "TablestoreMemoryService": ".tablestore_memory_service",
+        "MemoryServiceFactory": ".memory_service_factory",
     },
 )