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

recallrai/models/user.py

@@ -0,0 +1,75 @@
+# Path: recallrai/models/user.py
+# Description: User data models for the RecallrAI SDK
+
+"""
+User-related data models for the RecallrAI SDK.
+"""
+
+from datetime import datetime
+from typing import Any, Dict
+
+from pydantic import BaseModel, Field
+
+
+class User(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")
+
+    class Config:
+        """Pydantic configuration."""
+        frozen = True
+        json_encoders = {
+            datetime: lambda dt: dt.isoformat()
+        }
+
+    @classmethod
+    def from_api_response(cls, data: Dict[str, Any]) -> "User":
+        """
+        Create a User instance from an API response.
+
+        Args:
+            data: API response data
+
+        Returns:
+            A User 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", {}),
+            created_at=user_data["created_at"],
+            last_active_at=user_data["last_active_at"],
+        )
+
+
+class UserList(BaseModel):
+    """Represents a paginated list of users."""
+    
+    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")
+
+    @classmethod
+    def from_api_response(cls, data: Dict[str, Any]) -> "UserList":
+        """
+        Create a UserList instance from an API response.
+
+        Args:
+            data: API response data
+
+        Returns:
+            A UserList instance
+        """
+        return cls(
+            users=[User.from_api_response({"user": user}) for user in data["users"]],
+            total=data["total"],
+            has_more=data["has_more"],
+        )

recallrai/session.py

@@ -0,0 +1,279 @@
+# Path: recallrai/session.py
+# Description: Session management class for the RecallrAI SDK
+
+"""
+Session management functionality for the RecallrAI SDK.
+"""
+
+from typing import List
+from .utils import HTTPClient
+from .models import (
+    Context,
+    Message,
+    SessionStatus,
+    MessageRole
+)
+from .exceptions import (
+    UserNotFoundError,
+    SessionNotFoundError,
+    InvalidSessionStateError,
+    RecallrAIError
+)
+from logging import getLogger
+
+logger = getLogger(__name__)
+
+class Session:
+    """
+    Manages a conversation session with RecallrAI.
+    
+    This class handles adding messages, retrieving context, and processing the session
+    to update the user's memory.
+    """
+
+    def __init__(
+        self,
+        http_client: HTTPClient,
+        user_id: str,
+        session_id: str,
+    ):
+        """
+        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
+        """
+        self._http = http_client
+        self.user_id = user_id
+        self.session_id = session_id
+
+    def add_user_message(self, message: 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.
+
+        Args:
+            message: Content of the assistant 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
+        """
+        response = self._http.post(
+            f"/api/v1/users/{self.user_id}/sessions/{self.session_id}/add-message",
+            data={"message": message, "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)
+            else:
+                raise SessionNotFoundError(session_id=self.session_id)
+        elif response.status_code == 400:
+            raise InvalidSessionStateError(
+                message=f"Cannot add message to session with status {self.get_status()}",
+            )
+        elif response.status_code != 200:
+            raise RecallrAIError(
+                message=f"Failed to add message: {response.json().get('detail', 'Unknown error')}",
+                http_status=response.status_code
+            )
+
+    def get_context(self) -> Context:
+        """
+        Get the current context for this session.
+
+        The context contains information from the user's memory that is relevant
+        to the current conversation.
+
+        Returns:
+            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
+        """
+        response = self._http.get(
+            f"/api/v1/users/{self.user_id}/sessions/{self.session_id}/context"
+        )
+        
+        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)
+            else:
+                raise SessionNotFoundError(session_id=self.session_id)
+        elif response.status_code != 200:
+            raise RecallrAIError(
+                message=f"Failed to get context: {response.json().get('detail', 'Unknown error')}",
+                http_status=response.status_code
+            )
+        status = self.get_status()
+        if status == SessionStatus.PROCESSED:
+            logger.warning("Cannot add message to a session that has already been processed")
+        elif status == SessionStatus.PROCESSING:
+            logger.warning("Cannot add message to a session that is currently being processed")
+        return Context.from_api_response(response.json())
+
+    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)
+            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()}')}",
+            )
+        elif response.status_code != 200:
+            raise RecallrAIError(
+                message=f"Failed to process session: {response.json().get('detail', 'Unknown error')}",
+                http_status=response.status_code
+            )
+
+    def get_status(self) -> SessionStatus:
+        """
+        Get the current status of the session.
+
+        Returns:
+            SessionStatus: The current status of 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
+        """
+        response = self._http.get(
+            f"/api/v1/users/{self.user_id}/sessions/{self.session_id}/status"
+        )
+        
+        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)
+            else:
+                raise SessionNotFoundError(session_id=self.session_id)
+        elif response.status_code != 200:
+            raise RecallrAIError(
+                message=f"Failed to get session status: {response.json().get('detail', 'Unknown error')}",
+                http_status=response.status_code
+            )
+            
+        return SessionStatus(response.json()["status"])
+
+    def get_messages(self) -> List[Message]:
+        """
+        Get all messages in the session.
+
+        Returns:
+            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
+        """
+        response = self._http.get(
+            f"/api/v1/users/{self.user_id}/sessions/{self.session_id}/messages"
+        )
+        
+        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)
+            else:
+                raise SessionNotFoundError(session_id=self.session_id)
+        elif response.status_code != 200:
+            raise RecallrAIError(
+                message=f"Failed to get messages: {response.json().get('detail', 'Unknown error')}",
+                http_status=response.status_code
+            )
+            
+        data = response.json()
+        return [Message(**msg) for msg in data["messages"]]

recallrai/user.py

@@ -0,0 +1,211 @@
+"""
+User management functionality for the RecallrAI SDK.
+"""
+
+from typing import Any, Dict, Optional
+from .utils import HTTPClient
+from .models import User as UserModel, SessionList
+from .session import Session
+from .exceptions import (
+    UserNotFoundError,
+    UserAlreadyExistsError,
+    SessionNotFoundError,
+    RecallrAIError
+)
+from logging import getLogger
+
+logger = getLogger(__name__)
+
+class User:
+    """
+    Represents a user in the RecallrAI system with methods for user management.
+    
+    This class wraps a user object and provides methods for updating user data,
+    and for creating and managing sessions.
+    """
+
+    def __init__(
+        self,
+        http_client: HTTPClient,
+        user_data: UserModel,
+    ):
+        """
+        Initialize a user.
+
+        Args:
+            http_client: HTTP client for API communication
+            user_data: User data model with user information
+        """
+        self._http = http_client
+        self._user_data = user_data
+        self.user_id = user_data.user_id
+        self.metadata = user_data.metadata
+        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':
+        """
+        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
+
+        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
+        """
+        data = {}
+        if new_metadata is not None:
+            data["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)
+        elif response.status_code == 409:
+            raise UserAlreadyExistsError(user_id=new_user_id)
+        elif response.status_code != 200:
+            raise RecallrAIError(
+                message=f"Failed to update user: {response.json().get('detail', 'Unknown error')}",
+                http_status=response.status_code
+            )
+            
+        updated_data = UserModel.from_api_response(response.json())
+        
+        # Update internal state
+        self._user_data = updated_data
+        self.user_id = updated_data.user_id
+        self.metadata = updated_data.metadata
+        self.last_active_at = updated_data.last_active_at
+        
+        return self
+
+    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
+        """
+        response = self._http.delete(f"/api/v1/users/{self.user_id}")
+        
+        if response.status_code == 404:
+            raise UserNotFoundError(user_id=self.user_id)
+        elif response.status_code != 204:
+            raise RecallrAIError(
+                message=f"Failed to delete user: {response.json().get('detail', 'Unknown error')}",
+                http_status=response.status_code
+            )
+
+    def create_session(self, auto_process_after_minutes: int = -1) -> Session:
+        """
+        Create a new session for this user.
+
+        Args:
+            auto_process_after_minutes: Minutes to wait before auto-processing (-1 to disable)
+
+        Returns:
+            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
+        """
+        response = self._http.post(
+            f"/api/v1/users/{self.user_id}/sessions",
+            data={"auto_process_after_minutes": auto_process_after_minutes},
+        )
+        
+        if response.status_code == 404:
+            raise UserNotFoundError(user_id=self.user_id)
+        elif response.status_code != 201:
+            raise RecallrAIError(
+                message=f"Failed to create session: {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)
+
+    def get_session(self, session_id: str) -> Session:
+        """
+        Get an existing session for this user.
+
+        Args:
+            session_id: ID of the session to retrieve
+
+        Returns:
+            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:
+        """
+        List sessions for this user with pagination.
+
+        Args:
+            offset: Number of records to skip
+            limit: Maximum number of records to return
+
+        Returns:
+            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
+        """
+        response = self._http.get(
+            f"/api/v1/users/{self.user_id}/sessions",
+            params={"offset": offset, "limit": limit},
+        )
+        
+        if response.status_code == 404:
+            raise UserNotFoundError(user_id=self.user_id)
+        elif response.status_code != 200:
+            raise RecallrAIError(
+                message=f"Failed to list sessions: {response.json().get('detail', 'Unknown error')}",
+                http_status=response.status_code
+            )
+            
+        return SessionList.from_api_response(response.json())

recallrai/utils/__init__.py

@@ -0,0 +1,8 @@
+# Path: recallrai/utils/__init__.py
+# Description: Package initialization for utilities
+
+from .http_client import HTTPClient
+
+__all__ = [
+    "HTTPClient",
+]

recallrai/utils/http_client.py

@@ -0,0 +1,123 @@
+# Path: recallrai/utils/http.py
+# Description: HTTP client utilities for the RecallrAI SDK
+
+from httpx import Response, Client, TimeoutException, NetworkError, ConnectError
+from typing import Any, Dict, Optional
+from ..exceptions import (
+    TimeoutError, 
+    NetworkError as CustomNetworkError, 
+    ConnectionError,
+    ValidationError,
+    InternalServerError,
+    AuthenticationError,
+)
+
+class HTTPClient:
+    """HTTP client for making requests to the RecallrAI API."""
+
+    def __init__(
+        self,
+        api_key: str,
+        project_id: str,
+        base_url: str,
+        timeout: int = 30,
+    ):
+        """
+        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
+        """
+        self.api_key = api_key
+        self.project_id = project_id
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.client = Client(
+            timeout=self.timeout,
+            headers={
+                "X-Api-Key": self.api_key,
+                "X-Project-Id": self.project_id,
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+                "User-Agent": "RecallrAI-Python-SDK",
+                # TODO: "SDK-Version": "0.1.0",
+            },
+        )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        params: Optional[Dict[str, Any]] = None,
+        data: Optional[Dict[str, Any]] = None,
+    ) -> Response:
+        """
+        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
+
+        Returns:
+            The parsed JSON response
+        """
+        url = f"{self.base_url}{path}"
+        
+        # Filter out None values in params and data
+        if params:
+            params = {k: v for k, v in params.items() if v is not None}
+        
+        if data:
+            data = {k: v for k, v in data.items() if v is not None}
+        
+        try:
+            response = self.client.request(
+                method=method,
+                url=url,
+                params=params,
+                json=data,
+            )
+            if response.status_code == 422:
+                raise ValidationError(
+                    details=response.json()["detail"],
+                )
+            elif response.status_code == 500:
+                raise InternalServerError(
+                    details=response.json()["detail"],
+                )
+            elif response.status_code == 401:
+                raise AuthenticationError(
+                    details=response.json()["detail"],
+                )
+            
+            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}")
+        except Exception as e:
+            # Handle other exceptions as needed
+            raise e
+
+    def get(self, path: str, params: Optional[Dict[str, Any]] = None) -> Response:
+        """Make a GET request."""
+        return self.request("GET", path, params=params)
+
+    def post(self, path: str, data: Optional[Dict[str, Any]] = None) -> Response:
+        """Make a POST request."""
+        return self.request("POST", path, data=data)
+
+    def put(self, path: str, data: Optional[Dict[str, Any]] = None) -> Response:
+        """Make a PUT request."""
+        return self.request("PUT", path, data=data)
+
+    def delete(self, path: str) -> Response:
+        """Make a DELETE request."""
+        return self.request("DELETE", path)