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

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

@@ -0,0 +1,123 @@
+# 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, covering sessions, tasks, and messages.
+
+## 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-related response DTOs with field aliasing
+- `task_responses.py` - Task-related response DTOs with field aliasing
+
+## 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 SessionResponse, SessionListResponse, TaskResponse, TaskListResponse`
+
+### 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 response DTOs with field aliasing for API consistency
+**Import:** `from solace_agent_mesh.gateway.http_sse.routers.dto.responses import SessionResponse, SessionListResponse`
+
+**Classes:**
+- `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: PaginationMeta | 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 SessionResponse, SessionListResponse
+
+# 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 = session.model_dump_json()
+```
+
+### task_responses.py
+**Purpose:** Task response DTOs with field aliasing for API consistency
+**Import:** `from solace_agent_mesh.gateway.http_sse.routers.dto.responses import TaskResponse, TaskListResponse`
+
+**Classes:**
+- `TaskResponse(BaseTimestampResponse)` - Response DTO for a single task
+  - `task_id: str` - Unique task identifier (aliased as "taskId")
+  - `session_id: str` - Session this task belongs to (aliased as "sessionId")
+  - `user_message: str | None` - Optional user message (aliased as "userMessage")
+  - `message_bubbles: str` - JSON string containing message bubbles (aliased as "messageBubbles")
+  - `task_metadata: str | None` - Optional JSON string with task metadata (aliased as "taskMetadata")
+  - `created_time: int` - Creation timestamp in epoch ms (aliased as "createdTime")
+  - `updated_time: int | None` - Update timestamp in epoch ms (aliased as "updatedTime")
+
+- `TaskListResponse(BaseModel)` - Response DTO for a list of tasks
+  - `tasks: list[TaskResponse]` - List of task objects
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.routers.dto.responses import TaskResponse, TaskListResponse
+
+# Create a task response
+task = TaskResponse(
+    task_id="task_123",
+    session_id="sess_456",
+    user_message="Process this data",
+    message_bubbles='{"bubbles": [{"type": "text", "content": "Processing..."}]}',
+    task_metadata='{"priority": "high"}',
+    created_time=1640995200000,
+    updated_time=1640995260000
+)
+
+# Create a task list response
+task_list = TaskListResponse(
+    tasks=[task]
+)
+
+# Serialize to JSON (timestamps auto-converted to ISO strings)
+json_output = task.model_dump_json()
+```
+
+# content_hash: 059aa6ca2472994cbde0e223252c8e78ba2be6c5d0d4f3e91f5e10976e173e5d

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

@@ -0,0 +1,33 @@
+"""
+Session-related response DTOs.
+"""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ....shared.pagination import PaginationMeta
+from ....shared.types import SessionId, UserId
+from .base_responses import BaseTimestampResponse
+
+
+class SessionResponse(BaseTimestampResponse):
+    """Response DTO for a session."""
+
+    id: SessionId
+    user_id: UserId = Field(alias="userId")
+    name: str | None = None
+    agent_id: str | None = Field(default=None, alias="agentId")
+    project_id: str | None = Field(default=None, alias="projectId")
+    project_name: str | None = Field(default=None, alias="projectName")
+    has_running_background_task: bool = Field(default=False, alias="hasRunningBackgroundTask")
+    created_time: int = Field(alias="createdTime")
+    updated_time: int | None = Field(default=None, alias="updatedTime")
+
+
+class SessionListResponse(BaseModel):
+    """Response DTO for a list of sessions (legacy - use PaginatedResponse instead)."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    sessions: list[SessionResponse]
+    pagination: PaginationMeta | None = None
+    total_count: int = Field(alias="totalCount")

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/dto/responses/version_responses.py

@@ -0,0 +1,31 @@
+"""
+Version-related response DTOs.
+"""
+
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ProductInfo(BaseModel):
+    """Information about a single installed product."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    id: str = Field(..., description="Product identifier")
+    name: str = Field(..., description="Human-readable product name")
+    description: str = Field(..., description="Product description")
+    version: str = Field(..., description="Product version")
+    dependencies: Optional[dict[str, str]] = Field(
+        default=None, description="Optional map of dependency names to versions"
+    )
+
+
+class VersionResponse(BaseModel):
+    """Response containing version information for all installed products."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    products: list[ProductInfo] = Field(
+        ..., description="List of installed product information"
+    )

solace_agent_mesh/gateway/http_sse/routers/feedback.py

@@ -0,0 +1,168 @@
+"""
+API Router for receiving and processing user feedback on chat messages.
+"""
+
+import logging
+from datetime import datetime
+from typing import Literal, Optional
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi import Request as FastAPIRequest
+from pydantic import BaseModel, Field
+from sqlalchemy.orm import Session as DBSession
+
+from ..dependencies import (
+    get_db,
+    get_feedback_service,
+    get_task_repository,
+    get_user_config,
+    get_user_id,
+)
+from ..repository.entities import Feedback
+from ..repository.feedback_repository import FeedbackRepository
+from ..repository.interfaces import ITaskRepository
+from ..services.feedback_service import FeedbackService
+from ..shared.pagination import PaginationParams
+from ..shared.types import UserId
+
+router = APIRouter()
+log = logging.getLogger(__name__)
+
+
+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.get("/feedback", response_model=list[Feedback], tags=["Feedback"])
+async def get_feedback(
+    request: FastAPIRequest,
+    start_date: str | None = None,
+    end_date: str | None = None,
+    task_id: str | None = None,
+    session_id: str | None = None,
+    rating: Literal["up", "down"] | None = None,
+    page: int = 1,
+    page_size: int = 20,
+    query_user_id: str | None = None,
+    db: DBSession = Depends(get_db),
+    user_id: UserId = Depends(get_user_id),
+    user_config: dict = Depends(get_user_config),
+    task_repo: ITaskRepository = Depends(get_task_repository),
+):
+    """
+    Retrieves feedback with flexible filtering and security controls.
+
+    Regular users can only view their own feedback.
+    Users with the 'feedback:read:all' scope can view any user's feedback.
+
+    Query Parameters:
+    - start_date: Filter feedback created after this date (ISO 8601 format)
+    - end_date: Filter feedback created before this date (ISO 8601 format)
+    - task_id: Filter by specific task ID
+    - session_id: Filter by specific session ID
+    - rating: Filter by rating type ("up" or "down")
+    - page: Page number (default: 1)
+    - page_size: Results per page (default: 20)
+    - query_user_id: (Admin only) Query feedback for a specific user
+    """
+    log_prefix = "[GET /api/v1/feedback] "
+    log.info("%sRequest from user %s", log_prefix, user_id)
+
+    # Determine target user and permissions
+    target_user_id = user_id
+    can_query_all = user_config.get("scopes", {}).get("feedback:read:all", False)
+
+    if query_user_id:
+        if can_query_all:
+            target_user_id = query_user_id
+            log.info(
+                "%sAdmin user %s is querying feedback for user %s",
+                log_prefix,
+                user_id,
+                target_user_id,
+            )
+        else:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="You do not have permission to query other users' feedback.",
+            )
+    elif can_query_all:
+        target_user_id = "*"
+        log.info("%sAdmin user %s is querying feedback for all users.", log_prefix, user_id)
+
+    # Verify task ownership if task_id filter is provided
+    if task_id:
+        task = task_repo.find_by_id(db, task_id)
+        if not task:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Task with ID '{task_id}' not found.",
+            )
+        if task.user_id != user_id and not can_query_all:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="You do not have permission to view feedback for this task.",
+            )
+
+    # Parse date filters
+    start_time_ms = None
+    if start_date:
+        try:
+            start_time_ms = int(datetime.fromisoformat(start_date).timestamp() * 1000)
+        except ValueError:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Invalid start_date format. Use ISO 8601 format.",
+            )
+
+    end_time_ms = None
+    if end_date:
+        try:
+            end_time_ms = int(datetime.fromisoformat(end_date).timestamp() * 1000)
+        except ValueError:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Invalid end_date format. Use ISO 8601 format.",
+            )
+
+    pagination = PaginationParams(page_number=page, page_size=page_size)
+
+    try:
+        repo = FeedbackRepository()
+        feedback_list = repo.search(
+            db,
+            user_id=target_user_id,
+            start_date=start_time_ms,
+            end_date=end_time_ms,
+            task_id=task_id,
+            session_id=session_id,
+            rating=rating,
+            pagination=pagination,
+        )
+        log.info("%sReturning %d feedback entries", log_prefix, len(feedback_list))
+        return feedback_list
+    except Exception as e:
+        log.exception("%sError searching for feedback: %s", log_prefix, e)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="An error occurred while searching for feedback.",
+        )
+
+
+@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"}

solace_agent_mesh/gateway/http_sse/routers/people.py

@@ -0,0 +1,38 @@
+"""
+API endpoints for people-related features, such as user search for autocomplete.
+"""
+
+import logging
+from typing import Any, Dict, List
+
+from fastapi import APIRouter, Depends, Query
+
+from ..dependencies import get_people_service
+from ..services.people_service import PeopleService
+from ..shared.pagination import DataResponse
+from ..shared.response_utils import create_data_response
+
+log = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+@router.get("/people/search", response_model=DataResponse[List[Dict[str, Any]]])
+async def search_people(
+    q: str = Query(
+        ...,
+        min_length=2,
+        max_length=50,
+        description="Search query for user name/email.",
+    ),
+    limit: int = Query(
+        10, ge=1, le=25, description="Maximum number of results to return."
+    ),
+    people_service: PeopleService = Depends(get_people_service),
+):
+    """
+    Searches for users to populate frontend autocomplete suggestions (e.g., for @mentions).
+    """
+    log.debug("Endpoint /people/search called with query: '%s'", q)
+    results = await people_service.search_for_users(query=q, limit=limit)
+    return create_data_response(results)