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

solace_agent_mesh/common/client/client_llm.txt

@@ -1,133 +0,0 @@
-## 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/server/__init__.py

@@ -1,4 +0,0 @@
-from .server import A2AServer
-from .task_manager import TaskManager, InMemoryTaskManager
-
-__all__ = ["A2AServer", "TaskManager", "InMemoryTaskManager"]

solace_agent_mesh/common/server/server.py

@@ -1,122 +0,0 @@
-from starlette.applications import Starlette
-from starlette.responses import JSONResponse
-from sse_starlette.sse import EventSourceResponse
-from starlette.requests import Request
-from ...common.types import (
-    A2ARequest,
-    JSONRPCResponse,
-    InvalidRequestError,
-    JSONParseError,
-    GetTaskRequest,
-    CancelTaskRequest,
-    SendTaskRequest,
-    SetTaskPushNotificationRequest,
-    GetTaskPushNotificationRequest,
-    InternalError,
-    AgentCard,
-    TaskResubscriptionRequest,
-    SendTaskStreamingRequest,
-)
-from pydantic import ValidationError
-import json
-from typing import AsyncIterable, Any
-from solace_ai_connector.common.log import log
-
-from ...common.server.task_manager import TaskManager
-
-
-class A2AServer:
-    def __init__(
-        self,
-        host="0.0.0.0",
-        port=5000,
-        endpoint="/",
-        agent_card: AgentCard = None,
-        task_manager: TaskManager = None,
-    ):
-        self.host = host
-        self.port = port
-        self.endpoint = endpoint
-        self.task_manager = task_manager
-        self.agent_card = agent_card
-        self.app = Starlette()
-        self.app.add_route(self.endpoint, self._process_request, methods=["POST"])
-        self.app.add_route(
-            "/.well-known/agent.json", self._get_agent_card, methods=["GET"]
-        )
-
-    def start(self):
-        if self.agent_card is None:
-            raise ValueError("agent_card is not defined")
-
-        if self.task_manager is None:
-            raise ValueError("request_handler is not defined")
-
-        import uvicorn
-
-        uvicorn.run(self.app, host=self.host, port=self.port)
-
-    def _get_agent_card(self, request: Request) -> JSONResponse:
-        return JSONResponse(self.agent_card.model_dump(exclude_none=True))
-
-    async def _process_request(self, request: Request):
-        try:
-            body = await request.json()
-            json_rpc_request = A2ARequest.validate_python(body)
-
-            if isinstance(json_rpc_request, GetTaskRequest):
-                result = await self.task_manager.on_get_task(json_rpc_request)
-            elif isinstance(json_rpc_request, SendTaskRequest):
-                result = await self.task_manager.on_send_task(json_rpc_request)
-            elif isinstance(json_rpc_request, SendTaskStreamingRequest):
-                result = await self.task_manager.on_send_task_subscribe(
-                    json_rpc_request
-                )
-            elif isinstance(json_rpc_request, CancelTaskRequest):
-                result = await self.task_manager.on_cancel_task(json_rpc_request)
-            elif isinstance(json_rpc_request, SetTaskPushNotificationRequest):
-                result = await self.task_manager.on_set_task_push_notification(
-                    json_rpc_request
-                )
-            elif isinstance(json_rpc_request, GetTaskPushNotificationRequest):
-                result = await self.task_manager.on_get_task_push_notification(
-                    json_rpc_request
-                )
-            elif isinstance(json_rpc_request, TaskResubscriptionRequest):
-                result = await self.task_manager.on_resubscribe_to_task(
-                    json_rpc_request
-                )
-            else:
-                log.warning("Unexpected request type: %s", type(json_rpc_request))
-                raise ValueError("Unexpected request type: %s" % type(request))
-
-            return self._create_response(result)
-
-        except Exception as e:
-            return self._handle_exception(e)
-
-    def _handle_exception(self, e: Exception) -> JSONResponse:
-        if isinstance(e, json.decoder.JSONDecodeError):
-            json_rpc_error = JSONParseError()
-        elif isinstance(e, ValidationError):
-            json_rpc_error = InvalidRequestError(data=json.loads(e.json()))
-        else:
-            log.error("Unhandled exception: %s", e, exc_info=True)
-            json_rpc_error = InternalError()
-
-        response = JSONRPCResponse(id=None, error=json_rpc_error)
-        return JSONResponse(response.model_dump(exclude_none=True), status_code=400)
-
-    def _create_response(self, result: Any) -> JSONResponse | EventSourceResponse:
-        if isinstance(result, AsyncIterable):
-
-            async def event_generator(result) -> AsyncIterable[dict[str, str]]:
-                async for item in result:
-                    yield {"data": item.model_dump_json(exclude_none=True)}
-
-            return EventSourceResponse(event_generator(result))
-        elif isinstance(result, JSONRPCResponse):
-            return JSONResponse(result.model_dump(exclude_none=True))
-        else:
-            log.error("Unexpected result type: %s", type(result))
-            raise ValueError("Unexpected result type: %s" % type(result))

solace_agent_mesh/common/server/server_llm.txt

@@ -1,169 +0,0 @@
-## Quick Summary
-The `server` directory provides a complete, stand-alone Agent-to-Agent (A2A) communication server. It is built using Starlette and implements the JSON-RPC 2.0 protocol for handling various task-related requests, including standard request-response, task streaming via Server-Sent Events (SSE), and push notification management. It features an extensible task management system with a default in-memory implementation.
-
-## Files Overview
-- `__init__.py`: Exposes the primary public classes (`A2AServer`, `TaskManager`, `InMemoryTaskManager`) for easy access.
-- `server.py`: Contains the main `A2AServer` class, which sets up the Starlette web application, defines HTTP endpoints, and routes incoming A2A requests to the task manager.
-- `task_manager.py`: Defines the `TaskManager` abstract base class, which outlines the contract for handling all task operations, and provides a concrete `InMemoryTaskManager` implementation.
-- `utils.py`: A collection of utility functions for creating standardized error responses and checking modality compatibility.
-
-## Developer API Reference
-
-### __init__.py
-**Purpose:** This file makes the core server components available for direct import from the `server` package, simplifying access for developers.
-**Import:** `from solace_ai_connector.common.server import A2AServer, TaskManager, InMemoryTaskManager`
-
----
-
-### server.py
-**Purpose:** Implements the core HTTP server for Agent-to-Agent (A2A) communication. It handles JSON-RPC request parsing, routing to the appropriate task manager methods, and response generation, including support for Server-Sent Events (SSE).
-**Import:** `from solace_ai_connector.common.server import A2AServer`
-
-**Classes:**
-- `A2AServer(host: str = "0.0.0.0", port: int = 5000, endpoint: str = "/", agent_card: AgentCard = None, task_manager: TaskManager = None)` - A Starlette-based web server that exposes A2A endpoints.
-  - `start() -> None` - Starts the web server using uvicorn. Raises a `ValueError` if `agent_card` or `task_manager` are not set.
-  - `host: str` - The host address the server will bind to.
-  - `port: int` - The port the server will listen on.
-  - `endpoint: str` - The main API endpoint path for receiving JSON-RPC requests.
-  - `task_manager: TaskManager` - The handler responsible for all task-related business logic.
-  - `agent_card: AgentCard` - The metadata for the agent, served at `/.well-known/agent.json`.
-  
-**Usage Examples:**
-```python
-# main.py
-from solace_ai_connector.common.server import A2AServer, InMemoryTaskManager
-from solace_ai_connector.common.types import AgentCard
-
-# 1. Define the agent's capabilities and metadata
-my_agent_card = AgentCard(
-    id="my-awesome-agent-v1",
-    name="Awesome Agent",
-    version="1.0.0",
-    description="An agent that does awesome things.",
-    documentation_url="https://example.com/docs",
-    supported_tasks=["summarize", "translate"],
-    input_modalities=["text/plain"],
-    output_modalities=["text/plain"]
-)
-
-# 2. Instantiate a task manager (or use your own custom implementation)
-# This example uses a basic in-memory manager.
-# For a real agent, you would extend InMemoryTaskManager to implement your logic.
-class MyAgentTaskManager(InMemoryTaskManager):
-    async def on_send_task(self, request):
-        # Implement your agent's logic here
-        pass
-    async def on_send_task_subscribe(self, request):
-        # Implement your agent's streaming logic here
-        pass
-
-task_manager = MyAgentTaskManager()
-
-# 3. Create and configure the server
-server = A2AServer(
-    host="127.0.0.1",
-    port=8080,
-    endpoint="/api/v1/a2a",
-    agent_card=my_agent_card,
-    task_manager=task_manager
-)
-
-# 4. Start the server
-if __name__ == "__main__":
-    print("Starting A2A Server...")
-    server.start()
-```
-
----
-
-### task_manager.py
-**Purpose:** Defines the abstract interface for task management and provides a ready-to-use, in-memory implementation. This is the core component for implementing an agent's business logic.
-**Import:** `from solace_ai_connector.common.server import TaskManager, InMemoryTaskManager`
-
-**Classes:**
-- `TaskManager()` - An abstract base class that defines the interface for handling all A2A task-related operations. Developers must implement these methods in a subclass.
-  - `on_get_task(request: GetTaskRequest) -> GetTaskResponse` - Handles a request to retrieve the status and details of a task.
-  - `on_cancel_task(request: CancelTaskRequest) -> CancelTaskResponse` - Handles a request to cancel an ongoing task.
-  - `on_send_task(request: SendTaskRequest) -> SendTaskResponse` - Handles a standard request-response task submission.
-  - `on_send_task_subscribe(request: SendTaskStreamingRequest) -> Union[AsyncIterable[SendTaskStreamingResponse], JSONRPCResponse]` - Handles a task submission that requires a streaming response (SSE).
-  - `on_set_task_push_notification(request: SetTaskPushNotificationRequest) -> SetTaskPushNotificationResponse` - Handles a request to configure push notifications for a task.
-  - `on_get_task_push_notification(request: GetTaskPushNotificationRequest) -> GetTaskPushNotificationResponse` - Handles a request to retrieve the push notification configuration for a task.
-  - `on_resubscribe_to_task(request: TaskResubscriptionRequest) -> Union[AsyncIterable[SendTaskResponse], JSONRPCResponse]` - Handles a request to resubscribe to a streaming task.
-
-- `InMemoryTaskManager()` - A concrete implementation of `TaskManager` that stores tasks and push notification configurations in memory. It provides helper methods to manage task state and SSE subscriptions. It is designed to be extended.
-  - `upsert_task(task_send_params: TaskSendParams) -> Task` - Creates a new task or retrieves an existing one by its ID, adding the new message to its history.
-  - `update_store(task_id: str, status: TaskStatus, artifacts: list[Artifact]) -> Task` - Updates the status, message history, and artifacts of a specific task.
-  - `set_push_notification_info(task_id: str, notification_config: PushNotificationConfig) -> None` - Stores the push notification configuration for a given task.
-  - `get_push_notification_info(task_id: str) -> PushNotificationConfig` - Retrieves the push notification configuration for a given task.
-  - `has_push_notification_info(task_id: str) -> bool` - Checks if a push notification configuration exists for a task.
-  - `setup_sse_consumer(task_id: str, is_resubscribe: bool = False) -> asyncio.Queue` - Creates and registers an `asyncio.Queue` for a new SSE subscriber for a given task.
-  - `enqueue_events_for_sse(task_id: str, task_update_event: Any) -> None` - Puts a new event (e.g., `TaskStatusUpdateEvent`) into the queues of all active SSE subscribers for a task.
-  - `dequeue_events_for_sse(request_id: str, task_id: str, sse_event_queue: asyncio.Queue) -> AsyncIterable[SendTaskStreamingResponse]` - An async generator that yields events from an SSE queue, wrapping them in `SendTaskStreamingResponse` objects.
-
-**Usage Examples:**
-```python
-# custom_task_manager.py
-import asyncio
-from solace_ai_connector.common.server import InMemoryTaskManager
-from solace_ai_connector.common.types import (
-    SendTaskRequest, SendTaskResponse, Task, TaskStatus, TaskState,
-    SendTaskStreamingRequest, SendTaskStreamingResponse, TaskStatusUpdateEvent
-)
-from typing import AsyncIterable, Union
-
-class MyCustomTaskManager(InMemoryTaskManager):
-    # Implement the core logic for a standard task
-    async def on_send_task(self, request: SendTaskRequest) -> SendTaskResponse:
-        task = await self.upsert_task(request.params)
-        print(f"Received task {task.id} with message: {request.params.message.content}")
-        
-        # Simulate work
-        await asyncio.sleep(2)
-        
-        # Update task status to completed
-        final_status = TaskStatus(state=TaskState.COMPLETED)
-        await self.update_store(task.id, final_status, [])
-        
-        return SendTaskResponse(id=request.id, result=task)
-
-    # Implement the core logic for a streaming task
-    async def on_send_task_subscribe(
-        self, request: SendTaskStreamingRequest
-    ) -> Union[AsyncIterable[SendTaskStreamingResponse], JSONRPCResponse]:
-        
-        await self.upsert_task(request.params)
-        sse_queue = await self.setup_sse_consumer(request.params.id)
-
-        # Start the background task processing
-        asyncio.create_task(self._process_streaming_task(request.params.id))
-
-        # Return the async generator that will stream responses
-        return self.dequeue_events_for_sse(request.id, request.params.id, sse_queue)
-
-    async def _process_streaming_task(self, task_id: str):
-        # Simulate streaming work
-        for i in range(5):
-            await asyncio.sleep(1)
-            update = TaskStatusUpdateEvent(
-                status=TaskStatus(state=TaskState.IN_PROGRESS),
-                message={"content": f"Step {i+1} complete"}
-            )
-            # Enqueue the update for all subscribers
-            await self.enqueue_events_for_sse(task_id, update)
-        
-        # Send final event
-        final_update = TaskStatusUpdateEvent(
-            status=TaskStatus(state=TaskState.COMPLETED),
-            final=True
-        )
-        await self.enqueue_events_for_sse(task_id, final_update)
-```
-
----
-
-### utils.py
-**Purpose:** Provides common utility functions used within the server, primarily for creating standardized JSON-RPC error responses and performing compatibility checks.
-**Import:** `from solace_ai_connector.common.server.utils import are_modalities_compatible, new_incompatible_types_error, new_not_implemented_error`
-
-**Functions:**
-- `are_modalities_compatible(server_output_