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

recallrai/__init__.py

@@ -0,0 +1,19 @@
+# Path: recallrai/__init__.py
+# Description: Package initialization file with SDK version and main class exports
+
+"""
+RecallrAI Python SDK
+
+This package provides a Python interface to interact with the RecallrAI API.
+"""
+
+from .client import RecallrAI
+from .user import User
+from .session import Session
+
+__version__ = "0.1.0"
+__all__ = [
+    "RecallrAI",
+    "User",
+    "Session",
+]

recallrai/client.py

@@ -0,0 +1,220 @@
+# Path: recallrai/client.py
+# Description: Main client class for the RecallrAI SDK
+
+"""
+Main client class for the RecallrAI SDK.
+
+This module provides the RecallrAI class, which is the primary interface for the SDK.
+"""
+
+import uuid
+from typing import Any, Dict, Optional
+from pydantic import HttpUrl
+from .utils import HTTPClient, RecallrAIError
+from .models import User as UserModel, UserList, SessionStatus, SessionList
+from .user import User
+from .session import Session
+from logging import getLogger
+
+logger = getLogger(__name__)
+
+class RecallrAI:
+    """
+    Main client for interacting with the RecallrAI API.
+    
+    This class provides methods for creating and managing users, sessions, and memories.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        project_id: uuid.UUID,
+        base_url: HttpUrl = "https://api.recallrai.com",
+        timeout: int = 30,
+    ):
+        """
+        Initialize the RecallrAI client.
+
+        Args:
+            api_key: Your RecallrAI API key
+            project_id: Your project ID
+            base_url: The base URL for the RecallrAI API
+            timeout: Request timeout in seconds
+        """
+        if not api_key.startswith("rai_"):
+            raise ValueError("API key must start with 'rai_'")
+        
+        self.api_key = api_key
+        self.project_id = str(project_id)
+        self.base_url = str(base_url)
+        
+        self.http = HTTPClient(
+            api_key=self.api_key,
+            project_id=self.project_id,
+            base_url=self.base_url,
+            timeout=timeout,
+        )
+
+    # User management
+    def create_user(self, user_id: str, metadata: Optional[Dict[str, Any]] = None) -> User:
+        """
+        Create a new user.
+
+        Args:
+            user_id: Unique identifier for the user
+            metadata: Optional metadata to associate with the user
+
+        Returns:
+            The created user object
+
+        Raises:
+            ValidationError: If the user_id is invalid
+            BadRequestError: If a user with the same ID already exists
+        """
+        response = self.http.post("/api/v1/users", data={"user_id": user_id, "metadata": metadata or {}})
+        user_data = UserModel.from_api_response(response)
+        return User(self.http, user_data)
+
+    def get_user(self, user_id: str) -> User:
+        """
+        Get a user by ID.
+
+        Args:
+            user_id: Unique identifier of the user
+
+        Returns:
+            A User object representing the user
+
+        Raises:
+            NotFoundError: If the user is not found
+        """
+        response = self.http.get(f"/api/v1/users/{user_id}")
+        user_data = UserModel.from_api_response(response)
+        return User(self.http, user_data)
+
+    def list_users(self, offset: int = 0, limit: int = 10) -> UserList:
+        """
+        List users with pagination.
+
+        Args:
+            offset: Number of records to skip
+            limit: Maximum number of records to return
+
+        Returns:
+            List of users with pagination info
+        """
+        response = self.http.get("/api/v1/users", params={"offset": offset, "limit": limit})
+        return UserList.from_api_response(response)
+
+    def update_user(
+        self, 
+        user_id: str, 
+        new_metadata: Optional[Dict[str, Any]] = None, 
+        new_user_id: Optional[str] = None
+    ) -> User:
+        """
+        Update a user's metadata or ID.
+
+        Args:
+            user_id: Current ID of the user
+            new_metadata: New metadata to associate with the user
+            new_user_id: New ID for the user
+
+        Returns:
+            The updated user
+
+        Raises:
+            NotFoundError: If the user is not found
+            ValidationError: If the new_user_id is invalid
+            BadRequestError: If a user with the new_user_id already exists
+        """
+        data = {}
+        if new_metadata is not None:
+            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/{user_id}", data=data)
+        user_data = UserModel.from_api_response(response)
+        return User(self.http, user_data)
+
+    def delete_user(self, user_id: str) -> None:
+        """
+        Delete a user.
+
+        Args:
+            user_id: ID of the user to delete
+
+        Raises:
+            NotFoundError: If the user is not found
+        """
+        self.http.delete(f"/api/v1/users/{user_id}")
+
+    # Session management
+    def create_session(self, user_id: str, auto_process_after_minutes: int = -1) -> Session:
+        """
+        Create a new session for a user.
+
+        Args:
+            user_id: ID of the user to create the session for
+            auto_process_after_minutes: Minutes to wait before auto-processing (-1 to disable)
+
+        Returns:
+            A Session object to interact with the created session
+
+        Raises:
+            NotFoundError: If the user is not found
+            ValidationError: If auto_process_after_minutes is invalid
+        """
+        response = self.http.post(
+            f"/api/v1/users/{user_id}/sessions",
+            data={"auto_process_after_minutes": auto_process_after_minutes},
+        )
+        
+        session_id = response["session_id"]
+        return Session(self.http, user_id, session_id)
+
+    def get_session(self, user_id: str, session_id: str) -> Session:
+        """
+        Get an existing session.
+
+        Args:
+            user_id: ID of the user who owns the session
+            session_id: ID of the session to retrieve
+
+        Returns:
+            A Session object to interact with the session
+
+        Raises:
+            NotFoundError: If the user or session is not found
+        """
+        # Ensure the session exists by checking its status
+        session = Session(self.http, user_id, session_id)
+        status = session.get_status()
+        if status == SessionStatus.PROCESSING:
+            raise RecallrAIError("Session is already processing. You can't add messages to it. Create a new session instead.")
+        elif status == SessionStatus.PROCESSED:
+            raise RecallrAIError("Session has already been processed. You can't add messages to it. Create a new session instead.")
+        
+        return session
+
+    def list_sessions(self, user_id: str, offset: int = 0, limit: int = 10) -> SessionList:
+        """
+        List sessions for a user with pagination.
+
+        Args:
+            user_id: ID of the user
+            offset: Number of records to skip
+            limit: Maximum number of records to return
+
+        Returns:
+            List of sessions with pagination info
+
+        Raises:
+            NotFoundError: If the user is not found
+        """
+        response = self.http.get(
+            f"/api/v1/users/{user_id}/sessions",
+            params={"offset": offset, "limit": limit},
+        )
+        return SessionList.from_api_response(response)

recallrai/models/__init__.py

@@ -0,0 +1,16 @@
+# Path: recallrai/models/__init__.py
+# Description: Package initialization for data models
+
+from .session import Context, Message, MessageRole, Session, SessionList, SessionStatus
+from .user import User, UserList
+
+__all__ = [
+    "User", 
+    "UserList",
+    "Session",
+    "SessionList",
+    "SessionStatus",
+    "Message",
+    "MessageRole",
+    "Context",
+]

recallrai/models/session.py

@@ -0,0 +1,138 @@
+# Path: recallrai/models/session.py
+# Description: Session data models for the RecallrAI SDK
+
+"""
+Session-related data models for the RecallrAI SDK.
+"""
+
+import enum, uuid
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class MessageRole(str, enum.Enum):
+    """
+    Message role in a conversation.
+    """
+    USER = "user"
+    ASSISTANT = "assistant"
+
+
+class Message(BaseModel):
+    """
+    Represents a message in a conversation session.
+    """
+    role: MessageRole = 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")
+
+    class Config:
+        """Pydantic configuration."""
+        frozen = True
+        json_encoders = {
+            datetime: lambda dt: dt.isoformat()
+        }
+
+
+class SessionStatus(str, enum.Enum):
+    """
+    Status of a session.
+    """
+    PENDING = "pending"
+    PROCESSING = "processing"
+    PROCESSED = "processed"
+
+
+class Session(BaseModel):
+    """
+    Represents a conversation session.
+    """
+    session_id: uuid.UUID = Field(..., description="Unique identifier for the session")
+    status: SessionStatus = Field(..., description="Current status of the session")
+    created_at: datetime = Field(..., description="When the session was created")
+
+    class Config:
+        """Pydantic configuration."""
+        frozen = True
+        json_encoders = {
+            datetime: lambda dt: dt.isoformat(),
+            uuid.UUID: lambda id: str(id)
+        }
+
+    @classmethod
+    def from_api_response(cls, data: Dict[str, Any]) -> "Session":
+        """
+        Create a Session instance from an API response.
+
+        Args:
+            data: API response data
+
+        Returns:
+            A Session instance
+        """
+        return cls(
+            session_id=data["session_id"],
+            status=data.get("status", SessionStatus.PENDING),
+            created_at=data.get("created_at", datetime.now()),
+            messages=None
+        )
+
+
+class SessionList(BaseModel):
+    """
+    Represents a paginated list of sessions.
+    """
+    sessions: List[Session] = Field(..., description="List of sessions")
+    total: int = Field(..., description="Total number of sessions")
+    has_more: bool = Field(..., description="Whether there are more sessions to fetch")
+
+    class Config:
+        """Pydantic configuration."""
+        frozen = True
+
+    @classmethod
+    def from_api_response(cls, data: Dict[str, Any]) -> "SessionList":
+        """
+        Create a SessionList instance from an API response.
+
+        Args:
+            data: API response data
+
+        Returns:
+            A SessionList instance
+        """
+        return cls(
+            sessions=[Session.from_api_response(session) for session in data["sessions"]],
+            total=data["total"],
+            has_more=data["has_more"],
+        )
+
+
+class Context(BaseModel):
+    """
+    Represents the context for a session.
+    """
+    memory_used: bool = Field(..., description="Whether memory was used to generate the context")
+    context: str = Field(..., description="The context for the session")
+
+    class Config:
+        """Pydantic configuration."""
+        frozen = True
+
+    @classmethod
+    def from_api_response(cls, data: Dict[str, Any]) -> "Context":
+        """
+        Create a Context instance from an API response.
+
+        Args:
+            data: API response data
+
+        Returns:
+            A Context instance
+        """
+        return cls(
+            memory_used=data["memory_used"],
+            context=data["context"],
+        )

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,169 @@
+# 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, RecallrAIError
+from .models import (
+    Context,
+    Message,
+    SessionStatus,
+    MessageRole
+)
+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:
+            BadRequestError: If the session is already processed
+            NotFoundError: If the session or user is not found
+        """
+        # Check the status of session
+        status = self.get_status()
+        if status == SessionStatus.PROCESSED:
+            raise RecallrAIError("Cannot add message to a session that has already been processed")
+        elif status == SessionStatus.PROCESSING:
+            raise RecallrAIError("Cannot add message to a session that is currently being processed")
+        
+        # Add the user message
+        self._http.post(
+            f"/api/v1/users/{self.user_id}/sessions/{self.session_id}/add-message",
+            data={"message": message, "role": 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:
+            BadRequestError: If the session is already processed
+            NotFoundError: If the session or user is not found
+        """
+        # Check the status of session
+        status = self.get_status()
+        if status == SessionStatus.PROCESSED:
+            raise RecallrAIError("Cannot add message to a session that has already been processed")
+        elif status == SessionStatus.PROCESSING:
+            raise RecallrAIError("Cannot add message to a session that is currently being processed")
+        
+        # Add the assistant message
+        self._http.post(
+            f"/api/v1/users/{self.user_id}/sessions/{self.session_id}/add-message",
+            data={"message": message, "role": MessageRole.ASSISTANT},
+        )
+
+    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:
+            NotFoundError: If the session or user is not found
+        """
+        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")
+        response = self._http.get(
+            f"/api/v1/users/{self.user_id}/sessions/{self.session_id}/context"
+        )
+        return Context.from_api_response(response)
+
+    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:
+            BadRequestError: If the session is already processed or being processed
+            NotFoundError: If the session or user is not found
+            SessionProcessingError: If there is an error during processing
+        """
+        # Check the status of session
+        status = self.get_status()
+        if status == SessionStatus.PROCESSED:
+            raise RecallrAIError("Cannot process a session that has already been processed")
+        elif status == SessionStatus.PROCESSING:
+            raise RecallrAIError("Cannot process a session that is currently being processed")
+        
+        # Process the session
+        self._http.post(
+            f"/api/v1/users/{self.user_id}/sessions/{self.session_id}/process"
+        )
+
+    def get_status(self) -> SessionStatus:
+        """
+        Get the current status of the session.
+
+        Returns:
+            SessionStatus: The current status of the session
+
+        Raises:
+            NotFoundError: If the session or user is not found
+        """
+        response = self._http.get(
+            f"/api/v1/users/{self.user_id}/sessions/{self.session_id}/status"
+        )
+        return SessionStatus(response["status"])
+
+    def get_messages(self) -> List[Message]:
+        """
+        Get all messages in the session.
+
+        Returns:
+            List of messages in the session
+
+        Raises:
+            NotFoundError: If the session or user is not found
+        """
+        response = self._http.get(
+            f"/api/v1/users/{self.user_id}/sessions/{self.session_id}/messages"
+        )
+        return [Message(**msg) for msg in response["messages"]]

recallrai/user.py

@@ -0,0 +1,130 @@
+"""
+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
+
+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:
+            NotFoundError: If the user is not found
+            ValidationError: If the new_user_id is invalid
+            BadRequestError: If a user with the new_user_id already exists
+        """
+        data = {}
+        if new_metadata is not None:
+            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)
+        updated_data = UserModel.from_api_response(response)
+        
+        # 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:
+            NotFoundError: If the user is not found
+        """
+        self._http.delete(f"/api/v1/users/{self.user_id}")
+
+    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:
+            ValidationError: If auto_process_after_minutes is invalid
+        """
+        response = self._http.post(
+            f"/api/v1/users/{self.user_id}/sessions",
+            data={"auto_process_after_minutes": auto_process_after_minutes},
+        )
+        
+        session_id = response["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:
+            NotFoundError: If the session is not found
+        """
+        return Session(self._http, self.user_id, session_id)
+
+    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
+        """
+        response = self._http.get(
+            f"/api/v1/users/{self.user_id}/sessions",
+            params={"offset": offset, "limit": limit},
+        )
+        return SessionList.from_api_response(response)

recallrai/utils/__init__.py

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

recallrai/utils/exceptions.py

@@ -0,0 +1,61 @@
+# 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

recallrai/utils/http.py

@@ -0,0 +1,167 @@
+# Path: recallrai/utils/http.py
+# Description: HTTP client utilities for the RecallrAI SDK
+
+"""
+HTTP client utilities for making requests to the RecallrAI API.
+"""
+
+import json
+from typing import Any, Dict, Optional, Tuple, Union
+
+import httpx
+
+from .exceptions import (
+    AuthenticationError,
+    BadRequestError,
+    NotFoundError,
+    RateLimitError,
+    RecallrAIError,
+    ServerError,
+    ValidationError,
+)
+
+ACCEPTED_STATUS_CODES = [
+    200,  # OK
+    201,  # Created
+    204,  # No Content
+]
+
+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 = httpx.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 _handle_response(self, response: httpx.Response) -> Dict[str, Any]:
+        """
+        Handle the HTTP response and raise appropriate exceptions for errors.
+
+        Args:
+            response: The HTTP response from the API
+
+        Returns:
+            The parsed JSON response body
+            
+        Raises:
+            AuthenticationError: When the API key or project ID is invalid
+            NotFoundError: When the requested resource is not found
+            ValidationError: When the API rejects the request due to validation errors
+            RateLimitError: When the API rate limit has been exceeded
+            ServerError: When the API encounters an unexpected server error
+            RecallrAIError: For other types of errors
+        """
+        if response.status_code == 204:
+            return {}
+            
+        try:
+            data = response.json() if response.content else {}
+        except json.JSONDecodeError:
+            data = {}
+
+        error_detail = data.get("detail", "Unknown error")
+        
+        if response.status_code in ACCEPTED_STATUS_CODES:
+            return data
+        elif response.status_code == 400:
+            raise BadRequestError(message=f"Bad request: {error_detail}", details=data)
+        elif response.status_code == 401:
+            raise AuthenticationError(message="Invalid API key or project ID", details=data)
+        elif response.status_code == 404:
+            raise NotFoundError(message=f"Resource not found: {error_detail}", details=data)
+        elif response.status_code == 422:
+            raise ValidationError(message=f"Validation error: {error_detail}", details=data)
+        elif response.status_code == 429:
+            raise RateLimitError(message="API rate limit exceeded", details=data)
+        elif response.status_code >= 500:
+            raise ServerError(message=f"Server error: {error_detail}", details=data)
+        else:
+            raise RecallrAIError(
+                message=f"Unexpected error: {response.status_code} - {error_detail}",
+                details=data,
+            )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        params: Optional[Dict[str, Any]] = None,
+        data: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """
+        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,
+            )
+            return self._handle_response(response)
+        except httpx.HTTPError as e:
+            raise RecallrAIError(f"HTTP error: {str(e)}")
+        except Exception as e:
+            raise RecallrAIError(f"Unexpected error: {str(e)}")
+
+    def get(self, path: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """Make a GET request."""
+        return self.request("GET", path, params=params)
+
+    def post(self, path: str, data: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """Make a POST request."""
+        return self.request("POST", path, data=data)
+
+    def put(self, path: str, data: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """Make a PUT request."""
+        return self.request("PUT", path, data=data)
+
+    def delete(self, path: str) -> Dict[str, Any]:
+        """Make a DELETE request."""
+        return self.request("DELETE", path)

recallrai-0.1.0.dist-info/METADATA

@@ -0,0 +1,268 @@
+Metadata-Version: 2.3
+Name: recallrai
+Version: 0.1.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.8,<4.0
+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.8
+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.25.0,<0.26.0)
+Requires-Dist: pydantic (>=2.4.0,<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.user import User
+
+user_id = "user123"
+metadata = {"key": "value"}
+user = client.create_user(user_id=user_id, metadata=metadata)
+print("Created user:", user.user_id)
+```
+
+### Get a User
+
+```python
+user = client.get_user("user123")
+print("User metadata:", user.metadata)
+```
+
+### List Users
+
+```python
+user_list = client.list_users(offset=0, limit=10)
+for user in user_list.users:
+    print(user.user_id, user.metadata)
+```
+
+### Update a User
+
+```python
+# Update the user's metadata and/or change the user ID
+updated_user = client.update_user(user_id="user123", new_metadata={"role": "user"}, new_user_id="user1234")
+print("Updated user id:", updated_user.user_id)
+```
+
+### Delete a User
+
+```python
+client.delete_user("user1234")
+print("User deleted.")
+```
+
+## Session Management
+
+### Create a Session
+
+```python
+from recallrai.session import Session
+
+# Create a session for a user; auto_process_after_minutes set to -1 disables auto-processing.
+session = client.create_session(user_id="user123", auto_process_after_minutes=5)
+print("Created session id:", session.session_id)
+```
+
+### Get an Existing Session
+
+```python
+# Retrieve an existing session by its ID
+session = client.get_session(user_id="user123", session_id="session-uuid")
+print("Session status:", session.get_status())
+```
+
+### List Sessions
+
+```python
+session_list = client.list_sessions(user_id="user123", offset=0, limit=10)
+for session in session_list.sessions:
+    print(session.session_id, session.status)
+```
+
+### Session – Adding Messages
+
+#### Add a User Message
+
+```python
+session.add_user_message("Hello! How are you?")
+```
+
+### Session – Retrieving Context
+
+```python
+context = session.get_context()
+print("Memory used:", context.memory_used)
+print("Context:", context.context)
+```
+
+#### Add an Assistant Message
+
+```python
+session.add_assistant_message("I'm an assistant. How can I help you?")
+```
+
+### Session – Process Session
+
+```python
+session.process()
+```
+
+### Session – Get Status and Messages
+
+```python
+status = session.get_status()
+print("Session status:", status)
+
+messages = session.get_messages()
+for message in messages:
+    print(f"{message.role}: {message.content} at {message.timestamp}")
+```
+
+## Example Usage with LLMs
+
+```python
+import openai
+from recallrai import RecallrAI
+
+# Initialize RecallrAI and OpenAI clients
+recallrai_client = RecallrAI(api_key="rai_yourapikey", project_id="project-uuid")
+openai_client = openai.OpenAI(api_key="your-openai-api-key")
+
+def chat_with_memory(user_id, session_id=None):
+    # Get or create user
+    try:
+        user = recallrai_client.get_user(user_id)
+    except:
+        user = recallrai_client.create_user(user_id)
+    
+    # Create a new session or get an existing one
+    if session_id:
+        session = recallrai_client.get_session(user_id=user_id, session_id=session_id)
+    else:
+        session = recallrai_client.create_session(user_id=user_id, 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 user message
+        response = openai_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
+
+> Exception handling will be improved in future.
+Each operation may raise custom exceptions defined in the SDK:
+
+```python
+from recallrai.utils.exceptions import NotFoundError, ValidationError
+
+try:
+    user = client.get_user("nonexistent_id")
+except NotFoundError as e:
+    print("User not found:", e.message)
+except ValidationError as e:
+    print("Invalid input:", e.message)
+```
+
+## 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.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+recallrai/__init__.py,sha256=lw4pmQKtKkfTZ50xY3Z3J9IRxaG1XMrvEsN-jSazeHY,385
+recallrai/client.py,sha256=lzD4DYL8kedr6P-9zJbf93CCt9PxmmHcSE2HzKBIU0w,6976
+recallrai/models/__init__.py,sha256=2wwbyVAY4IgBn1a7YcbA4i1_pXJpYPYuQo80N8PVTlI,361
+recallrai/models/session.py,sha256=Okn2tMmnl0UPL9q-Bl4cBaUcgs_U_nnvmKj3CHWavGY,3701
+recallrai/models/user.py,sha256=yu7HzceZ-U2Hp6lbRjA31SQsyfD3dmuBoQ9dVGvfZ14,2190
+recallrai/session.py,sha256=r045TL3a4_g0JjbCJ7VyRdhMX4JsUpVTDmMeeVwpGtY,5690
+recallrai/user.py,sha256=VwQhKSJrwEEV7LgGDHOIRbIfwRi7OE5V-F146CGD8kY,4035
+recallrai/utils/__init__.py,sha256=p_RBdfNvgBWQ62psiokCPCmZI5H7AQm8EJiRLxfHUjA,212
+recallrai/utils/exceptions.py,sha256=b-8ONmtUgcjJxUg68pXwnana-5zt4C0cR2rTliFBGBE,1581
+recallrai/utils/http.py,sha256=dGd4uUWtRDRBLZctNDNfdDr5njekMjCPBYSWcvKRpJM,5513
+recallrai-0.1.0.dist-info/METADATA,sha256=WU87emxQgZ4t5p8k9ipp8MwbbwDLWDmzrWyYzY_-TJg,7801
+recallrai-0.1.0.dist-info/WHEEL,sha256=XbeZDeTWKc1w7CSIyre5aMDU_-PohRwTQceYnisIYYY,88
+recallrai-0.1.0.dist-info/RECORD,,

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

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

recallrai-0.0.1.dist-info/METADATA

@@ -1,17 +0,0 @@
-Metadata-Version: 2.3
-Name: recallrai
-Version: 0.0.1
-Summary: Comming soon
-License: MIT
-Author: Devasheesh Mishra
-Author-email: devasheeshmishra4@gmail.com
-Requires-Python: >=3.10,<4.0
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Description-Content-Type: text/markdown
-
-Comming soon...

recallrai-0.0.1.dist-info/RECORD

@@ -1,5 +0,0 @@
-recallrai/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-recallrai/__main__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-recallrai-0.0.1.dist-info/METADATA,sha256=SBCR1N69hXrhhNh6qZ2T9qO8ZyXBd8chEXPUNCiCZio,545
-recallrai-0.0.1.dist-info/WHEEL,sha256=RaoafKOydTQ7I_I3JTrPCg6kUmTgtm4BornzOqyEfJ8,88
-recallrai-0.0.1.dist-info/RECORD,,