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

solace_agent_mesh/gateway/http_sse/routers/dto/dto_llm.txt

@@ -0,0 +1,346 @@
+# DEVELOPER GUIDE: dto
+
+## Quick Summary
+The `dto` directory contains Data Transfer Objects (DTOs) for API contract definition and validation in the HTTP SSE gateway. It's organized into two main subdirectories: `requests` for incoming API request validation using Pydantic models, and `responses` for structured API response formatting with automatic timestamp conversion. The DTOs primarily focus on session management operations and provide type-safe interfaces for API endpoints.
+
+## Files and Subdirectories Overview
+- **Direct files:** 
+  - `__init__.py` - Main module exports for requests and responses submodules
+- **Subdirectories:**
+  - `requests/` - Request DTOs for API endpoint validation (session CRUD operations)
+  - `responses/` - Response DTOs with automatic timestamp serialization and field aliasing
+
+## Developer API Reference
+
+### Direct Files
+
+#### __init__.py
+**Purpose:** Main entry point that exports the requests and responses submodules
+**Import:** `from solace_agent_mesh.gateway.http_sse.routers.dto import requests, responses`
+
+**Exports:**
+- `requests` - Module containing all request DTOs
+- `responses` - Module containing all response DTOs
+
+### Subdirectory APIs
+
+#### requests/
+**Purpose:** Provides Pydantic models for validating incoming API requests, specifically for session management operations
+**Key Exports:** GetSessionsRequest, GetSessionRequest, GetSessionHistoryRequest, UpdateSessionRequest, DeleteSessionRequest
+**Import Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.routers.dto.requests import (
+    GetSessionRequest,
+    GetSessionHistoryRequest,
+    UpdateSessionRequest
+)
+```
+
+#### responses/
+**Purpose:** Provides structured response DTOs with automatic timestamp conversion and field aliasing for API consistency
+**Key Exports:** MessageResponse, SessionResponse, SessionListResponse, BaseTimestampResponse
+**Import Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.routers.dto.responses import (
+    MessageResponse,
+    SessionResponse,
+    SessionListResponse
+)
+```
+
+## Complete Usage Guide
+
+### 1. Basic Imports and Setup
+
+```python
+# Import the main dto modules
+from solace_agent_mesh.gateway.http_sse.routers.dto import requests, responses
+
+# Or import specific DTOs directly
+from solace_agent_mesh.gateway.http_sse.routers.dto.requests import (
+    GetSessionRequest,
+    GetSessionHistoryRequest,
+    UpdateSessionRequest
+)
+from solace_agent_mesh.gateway.http_sse.routers.dto.responses import (
+    SessionResponse,
+    MessageResponse,
+    SessionListResponse
+)
+```
+
+### 2. Working with Request DTOs
+
+```python
+from solace_agent_mesh.gateway.http_sse.routers.dto.requests import (
+    GetSessionRequest,
+    GetSessionHistoryRequest,
+    UpdateSessionRequest
+)
+from pydantic import ValidationError
+
+# Create a request to get a specific session
+def get_session(session_id: str, user_id: str):
+    try:
+        request = GetSessionRequest(
+            session_id=session_id,
+            user_id=user_id
+        )
+        return request
+    except ValidationError as e:
+        print(f"Invalid request parameters: {e}")
+        return None
+
+# Create a request to get session history with pagination
+def get_session_history(session_id: str, user_id: str, page: int = 1, size: int = 20):
+    try:
+        request = GetSessionHistoryRequest(
+            session_id=session_id,
+            user_id=user_id,
+            pagination={"page": page, "size": size}
+        )
+        return request
+    except ValidationError as e:
+        print(f"Validation failed: {e}")
+        return None
+
+# Create a request to update session name
+def update_session_name(session_id: str, user_id: str, new_name: str):
+    try:
+        request = UpdateSessionRequest(
+            session_id=session_id,
+            user_id=user_id,
+            name=new_name  # Automatically validated (1-255 characters)
+        )
+        return request
+    except ValidationError as e:
+        print(f"Validation failed: {e}")
+        return None
+```
+
+### 3. Working with Response DTOs
+
+```python
+from solace_agent_mesh.gateway.http_sse.routers.dto.responses import (
+    SessionResponse,
+    MessageResponse,
+    SessionListResponse
+)
+from solace_agent_mesh.gateway.http_sse.shared.enums import MessageType, SenderType
+import time
+
+# Create session responses
+def create_session_response(session_data: dict) -> SessionResponse:
+    return SessionResponse(
+        id=session_data["id"],
+        user_id=session_data["user_id"],
+        name=session_data.get("name"),
+        agent_id=session_data.get("agent_id"),
+        created_time=int(time.time() * 1000),  # Current time in epoch ms
+        updated_time=session_data.get("updated_time")
+    )
+
+# Create message responses
+def create_message_response(message_data: dict) -> MessageResponse:
+    return MessageResponse(
+        id=message_data["id"],
+        session_id=message_data["session_id"],
+        message=message_data["message"],
+        sender_type=SenderType.USER,
+        sender_name=message_data["sender_name"],
+        message_type=MessageType.TEXT,
+        created_time=int(time.time() * 1000)
+    )
+
+# Create paginated session list responses
+def create_session_list_response(sessions: list, total: int) -> SessionListResponse:
+    session_responses = [create_session_response(session) for session in sessions]
+    return SessionListResponse(
+        sessions=session_responses,
+        pagination={"page": 1, "size": len(sessions), "total_pages": 1},
+        total_count=total
+    )
+```
+
+### 4. Complete API Endpoint Example
+
+```python
+from fastapi import APIRouter, HTTPException
+from solace_agent_mesh.gateway.http_sse.routers.dto.requests import (
+    GetSessionRequest,
+    GetSessionHistoryRequest,
+    UpdateSessionRequest
+)
+from solace_agent_mesh.gateway.http_sse.routers.dto.responses import (
+    SessionResponse,
+    MessageResponse,
+    SessionListResponse
+)
+
+router = APIRouter()
+
+@router.get("/sessions/{session_id}")
+async def get_session(session_id: str, user_id: str) -> SessionResponse:
+    """Get a specific session"""
+    
+    # Create and validate request DTO
+    request = GetSessionRequest(
+        session_id=session_id,
+        user_id=user_id
+    )
+    
+    # Fetch data (mock implementation)
+    session_data = fetch_session(request)
+    
+    # Return structured response with automatic timestamp conversion
+    return SessionResponse(
+        id=session_data["id"],
+        user_id=session_data["user_id"],
+        name=session_data["name"],
+        created_time=session_data["created_time"]
+    )
+
+@router.get("/sessions/{session_id}/history")
+async def get_session_history(
+    session_id: str,
+    user_id: str,
+    page: int = 1,
+    size: int = 20
+) -> list[MessageResponse]:
+    """Get session message history"""
+    
+    # Validate request using DTO
+    request = GetSessionHistoryRequest(
+        session_id=session_id,
+        user_id=user_id,
+        pagination={"page": page, "size": size}
+    )
+    
+    # Fetch messages (mock implementation)
+    messages_data = fetch_session_messages(request)
+    
+    # Return response DTOs with automatic field aliasing
+    return [
+        MessageResponse(
+            id=msg["id"],
+            session_id=msg["session_id"],
+            message=msg["message"],
+            sender_type=msg["sender_type"],
+            sender_name=msg["sender_name"],
+            message_type=msg["message_type"],
+            created_time=msg["created_time"]
+        )
+        for msg in messages_data
+    ]
+
+@router.put("/sessions/{session_id}")
+async def update_session(
+    session_id: str,
+    user_id: str,
+    name: str
+) -> SessionResponse:
+    """Update session name"""
+    
+    # Validate request using DTO
+    try:
+        request = UpdateSessionRequest(
+            session_id=session_id,
+            user_id=user_id,
+            name=name
+        )
+    except ValidationError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    
+    # Update session (mock implementation)
+    updated_session = update_session_in_db(request)
+    
+    # Return response DTO with automatic field aliasing
+    return SessionResponse(
+        id=updated_session["id"],
+        user_id=updated_session["user_id"],
+        name=updated_session["name"],
+        created_time=updated_session["created_time"],
+        updated_time=updated_session["updated_time"]
+    )
+```
+
+### 5. JSON Serialization with Automatic Timestamp Conversion
+
+```python
+from solace_agent_mesh.gateway.http_sse.routers.dto.responses import SessionResponse, MessageResponse
+from solace_agent_mesh.gateway.http_sse.shared.enums import MessageType, SenderType
+import json
+
+# Create a session response
+session = SessionResponse(
+    id="sess_123",
+    user_id="user_456",
+    name="My Session",
+    created_time=1640995200000,  # Epoch milliseconds
+    updated_time=1640995260000
+)
+
+# Automatic conversion to ISO strings in JSON output
+json_output = session.model_dump_json()
+print(json_output)
+# Output: {
+#   "id": "sess_123",
+#   "userId": "user_456",  # Note the camelCase aliasing
+#   "name": "My Session",
+#   "createdTime": "2022-01-01T00:00:00Z",  # Converted to ISO string
+#   "updatedTime": "2022-01-01T00:01:00Z"
+# }
+
+# Create a message response with field aliasing
+message = MessageResponse(
+    id="msg_789",
+    session_id="sess_123",
+    message="Hello world",
+    sender_type=SenderType.USER,
+    sender_name="John Doe",
+    message_type=MessageType.TEXT,
+    created_time=1640995200000
+)
+
+# Get dict with converted timestamps and aliased fields
+dict_output = message.model_dump()
+print(dict_output["sessionId"])  # "sess_123" (camelCase alias)
+print(dict_output["senderType"])  # SenderType.USER (camelCase alias)
+print(dict_output["createdTime"])  # "2022-01-01T00:00:00Z" (converted timestamp)
+```
+
+### 6. Custom Response Classes Using Base
+
+```python
+from solace_agent_mesh.gateway.http_sse.routers.dto.responses.base_responses import BaseTimestampResponse
+
+class CustomResponse(BaseTimestampResponse):
+    """Custom response with automatic timestamp handling"""
+    name: str
+    status: str
+    created_time: int
+    last_accessed: int | None = None
+    
+    class Config:
+        # Add field aliases if needed
+        alias_generator = lambda field_name: ''.join(
+            word.capitalize() if i > 0 else word 
+            for i, word in enumerate(field_name.split('_'))
+        )
+
+# Usage
+custom_response = CustomResponse(
+    name="Test Item",
+    status="active",
+    created_time=1640995200000,
+    last_accessed=1640995300000
+)
+
+# Automatic timestamp conversion in JSON
+json_data = custom_response.model_dump_json()
+# Fields like created_time become ISO strings automatically
+```
+
+This comprehensive guide shows how the `dto` directory provides a complete type-safe API contract system with automatic validation for requests and structured responses with timestamp conversion for the HTTP SSE gateway.
+
+# content_hash: 3bb29d4c46b962221fc3034560b7e0da75b5a41f7f8f4d4f25aecf26e10f83f5

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

@@ -4,12 +4,12 @@ Request DTOs for API endpoints.
 
 from .session_requests import (
     GetSessionRequest,
-    GetSessionHistoryRequest,
     UpdateSessionRequest,
 )
+from .task_requests import SaveTaskRequest
 
 __all__ = [
     "GetSessionRequest",
-    "GetSessionHistoryRequest",
     "UpdateSessionRequest",
-]
+    "SaveTaskRequest",
+]

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."""