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

recallrai/__init__.py

@@ -0,0 +1,20 @@
+# 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.1"
+
+__all__ = [
+    "RecallrAI",
+    "User",
+    "Session",
+]

recallrai/client.py

@@ -0,0 +1,135 @@
+# 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.
+"""
+
+from typing import Any, Dict, Optional
+from .models import User as UserModel, UserList
+from .user import User
+from .utils import HTTPClient
+from .exceptions import (
+    UserAlreadyExistsError,
+    UserNotFoundError,
+    RecallrAIError,
+)
+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: str,
+        base_url: str = "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 = project_id
+        self.base_url = 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:
+            UserAlreadyExistsError: If a user with the same 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
+        """
+        response = self.http.post("/api/v1/users", data={"user_id": user_id, "metadata": metadata or {}})
+        if response.status_code == 409:
+            raise UserAlreadyExistsError(user_id=user_id)
+        elif response.status_code != 201:
+            raise RecallrAIError("Failed to create user", http_status=response.status_code)
+        user_data = UserModel.from_api_response(response.json())
+        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:
+            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/{user_id}")
+        if response.status_code == 404:
+            raise UserNotFoundError(user_id=user_id)
+        elif response.status_code != 200:
+            raise RecallrAIError("Failed to retrieve user", http_status=response.status_code)
+        user_data = UserModel.from_api_response(response.json())
+        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
+        
+        Raises:
+            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("/api/v1/users", params={"offset": offset, "limit": limit})
+        if response.status_code != 200:
+            raise RecallrAIError("Failed to list users", http_status=response.status_code)
+        return UserList.from_api_response(response.json())

recallrai/exceptions/__init__.py

@@ -0,0 +1,28 @@
+"""
+Exceptions for the RecallrAI SDK.
+"""
+
+from .auth import AuthenticationError
+from .base import RecallrAIError
+from .network import NetworkError, TimeoutError, ConnectionError
+from .server import ServerError, InternalServerError
+from .sessions import SessionError, SessionNotFoundError, InvalidSessionStateError
+from .users import UserError, UserNotFoundError, UserAlreadyExistsError
+from .validation import ValidationError
+
+__all__ = [
+    "RecallrAIError",
+    "AuthenticationError",
+    "NetworkError", 
+    "TimeoutError", 
+    "ConnectionError",
+    "ServerError", 
+    "InternalServerError",
+    "SessionError", 
+    "SessionNotFoundError", 
+    "InvalidSessionStateError",
+    "UserError", 
+    "UserNotFoundError", 
+    "UserAlreadyExistsError",
+    "ValidationError",
+]

recallrai/exceptions/auth.py

@@ -0,0 +1,24 @@
+"""
+Authentication-related exceptions for the RecallrAI SDK.
+"""
+
+from typing import Any, Dict, Optional
+from .base import RecallrAIError
+
+
+class AuthenticationError(RecallrAIError):
+    """
+    Raised when there is an authentication issue with the API key.
+    
+    This exception is typically raised when the API key is invalid,
+    has been revoked, or doesn't have the necessary permissions.
+    """
+
+    def __init__(
+        self, 
+        message: str = "Invalid API key or authentication failed", 
+        code: str = "authentication_error",
+        http_status: int = 401,
+        details: Optional[Dict[str, Any]] = None
+    ):
+        super().__init__(message, code, http_status, details)

recallrai/exceptions/base.py

@@ -0,0 +1,37 @@
+"""
+Base exception classes 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, 
+        http_status: Optional[int] = None,
+        details: Optional[Dict[str, Any]] = None
+    ):
+        """
+        Initialize a RecallrAI error.
+
+        Args:
+            message: A human-readable error message
+            code: An optional error code
+            http_status: The HTTP status code that triggered this error
+            details: Optional additional details about the error
+        """
+        self.message = message
+        self.code = code
+        self.http_status = http_status
+        self.details = details or {}
+        super().__init__(self.message)
+    
+    def __str__(self) -> str:
+        """Return a string representation of the error."""
+        if self.code:
+            return f"{self.code}: {self.message}"
+        return self.message

recallrai/exceptions/network.py

@@ -0,0 +1,58 @@
+"""
+Network-related exceptions for the RecallrAI SDK.
+"""
+
+from typing import Any, Dict, Optional
+from .base import RecallrAIError
+
+
+class NetworkError(RecallrAIError):
+    """
+    Base class for network-related exceptions.
+    
+    This exception is raised for errors related to network connectivity
+    and communication with the RecallrAI API.
+    """
+
+    def __init__(
+        self, 
+        message: str = "Network error occurred", 
+        code: str = "network_error",
+        http_status: Optional[int] = None,
+        details: Optional[Dict[str, Any]] = None
+    ):
+        super().__init__(message, code, http_status, details)
+
+
+class TimeoutError(NetworkError):
+    """
+    Raised when a request times out.
+    
+    This exception is raised when a request to the RecallrAI API
+    takes longer than the configured timeout.
+    """
+
+    def __init__(
+        self, 
+        message: str = "Request timed out", 
+        code: str = "timeout",
+        details: Optional[Dict[str, Any]] = None
+    ):
+        super().__init__(message, code, None, details)
+
+
+class ConnectionError(NetworkError):
+    """
+    Raised when a connection error occurs.
+    
+    This exception is raised when there's an issue connecting to
+    the RecallrAI API, such as DNS resolution issues or network unavailability.
+    """
+
+    def __init__(
+        self, 
+        message: str = "Failed to connect to the RecallrAI API", 
+        code: str = "connection_error",
+        details: Optional[Dict[str, Any]] = None
+    ):
+        super().__init__(message, code, None, details)

recallrai/exceptions/server.py

@@ -0,0 +1,82 @@
+"""
+Server-related exceptions for the RecallrAI SDK.
+"""
+
+from typing import Any, Dict, Optional
+from .base import RecallrAIError
+
+
+class ServerError(RecallrAIError):
+    """
+    Base class for server-related exceptions.
+    """
+    def __init__(
+        self, 
+        message: str = "Server error occurred", 
+        code: str = "server_error",
+        http_status: int = 500,
+        details: Optional[Dict[str, Any]] = None
+    ):
+        super().__init__(message, code, http_status, details)
+
+class InternalServerError(ServerError):
+    """
+    Raised when the RecallrAI API encounters an internal server error.
+    
+    This exception is typically raised when the API returns a 5xx error code.
+    """
+
+    def __init__(
+        self, 
+        message: str = "Internal server error", 
+        code: str = "server_error",
+        http_status: int = 500,
+        details: Optional[Dict[str, Any]] = None
+    ):
+        super().__init__(message, code, http_status, details)
+
+
+# class RateLimitError(ServerError):
+#     """
+#     Raised when the API rate limit has been exceeded.
+#
+#     This exception is raised when too many requests are made in a
+#     short period of time.
+#     """
+
+#     def __init__(
+#         self, 
+#         message: str = "API rate limit exceeded", 
+#         code: str = "rate_limit_exceeded",
+#         http_status: int = 429,
+#         retry_after: Optional[int] = None,
+#         details: Optional[Dict[str, Any]] = None
+#     ):
+#         details = details or {}
+#         if retry_after:
+#             details["retry_after"] = retry_after
+#         super().__init__(message, code, http_status, details)
+#         self.retry_after = retry_after
+
+
+# class ServiceUnavailableError(ServerError):
+#     """
+#     Raised when the RecallrAI service is temporarily unavailable.
+#
+#     This exception is raised when the API is down for maintenance
+#     or experiencing issues.
+#     """
+
+#     def __init__(
+#         self, 
+#         message: str = "Service temporarily unavailable", 
+#         code: str = "service_unavailable",
+#         http_status: int = 503,
+#         retry_after: Optional[int] = None,
+#         details: Optional[Dict[str, Any]] = None
+#     ):
+#         details = details or {}
+#         if retry_after:
+#             details["retry_after"] = retry_after
+#         super().__init__(message, code, http_status, details)
+#         self.retry_after = retry_after

recallrai/exceptions/sessions.py

@@ -0,0 +1,60 @@
+"""
+Sessions-related exceptions for the RecallrAI SDK.
+"""
+
+from typing import Any, Dict, Optional
+from .base import RecallrAIError
+
+class SessionError(RecallrAIError):
+    """
+    Base class for session-related exceptions.
+    
+    This exception is raised for errors related to session management
+    in the RecallrAI API.
+    """
+
+    def __init__(
+        self, 
+        message: str = "Session error occurred", 
+        code: str = "session_error",
+        http_status: Optional[int] = None,
+        details: Optional[Dict[str, Any]] = None
+    ):
+        super().__init__(message, code, http_status, details)
+
+class InvalidSessionStateError(SessionError):
+    """
+    Raised when a session is in an invalid state.
+    
+    This exception is typically raised when trying to perform an action
+    on a session that is not in the expected state.
+    """
+
+    def __init__(
+        self, 
+        message: str = "Invalid session state", 
+        code: str = "invalid_session_state",
+        http_status: int = 400,
+        details: Optional[Dict[str, Any]] = None
+    ):
+        super().__init__(message, code, http_status, details)
+
+class SessionNotFoundError(SessionError):
+    """
+    Raised when a session is not found.
+    
+    This exception is typically raised when trying to access or modify
+    a session that doesn't exist.
+    """
+
+    def __init__(
+        self, 
+        session_id: Optional[str] = None,
+        message: Optional[str] = None,
+        code: str = "session_not_found",
+        http_status: int = 404,
+        details: Optional[Dict[str, Any]] = None
+    ):
+        message = message or f"Session{f' {session_id}' if session_id else ''} not found"
+        super().__init__(message, code, http_status, details)
+        self.session_id = session_id

recallrai/exceptions/users.py

@@ -0,0 +1,61 @@
+"""
+Users-related exceptions for the RecallrAI SDK.
+"""
+
+from typing import Any, Dict, Optional
+from .base import RecallrAIError
+
+class UserError(RecallrAIError):
+    """
+    Base class for user-related exceptions.
+    
+    This exception is raised for errors related to user management
+    in the RecallrAI API.
+    """
+
+    def __init__(
+        self, 
+        message: str = "User error occurred", 
+        code: str = "user_error",
+        http_status: Optional[int] = None,
+        details: Optional[Dict[str, Any]] = None
+    ):
+        super().__init__(message, code, http_status, details)
+
+class UserNotFoundError(UserError):
+    """
+    Raised when a user is not found.
+    
+    This exception is typically raised when trying to access or modify
+    a user that doesn't exist.
+    """
+    def __init__(
+        self, 
+        user_id: Optional[str] = None,
+        message: Optional[str] = None,
+        code: str = "user_not_found",
+        http_status: int = 404,
+        details: Optional[Dict[str, Any]] = None
+    ):
+        message = message or f"User{f' {user_id}' if user_id else ''} not found"
+        super().__init__(message, code, http_status, details)
+        self.user_id = user_id
+
+class UserAlreadyExistsError(UserError):
+    """
+    Raised when a user already exists.
+    
+    This exception is typically raised when trying to create a user
+    that already exists in the system.
+    """
+    def __init__(
+        self, 
+        user_id: Optional[str] = None,
+        message: Optional[str] = None,
+        code: str = "user_already_exists",
+        http_status: int = 409,
+        details: Optional[Dict[str, Any]] = None
+    ):
+        message = message or f"User{f' {user_id}' if user_id else ''} already exists"
+        super().__init__(message, code, http_status, details)
+        self.user_id = user_id

recallrai/exceptions/validation.py

@@ -0,0 +1,24 @@
+"""
+Validation-related exceptions for the RecallrAI SDK.
+"""
+
+from typing import Any, Dict, Optional, Union
+from .base import RecallrAIError
+
+
+class ValidationError(RecallrAIError):
+    """
+    Raised when request parameters fail validation.
+    
+    This exception is raised when the API rejects a request
+    due to invalid or missing parameters.
+    """
+
+    def __init__(
+        self, 
+        message: str = "Validation error", 
+        code: str = "validation_error",
+        http_status: int = 422,
+        details: Optional[Dict[str, Any]] = None
+    ):
+        super().__init__(message, code, http_status, details)

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"],
+        )