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

solace_agent_mesh/common/a2a/protocol.py

@@ -0,0 +1,513 @@
+"""
+Helpers for A2A protocol-level concerns, such as topic construction and
+parsing of JSON-RPC requests and responses.
+"""
+import re
+import uuid
+from typing import Any, Dict, Optional, Union
+
+from solace_ai_connector.common.log import log
+
+from a2a.types import (
+    A2ARequest,
+    CancelTaskRequest,
+    GetTaskSuccessResponse,
+    InternalError,
+    InvalidRequestError,
+    JSONRPCError,
+    JSONRPCResponse,
+    JSONRPCSuccessResponse,
+    Message,
+    MessageSendParams,
+    SendMessageRequest,
+    SendMessageSuccessResponse,
+    SendStreamingMessageRequest,
+    SendStreamingMessageSuccessResponse,
+    Task,
+    TaskArtifactUpdateEvent,
+    TaskIdParams,
+    TaskStatusUpdateEvent,
+)
+
+# --- Topic Construction Helpers ---
+
+A2A_VERSION = "v1"
+A2A_BASE_PATH = f"a2a/{A2A_VERSION}"
+
+
+def get_a2a_base_topic(namespace: str) -> str:
+    """Returns the base topic prefix for all A2A communication."""
+    if not namespace:
+        raise ValueError("A2A namespace cannot be empty.")
+    return f"{namespace.rstrip('/')}/{A2A_BASE_PATH}"
+
+
+def get_discovery_topic(namespace: str) -> str:
+    """Returns the topic for agent card discovery."""
+    return f"{get_a2a_base_topic(namespace)}/discovery/agentcards"
+
+
+def get_agent_request_topic(namespace: str, agent_name: str) -> str:
+    """Returns the topic for sending requests to a specific agent."""
+    if not agent_name:
+        raise ValueError("Agent name cannot be empty.")
+    return f"{get_a2a_base_topic(namespace)}/agent/request/{agent_name}"
+
+
+def get_gateway_status_topic(namespace: str, gateway_id: str, task_id: str) -> str:
+    """
+    Returns the specific topic for an agent to publish status updates TO a specific gateway instance.
+    """
+    if not gateway_id:
+        raise ValueError("Gateway ID cannot be empty.")
+    if not task_id:
+        raise ValueError("Task ID cannot be empty.")
+    return f"{get_a2a_base_topic(namespace)}/gateway/status/{gateway_id}/{task_id}"
+
+
+def get_gateway_response_topic(namespace: str, gateway_id: str, task_id: str) -> str:
+    """
+    Returns the specific topic for an agent to publish the final response TO a specific gateway instance.
+    Includes task_id for potential correlation/filtering, though gateway might subscribe more broadly.
+    """
+    if not gateway_id:
+        raise ValueError("Gateway ID cannot be empty.")
+    if not task_id:
+        raise ValueError("Task ID cannot be empty.")
+    return f"{get_a2a_base_topic(namespace)}/gateway/response/{gateway_id}/{task_id}"
+
+
+def get_gateway_status_subscription_topic(namespace: str, self_gateway_id: str) -> str:
+    """
+    Returns the wildcard topic for a gateway instance to subscribe to receive status updates
+    intended for it.
+    """
+    if not self_gateway_id:
+        raise ValueError("Gateway ID is required for gateway status subscription")
+    return f"{get_a2a_base_topic(namespace)}/gateway/status/{self_gateway_id}/>"
+
+
+def get_gateway_response_subscription_topic(
+    namespace: str, self_gateway_id: str
+) -> str:
+    """
+    Returns the wildcard topic for a gateway instance to subscribe to receive final responses
+    intended for it.
+    """
+    if not self_gateway_id:
+        raise ValueError("Gateway ID is required for gateway response subscription")
+    return f"{get_a2a_base_topic(namespace)}/gateway/response/{self_gateway_id}/>"
+
+
+def get_peer_agent_status_topic(
+    namespace: str, delegating_agent_name: str, sub_task_id: str
+) -> str:
+    """
+    Returns the topic for publishing status updates for a sub-task *back to the delegating agent*.
+    This topic includes the delegating agent's name.
+    """
+    if not delegating_agent_name:
+        raise ValueError("delegating_agent_name is required for peer status topic")
+    return (
+        f"{get_a2a_base_topic(namespace)}/agent/status/{delegating_agent_name}/{sub_task_id}"
+    )
+
+
+def get_agent_response_topic(
+    namespace: str, delegating_agent_name: str, sub_task_id: str
+) -> str:
+    """
+    Returns the specific topic for publishing the final response for a sub-task
+    back to the delegating agent. Includes the delegating agent's name.
+    """
+    if not delegating_agent_name:
+        raise ValueError("delegating_agent_name is required for peer response topic")
+    if not sub_task_id:
+        raise ValueError("sub_task_id is required for peer response topic")
+    return f"{get_a2a_base_topic(namespace)}/agent/response/{delegating_agent_name}/{sub_task_id}"
+
+
+def get_agent_response_subscription_topic(namespace: str, self_agent_name: str) -> str:
+    """
+    Returns the wildcard topic for an agent to subscribe to receive responses
+    for tasks it delegated. Includes the agent's own name.
+    """
+    if not self_agent_name:
+        raise ValueError("self_agent_name is required for agent response subscription")
+    return f"{get_a2a_base_topic(namespace)}/agent/response/{self_agent_name}/>"
+
+
+def get_agent_status_subscription_topic(namespace: str, self_agent_name: str) -> str:
+    """
+    Returns the wildcard topic for an agent to subscribe to receive status updates
+    for tasks it delegated. Includes the agent's own name.
+    """
+    if not self_agent_name:
+        raise ValueError("self_agent_name is required for agent status subscription")
+    return f"{get_a2a_base_topic(namespace)}/agent/status/{self_agent_name}/>"
+
+
+def get_client_response_topic(namespace: str, client_id: str) -> str:
+    """Returns the topic for publishing the final response TO a specific client."""
+    if not client_id:
+        raise ValueError("Client ID cannot be empty.")
+    return f"{get_a2a_base_topic(namespace)}/client/response/{client_id}"
+
+
+def get_client_status_topic(namespace: str, client_id: str, task_id: str) -> str:
+    """
+    Returns the specific topic for publishing status updates for a task *to the original client*.
+    This topic is client and task-specific.
+    """
+    if not client_id:
+        raise ValueError("Client ID cannot be empty.")
+    if not task_id:
+        raise ValueError("Task ID cannot be empty.")
+    return f"{get_a2a_base_topic(namespace)}/client/status/{client_id}/{task_id}"
+
+
+def get_client_status_subscription_topic(namespace: str, client_id: str) -> str:
+    """
+    Returns the wildcard topic for a client to subscribe to receive status updates
+    for tasks it initiated. Includes the client's own ID.
+    """
+    if not client_id:
+        raise ValueError("Client ID cannot be empty.")
+    return f"{get_a2a_base_topic(namespace)}/client/status/{client_id}/>"
+
+
+def subscription_to_regex(subscription: str) -> str:
+    """Converts a Solace topic subscription string to a regex pattern."""
+    # Escape regex special characters except for Solace wildcards
+    pattern = re.escape(subscription)
+    # Replace Solace single-level wildcard '*' with regex equivalent '[^/]+'
+    pattern = pattern.replace(r"\*", r"[^/]+")
+    # Replace Solace multi-level wildcard '>' at the end with regex equivalent '.*'
+    if pattern.endswith(r"/>"):
+        pattern = pattern[:-1] + r".*"  # Remove escaped '>' and add '.*'
+    return pattern
+
+
+def topic_matches_subscription(topic: str, subscription: str) -> bool:
+    """Checks if a topic matches a Solace subscription pattern."""
+    regex_pattern = subscription_to_regex(subscription)
+    return re.fullmatch(regex_pattern, topic) is not None
+
+
+# --- JSON-RPC Envelope Helpers ---
+
+
+def get_request_id(request: A2ARequest) -> str | int:
+    """Gets the JSON-RPC request ID from any A2A request object."""
+    return request.root.id
+
+
+def get_request_method(request: A2ARequest) -> str:
+    """Gets the JSON-RPC method name from any A2A request object."""
+    return request.root.method
+
+
+def get_message_from_send_request(request: A2ARequest) -> Optional[Message]:
+    """
+    Safely gets the Message object from a SendMessageRequest or
+    SendStreamingMessageRequest. Returns None for other request types.
+    """
+    if isinstance(request.root, (SendMessageRequest, SendStreamingMessageRequest)):
+        return request.root.params.message
+    return None
+
+
+def get_task_id_from_cancel_request(request: A2ARequest) -> Optional[str]:
+    """Safely gets the task ID from a CancelTaskRequest."""
+    if isinstance(request.root, CancelTaskRequest):
+        return request.root.params.id
+    return None
+
+
+def get_response_id(response: JSONRPCResponse) -> Optional[Union[str, int]]:
+    """Safely gets the ID from any JSON-RPC response object."""
+    if hasattr(response.root, "id"):
+        return response.root.id
+    return None
+
+
+def get_response_result(response: JSONRPCResponse) -> Optional[Any]:
+    """Safely gets the result object from any successful JSON-RPC response."""
+    if hasattr(response.root, "result"):
+        return response.root.result
+    return None
+
+
+def get_response_error(response: JSONRPCResponse) -> Optional[JSONRPCError]:
+    """Safely gets the error object from any JSON-RPC error response."""
+    if hasattr(response.root, "error"):
+        return response.root.error
+    return None
+
+
+def get_error_message(error: JSONRPCError) -> str:
+    """Safely gets the message string from a JSONRPCError object."""
+    return error.message
+
+
+def get_error_code(error: JSONRPCError) -> int:
+    """Safely gets the code from a JSONRPCError object."""
+    return error.code
+
+
+def get_error_data(error: JSONRPCError) -> Optional[Any]:
+    """Safely gets the data from a JSONRPCError object."""
+    return error.data
+
+
+def create_success_response(
+    result: Any, request_id: Optional[Union[str, int]]
+) -> JSONRPCResponse:
+    """
+    Creates a successful JSON-RPC response object by wrapping the result in the
+    appropriate specific success response model based on the result's type.
+
+    Args:
+        result: The result payload (e.g., Task, TaskStatusUpdateEvent).
+        request_id: The ID of the original request.
+
+    Returns:
+        A new `JSONRPCResponse` object.
+
+    Raises:
+        TypeError: If the result type is not a supported A2A model.
+    """
+    specific_response: Any
+    if isinstance(result, (TaskStatusUpdateEvent, TaskArtifactUpdateEvent)):
+        specific_response = SendStreamingMessageSuccessResponse(
+            id=request_id, result=result
+        )
+    elif isinstance(result, Task):
+        # When returning a final task, GetTaskSuccessResponse is a suitable choice.
+        specific_response = GetTaskSuccessResponse(id=request_id, result=result)
+    else:
+        raise TypeError(
+            f"Unsupported result type for create_success_response: {type(result).__name__}"
+        )
+
+    return JSONRPCResponse(root=specific_response)
+
+
+def create_internal_error_response(
+    message: str,
+    request_id: Optional[Union[str, int]],
+    data: Optional[Dict[str, Any]] = None,
+) -> JSONRPCResponse:
+    """
+    Creates a JSON-RPC response object for an InternalError.
+
+    Args:
+        message: The error message.
+        request_id: The ID of the original request.
+        data: Optional structured data to include with the error.
+
+    Returns:
+        A new `JSONRPCResponse` object containing an `InternalError`.
+    """
+    error = create_internal_error(message=message, data=data)
+    return JSONRPCResponse(id=request_id, error=error)
+
+
+def create_invalid_request_error_response(
+    message: str,
+    request_id: Optional[Union[str, int]],
+    data: Optional[Any] = None,
+) -> JSONRPCResponse:
+    """
+    Creates a JSON-RPC response object for an InvalidRequestError.
+
+    Args:
+        message: The error message.
+        request_id: The ID of the original request.
+        data: Optional structured data to include with the error.
+
+    Returns:
+        A new `JSONRPCResponse` object containing an `InvalidRequestError`.
+    """
+    error = create_invalid_request_error(message=message, data=data)
+    return JSONRPCResponse(id=request_id, error=error)
+
+
+def create_internal_error(
+    message: str,
+    data: Optional[Dict[str, Any]] = None,
+) -> InternalError:
+    """
+    Creates an InternalError object.
+
+    Args:
+        message: The error message.
+        data: Optional structured data to include with the error.
+
+    Returns:
+        A new `InternalError` object.
+    """
+    return InternalError(message=message, data=data)
+
+
+def create_invalid_request_error(
+    message: str, data: Optional[Any] = None
+) -> InvalidRequestError:
+    """
+    Creates an InvalidRequestError object.
+
+    Args:
+        message: The error message.
+        data: Optional structured data to include with the error.
+
+    Returns:
+        A new `InvalidRequestError` object.
+    """
+    return InvalidRequestError(message=message, data=data)
+
+
+def create_generic_success_response(
+    result: Any, request_id: Optional[Union[str, int]] = None
+) -> JSONRPCSuccessResponse:
+    """
+    Creates a generic successful JSON-RPC response object.
+    Note: This is for non-A2A-spec-compliant endpoints that use a similar structure.
+
+    Args:
+        result: The result payload for the response.
+        request_id: The ID of the original request.
+
+    Returns:
+        A new `JSONRPCSuccessResponse` object.
+    """
+    return JSONRPCSuccessResponse(id=request_id, result=result)
+
+
+def create_error_response(
+    error: JSONRPCError,
+    request_id: Optional[Union[str, int]],
+) -> JSONRPCResponse:
+    """
+    Creates a JSON-RPC error response object from a given error model.
+
+    Args:
+        error: The JSONRPCError model instance.
+        request_id: The ID of the original request.
+
+    Returns:
+        A new `JSONRPCResponse` object containing the error.
+    """
+    return JSONRPCResponse(id=request_id, error=error)
+
+
+def create_cancel_task_request(task_id: str) -> CancelTaskRequest:
+    """
+    Creates a CancelTaskRequest object.
+
+    Args:
+        task_id: The ID of the task to cancel.
+
+    Returns:
+        A new `CancelTaskRequest` object.
+    """
+    params = TaskIdParams(id=task_id)
+    return CancelTaskRequest(id=uuid.uuid4().hex, params=params)
+
+
+def create_send_message_request(
+    message: Message,
+    task_id: str,
+    metadata: Optional[Dict[str, Any]] = None,
+) -> SendMessageRequest:
+    """
+    Creates a SendMessageRequest object.
+
+    Args:
+        message: The A2AMessage object to send.
+        task_id: The unique ID for the task.
+        metadata: Optional metadata for the send request.
+
+    Returns:
+        A new `SendMessageRequest` object.
+    """
+    send_params = MessageSendParams(message=message, metadata=metadata)
+    return SendMessageRequest(id=task_id, params=send_params)
+
+
+def create_send_streaming_message_request(
+    message: Message,
+    task_id: str,
+    metadata: Optional[Dict[str, Any]] = None,
+) -> SendStreamingMessageRequest:
+    """
+    Creates a SendStreamingMessageRequest object.
+
+    Args:
+        message: The A2AMessage object to send.
+        task_id: The unique ID for the task.
+        metadata: Optional metadata for the send request.
+
+    Returns:
+        A new `SendStreamingMessageRequest` object.
+    """
+    send_params = MessageSendParams(message=message, metadata=metadata)
+    return SendStreamingMessageRequest(id=task_id, params=send_params)
+
+
+def create_send_message_success_response(
+    result: Union[Task, Message], request_id: Optional[Union[str, int]]
+) -> SendMessageSuccessResponse:
+    """
+    Creates a SendMessageSuccessResponse object.
+
+    Args:
+        result: The result payload (Task or Message).
+        request_id: The ID of the original request.
+
+    Returns:
+        A new `SendMessageSuccessResponse` object.
+    """
+    return SendMessageSuccessResponse(id=request_id, result=result)
+
+
+def create_send_streaming_message_success_response(
+    result: Union[Task, Message, TaskStatusUpdateEvent, TaskArtifactUpdateEvent],
+    request_id: Optional[Union[str, int]],
+) -> SendStreamingMessageSuccessResponse:
+    """
+    Creates a SendStreamingMessageSuccessResponse object.
+
+    Args:
+        result: The result payload.
+        request_id: The ID of the original request.
+
+    Returns:
+        A new `SendStreamingMessageSuccessResponse` object.
+    """
+    return SendStreamingMessageSuccessResponse(id=request_id, result=result)
+
+
+def extract_task_id_from_topic(
+    topic: str, subscription_pattern: str, log_identifier: str
+) -> Optional[str]:
+    """Extracts the task ID from the end of a topic string based on the subscription."""
+    base_regex_str = subscription_to_regex(subscription_pattern).replace(r".*", "")
+    match = re.match(base_regex_str, topic)
+    if match:
+        task_id_part = topic[match.end() :]
+        task_id = task_id_part.lstrip("/")
+        if task_id:
+            log.debug(
+                "%s Extracted Task ID '%s' from topic '%s'",
+                log_identifier,
+                task_id,
+                topic,
+            )
+            return task_id
+    log.warning(
+        "%s Could not extract Task ID from topic '%s' using pattern '%s'",
+        log_identifier,
+        topic,
+        subscription_pattern,
+    )
+    return None

solace_agent_mesh/common/a2a/task.py

@@ -0,0 +1,127 @@
+"""
+Helpers for creating and consuming A2A Task objects.
+"""
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+from a2a.types import (
+    Artifact,
+    Message,
+    Task,
+    TaskState,
+    TaskStatus,
+)
+
+
+# --- Creation Helpers ---
+
+
+def create_initial_task(
+    task_id: str,
+    context_id: str,
+    agent_name: str,
+) -> Task:
+    """
+    Creates an initial Task object, typically for returning to a client
+    after a task has been submitted.
+
+    Args:
+        task_id: The unique ID for the task.
+        context_id: The context/session ID for the task.
+        agent_name: The name of the agent handling the task.
+
+    Returns:
+        A new `Task` object with 'submitted' status.
+    """
+    initial_status = TaskStatus(state=TaskState.submitted)
+    return Task(
+        id=task_id,
+        context_id=context_id,
+        status=initial_status,
+        kind="task",
+        metadata={"agent_name": agent_name},
+    )
+
+
+def create_task_status(
+    state: TaskState,
+    message: Optional[Message] = None,
+) -> TaskStatus:
+    """
+    Creates a TaskStatus object.
+
+    Args:
+        state: The state of the task.
+        message: An optional message providing more details.
+
+    Returns:
+        A new `TaskStatus` object with a current timestamp.
+    """
+    return TaskStatus(
+        state=state,
+        message=message,
+        timestamp=datetime.now(timezone.utc).isoformat(),
+    )
+
+
+def create_final_task(
+    task_id: str,
+    context_id: str,
+    final_status: TaskStatus,
+    artifacts: Optional[List[Artifact]] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+) -> Task:
+    """
+    Creates a final Task object, typically for sending as a final response.
+
+    Args:
+        task_id: The unique ID for the task.
+        context_id: The context/session ID for the task.
+        final_status: The final status of the task (e.g., completed, failed).
+        artifacts: A list of artifacts produced by the task.
+        metadata: Optional metadata to include in the task.
+
+    Returns:
+        A new `Task` object representing the final state.
+    """
+    return Task(
+        id=task_id,
+        context_id=context_id,
+        status=final_status,
+        artifacts=artifacts,
+        metadata=metadata,
+        kind="task",
+    )
+
+
+# --- Consumption Helpers ---
+
+
+def get_task_id(task: Task) -> str:
+    """Safely retrieves the ID from a Task object."""
+    return task.id
+
+
+def get_task_context_id(task: Task) -> str:
+    """Safely retrieves the context ID from a Task object."""
+    return task.context_id
+
+
+def get_task_status(task: Task) -> TaskState:
+    """Safely retrieves the state from a Task's status."""
+    return task.status.state
+
+
+def get_task_history(task: Task) -> Optional[List[Message]]:
+    """Safely retrieves the history from a Task object."""
+    return task.history
+
+
+def get_task_artifacts(task: Task) -> Optional[List[Artifact]]:
+    """Safely retrieves the artifacts from a Task object."""
+    return task.artifacts
+
+
+def get_task_metadata(task: Task) -> Optional[Dict[str, Any]]:
+    """Safely retrieves the metadata from a Task object."""
+    return task.metadata