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

recallrai/user.py

@@ -2,14 +2,27 @@
 User management functionality for the RecallrAI SDK.
 """
 
-from typing import Any, Dict, Optional
+import json
+from typing import Any, List, Dict, Optional
 from .utils import HTTPClient
-from .models import User as UserModel, SessionList
+from .models import (
+    UserModel, 
+    SessionModel, 
+    SessionList, 
+    UserMemoriesList, 
+    UserMessagesList,
+    MergeConflictList, 
+    MergeConflictStatus,
+    MergeConflictModel,
+)
 from .session import Session
+from .merge_conflict import MergeConflict
 from .exceptions import (
     UserNotFoundError,
     UserAlreadyExistsError,
+    InvalidCategoriesError,
     SessionNotFoundError,
+    MergeConflictNotFoundError,
     RecallrAIError
 )
 from logging import getLogger
@@ -33,8 +46,8 @@ class User:
         Initialize a user.
 
         Args:
-            http_client: HTTP client for API communication
-            user_data: User data model with user information
+            http_client: HTTP client for API communication.
+            user_data: User data model with user information.
         """
         self._http = http_client
         self._user_data = user_data
@@ -43,41 +56,40 @@ class User:
         self.created_at = user_data.created_at
         self.last_active_at = user_data.last_active_at
 
-    def update(self, new_metadata: Optional[Dict[str, Any]] = None, new_user_id: Optional[str] = None) -> 'User':
+    def update(self, new_metadata: Optional[Dict[str, Any]] = None, new_user_id: Optional[str] = None) -> None:
         """
         Update this user's metadata or ID.
 
         Args:
-            new_metadata: New metadata to associate with the user
-            new_user_id: New ID for the user
-
-        Returns:
-            The updated user object
+            new_metadata: New metadata to associate with the user.
+            new_user_id: New ID for the user.
 
         Raises:
-            UserNotFoundError: If the user is not found
-            UserAlreadyExistsError: If a user with the new_user_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
+            UserNotFoundError: If the user is not found.
+            UserAlreadyExistsError: If a user with the new_user_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.
         """
         data = {}
         if new_metadata is not None:
-            data["metadata"] = new_metadata
+            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/{self.user_id}", data=data)
         
         if response.status_code == 404:
-            raise UserNotFoundError(user_id=self.user_id)
+            detail = response.json().get("detail", f"User with ID {self.user_id} not found")
+            raise UserNotFoundError(message=detail, http_status=response.status_code)
         elif response.status_code == 409:
-            raise UserAlreadyExistsError(user_id=new_user_id)
+            detail = response.json().get("detail", f"User with ID {new_user_id} already exists")
+            raise UserAlreadyExistsError(message=detail, http_status=response.status_code)
         elif response.status_code != 200:
             raise RecallrAIError(
-                message=f"Failed to update user: {response.json().get('detail', 'Unknown error')}",
+                message=response.json().get('detail', 'Unknown error'),
                 http_status=response.status_code
             )
             
@@ -88,124 +100,387 @@ class User:
         self.user_id = updated_data.user_id
         self.metadata = updated_data.metadata
         self.last_active_at = updated_data.last_active_at
+
+    def refresh(self) -> None:
+        """
+        Refresh this user's data from the server.
+        
+        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.
+        """
+        response = self._http.get(f"/api/v1/users/{self.user_id}")
+        
+        if response.status_code == 404:
+            detail = response.json().get("detail", f"User with ID {self.user_id} not found")
+            raise UserNotFoundError(message=detail, http_status=response.status_code)
+        elif response.status_code != 200:
+            raise RecallrAIError(
+                message=response.json().get('detail', 'Unknown error'),
+                http_status=response.status_code
+            )
         
-        return self
+        refreshed_data = UserModel.from_api_response(response.json())
+        
+        # Update internal state
+        self._user_data = refreshed_data
+        self.user_id = refreshed_data.user_id
+        self.metadata = refreshed_data.metadata
+        self.created_at = refreshed_data.created_at
+        self.last_active_at = refreshed_data.last_active_at
 
     def delete(self) -> None:
         """
         Delete this 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.delete(f"/api/v1/users/{self.user_id}")
         
         if response.status_code == 404:
-            raise UserNotFoundError(user_id=self.user_id)
+            detail = response.json().get("detail", f"User with ID {self.user_id} not found")
+            raise UserNotFoundError(message=detail, http_status=response.status_code)
         elif response.status_code != 204:
             raise RecallrAIError(
-                message=f"Failed to delete user: {response.json().get('detail', 'Unknown error')}",
+                message=response.json().get('detail', 'Unknown error'),
                 http_status=response.status_code
             )
 
-    def create_session(self, auto_process_after_minutes: int = -1) -> Session:
+    def create_session(
+        self,
+        auto_process_after_seconds: int = 600,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Session:
         """
         Create a new session for this user.
 
         Args:
-            auto_process_after_minutes: Minutes to wait before auto-processing (-1 to disable)
+            auto_process_after_seconds: Seconds of inactivity allowed before automaticly processing the session (min 600).
+            metadata: Optional metadata for the session.
 
         Returns:
-            A Session object to interact with the created session
+            A Session object to interact with the created session.
 
         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.
         """
+        payload: Dict[str, Any] = {
+            "auto_process_after_seconds": auto_process_after_seconds,
+            "metadata": metadata or {},
+        }
         response = self._http.post(
             f"/api/v1/users/{self.user_id}/sessions",
-            data={"auto_process_after_minutes": auto_process_after_minutes},
+            data=payload,
         )
         
         if response.status_code == 404:
-            raise UserNotFoundError(user_id=self.user_id)
+            detail = response.json().get("detail", f"User {self.user_id} not found")
+            raise UserNotFoundError(message=detail, http_status=response.status_code)
         elif response.status_code != 201:
             raise RecallrAIError(
-                message=f"Failed to create session: {response.json().get('detail', 'Unknown error')}",
+                message=response.json().get('detail', 'Unknown error'),
                 http_status=response.status_code
             )
         
-        session_id = response.json()["session_id"]
-        return Session(self._http, self.user_id, session_id)
+        session_data = SessionModel.from_api_response(response.json())
+        return Session(self._http, self.user_id, session_data)
 
     def get_session(self, session_id: str) -> Session:
         """
         Get an existing session for this user.
 
         Args:
-            session_id: ID of the session to retrieve
+            session_id: ID of the session to retrieve.
 
         Returns:
-            A Session object to interact with the session
+            A Session object to interact with the session.
 
         Raises:
-            UserNotFoundError: If the user is not found
-            SessionNotFoundError: If the 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
-        """
-        # Verify the session exists by checking its status
-        session = Session(self._http, self.user_id, session_id)
-        try:
-            session.get_status()  # This will raise appropriate errors if the session doesn't exist
-            return session
-        except SessionNotFoundError:
-            raise
-        except Exception as e:
-            raise RecallrAIError(f"Error retrieving session: {str(e)}")
-
-    def list_sessions(self, offset: int = 0, limit: int = 10) -> SessionList:
+            UserNotFoundError: If the user is not found.
+            SessionNotFoundError: If the 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.
+        """
+        # First, verify the session exists by fetching its details
+        response = self._http.get(f"/api/v1/users/{self.user_id}/sessions/{session_id}")
+        
+        if response.status_code == 404:
+            # Check if it's a user not found or session not found error
+            detail = response.json().get('detail', '')
+            if f"User {self.user_id} not found" in detail:
+                raise UserNotFoundError(message=detail, http_status=response.status_code)
+            else:
+                raise SessionNotFoundError(message=detail, http_status=response.status_code)
+        elif response.status_code != 200:
+            raise RecallrAIError(
+                message=response.json().get('detail', 'Unknown error'),
+                http_status=response.status_code
+            )
+        
+        session_data = SessionModel.from_api_response(response.json())
+        return Session(self._http, self.user_id, session_data)
+
+    def list_sessions(
+        self,
+        offset: int = 0,
+        limit: int = 10,
+        metadata_filter: Optional[Dict[str, Any]] = None,
+        user_metadata_filter: Optional[Dict[str, Any]] = None,
+    ) -> SessionList:
         """
         List sessions for this user 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.
+            metadata_filter: Optional metadata filter for sessions.
+            user_metadata_filter: Optional metadata filter for the user.
 
         Returns:
-            List of sessions with pagination info
+            List of sessions with pagination info.
 
         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.
         """
+        params: Dict[str, Any] = {"offset": offset, "limit": limit}
+        if metadata_filter is not None:
+            params["metadata_filter"] = json.dumps(metadata_filter)
+        if user_metadata_filter is not None:
+            params["user_metadata_filter"] = json.dumps(user_metadata_filter)
+
         response = self._http.get(
             f"/api/v1/users/{self.user_id}/sessions",
-            params={"offset": offset, "limit": limit},
+            params=params,
         )
         
         if response.status_code == 404:
-            raise UserNotFoundError(user_id=self.user_id)
+            detail = response.json().get("detail", f"User {self.user_id} not found")
+            raise UserNotFoundError(message=detail, http_status=response.status_code)
         elif response.status_code != 200:
             raise RecallrAIError(
-                message=f"Failed to list sessions: {response.json().get('detail', 'Unknown error')}",
+                message=response.json().get('detail', 'Unknown error'),
                 http_status=response.status_code
             )
             
-        return SessionList.from_api_response(response.json())
+        return SessionList.from_api_response(response.json(), self.user_id, self._http)
+
+    def list_memories(
+        self,
+        offset: int = 0,
+        limit: int = 20,
+        categories: Optional[List[str]] = None,
+        include_previous_versions: bool = True,
+        include_connected_memories: bool = True,
+    ) -> UserMemoriesList:
+        """
+        List memories for this user with optional category filters.
+
+        Args:
+            offset: Number of records to skip.
+            limit: Maximum number of records to return (1-200).
+            categories: Optional list of category names to filter by.
+            include_previous_versions: Include full version history for each memory (default: True).
+            include_connected_memories: Include connected memories (default: True).
+
+        Returns:
+            UserMemoriesList: Paginated list of memory items.
+
+        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.
+        """
+        params: Dict[str, Any] = {
+            "offset": offset,
+            "limit": limit,
+            "include_previous_versions": include_previous_versions,
+            "include_connected_memories": include_connected_memories,
+        }
+        if categories is not None:
+            params["categories"] = categories
+
+        response = self._http.get(
+            f"/api/v1/users/{self.user_id}/memories",
+            params=params,
+        )
+
+        if response.status_code == 404:
+            detail = response.json().get("detail", f"User {self.user_id} not found")
+            raise UserNotFoundError(message=detail, http_status=response.status_code)
+        elif response.status_code == 400:
+            # Backend returns 400 for invalid categories
+            detail = response.json().get('detail', 'Invalid categories provided')
+            raise InvalidCategoriesError(
+                message=detail,
+                http_status=response.status_code
+            )
+        elif response.status_code != 200:
+            raise RecallrAIError(
+                message=response.json().get('detail', 'Unknown error'),
+                http_status=response.status_code,
+            )
+
+        return UserMemoriesList.from_api_response(response.json())
+
+    def list_merge_conflicts(
+        self,
+        offset: int = 0,
+        limit: int = 10,
+        status: Optional[MergeConflictStatus] = None,
+        sort_by: str = "created_at",
+        sort_order: str = "desc",
+    ) -> MergeConflictList:
+        """
+        List merge conflicts for this user.
+
+        Args:
+            offset: Number of records to skip.
+            limit: Maximum number of records to return.
+            status: Optional filter by conflict status.
+            sort_by: Field to sort by (created_at, resolved_at).
+            sort_order: Sort order (asc, desc).
+
+        Returns:
+            MergeConflictList: Paginated list of merge conflicts.
+
+        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.
+        """
+        params: Dict[str, Any] = {
+            "offset": offset,
+            "limit": limit,
+            "sort_by": sort_by,
+            "sort_order": sort_order,
+        }
+        if status is not None:
+            params["status"] = status.value
+
+        response = self._http.get(
+            f"/api/v1/users/{self.user_id}/merge-conflicts",
+            params=params,
+        )
+
+        if response.status_code == 404:
+            detail = response.json().get("detail", f"User {self.user_id} not found")
+            raise UserNotFoundError(message=detail, http_status=response.status_code)
+        elif response.status_code != 200:
+            raise RecallrAIError(
+                message=response.json().get('detail', 'Unknown error'),
+                http_status=response.status_code,
+            )
+
+        return MergeConflictList.from_api_response(response.json(), self._http, self.user_id)
+
+    def get_merge_conflict(self, conflict_id: str) -> MergeConflict:
+        """
+        Get a specific merge conflict by ID.
+
+        Args:
+            conflict_id: Unique identifier of the merge conflict.
+
+        Returns:
+            MergeConflict: The merge conflict object.
+
+        Raises:
+            UserNotFoundError: If the user is not found.
+            MergeConflictNotFoundError: If the merge conflict 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/{self.user_id}/merge-conflicts/{conflict_id}"
+        )
+
+        if response.status_code == 404:
+            # Check if it's a user not found or conflict not found error
+            detail = response.json().get('detail', '')
+            if f"User {self.user_id} not found" in detail:
+                raise UserNotFoundError(message=detail, http_status=response.status_code)
+            else:
+                raise MergeConflictNotFoundError(message=detail, http_status=response.status_code)
+        elif response.status_code != 200:
+            raise RecallrAIError(
+                message=response.json().get('detail', 'Unknown error'),
+                http_status=response.status_code
+            )
+
+        conflict_data = MergeConflictModel.from_api_response(response.json())
+        return MergeConflict(self._http, self.user_id, conflict_data)
+
+    def get_last_n_messages(self, n: int) -> UserMessagesList:
+        """
+        Get the last N messages for this user across all their sessions.
+
+        This method is useful for chatbot applications where you want to see
+        the recent conversation history for context.
+
+        Args:
+            n: Number of recent messages to retrieve (1-100, default: 10).
+
+        Returns:
+            UserMessagesList: List of the most recent messages.
+
+        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.
+            ValueError: If n is not between 1 and 100.
+        """
+        if not (1 <= n <= 100):
+            raise ValueError("n must be between 1 and 100")
+        
+        response = self._http.get(
+            f"/api/v1/users/{self.user_id}/messages",
+            params={"limit": n}
+        )
+        
+        if response.status_code == 404:
+            detail = response.json().get("detail", f"User with ID {self.user_id} not found")
+            raise UserNotFoundError(message=detail, http_status=response.status_code)
+        elif response.status_code != 200:
+            raise RecallrAIError(
+                message=response.json().get('detail', 'Unknown error'),
+                http_status=response.status_code
+            )
+        
+        return UserMessagesList.from_api_response(response.json())
+
+    def __repr__(self) -> str:
+        return f"<User id={self.user_id} created_at={self.created_at} last_active_at={self.last_active_at}>"

recallrai/utils/__init__.py

@@ -1,5 +1,6 @@
-# Path: recallrai/utils/__init__.py
-# Description: Package initialization for utilities
+"""
+Utility functions for the SDK.
+"""
 
 from .http_client import HTTPClient
 

recallrai/utils/http_client.py

@@ -1,11 +1,12 @@
-# Path: recallrai/utils/http.py
-# Description: HTTP client utilities for the RecallrAI SDK
+"""
+HTTP client for making requests to the RecallrAI API.
+"""
 
-from httpx import Response, Client, TimeoutException, NetworkError, ConnectError
+from json import JSONDecodeError
+from httpx import Response, Client, TimeoutException, ConnectError
 from typing import Any, Dict, Optional
 from ..exceptions import (
     TimeoutError, 
-    NetworkError as CustomNetworkError, 
     ConnectionError,
     ValidationError,
     InternalServerError,
@@ -26,11 +27,12 @@ class HTTPClient:
         Initialize the HTTP 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.
         """
+
         self.api_key = api_key
         self.project_id = project_id
         self.base_url = base_url.rstrip("/")
@@ -42,8 +44,7 @@ class HTTPClient:
                 "X-Project-Id": self.project_id,
                 "Content-Type": "application/json",
                 "Accept": "application/json",
-                "User-Agent": "RecallrAI-Python-SDK",
-                # TODO: "SDK-Version": "0.1.0",
+                "User-Agent": f"RecallrAI-Python-SDK/RecallrAI-Python-SDK/RecallrAI-Python-SDK/0.3.0",
             },
         )
 
@@ -58,13 +59,13 @@ class HTTPClient:
         Make a request to the RecallrAI API.
 
         Args:
-            method: HTTP method (GET, POST, PUT, DELETE)
-            path: API endpoint path
-            params: Query parameters
-            data: Request body data
+            method: HTTP method (GET, POST, PUT, DELETE).
+            path: API endpoint path.
+            params: Query parameters.
+            data: Request body data.
 
         Returns:
-            The parsed JSON response
+            The parsed JSON response.
         """
         url = f"{self.base_url}{path}"
         
@@ -82,26 +83,40 @@ class HTTPClient:
                 params=params,
                 json=data,
             )
+            
+            # Try to parse to JSON to catch JSON errors early
+            _ = response.json()
+            
             if response.status_code == 422:
+                detail = response.json().get("detail", "Validation error")
                 raise ValidationError(
-                    details=response.json()["detail"],
+                    message=detail,
+                    http_status=response.status_code
                 )
             elif response.status_code == 500:
+                detail = response.json().get("detail", "Internal server error")
                 raise InternalServerError(
-                    details=response.json()["detail"],
+                    message=detail,
+                    http_status=response.status_code
                 )
             elif response.status_code == 401:
+                detail = response.json().get("detail", "Authentication failed")
                 raise AuthenticationError(
-                    details=response.json()["detail"],
+                    message=detail,
+                    http_status=response.status_code
                 )
             
             return response
         except TimeoutException as e:
-            raise TimeoutError(f"Request timed out: {e}")
-        except NetworkError as e:
-            raise CustomNetworkError(f"Network error occurred: {e}")
-        except ConnectError as e:
-            raise ConnectionError(f"Failed to connect to the API: {e}")
+            raise TimeoutError(
+                message=f"Request timed out: {e}",
+                http_status=0  # No HTTP status for timeout
+            )
+        except (ConnectError, JSONDecodeError) as e:
+            raise ConnectionError(
+                message=f"Failed to connect to the API: {e}",
+                http_status=0  # No HTTP status for connection error
+            )
         except Exception as e:
             # Handle other exceptions as needed
             raise e