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

solace_agent_mesh/common/client/client.py

@@ -0,0 +1,85 @@
+import httpx
+from httpx_sse import connect_sse
+from typing import Any, AsyncIterable
+from ...common.types import (
+    AgentCard,
+    GetTaskRequest,
+    SendTaskRequest,
+    SendTaskResponse,
+    JSONRPCRequest,
+    GetTaskResponse,
+    CancelTaskResponse,
+    CancelTaskRequest,
+    SetTaskPushNotificationRequest,
+    SetTaskPushNotificationResponse,
+    GetTaskPushNotificationRequest,
+    GetTaskPushNotificationResponse,
+    A2AClientHTTPError,
+    A2AClientJSONError,
+    SendTaskStreamingRequest,
+    SendTaskStreamingResponse,
+)
+import json
+
+
+class A2AClient:
+    def __init__(self, agent_card: AgentCard = None, url: str = None):
+        if agent_card:
+            self.url = agent_card.url
+        elif url:
+            self.url = url
+        else:
+            raise ValueError("Must provide either agent_card or url")
+
+    async def send_task(self, payload: dict[str, Any]) -> SendTaskResponse:
+        request = SendTaskRequest(params=payload)
+        return SendTaskResponse(**await self._send_request(request))
+
+    async def send_task_streaming(
+        self, payload: dict[str, Any]
+    ) -> AsyncIterable[SendTaskStreamingResponse]:
+        request = SendTaskStreamingRequest(params=payload)
+        with httpx.Client(timeout=None) as client:
+            with connect_sse(
+                client, "POST", self.url, json=request.model_dump()
+            ) as event_source:
+                try:
+                    for sse in event_source.iter_sse():
+                        yield SendTaskStreamingResponse(**json.loads(sse.data))
+                except json.JSONDecodeError as e:
+                    raise A2AClientJSONError(str(e)) from e
+                except httpx.RequestError as e:
+                    raise A2AClientHTTPError(400, str(e)) from e
+
+    async def _send_request(self, request: JSONRPCRequest) -> dict[str, Any]:
+        async with httpx.AsyncClient() as client:
+            try:
+                response = await client.post(
+                    self.url, json=request.model_dump(), timeout=30
+                )
+                response.raise_for_status()
+                return response.json()
+            except httpx.HTTPStatusError as e:
+                raise A2AClientHTTPError(e.response.status_code, str(e)) from e
+            except json.JSONDecodeError as e:
+                raise A2AClientJSONError(str(e)) from e
+
+    async def get_task(self, payload: dict[str, Any]) -> GetTaskResponse:
+        request = GetTaskRequest(params=payload)
+        return GetTaskResponse(**await self._send_request(request))
+
+    async def cancel_task(self, payload: dict[str, Any]) -> CancelTaskResponse:
+        request = CancelTaskRequest(params=payload)
+        return CancelTaskResponse(**await self._send_request(request))
+
+    async def set_task_callback(
+        self, payload: dict[str, Any]
+    ) -> SetTaskPushNotificationResponse:
+        request = SetTaskPushNotificationRequest(params=payload)
+        return SetTaskPushNotificationResponse(**await self._send_request(request))
+
+    async def get_task_callback(
+        self, payload: dict[str, Any]
+    ) -> GetTaskPushNotificationResponse:
+        request = GetTaskPushNotificationRequest(params=payload)
+        return GetTaskPushNotificationResponse(**await self._send_request(request))

solace_agent_mesh/common/client/client_llm.txt

@@ -0,0 +1,133 @@
+## Quick Summary
+The `client` directory provides a Python-based client library for Agent-to-Agent (A2A) communication. It allows developers to discover remote agent capabilities via an "Agent Card" and then interact with that agent by sending tasks, receiving streaming responses, and managing the task lifecycle (getting status, cancelling, setting callbacks).
+
+## Files Overview
+- `__init__.py`: Exposes the primary `A2AClient` and `A2ACardResolver` classes for easy importing.
+- `card_resolver.py`: Contains the `A2ACardResolver` class, used to discover and fetch an agent's capabilities from a well-known endpoint.
+- `client.py`: Contains the main `A2AClient` class for all communication with a remote agent, including sending tasks and managing them.
+
+## Developer API Reference
+
+### __init__.py
+**Purpose:** This file makes the main client classes available directly under the `client` package, simplifying imports for developers.
+**Import:** `from src.solace_agent_mesh.common.client import A2AClient, A2ACardResolver`
+
+**Constants/Variables:**
+- `__all__: list[str]` - A list of the public objects that are exported from this module: `["A2AClient", "A2ACardResolver"]`.
+
+---
+
+### card_resolver.py
+**Purpose:** This file provides a utility to resolve and fetch an agent's "Agent Card". The Agent Card is a JSON file that describes the agent's capabilities, its endpoint URL, and other metadata.
+**Import:** `from src.solace_agent_mesh.common.client import A2ACardResolver`
+
+**Classes:**
+- `A2ACardResolver(base_url: str, agent_card_path: str = "/.well-known/agent.json")` - A client to discover and fetch an agent's capability card.
+  - `get_agent_card() -> AgentCard` - Makes an HTTP GET request to the constructed agent card URL, parses the JSON response, and returns it as an `AgentCard` object. Raises `A2AClientHTTPError` on network/status errors and `A2AClientJSONError` on parsing errors.
+
+**Usage Examples:**
+```python
+from src.solace_agent_mesh.common.client import A2ACardResolver
+from src.solace_agent_mesh.common.types import AgentCard, A2AClientHTTPError
+
+# --- Example 1: Standard usage ---
+# Create a resolver for an agent hosted at a specific domain
+resolver = A2ACardResolver(base_url="https://some-agent.ai")
+
+try:
+    # Fetch the agent's capability card from the default path
+    # (https://some-agent.ai/.well-known/agent.json)
+    agent_card: AgentCard = resolver.get_agent_card()
+    print(f"Successfully fetched card for agent: {agent_card.name}")
+    print(f"Agent API URL: {agent_card.url}")
+    print(f"Supported capabilities: {agent_card.capabilities}")
+
+except A2AClientHTTPError as e:
+    print(f"Error fetching agent card: {e.status_code} - {e.message}")
+
+
+# --- Example 2: Using a custom path for the agent card ---
+custom_path_resolver = A2ACardResolver(
+    base_url="https://another-agent.com",
+    agent_card_path="/api/v1/agent-info.json"
+)
+# This will fetch from https://another-agent.com/api/v1/agent-info.json
+custom_agent_card = custom_path_resolver.get_agent_card()
+print(f"Agent name from custom path: {custom_agent_card.name}")
+```
+
+---
+
+### client.py
+**Purpose:** This file contains the core `A2AClient`, which is used to communicate with a remote agent's API endpoint. It handles sending various types of JSON-RPC requests for task management. All methods are asynchronous.
+**Import:** `from src.solace_agent_mesh.common.client import A2AClient`
+
+**Classes:**
+- `A2AClient(agent_card: AgentCard = None, url: str = None)` - The main client for interacting with a remote agent. You must provide either an `AgentCard` object (from `A2ACardResolver`) or a direct `url` string to its API endpoint.
+  - `async send_task(self, payload: dict[str, Any]) -> SendTaskResponse` - Sends a task to the agent for processing. The `payload` should contain the action and its parameters. Returns a response typically containing a `task_id`.
+  - `async send_task_streaming(self, payload: dict[str, Any]) -> AsyncIterable[SendTaskStreamingResponse]` - Sends a task that is expected to return a stream of events (Server-Sent Events). The `payload` is the same as `send_task`. Returns an async iterator that yields response chunks as they arrive.
+  - `async get_task(self, payload: dict[str, Any]) -> GetTaskResponse` - Retrieves the current status and/or result of a previously submitted task. The `payload` must contain the `task_id`.
+  - `async cancel_task(self, payload: dict[str, Any]) -> CancelTaskResponse` - Requests the cancellation of a running task. The `payload` must contain the `task_id`.
+  - `async set_task_callback(self, payload: dict[str, Any]) -> SetTaskPushNotificationResponse` - Sets a callback URL for a specific task. The agent will send a notification to this URL upon task completion. The `payload` must contain the `task_id` and `callback_url`.
+  - `async get_task_callback(self, payload: dict[str, Any]) -> GetTaskPushNotificationResponse` - Retrieves the currently configured callback URL for a task. The `payload` must contain the `task_id`.
+
+**Usage Examples:**
+```python
+import asyncio
+from src.solace_agent_mesh.common.client import A2AClient, A2ACardResolver
+
+# Assume these types are available for type hinting
+# from src.solace_agent_mesh.common.types import SendTaskResponse, SendTaskStreamingResponse
+
+async def main():
+    # First, discover the agent's capabilities and endpoint URL
+    resolver = A2ACardResolver(base_url="https://some-agent.ai")
+    agent_card = resolver.get_agent_card()
+
+    # --- Initialization ---
+    # Method 1: Initialize client using the discovered AgentCard
+    client = A2AClient(agent_card=agent_card)
+
+    # Method 2: Initialize client with a direct URL (if known)
+    # client = A2AClient(url="https://some-agent.ai/api/v1/a2a")
+
+    # --- Send a simple task ---
+    print("--- Sending a simple task ---")
+    task_payload = {"action": "summarize_text", "text": "A long article..."}
+    send_response = await client.send_task(payload=task_payload)
+    task_id = send_response.result.task_id
+    print(f"Task created with ID: {task_id}")
+
+    # --- Get task status ---
+    print("\n--- Checking task status ---")
+    status_response = await client.get_task(payload={"task_id": task_id})
+    print(f"Task status: {status_response.result.status}")
+    
+    # --- Send a streaming task ---
+    print("\n--- Sending a streaming task ---")
+    stream_payload = {"action": "generate_story", "prompt": "A robot who discovers music"}
+    async for chunk in client.send_task_streaming(payload=stream_payload):
+        # Each chunk is a SendTaskStreamingResponse object
+        print(f"Received stream chunk: {chunk.result.content_chunk}")
+
+    # --- Set a callback URL for the task ---
+    print("\n--- Setting a callback URL ---")
+    await client.set_task_callback(
+        payload={"task_id": task_id, "callback_url": "https://my-app.com/webhook"}
+    )
+    print("Callback URL set.")
+
+    # --- Cancel a task ---
+    print("\n--- Cancelling a task ---")
+    cancel_response = await client.cancel_task(payload={"task_id": task_id})
+    print(f"Task cancellation requested. Success: {cancel_response.result.cancelled}")
+
+
+if __name__ == "__main__":
+    # Note: In a real application, you would use a running event loop.
+    # This example assumes the agent endpoint is available and working.
+    # To run this, you would need a live agent to connect to.
+    # asyncio.run(main())
+    print("Developer guide example executed.")
+
+```

solace_agent_mesh/common/common_llm.txt

@@ -0,0 +1,144 @@
+Here is the comprehensive developer guide for the `common` directory.
+
+## Quick Summary
+The `common` directory provides the foundational infrastructure for Agent-to-Agent (A2A) communication within the Solace AI Connector. It establishes the core protocol, data types, and message translation logic that underpins all interactions between AI agents and gateways.
+
+The architecture is designed for clarity and extensibility. Core, low-level definitions are located in **direct files**:
+*   `types.py` defines the canonical data structures (e.g., `Message`, `Task`, `AgentCard`).
+*   `a2a_protocol.py` handles the construction of Solace topics and the translation between A2A and Google ADK message formats.
+*   `agent_registry.py` provides a simple, thread-safe mechanism for discovering and tracking available agents.
+
+This foundation is then leveraged by specialized **subdirectories**, which provide higher-level, ready-to-use components:
+*   `client/`: A complete client library for discovering and interacting with remote agents.
+*   `server/`: A stand-alone server implementation for building A2A-compliant agents.
+*   `middleware/`: A pluggable framework for customizing configuration and feature access.
+*   `services/`: A factory-based system for integrating identity and other external data sources.
+*   `utils/`: A collection of cross-cutting utilities for caching, logging, and dynamic content processing.
+
+Together, these components form a cohesive ecosystem, enabling developers to either build new agents from scratch using the `server` components or interact with existing agents using the `client` library, all while relying on the same underlying protocol and types.
+
+## Files and Subdirectories Overview
+- **Direct files:**
+    - `__init__.py`: Package initialization file.
+    - `a2a_protocol.py`: Handles A2A topic construction and translation between A2A and ADK message formats.
+    - `agent_registry.py`: A thread-safe registry for managing discovered agent cards.
+    - `types.py`: Contains all Pydantic models for A2A protocol messages, tasks, and data structures.
+- **Subdirectories:**
+    - `client/`: Provides a high-level client for discovering and communicating with remote A2A agents.
+    - `middleware/`: A pluggable framework for configuration resolution and system extensibility.
+    - `server/`: A complete A2A server implementation with JSON-RPC support and task management.
+    - `services/`: Provides shared services like identity management using a factory pattern.
+    - `utils/`: Contains common utility functions and an embedded expression processing system.
+
+## Developer API Reference
+
+### Direct Files
+
+#### a2a_protocol.py
+**Purpose:** Provides the core functions for constructing Solace topics according to the A2A specification and for translating messages between the A2A format and the Google ADK format.
+**Import:** `from common.a2a_protocol import get_agent_request_topic, translate_a2a_to_adk_content`
+
+**Classes/Functions/Constants:**
+*   **Constants**:
+    *   `A2A_VERSION: str`: The current version of the A2A protocol (e.g., "v1").
+    *   `A2A_BASE_PATH: str`: The base path used in all A2A topics (e.g., "a2a/v1").
+*   **Topic Construction Functions**:
+    *   `get_a2a_base_topic(namespace: str) -> str`: Returns the base topic prefix for all A2A communication.
+    *   `get_discovery_topic(namespace: str) -> str`: Returns the topic for agent card discovery.
+    *   `get_agent_request_topic(namespace: str, agent_name: str) -> str`: Returns the topic for sending requests to a specific agent.
+    *   `get_gateway_status_topic(namespace: str, gateway_id: str, task_id: str) -> str`: Returns the topic for an agent to publish status updates to a gateway.
+    *   `get_gateway_response_topic(namespace: str, gateway_id: str, task_id: str) -> str`: Returns the topic for an agent to publish final responses to a gateway.
+    *   `get_client_response_topic(namespace: str, client_id: str) -> str`: Returns the topic for publishing final responses to a specific client.
+    *   `get_client_status_topic(namespace: str, client_id: str, task_id: str) -> str`: Returns the topic for publishing status updates to a specific client.
+    *   ... and various functions for subscription topics (e.g., `get_gateway_status_subscription_topic`).
+*   **Message Translation Functions**:
+    *   `translate_a2a_to_adk_content(a2a_message: A2AMessage, log_identifier: str) -> adk_types.Content`: Translates an A2A `Message` object into the Google ADK `Content` format.
+    *   `format_adk_event_as_a2a(...) -> Tuple[Optional[JSONRPCResponse], ...]`: Translates an ADK `Event` into an A2A `JSONRPCResponse` containing a `TaskStatusUpdateEvent`.
+    *   `format_and_route_adk_event(...) -> Tuple[Optional[Dict], Optional[str], ...]`: A higher-level wrapper that formats an ADK event and determines the correct Solace topic to publish it to.
+
+#### agent_registry.py
+**Purpose:** Provides a simple, thread-safe, in-memory store for discovered `AgentCard` objects. This is useful for components that need to keep track of available agents in the network.
+**Import:** `from common.agent_registry import AgentRegistry`
+
+**Classes/Functions/Constants:**
+*   **`AgentRegistry`**: A thread-safe class for storing and managing agent cards.
+    *   `add_or_update_agent(self, agent_card: AgentCard)`: Adds a new agent or updates an existing one.
+    *   `get_agent(self, agent_name: str) -> Optional[AgentCard]`: Retrieves an agent card by its unique name.
+    *   `get_agent_names(self) -> List[str]`: Returns a sorted list of all discovered agent names.
+    *   `clear(self)`: Clears all agents from the registry.
+
+#### types.py
+**Purpose:** Defines all the Pydantic data models that constitute the A2A protocol. These types ensure data consistency and provide validation across all components.
+**Import:** `from common.types import Message, Task, AgentCard, JSONRPCRequest, TaskState`
+
+**Classes/Functions/Constants:**
+*   **Core Data Structures**:
+    *   `Message`: Represents a message from a user or agent, containing a list of `Part` objects.
+    *   `Part`: A discriminated union of `TextPart`, `FilePart`, and `DataPart`.
+    *   `Task`: The central object representing a complete task, including its ID, status, history, and artifacts.
+    *   `TaskStatus`: Describes the current state of a task (e.g., `WORKING`, `COMPLETED`).
+    *   `TaskState(Enum)`: An enumeration of all possible task states.
+    *   `AgentCard`: A comprehensive description of an agent's identity, capabilities, and skills.
+    *   `Artifact`: Represents a task output, such as a generated file or structured data.
+*   **JSON-RPC Structures**:
+    *   `JSONRPCRequest`: The base model for all JSON-RPC requests.
+    *   `JSONRPCResponse`: The base model for all JSON-RPC responses.
+    *   `SendTaskRequest`, `GetTaskRequest`, etc.: Specific request types inheriting from `JSONRPCRequest`.
+*   **Error Structures**:
+    *   `JSONRPCError`: The base model for errors.
+    *   `InternalError`, `TaskNotFoundError`, etc.: Specific error types inheriting from `JSONRPCError`.
+
+### Subdirectory APIs
+
+#### client/
+**Purpose:** Provides a high-level, asynchronous client library for discovering and interacting with remote A2A agents.
+**Key Exports:** `A2AClient`, `A2ACardResolver`
+**Import Examples:**
+```python
+from common.client import A2AClient, A2ACardResolver
+```
+
+#### middleware/
+**Purpose:** A pluggable middleware framework for customizing system behavior, such as resolving user-specific configurations and feature flags.
+**Key Exports:** `ConfigResolver`, `MiddlewareRegistry`
+**Import Examples:**
+```python
+from common.middleware import ConfigResolver, MiddlewareRegistry
+```
+
+#### server/
+**Purpose:** A complete, stand-alone server for building A2A-compliant agents, handling HTTP requests, JSON-RPC, and task lifecycle management.
+**Key Exports:** `A2AServer`, `TaskManager`, `InMemoryTaskManager`
+**Import Examples:**
+```python
+from common.server import A2AServer, TaskManager, InMemoryTaskManager
+```
+
+#### services/
+**Purpose:** A factory-based system for integrating external data sources for identity, employee information, and more.
+**Key Exports:** `BaseIdentityService`, `create_identity_service`
+**Import Examples:**
+```python
+from common.services.identity_service import create_identity_service, BaseIdentityService
+```
+
+#### utils/
+**Purpose:** A collection of cross-cutting utilities for caching, logging, MIME type handling, and dynamic content processing.
+**Key Exports:** `InMemoryCache`, `is_text_based_mime_type`, `resolve_embeds_in_string`
+**Import Examples:**
+```python
+from common.utils.in_memory_cache import InMemoryCache
+from common.utils import is_text_based_mime_type
+from common.utils.embeds import resolve_embeds_in_string
+```
+
+## Complete Usage Guide
+These examples demonstrate how to use the components from the `common` directory to build and interact with A2A agents.
+
+### 1. How to import and use classes from direct files
+This example shows basic usage of the protocol, types, and agent registry, which form the foundation of any A2A component.
+
+```python
+import uuid
+from common.a2a_protocol import get_agent_request_topic, get_gateway_status_topic
+from common.types import AgentCard,

solace_agent_mesh/common/constants.py

@@ -1,15 +1,2 @@
-SOLACE_AGENT_MESH_SYSTEM_SESSION_ID = "solace_agent_mesh_system_session_id"
 
-DEFAULT_IDENTITY_KEY_FIELD = "identity"
-
-ORCHESTRATOR_COMPONENT_NAME = "orchestrator"
-
-HISTORY_MEMORY_ROLE = "history"
-
-HISTORY_ACTION_ROLE = "tool_call"
-
-HISTORY_USER_ROLE = "user"
-
-HISTORY_SYSTEM_ROLE = "system"
-
-HISTORY_ASSISTANT_ROLE = "assistant"
+DEFAULT_COMMUNICATION_TIMEOUT = 600  # 10 minutes

solace_agent_mesh/common/middleware/__init__.py

@@ -0,0 +1,12 @@
+"""
+Middleware package for pluggable system components.
+
+This package provides a framework for pluggable middleware components that can be
+extended or replaced at runtime. The default implementations provide permissive
+behavior suitable for development and testing.
+"""
+
+from .config_resolver import ConfigResolver
+from .registry import MiddlewareRegistry
+
+__all__ = ["ConfigResolver", "MiddlewareRegistry"]

solace_agent_mesh/common/middleware/config_resolver.py

@@ -0,0 +1,130 @@
+"""
+Generic configuration resolution middleware for user-specific settings and feature availability.
+
+This module provides a pluggable interface for resolving user-specific configuration
+and determining feature availability. The default implementation provides passthrough
+behavior that allows all operations.
+"""
+
+from typing import Any, Dict, List
+from solace_ai_connector.common.log import log
+
+LOG_IDENTIFIER = "[ConfigResolver]"
+
+
+class ConfigResolver:
+    """
+    Resolves user-specific configuration and determines feature availability.
+
+    This class provides a generic interface for configuration resolution that can be
+    extended or replaced at runtime. The default implementation is permissive and
+    allows all operations.
+    """
+
+    @staticmethod
+    async def resolve_user_config(
+        user_identity: Any, gateway_context: Dict[str, Any], base_config: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Resolve user-specific configuration settings.
+
+        Args:
+            user_identity: Identifier for the user (username, email, ID, etc.)
+            gateway_context: Context information from the gateway (gateway_id, etc.)
+            base_config: Base configuration to start with
+
+        Returns:
+            Dict containing user-specific configuration. Default implementation
+            returns base_config unchanged.
+        """
+        log.debug(
+            "%s Resolving user config for identity: %s (default implementation)",
+            LOG_IDENTIFIER,
+            user_identity,
+        )
+        return base_config
+
+    @staticmethod
+    def is_feature_enabled(
+        user_config: Dict[str, Any],
+        feature_descriptor: Dict[str, Any],
+        context: Dict[str, Any],
+    ) -> bool:
+        """
+        Check if a feature is enabled for the user.
+
+        Args:
+            user_config: User-specific configuration from resolve_user_config
+            feature_descriptor: Description of the feature being checked
+            context: Additional context for the feature check
+
+        Returns:
+            True if feature is enabled, False otherwise. Default implementation
+            returns True (all features enabled).
+        """
+        feature_type = feature_descriptor.get("feature_type", "unknown")
+        feature_name = feature_descriptor.get("function_name", "unknown")
+
+        log.debug(
+            "%s Feature check for %s:%s - enabled (default implementation)",
+            LOG_IDENTIFIER,
+            feature_type,
+            feature_name,
+        )
+        return True
+
+    @staticmethod
+    def validate_operation_config(
+        user_config: Dict[str, Any],
+        operation_spec: Dict[str, Any],
+        validation_context: Dict[str, Any],
+    ) -> Dict[str, Any]:
+        """
+        Validate operation against user configuration.
+
+        Args:
+            user_config: User-specific configuration from resolve_user_config
+            operation_spec: Specification of the operation being validated
+            validation_context: Additional context for validation
+
+        Returns:
+            Dict with validation result. Must include 'valid' boolean key.
+            Default implementation returns valid=True for all operations.
+        """
+        operation_type = operation_spec.get("operation_type", "unknown")
+
+        log.debug(
+            "%s Operation validation for %s - valid (default implementation)",
+            LOG_IDENTIFIER,
+            operation_type,
+        )
+
+        return {
+            "valid": True,
+            "reason": "default_validation",
+            "operation_type": operation_type,
+        }
+
+    @staticmethod
+    def filter_available_options(
+        user_config: Dict[str, Any],
+        available_options: List[Dict[str, Any]],
+        filter_context: Dict[str, Any],
+    ) -> List[Dict[str, Any]]:
+        """
+        Filter available options based on user configuration.
+
+        Args:
+            user_config: User-specific configuration from resolve_user_config
+            available_options: List of available options to filter
+            filter_context: Additional context for filtering
+
+        Returns:
+            Filtered list of options. Default implementation returns all options.
+        """
+        log.debug(
+            "%s Filtering %d options - returning all (default implementation)",
+            LOG_IDENTIFIER,
+            len(available_options),
+        )
+        return available_options