solace-agent-mesh 1.0.7__py3-none-any.whl → 1.1.0__py3-none-any.whl

solace_agent_mesh/gateway/base/base_llm.txt

@@ -1,52 +1,51 @@
+# DEVELOPER GUIDE: base
+
 ## Quick Summary
-The `base` directory provides the 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 a new gateway.
+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 (`BaseGatewayApp`) that handles configuration, schema merging, and broker setup.
-- `component.py`: Contains the core logic class (`BaseGatewayComponent`) 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.
+- `__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 gateway.base import ...`
+**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. It automates configuration schema merging, Solace broker setup (including topic subscriptions and queue creation), and component instantiation.
-**Import:** `from gateway.base.app import BaseGatewayApp, BaseGatewayComponent`
+**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)` - A base class marker for gateway components. Subclasses of `BaseGatewayComponent` from `component.py` inherit from this.
-- `BaseGatewayApp(app_info: Dict[str, Any], **kwargs)` - The main application class to be subclassed for a new gateway.
-  - `_get_gateway_component_class(self) -> Type[BaseGatewayComponent]` - **[Abstract Method]** Must be implemented by subclasses to return the specific gateway component class that will handle the core logic.
-  - `namespace: str` - The absolute topic prefix for A2A communication (e.g., 'myorg/dev').
-  - `gateway_id: str` - The 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 or disable late-stage 'artifact_content' embed resolution.
-  - `gateway_max_artifact_resolve_size_bytes: int` - Maximum size for resolving individual or recursively embedded artifacts.
-  - `gateway_recursive_embed_depth: int` - Maximum depth for recursively resolving 'artifact_content' embeds.
+- `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)
 
 **Constants/Variables:**
-- `BASE_GATEWAY_APP_SCHEMA: Dict[str, List[Dict[str, Any]]]` - The base configuration schema dictionary that is automatically merged with subclass-specific parameters.
-- `SPECIFIC_APP_SCHEMA_PARAMS_ATTRIBUTE_NAME: str` - The class attribute name (`"SPECIFIC_APP_SCHEMA_PARAMS"`) that subclasses should use to define their own configuration parameters.
+- `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
-# In your custom gateway's app.py
-
 from typing import Type, List, Dict, Any
-from gateway.base.app import BaseGatewayApp
-from .component import MyGatewayComponent # Your custom component
+from solace_agent_mesh.gateway.base.app import BaseGatewayApp
+from .component import MyGatewayComponent
 
 class MyGatewayApp(BaseGatewayApp):
-    """
-    A custom gateway application for My Platform.
-    """
-    # Define additional configuration parameters specific to this gateway
+    """Custom gateway application for My Platform."""
+    
+    # Define additional configuration parameters
     SPECIFIC_APP_SCHEMA_PARAMS: List[Dict[str, Any]] = [
         {
             "name": "my_platform_api_key",
@@ -57,63 +56,169 @@ class MyGatewayApp(BaseGatewayApp):
     ]
 
     def _get_gateway_component_class(self) -> Type[MyGatewayComponent]:
-        """
-        Returns our custom component class.
-        """
         return MyGatewayComponent
 
-# To run this app (typically via a YAML configuration file):
-# app_config = {
-#     "name": "my-gateway-app",
-#     "app_class": MyGatewayApp,
-#     "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"
-#     }
-# }
-# app = MyGatewayApp(app_info=app_config)
-# app.run()
+# 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. This class contains the core logic for handling the A2A protocol, managing services (identity, artifacts), and defining the interface for interaction with an external platform (e.g., a web server, a chat application).
-**Import:** `from gateway.base.component import BaseGatewayComponent`
+**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(**kwargs: Any)` - The abstract base class for gateway components. Developers must subclass this and implement the abstract methods.
+- `BaseGatewayComponent(**kwargs: Any)` - Abstract base class for gateway components
   - **Public Methods:**
-    - `publish_a2a_message(self, topic: str, payload: Dict, user_properties: Optional[Dict] = None) -> None` - Publishes a message to the Solace broker for A2A communication.
-    - `authenticate_and_enrich_user(self, external_event_data: Any) -> Optional[Dict[str, Any]]` - Orchestrates the full user authentication and identity enrichment flow by calling `_extract_initial_claims` and the configured Identity Service.
-    - `submit_a2a_task(self, target_agent_name: str, a2a_parts: List[A2APart], external_request_context: Dict[str, Any], user_identity: Any, is_streaming: bool = True, api_version: str = "v2") -> str` - Submits a task to a target agent, handling user configuration resolution, message creation, and context storage. Returns the generated `task_id`.
-    - `run(self) -> None` - Starts the component's asynchronous operations, including the message processor loop and the external platform listener.
-    - `cleanup(self) -> None` - Cleans up all resources, stops listeners, and shuts down background threads.
-  - **Abstract Methods (Must be Implemented by Subclasses):**
-    - `_extract_initial_claims(self, external_event_data: Any) -> Optional[Dict[str, Any]]` - Extracts primary identity claims (e.g., user ID) from a platform-specific event. Must return a dict with an 'id' key, or None if auth fails.
-    - `_start_listener(self) -> None` - Starts the listener for the external platform (e.g., start a web server, connect to a WebSocket).
-    - `_stop_listener(self) -> None` - Stops the listener for the external platform.
-    - `_translate_external_input(self, external_event: Any) -> Tuple[str, List[A2APart], Dict[str, Any]]` - Translates an incoming event from the external platform into a format the A2A protocol understands: `(target_agent_name, list_of_a2a_parts, external_request_context)`.
-    - `_send_update_to_external(self, external_request_context: Dict[str, Any], event_data: Union[TaskStatusUpdateEvent, TaskArtifactUpdateEvent], is_final_chunk_of_update: bool) -> None` - Sends a streaming update (e.g., a status message or an artifact) back to the external platform.
-    - `_send_final_response_to_external(self, external_request_context: Dict[str, Any], task_data: Task) -> None` - Sends the final, complete response of a task back to the external platform.
-    - `_send_error_to_external(self, external_request_context: Dict[str, Any], error_data: JSONRPCError) -> None` - Sends an error message back to the external platform.
+    - `get_config(self, key: str, default: Any = None) -> Any` - Retrieves configuration from nested app_config or component_config
+    - `publish_a2a_message(self, topic: str, payload: Dict, user_properties: Optional[Dict] = None) -> None` - Publishes A2A messages to Solace broker
+    - `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
+    - `run(self) -> None` - Starts component's async operations and external platform listener
+    - `cleanup(self) -> None` - Cleans up resources and stops background threads
+  - **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
-# In your custom gateway's component.py
-
 from typing import Any, Dict, List, Optional, Tuple, Union
-from gateway.base.component import BaseGatewayComponent
-from ...common.types import (
-    Part as A2APart, TextPart, Task, TaskStatusUpdateEvent,
-    TaskArtifactUpdateEvent, JSONRPCError
-)
+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):
-    # This is a simplified example. A real implementation would
-    #
+    
+    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: 016addd094bc383fc1606b1540887c181ef630740fff8f4d801ff03d91e1cbd4