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

recallrai/__init__.py

@@ -1,5 +1,5 @@
 """
-RecallrAI Python SDK
+RecallrAI Python SDK.
 
 This package provides a Python interface to interact with the RecallrAI API.
 """
@@ -8,7 +8,7 @@ from .client import RecallrAI
 from .user import User
 from .session import Session
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 __all__ = [
     "RecallrAI",

recallrai/client.py

@@ -4,6 +4,7 @@ Main client class for the RecallrAI SDK.
 This module provides the RecallrAI class, which is the primary interface for the SDK.
 """
 
+import json
 from typing import Any, Dict, Optional
 from .models import UserModel, UserList
 from .user import User
@@ -35,98 +36,112 @@ class RecallrAI:
         Initialize the RecallrAI client.
 
         Args:
-            api_key: Your RecallrAI API key
-            project_id: Your project ID
-            base_url: The base URL for the RecallrAI API
-            timeout: Request timeout in seconds
+            api_key: Your RecallrAI API key.
+            project_id: Your project ID.
+            base_url: The base URL for the RecallrAI API.
+            timeout: Request timeout in seconds.
         """
         if not api_key.startswith("rai_"):
             raise ValueError("API key must start with 'rai_'")
         
-        self.api_key = api_key
-        self.project_id = project_id
-        self.base_url = base_url
-        
-        self.http = HTTPClient(
-            api_key=self.api_key,
-            project_id=self.project_id,
-            base_url=self.base_url,
+        self._http = HTTPClient(
+            api_key=api_key,
+            project_id=project_id,
+            base_url=base_url,
             timeout=timeout,
         )
 
     # User management
-    def create_user(self, user_id: str, metadata: Optional[Dict[str, Any]] = None) -> User:
+    def create_user(
+        self, 
+        user_id: str, 
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> User:
         """
         Create a new user.
 
         Args:
-            user_id: Unique identifier for the user
-            metadata: Optional metadata to associate with the user
+            user_id: Unique identifier for the user.
+            metadata: Optional metadata to associate with the user.
 
         Returns:
-            The created user object
+            The created user object.
 
         Raises:
-            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
+            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 {}})
+        response = self._http.post("/api/v1/users", data={"user_id": user_id, "metadata": metadata or {}})
         if response.status_code == 409:
-            raise UserAlreadyExistsError(user_id=user_id)
+            detail = response.json().get("detail", f"User with ID {user_id} already exists")
+            raise UserAlreadyExistsError(message=detail, http_status=response.status_code)
         elif response.status_code != 201:
-            raise RecallrAIError("Failed to create user", http_status=response.status_code)
+            detail = response.json().get("detail", "Failed to create user")
+            raise RecallrAIError(message=detail, http_status=response.status_code)
         user_data = UserModel.from_api_response(response.json())
-        return User(self.http, user_data)
+        return User(self._http, user_data)
 
     def get_user(self, user_id: str) -> User:
         """
         Get a user by ID.
 
         Args:
-            user_id: Unique identifier of the user
+            user_id: Unique identifier of the user.
 
         Returns:
-            A User object representing the user
+            A User object representing the user.
 
         Raises:
-            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
+            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}")
+        response = self._http.get(f"/api/v1/users/{user_id}")
         if response.status_code == 404:
-            raise UserNotFoundError(user_id=user_id)
+            detail = response.json().get("detail", f"User with ID {user_id} not found")
+            raise UserNotFoundError(message=detail, http_status=response.status_code)
         elif response.status_code != 200:
-            raise RecallrAIError("Failed to retrieve user", http_status=response.status_code)
+            detail = response.json().get("detail", "Failed to retrieve user")
+            raise RecallrAIError(message=detail, 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:
+        return User(self._http, user_data)
+
+    def list_users(
+        self, 
+        offset: int = 0, 
+        limit: int = 10, 
+        metadata_filter: Optional[Dict[str, Any]] = None
+    ) -> UserList:
         """
         List users with pagination.
 
         Args:
-            offset: Number of records to skip
-            limit: Maximum number of records to return
+            offset: Number of records to skip.
+            limit: Maximum number of records to return.
 
         Returns:
-            List of users with pagination info
+            List of users with pagination info.
         
         Raises:
-            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
+            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("/api/v1/users", params={"offset": offset, "limit": limit})
+        params: Dict[str, Any] = {"offset": offset, "limit": limit}
+        if metadata_filter is not None:
+            params["metadata_filter"] = json.dumps(metadata_filter)
+
+        response = self._http.get("/api/v1/users", params=params)
         if response.status_code != 200:
-            raise RecallrAIError("Failed to list users", http_status=response.status_code)
-        return UserList.from_api_response(response.json())
+            detail = response.json().get("detail", "Failed to list users")
+            raise RecallrAIError(message=detail, http_status=response.status_code)
+        return UserList.from_api_response(response.json(), self._http)

recallrai/exceptions/__init__.py

@@ -2,27 +2,39 @@
 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 .auth import AuthenticationError
+from .network import TimeoutError, ConnectionError
+from .server import InternalServerError, RateLimitError
+from .sessions import SessionNotFoundError, InvalidSessionStateError
+from .users import UserNotFoundError, UserAlreadyExistsError, InvalidCategoriesError
 from .validation import ValidationError
+from .merge_conflicts import (
+    MergeConflictError, 
+    MergeConflictNotFoundError, 
+    MergeConflictAlreadyResolvedError,
+    MergeConflictInvalidQuestionsError,
+    MergeConflictMissingAnswersError,
+    MergeConflictInvalidAnswerError,
+)
 
 __all__ = [
     "RecallrAIError",
     "AuthenticationError",
-    "NetworkError", 
     "TimeoutError", 
     "ConnectionError",
-    "ServerError", 
     "InternalServerError",
-    "SessionError", 
+    "RateLimitError",
     "SessionNotFoundError", 
     "InvalidSessionStateError",
-    "UserError", 
     "UserNotFoundError", 
     "UserAlreadyExistsError",
+    "InvalidCategoriesError",
     "ValidationError",
+    "MergeConflictError",
+    "MergeConflictNotFoundError",
+    "MergeConflictAlreadyResolvedError",
+    "MergeConflictInvalidQuestionsError",
+    "MergeConflictMissingAnswersError",
+    "MergeConflictInvalidAnswerError",
 ]

recallrai/exceptions/auth.py

@@ -2,7 +2,6 @@
 Authentication-related exceptions for the RecallrAI SDK.
 """
 
-from typing import Any, Dict, Optional
 from .base import RecallrAIError
 
 
@@ -16,9 +15,7 @@ class AuthenticationError(RecallrAIError):
 
     def __init__(
         self, 
-        message: str = "Invalid API key or authentication failed", 
-        code: str = "authentication_error",
+        message: str = "Invalid API key or authentication failed.", 
         http_status: int = 401,
-        details: Optional[Dict[str, Any]] = None
     ):
-        super().__init__(message, code, http_status, details)
+        super().__init__(message, http_status)

recallrai/exceptions/base.py

@@ -2,32 +2,23 @@
 Base exception classes for the RecallrAI SDK.
 """
 
-from typing import Any, Dict, Optional
-
-
 class RecallrAIError(Exception):
-    """Base exception for all RecallrAI SDK errors."""
+    """Base exception class for all RecallrAI SDK exceptions."""
 
     def __init__(
         self, 
         message: str, 
-        code: Optional[str] = None, 
-        http_status: Optional[int] = None,
-        details: Optional[Dict[str, Any]] = None
+        http_status: int,
     ):
         """
         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
+            message: A human-readable error message.
+            http_status: The HTTP status code that triggered this error.
         """
         self.message = message
-        self.code = code
         self.http_status = http_status
-        self.details = details or {}
         super().__init__(self.message)
     
     def __str__(self) -> str:

recallrai/exceptions/merge_conflicts.py

@@ -0,0 +1,69 @@
+"""
+Merge conflicts-related exceptions for the RecallrAI SDK.
+"""
+
+from .base import RecallrAIError
+
+class MergeConflictError(RecallrAIError):
+    """
+    Base class for merge conflict-related exceptions.
+    
+    This exception is raised for errors related to merge conflict management
+    in the RecallrAI API.
+    """
+
+    def __init__(self, message: str, http_status: int):
+        super().__init__(message, http_status)
+
+class MergeConflictNotFoundError(MergeConflictError):
+    """
+    Raised when a merge conflict is not found.
+    
+    This exception is typically raised when trying to access or modify
+    a merge conflict that doesn't exist.
+    """
+    def __init__(self, message: str, http_status: int):
+        super().__init__(message, http_status)
+
+class MergeConflictAlreadyResolvedError(MergeConflictError):
+    """
+    Raised when trying to resolve a merge conflict that is already resolved.
+    
+    This exception is typically raised when trying to resolve a merge conflict
+    that has already been processed.
+    """
+    def __init__(self, message: str, http_status: int):
+        super().__init__(message, http_status)
+
+
+class MergeConflictInvalidQuestionsError(MergeConflictError):
+    """
+    Raised when trying to resolve a merge conflict with invalid questions.
+    
+    This exception is raised when the provided questions don't match the 
+    original clarifying questions for the merge conflict.
+    """
+    def __init__(self, message: str, http_status: int):
+        super().__init__(message, http_status)
+
+
+class MergeConflictMissingAnswersError(MergeConflictError):
+    """
+    Raised when trying to resolve a merge conflict with missing answers.
+    
+    This exception is raised when not all required clarifying questions 
+    have been answered.
+    """
+    def __init__(self, message: str, http_status: int):
+        super().__init__(message, http_status)
+
+
+class MergeConflictInvalidAnswerError(MergeConflictError):
+    """
+    Raised when trying to resolve a merge conflict with invalid answer options.
+    
+    This exception is raised when the provided answer is not one of the 
+    valid options for a question.
+    """
+    def __init__(self, message: str, http_status: int):
+        super().__init__(message, http_status)

recallrai/exceptions/network.py

@@ -2,7 +2,6 @@
 Network-related exceptions for the RecallrAI SDK.
 """
 
-from typing import Any, Dict, Optional
 from .base import RecallrAIError
 
 
@@ -14,14 +13,8 @@ class NetworkError(RecallrAIError):
     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)
+    def __init__(self, message: str, http_status: int):
+        super().__init__(message, http_status)
 
 
 class TimeoutError(NetworkError):
@@ -32,13 +25,8 @@ class TimeoutError(NetworkError):
     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)
+    def __init__(self, message: str, http_status: int):
+        super().__init__(message, http_status)
 
 
 class ConnectionError(NetworkError):
@@ -49,10 +37,5 @@ class ConnectionError(NetworkError):
     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)
+    def __init__(self, message: str, http_status: int):
+        super().__init__(message, http_status)

recallrai/exceptions/server.py

@@ -2,22 +2,18 @@
 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.
+    
+    This exception serves as the base for all exceptions related to
+    server-side errors in the RecallrAI API.
     """
-    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)
+    def __init__(self, message: str, http_status: int):
+        super().__init__(message, http_status)
 
 class InternalServerError(ServerError):
     """
@@ -26,38 +22,19 @@ class InternalServerError(ServerError):
     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)
-
+    def __init__(self, message: str, http_status: int):
+        super().__init__(message, http_status)
 
-# 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.
-#     """
+class RateLimitError(ServerError):
+    """
+    Raised when the API rate limit has been exceeded.
 
-#     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
+    This exception is raised when too many requests are made in a
+    short period of time.
+    """
 
+    def __init__(self, message: str, http_status: int):
+        super().__init__(message, http_status)
 
 # class ServiceUnavailableError(ServerError):
 #     """
@@ -66,10 +43,10 @@ class InternalServerError(ServerError):
 #     This exception is raised when the API is down for maintenance
 #     or experiencing issues.
 #     """
-
+#
 #     def __init__(
 #         self, 
-#         message: str = "Service temporarily unavailable", 
+#         message: str = "Service temporarily unavailable.", 
 #         code: str = "service_unavailable",
 #         http_status: int = 503,
 #         retry_after: Optional[int] = None,

recallrai/exceptions/sessions.py

@@ -2,7 +2,6 @@
 Sessions-related exceptions for the RecallrAI SDK.
 """
 
-from typing import Any, Dict, Optional
 from .base import RecallrAIError
 
 class SessionError(RecallrAIError):
@@ -13,14 +12,8 @@ class SessionError(RecallrAIError):
     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)
+    def __init__(self, message: str, http_status: int):
+        super().__init__(message, http_status)
 
 class InvalidSessionStateError(SessionError):
     """
@@ -30,14 +23,8 @@ class InvalidSessionStateError(SessionError):
     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)
+    def __init__(self, message: str, http_status: int):
+        super().__init__(message, http_status)
 
 class SessionNotFoundError(SessionError):
     """
@@ -47,14 +34,5 @@ class SessionNotFoundError(SessionError):
     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
+    def __init__(self, message: str, http_status: int):
+        super().__init__(message, http_status)

recallrai/exceptions/users.py

@@ -2,7 +2,6 @@
 Users-related exceptions for the RecallrAI SDK.
 """
 
-from typing import Any, Dict, Optional
 from .base import RecallrAIError
 
 class UserError(RecallrAIError):
@@ -13,14 +12,8 @@ class UserError(RecallrAIError):
     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)
+    def __init__(self, message: str, http_status: int):
+        super().__init__(message, http_status)
 
 class UserNotFoundError(UserError):
     """
@@ -29,17 +22,8 @@ class UserNotFoundError(UserError):
     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
+    def __init__(self, message: str, http_status: int):
+        super().__init__(message, http_status)
 
 class UserAlreadyExistsError(UserError):
     """
@@ -48,14 +32,15 @@ class UserAlreadyExistsError(UserError):
     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
+    def __init__(self, message: str, http_status: int):
+        super().__init__(message, http_status)
+
+class InvalidCategoriesError(UserError):
+    """
+    Raised when invalid categories are provided for user memories.
+    
+    This exception is typically raised when trying to filter memories
+    by categories that don't exist in the project.
+    """
+    def __init__(self, message: str, http_status: int):
+        super().__init__(message, http_status)

recallrai/exceptions/validation.py

@@ -2,7 +2,6 @@
 Validation-related exceptions for the RecallrAI SDK.
 """
 
-from typing import Any, Dict, Optional, Union
 from .base import RecallrAIError
 
 
@@ -14,11 +13,5 @@ class ValidationError(RecallrAIError):
     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)
+    def __init__(self, message: str, http_status: int):
+        super().__init__(message, http_status)