recallrai 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

recallrai/__init__.py

@@ -1,6 +1,3 @@
-# Path: recallrai/__init__.py
-# Description: Package initialization file with SDK version and main class exports
-
 """
 RecallrAI Python SDK
 
@@ -11,7 +8,8 @@ from .client import RecallrAI
 from .user import User
 from .session import Session
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
+
 __all__ = [
     "RecallrAI",
     "User",

recallrai/client.py

@@ -1,19 +1,18 @@
-# Path: recallrai/client.py
-# Description: Main client class for the RecallrAI SDK
-
 """
 Main client class for the RecallrAI SDK.
 
 This module provides the RecallrAI class, which is the primary interface for the SDK.
 """
 
-import uuid
 from typing import Any, Dict, Optional
-from pydantic import HttpUrl
-from .utils import HTTPClient, RecallrAIError
-from .models import User as UserModel, UserList, SessionStatus, SessionList
+from .models import UserModel, UserList
 from .user import User
-from .session import Session
+from .utils import HTTPClient
+from .exceptions import (
+    UserAlreadyExistsError,
+    UserNotFoundError,
+    RecallrAIError,
+)
 from logging import getLogger
 
 logger = getLogger(__name__)
@@ -28,8 +27,8 @@ class RecallrAI:
     def __init__(
         self,
         api_key: str,
-        project_id: uuid.UUID,
-        base_url: HttpUrl = "https://api.recallrai.com",
+        project_id: str,
+        base_url: str = "https://api.recallrai.com",
         timeout: int = 30,
     ):
         """
@@ -45,8 +44,8 @@ class RecallrAI:
             raise ValueError("API key must start with 'rai_'")
         
         self.api_key = api_key
-        self.project_id = str(project_id)
-        self.base_url = str(base_url)
+        self.project_id = project_id
+        self.base_url = base_url
         
         self.http = HTTPClient(
             api_key=self.api_key,
@@ -68,11 +67,19 @@ class RecallrAI:
             The created user object
 
         Raises:
-            ValidationError: If the user_id is invalid
-            BadRequestError: If a user with the same ID already exists
+            UserAlreadyExistsError: If a user with the same ID already exists
+            AuthenticationError: If the API key or project ID is invalid
+            InternalServerError: If the server encounters an error
+            NetworkError: If there are network issues
+            TimeoutError: If the request times out
+            RecallrAIError: For other API-related errors
         """
         response = self.http.post("/api/v1/users", data={"user_id": user_id, "metadata": metadata or {}})
-        user_data = UserModel.from_api_response(response)
+        if response.status_code == 409:
+            raise UserAlreadyExistsError(user_id=user_id)
+        elif response.status_code != 201:
+            raise RecallrAIError("Failed to create user", http_status=response.status_code)
+        user_data = UserModel.from_api_response(response.json())
         return User(self.http, user_data)
 
     def get_user(self, user_id: str) -> User:
@@ -86,10 +93,19 @@ class RecallrAI:
             A User object representing the user
 
         Raises:
-            NotFoundError: If the user is not found
+            UserNotFoundError: If the user is not found
+            AuthenticationError: If the API key or project ID is invalid
+            InternalServerError: If the server encounters an error
+            NetworkError: If there are network issues
+            TimeoutError: If the request times out
+            RecallrAIError: For other API-related errors
         """
         response = self.http.get(f"/api/v1/users/{user_id}")
-        user_data = UserModel.from_api_response(response)
+        if response.status_code == 404:
+            raise UserNotFoundError(user_id=user_id)
+        elif response.status_code != 200:
+            raise RecallrAIError("Failed to retrieve user", http_status=response.status_code)
+        user_data = UserModel.from_api_response(response.json())
         return User(self.http, user_data)
 
     def list_users(self, offset: int = 0, limit: int = 10) -> UserList:
@@ -102,119 +118,15 @@ class RecallrAI:
 
         Returns:
             List of users with pagination info
-        """
-        response = self.http.get("/api/v1/users", params={"offset": offset, "limit": limit})
-        return UserList.from_api_response(response)
-
-    def update_user(
-        self, 
-        user_id: str, 
-        new_metadata: Optional[Dict[str, Any]] = None, 
-        new_user_id: Optional[str] = None
-    ) -> User:
-        """
-        Update a user's metadata or ID.
-
-        Args:
-            user_id: Current ID of the user
-            new_metadata: New metadata to associate with the user
-            new_user_id: New ID for the user
-
-        Returns:
-            The updated user
-
-        Raises:
-            NotFoundError: If the user is not found
-            ValidationError: If the new_user_id is invalid
-            BadRequestError: If a user with the new_user_id already exists
-        """
-        data = {}
-        if new_metadata is not None:
-            data["new_metadata"] = new_metadata
-        if new_user_id is not None:
-            data["new_user_id"] = new_user_id
-            
-        response = self.http.put(f"/api/v1/users/{user_id}", data=data)
-        user_data = UserModel.from_api_response(response)
-        return User(self.http, user_data)
-
-    def delete_user(self, user_id: str) -> None:
-        """
-        Delete a user.
-
-        Args:
-            user_id: ID of the user to delete
-
-        Raises:
-            NotFoundError: If the user is not found
-        """
-        self.http.delete(f"/api/v1/users/{user_id}")
-
-    # Session management
-    def create_session(self, user_id: str, auto_process_after_minutes: int = -1) -> Session:
-        """
-        Create a new session for a user.
-
-        Args:
-            user_id: ID of the user to create the session for
-            auto_process_after_minutes: Minutes to wait before auto-processing (-1 to disable)
-
-        Returns:
-            A Session object to interact with the created session
-
-        Raises:
-            NotFoundError: If the user is not found
-            ValidationError: If auto_process_after_minutes is invalid
-        """
-        response = self.http.post(
-            f"/api/v1/users/{user_id}/sessions",
-            data={"auto_process_after_minutes": auto_process_after_minutes},
-        )
         
-        session_id = response["session_id"]
-        return Session(self.http, user_id, session_id)
-
-    def get_session(self, user_id: str, session_id: str) -> Session:
-        """
-        Get an existing session.
-
-        Args:
-            user_id: ID of the user who owns the session
-            session_id: ID of the session to retrieve
-
-        Returns:
-            A Session object to interact with the session
-
         Raises:
-            NotFoundError: If the user or session is not found
+            AuthenticationError: If the API key or project ID is invalid
+            InternalServerError: If the server encounters an error
+            NetworkError: If there are network issues
+            TimeoutError: If the request times out
+            RecallrAIError: For other API-related errors
         """
-        # Ensure the session exists by checking its status
-        session = Session(self.http, user_id, session_id)
-        status = session.get_status()
-        if status == SessionStatus.PROCESSING:
-            raise RecallrAIError("Session is already processing. You can't add messages to it. Create a new session instead.")
-        elif status == SessionStatus.PROCESSED:
-            raise RecallrAIError("Session has already been processed. You can't add messages to it. Create a new session instead.")
-        
-        return session
-
-    def list_sessions(self, user_id: str, offset: int = 0, limit: int = 10) -> SessionList:
-        """
-        List sessions for a user with pagination.
-
-        Args:
-            user_id: ID of the user
-            offset: Number of records to skip
-            limit: Maximum number of records to return
-
-        Returns:
-            List of sessions with pagination info
-
-        Raises:
-            NotFoundError: If the user is not found
-        """
-        response = self.http.get(
-            f"/api/v1/users/{user_id}/sessions",
-            params={"offset": offset, "limit": limit},
-        )
-        return SessionList.from_api_response(response)
+        response = self.http.get("/api/v1/users", params={"offset": offset, "limit": limit})
+        if response.status_code != 200:
+            raise RecallrAIError("Failed to list users", http_status=response.status_code)
+        return UserList.from_api_response(response.json())

recallrai/exceptions/__init__.py

@@ -0,0 +1,28 @@
+"""
+Exceptions for the RecallrAI SDK.
+"""
+
+from .auth import AuthenticationError
+from .base import RecallrAIError
+from .network import NetworkError, TimeoutError, ConnectionError
+from .server import ServerError, InternalServerError
+from .sessions import SessionError, SessionNotFoundError, InvalidSessionStateError
+from .users import UserError, UserNotFoundError, UserAlreadyExistsError
+from .validation import ValidationError
+
+__all__ = [
+    "RecallrAIError",
+    "AuthenticationError",
+    "NetworkError", 
+    "TimeoutError", 
+    "ConnectionError",
+    "ServerError", 
+    "InternalServerError",
+    "SessionError", 
+    "SessionNotFoundError", 
+    "InvalidSessionStateError",
+    "UserError", 
+    "UserNotFoundError", 
+    "UserAlreadyExistsError",
+    "ValidationError",
+]

recallrai/exceptions/auth.py

@@ -0,0 +1,24 @@
+"""
+Authentication-related exceptions for the RecallrAI SDK.
+"""
+
+from typing import Any, Dict, Optional
+from .base import RecallrAIError
+
+
+class AuthenticationError(RecallrAIError):
+    """
+    Raised when there is an authentication issue with the API key.
+    
+    This exception is typically raised when the API key is invalid,
+    has been revoked, or doesn't have the necessary permissions.
+    """
+
+    def __init__(
+        self, 
+        message: str = "Invalid API key or authentication failed", 
+        code: str = "authentication_error",
+        http_status: int = 401,
+        details: Optional[Dict[str, Any]] = None
+    ):
+        super().__init__(message, code, http_status, details)

recallrai/exceptions/base.py

@@ -0,0 +1,35 @@
+"""
+Base exception classes for the RecallrAI SDK.
+"""
+
+from typing import Any, Dict, Optional
+
+
+class RecallrAIError(Exception):
+    """Base exception for all RecallrAI SDK errors."""
+
+    def __init__(
+        self, 
+        message: str, 
+        code: Optional[str] = None, 
+        http_status: Optional[int] = None,
+        details: Optional[Dict[str, Any]] = None
+    ):
+        """
+        Initialize a RecallrAI error.
+
+        Args:
+            message: A human-readable error message
+            code: An optional error code
+            http_status: The HTTP status code that triggered this error
+            details: Optional additional details about the error
+        """
+        self.message = message
+        self.code = code
+        self.http_status = http_status
+        self.details = details or {}
+        super().__init__(self.message)
+    
+    def __str__(self) -> str:
+        """Return a string representation of the error."""
+        return f"{self.message}. HTTP Status: {self.http_status}."

recallrai/exceptions/network.py

@@ -0,0 +1,58 @@
+"""
+Network-related exceptions for the RecallrAI SDK.
+"""
+
+from typing import Any, Dict, Optional
+from .base import RecallrAIError
+
+
+class NetworkError(RecallrAIError):
+    """
+    Base class for network-related exceptions.
+    
+    This exception is raised for errors related to network connectivity
+    and communication with the RecallrAI API.
+    """
+
+    def __init__(
+        self, 
+        message: str = "Network error occurred", 
+        code: str = "network_error",
+        http_status: Optional[int] = None,
+        details: Optional[Dict[str, Any]] = None
+    ):
+        super().__init__(message, code, http_status, details)
+
+
+class TimeoutError(NetworkError):
+    """
+    Raised when a request times out.
+    
+    This exception is raised when a request to the RecallrAI API
+    takes longer than the configured timeout.
+    """
+
+    def __init__(
+        self, 
+        message: str = "Request timed out", 
+        code: str = "timeout",
+        details: Optional[Dict[str, Any]] = None
+    ):
+        super().__init__(message, code, None, details)
+
+
+class ConnectionError(NetworkError):
+    """
+    Raised when a connection error occurs.
+    
+    This exception is raised when there's an issue connecting to
+    the RecallrAI API, such as DNS resolution issues or network unavailability.
+    """
+
+    def __init__(
+        self, 
+        message: str = "Failed to connect to the RecallrAI API", 
+        code: str = "connection_error",
+        details: Optional[Dict[str, Any]] = None
+    ):
+        super().__init__(message, code, None, details)

recallrai/exceptions/server.py

@@ -0,0 +1,82 @@
+"""
+Server-related exceptions for the RecallrAI SDK.
+"""
+
+from typing import Any, Dict, Optional
+from .base import RecallrAIError
+
+
+class ServerError(RecallrAIError):
+    """
+    Base class for server-related exceptions.
+    """
+    def __init__(
+        self, 
+        message: str = "Server error occurred", 
+        code: str = "server_error",
+        http_status: int = 500,
+        details: Optional[Dict[str, Any]] = None
+    ):
+        super().__init__(message, code, http_status, details)
+
+class InternalServerError(ServerError):
+    """
+    Raised when the RecallrAI API encounters an internal server error.
+    
+    This exception is typically raised when the API returns a 5xx error code.
+    """
+
+    def __init__(
+        self, 
+        message: str = "Internal server error", 
+        code: str = "server_error",
+        http_status: int = 500,
+        details: Optional[Dict[str, Any]] = None
+    ):
+        super().__init__(message, code, http_status, details)
+
+
+# class RateLimitError(ServerError):
+#     """
+#     Raised when the API rate limit has been exceeded.
+#
+#     This exception is raised when too many requests are made in a
+#     short period of time.
+#     """
+
+#     def __init__(
+#         self, 
+#         message: str = "API rate limit exceeded", 
+#         code: str = "rate_limit_exceeded",
+#         http_status: int = 429,
+#         retry_after: Optional[int] = None,
+#         details: Optional[Dict[str, Any]] = None
+#     ):
+#         details = details or {}
+#         if retry_after:
+#             details["retry_after"] = retry_after
+#         super().__init__(message, code, http_status, details)
+#         self.retry_after = retry_after
+
+
+# class ServiceUnavailableError(ServerError):
+#     """
+#     Raised when the RecallrAI service is temporarily unavailable.
+#
+#     This exception is raised when the API is down for maintenance
+#     or experiencing issues.
+#     """
+
+#     def __init__(
+#         self, 
+#         message: str = "Service temporarily unavailable", 
+#         code: str = "service_unavailable",
+#         http_status: int = 503,
+#         retry_after: Optional[int] = None,
+#         details: Optional[Dict[str, Any]] = None
+#     ):
+#         details = details or {}
+#         if retry_after:
+#             details["retry_after"] = retry_after
+#         super().__init__(message, code, http_status, details)
+#         self.retry_after = retry_after

recallrai/exceptions/sessions.py

@@ -0,0 +1,60 @@
+"""
+Sessions-related exceptions for the RecallrAI SDK.
+"""
+
+from typing import Any, Dict, Optional
+from .base import RecallrAIError
+
+class SessionError(RecallrAIError):
+    """
+    Base class for session-related exceptions.
+    
+    This exception is raised for errors related to session management
+    in the RecallrAI API.
+    """
+
+    def __init__(
+        self, 
+        message: str = "Session error occurred", 
+        code: str = "session_error",
+        http_status: Optional[int] = None,
+        details: Optional[Dict[str, Any]] = None
+    ):
+        super().__init__(message, code, http_status, details)
+
+class InvalidSessionStateError(SessionError):
+    """
+    Raised when a session is in an invalid state.
+    
+    This exception is typically raised when trying to perform an action
+    on a session that is not in the expected state.
+    """
+
+    def __init__(
+        self, 
+        message: str = "Invalid session state", 
+        code: str = "invalid_session_state",
+        http_status: int = 400,
+        details: Optional[Dict[str, Any]] = None
+    ):
+        super().__init__(message, code, http_status, details)
+
+class SessionNotFoundError(SessionError):
+    """
+    Raised when a session is not found.
+    
+    This exception is typically raised when trying to access or modify
+    a session that doesn't exist.
+    """
+
+    def __init__(
+        self, 
+        session_id: Optional[str] = None,
+        message: Optional[str] = None,
+        code: str = "session_not_found",
+        http_status: int = 404,
+        details: Optional[Dict[str, Any]] = None
+    ):
+        message = message or f"Session{f' {session_id}' if session_id else ''} not found"
+        super().__init__(message, code, http_status, details)
+        self.session_id = session_id

recallrai/exceptions/users.py

@@ -0,0 +1,61 @@
+"""
+Users-related exceptions for the RecallrAI SDK.
+"""
+
+from typing import Any, Dict, Optional
+from .base import RecallrAIError
+
+class UserError(RecallrAIError):
+    """
+    Base class for user-related exceptions.
+    
+    This exception is raised for errors related to user management
+    in the RecallrAI API.
+    """
+
+    def __init__(
+        self, 
+        message: str = "User error occurred", 
+        code: str = "user_error",
+        http_status: Optional[int] = None,
+        details: Optional[Dict[str, Any]] = None
+    ):
+        super().__init__(message, code, http_status, details)
+
+class UserNotFoundError(UserError):
+    """
+    Raised when a user is not found.
+    
+    This exception is typically raised when trying to access or modify
+    a user that doesn't exist.
+    """
+    def __init__(
+        self, 
+        user_id: Optional[str] = None,
+        message: Optional[str] = None,
+        code: str = "user_not_found",
+        http_status: int = 404,
+        details: Optional[Dict[str, Any]] = None
+    ):
+        message = message or f"User{f' {user_id}' if user_id else ''} not found"
+        super().__init__(message, code, http_status, details)
+        self.user_id = user_id
+
+class UserAlreadyExistsError(UserError):
+    """
+    Raised when a user already exists.
+    
+    This exception is typically raised when trying to create a user
+    that already exists in the system.
+    """
+    def __init__(
+        self, 
+        user_id: Optional[str] = None,
+        message: Optional[str] = None,
+        code: str = "user_already_exists",
+        http_status: int = 409,
+        details: Optional[Dict[str, Any]] = None
+    ):
+        message = message or f"User{f' {user_id}' if user_id else ''} already exists"
+        super().__init__(message, code, http_status, details)
+        self.user_id = user_id

recallrai/exceptions/validation.py

@@ -0,0 +1,24 @@
+"""
+Validation-related exceptions for the RecallrAI SDK.
+"""
+
+from typing import Any, Dict, Optional, Union
+from .base import RecallrAIError
+
+
+class ValidationError(RecallrAIError):
+    """
+    Raised when request parameters fail validation.
+    
+    This exception is raised when the API rejects a request
+    due to invalid or missing parameters.
+    """
+
+    def __init__(
+        self, 
+        message: str = "Validation error", 
+        code: str = "validation_error",
+        http_status: int = 422,
+        details: Optional[Dict[str, Any]] = None
+    ):
+        super().__init__(message, code, http_status, details)

recallrai/models/__init__.py

@@ -1,13 +1,13 @@
-# Path: recallrai/models/__init__.py
-# Description: Package initialization for data models
-
-from .session import Context, Message, MessageRole, Session, SessionList, SessionStatus
-from .user import User, UserList
+"""
+Models used in the SDK.
+"""
+from .session import Context, Message, MessageRole, SessionModel, SessionList, SessionStatus
+from .user import UserModel, UserList
 
 __all__ = [
-    "User", 
+    "UserModel", 
     "UserList",
-    "Session",
+    "SessionModel",
     "SessionList",
     "SessionStatus",
     "Message",