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

solace_agent_mesh/gateway/http_sse/routers/dto/prompt_dto.py

@@ -0,0 +1,255 @@
+"""
+Pydantic models for prompt library API.
+"""
+
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel, Field
+
+
+class PromptBase(BaseModel):
+    """Base schema for Prompt"""
+    prompt_text: str = Field(
+        ...,
+        min_length=1,
+        max_length=10000,
+        description="The prompt text content",
+        alias="promptText"
+    )
+    
+    class Config:
+        populate_by_name = True
+
+
+class PromptCreate(PromptBase):
+    """Schema for creating a new prompt version"""
+    pass
+
+
+class PromptResponse(PromptBase):
+    """Schema for prompt response"""
+    id: str
+    group_id: str = Field(alias="groupId")
+    user_id: str = Field(alias="userId")
+    version: int
+    # Versioned metadata fields
+    name: Optional[str] = Field(None, description="Prompt name at this version")
+    description: Optional[str] = Field(None, description="Prompt description at this version")
+    category: Optional[str] = Field(None, description="Prompt category at this version")
+    command: Optional[str] = Field(None, description="Prompt command at this version")
+    created_at: int = Field(alias="createdAt")  # epoch milliseconds
+    updated_at: int = Field(alias="updatedAt")  # epoch milliseconds
+    
+    class Config:
+        from_attributes = True
+        populate_by_name = True
+
+
+class PromptGroupBase(BaseModel):
+    """Base schema for PromptGroup"""
+    name: str = Field(
+        ..., 
+        min_length=1, 
+        max_length=255, 
+        description="Name of the prompt group"
+    )
+    description: Optional[str] = Field(
+        None, 
+        max_length=1000, 
+        description="Short description"
+    )
+    category: Optional[str] = Field(
+        None, 
+        max_length=100, 
+        description="Category for organization"
+    )
+    command: Optional[str] = Field(
+        None,
+        min_length=1,
+        max_length=50,
+        pattern="^[a-zA-Z0-9_-]+$",
+        description="Shorthand command (alphanumeric, dash, underscore only)"
+    )
+
+
+class PromptGroupCreate(PromptGroupBase):
+    """Schema for creating a new prompt group"""
+    initial_prompt: str = Field(
+        ..., 
+        min_length=1, 
+        max_length=10000, 
+        description="Initial prompt text"
+    )
+
+
+class PromptGroupUpdate(BaseModel):
+    """Schema for updating a prompt group"""
+    name: Optional[str] = Field(None, min_length=1, max_length=255)
+    description: Optional[str] = Field(None, max_length=1000)
+    category: Optional[str] = Field(None, max_length=100)
+    command: Optional[str] = Field(
+        None,
+        min_length=1,
+        max_length=50,
+        pattern="^[a-zA-Z0-9_-]+$"
+    )
+    initial_prompt: Optional[str] = Field(
+        None,
+        min_length=1,
+        max_length=10000,
+        description="Updated prompt text (creates new version if changed)"
+    )
+
+
+class PromptGroupResponse(PromptGroupBase):
+    """Schema for prompt group response"""
+    id: str
+    user_id: str = Field(alias="userId")
+    author_name: Optional[str] = Field(None, alias="authorName")
+    production_prompt_id: Optional[str] = Field(None, alias="productionPromptId")
+    is_shared: bool = Field(alias="isShared")
+    is_pinned: bool = Field(alias="isPinned")
+    created_at: int = Field(alias="createdAt")  # epoch milliseconds
+    updated_at: int = Field(alias="updatedAt")  # epoch milliseconds
+    
+    # Include production prompt if available
+    production_prompt: Optional[PromptResponse] = Field(None, alias="productionPrompt")
+    
+    class Config:
+        from_attributes = True
+        populate_by_name = True
+
+
+class PromptGroupListResponse(BaseModel):
+    """Schema for paginated prompt group list"""
+    groups: List[PromptGroupResponse]
+    total: int
+    skip: int
+    limit: int
+
+
+# AI-Assisted Prompt Builder Models
+
+class ChatMessage(BaseModel):
+    """Schema for a chat message"""
+    role: str = Field(
+        ..., 
+        pattern="^(user|assistant)$", 
+        description="Message role"
+    )
+    content: str = Field(..., min_length=1, description="Message content")
+
+
+class PromptBuilderChatRequest(BaseModel):
+    """Schema for prompt builder chat request"""
+    message: str = Field(
+        ...,
+        min_length=1,
+        max_length=200000,
+        description="User message (supports long conversation histories for template creation)"
+    )
+    conversation_history: List[ChatMessage] = Field(
+        default_factory=list, 
+        description="Previous messages"
+    )
+    current_template: Optional[Dict[str, Any]] = Field(
+        None, 
+        description="Current template state"
+    )
+
+
+class PromptBuilderChatResponse(BaseModel):
+    """Schema for prompt builder chat response"""
+    message: str = Field(..., description="Assistant's response message")
+    template_updates: Dict[str, Any] = Field(
+        default_factory=dict, 
+        description="Updates to template config"
+    )
+    confidence: float = Field(
+        0.0, 
+        ge=0.0, 
+        le=1.0, 
+        description="Confidence score"
+    )
+    ready_to_save: bool = Field(
+        False,
+        description="Whether template is ready to save"
+    )
+
+
+# Export/Import Models
+
+class PromptExportMetadata(BaseModel):
+    """Metadata for exported prompt"""
+    author_name: Optional[str] = Field(None, alias="authorName")
+    original_version: int = Field(alias="originalVersion")
+    original_created_at: int = Field(alias="originalCreatedAt")
+    
+    class Config:
+        populate_by_name = True
+
+
+class PromptExportData(BaseModel):
+    """Data structure for exported prompt"""
+    name: str
+    description: Optional[str] = None
+    category: Optional[str] = None
+    command: Optional[str] = None
+    prompt_text: str = Field(alias="promptText")
+    metadata: PromptExportMetadata
+    
+    class Config:
+        populate_by_name = True
+
+
+class PromptExportResponse(BaseModel):
+    """Schema for exported prompt file"""
+    version: str = "1.0"
+    exported_at: int = Field(alias="exportedAt")
+    prompt: PromptExportData
+    
+    class Config:
+        populate_by_name = True
+        by_alias = True
+
+
+class PromptImportOptions(BaseModel):
+    """Options for importing a prompt"""
+    preserve_command: bool = Field(
+        False,
+        alias="preserveCommand",
+        description="If true, attempt to keep original command (may be modified if conflict exists)"
+    )
+    preserve_category: bool = Field(
+        True,
+        alias="preserveCategory",
+        description="If true, keep the original category"
+    )
+    
+    class Config:
+        populate_by_name = True
+
+
+class PromptImportRequest(BaseModel):
+    """Schema for importing a prompt"""
+    prompt_data: Dict[str, Any] = Field(
+        ...,
+        description="The exported prompt JSON data"
+    )
+    options: Optional[PromptImportOptions] = Field(
+        default_factory=PromptImportOptions,
+        description="Import options"
+    )
+
+
+class PromptImportResponse(BaseModel):
+    """Schema for import response"""
+    success: bool
+    prompt_group_id: str = Field(alias="promptGroupId")
+    warnings: List[str] = Field(
+        default_factory=list,
+        description="Any warnings generated during import (e.g., command conflicts)"
+    )
+    
+    class Config:
+        populate_by_name = True
+        by_alias = True

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

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

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

@@ -0,0 +1,48 @@
+"""
+Request DTOs for project-related API endpoints.
+"""
+
+from pydantic import BaseModel, Field
+from typing import Optional
+
+
+class CreateProjectRequest(BaseModel):
+    """Request to create a new project."""
+    
+    name: str = Field(..., min_length=1, max_length=255, description="Project name")
+    description: Optional[str] = Field(None, max_length=1000, description="Project description")
+    system_prompt: Optional[str] = Field(None, max_length=4000, description="Instructions for the project")
+    default_agent_id: Optional[str] = Field(None, description="Default agent ID for new chats")
+    file_metadata: Optional[str] = Field(None, description="JSON string containing file metadata")
+    user_id: str
+
+
+class UpdateProjectRequest(BaseModel):
+    """Request to update an existing project."""
+    
+    name: Optional[str] = Field(None, min_length=1, max_length=255, description="Project name")
+    description: Optional[str] = Field(None, max_length=1000, description="Project description")
+    system_prompt: Optional[str] = Field(None, alias="systemPrompt", max_length=4000, description="Instructions for the project")
+    default_agent_id: Optional[str] = Field(None, alias="defaultAgentId", description="Default agent ID for new chats")
+
+
+class GetProjectsRequest(BaseModel):
+    """Request DTO for retrieving projects."""
+    user_id: str
+
+
+class GetProjectRequest(BaseModel):
+    """Request DTO for retrieving a specific project."""
+    project_id: str
+    user_id: str
+
+
+class DeleteProjectRequest(BaseModel):
+    """Request DTO for deleting a project."""
+    project_id: str
+    user_id: str
+
+
+class ProjectFilter(BaseModel):
+    """Filter criteria for retrieving projects."""
+    user_id: Optional[str] = None

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

@@ -0,0 +1,133 @@
+# DEVELOPER GUIDE: requests
+
+## Quick Summary
+This directory contains request Data Transfer Objects (DTOs) for API endpoints, providing Pydantic models for session management and task operations. These DTOs handle request validation, field transformation, and type safety for incoming API requests.
+
+## Files Overview
+- `__init__.py` - Exports all request DTOs for centralized importing
+- `session_requests.py` - Defines request DTOs for session operations (get, update)
+- `task_requests.py` - Defines request DTOs for task operations (save)
+
+## 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, UpdateSessionRequest, SaveTaskRequest`
+
+**Usage Examples:**
+```python
+# Import all request DTOs
+from solace_agent_mesh.gateway.http_sse.routers.dto.requests import (
+    GetSessionRequest,
+    UpdateSessionRequest,
+    SaveTaskRequest
+)
+```
+
+### 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, UpdateSessionRequest`
+
+**Classes:**
+- `GetSessionRequest(session_id: SessionId, user_id: UserId)` - Request DTO for retrieving a specific session by ID
+- `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,
+    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 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}")
+```
+
+### task_requests.py
+**Purpose:** Defines Pydantic models for task-related API request validation with JSON field handling
+**Import:** `from solace_agent_mesh.gateway.http_sse.routers.dto.requests.task_requests import SaveTaskRequest`
+
+**Classes:**
+- `SaveTaskRequest(task_id: str, user_message: Optional[str], message_bubbles: str, task_metadata: Optional[str])` - Request DTO for saving tasks with JSON validation
+  - `validate_task_id(v: str) -> str` - Validates task_id is non-empty and strips whitespace
+  - `validate_message_bubbles(v: str) -> str` - Validates message_bubbles is valid non-empty JSON array
+  - `validate_task_metadata(v: Optional[str]) -> Optional[str]` - Validates task_metadata is valid JSON if provided
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.routers.dto.requests.task_requests import SaveTaskRequest
+from pydantic import ValidationError
+import json
+
+# Create a save task request with camelCase field names (API style)
+task_data = {
+    "taskId": "task_123",
+    "userMessage": "Please analyze this data",
+    "messageBubbles": json.dumps([
+        {"type": "user", "content": "Hello"},
+        {"type": "assistant", "content": "Hi there!"}
+    ]),
+    "taskMetadata": json.dumps({"priority": "high", "category": "analysis"})
+}
+
+try:
+    save_task_req = SaveTaskRequest(**task_data)
+    print(f"Task ID: {save_task_req.task_id}")
+    print(f"User Message: {save_task_req.user_message}")
+    print(f"Message Bubbles: {save_task_req.message_bubbles}")
+    print(f"Task Metadata: {save_task_req.task_metadata}")
+except ValidationError as e:
+    print(f"Validation failed: {e}")
+
+# Create with snake_case field names (internal style)
+task_data_snake = {
+    "task_id": "task_456",
+    "user_message": "Process this request",
+    "message_bubbles": json.dumps([{"type": "system", "content": "Processing..."}]),
+    "task_metadata": None  # Optional field
+}
+
+save_task_req2 = SaveTaskRequest(**task_data_snake)
+
+# Handle validation errors
+invalid_data = {
+    "taskId": "",  # Empty task_id will fail validation
+    "messageBubbles": "invalid json"  # Invalid JSON will fail
+}
+
+try:
+    SaveTaskRequest(**invalid_data)
+except ValidationError as e:
+    print(f"Expected validation error: {e}")
+```
+
+# content_hash: 57595b5f602ab4728452316a250ef1ecdcf8dedba497c07de378959b659eccc2

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

@@ -0,0 +1,33 @@
+"""
+Session-related request DTOs.
+"""
+
+from typing import Optional
+from pydantic import BaseModel, Field
+
+from ....shared.types import SessionId, UserId
+
+
+class GetSessionRequest(BaseModel):
+    """Request DTO for retrieving a specific session."""
+    session_id: SessionId
+    project_id: Optional[str] = None
+    user_id: UserId
+
+
+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")
+
+
+class MoveSessionRequest(BaseModel):
+    """Request DTO for moving a session to a different project."""
+    project_id: Optional[str] = Field(None, alias="projectId", description="New project ID (null to remove from project)")
+
+
+class SearchSessionsRequest(BaseModel):
+    """Request DTO for searching sessions."""
+    query: str = Field(..., min_length=1, description="Search query string")
+    project_id: Optional[str] = Field(None, alias="projectId", description="Optional project ID to filter results")

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

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

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

@@ -0,0 +1,42 @@
+"""
+Base response classes with automatic timestamp serialization.
+"""
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+from ....shared import epoch_ms_to_iso8601
+
+
+class BaseTimestampResponse(BaseModel):
+    """
+    Base class for responses that include standard timestamp fields.
+
+    Timestamp fields are stored as epoch milliseconds (int) internally.
+    Automatically converts created_time and updated_time to ISO strings in JSON output.
+    """
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    def model_dump(self, **kwargs) -> dict[str, Any]:
+        kwargs.setdefault('by_alias', True)
+        """Override model_dump to convert timestamp fields to ISO strings."""
+        data = super().model_dump(**kwargs)
+
+        # Convert timestamp fields to ISO strings for JSON output
+        # Check both snake_case (internal) and camelCase (API) names
+        timestamp_fields = ["created_time", "updated_time", "createdTime", "updatedTime"]
+        for field in timestamp_fields:
+            if field in data and data[field] is not None:
+                data[field] = epoch_ms_to_iso8601(data[field])
+
+        return data
+
+    def model_dump_json(self, **kwargs) -> str:
+        """Override model_dump_json to use our timestamp conversion."""
+        # Get the converted data first, then serialize to JSON
+        converted_data = self.model_dump(**kwargs)
+        import json
+
+        return json.dumps(converted_data, default=str)

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

@@ -0,0 +1,31 @@
+"""
+Project-related response DTOs.
+"""
+
+from pydantic import BaseModel, ConfigDict, Field
+from typing import Optional
+
+from .base_responses import BaseTimestampResponse
+
+
+class ProjectResponse(BaseTimestampResponse):
+    """Response DTO for a project."""
+
+    id: str
+    name: str
+    user_id: str = Field(alias="userId")
+    description: Optional[str] = None
+    system_prompt: Optional[str] = Field(default=None, alias="systemPrompt")
+    default_agent_id: Optional[str] = Field(default=None, alias="defaultAgentId")
+    artifact_count: Optional[int] = Field(default=None, alias="artifactCount")
+    created_at: int = Field(alias="createdAt")
+    updated_at: Optional[int] = Field(default=None, alias="updatedAt")
+
+
+class ProjectListResponse(BaseModel):
+    """Response DTO for a list of projects."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    projects: list[ProjectResponse]
+    total: int