solace-agent-mesh 1.6.3__py3-none-any.whl → 1.7.1__py3-none-any.whl

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

@@ -1,13 +1,13 @@
 # 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.
+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 and task operations, providing type-safe interfaces for API endpoints with field aliasing and validation.
 
 ## 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)
+  - `requests/` - Request DTOs for API endpoint validation (session and task CRUD operations)
   - `responses/` - Response DTOs with automatic timestamp serialization and field aliasing
 
 ## Developer API Reference
@@ -25,26 +25,27 @@ The `dto` directory contains Data Transfer Objects (DTOs) for API contract defin
 ### Subdirectory APIs
 
 #### requests/
-**Purpose:** Provides Pydantic models for validating incoming API requests, specifically for session management operations
-**Key Exports:** GetSessionsRequest, GetSessionRequest, GetSessionHistoryRequest, UpdateSessionRequest, DeleteSessionRequest
+**Purpose:** Provides Pydantic models for validating incoming API requests for session management and task operations
+**Key Exports:** GetSessionRequest, UpdateSessionRequest, SaveTaskRequest
 **Import Examples:**
 ```python
 from solace_agent_mesh.gateway.http_sse.routers.dto.requests import (
     GetSessionRequest,
-    GetSessionHistoryRequest,
-    UpdateSessionRequest
+    UpdateSessionRequest,
+    SaveTaskRequest
 )
 ```
 
 #### responses/
 **Purpose:** Provides structured response DTOs with automatic timestamp conversion and field aliasing for API consistency
-**Key Exports:** MessageResponse, SessionResponse, SessionListResponse, BaseTimestampResponse
+**Key Exports:** SessionResponse, SessionListResponse, TaskResponse, TaskListResponse, BaseTimestampResponse
 **Import Examples:**
 ```python
 from solace_agent_mesh.gateway.http_sse.routers.dto.responses import (
-    MessageResponse,
     SessionResponse,
-    SessionListResponse
+    SessionListResponse,
+    TaskResponse,
+    TaskListResponse
 )
 ```
 
@@ -59,22 +60,22 @@ 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
+    UpdateSessionRequest,
+    SaveTaskRequest
 )
 from solace_agent_mesh.gateway.http_sse.routers.dto.responses import (
     SessionResponse,
-    MessageResponse,
-    SessionListResponse
+    SessionListResponse,
+    TaskResponse,
+    TaskListResponse
 )
 ```
 
-### 2. Working with Request DTOs
+### 2. Working with Session Request DTOs
 
 ```python
 from solace_agent_mesh.gateway.http_sse.routers.dto.requests import (
     GetSessionRequest,
-    GetSessionHistoryRequest,
     UpdateSessionRequest
 )
 from pydantic import ValidationError
@@ -91,42 +92,64 @@ def get_session(session_id: str, user_id: str):
         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):
+# Create a request to update session name
+def update_session_name(session_id: str, user_id: str, new_name: str):
     try:
-        request = GetSessionHistoryRequest(
+        request = UpdateSessionRequest(
             session_id=session_id,
             user_id=user_id,
-            pagination={"page": page, "size": size}
+            name=new_name  # Automatically validated (1-255 characters)
         )
         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):
+### 3. Working with Task Request DTOs
+
+```python
+from solace_agent_mesh.gateway.http_sse.routers.dto.requests import SaveTaskRequest
+from pydantic import ValidationError
+import json
+
+# Create a save task request with camelCase field names (API style)
+def save_task_with_validation(task_id: str, message_bubbles: list, user_message: str = None, metadata: dict = None):
     try:
-        request = UpdateSessionRequest(
-            session_id=session_id,
-            user_id=user_id,
-            name=new_name  # Automatically validated (1-255 characters)
+        # Convert data to JSON strings as required
+        bubbles_json = json.dumps(message_bubbles)
+        metadata_json = json.dumps(metadata) if metadata else None
+        
+        request = SaveTaskRequest(
+            task_id=task_id,
+            user_message=user_message,
+            message_bubbles=bubbles_json,
+            task_metadata=metadata_json
         )
         return request
     except ValidationError as e:
-        print(f"Validation failed: {e}")
+        print(f"Task validation failed: {e}")
         return None
+
+# Example usage
+task_request = save_task_with_validation(
+    task_id="task_123",
+    message_bubbles=[
+        {"type": "user", "content": "Hello"},
+        {"type": "assistant", "content": "Hi there!"}
+    ],
+    user_message="Please analyze this data",
+    metadata={"priority": "high", "category": "analysis"}
+)
 ```
 
-### 3. Working with Response DTOs
+### 4. Working with Session 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
@@ -140,18 +163,6 @@ def create_session_response(session_data: dict) -> SessionResponse:
         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]
@@ -162,19 +173,47 @@ def create_session_list_response(sessions: list, total: int) -> SessionListRespo
     )
 ```
 
-### 4. Complete API Endpoint Example
+### 5. Working with Task Response DTOs
+
+```python
+from solace_agent_mesh.gateway.http_sse.routers.dto.responses import (
+    TaskResponse,
+    TaskListResponse
+)
+import json
+import time
+
+# Create task responses
+def create_task_response(task_data: dict) -> TaskResponse:
+    return TaskResponse(
+        task_id=task_data["task_id"],
+        session_id=task_data["session_id"],
+        user_message=task_data.get("user_message"),
+        message_bubbles=json.dumps(task_data["message_bubbles"]),
+        task_metadata=json.dumps(task_data["metadata"]) if task_data.get("metadata") else None,
+        created_time=int(time.time() * 1000),
+        updated_time=task_data.get("updated_time")
+    )
+
+# Create task list responses
+def create_task_list_response(tasks: list) -> TaskListResponse:
+    task_responses = [create_task_response(task) for task in tasks]
+    return TaskListResponse(tasks=task_responses)
+```
+
+### 6. Complete API Endpoint Examples
 
 ```python
 from fastapi import APIRouter, HTTPException
 from solace_agent_mesh.gateway.http_sse.routers.dto.requests import (
     GetSessionRequest,
-    GetSessionHistoryRequest,
-    UpdateSessionRequest
+    UpdateSessionRequest,
+    SaveTaskRequest
 )
 from solace_agent_mesh.gateway.http_sse.routers.dto.responses import (
     SessionResponse,
-    MessageResponse,
-    SessionListResponse
+    SessionListResponse,
+    TaskResponse
 )
 
 router = APIRouter()
@@ -200,39 +239,6 @@ async def get_session(session_id: str, user_id: str) -> SessionResponse:
         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,
@@ -262,13 +268,45 @@ async def update_session(
         created_time=updated_session["created_time"],
         updated_time=updated_session["updated_time"]
     )
+
+@router.post("/tasks")
+async def save_task(
+    task_id: str,
+    message_bubbles: str,
+    user_message: str = None,
+    task_metadata: str = None
+) -> TaskResponse:
+    """Save a new task"""
+    
+    # Validate request using DTO
+    try:
+        request = SaveTaskRequest(
+            task_id=task_id,
+            user_message=user_message,
+            message_bubbles=message_bubbles,
+            task_metadata=task_metadata
+        )
+    except ValidationError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    
+    # Save task (mock implementation)
+    saved_task = save_task_to_db(request)
+    
+    # Return response DTO
+    return TaskResponse(
+        task_id=saved_task["task_id"],
+        session_id=saved_task["session_id"],
+        user_message=saved_task["user_message"],
+        message_bubbles=saved_task["message_bubbles"],
+        task_metadata=saved_task["task_metadata"],
+        created_time=saved_task["created_time"]
+    )
 ```
 
-### 5. JSON Serialization with Automatic Timestamp Conversion
+### 7. 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
+from solace_agent_mesh.gateway.http_sse.routers.dto.responses import SessionResponse, TaskResponse
 import json
 
 # Create a session response
@@ -291,25 +329,24 @@ print(json_output)
 #   "updatedTime": "2022-01-01T00:01:00Z"
 # }
 
-# Create a message response with field aliasing
-message = MessageResponse(
-    id="msg_789",
+# Create a task response with field aliasing
+task = TaskResponse(
+    task_id="task_789",
     session_id="sess_123",
-    message="Hello world",
-    sender_type=SenderType.USER,
-    sender_name="John Doe",
-    message_type=MessageType.TEXT,
+    user_message="Process this data",
+    message_bubbles='[{"type": "text", "content": "Processing..."}]',
+    task_metadata='{"priority": "high"}',
     created_time=1640995200000
 )
 
 # Get dict with converted timestamps and aliased fields
-dict_output = message.model_dump()
+dict_output = task.model_dump()
+print(dict_output["taskId"])  # "task_789" (camelCase alias)
 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
+### 8. Custom Response Classes Using Base
 
 ```python
 from solace_agent_mesh.gateway.http_sse.routers.dto.responses.base_responses import BaseTimestampResponse
@@ -341,6 +378,73 @@ 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.
+### 9. Working with Both Requests and Responses Together
+
+```python
+from solace_agent_mesh.gateway.http_sse.routers.dto.requests import UpdateSessionRequest, SaveTaskRequest
+from solace_agent_mesh.gateway.http_sse.routers.dto.responses import SessionResponse, TaskResponse
+from pydantic import ValidationError
+import json
+
+async def complete_session_workflow():
+    """Example showing complete request/response workflow"""
+    
+    # 1. Validate incoming request data
+    try:
+        update_request = UpdateSessionRequest(
+            session_id="sess_123",
+            user_id="user_456",
+            name="Updated Session Name"
+        )
+    except ValidationError as e:
+        return {"error": f"Invalid session update request: {e}"}
+    
+    # 2. Process the request (mock database operation)
+    updated_session_data = {
+        "id": update_request.session_id,
+        "user_id": update_request.user_id,
+        "name": update_request.name,
+        "created_time": 1640995200000,
+        "updated_time": 1640995260000
+    }
+    
+    # 3. Create structured response
+    session_response = SessionResponse(**updated_session_data)
+    
+    # 4. Save a related task
+    try:
+        task_request = SaveTaskRequest(
+            task_id="task_456",
+            user_message="Session updated successfully",
+            message_bubbles=json.dumps([
+                {"type": "system", "content": "Session name updated"}
+            ]),
+            task_metadata=json.dumps({"action": "session_update"})
+        )
+    except ValidationError as e:
+        return {"error": f"Invalid task request: {e}"}
+    
+    # 5. Create task response
+    task_response = TaskResponse(
+        task_id=task_request.task_id,
+        session_id=update_request.session_id,
+        user_message=task_request.user_message,
+        message_bubbles=task_request.message_bubbles,
+        task_metadata=task_request.task_metadata,
+        created_time=1640995300000
+    )
+    
+    # 6. Return both responses with automatic field aliasing and timestamp conversion
+    return {
+        "session": session_response.model_dump(),
+        "task": task_response.model_dump()
+    }
+
+# Usage
+result = await complete_session_workflow()
+print(json.dumps(result, indent=2))
+```
+
+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 and field aliasing for both session management and task operations in the HTTP SSE gateway.
 
-# content_hash: 3bb29d4c46b962221fc3034560b7e0da75b5a41f7f8f4d4f25aecf26e10f83f5
+# content_hash: 4a446edeace8a993477cc29e6c5676bbeb9fc98ae411e799017a21b610e486be

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

@@ -1,42 +1,41 @@
 # 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.
+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 session-related request DTOs for easy importing
-- `session_requests.py` - Defines request DTOs for session CRUD operations (get, update, history retrieval)
+- `__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, GetSessionHistoryRequest, UpdateSessionRequest`
+**Import:** `from solace_agent_mesh.gateway.http_sse.routers.dto.requests import GetSessionRequest, UpdateSessionRequest, SaveTaskRequest`
 
 **Usage Examples:**
 ```python
-# Import all session request DTOs
+# Import all request DTOs
 from solace_agent_mesh.gateway.http_sse.routers.dto.requests import (
     GetSessionRequest,
-    GetSessionHistoryRequest,
-    UpdateSessionRequest
+    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, GetSessionHistoryRequest, UpdateSessionRequest`
+**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
-- `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
@@ -47,13 +46,6 @@ get_session_req = GetSessionRequest(
     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",
@@ -80,4 +72,62 @@ print(f"User ID: {update_req.user_id}")
 print(f"New name: {update_req.name}")
 ```
 
-# content_hash: d40151714f449905662170c71b393dba7c98e7ec1c46f5f3a861097b2d5376b2
+### 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

@@ -2,6 +2,7 @@
 Session-related request DTOs.
 """
 
+from typing import Optional
 from pydantic import BaseModel, Field
 
 from ....shared.types import SessionId, UserId
@@ -10,6 +11,7 @@ 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
 
 
@@ -18,3 +20,14 @@ class UpdateSessionRequest(BaseModel):
     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/responses/project_responses.py

@@ -0,0 +1,30 @@
+"""
+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")
+    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