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

recallrai/utils/http_client.py

@@ -0,0 +1,123 @@
+"""
+HTTP client for making requests to the RecallrAI API.
+"""
+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)

recallrai-0.2.0.dist-info/METADATA

@@ -0,0 +1,439 @@
+Metadata-Version: 2.3
+Name: recallrai
+Version: 0.2.0
+Summary: Official Python SDK for RecallrAI - Revolutionary contextual memory system that enables AI assistants to form meaningful connections between conversations, just like human memory.
+License: MIT
+Keywords: ai,memory,context,llm,mem0,getzep,zep
+Author: Devasheesh Mishra
+Author-email: devasheeshmishra4@gmail.com
+Requires-Python: >=3.9,<3.14
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: httpx (>=0.28.1,<0.29.0)
+Requires-Dist: pydantic (>=2.11.1,<3.0.0)
+Project-URL: Homepage, https://recallrai.com
+Project-URL: Repository, https://github.com/recallrai/sdk-python
+Description-Content-Type: text/markdown
+
+# RecallrAI Python SDK
+
+Official Python SDK for RecallrAI – a revolutionary contextual memory system that enables AI assistants to form meaningful connections between conversations, just like human memory.
+
+## Installation
+
+Install the SDK via Poetry or pip:
+
+```bash
+poetry add recallrai
+# or
+pip install recallrai
+```
+
+## Initialization
+
+Create a client instance with your API key and project ID:
+
+```python
+from recallrai import RecallrAI
+
+api_key = "rai_yourapikey"
+project_id = "project-uuid"
+client = RecallrAI(api_key=api_key, project_id=project_id)
+```
+
+## User Management
+
+### Create a User
+
+```python
+from recallrai.exceptions import UserAlreadyExistsError
+try:
+    user = client.create_user(user_id="user123", metadata={"name": "John Doe"})
+    print(f"Created user: {user.user_id}")
+    print(f"User metadata: {user.metadata}")
+    print(f"Created at: {user.created_at}")
+except UserAlreadyExistsError as e:
+    print(f"Error: {e}")
+```
+
+### Get a User
+
+```python
+from recallrai.exceptions import UserNotFoundError
+try:
+    user = client.get_user("user123")
+    print(f"User metadata: {user.metadata}")
+    print(f"Last active: {user.last_active_at}")
+except UserNotFoundError as e:
+    print(f"Error: {e}")
+```
+
+### List Users
+
+```python
+user_list = client.list_users(offset=0, limit=10)
+print(f"Total users: {user_list.total}")
+print(f"Has more users: {user_list.has_more}")
+
+for user in user_list.users:
+    print(f"User ID: {user.user_id}")
+    print(f"Metadata: {user.metadata}")
+    print(f"Created at: {user.created_at}")
+    print(f"Last active: {user.last_active_at}")
+    print("---")
+```
+
+### Update a User
+
+```python
+from recallrai.exceptions import UserNotFoundError, UserAlreadyExistsError
+try:
+    user = client.get_user("user123")
+    updated_user = user.update(
+        new_metadata={"name": "John Doe", "role": "admin"},
+        new_user_id="john_doe"
+    )
+    print(f"Updated user ID: {updated_user.user_id}")
+    print(f"Updated metadata: {updated_user.metadata}")
+except UserNotFoundError as e:
+    print(f"Error: {e}")
+except UserAlreadyExistsError as e:
+    print(f"Error: {e}")
+```
+
+### Delete a User
+
+```python
+from recallrai.exceptions import UserNotFoundError
+try:
+    user = client.get_user("john_doe")
+    user.delete()
+    print("User deleted successfully")
+except UserNotFoundError as e:
+    print(f"Error: {e}")
+```
+
+## Session Management
+
+### Create a Session
+
+```python
+from recallrai.exceptions import UserNotFoundError
+from recallrai.session import Session
+
+try:
+    # First, get the user
+    user = client.get_user("user123")
+    
+    # Create a session for the user; auto_process_after_minutes set to -1 disables auto-processing
+    session: Session = user.create_session(auto_process_after_minutes=5)
+    print("Created session id:", session.session_id)
+except UserNotFoundError as e:
+    print(f"Error: {e}")
+```
+
+### Get an Existing Session
+
+```python
+from recallrai.exceptions import UserNotFoundError, SessionNotFoundError
+
+try:
+    # First, get the user
+    user = client.get_user("user123")
+    
+    # Retrieve an existing session by its ID
+    session = user.get_session(session_id="session-uuid")
+    print("Session status:", session.get_status())
+except UserNotFoundError as e:
+    print(f"Error: {e}")
+except SessionNotFoundError as e:
+    print(f"Error: {e}")
+```
+
+### List Sessions
+
+```python
+from recallrai.exceptions import UserNotFoundError
+
+try:
+    # First, get the user
+    user = client.get_user("user123")
+    
+    # List sessions for this user
+    session_list = user.list_sessions(offset=0, limit=10)
+    for session in session_list.sessions:
+        print(session.session_id, session.status)
+except UserNotFoundError as e:
+    print(f"Error: {e}")
+```
+
+### Session – Adding Messages
+
+```python
+from recallrai.exceptions import UserNotFoundError, SessionNotFoundError, InvalidSessionStateError
+
+try:
+    # Add a user message
+    session.add_user_message("Hello! How are you?")
+    
+    # Add an assistant message
+    session.add_assistant_message("I'm an assistant. How can I help you?")
+except UserNotFoundError as e:
+    print(f"Error: {e}")
+except SessionNotFoundError as e:
+    print(f"Error: {e}")
+except InvalidSessionStateError as e:
+    print(f"Error: {e}")
+```
+
+### Session – Retrieving Context
+
+```python
+from recallrai.exceptions import UserNotFoundError, SessionNotFoundError
+
+try:
+    context = session.get_context()
+    print("Memory used:", context.memory_used)
+    print("Context:", context.context)
+except UserNotFoundError as e:
+    print(f"Error: {e}")
+except SessionNotFoundError as e:
+    print(f"Error: {e}")
+```
+
+### Session – Process Session
+
+```python
+from recallrai.exceptions import UserNotFoundError, SessionNotFoundError, InvalidSessionStateError
+
+try:
+    session.process()
+except UserNotFoundError as e:
+    print(f"Error: {e}")
+except SessionNotFoundError as e:
+    print(f"Error: {e}")
+except InvalidSessionStateError as e:
+    print(f"Error: {e}")
+```
+
+### Session – Get Status and Messages
+
+```python
+from recallrai.exceptions import UserNotFoundError, SessionNotFoundError
+from recallrai.models import SessionStatus
+
+try:
+    status = session.get_status()
+    print("Session status:", status)
+    
+    # Check if the session is in a specific state
+    if status == SessionStatus.PROCESSED:
+        print("Session has been processed")
+    
+    messages = session.get_messages()
+    for message in messages:
+        print(f"{message.role}: {message.content} at {message.timestamp}")
+except UserNotFoundError as e:
+    print(f"Error: {e}")
+except SessionNotFoundError as e:
+    print(f"Error: {e}")
+```
+
+## Example Usage with LLMs
+
+```python
+import openai
+from recallrai import RecallrAI
+from recallrai.exceptions import UserNotFoundError
+
+# Initialize RecallrAI and OpenAI clients
+rai_client = RecallrAI(
+    api_key="rai_yourapikey", 
+    project_id="your-project-uuid"
+)
+oai_client = openai.OpenAI(api_key="your-openai-api-key")
+
+def chat_with_memory(user_id, session_id=None):
+    # Get or create user
+    try:
+        user = rai_client.get_user(user_id)
+    except UserNotFoundError:
+        user = rai_client.create_user(user_id)
+    
+    # Create a new session or get an existing one
+    if session_id:
+        session = user.get_session(session_id=session_id)
+    else:
+        session = user.create_session(auto_process_after_minutes=30)
+        print(f"Created new session: {session.session_id}")
+    
+    print("Chat session started. Type 'exit' to end the conversation.")
+    
+    while True:
+        # Get user input
+        user_message = input("You: ")
+        if user_message.lower() == 'exit':
+            break
+        
+        # Add the user message to RecallrAI
+        session.add_user_message(user_message)
+        
+        # Get context from RecallrAI after adding the user message
+        context = session.get_context()
+        
+        # Create a system prompt that includes the context
+        system_prompt = f"""You are a helpful assistant with memory of previous conversations.
+        
+        MEMORIES ABOUT THE USER:
+        {context.context}
+        
+        You can use the above memories to provide better responses to the user.
+        Don't mention that you have access to memories unless you are explicitly asked."""
+        
+        # Get previous messages
+        previous_messages = session.get_messages()
+        previous_messages = [{"role": message.role, "content": message.content} for message in previous_messages]
+
+        # Call the LLM with the system prompt and conversation history
+        response = oai_client.chat.completions.create(
+            model="gpt-4o-mini",
+            messages=[
+                {"role": "system", "content": system_prompt},
+                **previous_messages,
+            ],
+            temperature=0.7
+        )
+        
+        assistant_message = response.choices[0].message.content
+        
+        # Print the assistant's response
+        print(f"Assistant: {assistant_message}")
+        
+        # Add the assistant's response to RecallrAI
+        session.add_assistant_message(assistant_message)
+    
+    # Process the session at the end of the conversation
+    print("Processing session to update memory...")
+    session.process()
+    print(f"Session ended. Session ID: {session.session_id}")
+    return session.session_id
+
+# Example usage
+if __name__ == "__main__":
+    user_id = "user123"
+    # To continue a previous session, uncomment below and provide the session ID
+    # previous_session_id = "previously-saved-session-uuid"
+    # session_id = chat_with_memory(user_id, previous_session_id)
+    
+    # Start a new session
+    session_id = chat_with_memory(user_id)
+    print(f"To continue this conversation later, use session ID: {session_id}")
+```
+
+## Exception Handling
+
+The RecallrAI SDK implements a comprehensive exception hierarchy to help you handle different error scenarios gracefully:
+
+### Base Exception
+
+- **RecallrAIError**: The base exception for all SDK-specific errors. All other exceptions inherit from this.
+
+### Authentication Errors
+
+- **AuthenticationError**: Raised when there's an issue with your API key or project ID authentication.
+
+### Network-Related Errors
+
+- **NetworkError**: Base exception for all network-related issues.
+- **TimeoutError**: Occurs when a request takes too long to complete.
+- **ConnectionError**: Happens when the SDK cannot establish a connection to the RecallrAI API.
+
+### Server Errors
+
+- **ServerError**: Base class for server-side errors.
+- **InternalServerError**: Raised when the RecallrAI API returns a 5xx error code.
+
+### User-Related Errors
+
+- **UserError**: Base for all user-related exceptions.
+- **UserNotFoundError**: Raised when attempting to access a user that doesn't exist.
+- **UserAlreadyExistsError**: Occurs when creating a user with an ID that already exists.
+
+### Session-Related Errors
+
+- **SessionError**: Base for all session-related exceptions.
+- **SessionNotFoundError**: Raised when attempting to access a non-existent session.
+- **InvalidSessionStateError**: Occurs when performing an operation that's not valid for the current session state (e.g., adding a message to a processed session).
+
+### Input Validation Errors
+
+- **ValidationError**: Raised when provided data doesn't meet the required format or constraints.
+
+### Importing Exceptions
+
+You can import exceptions directly from the `recallrai.exceptions` module:
+
+```python
+# Import specific exceptions
+from recallrai.exceptions import UserNotFoundError, SessionNotFoundError
+
+# Import all exceptions
+from recallrai.exceptions import (
+    RecallrAIError,
+    AuthenticationError,
+    NetworkError,
+    TimeoutError,
+    ConnectionError,
+    ServerError, 
+    InternalServerError,
+    SessionError, 
+    SessionNotFoundError, 
+    InvalidSessionStateError,
+    UserError, 
+    UserNotFoundError, 
+    UserAlreadyExistsError,
+    ValidationError,
+)
+```
+
+### Best Practices for Error Handling
+
+When implementing error handling with the RecallrAI SDK, consider these best practices:
+
+1. **Handle specific exceptions first**: Catch more specific exceptions before general ones.
+
+   ```python
+   try:
+       # SDK operation
+   except UserNotFoundError:
+       # Specific handling
+   except RecallrAIError:
+       # General fallback
+   ```
+
+2. **Implement retry logic for transient errors**: Network and timeout errors might be temporary.
+
+3. **Log detailed error information**: Exceptions contain useful information for debugging.
+
+4. **Handle common user flows**: For example, check if a user exists before operations, or create them if they don't:
+
+   ```python
+   try:
+       user = client.get_user(user_id)
+   except UserNotFoundError:
+       user = client.create_user(user_id)
+   ```
+
+For more detailed information on specific exceptions, refer to the API documentation.
+
+## Conclusion
+
+This README outlines the basic usage of the RecallrAI SDK functions for user and session management. For additional documentation and advanced usage, please see the [official documentation](https://recallrai.com) or the source code repository on [GitHub](https://github.com/recallrai/sdk-python).
+

recallrai-0.2.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+recallrai/__init__.py,sha256=kv6EEDKXguLde8pXjnAdeDFA67v7PDRKelhdCCnwOsQ,272
+recallrai/client.py,sha256=eNK2cXZDlWPYqAObE9Hc83h0m9FA8Eeh5NAjy1TRAv0,4575
+recallrai/exceptions/__init__.py,sha256=uE-7ywJ1dIJPdUTJisVRXwMzgv6AMgTEpRfDe_d9-1c,782
+recallrai/exceptions/auth.py,sha256=dLabhdTmCBtpp0Ghv3iIw6f3xQn2XXjKCFm1WsiIqXc,700
+recallrai/exceptions/base.py,sha256=89wTP9Yt3S7Mej2pzKkAZKM0OFXho4t2KouEaiJ69Wg,1016
+recallrai/exceptions/network.py,sha256=QriByZFgXPEeYfpl_ozxTtzNwHfHtUlPSVb2pAymCx0,1562
+recallrai/exceptions/server.py,sha256=jLINK_3CoOwqKyzKtGB5DwxyZj5S8U2z6zYCZePWqbk,2416
+recallrai/exceptions/sessions.py,sha256=EwcdzxpDxDjUZVu-etgnayWFq2ADmybKfEQuweLw1VE,1777
+recallrai/exceptions/users.py,sha256=kpIhgt92cmW9AOazkD4hgvF8PPq2aYRridtO5pyto8M,1835
+recallrai/exceptions/validation.py,sha256=H0Nnv_RDeah3KzLhB13Ozu0q2cFMJIO-kfl3PWnCpyc,625
+recallrai/models/__init__.py,sha256=g4alYb0tTelVYF-MWCUhgDH1Ea2uK88SCnel4maDlR0,321
+recallrai/models/session.py,sha256=8lf5JxC4RtiO8vPVP17DA5_IDEsGgeZyx9bdoWF9PtE,3601
+recallrai/models/user.py,sha256=E1NSDsG7suW8fTTm5tu4dnWY45vasPauhu0DRMaFRf8,2131
+recallrai/session.py,sha256=aIgVrwmI7OUEnx3iqzVkYxLQ17tgQ9m1-K2UC4d9I5E,10982
+recallrai/user.py,sha256=coK42Rj6fUgzrj0AjOnZyNxxLRH_vEiFFvwRvhpLLqI,7706
+recallrai/utils/__init__.py,sha256=6DovotQG1UrscXSIHMkAJcFXmpf4D-4Iwl1RbeKKY84,107
+recallrai/utils/http_client.py,sha256=sLpKEcvfWoq7Ny-U_bptfqxqQbZGCL_1cwbDmvKXUwk,3930
+recallrai-0.2.0.dist-info/METADATA,sha256=HwQu0i-lX5PhwEKpAdcnWoMp6Bri_sBPHVD1Qov1v8U,13217
+recallrai-0.2.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+recallrai-0.2.0.dist-info/RECORD,,

{recallrai-0.1.0.dist-info → recallrai-0.2.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 2.1.1
+Generator: poetry-core 2.1.3
 Root-Is-Purelib: true
 Tag: py3-none-any

recallrai/utils/exceptions.py

@@ -1,61 +0,0 @@
-# Path: recallrai/exceptions.py
-# Description: Custom exceptions for the RecallrAI SDK
-
-"""
-Custom exceptions for the RecallrAI SDK.
-"""
-
-from typing import Any, Dict, Optional
-
-
-class RecallrAIError(Exception):
-    """Base exception for all RecallrAI SDK errors."""
-
-    def __init__(self, message: str, code: Optional[str] = None, details: Optional[Dict[str, Any]] = None):
-        """
-        Initialize a RecallrAI error.
-
-        Args:
-            message: A human-readable error message
-            code: An optional error code
-            details: Optional additional details about the error
-        """
-        self.message = message
-        self.code = code
-        self.details = details or {}
-        super().__init__(self.message)
-
-
-class AuthenticationError(RecallrAIError):
-    """Raised when there is an authentication issue with the API key or project ID."""
-    pass
-
-
-class NotFoundError(RecallrAIError):
-    """Raised when a requested resource is not found."""
-    pass
-
-
-class ValidationError(RecallrAIError):
-    """Raised when the API rejects a request due to validation errors."""
-    pass
-
-
-class RateLimitError(RecallrAIError):
-    """Raised when the API rate limit has been exceeded."""
-    pass
-
-
-class ServerError(RecallrAIError):
-    """Raised when the API encounters an unexpected server error."""
-    pass
-
-
-class BadRequestError(RecallrAIError):
-    """Raised when the API rejects a request due to invalid parameters."""
-    pass
-
-
-class SessionProcessingError(RecallrAIError):
-    """Raised when there is an error processing a session."""
-    pass