solace-agent-mesh 1.11.2__py3-none-any.whl

solace_agent_mesh/gateway/http_sse/repository/__init__.py

@@ -0,0 +1,46 @@
+"""
+Repository layer containing all data access logic organized by entity type.
+"""
+
+# Interfaces
+from .interfaces import (
+    IChatTaskRepository,
+    IFeedbackRepository,
+    IProjectRepository,
+    ISessionRepository,
+    ITaskRepository,
+)
+
+# Implementations
+from .chat_task_repository import ChatTaskRepository
+from .feedback_repository import FeedbackRepository
+from .project_repository import ProjectRepository
+from .session_repository import SessionRepository
+from .task_repository import TaskRepository
+
+# Entities (re-exported for convenience)
+from .entities.session import Session
+
+# Models (re-exported for convenience)
+from .models.base import Base
+from .models.session_model import SessionModel
+
+__all__ = [
+    # Interfaces
+    "IChatTaskRepository",
+    "IFeedbackRepository",
+    "IProjectRepository",
+    "ISessionRepository",
+    "ITaskRepository",
+    # Implementations
+    "ChatTaskRepository",
+    "FeedbackRepository",
+    "ProjectRepository",
+    "SessionRepository",
+    "TaskRepository",
+    # Entities
+    "Session",
+    # Models
+    "Base",
+    "SessionModel",
+]

solace_agent_mesh/gateway/http_sse/repository/chat_task_repository.py

@@ -0,0 +1,102 @@
+"""
+ChatTask repository implementation using SQLAlchemy.
+"""
+
+from typing import List, Optional
+
+from sqlalchemy.orm import Session as DBSession
+
+from ..shared import now_epoch_ms
+from ..shared.types import SessionId, UserId
+from .entities import ChatTask
+from .interfaces import IChatTaskRepository
+from .models import ChatTaskModel
+
+
+class ChatTaskRepository(IChatTaskRepository):
+    """SQLAlchemy implementation of chat task repository."""
+
+    def save(self, session: DBSession, task: ChatTask) -> ChatTask:
+        """Save or update a chat task (upsert)."""
+        existing = session.query(ChatTaskModel).filter(
+            ChatTaskModel.id == task.id
+        ).first()
+
+        if existing:
+            # Update existing task - store strings directly
+            existing.user_message = task.user_message
+            existing.message_bubbles = task.message_bubbles  # Already a string
+            existing.task_metadata = task.task_metadata      # Already a string
+            existing.updated_time = now_epoch_ms()
+        else:
+            # Create new task - store strings directly
+            model = ChatTaskModel(
+                id=task.id,
+                session_id=task.session_id,
+                user_id=task.user_id,
+                user_message=task.user_message,
+                message_bubbles=task.message_bubbles,  # Already a string
+                task_metadata=task.task_metadata,      # Already a string
+                created_time=task.created_time,
+                updated_time=task.updated_time
+            )
+            session.add(model)
+
+        session.flush()
+
+        # Reload to get updated values
+        model = session.query(ChatTaskModel).filter(
+            ChatTaskModel.id == task.id
+        ).first()
+
+        return self._model_to_entity(model)
+
+    def find_by_session(
+        self,
+        session: DBSession,
+        session_id: SessionId,
+        user_id: UserId
+    ) -> List[ChatTask]:
+        """Find all tasks for a session."""
+        models = session.query(ChatTaskModel).filter(
+            ChatTaskModel.session_id == session_id,
+            ChatTaskModel.user_id == user_id
+        ).order_by(ChatTaskModel.created_time.asc()).all()
+
+        return [self._model_to_entity(m) for m in models]
+
+    def find_by_id(
+        self,
+        session: DBSession,
+        task_id: str,
+        user_id: UserId
+    ) -> Optional[ChatTask]:
+        """Find a specific task."""
+        model = session.query(ChatTaskModel).filter(
+            ChatTaskModel.id == task_id,
+            ChatTaskModel.user_id == user_id
+        ).first()
+
+        return self._model_to_entity(model) if model else None
+
+    def delete_by_session(self, session: DBSession, session_id: SessionId) -> bool:
+        """Delete all tasks for a session."""
+        result = session.query(ChatTaskModel).filter(
+            ChatTaskModel.session_id == session_id
+        ).delete()
+        session.flush()
+        return result > 0
+
+    def _model_to_entity(self, model: ChatTaskModel) -> ChatTask:
+        """Convert SQLAlchemy model to domain entity."""
+        # No deserialization - just pass strings through
+        return ChatTask(
+            id=model.id,
+            session_id=model.session_id,
+            user_id=model.user_id,
+            user_message=model.user_message,
+            message_bubbles=model.message_bubbles,  # String (opaque)
+            task_metadata=model.task_metadata,      # String (opaque)
+            created_time=model.created_time,
+            updated_time=model.updated_time
+        )

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

@@ -0,0 +1,11 @@
+"""
+Domain entities for the repository layer.
+"""
+
+from .chat_task import ChatTask
+from .feedback import Feedback
+from .session import Session
+from .task import Task
+from .task_event import TaskEvent
+
+__all__ = ["ChatTask", "Feedback", "Session", "Task", "TaskEvent"]

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

@@ -0,0 +1,75 @@
+"""
+ChatTask domain entity.
+"""
+
+import json
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel, ConfigDict, field_validator
+
+
+class ChatTask(BaseModel):
+    """ChatTask domain entity with business logic."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: str
+    session_id: str
+    user_id: str
+    user_message: Optional[str] = None
+    message_bubbles: str  # JSON string (opaque to backend)
+    task_metadata: Optional[str] = None  # JSON string (opaque to backend)
+    created_time: int
+    updated_time: Optional[int] = None
+
+    @field_validator("message_bubbles")
+    @classmethod
+    def validate_message_bubbles(cls, v: str) -> str:
+        """Validate that message_bubbles is a non-empty JSON string."""
+        if not v or not v.strip():
+            raise ValueError("message_bubbles cannot be empty")
+        
+        # Validate it's valid JSON (but don't validate structure)
+        try:
+            parsed = json.loads(v)
+            if not isinstance(parsed, list) or len(parsed) == 0:
+                raise ValueError("message_bubbles must be a non-empty JSON array")
+        except json.JSONDecodeError as e:
+            raise ValueError(f"message_bubbles must be valid JSON: {e}")
+        
+        return v
+
+    @field_validator("task_metadata")
+    @classmethod
+    def validate_task_metadata(cls, v: Optional[str]) -> Optional[str]:
+        """Validate that task_metadata is valid JSON if provided."""
+        if v is None or not v.strip():
+            return None
+        
+        # Validate it's valid JSON (but don't validate structure)
+        try:
+            json.loads(v)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"task_metadata must be valid JSON: {e}")
+        
+        return v
+
+    def add_feedback(self, feedback_type: str, feedback_text: Optional[str] = None) -> None:
+        """Add or update feedback for this task."""
+        # Parse metadata, update, re-serialize
+        metadata = json.loads(self.task_metadata) if self.task_metadata else {}
+        
+        metadata["feedback"] = {
+            "type": feedback_type,
+            "text": feedback_text,
+            "submitted": True
+        }
+        
+        self.task_metadata = json.dumps(metadata)
+
+    def get_feedback(self) -> Optional[Dict[str, Any]]:
+        """Get feedback for this task."""
+        if self.task_metadata:
+            metadata = json.loads(self.task_metadata)
+            return metadata.get("feedback")
+        return None

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

@@ -0,0 +1,221 @@
+# DEVELOPER GUIDE: entities
+
+## Quick Summary
+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 (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
+- `session.py` - Session entity with name management and access control
+- `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 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, 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
+  - `user_id: str` - User who provided feedback
+  - `rating: str` - User rating
+  - `comment: str | None` - Optional feedback comment
+  - `created_time: int` - Feedback creation timestamp
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.repository.entities import Feedback
+
+# Create feedback
+feedback = Feedback(
+    id="feedback_123",
+    session_id="session_456",
+    task_id="task_789",
+    user_id="user_123",
+    rating="5",
+    comment="Great service!",
+    created_time=1640995200000
+)
+```
+
+### 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, 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
+  - `can_be_accessed_by_user(user_id: UserId) -> bool` - Checks if user can access this session
+  - `id: SessionId` - Unique session identifier
+  - `user_id: UserId` - Owner user identifier
+  - `name: str | None` - Optional session name
+  - `agent_id: AgentId | None` - Optional associated agent identifier
+  - `created_time: int` - Session creation timestamp
+  - `updated_time: int | None` - Last update timestamp
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.repository.entities import Session
+
+# Create a new session
+session = Session(
+    id="session_123",
+    user_id="user_456",
+    name="Customer Support Chat",
+    agent_id="agent_789",
+    created_time=1640995200000
+)
+
+# Update session name
+session.update_name("Updated Chat Name")
+
+# Mark activity
+session.mark_activity()
+
+# Check permissions
+if session.can_be_accessed_by_user("user_456"):
+    print("User can access this session")
+```
+
+### 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`
+
+**Classes:**
+- `Task(id: str, user_id: str, start_time: int, end_time: int | None = None, status: str | None = None, initial_request_text: str | None = None, total_input_tokens: int | None = None, total_output_tokens: int | None = None, total_cached_input_tokens: int | None = None, token_usage_details: dict | None = None)` - Task domain entity with token usage tracking
+  - `id: str` - Unique task identifier
+  - `user_id: str` - User who owns the task
+  - `start_time: int` - Task start timestamp
+  - `end_time: int | None` - Optional task end timestamp
+  - `status: str | None` - Optional task status
+  - `initial_request_text: str | None` - Optional initial request text
+  - `total_input_tokens: int | None` - Total input tokens used
+  - `total_output_tokens: int | None` - Total output tokens generated
+  - `total_cached_input_tokens: int | None` - Total cached input tokens used
+  - `token_usage_details: dict | None` - Detailed token usage information
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.repository.entities import Task
+
+# Create a task
+task = Task(
+    id="task_123",
+    user_id="user_456",
+    start_time=1640995200000,
+    status="in_progress",
+    initial_request_text="Help me with my order"
+)
+
+# Task with token usage tracking
+task_with_tokens = Task(
+    id="task_124",
+    user_id="user_456",
+    start_time=1640995200000,
+    end_time=1640995800000,
+    status="completed",
+    total_input_tokens=150,
+    total_output_tokens=300,
+    total_cached_input_tokens=50,
+    token_usage_details={"model": "gpt-4", "cost": 0.05}
+)
+```
+
+### task_event.py
+**Purpose:** Defines the TaskEvent domain entity for tracking events related to tasks
+**Import:** `from solace_agent_mesh.gateway.http_sse.repository.entities import TaskEvent`
+
+**Classes:**
+- `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
+  - `created_time: int` - Event creation timestamp
+  - `topic: str` - Event topic
+  - `direction: str` - Event direction
+  - `payload: dict[str, Any]` - Event payload data
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.repository.entities import TaskEvent
+
+# Create a task event
+event = TaskEvent(
+    id="event_123",
+    task_id="task_456",
+    user_id="user_789",
+    created_time=1640995200000,
+    topic="task.status.changed",
+    direction="outbound",
+    payload={"status": "completed", "result": "success"}
+)
+
+# Event without user
+system_event = TaskEvent(
+    id="event_124",
+    task_id="task_456",
+    created_time=1640995200000,
+    topic="task.system.notification",
+    direction="inbound",
+    payload={"message": "Task processing started"}
+)
+```
+
+# content_hash: d7b07fd8577e43715a286030d4119267ddff5483180284a16dc6d8aab19fd089

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

@@ -0,0 +1,20 @@
+"""
+Feedback domain entity.
+"""
+
+from pydantic import BaseModel
+
+
+class Feedback(BaseModel):
+    """Feedback domain entity."""
+
+    id: str
+    session_id: str
+    task_id: str
+    user_id: str
+    rating: str
+    comment: str | None = None
+    created_time: int
+
+    class Config:
+        from_attributes = True

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

@@ -0,0 +1,66 @@
+"""
+Session domain entity.
+"""
+
+from pydantic import BaseModel, ConfigDict
+
+from ...shared import now_epoch_ms
+from ...shared.types import AgentId, SessionId, UserId
+
+
+class Session(BaseModel):
+    """Session domain entity with business logic."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: SessionId
+    user_id: UserId
+    name: str | None = None
+    agent_id: AgentId | None = None
+    project_id: str | None = None
+    project_name: str | None = None
+    has_running_background_task: bool = False  # Enriched field, not stored in DB
+    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."""
+        if not new_name or len(new_name.strip()) == 0:
+            raise ValueError("Session name cannot be empty")
+        if len(new_name) > 255:
+            raise ValueError("Session name cannot exceed 255 characters")
+
+        self.name = new_name.strip()
+        self.updated_time = now_epoch_ms()
+
+    def mark_activity(self) -> None:
+        """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 and not self.is_deleted()