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

solace_agent_mesh/common/data_parts.py

@@ -0,0 +1,99 @@
+"""
+Pydantic models for the structured data payloads used in A2A DataPart objects.
+These models correspond to the JSON schemas defined in a2a_spec/schemas/
+and are used for validating non-visible status update messages.
+"""
+
+from typing import Any, Dict, Literal, Union
+from pydantic import BaseModel, Field
+
+
+class ToolInvocationStartData(BaseModel):
+    """
+    Data model for a tool invocation start signal.
+    Corresponds to tool_invocation_start.json schema.
+    """
+
+    type: Literal["tool_invocation_start"] = Field(
+        "tool_invocation_start", description="The constant type for this data part."
+    )
+    tool_name: str = Field(..., description="The name of the tool being called.")
+    tool_args: Dict[str, Any] = Field(
+        ..., description="The arguments passed to the tool."
+    )
+    function_call_id: str = Field(
+        ..., description="The ID from the LLM's function call."
+    )
+
+
+class LlmInvocationData(BaseModel):
+    """
+    Data model for an LLM invocation signal.
+    Corresponds to llm_invocation.json schema.
+    """
+
+    type: Literal["llm_invocation"] = Field(
+        "llm_invocation", description="The constant type for this data part."
+    )
+    request: Dict[str, Any] = Field(
+        ...,
+        description="A sanitized representation of the LlmRequest object sent to the model.",
+    )
+
+
+class AgentProgressUpdateData(BaseModel):
+    """
+    Data model for an agent progress update signal.
+    Corresponds to agent_progress_update.json schema.
+    """
+
+    type: Literal["agent_progress_update"] = Field(
+        "agent_progress_update", description="The constant type for this data part."
+    )
+    status_text: str = Field(
+        ...,
+        description="A human-readable progress message (e.g., 'Analyzing the report...').",
+    )
+
+
+class ArtifactCreationProgressData(BaseModel):
+    """
+    Data model for an artifact creation progress signal.
+    Corresponds to artifact_creation_progress.json schema.
+    """
+
+    type: Literal["artifact_creation_progress"] = Field(
+        "artifact_creation_progress",
+        description="The constant type for this data part.",
+    )
+    filename: str = Field(..., description="The name of the artifact being created.")
+    bytes_saved: int = Field(..., description="The number of bytes saved so far.")
+    artifact_chunk: str = Field(
+        ...,
+        description="The chunk of artifact data that was saved in this progress update.",
+    )
+
+
+class ToolResultData(BaseModel):
+    """
+    Data model for a tool execution result signal.
+    Corresponds to tool_result.json schema.
+    """
+
+    type: Literal["tool_result"] = Field(
+        "tool_result", description="The constant type for this data part."
+    )
+    tool_name: str = Field(..., description="The name of the tool that was called.")
+    result_data: Any = Field(..., description="The data returned by the tool.")
+    function_call_id: str = Field(
+        ..., description="The ID from the LLM's function call."
+    )
+
+
+SignalData = Union[
+    ToolInvocationStartData,
+    LlmInvocationData,
+    AgentProgressUpdateData,
+    ArtifactCreationProgressData,
+    ToolResultData,
+]

solace_agent_mesh/common/middleware/middleware_llm.txt

@@ -1,4 +1,4 @@
-Here is the DEVELOPER GUIDE for the `middleware` directory.
+# DEVELOPER GUIDE: middleware
 
 ## Quick Summary
 The `middleware` directory provides a pluggable framework for system components that can be extended or replaced at runtime. It offers a registry system to dynamically bind custom implementations for core functionalities like configuration resolution. The default implementations provide permissive behavior, making them suitable for development and testing environments where all features are enabled by default.
@@ -13,22 +13,22 @@ The `middleware` directory provides a pluggable framework for system components
 ### __init__.py
 **Purpose:** This file serves as the entry point to the `middleware` package, exporting the primary public interfaces for developers to use.
 
+**Import:** `from solace_agent_mesh.common.middleware import ConfigResolver, MiddlewareRegistry`
+
 **Usage Examples:**
 ```python
 # Import the main classes directly from the middleware package
-from solace_ai_connector.common.middleware import ConfigResolver, MiddlewareRegistry
+from solace_agent_mesh.common.middleware import ConfigResolver, MiddlewareRegistry
 
 # Now you can use ConfigResolver and MiddlewareRegistry
 print(ConfigResolver)
 print(MiddlewareRegistry)
 ```
 
----
-
 ### config_resolver.py
 **Purpose:** This file provides a pluggable interface for resolving user-specific configuration and determining feature availability. The default `ConfigResolver` class is permissive, allowing all operations and enabling all features, which is ideal for development or simple deployments.
 
-**Import:** `from solace_ai_connector.common.middleware import ConfigResolver`
+**Import:** `from solace_agent_mesh.common.middleware import ConfigResolver`
 
 **Classes:**
 - `ConfigResolver()` - A class containing static methods to resolve user-specific configuration and determine feature availability. This default implementation is permissive.
@@ -40,7 +40,7 @@ print(MiddlewareRegistry)
 **Usage Examples:**
 ```python
 import asyncio
-from solace_ai_connector.common.middleware import ConfigResolver
+from solace_agent_mesh.common.middleware import ConfigResolver
 
 async def main():
     # Example user identity and base configuration
@@ -89,12 +89,10 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
----
-
 ### registry.py
 **Purpose:** This file provides the `MiddlewareRegistry`, a static class that allows developers to dynamically bind, or "plug in," their own custom middleware implementations at runtime. This is the core of the pluggable system.
 
-**Import:** `from solace_ai_connector.common.middleware import MiddlewareRegistry`
+**Import:** `from solace_agent_mesh.common.middleware import MiddlewareRegistry`
 
 **Classes:**
 - `MiddlewareRegistry()` - A registry for managing middleware implementations. All methods are class methods.
@@ -109,19 +107,19 @@ if __name__ == "__main__":
 ```python
 import asyncio
 from typing import Any, Dict, List
-from solace_ai_connector.common.middleware import MiddlewareRegistry, ConfigResolver
+from solace_agent_mesh.common.middleware import MiddlewareRegistry, ConfigResolver
 
 # 1. Define a custom ConfigResolver implementation
 class MyCustomConfigResolver:
     """A custom resolver that only allows 'admin' users to use 'gpt-4'."""
     @staticmethod
-    async def resolve_user_config(user_identity: Any, **kwargs) -> Dict[str, Any]:
+    async def resolve_user_config(user_identity: Any, gateway_context: Dict[str, Any], base_config: Dict[str, Any]) -> Dict[str, Any]:
         if user_identity == "admin":
             return {"role": "admin", "allowed_models": ["gpt-4", "gpt-3.5-turbo"]}
         return {"role": "user", "allowed_models": ["gpt-3.5-turbo"]}
 
     @staticmethod
-    def validate_operation_config(user_config: Dict, operation_spec: Dict, **kwargs) -> Dict:
+    def validate_operation_config(user_config: Dict, operation_spec: Dict, validation_context: Dict) -> Dict:
         model = operation_spec.get("model")
         if model and model not in user_config.get("allowed_models", []):
             return {"valid": False, "reason": f"Model '{model}' not allowed for this user."}
@@ -151,16 +149,16 @@ async def check_permissions():
     print(f"Current resolver is: {CurrentResolver.__name__}")
 
     # Check an admin user
-    admin_config = await CurrentResolver.resolve_user_config("admin")
+    admin_config = await CurrentResolver.resolve_user_config("admin", {}, {})
     validation_result = CurrentResolver.validate_operation_config(
-        admin_config, {"model": "gpt-4"}
+        admin_config, {"model": "gpt-4"}, {}
     )
     print(f"Admin validation for gpt-4: {validation_result}")
 
     # Check a regular user
-    user_config = await CurrentResolver.resolve_user_config("user")
+    user_config = await CurrentResolver.resolve_user_config("user", {}, {})
     validation_result = CurrentResolver.validate_operation_config(
-        user_config, {"model": "gpt-4"}
+        user_config, {"model": "gpt-4"}, {}
     )
     print(f"User validation for gpt-4: {validation_result}")
 
@@ -171,4 +169,6 @@ asyncio.run(check_permissions())
 print(f"\nRegistry Status: {MiddlewareRegistry.get_registry_status()}")
 MiddlewareRegistry.reset_bindings()
 print(f"Registry Status after reset: {MiddlewareRegistry.get_registry_status()}")
-```
+```
+
+# content_hash: 9f505d5203463aeca42959c92c78fe35212f34e4ea0288b67c1c6a6450117d6c

solace_agent_mesh/common/sac/sac_llm.txt

@@ -0,0 +1,71 @@
+# DEVELOPER GUIDE: sac
+
+## Quick Summary
+The `sac` directory provides the base component framework for Solace Agent Mesh (SAM) implementations in the Solace AI Connector. It offers a standardized foundation for building high-level SAM components like Agents and Gateways with built-in async operations management and message publishing capabilities.
+
+## Files Overview
+- `__init__.py` - Empty package initialization file
+- `sam_component_base.py` - Abstract base class providing async thread management and A2A message publishing for SAM components
+
+## Developer API Reference
+
+### sam_component_base.py
+**Purpose:** Provides an abstract base class for SAM components with managed asyncio event loops and message publishing
+**Import:** `from solace_agent_mesh.common.sac.sam_component_base import SamComponentBase`
+
+**Classes:**
+- `SamComponentBase(info: Dict[str, Any], **kwargs: Any)` - Abstract base class for high-level SAM components (Agents, Gateways)
+  - `publish_a2a_message(payload: Dict, topic: str, user_properties: Optional[Dict] = None) -> None` - Publishes A2A messages with size validation
+  - `run() -> None` - Starts the component's dedicated async thread
+  - `cleanup() -> None` - Cleans up resources including async thread and loop
+  - `get_async_loop() -> Optional[asyncio.AbstractEventLoop]` - Returns the dedicated asyncio event loop
+  - `_async_setup_and_run() -> None` - Abstract method for subclasses to implement main async logic
+  - `_pre_async_cleanup() -> None` - Abstract method for cleanup before async loop stops
+  - `namespace: str` - The configured namespace for the component
+  - `max_message_size_bytes: int` - Maximum allowed message size in bytes
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.common.sac.sam_component_base import SamComponentBase
+from typing import Dict, Any
+import asyncio
+
+class MyAgent(SamComponentBase):
+    def __init__(self, info: Dict[str, Any], **kwargs: Any):
+        super().__init__(info, **kwargs)
+        # Additional initialization
+    
+    async def _async_setup_and_run(self) -> None:
+        """Implement your main async logic here"""
+        while not self.stop_signal.is_set():
+            # Your async operations
+            await asyncio.sleep(1)
+    
+    def _pre_async_cleanup(self) -> None:
+        """Cleanup before async loop stops"""
+        # Your cleanup logic
+        pass
+
+# Usage
+config = {
+    "namespace": "my_namespace",
+    "max_message_size_bytes": 1048576  # 1MB
+}
+agent = MyAgent(config)
+
+# Publish a message
+payload = {"message": "Hello World"}
+agent.publish_a2a_message(
+    payload=payload,
+    topic="sam/agents/my_agent/response",
+    user_properties={"correlation_id": "123"}
+)
+
+# Start the component
+agent.run()
+
+# Later, cleanup
+agent.cleanup()
+```
+
+# content_hash: 44ffaa77554dd658386afa3a420ade21c016b72b1e5394fdba814ea897b3480c

solace_agent_mesh/common/sac/sam_component_base.py

@@ -0,0 +1,252 @@
+"""
+Base Component class for SAM implementations in the Solace AI Connector.
+"""
+
+import asyncio
+import threading
+import abc
+from typing import Any, Dict, Optional
+
+from solace_ai_connector.components.component_base import ComponentBase
+from solace_ai_connector.common.log import log
+
+from ..utils.message_utils import validate_message_size
+from ..exceptions import MessageSizeExceededError
+
+
+class SamComponentBase(ComponentBase, abc.ABC):
+    """
+    Abstract base class for high-level SAM components (Agents, Gateways).
+
+    Provides a standardized framework for:
+    - Managing a dedicated asyncio event loop running in a separate thread.
+    - Publishing A2A messages with built-in size validation.
+    """
+
+    def __init__(self, info: Dict[str, Any], **kwargs: Any):
+        super().__init__(info, **kwargs)
+        log.info("%s Initializing SamComponentBase...", self.log_identifier)
+
+        try:
+            self.namespace: str = self.get_config("namespace")
+            if not self.namespace:
+                raise ValueError("Namespace must be configured in the app_config.")
+
+            # For agents, this is 'max_message_size_bytes'.
+            # For gateways, this is 'gateway_max_message_size_bytes'.
+            self.max_message_size_bytes: int = self.get_config(
+                "max_message_size_bytes"
+            ) or self.get_config("gateway_max_message_size_bytes")
+
+            if not self.max_message_size_bytes:
+                raise ValueError(
+                    "max_message_size_bytes (or gateway_max_message_size_bytes) must be configured."
+                )
+
+        except Exception as e:
+            log.error(
+                "%s Failed to retrieve essential configuration: %s",
+                self.log_identifier,
+                e,
+            )
+            raise ValueError(f"Configuration retrieval error: {e}") from e
+
+        self._async_loop: Optional[asyncio.AbstractEventLoop] = None
+        self._async_thread: Optional[threading.Thread] = None
+        log.info("%s SamComponentBase initialized successfully.", self.log_identifier)
+
+    def publish_a2a_message(
+        self, payload: Dict, topic: str, user_properties: Optional[Dict] = None
+    ):
+        """Helper to publish A2A messages via the SAC App with size validation."""
+        try:
+            # Validate message size
+            is_valid, actual_size = validate_message_size(
+                payload, self.max_message_size_bytes, self.log_identifier
+            )
+
+            if not is_valid:
+                error_msg = (
+                    f"Message size validation failed: payload size ({actual_size} bytes) "
+                    f"exceeds maximum allowed size ({self.max_message_size_bytes} bytes)"
+                )
+                log.error("%s %s", self.log_identifier, error_msg)
+                raise MessageSizeExceededError(
+                    actual_size, self.max_message_size_bytes, error_msg
+                )
+
+            # Debug logging to show message size when publishing
+            log.debug(
+                "%s Publishing message to topic %s (size: %d bytes)",
+                self.log_identifier,
+                topic,
+                actual_size,
+            )
+
+            app = self.get_app()
+            if app:
+                # Conditionally log to invocation monitor if it exists (i.e., on an agent)
+                if hasattr(self, "invocation_monitor") and self.invocation_monitor:
+                    self.invocation_monitor.log_message_event(
+                        direction="PUBLISHED",
+                        topic=topic,
+                        payload=payload,
+                        component_identifier=self.log_identifier,
+                    )
+                app.send_message(
+                    payload=payload, topic=topic, user_properties=user_properties
+                )
+            else:
+                log.error(
+                    "%s Cannot publish message: Not running within a SAC App context.",
+                    self.log_identifier,
+                )
+        except MessageSizeExceededError:
+            # Re-raise MessageSizeExceededError without wrapping
+            raise
+        except Exception as e:
+            log.exception(
+                "%s Failed to publish A2A message to topic %s: %s",
+                self.log_identifier,
+                topic,
+                e,
+            )
+            raise
+
+    def _run_async_operations(self):
+        """Target for the dedicated async thread. Sets up and runs the event loop."""
+        log.info(
+            "%s Initializing asyncio event loop in dedicated thread...",
+            self.log_identifier,
+        )
+        self._async_loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(self._async_loop)
+
+        main_task = None
+        try:
+            log.info(
+                "%s Starting _async_setup_and_run as an asyncio task.",
+                self.log_identifier,
+            )
+            main_task = self._async_loop.create_task(self._async_setup_and_run())
+
+            log.info(
+                "%s Running asyncio event loop forever (or until stop_signal).",
+                self.log_identifier,
+            )
+            self._async_loop.run_forever()
+
+        except Exception as e:
+            log.exception(
+                "%s Unhandled exception in _run_async_operations: %s",
+                self.log_identifier,
+                e,
+            )
+            self.stop_signal.set()
+        finally:
+            if main_task and not main_task.done():
+                log.info(
+                    "%s Cancelling main async task (_async_setup_and_run).",
+                    self.log_identifier,
+                )
+                main_task.cancel()
+                try:
+                    # Use gather to await the cancellation
+                    self._async_loop.run_until_complete(
+                        asyncio.gather(main_task, return_exceptions=True)
+                    )
+                except RuntimeError as loop_err:
+                    log.warning(
+                        "%s Error awaiting main task during cleanup (loop closed?): %s",
+                        self.log_identifier,
+                        loop_err,
+                    )
+
+            if self._async_loop.is_running():
+                log.info(
+                    "%s Stopping asyncio event loop from _run_async_operations finally block.",
+                    self.log_identifier,
+                )
+                self._async_loop.stop()
+            log.info(
+                "%s Async operations loop finished in dedicated thread.",
+                self.log_identifier,
+            )
+
+    def run(self):
+        """Starts the component's dedicated async thread."""
+        log.info("%s Starting SamComponentBase run method.", self.log_identifier)
+        if not self._async_thread or not self._async_thread.is_alive():
+            self._async_thread = threading.Thread(
+                target=self._run_async_operations,
+                name=f"{self.name}_AsyncOpsThread",
+                daemon=True,
+            )
+            self._async_thread.start()
+            log.info("%s Async operations thread started.", self.log_identifier)
+        else:
+            log.warning(
+                "%s Async operations thread already running.", self.log_identifier
+            )
+
+        super().run()
+        log.info("%s SamComponentBase run method finished.", self.log_identifier)
+
+    def cleanup(self):
+        """Cleans up the component's resources, including the async thread and loop."""
+        log.info("%s Starting cleanup for SamComponentBase...", self.log_identifier)
+
+        try:
+            self._pre_async_cleanup()
+        except Exception as e:
+            log.exception(
+                "%s Error during _pre_async_cleanup(): %s", self.log_identifier, e
+            )
+
+        if self._async_loop and self._async_loop.is_running():
+            log.info("%s Requesting asyncio loop to stop...", self.log_identifier)
+            self._async_loop.call_soon_threadsafe(self._async_loop.stop)
+
+        if self._async_thread and self._async_thread.is_alive():
+            log.info(
+                "%s Joining async operations thread (timeout 10s)...",
+                self.log_identifier,
+            )
+            self._async_thread.join(timeout=10)
+            if self._async_thread.is_alive():
+                log.warning(
+                    "%s Async operations thread did not join cleanly.",
+                    self.log_identifier,
+                )
+
+        if self._async_loop and not self._async_loop.is_closed():
+            log.info(
+                "%s Closing asyncio event loop (if not already closed by its thread).",
+                self.log_identifier,
+            )
+            # The loop should have been stopped by its own thread's finally block.
+            # We just need to close it from this thread.
+            self._async_loop.call_soon_threadsafe(self._async_loop.close)
+
+        super().cleanup()
+        log.info("%s SamComponentBase cleanup finished.", self.log_identifier)
+
+    def get_async_loop(self) -> Optional[asyncio.AbstractEventLoop]:
+        """Returns the dedicated asyncio event loop for this component's async tasks."""
+        return self._async_loop
+
+    @abc.abstractmethod
+    async def _async_setup_and_run(self) -> None:
+        """
+        Abstract method for subclasses to implement their main asynchronous logic.
+        This coroutine is executed within the managed event loop.
+        """
+        pass
+
+    @abc.abstractmethod
+    def _pre_async_cleanup(self) -> None:
+        """
+        Abstract method for subclasses to perform cleanup actions
+        before the async loop is stopped.
+        """
+        pass