couchbase-agent-memory 1.0.0__py3-none-any.whl

agentmemory/exceptions.py

@@ -0,0 +1,230 @@
+"""
+Custom exceptions for the Couchbase Agent Memory client SDK.
+"""
+
+from typing import Optional, Dict, Any
+
+
+class AgentMemoryError(Exception):
+    """Base exception for Couchbase Agent Memory SDK errors."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        self.message = message
+        self.status_code = status_code
+        self.details = details or {}
+        super().__init__(self.message)
+
+    def __str__(self) -> str:
+        if self.status_code:
+            return f"[{self.status_code}] {self.message}"
+        return self.message
+
+
+class AuthenticationError(AgentMemoryError):
+    """Raised when authentication or authorization fails.
+
+    HTTP 401 Unauthorized - Authentication failures:
+    - Token is missing when server requires authentication
+    - Token is expired
+    - Token is invalid or malformed
+    - ID token used instead of access token
+    - Token claims (iss, aud) don't match server configuration
+    - Token validation failed
+
+    HTTP 403 Forbidden - Authorization failures:
+    - User lacks required role/permissions
+    - Insufficient permissions for the requested operation
+    """
+
+    def __init__(
+        self,
+        message: str = "Authentication failed",
+        status_code: int = 401,
+    ):
+        super().__init__(message, status_code=status_code)
+
+
+class NotFoundError(AgentMemoryError):
+    """Raised when a requested resource is not found."""
+
+    def __init__(
+        self,
+        message: str = "Resource not found",
+        resource_type: Optional[str] = None,
+        resource_id: Optional[str] = None,
+    ):
+        details = {}
+        if resource_type:
+            details["resource_type"] = resource_type
+        if resource_id:
+            details["resource_id"] = resource_id
+        super().__init__(message, status_code=404, details=details)
+
+
+class ValidationError(AgentMemoryError):
+    """Raised when request validation fails."""
+
+    def __init__(self, message: str, details: Optional[Dict[str, Any]] = None):
+        super().__init__(message, status_code=400, details=details)
+
+
+class ConflictError(AgentMemoryError):
+    """Raised when a resource already exists."""
+
+    def __init__(
+        self,
+        message: str = "Resource already exists",
+        resource_type: Optional[str] = None,
+        resource_id: Optional[str] = None,
+    ):
+        details = {}
+        if resource_type:
+            details["resource_type"] = resource_type
+        if resource_id:
+            details["resource_id"] = resource_id
+        super().__init__(message, status_code=409, details=details)
+
+
+class RateLimitError(AgentMemoryError):
+    """Raised when rate limit is exceeded."""
+
+    def __init__(
+        self,
+        message: str = "Rate limit exceeded",
+        retry_after: Optional[float] = None,
+    ):
+        details = {}
+        if retry_after:
+            details["retry_after_seconds"] = retry_after
+        self.retry_after = retry_after
+        super().__init__(message, status_code=429, details=details)
+
+
+class ServiceUnavailableError(AgentMemoryError):
+    """Raised when a required service is unavailable."""
+
+    def __init__(
+        self,
+        message: str = "Service unavailable",
+        service: Optional[str] = None,
+        retry_after: Optional[float] = None,
+    ):
+        details = {}
+        if service:
+            details["service"] = service
+        if retry_after:
+            details["retry_after_seconds"] = retry_after
+        self.service = service
+        self.retry_after = retry_after
+        super().__init__(message, status_code=503, details=details)
+
+
+class UpstreamError(AgentMemoryError):
+    """Raised when an upstream service (embedding, LLM) fails."""
+
+    def __init__(
+        self,
+        message: str,
+        service: Optional[str] = None,
+        retry_after: Optional[float] = None,
+    ):
+        details = {}
+        if service:
+            details["service"] = service
+        if retry_after:
+            details["retry_after_seconds"] = retry_after
+        self.service = service
+        self.retry_after = retry_after
+        super().__init__(message, status_code=502, details=details)
+
+
+class ServerError(AgentMemoryError):
+    """Raised when the server returns an unexpected error."""
+
+    def __init__(
+        self,
+        message: str = "Internal server error",
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(message, status_code=500, details=details)
+
+
+class ConnectionError(AgentMemoryError):
+    """Raised when unable to connect to the Couchbase Agent Memory server."""
+
+    def __init__(
+        self, message: str = "Failed to connect to Couchbase Agent Memory server"
+    ):
+        super().__init__(message)
+
+
+class TimeoutError(AgentMemoryError):
+    """Raised when a request times out.
+
+    Attributes:
+        server_status: Status of the server after timeout. One of:
+            - "unknown": Health check was not performed or failed
+            - "healthy": Server is up but request took too long (server busy/slow)
+            - "unreachable": Server is down or unreachable
+        is_server_healthy: True if server responded to health check after timeout
+    """
+
+    def __init__(
+        self,
+        message: str = "Request timed out",
+        server_status: str = "unknown",
+        is_server_healthy: Optional[bool] = None,
+    ):
+        self.server_status = server_status
+        self.is_server_healthy = is_server_healthy
+
+        # Build informative message
+        if server_status == "healthy":
+            full_message = (
+                f"{message} (server is still running - request was slow to process)"
+            )
+        elif server_status == "unreachable":
+            full_message = f"{message} (server appears to be down or unreachable)"
+        else:
+            full_message = message
+
+        super().__init__(
+            full_message,
+            status_code=408,
+            details={
+                "server_status": server_status,
+                "is_server_healthy": is_server_healthy,
+            },
+        )
+
+
+class ServerDownError(TimeoutError):
+    """Raised when a timeout occurs and the server is confirmed to be down.
+
+    This exception is raised when:
+    1. A request times out (ReadTimeout)
+    2. A subsequent health check also fails
+    """
+
+    def __init__(self, message: str = "Server is down or unreachable"):
+        super().__init__(message, server_status="unreachable", is_server_healthy=False)
+
+
+class ReadTimeoutError(TimeoutError):
+    """Raised when a read timeout occurs but the server is confirmed to be healthy.
+
+    This exception is raised when:
+    1. A request times out while reading the response (ReadTimeout)
+    2. A subsequent health check succeeds, confirming the server is still running
+    """
+
+    def __init__(
+        self,
+        message: str = "Request timed out while reading response, but server is healthy",
+    ):
+        super().__init__(message, server_status="healthy", is_server_healthy=True)