solace-agent-mesh 1.6.1__py3-none-any.whl → 1.13.2__py3-none-any.whl

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

@@ -1,83 +0,0 @@
-# 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/responses/responses_llm.txt

@@ -1,107 +0,0 @@
-# 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/routers_llm.txt

@@ -1,314 +0,0 @@
-# DEVELOPER GUIDE for the routers directory
-
-## Quick Summary
-The `routers` directory contains FastAPI router modules that define the REST API endpoints for the HTTP SSE Gateway. Each router groups endpoints by functional domain (agent discovery, artifact management, authentication, sessions, etc.) and provides the primary interface for frontend applications and other clients to interact with the gateway. The routers work together to provide a complete web API with real-time capabilities through Server-Sent Events (SSE), along with comprehensive session management, artifact handling, and A2A message visualization.
-
-## Files and Subdirectories Overview
-- **Direct files:**
-  - `__init__.py` - Package initialization for router modules
-  - `agent_cards.py` - Agent discovery endpoints
-  - `artifacts.py` - Artifact management (upload, download, versioning)
-  - `auth.py` - Authentication flow endpoints (login, callback, refresh)
-  - `config.py` - Frontend configuration endpoint
-  - `feedback.py` - User feedback collection endpoints
-  - `people.py` - User search for autocomplete features
-  - `sessions.py` - Session management (CRUD operations)
-  - `sse.py` - Server-Sent Events streaming endpoint
-  - `tasks.py` - Task submission and management endpoints
-  - `users.py` - Current user information endpoint
-  - `visualization.py` - A2A message visualization streaming
-- **Subdirectories:**
-  - `dto/` - Data Transfer Objects for request/response validation
-
-## Developer API Reference
-
-### Direct Files
-
-#### __init__.py
-**Purpose:** Package initialization for the routers module
-**Import:** `from solace_agent_mesh.gateway.http_sse.routers import *`
-
-#### agent_cards.py
-**Purpose:** Provides REST endpoints for agent discovery
-**Import:** `from solace_agent_mesh.gateway.http_sse.routers.agent_cards import router`
-
-**Functions:**
-- `get_discovered_agent_cards() -> List[AgentCard]` - Retrieves all currently discovered A2A agents
-
-#### artifacts.py
-**Purpose:** Manages session-specific artifacts via REST endpoints with versioning and metadata support
-**Import:** `from solace_agent_mesh.gateway.http_sse.routers.artifacts import router, ArtifactUploadResponse`
-
-**Classes:**
-- `ArtifactUploadResponse(BaseModel)` - Response model for artifact uploads with camelCase fields
-
-**Functions:**
-- `upload_artifact_with_session(upload_file: UploadFile, sessionId: str, filename: str, metadata_json: str) -> ArtifactUploadResponse` - Uploads artifact with session management
-- `list_artifact_versions(session_id: str, filename: str) -> List[int]` - Lists available versions for an artifact
-- `list_artifacts(session_id: str) -> List[ArtifactInfo]` - Lists all artifacts in a session with metadata
-- `get_latest_artifact(session_id: str, filename: str) -> StreamingResponse` - Downloads latest artifact version with embed resolution
-- `get_specific_artifact_version(session_id: str, filename: str, version: Union[int, str]) -> StreamingResponse` - Downloads specific version
-- `get_artifact_by_uri(uri: str) -> StreamingResponse` - Downloads artifact by formal artifact:// URI
-- `upload_artifact(session_id: str, filename: str, upload_file: UploadFile, metadata_json: Optional[str]) -> Dict[str, Any]` - Uploads new artifact version with metadata
-- `delete_artifact(session_id: str, filename: str) -> Response` - Deletes artifact and all versions
-
-#### auth.py
-**Purpose:** Handles OAuth-based user authentication flow with external authorization service
-**Import:** `from solace_agent_mesh.gateway.http_sse.routers.auth import router`
-
-**Functions:**
-- `initiate_login(request: FastAPIRequest) -> RedirectResponse` - Starts OAuth login flow with external service
-- `get_csrf_token(response: Response) -> Dict[str, str]` - Generates and sets CSRF token
-- `auth_callback(request: FastAPIRequest) -> RedirectResponse` - Handles OAuth callback and token exchange
-- `refresh_token(request: FastAPIRequest) -> Dict[str, str]` - Refreshes access token using refresh token
-
-#### config.py
-**Purpose:** Provides frontend configuration settings including feature flags
-**Import:** `from solace_agent_mesh.gateway.http_sse.routers.config import router`
-
-**Functions:**
-- `get_app_config() -> Dict[str, Any]` - Returns frontend configuration including auth URLs, feature flags, and persistence settings
-
-#### feedback.py
-**Purpose:** Receives and processes user feedback on chat messages
-**Import:** `from solace_agent_mesh.gateway.http_sse.routers.feedback import router, FeedbackPayload`
-
-**Classes:**
-- `FeedbackPayload(BaseModel)` - Data model for feedback submission
-  - `task_id: str` - ID of the task being rated
-  - `session_id: str` - Session containing the task
-  - `feedback_type: Literal["up", "down"]` - Type of feedback
-  - `feedback_text: Optional[str]` - Optional text feedback
-
-**Functions:**
-- `submit_feedback(payload: FeedbackPayload, user_id: str) -> Dict[str, str]` - Processes user feedback asynchronously
-
-#### people.py
-**Purpose:** Provides user search functionality for autocomplete features
-**Import:** `from solace_agent_mesh.gateway.http_sse.routers.people import router`
-
-**Functions:**
-- `search_people(q: str, limit: int = 10) -> List[Dict[str, Any]]` - Searches for users for @mention autocomplete
-
-#### sessions.py
-**Purpose:** Manages user sessions including CRUD operations with persistence
-**Import:** `from solace_agent_mesh.gateway.http_sse.routers.sessions import router`
-
-**Functions:**
-- `get_all_sessions(page_number: int, page_size: int, user: dict) -> PaginatedResponse[SessionResponse]` - Lists user's sessions with pagination
-- `get_session(session_id: str, user: dict) -> DataResponse[SessionResponse]` - Gets session details with authorization
-- `get_session_history(session_id: str, user: dict) -> List[MessageResponse]` - Gets session message history
-- `update_session_name(session_id: str, name: str, user: dict) -> SessionResponse` - Updates session name with validation
-- `delete_session(session_id: str, user: dict) -> None` - Deletes session with cascade notifications
-
-#### sse.py
-**Purpose:** Provides Server-Sent Events endpoint for real-time streaming
-**Import:** `from solace_agent_mesh.gateway.http_sse.routers.sse import router`
-
-**Functions:**
-- `subscribe_to_task_events(task_id: str, request: FastAPIRequest) -> EventSourceResponse` - Establishes SSE connection for task updates with automatic cleanup
-
-#### tasks.py
-**Purpose:** Handles task submission, management, and historical search
-**Import:** `from solace_agent_mesh.gateway.http_sse.routers.tasks import router`
-
-**Functions:**
-- `search_tasks(start_date: Optional[str], end_date: Optional[str], search: Optional[str], page: int, page_size: int, query_user_id: Optional[str]) -> List[Task]` - Searches historical tasks with admin capabilities
-- `get_task_as_stim_file(task_id: str) -> Response` - Downloads complete task history as .stim file
-- `send_task_to_agent(request: FastAPIRequest, payload: SendMessageRequest) -> SendMessageSuccessResponse` - Submits non-streaming task
-- `subscribe_task_from_agent(request: FastAPIRequest, payload: SendStreamingMessageRequest) -> SendStreamingMessageSuccessResponse` - Submits streaming task
-- `cancel_agent_task(request: FastAPIRequest, taskId: str, payload: CancelTaskRequest) -> Dict[str, str]` - Cancels active task
-
-#### users.py
-**Purpose:** Provides current user information with authentication status
-**Import:** `from solace_agent_mesh.gateway.http_sse.routers.users import router`
-
-**Functions:**
-- `get_current_user_endpoint(user: dict) -> Dict[str, Any]` - Returns current user information with auth status
-
-#### visualization.py
-**Purpose:** Manages A2A message visualization streams for real-time monitoring
-**Import:** `from solace_agent_mesh.gateway.http_sse.routers.visualization import router, SubscriptionTarget, VisualizationSubscribeRequest`
-
-**Classes:**
-- `SubscriptionTarget(BaseModel)` - Defines visualization target
-  - `type: str` - Target type (e.g., "current_namespace_a2a_messages", "agent_a2a_messages")
-  - `identifier: Optional[str]` - Target identifier (namespace or agent name)
-- `VisualizationSubscribeRequest(BaseModel)` - Subscription request
-  - `subscription_targets: Optional[List[SubscriptionTarget]]` - Targets to monitor
-  - `client_stream_id: Optional[str]` - Client-generated stream ID for idempotency
-- `VisualizationSubscribeResponse(BaseModel)` - Subscription response with SSE URL
-- `VisualizationConfigUpdateRequest(BaseModel)` - Configuration update request
-- `VisualizationConfigUpdateResponse(BaseModel)` - Configuration update response
-
-**Functions:**
-- `subscribe_to_visualization_stream(request_data: VisualizationSubscribeRequest) -> VisualizationSubscribeResponse` - Starts visualization stream with authorization
-- `get_visualization_stream_events(stream_id: str) -> EventSourceResponse` - SSE endpoint for visualization events
-- `update_visualization_stream_config(stream_id: str, update_request: VisualizationConfigUpdateRequest) -> VisualizationConfigUpdateResponse` - Updates stream configuration
-- `unsubscribe_from_visualization_stream(stream_id: str) -> Response` - Terminates visualization stream
-
-### Subdirectory APIs
-
-#### dto/
-**Purpose:** Provides Data Transfer Objects for request/response validation and serialization with automatic timestamp conversion
-**Key Exports:** Request and response DTOs for session management with field validation and camelCase aliasing
-**Import Examples:**
-```python
-from solace_agent_mesh.gateway.http_sse.routers.dto.requests import GetSessionsRequest, UpdateSessionRequest
-from solace_agent_mesh.gateway.http_sse.routers.dto.responses import SessionResponse, MessageResponse
-```
-
-## Complete Usage Guide
-
-### 1. Setting Up Routers in FastAPI Application
-
-```python
-from fastapi import FastAPI
-from solace_agent_mesh.gateway.http_sse.routers import (
-    agent_cards,
-    artifacts,
-    auth,
-    config,
-    feedback,
-    people,
-    sessions,
-    sse,
-    tasks,
-    users,
-    visualization
-)
-
-app = FastAPI()
-
-# Include all routers with appropriate prefixes
-app.include_router(agent_cards.router, prefix="/api/v1", tags=["agents"])
-app.include_router(artifacts.router, prefix="/api/v1/artifacts", tags=["artifacts"])
-app.include_router(auth.router, prefix="/api/v1", tags=["auth"])
-app.include_router(config.router, prefix="/api/v1", tags=["config"])
-app.include_router(feedback.router, prefix="/api/v1", tags=["feedback"])
-app.include_router(people.router, prefix="/api/v1", tags=["people"])
-app.include_router(sessions.router, prefix="/api/v1", tags=["sessions"])
-app.include_router(sse.router, prefix="/api/v1/sse", tags=["sse"])
-app.include_router(tasks.router, prefix="/api/v1/tasks", tags=["tasks"])
-app.include_router(users.router, prefix="/api/v1/users", tags=["users"])
-app.include_router(visualization.router, prefix="/api/v1/visualization", tags=["visualization"])
-```
-
-### 2. Agent Discovery and Task Submission
-
-```python
-import httpx
-from a2a.types import SendStreamingMessageRequest, Message, MessagePart
-
-# Discover available agents
-async def get_available_agents():
-    async with httpx.AsyncClient() as client:
-        response = await client.get("http://localhost:8000/api/v1/agentCards")
-        return response.json()
-
-# Submit a streaming task to an agent
-async def submit_streaming_task(agent_name: str, message_text: str, session_id: str):
-    # Create message parts
-    parts = [MessagePart(text=message_text)]
-    
-    # Create message with metadata
-    message = Message(
-        parts=parts,
-        context_id=session_id,
-        metadata={"agent_name": agent_name}
-    )
-    
-    # Create request payload
-    payload = SendStreamingMessageRequest(
-        method="message:stream",
-        params={"message": message},
-        id="req_123"
-    )
-    
-    async with httpx.AsyncClient() as client:
-        response = await client.post(
-            "http://localhost:8000/api/v1/tasks/message:stream",
-            json=payload.model_dump()
-        )
-        return response.json()
-
-# Search historical tasks (admin users can query all users)
-async def search_historical_tasks(start_date: str = None, query_user_id: str = None):
-    params = {}
-    if start_date:
-        params["start_date"] = start_date
-    if query_user_id:
-        params["query_user_id"] = query_user_id
-    
-    async with httpx.AsyncClient() as client:
-        response = await client.get(
-            "http://localhost:8000/api/v1/tasks",
-            params=params
-        )
-        return response.json()
-```
-
-### 3. Real-time Event Streaming with SSE
-
-```python
-import asyncio
-import httpx
-import json
-
-# Client-side SSE connection for task events
-async def listen_to_task_events(task_id: str):
-    async with httpx.AsyncClient() as client:
-        async with client.stream(
-            "GET", 
-            f"http://localhost:8000/api/v1/sse/subscribe/{task_id}",
-            headers={"Accept": "text/event-stream"}
-        ) as response:
-            async for line in response.aiter_lines():
-                if line.startswith("data: "):
-                    event_data = line[6:]  # Remove "data: " prefix
-                    try:
-                        parsed_data = json.loads(event_data)
-                        print(f"Received event: {parsed_data}")
-                    except json.JSONDecodeError:
-                        print(f"Received raw data: {event_data}")
-
-# Client-side SSE connection for visualization
-async def listen_to_visualization_events(stream_id: str):
-    async with httpx.AsyncClient() as client:
-        async with client.stream(
-            "GET",
-            f"http://localhost:8000/api/v1/visualization/{stream_id}/events",
-            headers={"Accept": "text/event-stream"}
-        ) as response:
-            async for line in response.aiter_lines():
-                if line.startswith("data: "):
-                    event_data = line[6:]
-                    print(f"Visualization event: {event_data}")
-```
-
-### 4. Comprehensive Artifact Management
-
-```python
-import httpx
-import json
-from pathlib import Path
-
-# Upload an artifact with metadata using session-based endpoint
-async def upload_artifact_with_metadata(session_id: str, filename: str, file_path: Path, metadata: dict = None):
-    files = {"upload_file": (filename, file_path.open("rb"))}
-    data = {}
-    
-    if metadata:
-        data["metadata_json"] = json.dumps(metadata)
-    
-    async with httpx.AsyncClient() as client:
-        response = await client.post(
-            f"http://localhost:8000/api/v1/artifacts/{session_id}/{filename}",
-            files=files,
-            data=data
-        )
-        return response.json()
-
-# Upload artifact with automatic session creation
-
-# content_hash: a98ae1eb7e5483f6e9438569a4c3dd2df4d9992a968e84230d41cf18d2d34624