solace-agent-mesh 0.2.4__py3-none-any.whl → 1.0.1__py3-none-any.whl

solace_agent_mesh/gateway/base/task_context.py

@@ -0,0 +1,74 @@
+"""
+Manages context for tasks being processed by a gateway.
+"""
+
+import threading
+from typing import Dict, Optional, Any
+
+from solace_ai_connector.common.log import log
+
+
+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,125 @@
+Here is the comprehensive developer guide for the `gateway` directory.
+
+## Quick Summary
+The `gateway` directory provides a comprehensive framework for building gateway implementations that bridge external platforms with the Solace AI Connector's A2A (Agent-to-Agent) messaging system. The architecture consists of a foundational base framework and three specialized gateway implementations: HTTP/SSE for web interfaces, Slack for team collaboration, and Webhook for external system integration. All gateways share common patterns for authentication, message translation, and real-time communication while providing platform-specific features.
+
+## Files and Subdirectories Overview
+- **Direct files:**
+  - `__init__.py`: Marks the directory as a Python package.
+- **Subdirectories:**
+  - `base/`: Foundational classes and utilities for building all gateway implementations.
+  - `http_sse/`: A complete HTTP/SSE gateway with a FastAPI web server for real-time web UI backends.
+  - `slack/`: A gateway for integrating with the Slack collaboration platform.
+  - `webhook/`: A universal webhook gateway for receiving HTTP requests from external systems.
+
+## Developer API Reference
+
+### Direct Files
+
+#### __init__.py
+**Purpose:** Initializes the `gateway` module, making it a Python package.
+**Import:** `from gateway import ...`
+
+**Classes/Functions/Constants:**
+This file is empty and contains no direct exports.
+
+### Subdirectory APIs
+
+#### base/
+**Purpose:** Provides the foundational, abstract classes for building all Gateway implementations. It establishes a framework for configuration, A2A message handling, and managing the lifecycle of requests from external platforms.
+**Key Exports:** `BaseGatewayApp`, `BaseGatewayComponent`, `TaskContextManager`
+**Import Examples:**
+```python
+from gateway.base.app import BaseGatewayApp
+from gateway.base.component import BaseGatewayComponent
+from gateway.base.task_context import TaskContextManager
+```
+
+**Key Modules:**
+
+*   **`app.py`**:
+    *   **`BaseGatewayApp`**: The main application class to be subclassed for a new gateway. It automates configuration schema merging, Solace broker setup, and component instantiation.
+        *   `_get_gateway_component_class(self)`: **[Abstract Method]** Subclasses must implement this to return their specific gateway component class.
+
+*   **`component.py`**:
+    *   **`BaseGatewayComponent`**: The abstract base class for gateway logic. Subclasses implement the abstract methods to define how the gateway interacts with its specific external platform.
+        *   **Public Methods**:
+            *   `submit_a2a_task(...)`: The primary method for submitting a task to an agent on behalf of an external user.
+            *   `publish_a2a_message(...)`: A lower-level method to publish any message to the A2A message bus.
+        *   **Abstract Methods to Implement**:
+            *   `_extract_initial_claims(self, external_event_data)`: Extracts user identity from a platform-specific event.
+            *   `_start_listener(self)` / `_stop_listener(self)`: Manages the lifecycle of the external platform listener (e.g., a web server).
+            *   `_translate_external_input(self, external_event)`: Translates an incoming event from the external platform into the A2A protocol format.
+            *   `_send_update_to_external(...)`: Sends a streaming update back to the external platform.
+            *   `_send_final_response_to_external(...)`: Sends the final task result back to the external platform.
+            *   `_send_error_to_external(...)`: Sends an error message back to the external platform.
+
+*   **`task_context.py`**:
+    *   **`TaskContextManager`**: A thread-safe dictionary-like class for mapping A2A task IDs to the original request context from the external platform. This is crucial for routing responses back to the correct user/channel/thread.
+
+#### http_sse/
+**Purpose:** Implements a complete HTTP/SSE gateway to serve a web-based user interface, bridging web protocols with the backend A2A messaging fabric.
+**Key Exports:** `WebUIBackendApp`, `WebUIBackendComponent`, `SSEManager`, `SessionManager`, and various dependency injectors.
+**Import Examples:**
+```python
+from gateway.http_sse.app import WebUIBackendApp
+from gateway.http_sse.component import WebUIBackendComponent
+from gateway.http_sse.sse_manager import SSEManager
+from gateway.http_sse.session_manager import SessionManager
+from gateway.http_sse.dependencies import get_agent_service, get_task_service, get_user_id
+```
+
+**Key Modules & Exports:**
+
+*   **`app.py`**:
+    *   **`WebUIBackendApp`**: The main SAC App class that defines the configuration schema and launches the `WebUIBackendComponent`.
+*   **`component.py`**:
+    *   **`WebUIBackendComponent`**: The core component that hosts the FastAPI server, manages shared state, and implements the A2A translation logic for HTTP requests.
+*   **`session_manager.py`**:
+    *   **`SessionManager`**: Manages web user sessions, creating and tracking unique A2A client and session IDs from HTTP requests.
+*   **`sse_manager.py`**:
+    *   **`SSEManager`**: Manages Server-Sent Event (SSE) connections, allowing for real-time, streaming updates to be pushed from the server to connected web clients.
+*   **`dependencies.py`**:
+    *   Provides FastAPI dependency injectors for giving API routers safe access to shared resources (e.g., `get_agent_service`, `get_task_service`, `get_sac_component`).
+*   **`services/`**:
+    *   **`AgentService`**, **`TaskService`**: Contain the business logic for interacting with agents and managing tasks, respectively. These are accessed via the dependency injectors.
+
+#### slack/
+**Purpose:** Provides a gateway for integrating the Solace AI Connector with the Slack collaboration platform, enabling bot interactions within Slack channels and threads.
+**Key Exports:** `SlackGatewayApp`, `SlackGatewayComponent`, and various utility functions.
+**Import Examples:**
+```python
+from gateway.slack.app import SlackGatewayApp
+from gateway.slack.component import SlackGatewayComponent
+from gateway.slack.utils import generate_a2a_session_id, send_slack_message, correct_slack_markdown
+```
+
+#### webhook/
+**Purpose:** Provides a universal webhook gateway for receiving HTTP requests from external systems and triggering A2A tasks. It is highly configurable for different authentication methods, payload formats, and target agents.
+**Key Exports:** `WebhookGatewayApp`, `WebhookGatewayComponent`
+**Import Examples:**
+```python
+from gateway.webhook.app import WebhookGatewayApp
+from gateway.webhook.component import WebhookGatewayComponent
+from gateway.webhook.dependencies import get_sac_component
+```
+
+## Complete Usage Guide
+This guide provides practical examples of how to use the components and frameworks within the `gateway` directory.
+
+### 1. How to Create a Custom Gateway
+This example shows how to use the `base` module to build a new gateway for a hypothetical external platform.
+
+```python
+# my_gateway/app.py
+from gateway.base.app import BaseGatewayApp
+from .component import MyGatewayComponent
+
+class MyGatewayApp(BaseGatewayApp):
+    """Defines the application and its configuration for My Platform."""
+    SPECIFIC_APP_SCHEMA_PARAMS = [
+        {
+            "name": "my_platform_api_key",
+            "required": True,
+            "type": "string",
+            "

solace_agent_mesh/gateway/http_sse/app.py

@@ -0,0 +1,190 @@
+"""
+Custom Solace AI Connector App class for the Web UI Backend.
+Defines configuration schema and programmatically creates the WebUIBackendComponent.
+"""
+
+from typing import Any, Dict, List
+from solace_ai_connector.common.log import log
+
+from ...gateway.http_sse.component import WebUIBackendComponent
+
+from ...gateway.base.app import BaseGatewayApp
+from ...gateway.base.component import BaseGatewayComponent
+
+
+info = {
+    "class_name": "WebUIBackendApp",
+    "description": "Custom App class for the A2A Web UI Backend with automatic subscription generation.",
+}
+
+
+class WebUIBackendApp(BaseGatewayApp):
+    """
+    Custom App class for the A2A Web UI Backend.
+    - Extends BaseGatewayApp for common gateway functionalities.
+    - Defines WebUI-specific configuration parameters.
+    """
+
+    SPECIFIC_APP_SCHEMA_PARAMS: List[Dict[str, Any]] = [
+        {
+            "name": "session_secret_key",
+            "required": True,
+            "type": "string",
+            "description": "Secret key for signing web user sessions.",
+        },
+        {
+            "name": "fastapi_host",
+            "required": False,
+            "type": "string",
+            "default": "127.0.0.1",
+            "description": "Host address for the embedded FastAPI server.",
+        },
+        {
+            "name": "fastapi_port",
+            "required": False,
+            "type": "integer",
+            "default": 8000,
+            "description": "Port for the embedded FastAPI server.",
+        },
+        {
+            "name": "fastapi_https_port",
+            "required": False,
+            "type": "integer",
+            "default": 8443,
+            "description": "Port for the embedded FastAPI server when SSL is enabled.",
+        },
+        {
+            "name": "cors_allowed_origins",
+            "required": False,
+            "type": "list",
+            "default": ["*"],
+            "description": "List of allowed origins for CORS requests.",
+        },
+        {
+            "name": "sse_max_queue_size",
+            "required": False,
+            "type": "integer",
+            "default": 200,
+            "description": "Maximum size of the SSE connection queues. Adjust based on expected load.",
+        },
+        {
+            "name": "resolve_artifact_uris_in_gateway",
+            "required": False,
+            "type": "boolean",
+            "default": True,
+            "description": "If true, the gateway will resolve artifact:// URIs found in A2A messages and embed the content as bytes before sending to the UI. If false, URIs are passed through.",
+        },
+        {
+            "name": "system_purpose",
+            "required": False,
+            "type": "string",
+            "default": "",
+            "description": "Detailed description of the system's overall purpose, to be optionally used by agents.",
+        },
+        {
+            "name": "response_format",
+            "required": False,
+            "type": "string",
+            "default": "",
+            "description": "General guidelines on how agent responses should be structured, to be optionally used by agents.",
+        },
+        {
+            "name": "frontend_welcome_message",
+            "required": False,
+            "type": "string",
+            "default": "Hi! How can I help?",
+            "description": "Initial welcome message displayed in the chat.",
+        },
+        {
+            "name": "frontend_bot_name",
+            "required": False,
+            "type": "string",
+            "default": "A2A Agent",
+            "description": "Name displayed for the bot/agent in the UI.",
+        },
+        {
+            "name": "frontend_collect_feedback",
+            "required": False,
+            "type": "boolean",
+            "default": False,
+            "description": "Enable/disable the feedback buttons in the UI.",
+        },
+        {
+            "name": "frontend_auth_login_url",
+            "required": False,
+            "type": "string",
+            "default": "",
+            "description": "URL for the external login page (if auth is enabled).",
+        },
+        {
+            "name": "frontend_use_authorization",
+            "required": False,
+            "type": "boolean",
+            "default": False,
+            "description": "Tell frontend whether backend expects authorization.",
+        },
+        {
+            "name": "frontend_redirect_url",
+            "required": False,
+            "type": "string",
+            "default": "",
+            "description": "Redirect URL for OAuth flows (if auth is enabled).",
+        },
+        {
+            "name": "external_auth_callback_uri",
+            "required": False,
+            "type": "string",
+            "default": "",
+            "description": "Redirect URI for the OIDC application.",
+        },
+        {
+            "name": "external_auth_service_url",
+            "required": False,
+            "type": "string",
+            "default": "http://localhost:8080",
+            "description": "External authorization service URL for login initiation.",
+        },
+        {
+            "name": "external_auth_provider",
+            "required": False,
+            "type": "string",
+            "default": "",
+            "description": "The external authentication provider.",
+        },
+        {
+            "name": "ssl_keyfile",
+            "required": False,
+            "type": "string",
+            "default": "",
+            "description": "The file path to the SSL private key.",
+        },
+        {
+            "name": "ssl_certfile",
+            "required": False,
+            "type": "string",
+            "default": "",
+            "description": "The file path to the SSL certificate.",
+        },
+        {
+            "name": "ssl_keyfile_password",
+            "required": False,
+            "type": "string",
+            "default": "",
+            "description": "The passphrase for the SSL private key.",
+        },
+    ]
+
+    def __init__(self, app_info: Dict[str, Any], **kwargs):
+        """
+        Initializes the WebUIBackendApp.
+        Most setup is handled by BaseGatewayApp.
+        """
+        log.debug(
+            "%s Initializing WebUIBackendApp...",
+            app_info.get("name", "WebUIBackendApp"),
+        )
+        super().__init__(app_info=app_info, **kwargs)
+        log.debug("%s WebUIBackendApp initialization complete.", self.name)
+
+    def _get_gateway_component_class(self) -> type[BaseGatewayComponent]:
+        return WebUIBackendComponent