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

solace_agent_mesh/gateway/http_sse/components/__init__.py

@@ -0,0 +1,7 @@
+"""
+Makes components within this directory importable.
+"""
+
+from .visualization_forwarder_component import VisualizationForwarderComponent
+
+__all__ = ["VisualizationForwarderComponent"]

solace_agent_mesh/gateway/http_sse/components/components_llm.txt

@@ -0,0 +1,65 @@
+## Quick Summary
+This directory contains components for the HTTP SSE (Server-Sent Events) gateway, designed to work within the Solace AI Connector (SAC) framework. The primary component forwards messages received from the Solace broker to an internal queue, enabling real-time visualization in a web-based user interface.
+
+## Files Overview
+- `__init__.py`: Makes the `VisualizationForwarderComponent` class directly importable from the `components` package.
+- `visualization_forwarder_component.py`: Defines a component that forwards messages from a broker input to a Python `queue.Queue` for visualization.
+
+## Developer API Reference
+
+### __init__.py
+**Purpose:** Exposes the public components of this directory for easy importing.
+**Import:** `from gateway.http_sse.components import VisualizationForwarderComponent`
+
+**Exports:**
+- `VisualizationForwarderComponent`: The main component class for forwarding messages to a visualization queue.
+
+---
+
+### visualization_forwarder_component.py
+**Purpose:** A Solace AI Connector (SAC) component that listens for messages from a `BrokerInput` and forwards them to a specified Python `queue.Queue`. This is primarily used to send data to the Web UI for real-time display.
+**Import:** `from gateway.http_sse.components.visualization_forwarder_component import VisualizationForwarderComponent`
+
+**Classes:**
+- `VisualizationForwarderComponent(**kwargs: Any)` - A component that forwards messages to a target queue. It is initialized with configuration parameters, most importantly `target_queue_ref`.
+  - `invoke(self, message: SolaceMessage, data: Dict[str, Any]) -> None` - The core method called by the SAC framework for each incoming message. It formats the data and places it onto the target queue. This method should not be called directly by developers; the framework handles its execution.
+
+**Constants/Variables:**
+- `info: Dict` - A metadata dictionary required by the SAC framework. It describes the component's configuration parameters, input schema, and purpose. This is for framework use and not for direct interaction.
+
+**Usage Examples:**
+```python
+import queue
+from gateway.http_sse.components import VisualizationForwarderComponent
+from solace_ai_connector.common.message import Message as SolaceMessage
+
+# 1. Create a target queue that will receive the forwarded messages.
+#    This queue is typically managed by another component, like a Web UI backend.
+visualization_queue = queue.Queue()
+
+# 2. Instantiate the component, providing a reference to the target queue.
+#    This is usually done within a SAC flow configuration file.
+forwarder = VisualizationForwarderComponent(
+    name="my_forwarder",
+    target_queue_ref=visualization_queue
+)
+
+# 3. The `invoke` method is called automatically by the SAC framework when a message
+#    arrives from a connected BrokerInput component.
+
+# Example of what the consuming component would get from the queue:
+# A dictionary containing the message topic, payload, and other details.
+#
+# if not visualization_queue.empty():
+#     forwarded_data = visualization_queue.get()
+#     print(f"Received topic: {forwarded_data['topic']}")
+#     print(f"Received payload: {forwarded_data['payload']}")
+#
+# Expected structure of `forwarded_data`:
+# {
+#     "topic": "some/broker/topic",
+#     "payload": {"key": "value"},
+#     "user_properties": {"prop1": "value1"},
+#     "_original_broker_message": <SolaceMessage object>
+# }
+```

solace_agent_mesh/gateway/http_sse/components/visualization_forwarder_component.py

@@ -0,0 +1,108 @@
+"""
+SAC Component to forward messages from an internal BrokerInput
+to the WebUIBackendComponent's internal queue for visualization.
+"""
+
+import queue
+from typing import Any, Dict
+
+from solace_ai_connector.components.component_base import ComponentBase
+from solace_ai_connector.common.message import Message as SolaceMessage
+from solace_ai_connector.common.log import log
+
+info = {
+    "class_name": "VisualizationForwarderComponent",
+    "description": (
+        "Forwards A2A messages from an internal BrokerInput to the main "
+        "WebUIBackendComponent's internal queue for visualization."
+    ),
+    "config_parameters": [
+        {
+            "name": "target_queue_ref",
+            "required": True,
+            "type": "queue.Queue",
+            "description": "A direct reference to the target queue.Queue instance in WebUIBackendComponent.",
+        }
+    ],
+    "input_schema": {
+        "type": "object",
+        "description": "Output from a BrokerInput component.",
+        "properties": {
+            "payload": {"type": "any", "description": "The message payload."},
+            "topic": {"type": "string", "description": "The message topic."},
+            "user_properties": {
+                "type": "object",
+                "description": "User properties of the message.",
+            },
+        },
+        "required": ["payload", "topic"],
+    },
+    "output_schema": None,
+}
+
+
+class VisualizationForwarderComponent(ComponentBase):
+    """
+    A simple SAC component that takes messages from its input (typically
+    from a BrokerInput) and puts them onto a target Python queue.Queue
+    instance provided in its configuration.
+    """
+
+    def __init__(self, **kwargs: Any):
+        super().__init__(info, **kwargs)
+        self.target_queue: queue.Queue = self.get_config("target_queue_ref")
+        if not isinstance(self.target_queue, queue.Queue):
+            log.error(
+                "%s Configuration 'target_queue_ref' is not a valid queue.Queue instance. Type: %s",
+                self.log_identifier,
+                type(self.target_queue),
+            )
+            raise ValueError(
+                f"{self.log_identifier} 'target_queue_ref' must be a queue.Queue instance."
+            )
+        log.info("%s VisualizationForwarderComponent initialized.", self.log_identifier)
+
+    def invoke(self, message: SolaceMessage, data: Dict[str, Any]) -> None:
+        """
+        Processes the incoming message and forwards it.
+
+        Args:
+            message: The SolaceMessage object from BrokerInput (this is the original message).
+            data: The data extracted by BrokerInput's output_schema (payload, topic, user_properties).
+        """
+        log_id_prefix = f"{self.log_identifier}[Invoke]"
+        try:
+
+            forward_data = {
+                "topic": data.get("topic"),
+                "payload": data.get("payload"),
+                "user_properties": data.get("user_properties"),
+                "_original_broker_message": message,
+            }
+            log.debug(
+                "%s Forwarding message for topic: %s",
+                log_id_prefix,
+                forward_data["topic"],
+            )
+            try:
+                self.target_queue.put_nowait(forward_data)
+            except queue.Full:
+                log.warning(
+                    "%s Visualization queue is full. Message dropped. Current size: %d",
+                    log_id_prefix,
+                    self.target_queue.qsize(),
+                )
+
+            message.call_acknowledgements()
+            log.debug("%s Message acknowledged to BrokerInput.", log_id_prefix)
+
+        except Exception as e:
+            log.exception(
+                "%s Error in VisualizationForwarderComponent invoke: %s",
+                log_id_prefix,
+                e,
+            )
+            if message:
+                message.call_negative_acknowledgements()
+            raise
+        return None

solace_agent_mesh/gateway/http_sse/dependencies.py

@@ -0,0 +1,316 @@
+"""
+Defines FastAPI dependency injectors to access shared resources
+managed by the WebUIBackendComponent.
+"""
+
+from fastapi import Depends, HTTPException, status, Request
+from typing import (
+    TYPE_CHECKING,
+    Callable,
+    Dict,
+    Optional,
+    Any,
+)
+import os
+
+from solace_ai_connector.common.log import log
+from ...gateway.http_sse.sse_manager import SSEManager
+from ...gateway.http_sse.session_manager import SessionManager
+from ...common.agent_registry import AgentRegistry
+
+from ...gateway.http_sse.services.agent_service import AgentService
+from ...gateway.http_sse.services.task_service import TaskService
+from ...gateway.http_sse.services.people_service import PeopleService
+from ...gateway.base.task_context import TaskContextManager
+
+from ...core_a2a.service import CoreA2AService
+from ...common.services.identity_service import BaseIdentityService
+from ...common.middleware.config_resolver import ConfigResolver
+
+from google.adk.artifacts import BaseArtifactService
+
+
+if TYPE_CHECKING:
+    from gateway.http_sse.component import WebUIBackendComponent
+
+sac_component_instance: "WebUIBackendComponent" = None
+
+api_config: Optional[Dict[str, Any]] = None
+
+
+def set_component_instance(component: "WebUIBackendComponent"):
+    """Called by the component during its startup to provide its instance."""
+    global sac_component_instance
+    if sac_component_instance is None:
+        sac_component_instance = component
+        log.info("[Dependencies] SAC Component instance provided.")
+    else:
+        log.warning("[Dependencies] SAC Component instance already set.")
+
+
+def set_api_config(config: Dict[str, Any]):
+    """Called during startup to provide API configuration."""
+    global api_config
+    if api_config is None:
+        api_config = config
+        log.info("[Dependencies] API configuration provided.")
+    else:
+        log.warning("[Dependencies] API configuration already set.")
+
+
+def get_sac_component() -> "WebUIBackendComponent":
+    """FastAPI dependency to get the SAC component instance."""
+    if sac_component_instance is None:
+        log.critical(
+            "[Dependencies] SAC Component instance accessed before it was set!"
+        )
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Backend component not yet initialized.",
+        )
+    return sac_component_instance
+
+
+def get_api_config() -> Dict[str, Any]:
+    """FastAPI dependency to get the API configuration."""
+    if api_config is None:
+        log.critical("[Dependencies] API configuration accessed before it was set!")
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="API configuration not yet initialized.",
+        )
+    return api_config
+
+
+def get_agent_registry(
+    component: "WebUIBackendComponent" = Depends(get_sac_component),
+) -> AgentRegistry:
+    """FastAPI dependency to get the AgentRegistry."""
+    log.debug("[Dependencies] get_agent_registry called")
+    return component.get_agent_registry()
+
+
+def get_sse_manager(
+    component: "WebUIBackendComponent" = Depends(get_sac_component),
+) -> SSEManager:
+    """FastAPI dependency to get the SSEManager."""
+    log.debug("[Dependencies] get_sse_manager called")
+    return component.get_sse_manager()
+
+
+def get_session_manager(
+    component: "WebUIBackendComponent" = Depends(get_sac_component),
+) -> SessionManager:
+    """FastAPI dependency to get the SessionManager."""
+    log.debug("[Dependencies] get_session_manager called")
+    return component.get_session_manager()
+
+
+def get_user_id_callable(
+    session_manager: SessionManager = Depends(get_session_manager),
+) -> Callable:
+    """Dependency that provides the callable for getting user_id (client_id)."""
+    log.debug("[Dependencies] Providing user_id callable")
+    return session_manager.dep_get_client_id()
+
+
+def ensure_session_id_callable(
+    session_manager: SessionManager = Depends(get_session_manager),
+) -> Callable:
+    """Dependency that provides the callable for ensuring session_id."""
+    log.debug("[Dependencies] Providing ensure_session_id callable")
+    return session_manager.dep_ensure_session_id()
+
+
+def get_user_id(
+    request: Request,
+    session_manager: SessionManager = Depends(get_session_manager),
+) -> str:
+    """
+    FastAPI dependency that returns the user's identity.
+    It prioritizes the authenticated user from `request.state.user` (set by AuthMiddleware)
+    and falls back to the SessionManager for non-authenticated or legacy scenarios.
+    """
+    log.debug("[Dependencies] Resolving user_id string")
+
+    if hasattr(request.state, "user") and request.state.user:
+        user_id = request.state.user.get("id")
+        if user_id:
+            log.debug(f"[Dependencies] Using user ID from AuthMiddleware: {user_id}")
+            return user_id
+        else:
+            log.warning(
+                "[Dependencies] request.state.user exists but has no 'id' field. Falling back."
+            )
+
+    log.debug("[Dependencies] Falling back to SessionManager for user_id")
+    try:
+        return session_manager.get_a2a_client_id(request)
+    except AssertionError:
+        return f"anonymous_user:{os.urandom(8).hex()}"
+
+
+def ensure_session_id(
+    request: Request,
+    session_manager: SessionManager = Depends(get_session_manager),
+) -> str:
+    """FastAPI dependency that directly returns the ensured session_id string."""
+    log.debug("[Dependencies] Resolving ensured session_id string")
+    return session_manager.ensure_a2a_session(request)
+
+
+def get_identity_service(
+    component: "WebUIBackendComponent" = Depends(get_sac_component),
+) -> Optional[BaseIdentityService]:
+    """FastAPI dependency to get the configured IdentityService instance."""
+    log.debug("[Dependencies] get_identity_service called")
+    return component.identity_service
+
+
+def get_people_service(
+    identity_service: Optional[BaseIdentityService] = Depends(get_identity_service),
+) -> PeopleService:
+    """FastAPI dependency to get an instance of PeopleService."""
+    log.debug("[Dependencies] get_people_service called")
+    return PeopleService(identity_service=identity_service)
+
+
+PublishFunc = Callable[[str, Dict, Optional[Dict]], None]
+
+
+def get_publish_a2a_func(
+    component: "WebUIBackendComponent" = Depends(get_sac_component),
+) -> PublishFunc:
+    """FastAPI dependency to get the component's publish_a2a method."""
+    log.debug("[Dependencies] get_publish_a2a_func called")
+    return component.publish_a2a
+
+
+def get_namespace(
+    component: "WebUIBackendComponent" = Depends(get_sac_component),
+) -> str:
+    """FastAPI dependency to get the A2A namespace."""
+    log.debug("[Dependencies] get_namespace called")
+    return component.get_namespace()
+
+
+def get_gateway_id(
+    component: "WebUIBackendComponent" = Depends(get_sac_component),
+) -> str:
+    """FastAPI dependency to get the Gateway ID."""
+    log.debug("[Dependencies] get_gateway_id called")
+    return component.get_gateway_id()
+
+
+def get_config_resolver(
+    component: "WebUIBackendComponent" = Depends(get_sac_component),
+) -> ConfigResolver:
+    """FastAPI dependency to get the ConfigResolver."""
+    log.debug("[Dependencies] get_config_resolver called")
+    return component.get_config_resolver()
+
+
+def get_app_config(
+    component: "WebUIBackendComponent" = Depends(get_sac_component),
+) -> Dict[str, Any]:
+    """
+    FastAPI dependency to safely get the application configuration dictionary.
+    """
+    log.debug("[Dependencies] get_app_config called")
+    return component.component_config.get("app_config", {})
+
+
+async def get_user_config(
+    request: Request,
+    user_id: str = Depends(get_user_id),
+    config_resolver: ConfigResolver = Depends(get_config_resolver),
+    component: "WebUIBackendComponent" = Depends(get_sac_component),
+    app_config: Dict[str, Any] = Depends(get_app_config),
+) -> Dict[str, Any]:
+    """
+    FastAPI dependency to get the user-specific configuration.
+    """
+    log.debug(f"[Dependencies] get_user_config called for user_id: {user_id}")
+    gateway_context = {
+        "gateway_id": component.gateway_id,
+        "gateway_app_config": app_config,
+        "request": request,
+    }
+    return await config_resolver.resolve_user_config(
+        user_id, gateway_context, app_config
+    )
+
+
+def get_shared_artifact_service(
+    component: "WebUIBackendComponent" = Depends(get_sac_component),
+) -> Optional[BaseArtifactService]:
+    """FastAPI dependency to get the shared ArtifactService."""
+    log.debug("[Dependencies] get_shared_artifact_service called")
+    return component.get_shared_artifact_service()
+
+
+def get_embed_config(
+    component: "WebUIBackendComponent" = Depends(get_sac_component),
+) -> Dict[str, Any]:
+    """FastAPI dependency to get embed-related configuration."""
+    log.debug("[Dependencies] get_embed_config called")
+    return component.get_embed_config()
+
+
+def get_core_a2a_service(
+    component: "WebUIBackendComponent" = Depends(get_sac_component),
+) -> CoreA2AService:
+    """FastAPI dependency to get the CoreA2AService."""
+    log.debug("[Dependencies] get_core_a2a_service called")
+    core_service = component.get_core_a2a_service()
+    if core_service is None:
+        log.critical("[Dependencies] CoreA2AService accessed before initialization!")
+        raise HTTPException(status_code=503, detail="Core service not ready.")
+    return core_service
+
+
+def get_task_context_manager_from_component(
+    component: "WebUIBackendComponent" = Depends(get_sac_component),
+) -> TaskContextManager:
+    """FastAPI dependency to get the TaskContextManager from the component."""
+    log.debug("[Dependencies] get_task_context_manager_from_component called")
+    if component.task_context_manager is None:
+        log.critical(
+            "[Dependencies] TaskContextManager accessed before initialization!"
+        )
+        raise HTTPException(status_code=503, detail="Task context manager not ready.")
+    return component.task_context_manager
+
+
+def get_agent_service(
+    registry: AgentRegistry = Depends(get_agent_registry),
+) -> AgentService:
+    """FastAPI dependency to get an instance of AgentService."""
+    log.debug("[Dependencies] get_agent_service called")
+    return AgentService(agent_registry=registry)
+
+
+def get_task_service(
+    core_a2a_service: CoreA2AService = Depends(get_core_a2a_service),
+    publish_func: PublishFunc = Depends(get_publish_a2a_func),
+    namespace: str = Depends(get_namespace),
+    gateway_id: str = Depends(get_gateway_id),
+    sse_manager: SSEManager = Depends(get_sse_manager),
+    task_context_manager: TaskContextManager = Depends(
+        get_task_context_manager_from_component
+    ),
+    component: "WebUIBackendComponent" = Depends(get_sac_component),
+) -> TaskService:
+    """FastAPI dependency to get an instance of TaskService."""
+    log.debug("[Dependencies] get_task_service called")
+    app_name = component.get_config("name", "WebUIBackendApp")
+    return TaskService(
+        core_a2a_service=core_a2a_service,
+        publish_func=publish_func,
+        namespace=namespace,
+        gateway_id=gateway_id,
+        sse_manager=sse_manager,
+        task_context_map=task_context_manager._contexts,
+        task_context_lock=task_context_manager._lock,
+        app_name=app_name,
+    )

solace_agent_mesh/gateway/http_sse/http_sse_llm.txt

@@ -0,0 +1,63 @@
+Here is the comprehensive developer guide for the `http_sse` directory.
+
+## Quick Summary
+The `http_sse` directory implements a complete HTTP/SSE (Server-Sent Events) gateway for the A2A (Agent-to-Agent) system. Its primary purpose is to serve a web-based user interface and act as a bridge between standard web protocols (HTTP, WebSockets/SSE) and the backend A2A messaging fabric.
+
+The architecture is centered around the `WebUIBackendComponent`, a custom Solace AI Connector (SAC) component that hosts an embedded FastAPI web server. This component manages shared state and resources, such as the `SSEManager` for real-time updates, the `SessionManager` for user sessions, and the `AgentRegistry` for discovering available agents.
+
+Subdirectories organize the functionality:
+-   `routers/` defines the REST API endpoints (e.g., `/tasks`, `/agents`).
+-   `services/` contains the business logic that the API endpoints call.
+-   `dependencies.py` uses FastAPI's dependency injection system to provide the routers and services with safe access to the shared resources managed by the main component.
+-   `components/` contains specialized SAC components, for example, to forward A2A messages for real-time visualization.
+
+This design creates a clean separation of concerns, where the web layer (FastAPI) is decoupled from the core messaging and state management layer (SAC Component).
+
+## Files and Subdirectories Overview
+- **Direct files:**
+    - `__init__.py`: Standard Python package initializer.
+    - `app.py`: Defines the main SAC `WebUIBackendApp`, which specifies configuration and launches the component.
+    - `component.py`: The core SAC component that hosts the FastAPI server and manages all shared resources and A2A logic.
+    - `dependencies.py`: Provides FastAPI dependency injectors for accessing shared resources like services and managers.
+    - `main.py`: The main FastAPI application instance, including middleware, router mounting, and exception handling.
+    - `session_manager.py`: Manages web user sessions and maps them to unique A2A client and session IDs.
+    - `sse_manager.py`: Manages Server-Sent Event (SSE) connections for streaming real-time updates to clients.
+- **Subdirectories:**
+    - `components/`: Contains specialized SAC components, such as for forwarding messages to the visualization system.
+    - `routers/`: Defines the FastAPI `APIRouter` modules for all REST API endpoints.
+    - `services/`: Encapsulates business logic for agents, tasks, and other domain-specific operations.
+
+## Developer API Reference
+
+### Direct Files
+
+#### app.py
+**Purpose:** This file defines the `WebUIBackendApp`, a custom SAC (Solace AI Connector) App class. It is responsible for defining the configuration schema for the entire HTTP/SSE gateway and programmatically creating the `WebUIBackendComponent`.
+**Import:** `from gateway.http_sse.app import WebUIBackendApp`
+
+**Classes/Functions/Constants:**
+-   **`WebUIBackendApp(BaseGatewayApp)`**: The main application class. It extends `BaseGatewayApp` and adds a list of WebUI-specific configuration parameters to the application schema.
+-   **`SPECIFIC_APP_SCHEMA_PARAMS: List[Dict[str, Any]]`**: A constant list defining the configuration parameters specific to the HTTP/SSE gateway, such as `session_secret_key`, `fastapi_host`, `fastapi_port`, and various frontend-related settings.
+
+#### component.py
+**Purpose:** This is the core component of the gateway. It hosts the FastAPI server, manages all shared state (like the SSE and Session managers), handles the lifecycle of the web server, and implements the logic for translating between external HTTP requests and internal A2A messages.
+**Import:** `from gateway.http_sse.component import WebUIBackendComponent`
+
+**Classes/Functions/Constants:**
+-   **`WebUIBackendComponent(BaseGatewayComponent)`**: The main component class. Developers will primarily interact with its instances via the dependency injection system.
+    -   **Public Accessor Methods (for Dependencies):**
+        -   `get_sse_manager() -> SSEManager`: Returns the shared `SSEManager` instance.
+        -   `get_session_manager() -> SessionManager`: Returns the shared `SessionManager` instance.
+        -   `get_agent_registry() -> AgentRegistry`: Returns the shared `AgentRegistry` instance.
+        -   `get_core_a2a_service() -> CoreA2AService`: Returns the core service for creating A2A messages.
+        -   `get_shared_artifact_service() -> Optional[BaseArtifactService]`: Returns the service for artifact storage.
+        -   `get_namespace() -> str`: Returns the configured A2A namespace.
+        -   `get_gateway_id() -> str`: Returns the unique ID of this gateway.
+    -   **Core Logic Methods:**
+        -   `publish_a2a(topic: str, payload: Dict, user_properties: Optional[Dict] = None)`: Publishes a message onto the A2A messaging fabric. This is the primary method for sending data to agents.
+    -   **Gateway-Development-Kit (GDK) Hooks:** These methods implement the `BaseGatewayComponent` abstract interface.
+        -   `_start_listener()`: Starts the FastAPI/Uvicorn server.
+        -   `_stop_listener()`: Stops the FastAPI/Uvicorn server.
+        -   `_translate_external_input(...)`: Translates an incoming HTTP request (e.g., form data with files) into a structured A2A message (`List[A2APart]`).
+        -   `_send_update_to_external(...)`: Sends an intermediate status update from an agent back to the client via SSE.
+        -