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

recallrai/merge_conflict.py

@@ -0,0 +1,189 @@
+"""
+Merge conflict management functionality for the RecallrAI SDK.
+"""
+
+from typing import List
+from .utils import HTTPClient
+from .models import (
+    MergeConflictModel,
+    MergeConflictStatus,
+    MergeConflictAnswer,
+)
+from .exceptions import (
+    UserNotFoundError,
+    MergeConflictNotFoundError,
+    MergeConflictAlreadyResolvedError,
+    MergeConflictInvalidQuestionsError,
+    MergeConflictMissingAnswersError,
+    MergeConflictInvalidAnswerError,
+    RecallrAIError
+)
+from logging import getLogger
+
+logger = getLogger(__name__)
+
+
+class MergeConflict:
+    """
+    Represents a merge conflict in the RecallrAI system.
+    
+    This class provides methods for inspecting and resolving merge conflicts
+    that occur when new memories conflict with existing ones.
+    """
+
+    def __init__(
+        self,
+        http_client: HTTPClient,
+        user_id: str,
+        conflict_data: MergeConflictModel,
+    ):
+        """
+        Initialize a merge conflict.
+
+        Args:
+            http_client: HTTP client for API communication.
+            user_id: User ID who owns this conflict.
+            conflict_data: Merge conflict data model.
+        """
+        self._http = http_client
+        self.user_id = user_id
+        self._conflict_data = conflict_data
+        
+        # Expose key properties for easy access
+        self.conflict_id = conflict_data.id
+        self.status = conflict_data.status
+        self.new_memory_content = conflict_data.new_memory_content
+        self.conflicting_memories = conflict_data.conflicting_memories
+        self.clarifying_questions = conflict_data.clarifying_questions
+        self.created_at = conflict_data.created_at
+        self.resolved_at = conflict_data.resolved_at
+        self.resolution_data = conflict_data.resolution_data
+
+    def resolve(self, answers: List[MergeConflictAnswer]) -> None:
+        """
+        Resolve this merge conflict by providing answers to clarifying questions.
+
+        Args:
+            answers: List of answers to the clarifying questions.
+
+        Raises:
+            UserNotFoundError: If the user is not found.
+            MergeConflictNotFoundError: If the merge conflict is not found.
+            MergeConflictAlreadyResolvedError: If the conflict is already resolved.
+            MergeConflictInvalidQuestionsError: If the provided questions don't match the original questions.
+            MergeConflictMissingAnswersError: If not all required questions have been answered.
+            MergeConflictInvalidAnswerError: If an answer is not a valid option for its question.
+            ValidationError: If the answers are invalid.
+            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.
+        """
+        if self.status in [MergeConflictStatus.RESOLVED, MergeConflictStatus.FAILED]:
+            raise MergeConflictAlreadyResolvedError(
+                message=f"Merge conflict {self.conflict_id} is already resolved",
+                http_status=400
+            )
+
+        # Convert answers to the format expected by the API
+        answer_data = {
+            "question_answers": [
+                {
+                    "question": answer.question,
+                    "answer": answer.answer,
+                    "message": answer.message,
+                }
+                for answer in answers
+            ]
+        }
+
+        response = self._http.post(
+            f"/api/v1/users/{self.user_id}/merge-conflicts/{self.conflict_id}/resolve",
+            data={"answers": answer_data},
+        )
+
+        if response.status_code == 404:
+            # Check if it's a user not found or conflict not found error
+            detail = response.json().get('detail', '')
+            if f"User {self.user_id} not found" in detail:
+                raise UserNotFoundError(message=detail, http_status=response.status_code)
+            else:
+                raise MergeConflictNotFoundError(message=detail, http_status=response.status_code)
+        elif response.status_code == 400:
+            detail = response.json().get('detail', '')
+            if "already resolved" in detail:
+                raise MergeConflictAlreadyResolvedError(message=detail, http_status=response.status_code)
+            elif "Invalid questions provided" in detail:
+                raise MergeConflictInvalidQuestionsError(
+                    message=detail,
+                    http_status=response.status_code
+                )
+            elif "Missing answers for the following questions" in detail:
+                raise MergeConflictMissingAnswersError(
+                    message=detail,
+                    http_status=response.status_code
+                )
+            elif "Invalid answer" in detail and "for question" in detail:
+                raise MergeConflictInvalidAnswerError(
+                    message=detail,
+                    http_status=response.status_code
+                )
+            else:
+                raise RecallrAIError(
+                    message=detail,
+                    http_status=response.status_code
+                )
+        elif response.status_code != 200:
+            raise RecallrAIError(
+                message=response.json().get('detail', 'Unknown error'),
+                http_status=response.status_code
+            )
+
+        # Update the conflict data with the response
+        updated_data = MergeConflictModel.from_api_response(response.json())
+        self._conflict_data = updated_data
+        self.status = updated_data.status
+        self.resolved_at = updated_data.resolved_at
+        self.resolution_data = updated_data.resolution_data
+
+    def refresh(self) -> None:
+        """
+        Refresh this merge conflict's data from the API.
+
+        Raises:
+            UserNotFoundError: If the user is not found.
+            MergeConflictNotFoundError: If the merge conflict 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}/merge-conflicts/{self.conflict_id}"
+        )
+
+        if response.status_code == 404:
+            # Check if it's a user not found or conflict not found error
+            detail = response.json().get('detail', '')
+            if f"User {self.user_id} not found" in detail:
+                raise UserNotFoundError(message=detail, http_status=response.status_code)
+            else:
+                raise MergeConflictNotFoundError(message=detail, http_status=response.status_code)
+        elif response.status_code != 200:
+            raise RecallrAIError(
+                message=response.json().get('detail', 'Unknown error'),
+                http_status=response.status_code
+            )
+
+        # Update with fresh data
+        updated_data = MergeConflictModel.from_api_response(response.json())
+        self._conflict_data = updated_data
+        self.status = updated_data.status
+        self.resolved_at = updated_data.resolved_at
+        self.resolution_data = updated_data.resolution_data
+
+    def __repr__(self) -> str:
+        """Return a string representation of the merge conflict."""
+        return f"MergeConflict(id='{self.conflict_id}', status='{self.status}', user_id='{self.user_id}')"

recallrai/models/__init__.py

@@ -1,16 +1,49 @@
 """
 Models used in the SDK.
 """
-from .session import Context, Message, MessageRole, SessionModel, SessionList, SessionStatus
-from .user import UserModel, UserList
+
+from .user import (
+    UserModel,
+    UserList,
+    UserMemoriesList,
+    UserMessage,
+    UserMessagesList,
+    UserMemoryItem,
+    MemoryVersionInfo,
+    MemoryRelationship,
+)
+from .session import SessionModel, SessionList, SessionMessagesList, MessageRole, SessionStatus, Context, RecallStrategy
+from .merge_conflict import (
+    MergeConflictModel, 
+    MergeConflictList, 
+    MergeConflictStatus,
+    MergeConflictMemory,
+    MergeConflictQuestion,
+    MergeConflictAnswer,
+)
 
 __all__ = [
-    "UserModel", 
+    "UserModel",
     "UserList",
+    "UserMemoriesList",
+    "UserMessage",
+    "UserMessagesList",
+    "UserMemoryItem",
+    "MemoryVersionInfo",
+    "MemoryRelationship",
+
     "SessionModel",
     "SessionList",
-    "SessionStatus",
-    "Message",
+    "SessionMessagesList",
     "MessageRole",
+    "SessionStatus",
     "Context",
+    "RecallStrategy",
+
+    "MergeConflictModel",
+    "MergeConflictList",
+    "MergeConflictStatus",
+    "MergeConflictMemory",
+    "MergeConflictQuestion",
+    "MergeConflictAnswer",
 ]

recallrai/models/merge_conflict.py

@@ -0,0 +1,151 @@
+"""
+Merge conflict-related data models for the RecallrAI SDK.
+"""
+
+import enum
+from datetime import datetime
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+from pydantic import BaseModel, Field
+from ..utils import HTTPClient
+
+if TYPE_CHECKING:
+    from ..merge_conflict import MergeConflict
+
+
+class MergeConflictStatus(str, enum.Enum):
+    """
+    Status of a merge conflict.
+    """
+    PENDING = "PENDING"
+    IN_QUEUE = "IN_QUEUE"
+    RESOLVING = "RESOLVING"
+    RESOLVED = "RESOLVED"
+    FAILED = "FAILED"
+
+
+class MergeConflictMemory(BaseModel):
+    """
+    Represents a memory involved in a merge conflict.
+    """
+    content: str = Field(..., description="Content of the conflicting memory.")
+    reason: str = Field(..., description="Reason why this memory conflicts.")
+
+    class Config:
+        """Pydantic configuration."""
+        frozen = True
+
+
+class MergeConflictQuestion(BaseModel):
+    """
+    Represents a clarifying question for merge conflict resolution.
+    """
+    question: str = Field(..., description="The clarifying question.")
+    options: List[str] = Field(..., description="Available answer options.")
+
+    class Config:
+        """Pydantic configuration."""
+        frozen = True
+
+
+class MergeConflictAnswer(BaseModel):
+    """
+    Represents an answer to a clarifying question.
+    """
+    question: str = Field(..., description="The question being answered.")
+    answer: str = Field(..., description="The selected answer.")
+    message: Optional[str] = Field(None, description="Optional additional message.")
+
+    class Config:
+        """Pydantic configuration."""
+        frozen = True
+
+
+class MergeConflictModel(BaseModel):
+    """
+    Represents a merge conflict in the RecallrAI system.
+    """
+    id: str = Field(..., description="Unique identifier for the merge conflict.")
+    custom_user_id: str = Field(..., description="User ID who owns this conflict.")
+    project_user_session_id: str = Field(..., description="Session ID where the conflict occurred.")
+    new_memory_content: str = Field(..., description="New memory content that caused the conflict.")
+    conflicting_memories: List[MergeConflictMemory] = Field(..., description="Existing memories that conflict.")
+    clarifying_questions: List[MergeConflictQuestion] = Field(..., description="Questions to resolve the conflict.")
+    status: MergeConflictStatus = Field(..., description="Current status of the conflict.")
+    resolution_data: Optional[Dict[str, Any]] = Field(None, description="Resolution data if resolved.")
+    created_at: datetime = Field(..., description="When the conflict was created.")
+    resolved_at: Optional[datetime] = Field(None, description="When the conflict was resolved.")
+
+    class Config:
+        """Pydantic configuration."""
+        frozen = True
+        json_encoders = {
+            datetime: lambda dt: dt.isoformat()
+        }
+
+    @classmethod
+    def from_api_response(cls, data: Dict[str, Any]) -> "MergeConflictModel":
+        """
+        Create a MergeConflictModel instance from an API response.
+
+        Args:
+            data: API response data.
+
+        Returns:
+            A MergeConflictModel instance.
+        """
+        conflict_data = data.get("conflict", data)
+        
+        return cls(
+            id=conflict_data["id"],
+            custom_user_id=conflict_data["custom_user_id"],
+            project_user_session_id=conflict_data["project_user_session_id"],
+            new_memory_content=conflict_data["new_memory_content"],
+            conflicting_memories=[
+                MergeConflictMemory(**memory) for memory in conflict_data["conflicting_memories"]
+            ],
+            clarifying_questions=[
+                MergeConflictQuestion(**question) for question in conflict_data["clarifying_questions"]
+            ],
+            status=MergeConflictStatus(conflict_data["status"]),
+            resolution_data=conflict_data.get("resolution_data"),
+            created_at=conflict_data["created_at"],
+            resolved_at=conflict_data.get("resolved_at"),
+        )
+
+
+class MergeConflictList(BaseModel):
+    """
+    Represents a paginated list of merge conflicts.
+    """
+    conflicts: List["MergeConflict"] = Field(..., description="List of merge conflicts.")
+    total: int = Field(..., description="Total number of conflicts.")
+    has_more: bool = Field(..., description="Whether there are more conflicts to fetch.")
+
+    class Config:
+        """Pydantic configuration."""
+        frozen = True
+        arbitrary_types_allowed = True
+
+    @classmethod
+    def from_api_response(cls, data: Dict[str, Any], http_client: HTTPClient, user_id: str) -> "MergeConflictList":
+        """
+        Create a MergeConflictList instance from an API response.
+
+        Args:
+            data: API response data.
+            http_client: HTTP client for making API requests.
+            user_id: User ID who owns these conflicts.
+
+        Returns:
+            A MergeConflictList instance.
+        """
+        from ..merge_conflict import MergeConflict
+        
+        return cls(
+            conflicts=[
+                MergeConflict(http_client, user_id, MergeConflictModel.from_api_response(conflict))
+                for conflict in data["conflicts"]
+            ],
+            total=data["total"],
+            has_more=data["has_more"],
+        )

recallrai/models/session.py

@@ -2,12 +2,13 @@
 Session-related data models for the RecallrAI SDK.
 """
 
-import enum, uuid
+import enum
 from datetime import datetime
-from typing import Any, Dict, List
-
+from typing import TYPE_CHECKING, Any, Dict, List
 from pydantic import BaseModel, Field
-
+from ..utils import HTTPClient
+if TYPE_CHECKING:
+    from ..session import Session
 
 class MessageRole(str, enum.Enum):
     """
@@ -21,9 +22,9 @@ 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")
+    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."""
@@ -33,6 +34,27 @@ class Message(BaseModel):
         }
 
 
+class SessionMessagesList(BaseModel):
+    """
+    Represents a paginated list of messages in a session.
+    """
+
+    messages: List[Message] = Field(..., description="List of messages in the page.")
+    total: int = Field(..., description="Total number of messages in the session.")
+    has_more: bool = Field(..., description="Whether there are more messages to fetch.")
+
+    class Config:
+        frozen = True
+
+    @classmethod
+    def from_api_response(cls, data: Dict[str, Any]) -> "SessionMessagesList":
+        return cls(
+            messages=[Message(**msg) for msg in data["messages"]],
+            total=data["total"],
+            has_more=data["has_more"],
+        )
+
+
 class SessionStatus(str, enum.Enum):
     """
     Status of a session.
@@ -46,16 +68,16 @@ class SessionModel(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")
+    session_id: str = 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.")
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Optional metadata for the session.")
 
     class Config:
         """Pydantic configuration."""
         frozen = True
         json_encoders = {
             datetime: lambda dt: dt.isoformat(),
-            uuid.UUID: lambda id: str(id)
         }
 
     @classmethod
@@ -64,15 +86,20 @@ class SessionModel(BaseModel):
         Create a SessionModel instance from an API response.
 
         Args:
-            data: API response data
+            data: API response data.
 
         Returns:
-            A SessionModel instance
+            A SessionModel instance.
         """
+        if "session" in data:
+            session_data = data["session"]
+        else:
+            session_data = data
         return cls(
-            session_id=data["session_id"],
-            status=data.get("status", SessionStatus.PENDING),
-            created_at=data.get("created_at", datetime.now()),
+            session_id=session_data["session_id"],
+            status=session_data["status"],
+            created_at=session_data["created_at"],
+            metadata=session_data["metadata"],
         )
 
 
@@ -80,38 +107,48 @@ class SessionList(BaseModel):
     """
     Represents a paginated list of sessions.
     """
-    sessions: List[SessionModel] = 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")
+    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
+        arbitrary_types_allowed = True
 
     @classmethod
-    def from_api_response(cls, data: Dict[str, Any]) -> "SessionList":
+    def from_api_response(cls, data: Dict[str, Any], user_id: str, http_client: HTTPClient) -> "SessionList":
         """
         Create a SessionList instance from an API response.
 
         Args:
-            data: API response data
+            data: API response data.
 
         Returns:
-            A SessionList instance
+            A SessionList instance.
         """
+        from ..session import Session
         return cls(
-            sessions=[SessionModel.from_api_response(session) for session in data["sessions"]],
+            sessions=[
+                Session(http_client, user_id, SessionModel.from_api_response(session)) for session in data["sessions"]
+            ],
             total=data["total"],
             has_more=data["has_more"],
         )
 
+class RecallStrategy(str, enum.Enum):
+    """
+    Type of recall strategy.
+    """
+    LOW_LATENCY = "low_latency"
+    BALANCED = "balanced"
+    DEEP = "deep"
 
 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")
+    context: str = Field(..., description="The context for the session.")
 
     class Config:
         """Pydantic configuration."""
@@ -123,12 +160,11 @@ class Context(BaseModel):
         Create a Context instance from an API response.
 
         Args:
-            data: API response data
+            data: API response data.
 
         Returns:
-            A Context instance
+            A Context instance.
         """
         return cls(
-            memory_used=data["memory_used"],
             context=data["context"],
         )