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

recallrai/models/user.py

@@ -3,17 +3,20 @@ User-related data models for the RecallrAI SDK.
 """
 
 from datetime import datetime
-from typing import Any, Dict
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
 from pydantic import BaseModel, Field
+from ..utils import HTTPClient
+if TYPE_CHECKING:
+    from ..user import User
 
 
 class UserModel(BaseModel):
     """Represents a user in the RecallrAI system."""
     
-    user_id: str = Field(..., description="Unique identifier for the user")
-    metadata: Dict[str, Any] = Field(default_factory=dict, description="Custom metadata for the user")
-    created_at: datetime = Field(..., description="When the user was created")
-    last_active_at: datetime = Field(..., description="When the user was last active")
+    user_id: str = Field(..., description="Unique identifier for the user.")
+    metadata: Dict[str, Any] = Field(..., description="Custom metadata for the user.")
+    created_at: datetime = Field(..., description="When the user was created.")
+    last_active_at: datetime = Field(..., description="When the user was last active.")
 
     class Config:
         """Pydantic configuration."""
@@ -28,16 +31,16 @@ class UserModel(BaseModel):
         Create a UserModel instance from an API response.
 
         Args:
-            data: API response data
+            data: API response data.
 
         Returns:
-            A UserModel instance
+            A UserModel instance.
         """
         if "user" in data:
             user_data = data["user"]
         else:
             user_data = data
-            
+
         return cls(
             user_id=user_data["user_id"],
             metadata=user_data.get("metadata", {}),
@@ -48,24 +51,140 @@ class UserModel(BaseModel):
 
 class UserList(BaseModel):
     """Represents a paginated list of users."""
-    
-    users: list[UserModel] = Field(..., description="List of users")
-    total: int = Field(..., description="Total number of users")
-    has_more: bool = Field(..., description="Whether there are more users to fetch")
+
+    users: List["User"] = Field(..., description="List of users.")
+    total: int = Field(..., description="Total number of users.")
+    has_more: bool = Field(..., description="Whether there are more users to fetch.")
+
+    class Config:
+        arbitrary_types_allowed = True
 
     @classmethod
-    def from_api_response(cls, data: Dict[str, Any]) -> "UserList":
+    def from_api_response(cls, data: Dict[str, Any], http_client: HTTPClient) -> "UserList":
         """
         Create a UserList instance from an API response.
 
         Args:
-            data: API response data
+            data: API response data.
 
         Returns:
-            A UserList instance
+            A UserList instance.
         """
+        from ..user import User
         return cls(
-            users=[UserModel.from_api_response({"user": user}) for user in data["users"]],
+            users=[
+                User(http_client, UserModel.from_api_response(user)) for user in data["users"]
+            ],
             total=data["total"],
             has_more=data["has_more"],
         )
+
+
+class MemoryVersionInfo(BaseModel):
+    """Information about a specific version of a memory."""
+    
+    version_number: int = Field(..., description="Version number (1 = oldest, N = current)")
+    content: str = Field(..., description="Content of this version")
+    created_at: datetime = Field(..., description="When this version was created")
+    expired_at: datetime = Field(..., description="When this version expired")
+    expiration_reason: str = Field(..., description="Why this version expired (NewMemoryVersionCreationReason enum)")
+
+    class Config:
+        frozen = True
+        json_encoders = {
+            datetime: lambda dt: dt.isoformat()
+        }
+
+
+class MemoryRelationship(BaseModel):
+    """Connected memory information."""
+    
+    memory_id: str = Field(..., description="ID of the connected memory")
+    content: str = Field(..., description="Brief content for context")
+
+    class Config:
+        frozen = True
+
+
+class UserMemoryItem(BaseModel):
+    """Complete memory information with all metadata."""
+
+    memory_id: str = Field(..., description="ID of the current/latest version")
+    categories: List[str] = Field(..., description="Memory categories")
+    content: str = Field(..., description="Current version content")
+    created_at: datetime = Field(..., description="When the latest version was created")
+    
+    # Version information
+    version_number: int = Field(..., description="Which version this is (e.g., 3 means 3rd version)")
+    total_versions: int = Field(..., description="How many versions exist total")
+    has_previous_versions: bool = Field(..., description="If total_versions > 1")
+    
+    # Version history (only if requested)
+    previous_versions: Optional[List[MemoryVersionInfo]] = Field(None, description="Memories connected via prev_version_id")
+    
+    # Relationships (only if requested)
+    connected_memories: Optional[List[MemoryRelationship]] = Field(None, description="Memories connected via ProjectUserMemoryConnections")
+    
+    # Merge conflict info
+    merge_conflict_in_progress: bool = Field(..., description="Whether a merge conflict is in progress")
+    
+    # Session info
+    session_id: str = Field(..., description="Which session created this version")
+
+    class Config:
+        frozen = True
+        json_encoders = {
+            datetime: lambda dt: dt.isoformat()
+        }
+
+
+class UserMemoriesList(BaseModel):
+    """Represents a paginated list of user memories."""
+
+    items: List[UserMemoryItem]
+    total: int
+    has_more: bool
+
+    @classmethod
+    def from_api_response(cls, data: Dict[str, Any]) -> "UserMemoriesList":
+        return cls(
+            items=[UserMemoryItem(**item) for item in data["items"]],
+            total=data["total"],
+            has_more=data["has_more"],
+        )
+
+
+class UserMessage(BaseModel):
+    """Represents a single message from a user's conversation history."""
+
+    role: str = Field(..., description="Role of the message sender (user or assistant).")
+    content: str = Field(..., description="Content of the message.")
+    timestamp: datetime = Field(..., description="When the message was sent.")
+    session_id: str = Field(..., description="ID of the session this message belongs to.")
+
+    class Config:
+        frozen = True
+        json_encoders = {
+            datetime: lambda dt: dt.isoformat()
+        }
+
+
+class UserMessagesList(BaseModel):
+    """Represents a list of user messages."""
+
+    messages: List[UserMessage] = Field(..., description="List of user messages.")
+
+    @classmethod
+    def from_api_response(cls, data: Dict[str, Any]) -> "UserMessagesList":
+        """
+        Create a UserMessagesList instance from an API response.
+
+        Args:
+            data: API response data.
+
+        Returns:
+            A UserMessagesList instance.
+        """
+        return cls(
+            messages=[UserMessage(**message) for message in data["messages"]]
+        )

recallrai/session.py

@@ -2,13 +2,15 @@
 Session management functionality for the RecallrAI SDK.
 """
 
-from typing import List
+from typing import Optional, Dict, Any
 from .utils import HTTPClient
 from .models import (
     Context,
-    Message,
+    SessionMessagesList,
+    SessionModel,
     SessionStatus,
-    MessageRole
+    MessageRole,
+    RecallStrategy,
 )
 from .exceptions import (
     UserNotFoundError,
@@ -32,245 +34,293 @@ class Session:
         self,
         http_client: HTTPClient,
         user_id: str,
-        session_id: str,
+        session_data: SessionModel,
     ):
         """
         Initialize a session.
 
         Args:
-            http_client: HTTP client for API communication
-            user_id: ID of the user who owns this session
-            session_id: Unique identifier for the session
+            http_client: HTTP client for API communication.
+            user_id: ID of the user who owns this session.
+            session_data: Initial session data from the API.
         """
         self._http = http_client
-        self.user_id = user_id
-        self.session_id = session_id
+        self._user_id = user_id
+        self._session_data = session_data
+        self.session_id = self._session_data.session_id
+        self.status = self._session_data.status
+        self.created_at = self._session_data.created_at
+        self.metadata = self._session_data.metadata
 
-    def add_user_message(self, message: str) -> None:
+    def add_message(self, role: MessageRole, content: str) -> None:
         """
-        Add a user message to the session.
-
-        Args:
-            message: Content of the user message
-
-        Raises:
-            UserNotFoundError: If the user is not found
-            SessionNotFoundError: If the session is not found
-            InvalidSessionStateError: If the session is already processed or processing
-            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
-        """
-        self._add_message(message, MessageRole.USER)
-
-    def add_assistant_message(self, message: str) -> None:
-        """
-        Add an assistant message to the session.
+        Internal helper to add a message to the session.
 
         Args:
-            message: Content of the assistant message
+            role: Role of the message sender.
+            content: Content of the message.
 
         Raises:
-            UserNotFoundError: If the user is not found
-            SessionNotFoundError: If the session is not found
-            InvalidSessionStateError: If the session is already processed or processing
-            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
-        """
-        self._add_message(message, MessageRole.ASSISTANT)
-
-    def _add_message(self, message: str, role: MessageRole) -> None:
-        """
-        Internal helper to add a message to the session.
-        
-        Args:
-            message: Content of the message
-            role: Role of the message sender
-            
-        Raises:
-            UserNotFoundError: If the user is not found
-            SessionNotFoundError: If the session is not found
-            InvalidSessionStateError: If the session is already processed or processing
-            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.
+            SessionNotFoundError: If the session is not found.
+            InvalidSessionStateError: If the session is already processed or processing.
+            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(
-            f"/api/v1/users/{self.user_id}/sessions/{self.session_id}/add-message",
-            data={"message": message, "role": role.value},
+            f"/api/v1/users/{self._user_id}/sessions/{self.session_id}/add-message",
+            data={"message": content, "role": role.value},
         )
-        
+
         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(user_id=self.user_id)
+            if f"User {self._user_id} not found" in detail:
+                raise UserNotFoundError(message=detail, http_status=response.status_code)
             else:
-                raise SessionNotFoundError(session_id=self.session_id)
+                raise SessionNotFoundError(message=detail, http_status=response.status_code)
         elif response.status_code == 400:
+            detail = response.json().get('detail', f"Cannot add message to session with status {self.status}")
             raise InvalidSessionStateError(
-                message=f"Cannot add message to session with status {self.get_status()}",
+                message=detail,
+                http_status=response.status_code
             )
         elif response.status_code != 200:
             raise RecallrAIError(
-                message=f"Failed to add message: {response.json().get('detail', 'Unknown error')}",
+                message=response.json().get('detail', 'Unknown error'),
                 http_status=response.status_code
             )
 
-    def get_context(self) -> Context:
+    def get_context(
+        self, 
+        recall_strategy: RecallStrategy = RecallStrategy.BALANCED, 
+        min_top_k: int = 15,
+        max_top_k: int = 50, 
+        memories_threshold: float = 0.6,
+        summaries_threshold: float = 0.5,
+        last_n_messages: Optional[int] = None, 
+        last_n_summaries: Optional[int] = None,
+        timezone: Optional[str] = None
+    ) -> Context:
         """
         Get the current context for this session.
 
-        The context contains information from the user's memory that is relevant
-        to the current conversation.
+        Args:
+            recall_strategy: The type of recall strategy to use.
+            min_top_k: Minimum number of memories to return.
+            max_top_k: Maximum number of memories to return.
+            memories_threshold: Similarity threshold for memories.
+            summaries_threshold: Similarity threshold for summaries.
+            last_n_messages: Number of last messages to include in context.
+            last_n_summaries: Number of last summaries to include in context.
+            timezone: Timezone for formatting timestamps (e.g., 'America/New_York'). None for UTC.
 
         Returns:
-            Context information with the memory text and whether memory was used
+            Context information with the memory text and whether memory was used.
 
         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
+            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.
         """
+        params = {
+            "recall_strategy": recall_strategy.value,
+            "min_top_k": min_top_k,
+            "max_top_k": max_top_k,
+            "memories_threshold": memories_threshold,
+            "summaries_threshold": summaries_threshold,
+        }
+        if last_n_messages is not None:
+            params["last_n_messages"] = last_n_messages
+        if last_n_summaries is not None:
+            params["last_n_summaries"] = last_n_summaries
+        if timezone is not None:
+            params["timezone"] = timezone
+
         response = self._http.get(
-            f"/api/v1/users/{self.user_id}/sessions/{self.session_id}/context"
+            f"/api/v1/users/{self._user_id}/sessions/{self.session_id}/context",
+            params=params,
         )
-        
+
         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(user_id=self.user_id)
+            if f"User {self._user_id} not found" in detail:
+                raise UserNotFoundError(message=detail, http_status=response.status_code)
             else:
-                raise SessionNotFoundError(session_id=self.session_id)
+                raise SessionNotFoundError(message=detail, http_status=response.status_code)
         elif response.status_code != 200:
             raise RecallrAIError(
-                message=f"Failed to get context: {response.json().get('detail', 'Unknown error')}",
+                message=response.json().get('detail', 'Unknown error'),
                 http_status=response.status_code
             )
-        status = self.get_status()
-        if status == SessionStatus.PROCESSED:
+        if self.status == SessionStatus.PROCESSED:
             logger.warning("You are trying to get context for a processed session. Why do you need it?")
-        elif status == SessionStatus.PROCESSING:
+        elif self.status == SessionStatus.PROCESSING:
             logger.warning("You are trying to get context for a processing session. Why do you need it?")
         return Context.from_api_response(response.json())
 
-    def process(self) -> None:
+    def update(self, new_metadata: Optional[Dict[str, Any]] = None) -> None:
         """
-        Process the session to update the user's memory.
+        Update the session's metadata.
 
-        This method triggers the processing of the conversation to extract and update
-        the user's memory.
+        Args:
+            new_metadata: New metadata to associate with the session.
 
         Raises:
-            UserNotFoundError: If the user is not found
-            SessionNotFoundError: If the session is not found
-            InvalidSessionStateError: If the session is already processed or being processed
-            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.
+            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.
         """
-        response = self._http.post(
-            f"/api/v1/users/{self.user_id}/sessions/{self.session_id}/process"
+        response = self._http.put(
+            f"/api/v1/users/{self._user_id}/sessions/{self.session_id}",
+            data={"new_metadata": new_metadata},
         )
-        
+
         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(user_id=self.user_id)
+            if f"User {self._user_id} not found" in detail:
+                raise UserNotFoundError(message=detail, http_status=response.status_code)
             else:
-                raise SessionNotFoundError(session_id=self.session_id)
-        elif response.status_code == 400:
-            raise InvalidSessionStateError(
-                message=f"{response.json().get('detail', f'Cannot process session with status {self.get_status()}')}",
-            )
+                raise SessionNotFoundError(message=detail, http_status=response.status_code)
         elif response.status_code != 200:
             raise RecallrAIError(
-                message=f"Failed to process session: {response.json().get('detail', 'Unknown error')}",
+                message=response.json().get('detail', 'Unknown error'),
                 http_status=response.status_code
             )
+        
+        updated_data = SessionModel.from_api_response(response.json())
+        self.metadata = updated_data.metadata
 
-    def get_status(self) -> SessionStatus:
+    def refresh(self) -> None:
         """
-        Get the current status of the session.
+        Refresh the session data from the API.
 
-        Returns:
-            SessionStatus: The current status of the session
+        This method updates the local session data to reflect any changes
+        that may have occurred on the server.
 
         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
+            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.
         """
         response = self._http.get(
-            f"/api/v1/users/{self.user_id}/sessions/{self.session_id}/status"
+            f"/api/v1/users/{self._user_id}/sessions/{self.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
+            )
+        
+        self._session_data = SessionModel.from_api_response(response.json())
+        self.status = self._session_data.status
+        self.created_at = self._session_data.created_at
+        self.metadata = self._session_data.metadata
+
+    def process(self) -> None:
+        """
+        Process the session to update the user's memory.
+
+        This method triggers the processing of the conversation to extract and update
+        the user's memory.
+
+        Raises:
+            UserNotFoundError: If the user is not found.
+            SessionNotFoundError: If the session is not found.
+            InvalidSessionStateError: If the session is already processed or being processed.
+            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(
+            f"/api/v1/users/{self._user_id}/sessions/{self.session_id}/process"
         )
         
         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(user_id=self.user_id)
+            if f"User {self._user_id} not found" in detail:
+                raise UserNotFoundError(message=detail, http_status=response.status_code)
             else:
-                raise SessionNotFoundError(session_id=self.session_id)
+                raise SessionNotFoundError(message=detail, http_status=response.status_code)
+        elif response.status_code == 400:
+            detail = response.json().get('detail', f'Cannot process session with status {self.status}')
+            raise InvalidSessionStateError(
+                message=detail,
+                http_status=response.status_code
+            )
         elif response.status_code != 200:
             raise RecallrAIError(
-                message=f"Failed to get session status: {response.json().get('detail', 'Unknown error')}",
+                message=response.json().get('detail', 'Unknown error'),
                 http_status=response.status_code
             )
-            
-        return SessionStatus(response.json()["status"])
 
-    def get_messages(self) -> List[Message]:
+    def get_messages(
+        self,
+        offset: int = 0,
+        limit: int = 50,
+    ) -> SessionMessagesList:
         """
         Get all messages in the session.
 
         Returns:
-            List of messages in the session
+            Paginated list of messages in 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
+            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.
         """
         response = self._http.get(
-            f"/api/v1/users/{self.user_id}/sessions/{self.session_id}/messages"
+            f"/api/v1/users/{self._user_id}/sessions/{self.session_id}/messages",
+            params={"offset": offset, "limit": limit},
         )
         
         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(user_id=self.user_id)
+            if f"User {self._user_id} not found" in detail:
+                raise UserNotFoundError(message=detail, http_status=response.status_code)
             else:
-                raise SessionNotFoundError(session_id=self.session_id)
+                raise SessionNotFoundError(message=detail, http_status=response.status_code)
         elif response.status_code != 200:
             raise RecallrAIError(
-                message=f"Failed to get messages: {response.json().get('detail', 'Unknown error')}",
+                message=response.json().get('detail', 'Unknown error'),
                 http_status=response.status_code
             )
-            
-        data = response.json()
-        return [Message(**msg) for msg in data["messages"]]
+        
+        return SessionMessagesList.from_api_response(response.json())
+
+    def __repr__(self) -> str:
+        return f"<Session id={self.session_id} user_id={self._user_id} status={self.status}>"