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

solace_agent_mesh/gateway/base/app.py

@@ -0,0 +1,345 @@
+"""
+Base App class for Gateway implementations in the Solace AI Connector.
+"""
+
+import logging
+import uuid
+from abc import abstractmethod
+from typing import Any, Dict, List, Type
+
+from solace_ai_connector.common.utils import deep_merge
+from solace_ai_connector.flow.app import App
+from solace_ai_connector.components.component_base import ComponentBase
+
+from ...common.a2a import (
+    get_discovery_topic,
+    get_gateway_response_subscription_topic,
+    get_gateway_status_subscription_topic,
+)
+
+log = logging.getLogger(__name__)
+
+
+class BaseGatewayComponent(ComponentBase):
+    pass
+
+
+BASE_GATEWAY_APP_SCHEMA: Dict[str, List[Dict[str, Any]]] = {
+    "config_parameters": [
+        {
+            "name": "namespace",
+            "required": True,
+            "type": "string",
+            "description": "Absolute topic prefix for A2A communication (e.g., 'myorg/dev').",
+        },
+        {
+            "name": "gateway_id",
+            "required": False,
+            "type": "string",
+            "default": None,
+            "description": "Unique ID for this gateway instance. Auto-generated if omitted.",
+        },
+        {
+            "name": "default_agent_name",
+            "required": False,
+            "type": "string",
+            "default": None,
+            "description": "Default agent to route messages to if not specified by the platform or user.",
+        },
+        {
+            "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": "artifact_service",
+            "required": True,
+            "type": "object",
+            "description": "Configuration for the SHARED ADK Artifact Service.",
+        },
+        {
+            "name": "enable_embed_resolution",
+            "required": False,
+            "type": "boolean",
+            "default": True,
+            "description": "Enable late-stage 'artifact_content' embed resolution in the gateway.",
+        },
+        {
+            "name": "gateway_max_artifact_resolve_size_bytes",
+            "required": False,
+            "type": "integer",
+            "default": 104857600,  # 100MB
+            "description": "Maximum size of an individual artifact's raw content for 'artifact_content' embeds and max total accumulated size for a parent artifact after internal recursive resolution.",
+        },
+        {
+            "name": "gateway_recursive_embed_depth",
+            "required": False,
+            "type": "integer",
+            "default": 12,
+            "description": "Maximum depth for recursively resolving 'artifact_content' embeds within files.",
+        },
+        {
+            "name": "artifact_handling_mode",
+            "required": False,
+            "type": "string",
+            "default": "reference",
+            "description": (
+                "How the gateway handles file parts from clients. "
+                "'reference': Save inline file bytes to the artifact store and replace with a URI. "
+                "'embed': Resolve file URIs and embed content as bytes. "
+                "'passthrough': Send file parts to the agent as-is."
+            ),
+            "enum": ["reference", "embed", "passthrough"],
+        },
+        {
+            "name": "gateway_max_message_size_bytes",
+            "required": False,
+            "type": "integer",
+            "default": 10_000_000,  # 10MB
+            "description": "Maximum allowed message size in bytes for messages published by the gateway.",
+        },
+        {
+            "name": "gateway_max_upload_size_bytes",
+            "required": False,
+            "type": "integer",
+            "default": 52428800,  # 50MB
+            "description": "Maximum file upload size in bytes. Validated before reading file content to prevent memory exhaustion.",
+        },
+        # --- Default User Identity Configuration ---
+        {
+            "name": "default_user_identity",
+            "required": False,
+            "type": "string",
+            "description": "Default user identity to use when no user authentication is provided. WARNING: Only use in development environments with trusted access!",
+        },
+        {
+            "name": "force_user_identity",
+            "required": False,
+            "type": "string",
+            "description": "Override any provided user identity with this value. WARNING: Development only! This completely replaces authentication.",
+        },
+        # --- Identity Service Configuration ---
+        {
+            "name": "identity_service",
+            "required": False,
+            "type": "object",
+            "default": None,
+            "description": "Configuration for the pluggable Identity Service provider.",
+        },
+    ]
+}
+
+
+class BaseGatewayApp(App):
+    """
+    Base class for Gateway applications.
+
+    Handles common configuration, Solace broker setup, and instantiation
+    of the gateway-specific component. It also automatically merges its
+    base schema with specific schema parameters defined by subclasses.
+    """
+
+    app_schema: Dict[str, List[Dict[str, Any]]] = BASE_GATEWAY_APP_SCHEMA
+    SPECIFIC_APP_SCHEMA_PARAMS_ATTRIBUTE_NAME = "SPECIFIC_APP_SCHEMA_PARAMS"
+
+    def __init_subclass__(cls, **kwargs):
+        """
+        Automatically merges the base gateway schema with specific schema
+        parameters defined in any subclass.
+        """
+        super().__init_subclass__(**kwargs)
+
+        specific_params = getattr(
+            cls, cls.SPECIFIC_APP_SCHEMA_PARAMS_ATTRIBUTE_NAME, []
+        )
+
+        if not isinstance(specific_params, list):
+            log.warning(
+                "Class attribute '%s' in %s is not a list. Schema merging might be incorrect.",
+                cls.SPECIFIC_APP_SCHEMA_PARAMS_ATTRIBUTE_NAME,
+                cls.__name__,
+            )
+            specific_params = []
+
+        base_params = BaseGatewayApp.app_schema.get("config_parameters", [])
+
+        # Start with the child's parameters to give them precedence.
+        merged_config_parameters = list(specific_params)
+        specific_param_names = {p["name"] for p in specific_params}
+
+        # Add base parameters only if they are not already defined in the child.
+        for base_param in base_params:
+            if base_param["name"] not in specific_param_names:
+                merged_config_parameters.append(base_param)
+
+        cls.app_schema = {"config_parameters": merged_config_parameters}
+        log.debug(
+            "BaseGatewayApp.__init_subclass__ created merged app_schema for %s with %d params.",
+            cls.__name__,
+            len(merged_config_parameters),
+        )
+
+    def __init__(self, app_info: Dict[str, Any], **kwargs):
+        """
+        Initializes the BaseGatewayApp.
+
+        Args:
+            app_info: Configuration dictionary for the app, typically from YAML.
+            **kwargs: Additional arguments for the parent App class.
+        """
+        log.debug(
+            "Initializing BaseGatewayApp with app_info: %s",
+            app_info.get("name", "Unnamed App"),
+        )
+
+        code_config_app_block = getattr(self.__class__, "app_config", {}).get(
+            "app_config", {}
+        )
+        yaml_app_config_block = app_info.get("app_config", {})
+        resolved_app_config_block = deep_merge(
+            code_config_app_block, yaml_app_config_block
+        )
+
+        self.namespace: str = resolved_app_config_block.get("namespace")
+        if not self.namespace:
+            raise ValueError(
+                "Namespace is required in app_config for BaseGatewayApp or its derivatives."
+            )
+
+        self.gateway_id: str = resolved_app_config_block.get("gateway_id")
+        if not self.gateway_id:
+            self.gateway_id = f"gdk-gateway-{uuid.uuid4().hex[:8]}"
+            resolved_app_config_block["gateway_id"] = self.gateway_id
+            log.info("Generated unique gateway_id: %s", self.gateway_id)
+
+        self.artifact_service_config: Dict = resolved_app_config_block.get(
+            "artifact_service", {}
+        )
+        self.enable_embed_resolution: bool = resolved_app_config_block.get(
+            "enable_embed_resolution", True
+        )
+
+        new_size_limit_key = "gateway_max_artifact_resolve_size_bytes"
+        default_new_size_limit = 104857600
+        old_size_limit_key = "gateway_artifact_content_limit_bytes"
+
+        new_value = resolved_app_config_block.get(new_size_limit_key)
+        old_value = resolved_app_config_block.get(old_size_limit_key)
+
+        app_name_for_log = app_info.get("name", "BaseGatewayApp")
+
+        if new_value is not None:
+            self.gateway_max_artifact_resolve_size_bytes = new_value
+            if old_value is not None and new_value != old_value:
+                log.warning(
+                    f"[{app_name_for_log}] Both '{new_size_limit_key}' (value: {new_value}) and deprecated '{old_size_limit_key}' (value: {old_value}) are present. "
+                    f"Using value from '{new_size_limit_key}'."
+                )
+        elif old_value is not None:
+            self.gateway_max_artifact_resolve_size_bytes = old_value
+            log.warning(
+                f"[{app_name_for_log}] Configuration key '{old_size_limit_key}' (value: {old_value}) is deprecated. "
+                f"Please use '{new_size_limit_key}'. Using value from old key."
+            )
+        else:
+            self.gateway_max_artifact_resolve_size_bytes = default_new_size_limit
+
+        self.gateway_recursive_embed_depth: int = resolved_app_config_block.get(
+            "gateway_recursive_embed_depth", 12
+        )
+        self.artifact_handling_mode: str = resolved_app_config_block.get(
+            "artifact_handling_mode", "reference"
+        )
+        self.gateway_max_message_size_bytes: int = resolved_app_config_block.get(
+            "gateway_max_message_size_bytes", 10_000_000
+        )
+        self.gateway_max_upload_size_bytes: int = resolved_app_config_block.get(
+            "gateway_max_upload_size_bytes", 52428800
+        )
+
+        modified_app_info = app_info.copy()
+        modified_app_info["app_config"] = resolved_app_config_block
+
+        subscriptions = [
+            {"topic": get_discovery_topic(self.namespace)},
+            {
+                "topic": get_gateway_response_subscription_topic(
+                    self.namespace, self.gateway_id
+                )
+            },
+            {
+                "topic": get_gateway_status_subscription_topic(
+                    self.namespace, self.gateway_id
+                )
+            },
+        ]
+
+        # Add trust card subscription if trust manager is enabled
+        trust_config = resolved_app_config_block.get("trust_manager")
+        if trust_config and trust_config.get("enabled", False):
+            from ...common.a2a.protocol import get_trust_card_subscription_topic
+
+            trust_card_topic = get_trust_card_subscription_topic(self.namespace)
+            subscriptions.append({"topic": trust_card_topic})
+            log.info(
+                "Trust Manager enabled for gateway '%s', added trust card subscription: %s",
+                self.gateway_id,
+                trust_card_topic,
+            )
+
+        log.info(
+            "Generated Solace subscriptions for gateway '%s': %s",
+            self.gateway_id,
+            subscriptions,
+        )
+
+        gateway_component_class = self._get_gateway_component_class()
+        if not gateway_component_class or not issubclass(
+            gateway_component_class, ComponentBase
+        ):
+            raise TypeError(
+                f"_get_gateway_component_class in {self.__class__.__name__} must return a valid ComponentBase subclass."
+            )
+
+        component_definition = {
+            "name": f"{self.gateway_id}_component",
+            "component_class": gateway_component_class,
+            "component_config": {"app_config": resolved_app_config_block},
+            "subscriptions": subscriptions,
+        }
+        modified_app_info["components"] = [component_definition]
+
+        broker_config = modified_app_info.setdefault("broker", {})
+        broker_config["input_enabled"] = True
+        broker_config["output_enabled"] = True
+        broker_config["queue_name"] = (
+            f"{self.namespace.strip('/')}/q/gdk/gateway/{self.gateway_id}"
+        )
+        broker_config["temporary_queue"] = modified_app_info.get("broker", {}).get("temporary_queue", True)
+        log.debug(
+            "Injected broker settings for gateway '%s': %s",
+            self.gateway_id,
+            broker_config,
+        )
+
+        super().__init__(app_info=modified_app_info, **kwargs)
+        log.info("BaseGatewayApp '%s' initialized successfully.", self.name)
+
+    @abstractmethod
+    def _get_gateway_component_class(self) -> Type[BaseGatewayComponent]:
+        """
+        Abstract method to be implemented by derived gateway applications.
+
+        Returns:
+            The specific gateway component class (e.g., WebUIBackendComponent).
+        """
+        pass

solace_agent_mesh/gateway/base/base_llm.txt

@@ -0,0 +1,226 @@
+# DEVELOPER GUIDE: base
+
+## Quick Summary
+The `base` directory provides foundational abstract classes for building Gateway implementations within the Solace AI Connector. It establishes a framework for handling common gateway tasks such as application configuration, Solace broker integration, A2A (Agent-to-Agent) message protocol handling, and managing the lifecycle of requests from external platforms. Developers should subclass `BaseGatewayApp` and `BaseGatewayComponent` to create new gateways.
+
+## Files Overview
+- `__init__.py` - Marks the directory as a Python package
+- `app.py` - Contains the base application class that handles configuration, schema merging, and broker setup
+- `component.py` - Contains the core logic class for processing A2A messages and integrating with external platforms
+- `task_context.py` - Provides a thread-safe manager for mapping A2A task IDs to their original request context
+
+## Developer API Reference
+
+### __init__.py
+**Purpose:** Initializes the `gateway.base` Python package
+**Import:** `from solace_agent_mesh.gateway.base import ...`
+
+---
+
+### app.py
+**Purpose:** Provides the base application class for gateway implementations with automated configuration schema merging, Solace broker setup, and component instantiation
+**Import:** `from solace_agent_mesh.gateway.base.app import BaseGatewayApp, BaseGatewayComponent`
+
+**Classes:**
+- `BaseGatewayComponent(ComponentBase)` - Base marker class for gateway components
+- `BaseGatewayApp(app_info: Dict[str, Any], **kwargs)` - Main application class to be subclassed for new gateways
+  - `_get_gateway_component_class(self) -> Type[BaseGatewayComponent]` - **[Abstract Method]** Must return the specific gateway component class
+  - `namespace: str` - Absolute topic prefix for A2A communication (e.g., 'myorg/dev')
+  - `gateway_id: str` - Unique ID for this gateway instance (auto-generated if not provided)
+  - `artifact_service_config: Dict` - Configuration for the shared ADK Artifact Service
+  - `enable_embed_resolution: bool` - Flag to enable/disable late-stage 'artifact_content' embed resolution
+  - `gateway_max_artifact_resolve_size_bytes: int` - Maximum size for resolving artifacts (default: 104857600)
+  - `gateway_recursive_embed_depth: int` - Maximum depth for recursive embed resolution (default: 12)
+  - `artifact_handling_mode: str` - How gateway handles file parts: "reference", "embed", or "passthrough"
+  - `gateway_max_message_size_bytes: int` - Maximum message size in bytes (default: 10MB)
+
+**Constants/Variables:**
+- `BASE_GATEWAY_APP_SCHEMA: Dict[str, List[Dict[str, Any]]]` - Base configuration schema automatically merged with subclass parameters
+- `SPECIFIC_APP_SCHEMA_PARAMS_ATTRIBUTE_NAME: str` - Class attribute name ("SPECIFIC_APP_SCHEMA_PARAMS") for subclass-specific config parameters
+
+**Usage Examples:**
+```python
+from typing import Type, List, Dict, Any
+from solace_agent_mesh.gateway.base.app import BaseGatewayApp, BaseGatewayComponent
+
+class MyGatewayComponent(BaseGatewayComponent):
+    # Implementation details...
+    pass
+
+class MyGatewayApp(BaseGatewayApp):
+    """Custom gateway application for My Platform."""
+    
+    # Define additional configuration parameters
+    SPECIFIC_APP_SCHEMA_PARAMS: List[Dict[str, Any]] = [
+        {
+            "name": "my_platform_api_key",
+            "required": True,
+            "type": "string",
+            "description": "API key for connecting to My Platform."
+        }
+    ]
+
+    def _get_gateway_component_class(self) -> Type[BaseGatewayComponent]:
+        return MyGatewayComponent
+
+# Usage in YAML config:
+# app_config:
+#   namespace: "myorg/prod"
+#   gateway_id: "my-gateway-instance-01"
+#   artifact_service:
+#     type: "local_file"
+#     base_path: "/data/artifacts"
+#   my_platform_api_key: "secret-key-here"
+```
+
+---
+
+### component.py
+**Purpose:** Provides the abstract base class for gateway components containing core A2A protocol logic, service management, and external platform integration interface
+**Import:** `from solace_agent_mesh.gateway.base.component import BaseGatewayComponent`
+
+**Classes:**
+- `BaseGatewayComponent(resolve_artifact_uris_in_gateway: bool = True, **kwargs: Any)` - Abstract base class for gateway components
+  - **Public Methods:**
+    - `get_config(self, key: str, default: Any = None) -> Any` - Retrieves configuration from nested app_config or component_config
+    - `authenticate_and_enrich_user(self, external_event_data: Any) -> Optional[Dict[str, Any]]` - Orchestrates user authentication and identity enrichment
+    - `submit_a2a_task(self, target_agent_name: str, a2a_parts: List[ContentPart], external_request_context: Dict[str, Any], user_identity: Any, is_streaming: bool = True, api_version: str = "v2") -> str` - Submits task to target agent, returns task_id
+  - **Abstract Methods (Must be Implemented):**
+    - `_extract_initial_claims(self, external_event_data: Any) -> Optional[Dict[str, Any]]` - Extract identity claims from platform event (must return dict with 'id' key)
+    - `_start_listener(self) -> None` - Start external platform listener (e.g., web server, WebSocket)
+    - `_stop_listener(self) -> None` - Stop external platform listener
+    - `_translate_external_input(self, external_event: Any) -> Tuple[str, List[ContentPart], Dict[str, Any]]` - Convert external event to A2A format: (target_agent_name, a2a_parts, context)
+    - `_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 external platform
+    - `_send_final_response_to_external(self, external_request_context: Dict[str, Any], task_data: Task) -> None` - Send final response to external platform
+    - `_send_error_to_external(self, external_request_context: Dict[str, Any], error_data: JSONRPCError) -> None` - Send error to external platform
+  - **Properties:**
+    - `namespace: str` - A2A communication namespace
+    - `gateway_id: str` - Unique gateway instance ID
+    - `agent_registry: AgentRegistry` - Registry for discovered agents
+    - `core_a2a_service: CoreA2AService` - Core A2A protocol service
+    - `shared_artifact_service: Optional[BaseArtifactService]` - Artifact service instance
+    - `task_context_manager: TaskContextManager` - Thread-safe task context storage
+    - `identity_service: Optional[BaseIdentityService]` - Identity enrichment service
+
+**Usage Examples:**
+```python
+from typing import Any, Dict, List, Optional, Tuple, Union
+from solace_agent_mesh.gateway.base.component import BaseGatewayComponent
+from solace_agent_mesh.common.a2a.types import ContentPart
+from a2a.types import TextPart, Task, TaskStatusUpdateEvent, TaskArtifactUpdateEvent, JSONRPCError
+
+class MyGatewayComponent(BaseGatewayComponent):
+    
+    async def _extract_initial_claims(self, external_event_data: Any) -> Optional[Dict[str, Any]]:
+        """Extract user identity from platform-specific event."""
+        # Example for HTTP request
+        if hasattr(external_event_data, 'headers'):
+            user_id = external_event_data.headers.get('X-User-ID')
+            if user_id:
+                return {"id": user_id, "source": "http_header"}
+        return None
+    
+    def _start_listener(self) -> None:
+        """Start your platform listener (web server, etc.)."""
+        # Example: Start FastAPI server, WebSocket connection, etc.
+        pass
+    
+    def _stop_listener(self) -> None:
+        """Stop your platform listener."""
+        pass
+    
+    async def _translate_external_input(self, external_event: Any) -> Tuple[str, List[ContentPart], Dict[str, Any]]:
+        """Convert external event to A2A format."""
+        # Example translation
+        target_agent = "my-agent"
+        message_text = getattr(external_event, 'message', 'Hello')
+        a2a_parts = [TextPart(text=message_text)]
+        context = {
+            "platform": "my_platform",
+            "user_id_for_artifacts": "user123",
+            "a2a_session_id": "session456"
+        }
+        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 back to external platform."""
+        # Extract text from event and send to your platform
+        pass
+    
+    async def _send_final_response_to_external(self, external_request_context: Dict[str, Any], 
+                                             task_data: Task) -> None:
+        """Send final response back to external platform."""
+        # Extract final result and send to your platform
+        pass
+    
+    async def _send_error_to_external(self, external_request_context: Dict[str, Any], 
+                                     error_data: JSONRPCError) -> None:
+        """Send error back to external platform."""
+        # Send error message to your platform
+        pass
+
+# Usage in your handler:
+async def handle_external_request(request):
+    # Authenticate user
+    user_identity = await component.authenticate_and_enrich_user(request)
+    if not user_identity:
+        return "Authentication failed"
+    
+    # Translate request
+    target_agent, a2a_parts, context = await component._translate_external_input(request)
+    
+    # Submit to A2A system
+    task_id = await component.submit_a2a_task(
+        target_agent_name=target_agent,
+        a2a_parts=a2a_parts,
+        external_request_context=context,
+        user_identity=user_identity,
+        is_streaming=True
+    )
+    
+    return f"Task submitted: {task_id}"
+```
+
+---
+
+### task_context.py
+**Purpose:** Provides thread-safe storage for mapping A2A task IDs to their original external request context
+**Import:** `from solace_agent_mesh.gateway.base.task_context import TaskContextManager`
+
+**Classes:**
+- `TaskContextManager()` - Thread-safe context storage manager
+  - `store_context(self, task_id: str, context_data: Dict[str, Any]) -> None` - Store context for a task ID
+  - `get_context(self, task_id: str) -> Optional[Dict[str, Any]]` - Retrieve context for a task ID
+  - `remove_context(self, task_id: str) -> Optional[Dict[str, Any]]` - Remove and return context for a task ID
+  - `clear_all_contexts_for_testing(self) -> None` - Clear all contexts (testing only)
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.gateway.base.task_context import TaskContextManager
+
+# Initialize manager
+context_manager = TaskContextManager()
+
+# Store context when submitting task
+task_id = "gdk-task-abc123"
+context = {
+    "platform": "slack",
+    "channel_id": "C1234567890",
+    "thread_ts": "1234567890.123456",
+    "user_identity": {"id": "user123", "name": "John Doe"}
+}
+context_manager.store_context(task_id, context)
+
+# Retrieve context when processing response
+retrieved_context = context_manager.get_context(task_id)
+if retrieved_context:
+    channel_id = retrieved_context["channel_id"]
+    # Send response back to Slack channel
+
+# Clean up when task is complete
+context_manager.remove_context(task_id)
+```
+
+# content_hash: 74574cc0c8234142d9ecddd116cc306b5420f938289ab4eab77feaa225adae7a