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

solace_agent_mesh/gateway/gateway_llm.txt

@@ -1,369 +0,0 @@
-# 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