solace-agent-mesh 1.4.12__py3-none-any.whl → 1.5.0__py3-none-any.whl

solace_agent_mesh/gateway/http_sse/routers/dto/requests/requests_llm.txt

@@ -0,0 +1,83 @@
+# DEVELOPER GUIDE: requests
+
+## Quick Summary
+This directory contains request Data Transfer Objects (DTOs) for API endpoints, specifically focused on session management operations. These Pydantic models define the structure and validation rules for incoming API requests.
+
+## Files Overview
+- `__init__.py` - Exports all session-related request DTOs for easy importing
+- `session_requests.py` - Defines request DTOs for session CRUD operations (get, update, history retrieval)
+
+## Developer API Reference
+
+### __init__.py
+**Purpose:** Provides centralized imports for all request DTOs
+**Import:** `from solace_agent_mesh.gateway.http_sse.routers.dto.requests import GetSessionRequest, GetSessionHistoryRequest, UpdateSessionRequest`
+
+**Usage Examples:**
+```python
+# Import all session request DTOs
+from solace_agent_mesh.gateway.http_sse.routers.dto.requests import (
+    GetSessionRequest,
+    GetSessionHistoryRequest,
+    UpdateSessionRequest
+)
+```
+
+### session_requests.py
+**Purpose:** Defines Pydantic models for session-related API request validation
+**Import:** `from solace_agent_mesh.gateway.http_sse.routers.dto.requests.session_requests import GetSessionRequest, GetSessionHistoryRequest, UpdateSessionRequest`
+
+**Classes:**
+- `GetSessionRequest(session_id: SessionId, user_id: UserId)` - Request DTO for retrieving a specific session by ID
+- `GetSessionHistoryRequest(session_id: SessionId, user_id: UserId, pagination: Optional[PaginationInfo] = None)` - Request DTO for retrieving session message history with optional pagination
+- `UpdateSessionRequest(session_id: SessionId, user_id: UserId, name: str)` - Request DTO for updating session details with validation (name must be 1-255 characters)
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.routers.dto.requests.session_requests import (
+    GetSessionRequest,
+    GetSessionHistoryRequest,
+    UpdateSessionRequest
+)
+from pydantic import ValidationError
+
+# Create a request to get a specific session
+get_session_req = GetSessionRequest(
+    session_id="session456",
+    user_id="user123"
+)
+
+# Create a request to get session history with pagination
+get_history_req = GetSessionHistoryRequest(
+    session_id="session456",
+    user_id="user123",
+    pagination={"page": 1, "size": 20}
+)
+
+# Create a request to update a session name
+update_req = UpdateSessionRequest(
+    session_id="session456",
+    user_id="user123",
+    name="My Updated Session"
+)
+
+# Validate request data from dictionary
+request_data = {
+    "session_id": "session789",
+    "user_id": "user456",
+    "name": "New Session Name"
+}
+
+try:
+    validated_request = UpdateSessionRequest(**request_data)
+    print(f"Valid request: {validated_request}")
+except ValidationError as e:
+    print(f"Validation failed: {e}")
+
+# Access validated fields
+print(f"Session ID: {update_req.session_id}")
+print(f"User ID: {update_req.user_id}")
+print(f"New name: {update_req.name}")
+```
+
+# content_hash: d40151714f449905662170c71b393dba7c98e7ec1c46f5f3a861097b2d5376b2

solace_agent_mesh/gateway/http_sse/routers/dto/requests/session_requests.py

@@ -2,10 +2,9 @@
 Session-related request DTOs.
 """
 
-from typing import Optional
 from pydantic import BaseModel, Field
 
-from ....shared.types import SessionId, UserId, PaginationInfo
+from ....shared.types import SessionId, UserId
 
 
 class GetSessionRequest(BaseModel):
@@ -14,15 +13,8 @@ class GetSessionRequest(BaseModel):
     user_id: UserId
 
 
-class GetSessionHistoryRequest(BaseModel):
-    """Request DTO for retrieving session message history."""
-    session_id: SessionId
-    user_id: UserId
-    pagination: Optional[PaginationInfo] = None
-
-
 class UpdateSessionRequest(BaseModel):
     """Request DTO for updating session details."""
     session_id: SessionId
     user_id: UserId
-    name: str = Field(..., min_length=1, max_length=255, description="New session name")
+    name: str = Field(..., min_length=1, max_length=255, description="New session name")

solace_agent_mesh/gateway/http_sse/routers/dto/requests/task_requests.py

@@ -0,0 +1,58 @@
+"""
+Task-related request DTOs.
+"""
+
+import json
+from typing import Optional
+from pydantic import BaseModel, Field, field_validator
+
+
+class SaveTaskRequest(BaseModel):
+    """Request DTO for saving a task."""
+    
+    task_id: str = Field(..., alias="taskId", min_length=1)
+    user_message: Optional[str] = Field(None, alias="userMessage")
+    message_bubbles: str = Field(..., alias="messageBubbles")  # JSON string (opaque)
+    task_metadata: Optional[str] = Field(None, alias="taskMetadata")  # JSON string (opaque)
+    
+    model_config = {"populate_by_name": True}
+    
+    @field_validator("task_id")
+    @classmethod
+    def validate_task_id(cls, v: str) -> str:
+        """Validate that task_id is non-empty."""
+        if not v or not v.strip():
+            raise ValueError("task_id cannot be empty")
+        return v.strip()
+    
+    @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

solace_agent_mesh/gateway/http_sse/routers/dto/responses/__init__.py

@@ -3,14 +3,16 @@ Response DTOs for API endpoints.
 """
 
 from .session_responses import (
-    MessageResponse,
     SessionResponse,
     SessionListResponse,
 )
+from .task_responses import TaskResponse, TaskListResponse
 
 __all__ = [
     # Session responses
-    "MessageResponse",
     "SessionResponse",
     "SessionListResponse",
-]
+    # Task responses
+    "TaskResponse",
+    "TaskListResponse",
+]

solace_agent_mesh/gateway/http_sse/routers/dto/responses/responses_llm.txt

@@ -0,0 +1,107 @@
+# DEVELOPER GUIDE: responses
+
+## Quick Summary
+The `responses` directory contains Pydantic response DTOs (Data Transfer Objects) for API endpoints. It provides structured response models with automatic timestamp conversion from epoch milliseconds to ISO 8601 strings for JSON serialization.
+
+## Files Overview
+- `__init__.py` - Exports all response DTOs for easy importing
+- `base_responses.py` - Base response class with automatic timestamp serialization
+- `session_responses.py` - Session and message-related response DTOs
+
+## Developer API Reference
+
+### __init__.py
+**Purpose:** Central import point for all response DTOs
+**Import:** `from solace_agent_mesh.gateway.http_sse.routers.dto.responses import MessageResponse, SessionResponse, SessionListResponse`
+
+### base_responses.py
+**Purpose:** Provides base response class with automatic timestamp field conversion
+**Import:** `from solace_agent_mesh.gateway.http_sse.routers.dto.responses.base_responses import BaseTimestampResponse`
+
+**Classes:**
+- `BaseTimestampResponse(BaseModel)` - Base class for responses with timestamp fields that auto-converts epoch ms to ISO strings
+  - `model_dump(**kwargs) -> dict[str, Any]` - Converts timestamp fields to ISO strings in output
+  - `model_dump_json(**kwargs) -> str` - Serializes to JSON with timestamp conversion
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.routers.dto.responses.base_responses import BaseTimestampResponse
+
+class MyResponse(BaseTimestampResponse):
+    name: str
+    created_time: int  # Will be auto-converted to ISO string in JSON output
+    updated_time: int | None = None
+
+# Usage
+response = MyResponse(name="test", created_time=1640995200000)
+json_data = response.model_dump()  # created_time becomes ISO string
+```
+
+### session_responses.py
+**Purpose:** Session and message response DTOs with field aliasing for API consistency
+**Import:** `from solace_agent_mesh.gateway.http_sse.routers.dto.responses import MessageResponse, SessionResponse, SessionListResponse`
+
+**Classes:**
+- `MessageResponse(BaseTimestampResponse)` - Response DTO for chat messages
+  - `id: MessageId` - Unique message identifier
+  - `session_id: SessionId` - Session this message belongs to (aliased as "sessionId")
+  - `message: str` - Message content
+  - `sender_type: SenderType` - Type of sender (aliased as "senderType")
+  - `sender_name: str` - Name of sender (aliased as "senderName")
+  - `message_type: MessageType` - Type of message (aliased as "messageType")
+  - `created_time: int` - Creation timestamp in epoch ms (aliased as "createdTime")
+  - `updated_time: int | None` - Update timestamp in epoch ms (aliased as "updatedTime")
+
+- `SessionResponse(BaseTimestampResponse)` - Response DTO for chat sessions
+  - `id: SessionId` - Unique session identifier
+  - `user_id: UserId` - User who owns the session (aliased as "userId")
+  - `name: str | None` - Optional session name
+  - `agent_id: str | None` - Optional agent identifier (aliased as "agentId")
+  - `created_time: int` - Creation timestamp in epoch ms (aliased as "createdTime")
+  - `updated_time: int | None` - Update timestamp in epoch ms (aliased as "updatedTime")
+
+- `SessionListResponse(BaseModel)` - Response DTO for paginated session lists
+  - `sessions: list[SessionResponse]` - List of session objects
+  - `pagination: PaginationInfo | None` - Pagination metadata
+  - `total_count: int` - Total number of sessions (aliased as "totalCount")
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.routers.dto.responses import (
+    MessageResponse, 
+    SessionResponse, 
+    SessionListResponse
+)
+from solace_agent_mesh.gateway.http_sse.shared.enums import MessageType, SenderType
+
+# Create a message response
+message = MessageResponse(
+    id="msg_123",
+    session_id="sess_456", 
+    message="Hello world",
+    sender_type=SenderType.USER,
+    sender_name="John Doe",
+    message_type=MessageType.TEXT,
+    created_time=1640995200000
+)
+
+# Create a session response
+session = SessionResponse(
+    id="sess_456",
+    user_id="user_789",
+    name="My Chat Session",
+    agent_id="agent_001",
+    created_time=1640995200000
+)
+
+# Create a session list response
+session_list = SessionListResponse(
+    sessions=[session],
+    total_count=1
+)
+
+# Serialize to JSON (timestamps auto-converted to ISO strings)
+json_output = message.model_dump_json()
+```
+
+# content_hash: ed7205266a0eb2b2cb548d0c84fd44758cf1030524ffb144d08e9c82545fc4eb

solace_agent_mesh/gateway/http_sse/routers/dto/responses/session_responses.py

@@ -4,24 +4,10 @@ Session-related response DTOs.
 
 from pydantic import BaseModel, ConfigDict, Field
 
-from ....shared.enums import MessageType, SenderType
-from ....shared.types import MessageId, PaginationInfo, SessionId, UserId
+from ....shared.types import PaginationInfo, SessionId, UserId
 from .base_responses import BaseTimestampResponse
 
 
-class MessageResponse(BaseTimestampResponse):
-    """Response DTO for a chat message."""
-
-    id: MessageId
-    session_id: SessionId = Field(alias="sessionId")
-    message: str
-    sender_type: SenderType = Field(alias="senderType")
-    sender_name: str = Field(alias="senderName")
-    message_type: MessageType = Field(default=MessageType.TEXT, alias="messageType")
-    created_time: int = Field(alias="createdTime")
-    updated_time: int | None = Field(default=None, alias="updatedTime")
-
-
 class SessionResponse(BaseTimestampResponse):
     """Response DTO for a session."""
 

solace_agent_mesh/gateway/http_sse/routers/dto/responses/task_responses.py

@@ -0,0 +1,30 @@
+"""
+Task-related response DTOs.
+"""
+
+from typing import List, Optional
+from pydantic import BaseModel, Field
+
+from .base_responses import BaseTimestampResponse
+
+
+class TaskResponse(BaseTimestampResponse):
+    """Response DTO for a single task."""
+    
+    task_id: str = Field(..., alias="taskId")
+    session_id: str = Field(..., alias="sessionId")
+    user_message: Optional[str] = Field(None, alias="userMessage")
+    message_bubbles: str = Field(..., alias="messageBubbles")  # JSON string (opaque)
+    task_metadata: Optional[str] = Field(None, alias="taskMetadata")  # JSON string (opaque)
+    created_time: int = Field(..., alias="createdTime")
+    updated_time: Optional[int] = Field(None, alias="updatedTime")
+    
+    model_config = {"populate_by_name": True}
+
+
+class TaskListResponse(BaseModel):
+    """Response DTO for a list of tasks."""
+    
+    tasks: List[TaskResponse]
+    
+    model_config = {"populate_by_name": True}

solace_agent_mesh/gateway/http_sse/routers/feedback.py

@@ -0,0 +1,37 @@
+"""
+API Router for receiving and processing user feedback on chat messages.
+"""
+
+from typing import Literal, Optional
+
+from fastapi import APIRouter, Depends
+from fastapi import Request as FastAPIRequest
+from pydantic import BaseModel, Field
+
+from ..dependencies import get_feedback_service, get_user_id
+from ..services.feedback_service import FeedbackService
+
+router = APIRouter()
+
+
+class FeedbackPayload(BaseModel):
+    """Data model for the feedback submission payload."""
+
+    task_id: str = Field(..., alias="taskId")
+    session_id: str = Field(..., alias="sessionId")
+    feedback_type: Literal["up", "down"] = Field(..., alias="feedbackType")
+    feedback_text: Optional[str] = Field(None, alias="feedbackText")
+
+
+@router.post("/feedback", status_code=202, tags=["Feedback"])
+async def submit_feedback(
+    payload: FeedbackPayload,
+    request: FastAPIRequest,
+    user_id: str = Depends(get_user_id),
+    feedback_service: FeedbackService = Depends(get_feedback_service),
+):
+    """
+    Receives and processes user feedback for a specific task.
+    """
+    await feedback_service.process_feedback(payload, user_id)
+    return {"status": "feedback received"}