solace-agent-mesh 1.6.3__py3-none-any.whl → 1.7.1__py3-none-any.whl

solace_agent_mesh/gateway/http_sse/repository/entities/entities_llm.txt

@@ -1,29 +1,74 @@
 # DEVELOPER GUIDE: entities
 
 ## Quick Summary
-The entities directory contains domain entities for the repository layer, providing core business objects for managing chat sessions, messages, tasks, feedback, and events with built-in validation and business logic.
+The entities directory contains domain entities for the repository layer, providing core business objects for managing chat sessions, tasks, feedback, and events with built-in validation and business logic.
 
 ## Files Overview
-- `__init__.py` - Exports the main domain entities (Feedback, Message, Session, SessionHistory, Task, TaskEvent)
+- `__init__.py` - Exports the main domain entities (ChatTask, Feedback, Session, Task, TaskEvent)
+- `chat_task.py` - ChatTask entity for managing chat conversations with JSON validation
 - `feedback.py` - Feedback entity for user ratings and comments on tasks
-- `message.py` - Message entity with content validation and sender type checking
 - `session.py` - Session entity with name management and access control
-- `session_history.py` - Composite entity combining sessions with their message history
-- `task.py` - Task entity for tracking user tasks and their status with token usage
-- `task_event.py` - Task event entity for tracking events related to tasks
+- `task.py` - Task entity for tracking user tasks with token usage metrics
+- `task_event.py` - TaskEvent entity for tracking events related to tasks
 
 ## Developer API Reference
 
 ### __init__.py
 **Purpose:** Provides centralized imports for all domain entities
-**Import:** `from solace_agent_mesh.gateway.http_sse.repository.entities import Feedback, Message, Session, SessionHistory, Task, TaskEvent`
+**Import:** `from solace_agent_mesh.gateway.http_sse.repository.entities import ChatTask, Feedback, Session, Task, TaskEvent`
+
+### chat_task.py
+**Purpose:** Defines the ChatTask domain entity for managing chat conversations with JSON validation
+**Import:** `from solace_agent_mesh.gateway.http_sse.repository.entities import ChatTask`
+
+**Classes:**
+- `ChatTask(id: str, session_id: str, user_id: str, message_bubbles: str, created_time: int, user_message: str | None = None, task_metadata: str | None = None, updated_time: int | None = None)` - ChatTask domain entity with business logic
+  - `add_feedback(feedback_type: str, feedback_text: str | None = None) -> None` - Add or update feedback for this task
+  - `get_feedback() -> dict[str, Any] | None` - Get feedback for this task
+  - `id: str` - Unique task identifier
+  - `session_id: str` - Associated session identifier
+  - `user_id: str` - User who owns the task
+  - `user_message: str | None` - Optional user message
+  - `message_bubbles: str` - JSON string containing message bubbles (must be non-empty JSON array)
+  - `task_metadata: str | None` - Optional JSON string for task metadata
+  - `created_time: int` - Task creation timestamp
+  - `updated_time: int | None` - Last update timestamp
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.repository.entities import ChatTask
+import json
+
+# Create a chat task
+message_bubbles = json.dumps([
+    {"type": "user", "content": "Hello"},
+    {"type": "agent", "content": "Hi there!"}
+])
+
+chat_task = ChatTask(
+    id="chat_123",
+    session_id="session_456",
+    user_id="user_789",
+    user_message="Hello",
+    message_bubbles=message_bubbles,
+    created_time=1640995200000
+)
+
+# Add feedback
+chat_task.add_feedback("positive", "Great response!")
+
+# Get feedback
+feedback = chat_task.get_feedback()
+if feedback:
+    print(f"Feedback type: {feedback['type']}")
+```
 
 ### feedback.py
 **Purpose:** Defines the Feedback domain entity for user ratings and comments
 **Import:** `from solace_agent_mesh.gateway.http_sse.repository.entities import Feedback`
 
 **Classes:**
-- `Feedback(id: str, session_id: str, task_id: str, user_id: str, rating: str, comment: str | None = None, created_time: int)` - Feedback domain entity
+- `Feedback(id: str, session_id: str, task_id: str, user_id: str, rating: str, created_time: int, comment: str | None = None)` - Feedback domain entity
   - `id: str` - Unique feedback identifier
   - `session_id: str` - Associated session identifier
   - `task_id: str` - Associated task identifier
@@ -48,54 +93,12 @@ feedback = Feedback(
 )
 ```
 
-### message.py
-**Purpose:** Defines the Message domain entity with business logic for chat messages
-**Import:** `from solace_agent_mesh.gateway.http_sse.repository.entities import Message`
-
-**Classes:**
-- `Message(id: MessageId, session_id: SessionId, message: str, sender_type: SenderType, sender_name: str, message_type: MessageType = MessageType.TEXT, created_time: int)` - Message domain entity with business logic
-  - `validate_message_content() -> None` - Validates message content is not empty and under 10MB limit
-  - `is_from_user() -> bool` - Checks if message is from a user
-  - `is_from_agent() -> bool` - Checks if message is from an agent
-  - `is_system_message() -> bool` - Checks if message is a system message
-  - `id: MessageId` - Unique message identifier
-  - `session_id: SessionId` - Associated session identifier
-  - `message: str` - Message content
-  - `sender_type: SenderType` - Type of sender (USER, AGENT, SYSTEM)
-  - `sender_name: str` - Name of the message sender
-  - `message_type: MessageType` - Type of message content
-  - `created_time: int` - Message creation timestamp
-
-**Usage Examples:**
-```python
-from solace_agent_mesh.gateway.http_sse.repository.entities import Message
-from solace_agent_mesh.gateway.http_sse.shared.enums import SenderType, MessageType
-
-# Create a user message
-message = Message(
-    id="msg_123",
-    session_id="session_456",
-    message="Hello, how can I help?",
-    sender_type=SenderType.USER,
-    sender_name="John Doe",
-    message_type=MessageType.TEXT,
-    created_time=1640995200000
-)
-
-# Validate message content
-message.validate_message_content()
-
-# Check sender type
-if message.is_from_user():
-    print("Message from user")
-```
-
 ### session.py
 **Purpose:** Defines the Session domain entity with business logic for chat sessions
 **Import:** `from solace_agent_mesh.gateway.http_sse.repository.entities import Session`
 
 **Classes:**
-- `Session(id: SessionId, user_id: UserId, name: str | None = None, agent_id: AgentId | None = None, created_time: int, updated_time: int | None = None)` - Session domain entity with business logic
+- `Session(id: SessionId, user_id: UserId, created_time: int, name: str | None = None, agent_id: AgentId | None = None, updated_time: int | None = None)` - Session domain entity with business logic
   - `update_name(new_name: str) -> None` - Updates session name with validation and sets updated_time
   - `mark_activity() -> None` - Marks session as having recent activity by updating timestamp
   - `can_be_deleted_by_user(user_id: UserId) -> bool` - Checks if user can delete this session
@@ -131,51 +134,6 @@ if session.can_be_accessed_by_user("user_456"):
     print("User can access this session")
 ```
 
-### session_history.py
-**Purpose:** Defines a composite entity that combines a session with its message history
-**Import:** `from solace_agent_mesh.gateway.http_sse.repository.entities import SessionHistory`
-
-**Classes:**
-- `SessionHistory(session: Session, messages: list[Message] = [], total_message_count: int = 0)` - Composite entity representing a session with its messages
-  - `session: Session` - The session entity
-  - `messages: list[Message]` - List of messages in the session
-  - `total_message_count: int` - Total count of messages (may exceed messages list length for pagination)
-
-**Usage Examples:**
-```python
-from solace_agent_mesh.gateway.http_sse.repository.entities import SessionHistory, Session, Message
-from solace_agent_mesh.gateway.http_sse.shared.enums import SenderType
-
-# Create session history
-session = Session(
-    id="session_123",
-    user_id="user_456",
-    created_time=1640995200000
-)
-
-messages = [
-    Message(
-        id="msg_1",
-        session_id="session_123",
-        message="Hello",
-        sender_type=SenderType.USER,
-        sender_name="John",
-        created_time=1640995200000
-    )
-]
-
-history = SessionHistory(
-    session=session,
-    messages=messages,
-    total_message_count=1
-)
-
-# Access session and messages
-print(f"Session: {history.session.id}")
-print(f"Message count: {len(history.messages)}")
-print(f"Total messages: {history.total_message_count}")
-```
-
 ### task.py
 **Purpose:** Defines the Task domain entity for tracking user tasks with token usage metrics
 **Import:** `from solace_agent_mesh.gateway.http_sse.repository.entities import Task`
@@ -225,7 +183,7 @@ task_with_tokens = Task(
 **Import:** `from solace_agent_mesh.gateway.http_sse.repository.entities import TaskEvent`
 
 **Classes:**
-- `TaskEvent(id: str, task_id: str, user_id: str | None = None, created_time: int, topic: str, direction: str, payload: dict[str, Any])` - TaskEvent domain entity
+- `TaskEvent(id: str, task_id: str, created_time: int, topic: str, direction: str, payload: dict[str, Any], user_id: str | None = None)` - TaskEvent domain entity
   - `id: str` - Unique event identifier
   - `task_id: str` - Associated task identifier
   - `user_id: str | None` - Optional user identifier
@@ -260,4 +218,4 @@ system_event = TaskEvent(
 )
 ```
 
-# content_hash: 14f978bcbf2c820db1c7f3185ffa1529a656b3b5fa0f64cff81927eb2f7d12e9
+# content_hash: d7b07fd8577e43715a286030d4119267ddff5483180284a16dc6d8aab19fd089

solace_agent_mesh/gateway/http_sse/repository/entities/project.py

@@ -0,0 +1,81 @@
+"""
+Project domain entity.
+"""
+
+from typing import Optional
+from pydantic import BaseModel, Field
+
+from ...shared import now_epoch_ms
+
+
+class Project(BaseModel):
+    """Project domain entity with business logic."""
+    
+    id: str
+    name: str = Field(..., min_length=1, max_length=255)
+    user_id: str
+    description: Optional[str] = Field(None, max_length=1000)
+    system_prompt: Optional[str] = Field(None, max_length=4000)
+    default_agent_id: Optional[str] = None
+    created_at: int
+    updated_at: Optional[int] = None
+    deleted_at: Optional[int] = None
+    deleted_by: Optional[str] = None
+    
+    def update_name(self, new_name: str) -> None:
+        """Update project name with validation."""
+        if not new_name or len(new_name.strip()) == 0:
+            raise ValueError("Project name cannot be empty")
+        if len(new_name) > 255:
+            raise ValueError("Project name cannot exceed 255 characters")
+        
+        self.name = new_name.strip()
+        self.updated_at = now_epoch_ms()
+    
+    def update_description(self, new_description: Optional[str]) -> None:
+        """Update project description with validation."""
+        if new_description is not None:
+            if len(new_description) > 1000:
+                raise ValueError("Project description cannot exceed 1000 characters")
+            self.description = new_description.strip() if new_description else None
+        else:
+            self.description = None
+        
+        self.updated_at = now_epoch_ms()
+    
+    def update_default_agent(self, agent_id: Optional[str]) -> None:
+        """Update project default agent."""
+        self.default_agent_id = agent_id
+        self.updated_at = now_epoch_ms()
+    
+    def soft_delete(self, user_id: str) -> None:
+        """Soft delete the project."""
+        if not self.can_be_deleted_by_user(user_id):
+            raise ValueError("User does not have permission to delete this project")
+        
+        self.deleted_at = now_epoch_ms()
+        self.deleted_by = user_id
+        self.updated_at = now_epoch_ms()
+    
+    def is_deleted(self) -> bool:
+        """Check if project is soft deleted."""
+        return self.deleted_at is not None
+    
+    def can_be_accessed_by_user(self, user_id: str) -> bool:
+        """Check if project can be accessed by the given user."""
+        # User projects are only accessible by their owner and not deleted
+        return self.user_id == user_id and not self.is_deleted()
+    
+    def can_be_edited_by_user(self, user_id: str) -> bool:
+        """Check if project can be edited by the given user."""
+        # Users can only edit their own projects that are not deleted
+        return self.user_id == user_id and not self.is_deleted()
+    
+    def can_be_deleted_by_user(self, user_id: str) -> bool:
+        """Check if project can be deleted by the given user."""
+        # Users can only delete their own projects that are not already deleted
+        return self.user_id == user_id and not self.is_deleted()
+    
+    def mark_as_updated(self) -> None:
+        """Mark project as updated."""
+        self.updated_at = now_epoch_ms()

solace_agent_mesh/gateway/http_sse/repository/entities/project_user.py

@@ -0,0 +1,47 @@
+"""
+Project user access domain entity.
+"""
+
+from typing import Optional
+from pydantic import BaseModel, Field
+
+from ...shared import now_epoch_ms
+
+
+class ProjectUser(BaseModel):
+    """
+    Project user access domain entity.
+    
+    Represents a user's access to a project with a specific role.
+    """
+    
+    id: str
+    project_id: str
+    user_id: str
+    role: str = Field(..., pattern="^(owner|editor|viewer)$") 
+    added_at: int
+    added_by_user_id: str
+    
+    def can_edit_project(self) -> bool:
+        """Check if this user can edit the project based on their role."""
+        return self.role in ["owner", "editor"]
+    
+    def can_manage_users(self) -> bool:
+        """Check if this user can manage other users' access to the project."""
+        return self.role == "owner"
+    
+    def can_view_project(self) -> bool:
+        """Check if this user can view the project."""
+        return self.role in ["owner", "editor", "viewer"]
+    
+    def update_role(self, new_role: str) -> None:
+        """Update the user's role with validation."""
+        valid_roles = ["owner", "editor", "viewer"]
+        if new_role not in valid_roles:
+            raise ValueError(f"Invalid role. Must be one of: {', '.join(valid_roles)}")
+        
+        self.role = new_role
+    
+    class Config:
+        """Pydantic configuration."""
+        frozen = False  

solace_agent_mesh/gateway/http_sse/repository/entities/session.py

@@ -17,8 +17,12 @@ class Session(BaseModel):
     user_id: UserId
     name: str | None = None
     agent_id: AgentId | None = None
+    project_id: str | None = None
+    project_name: str | None = None
     created_time: int
     updated_time: int | None = None
+    deleted_at: int | None = None
+    deleted_by: str | None = None
 
     def update_name(self, new_name: str) -> None:
         """Update session name with validation."""
@@ -34,10 +38,28 @@ class Session(BaseModel):
         """Mark session as having recent activity."""
         self.updated_time = now_epoch_ms()
 
+    def soft_delete(self, user_id: UserId) -> None:
+        """Soft delete the session."""
+        if not self.can_be_deleted_by_user(user_id):
+            raise ValueError("User does not have permission to delete this session")
+        
+        self.deleted_at = now_epoch_ms()
+        self.deleted_by = user_id
+        self.updated_time = now_epoch_ms()
+
+    def is_deleted(self) -> bool:
+        """Check if session is soft deleted."""
+        return self.deleted_at is not None
+
+    def move_to_project(self, new_project_id: str | None) -> None:
+        """Move session to a different project."""
+        self.project_id = new_project_id
+        self.updated_time = now_epoch_ms()
+
     def can_be_deleted_by_user(self, user_id: UserId) -> bool:
         """Check if user can delete this session."""
         return self.user_id == user_id
 
     def can_be_accessed_by_user(self, user_id: UserId) -> bool:
         """Check if user can access this session."""
-        return self.user_id == user_id
+        return self.user_id == user_id and not self.is_deleted()

solace_agent_mesh/gateway/http_sse/repository/feedback_repository.py

@@ -4,6 +4,8 @@ Feedback repository implementation using SQLAlchemy.
 
 from sqlalchemy.orm import Session as DBSession
 
+from ..shared.pagination import PaginationParams
+from ..shared.types import UserId
 from .entities import Feedback
 from .interfaces import IFeedbackRepository
 from .models import FeedbackModel
@@ -28,6 +30,51 @@ class FeedbackRepository(IFeedbackRepository):
         session.refresh(model)
         return self._model_to_entity(model)
 
+    def search(
+        self,
+        session: DBSession,
+        user_id: UserId,
+        start_date: int | None = None,
+        end_date: int | None = None,
+        task_id: str | None = None,
+        session_id: str | None = None,
+        rating: str | None = None,
+        pagination: PaginationParams | None = None,
+    ) -> list[Feedback]:
+        """
+        Search feedback with flexible filtering.
+        All filters are optional and can be combined.
+        """
+        query = session.query(FeedbackModel)
+
+        # User filter (unless admin querying all users)
+        if user_id != "*":
+            query = query.filter(FeedbackModel.user_id == user_id)
+
+        # Time-based filters
+        if start_date:
+            query = query.filter(FeedbackModel.created_time >= start_date)
+        if end_date:
+            query = query.filter(FeedbackModel.created_time <= end_date)
+
+        # Resource-based filters
+        if task_id:
+            query = query.filter(FeedbackModel.task_id == task_id)
+        if session_id:
+            query = query.filter(FeedbackModel.session_id == session_id)
+        if rating:
+            query = query.filter(FeedbackModel.rating == rating)
+
+        # Order by most recent first
+        query = query.order_by(FeedbackModel.created_time.desc())
+
+        # Apply pagination
+        if pagination:
+            query = query.offset(pagination.offset).limit(pagination.page_size)
+
+        models = query.all()
+        return [self._model_to_entity(model) for model in models]
+
     def delete_feedback_older_than(self, session: DBSession, cutoff_time_ms: int, batch_size: int) -> int:
         """
         Delete feedback records older than the cutoff time.

solace_agent_mesh/gateway/http_sse/repository/interfaces.py

@@ -9,6 +9,8 @@ from sqlalchemy.orm import Session as DBSession
 from ..shared.pagination import PaginationParams
 from ..shared.types import SessionId, UserId
 from .entities import Feedback, Session, Task, TaskEvent
+from .entities.project import Project
+from ..routers.dto.requests.project_requests import ProjectFilter
 
 if TYPE_CHECKING:
     from .entities import ChatTask
@@ -19,14 +21,14 @@ class ISessionRepository(ABC):
 
     @abstractmethod
     def find_by_user(
-        self, session: DBSession, user_id: UserId, pagination: PaginationParams | None = None
+        self, session: DBSession, user_id: UserId, pagination: PaginationParams | None = None, project_id: str | None = None
     ) -> list[Session]:
-        """Find all sessions for a specific user."""
+        """Find all sessions for a specific user, optionally filtered by project."""
         pass
 
     @abstractmethod
-    def count_by_user(self, session: DBSession, user_id: UserId) -> int:
-        """Count total sessions for a specific user."""
+    def count_by_user(self, session: DBSession, user_id: UserId, project_id: str | None = None) -> int:
+        """Count total sessions for a specific user, optionally filtered by project."""
         pass
 
     @abstractmethod
@@ -46,6 +48,41 @@ class ISessionRepository(ABC):
         """Delete a session belonging to a user."""
         pass
 
+    @abstractmethod
+    def soft_delete(self, session: DBSession, session_id: SessionId, user_id: UserId) -> bool:
+        """Soft delete a session belonging to a user."""
+        pass
+
+    @abstractmethod
+    def move_to_project(
+        self, session: DBSession, session_id: SessionId, user_id: UserId, new_project_id: str | None
+    ) -> Session | None:
+        """Move a session to a different project."""
+        pass
+
+    @abstractmethod
+    def search(
+        self,
+        session: DBSession,
+        user_id: UserId,
+        query: str,
+        pagination: PaginationParams | None = None,
+        project_id: str | None = None
+    ) -> list[Session]:
+        """Search sessions by name or content."""
+        pass
+
+    @abstractmethod
+    def count_search_results(
+        self,
+        session: DBSession,
+        user_id: UserId,
+        query: str,
+        project_id: str | None = None
+    ) -> int:
+        """Count search results for pagination."""
+        pass
+
 
 class ITaskRepository(ABC):
     """Interface for task data access operations."""
@@ -99,6 +136,37 @@ class IFeedbackRepository(ABC):
         """Save feedback."""
         pass
 
+    @abstractmethod
+    def search(
+        self,
+        session: DBSession,
+        user_id: UserId,
+        start_date: int | None = None,
+        end_date: int | None = None,
+        task_id: str | None = None,
+        session_id: str | None = None,
+        rating: str | None = None,
+        pagination: PaginationParams | None = None,
+    ) -> list[Feedback]:
+        """
+        Search feedback with flexible filtering.
+        All filters are optional and can be combined.
+
+        Args:
+            session: Database session
+            user_id: User ID to filter by, or "*" for all users (admin)
+            start_date: Start of date range in epoch milliseconds
+            end_date: End of date range in epoch milliseconds
+            task_id: Filter by specific task ID
+            session_id: Filter by specific session ID
+            rating: Filter by rating type ("up" or "down")
+            pagination: Pagination parameters
+
+        Returns:
+            List of feedback entries matching the filters
+        """
+        pass
+
     @abstractmethod
     def delete_feedback_older_than(self, session: DBSession, cutoff_time_ms: int, batch_size: int) -> int:
         """Delete feedback older than cutoff time using batch deletion."""
@@ -129,3 +197,43 @@ class IChatTaskRepository(ABC):
     def delete_by_session(self, session: DBSession, session_id: SessionId) -> bool:
         """Delete all tasks for a session."""
         pass
+
+
+class IProjectRepository(ABC):
+    """Interface for project repository operations."""
+
+    @abstractmethod
+    def create_project(self, name: str, user_id: str, description: Optional[str] = None,
+                      system_prompt: Optional[str] = None) -> Project:
+        """Create a new user project."""
+        pass
+
+    @abstractmethod
+    def get_user_projects(self, user_id: str) -> list[Project]:
+        """Get all projects owned by a specific user."""
+        pass
+
+    @abstractmethod
+    def get_filtered_projects(self, project_filter: ProjectFilter) -> list[Project]:
+        """Get projects based on filter criteria."""
+        pass
+
+    @abstractmethod
+    def get_by_id(self, project_id: str, user_id: str) -> Optional[Project]:
+        """Get a project by its ID, ensuring user access."""
+        pass
+
+    @abstractmethod
+    def update(self, project_id: str, user_id: str, update_data: dict) -> Optional[Project]:
+        """Update a project with the given data, ensuring user access."""
+        pass
+
+    @abstractmethod
+    def delete(self, project_id: str, user_id: str) -> bool:
+        """Delete a project by its ID, ensuring user access."""
+        pass
+
+    @abstractmethod
+    def soft_delete(self, project_id: str, user_id: str) -> bool:
+        """Soft delete a project by its ID, ensuring user access."""
+        pass

solace_agent_mesh/gateway/http_sse/repository/models/__init__.py

@@ -5,6 +5,8 @@ SQLAlchemy models and Pydantic models for database persistence.
 from .base import Base
 from .chat_task_model import ChatTaskModel
 from .feedback_model import FeedbackModel
+from .project_model import ProjectModel, CreateProjectModel, UpdateProjectModel
+from .project_user_model import ProjectUserModel, CreateProjectUserModel, UpdateProjectUserModel
 from .session_model import SessionModel, CreateSessionModel, UpdateSessionModel
 from .task_event_model import TaskEventModel
 from .task_model import TaskModel
@@ -12,10 +14,16 @@ from .task_model import TaskModel
 __all__ = [
     "Base",
     "ChatTaskModel",
+    "FeedbackModel",
+    "ProjectModel",
+    "ProjectUserModel",
     "SessionModel",
+    "CreateProjectModel",
+    "UpdateProjectModel",
+    "CreateProjectUserModel",
+    "UpdateProjectUserModel",
     "CreateSessionModel",
     "UpdateSessionModel",
     "TaskEventModel",
     "TaskModel",
-    "FeedbackModel",
 ]