solace-agent-mesh 1.11.2__py3-none-any.whl

solace_agent_mesh/common/constants.py

@@ -0,0 +1,6 @@
+
+DEFAULT_COMMUNICATION_TIMEOUT = 600  # 10 minutes
+HEALTH_CHECK_TTL_SECONDS = 60  # 60 seconds - time after which a health check is considered stale
+HEALTH_CHECK_INTERVAL_SECONDS = 10  # 10 seconds - interval between health checks
+TEXT_ARTIFACT_CONTEXT_MAX_LENGTH_CAPACITY = 200000  # maximum number of characters that can be loaded from a text artifact
+TEXT_ARTIFACT_CONTEXT_DEFAULT_LENGTH = 100000  # default number of characters to load from a text artifact 

solace_agent_mesh/common/data_parts.py

@@ -0,0 +1,150 @@
+"""
+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, Optional, 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.",
+    )
+    usage: Optional[Dict[str, Any]] = Field(
+        None,
+        description="Token usage information for this LLM call (input_tokens, output_tokens, cached_input_tokens, 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.")
+    status: Literal["in-progress", "completed", "failed"] = Field(
+        ..., description="The status of the artifact creation."
+    )
+    bytes_transferred: int = Field(
+        ..., description="The number of bytes transferred so far."
+    )
+    description: Optional[str] = Field(
+        None, description="An optional description of the artifact being created."
+    )
+    artifact_chunk: Optional[str] = Field(
+        None,
+        description="The chunk of artifact data that was transferred in this progress update. Only present for 'in-progress' status.",
+    )
+    mime_type: Optional[str] = Field(
+        None,
+        description="The MIME type of the artifact. Only present for 'completed' status.",
+    )
+    version: Optional[int] = Field(
+        None,
+        description="The version number of the artifact being created or updated.",
+    )
+
+
+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."
+    )
+    llm_usage: Optional[Dict[str, Any]] = Field(
+        None,
+        description="Token usage if this tool made LLM calls (input_tokens, output_tokens, cached_input_tokens, model)",
+    )
+
+
+class TemplateBlockData(BaseModel):
+    """
+    Data model for a buffered inline template block ready for resolution.
+    Corresponds to template_block.json schema.
+    """
+
+    type: Literal["template_block"] = Field(
+        "template_block", description="The constant type for this data part."
+    )
+    template_id: str = Field(
+        ..., description="UUID for tracking this specific template instance."
+    )
+    data_artifact: str = Field(
+        ..., description="Data artifact filename or filename:version."
+    )
+    jsonpath: Optional[str] = Field(
+        None, description="Optional JSONPath expression to filter data."
+    )
+    limit: Optional[int] = Field(
+        None, description="Optional limit on number of items/rows to pass to template."
+    )
+    template_content: str = Field(
+        ..., description="The full Liquid template content."
+    )
+
+
+SignalData = Union[
+    ToolInvocationStartData,
+    LlmInvocationData,
+    AgentProgressUpdateData,
+    ArtifactCreationProgressData,
+    ToolResultData,
+    TemplateBlockData,
+]

solace_agent_mesh/common/exceptions.py

@@ -0,0 +1,49 @@
+"""Custom exceptions for Solace Agent Mesh."""
+
+
+class MessageSizeExceededError(Exception):
+    """Raised when a message exceeds the maximum allowed size."""
+
+    def __init__(self, actual_size: int, max_size: int, message: str = None):
+        """Initialize the MessageSizeExceededError.
+
+        Args:
+            actual_size: The actual size of the message in bytes.
+            max_size: The maximum allowed size in bytes.
+            message: Optional custom error message. If None, a default message
+                    will be generated.
+        """
+        self.actual_size = actual_size
+        self.max_size = max_size
+
+        if message is None:
+            message = (
+                f"Message size {actual_size} bytes exceeds maximum limit of "
+                f"{max_size} bytes"
+            )
+
+        super().__init__(message)
+
+
+class ComponentInitializationError(Exception):
+    """Raised when a SAM component fails to initialize."""
+
+    def __init__(self, component_identifier: str, original_error: Exception, message: str = None):
+        """Initialize the ComponentInitializationError.
+
+        Args:
+            component_identifier: The identifier of the component that failed to initialize.
+            original_error: The original exception that caused the failure.
+            message: Optional custom error message. If None, a default message
+                    will be generated.
+        """
+        self.component_identifier = component_identifier
+        self.original_error = original_error
+
+        if message is None:
+            message = (
+                f"Component {component_identifier} failed to initialize: "
+                f"{original_error}"
+            )
+
+        super().__init__(message)

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,132 @@
+"""
+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.
+"""
+
+import logging
+from typing import Any, Dict, List
+
+log = logging.getLogger(__name__)
+
+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

solace_agent_mesh/common/middleware/middleware_llm.txt

@@ -0,0 +1,174 @@
+# 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.
+
+## Files Overview
+- `__init__.py`: Exposes the main public classes of the middleware package for easy importing.
+- `config_resolver.py`: Defines the default, permissive configuration resolution middleware.
+- `registry.py`: Provides the `MiddlewareRegistry` for dynamically binding custom middleware implementations.
+
+## Developer API Reference
+
+### __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_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_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.
+  - `resolve_user_config(user_identity: Any, gateway_context: Dict[str, Any], base_config: Dict[str, Any]) -> Dict[str, Any]` - (async) Resolves user-specific configuration. The default implementation returns the `base_config` unchanged.
+  - `is_feature_enabled(user_config: Dict[str, Any], feature_descriptor: Dict[str, Any], context: Dict[str, Any]) -> bool` - Checks if a feature is enabled for a user. The default implementation always returns `True`.
+  - `validate_operation_config(user_config: Dict[str, Any], operation_spec: Dict[str, Any], validation_context: Dict[str, Any]) -> Dict[str, Any]` - Validates if an operation is allowed for a user. The default implementation always returns a dictionary with `{'valid': True}`.
+  - `filter_available_options(user_config: Dict[str, Any], available_options: List[Dict[str, Any]], filter_context: Dict[str, Any]) -> List[Dict[str, Any]]` - Filters a list of options based on user permissions. The default implementation returns the original `available_options` list.
+
+**Usage Examples:**
+```python
+import asyncio
+from solace_agent_mesh.common.middleware import ConfigResolver
+
+async def main():
+    # Example user identity and base configuration
+    user_id = "test-user@example.com"
+    base_conf = {"api_key": "default_key", "allowed_models": ["gpt-3.5-turbo"]}
+
+    # 1. Resolve user configuration (default implementation returns base_conf)
+    user_config = await ConfigResolver.resolve_user_config(
+        user_identity=user_id,
+        gateway_context={"gateway_id": "gw-1"},
+        base_config=base_conf
+    )
+    print(f"Resolved User Config: {user_config}")
+
+    # 2. Check if a feature is enabled (default is always True)
+    feature_desc = {"feature_type": "ai_tool", "function_name": "code_interpreter"}
+    is_enabled = ConfigResolver.is_feature_enabled(
+        user_config=user_config,
+        feature_descriptor=feature_desc,
+        context={}
+    )
+    print(f"Is Feature Enabled: {is_enabled}")
+
+    # 3. Validate an operation (default is always valid)
+    op_spec = {"operation_type": "model_inference", "model": "gpt-4"}
+    validation = ConfigResolver.validate_operation_config(
+        user_config=user_config,
+        operation_spec=op_spec,
+        validation_context={}
+    )
+    print(f"Operation Validation: {validation}")
+
+    # 4. Filter available options (default returns all options)
+    all_models = [
+        {"name": "gpt-3.5-turbo", "provider": "openai"},
+        {"name": "gpt-4", "provider": "openai"},
+    ]
+    available_models = ConfigResolver.filter_available_options(
+        user_config=user_config,
+        available_options=all_models,
+        filter_context={"type": "language_model"}
+    )
+    print(f"Filtered Options: {available_models}")
+
+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_agent_mesh.common.middleware import MiddlewareRegistry`
+
+**Classes:**
+- `MiddlewareRegistry()` - A registry for managing middleware implementations. All methods are class methods.
+  - `bind_config_resolver(resolver_class: Type)` - Binds a custom class that implements the `ConfigResolver` interface. This new class will be used for all subsequent configuration resolution calls.
+  - `get_config_resolver() -> Type` - Returns the currently bound `ConfigResolver` class. If no custom resolver has been bound, it returns the default `ConfigResolver`.
+  - `register_initialization_callback(callback: callable)` - Registers a function to be executed when `initialize_middleware()` is called. Useful for setting up custom middleware components at application startup.
+  - `initialize_middleware()` - Executes all registered initialization callbacks. This should be called once during application startup.
+  - `reset_bindings()` - Resets all bindings back to their defaults. This is primarily useful for testing environments.
+  - `get_registry_status() -> Dict[str, Any]` - Returns a dictionary containing the current status of the registry, such as which resolver is bound.
+
+**Usage Examples:**
+```python
+import asyncio
+from typing import Any, Dict, List
+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, 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, 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."}
+        return {"valid": True}
+    
+    # Inherit other methods from the default for simplicity
+    is_feature_enabled = ConfigResolver.is_feature_enabled
+    filter_available_options = ConfigResolver.filter_available_options
+
+# 2. Define an initialization callback
+def setup_custom_logging():
+    print("Custom middleware initialization logic is running!")
+
+# 3. Bind the custom components
+MiddlewareRegistry.bind_config_resolver(MyCustomConfigResolver)
+MiddlewareRegistry.register_initialization_callback(setup_custom_logging)
+
+# 4. Initialize the middleware (e.g., at application startup)
+print("--- Initializing Middleware ---")
+MiddlewareRegistry.initialize_middleware()
+print("--- Initialization Complete ---")
+
+# 5. Use the middleware system
+async def check_permissions():
+    # The registry will now use MyCustomConfigResolver automatically
+    CurrentResolver = MiddlewareRegistry.get_config_resolver()
+    print(f"Current resolver is: {CurrentResolver.__name__}")
+
+    # Check an admin user
+    admin_config = await CurrentResolver.resolve_user_config("admin", {}, {})
+    validation_result = CurrentResolver.validate_operation_config(
+        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", {}, {})
+    validation_result = CurrentResolver.validate_operation_config(
+        user_config, {"model": "gpt-4"}, {}
+    )
+    print(f"User validation for gpt-4: {validation_result}")
+
+# Run the example
+asyncio.run(check_permissions())
+
+# 6. Check status and reset (useful for testing)
+print(f"\nRegistry Status: {MiddlewareRegistry.get_registry_status()}")
+MiddlewareRegistry.reset_bindings()
+print(f"Registry Status after reset: {MiddlewareRegistry.get_registry_status()}")
+```
+
+# content_hash: eb6f60d7fdc4a0fb198bf8cc5644c3d372a72ebf46870c79282f230b07637095