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

solace_agent_mesh/gateway/base/task_context.py

@@ -0,0 +1,75 @@
+"""
+Manages context for tasks being processed by a gateway.
+"""
+
+import logging
+import threading
+from typing import Dict, Optional, Any
+
+log = logging.getLogger(__name__)
+
+
+class TaskContextManager:
+    """
+    Stores and retrieves arbitrary context associated with an A2A task_id.
+
+    This context is typically provided by a specific gateway implementation
+    (e.g., Slack channel/thread, HTTP session details) and is needed to
+    route responses back correctly to the external system.
+
+    The manager is thread-safe.
+    """
+
+    def __init__(self):
+        """Initializes the TaskContextManager."""
+        self._contexts: Dict[str, Dict[str, Any]] = {}
+        self._lock = threading.Lock()
+        log.debug("[TaskContextManager] Initialized.")
+
+    def store_context(self, task_id: str, context_data: Dict[str, Any]) -> None:
+        """
+        Stores context data for a given task ID.
+
+        Args:
+            task_id: The unique identifier for the task.
+            context_data: A dictionary containing the context to store.
+        """
+        with self._lock:
+            self._contexts[task_id] = context_data
+        log.debug("[TaskContextManager] Stored context for task_id: %s", task_id)
+
+    def get_context(self, task_id: str) -> Optional[Dict[str, Any]]:
+        """
+        Retrieves the context data for a given task ID.
+
+        Args:
+            task_id: The unique identifier for the task.
+
+        Returns:
+            The context data dictionary if found, otherwise None.
+        """
+        with self._lock:
+            context = self._contexts.get(task_id)
+        log.debug(
+            "[TaskContextManager] Retrieved context for task_id: %s (Found: %s)",
+            task_id,
+            context is not None,
+        )
+        return context
+
+    def remove_context(self, task_id: str) -> Optional[Dict[str, Any]]:
+        """Removes and returns the context data for a given task ID."""
+        with self._lock:
+            context = self._contexts.pop(task_id, None)
+        log.debug(
+            "[TaskContextManager] Removed context for task_id: %s (Found: %s)",
+            task_id,
+            context is not None,
+        )
+        return context
+
+    def clear_all_contexts_for_testing(self) -> None:
+        """Removes all stored contexts. For testing purposes."""
+        with self._lock:
+            self._contexts.clear()
+        log.debug("[TaskContextManager] All contexts cleared for testing.")

solace_agent_mesh/gateway/gateway_llm.txt

@@ -0,0 +1,369 @@
+# DEVELOPER GUIDE: gateway
+
+## Quick Summary
+The `gateway` directory provides a comprehensive framework for building gateways that connect external platforms (Slack, HTTP/SSE web interfaces) to the Solace AI Connector's A2A (Agent-to-Agent) messaging system. The architecture consists of a foundational `base` module that defines abstract classes for gateway implementations, and specific gateway implementations like `slack` for Slack integration and `http_sse` for web-based interfaces. The framework handles authentication, message translation between external formats and A2A protocol, real-time streaming updates, and manages the complete lifecycle of requests from external platforms to AI agents.
+
+## Files and Subdirectories Overview
+- **Direct files:**
+  - `__init__.py`: Standard Python package initializer
+  - `gateway_llm.txt`: Documentation or configuration file for LLM-related gateway functionality
+  - `gateway_llm_detail.txt`: Comprehensive documentation combining all gateway module summaries
+
+- **Subdirectories:**
+  - `base/`: Foundational abstract classes and utilities for building gateway implementations
+  - `http_sse/`: HTTP/Server-Sent Events gateway for web-based user interfaces
+
+## Developer API Reference
+
+### Direct Files
+
+#### __init__.py
+**Purpose:** Initializes the `gateway` Python package
+**Import:** `from solace_agent_mesh.gateway import ...`
+
+**Classes/Functions/Constants:**
+This file is empty and contains no direct exports.
+
+#### gateway_llm.txt
+**Purpose:** Documentation or configuration file for LLM-related gateway functionality
+**Import:** Not applicable (text/documentation file)
+
+**Content:** This appears to be a documentation or configuration file rather than executable code.
+
+#### gateway_llm_detail.txt
+**Purpose:** Comprehensive documentation combining all individual LLM summary files from the gateway directory tree
+**Import:** Not applicable (text/documentation file)
+
+**Content:** Contains concatenated developer guides for all gateway subdirectories and components.
+
+### Subdirectory APIs
+
+#### base/
+**Purpose:** Provides foundational abstract classes for building Gateway implementations
+**Key Exports:** `BaseGatewayApp`, `BaseGatewayComponent`, `TaskContextManager`
+**Import Examples:**
+```python
+from solace_agent_mesh.gateway.base.app import BaseGatewayApp
+from solace_agent_mesh.gateway.base.component import BaseGatewayComponent
+from solace_agent_mesh.gateway.base.task_context import TaskContextManager
+```
+
+#### http_sse/
+**Purpose:** HTTP/Server-Sent Events gateway for web-based user interfaces with real-time streaming
+**Key Exports:** `WebUIBackendApp`, `WebUIBackendComponent`, `SSEManager`, `SessionManager`, routers, services
+**Import Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.app import WebUIBackendApp
+from solace_agent_mesh.gateway.http_sse.component import WebUIBackendComponent
+from solace_agent_mesh.gateway.http_sse.sse_manager import SSEManager
+from solace_agent_mesh.gateway.http_sse.dependencies import get_sse_manager, get_session_manager
+```
+
+## Complete Usage Guide
+
+### 1. Creating a Custom Gateway Implementation
+
+```python
+from typing import Type, List, Dict, Any, Optional, Tuple, Union
+from solace_agent_mesh.gateway.base.app import BaseGatewayApp
+from solace_agent_mesh.gateway.base.component import BaseGatewayComponent
+from solace_agent_mesh.common.a2a.types import ContentPart, TextPart
+from a2a.types import Task, TaskStatusUpdateEvent, TaskArtifactUpdateEvent, JSONRPCError
+
+# Step 1: Define your gateway app class
+class MyCustomGatewayApp(BaseGatewayApp):
+    """Custom gateway for My Platform integration."""
+    
+    # Define platform-specific configuration parameters
+    SPECIFIC_APP_SCHEMA_PARAMS: List[Dict[str, Any]] = [
+        {
+            "name": "my_platform_api_key",
+            "required": True,
+            "type": "string",
+            "description": "API key for My Platform"
+        },
+        {
+            "name": "my_platform_webhook_url",
+            "required": False,
+            "type": "string",
+            "description": "Webhook URL for receiving events"
+        },
+        {
+            "name": "default_agent_name",
+            "required": False,
+            "type": "string",
+            "default": "assistant",
+            "description": "Default agent to route messages to"
+        }
+    ]
+
+    def _get_gateway_component_class(self) -> Type[BaseGatewayComponent]:
+        return MyCustomGatewayComponent
+
+# Step 2: Implement your gateway component
+class MyCustomGatewayComponent(BaseGatewayComponent):
+    """Component implementing My Platform integration logic."""
+    
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self.api_key = self.get_config("my_platform_api_key")
+        self.webhook_url = self.get_config("my_platform_webhook_url")
+        self.default_agent = self.get_config("default_agent_name", "assistant")
+        self.platform_client = None  # Initialize your platform client
+    
+    async def _extract_initial_claims(self, external_event_data: Any) -> Optional[Dict[str, Any]]:
+        """Extract user identity from platform event."""
+        # Example: Extract user ID from your platform's event structure
+        if hasattr(external_event_data, 'user_id'):
+            return {
+                "id": external_event_data.user_id,
+                "platform": "my_platform",
+                "username": getattr(external_event_data, 'username', None)
+            }
+        return None
+    
+    def _start_listener(self) -> None:
+        """Start your platform's event listener."""
+        # Example: Start webhook server, WebSocket connection, etc.
+        print(f"Starting My Platform listener on {self.webhook_url}")
+        # Initialize your platform client/listener here
+    
+    def _stop_listener(self) -> None:
+        """Stop your platform's event listener."""
+        print("Stopping My Platform listener")
+        # Clean up platform client/listener here
+    
+    async def _translate_external_input(self, external_event: Any) -> Tuple[str, List[ContentPart], Dict[str, Any]]:
+        """Convert platform event to A2A format."""
+        # Extract message content
+        message_text = getattr(external_event, 'message', '')
+        
+        # Determine target agent (could be extracted from message or use default)
+        target_agent = getattr(external_event, 'target_agent', self.default_agent)
+        
+        # Create A2A content parts
+        a2a_parts = [TextPart(text=message_text)]
+        
+        # Create context for tracking this request
+        context = {
+            "platform": "my_platform",
+            "event_id": getattr(external_event, 'id', ''),
+            "channel_id": getattr(external_event, 'channel_id', ''),
+            "user_id_for_artifacts": getattr(external_event, 'user_id', ''),
+            "a2a_session_id": f"my_platform_{getattr(external_event, 'session_id', '')}"
+        }
+        
+        return target_agent, a2a_parts, context
+    
+    async def _send_update_to_external(self, 
+                                     external_request_context: Dict[str, Any], 
+                                     event_data: Union[TaskStatusUpdateEvent, TaskArtifactUpdateEvent], 
+                                     is_final_chunk_of_update: bool) -> None:
+        """Send streaming update to your platform."""
+        channel_id = external_request_context.get("channel_id")
+        
+        # Extract text content from the event
+        if hasattr(event_data, 'text_delta'):
+            text_content = event_data.text_delta
+        elif hasattr(event_data, 'content'):
+            text_content = str(event_data.content)
+        else:
+            text_content = "Update received"
+        
+        # Send to your platform (example)
+        await self._send_to_platform(channel_id, text_content, is_partial=not is_final_chunk_of_update)
+    
+    async def _send_final_response_to_external(self, 
+                                             external_request_context: Dict[str, Any], 
+                                             task_data: Task) -> None:
+        """Send final response to your platform."""
+        channel_id = external_request_context.get("channel_id")
+        
+        # Extract final response from task data
+        final_response = "Task completed"
+        if task_data.result and hasattr(task_data.result, 'content'):
+            final_response = str(task_data.result.content)
+        
+        await self._send_to_platform(channel_id, final_response, is_final=True)
+    
+    async def _send_error_to_external(self, 
+                                     external_request_context: Dict[str, Any], 
+                                     error_data: JSONRPCError) -> None:
+        """Send error to your platform."""
+        channel_id = external_request_context.get("channel_id")
+        error_message = f"Error: {error_data.message}"
+        await self._send_to_platform(channel_id, error_message, is_error=True)
+    
+    async def _send_to_platform(self, channel_id: str, message: str, **kwargs):
+        """Helper method to send messages to your platform."""
+        # Implement your platform's message sending logic here
+        print(f"Sending to {channel_id}: {message}")
+
+# Step 3: Usage
+if __name__ == "__main__":
+    config = {
+        "name": "my-custom-gateway",
+        "namespace": "/myorg/prod",
+        "gateway_id": "my-gateway-01",
+        "my_platform_api_key": "your-api-key",
+        "my_platform_webhook_url": "https://my-webhook.example.com",
+        "default_agent_name": "my-assistant",
+        "solace_config": {
+            "broker_url": "tcp://localhost:55555",
+            "vpn_name": "default",
+            "username": "default",
+            "password": "default"
+        }
+    }
+    
+    app = MyCustomGatewayApp(app_info=config)
+    app.run()
+```
+
+### 2. Using the HTTP/SSE Gateway for Web Interfaces
+
+```python
+from solace_agent_mesh.gateway.http_sse.app import WebUIBackendApp
+from fastapi import APIRouter, Depends, Request
+from solace_agent_mesh.gateway.http_sse.dependencies import (
+    get_sse_manager, get_session_manager, get_core_a2a_service
+)
+
+# Configure web UI gateway
+webui_config = {
+    "name": "my-webui",
+    "session_secret_key": "your-secret-key",
+    "fastapi_host": "0.0.0.0",
+    "fastapi_port": 8000,
+    "namespace": "/myorg/prod",
+    "gateway_id": "webui-01",
+    "cors_allowed_origins": ["http://localhost:3000"],
+    "frontend_welcome_message": "Welcome to AI Assistant!",
+    "frontend_bot_name": "Assistant",
+    "frontend_enable_file_upload": True,
+    "frontend_enable_agent_selection": True,
+    
+    # Database for session persistence
+    "session_service": {
+        "type": "sql",
+        "database_url": "sqlite:///./sessions.db"
+    },
+    
+    # A2A system configuration
+    "solace_config": {
+        "broker_url": "tcp://localhost:55555",
+        "vpn_name": "default",
+        "username": "default",
+        "password": "default"
+    }
+}
+
+# Create custom router for additional endpoints
+custom_router = APIRouter(prefix="/api/custom")
+
+@custom_router.get("/my-endpoint")
+async def my_custom_endpoint(
+    request: Request,
+    sse_manager = Depends(get_sse_manager),
+    session_manager = Depends(get_session_manager)
+):
+    """Custom endpoint with access to gateway services."""
+    user_id = session_manager.get_a2a_client_id(request)
+    return {"user_id": user_id, "message": "Custom endpoint response"}
+
+# Create and run the web UI gateway
+webui_app = WebUIBackendApp(app_info=webui_config)
+webui_app.run()
+```
+
+### 3. Working with Task Context and Session Management
+
+```python
+from solace_agent_mesh.gateway.base.task_context import TaskContextManager
+from solace_agent_mesh.gateway.http_sse.session_manager import SessionManager
+
+# Task context management (used internally by gateways)
+context_manager = TaskContextManager()
+
+# Store context when submitting a task
+task_id = "task-123"
+context = {
+    "platform": "http_sse",
+    "session_id": "session-456",
+    "user_id": "user-789",
+    "client_id": "client-abc"
+}
+context_manager.store_context(task_id, context)
+
+# Retrieve context when processing response
+retrieved_context = context_manager.get_context(task_id)
+if retrieved_context:
+    # Send response back to original platform
+    session_id = retrieved_context["session_id"]
+
+# Session management for web interfaces
+session_manager = SessionManager(
+    secret_key="your-secret-key",
+    app_config={"session_timeout": 3600}
+)
+
+# In a FastAPI endpoint
+@app.get("/api/session-info")
+async def get_session_info(request: Request):
+    # Get A2A client ID for this web session
+    client_id = session_manager.get_a2a_client_id(request)
+    
+    # Ensure we have an A2A session
+    session_id = session_manager.ensure_a2a_session(request)
+    
+    return {
+        "client_id": client_id,
+        "session_id": session_id
+    }
+```
+
+### 4. Real-time Streaming with Server-Sent Events
+
+```python
+import asyncio
+import httpx
+import json
+from solace_agent_mesh.gateway.http_sse.sse_manager import SSEManager
+from solace_agent_mesh.gateway.http_sse.sse_event_buffer import SSEEventBuffer
+
+# Server-side SSE management
+sse_buffer = SSEEventBuffer(max_queue_size=100, max_age_seconds=300)
+sse_manager = SSEManager(max_queue_size=100, event_buffer=sse_buffer)
+
+# Create SSE connection for a task
+task_id = "task-123"
+sse_queue = sse_manager.create_sse_connection(task_id)
+
+# Send events to connected clients
+sse_manager.send_event(
+    task_id=task_id,
+    event_data={"message": "Task started", "progress": 0},
+    event_type="task_update"
+)
+
+# Client-side SSE consumption
+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}")
+```
+
+### 5. Database
+
+# content_hash: 0b7ed0154e912abecea7634ace04f072596af9b37780b6093ab5585b700d3d39