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

solace_agent_mesh/common/utils/pydantic_utils.py

@@ -0,0 +1,159 @@
+"""Provides a Pydantic BaseModel for SAM configuration with dict-like access."""
+from pydantic import BaseModel, ValidationError
+from typing import Any, TypeVar, Union, get_args, get_origin
+from types import UnionType
+
+T = TypeVar("T", bound="SamConfigBase")
+
+
+class SamConfigBase(BaseModel):
+    """
+    A Pydantic BaseModel for SAM configuration that allows dictionary-style access
+    for backward compatibility with components expecting dicts.
+    Supports .get(), ['key'], and 'in' operator.
+    """
+
+    @classmethod
+    def model_validate_and_clean(cls: type[T], obj: Any) -> T:
+        """
+        Validates a dictionary, first removing any keys with None values.
+        This allows Pydantic's default values to be applied correctly when
+        a config key is present but has no value in YAML.
+        """
+        if isinstance(obj, dict):
+            cleaned_obj = {k: v for k, v in obj.items() if v is not None}
+            return cls.model_validate(cleaned_obj)
+        return cls.model_validate(obj)
+
+    @classmethod
+    def format_validation_error_message(cls: type[T], error: ValidationError, app_name: str | None, agent_name: str | None = None) -> str:
+        """
+        Formats Pydantic validation error messages into a clear, actionable format.
+
+        Example output:
+        ---- Configuration validation failed for 'my-agent-app' ----
+
+           Agent Name: AgentConfig
+
+        ERROR 1:
+           Missing required field: 'namespace'
+           Location: app_config.namespace
+           Description: Absolute topic prefix for A2A communication (e.g., 'myorg/dev')
+
+        ---- Please update your YAML configuration ----
+        """
+
+        error_lines = [
+            f"\n---- Configuration validation failed for {app_name or 'UNKNOWN'} ----",
+            ""
+        ]
+
+        if agent_name:
+            error_lines.append(f"   Agent Name: {agent_name}\n")
+
+        def get_nested_field_description(model_class: type[BaseModel], path: list[str | int]) -> str | None:
+            """Recursively get field description from nested models"""
+            if not path:
+                return None
+
+            current_field = path[0]
+            if str(current_field) not in model_class.model_fields:
+                return None
+
+            field_info = model_class.model_fields[str(current_field)]
+
+            if len(path) == 1:
+                return field_info.description
+
+            annotation = field_info.annotation
+
+            # Handle Optional/Union types
+            if annotation is not None:
+                origin = get_origin(annotation)
+                if origin is Union or origin is UnionType:
+                    types = get_args(annotation)
+                    annotation = next((t for t in types if t is not type(None)), None)
+                elif origin is list:
+                    inner_type = get_args(annotation)[0]
+                    if len(path) > 1 and isinstance(path[1], int):
+                        if isinstance(inner_type, type) and issubclass(inner_type, BaseModel):
+                            return get_nested_field_description(inner_type, path[2:])
+                        return None
+                    annotation = inner_type
+
+            if annotation is not None and isinstance(annotation, type) and issubclass(annotation, BaseModel):
+                return get_nested_field_description(annotation, path[1:])
+
+            return None
+
+
+        for index, err in enumerate(error.errors()):
+            error_type = err.get('type')
+            loc = err['loc']
+            msg = err['msg']
+
+            error_lines.append(f"ERROR {index + 1}:")
+
+            absolute_path = '.'.join(str(item) for item in loc)
+            description = get_nested_field_description(cls, list(loc))
+            if error_type == 'missing':
+                error_lines.extend([
+                    f"   Missing required field: '{loc[-1]}'",
+                ])
+            else:
+                error_lines.extend([
+                    f"   Error: {msg}",
+                ])
+            error_lines.append(f"   Location: app_config.{absolute_path}")
+            error_lines.append(f"   Description: {description or 'UNKNOWN'}")
+            error_lines.append("")
+
+        error_lines.append('---- Please update your YAML configuration ----')
+        return '\n'.join(error_lines) + "\n"
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Provides dict-like .get() method."""
+        return getattr(self, key, default)
+
+    def __getitem__(self, key: str) -> Any:
+        """Provides dict-like ['key'] access."""
+        return getattr(self, key)
+
+    def __setitem__(self, key: str, value: Any):
+        """Provides dict-like ['key'] = value assignment."""
+        setattr(self, key, value)
+
+    def __contains__(self, key: str) -> bool:
+        """
+        Provides dict-like 'in' support that mimics the old behavior.
+        Returns True only if the key was explicitly provided during model creation.
+        """
+        return key in self.model_fields_set
+
+    def keys(self):
+        """Provides dict-like .keys() method."""
+        return self.model_dump().keys()
+
+    def values(self):
+        """Provides dict-like .values() method."""
+        return self.model_dump().values()
+
+    def items(self):
+        """Provides dict-like .items() method."""
+        return self.model_dump().items()
+
+    def __iter__(self):
+        """Provides dict-like iteration over keys."""
+        return iter(self.model_dump())
+    
+    def pop(self, key: str, default: Any = None) -> Any:
+        """
+        Provides dict-like .pop() method.
+        Removes the attribute and returns its value, or default if not present.
+        """
+        if hasattr(self, key):
+            value = getattr(self, key)
+            # Set to None rather than deleting, as Pydantic models don't support delattr
+            setattr(self, key, None)
+            return value
+        return default

solace_agent_mesh/common/utils/rbac_utils.py

@@ -0,0 +1,69 @@
+"""
+RBAC utility functions for agent access control.
+
+Provides common validation logic for enforcing agent access permissions
+across gateways and agent components.
+"""
+
+import logging
+from typing import Dict, Any
+
+from ..middleware.registry import MiddlewareRegistry
+
+log = logging.getLogger(__name__)
+
+
+def validate_agent_access(
+    user_config: Dict[str, Any],
+    target_agent_name: str,
+    validation_context: Dict[str, Any],
+    log_identifier: str = "[RBAC]",
+) -> None:
+    """
+    Validates that a user has permission to access a target agent.
+
+    Uses the middleware ConfigResolver to check if the user has the required
+    agent:{target_agent}:delegate scope. Raises PermissionError if access is denied.
+
+    Args:
+        user_config: User configuration dict containing scopes (from ConfigResolver.resolve_user_config)
+        target_agent_name: Name of the agent being accessed
+        validation_context: Additional context for validation (e.g., gateway_id, delegating_agent)
+        log_identifier: Logging prefix for error messages
+
+    Raises:
+        PermissionError: If the user does not have the required agent:*:delegate scope
+    """
+    config_resolver = MiddlewareRegistry.get_config_resolver()
+    operation_spec = {
+        "operation_type": "agent_access",
+        "target_agent": target_agent_name,
+    }
+
+    validation_result = config_resolver.validate_operation_config(
+        user_config, operation_spec, validation_context
+    )
+
+    if not validation_result.get("valid", False):
+        reason = validation_result.get(
+            "reason", f"Access denied to agent '{target_agent_name}'"
+        )
+        required_scopes = validation_result.get("required_scopes", [])
+
+        log.warning(
+            "%s Access to agent '%s' denied. Required scopes: %s. Reason: %s",
+            log_identifier,
+            target_agent_name,
+            required_scopes,
+            reason,
+        )
+
+        raise PermissionError(
+            f"Access denied to agent '{target_agent_name}'. Required scopes: {required_scopes}"
+        )
+
+    log.debug(
+        "%s Access to agent '%s' granted.",
+        log_identifier,
+        target_agent_name,
+    )

solace_agent_mesh/common/utils/templates/__init__.py

@@ -0,0 +1,8 @@
+"""
+Templating utilities for inline template rendering.
+"""
+
+from .liquid_renderer import render_liquid_template
+from .template_resolver import resolve_template_blocks_in_string
+
+__all__ = ["render_liquid_template", "resolve_template_blocks_in_string"]

solace_agent_mesh/common/utils/templates/liquid_renderer.py

@@ -0,0 +1,210 @@
+"""
+Liquid template rendering with data context preparation.
+"""
+
+import logging
+import csv
+import io
+import json
+from typing import Any, Dict, Optional, Tuple
+from liquid import Environment
+from jsonpath_ng.ext import parse as jsonpath_parse
+import yaml
+
+log = logging.getLogger(__name__)
+
+
+def _parse_csv_to_context(csv_content: str) -> Dict[str, Any]:
+    """
+    Parses CSV content into a template context with headers and data_rows.
+
+    Returns:
+        Dict with keys: headers (list of strings), data_rows (list of lists)
+    """
+    try:
+        reader = csv.reader(io.StringIO(csv_content))
+        rows = list(reader)
+
+        if not rows:
+            return {"headers": [], "data_rows": []}
+
+        headers = rows[0]
+        data_rows = rows[1:]
+
+        return {"headers": headers, "data_rows": data_rows}
+    except Exception as e:
+        log.error("CSV parsing failed: %s", e)
+        # Fallback to text
+        return {"text": csv_content}
+
+
+def _apply_jsonpath_filter(
+    data: Any, jsonpath_expr: str, log_id: str
+) -> Tuple[Any, Optional[str]]:
+    """
+    Applies JSONPath filter to data.
+
+    Returns:
+        Tuple of (filtered_data, error_message)
+    """
+    if not isinstance(data, (dict, list)):
+        return data, f"JSONPath requires dict or list input, got {type(data).__name__}"
+
+    try:
+        expr = jsonpath_parse(jsonpath_expr)
+        matches = [match.value for match in expr.find(data)]
+
+        # Special case: if path selects a single array (like $.products), return the array directly
+        # But if path uses filters (like $.products[?@.x==y]), return matches as array
+        # Heuristic: if we have exactly 1 match and it's a list, return it directly
+        # Otherwise, return matches list
+        if len(matches) == 1 and isinstance(matches[0], list):
+            return matches[0], None
+        else:
+            return matches, None
+    except Exception as e:
+        return data, f"JSONPath error: {e}"
+
+
+def _prepare_template_context(
+    data: Any,
+    data_mime_type: str,
+    jsonpath: Optional[str],
+    limit: Optional[int],
+    log_id: str,
+) -> Tuple[Dict[str, Any], Optional[str]]:
+    """
+    Prepares the template rendering context.
+    This involves:
+    1. Parsing raw data (e.g., JSON string) into Python objects.
+    2. Applying JSONPath filter if provided.
+    3. Structuring the data into the final context format (e.g., {"items": ...}).
+    4. Applying a limit to the number of items/rows.
+
+    Returns:
+        A tuple of (context_dict, error_message).
+    """
+    # Step 1: Parse raw data into structured data if necessary
+    parsed_data = data
+    is_csv = data_mime_type in ["text/csv", "application/csv"]
+    is_json = "json" in data_mime_type
+    is_yaml = "yaml" in data_mime_type or "yml" in data_mime_type
+
+    if isinstance(data, str):
+        if is_csv:
+            parsed_data = _parse_csv_to_context(data)
+        elif is_json:
+            try:
+                parsed_data = json.loads(data)
+            except json.JSONDecodeError as e:
+                return {}, f"Failed to parse JSON data: {e}"
+        elif is_yaml:
+            try:
+                parsed_data = yaml.safe_load(data)
+            except yaml.YAMLError as e:
+                return {}, f"Failed to parse YAML data: {e}"
+
+    # Step 2: Apply JSONPath if provided
+    if jsonpath:
+        log.info("%s Applying JSONPath: %s", log_id, jsonpath)
+        parsed_data, jsonpath_error = _apply_jsonpath_filter(
+            parsed_data, jsonpath, log_id
+        )
+        if jsonpath_error:
+            return {}, f"JSONPath filter failed: {jsonpath_error}"
+
+    # Step 3: Structure the data into the final context format
+    context: Dict[str, Any]
+    if (
+        isinstance(parsed_data, dict)
+        and "headers" in parsed_data
+        and "data_rows" in parsed_data
+    ):
+        # Already in CSV context format
+        context = parsed_data
+    elif isinstance(parsed_data, list):
+        # Array: available under 'items'
+        context = {"items": parsed_data}
+    elif isinstance(parsed_data, dict):
+        # Dictionary: keys directly available
+        context = parsed_data
+    elif isinstance(parsed_data, (str, int, float, bool)) or parsed_data is None:
+        # Primitives: available under 'value'
+        context = {"value": parsed_data}
+    else:
+        # Fallback: convert to string
+        context = {"text": str(parsed_data)}
+
+    # Step 4: Apply limit if provided
+    if limit is not None and limit > 0:
+        log.info("%s Applying limit: %d", log_id, limit)
+        if "data_rows" in context and isinstance(context["data_rows"], list):
+            context["data_rows"] = context["data_rows"][:limit]
+        elif "items" in context and isinstance(context["items"], list):
+            context["items"] = context["items"][:limit]
+
+    return context, None
+
+
+def render_liquid_template(
+    template_content: str,
+    data_artifact_content: Any,
+    data_mime_type: str,
+    jsonpath: Optional[str] = None,
+    limit: Optional[int] = None,
+    log_identifier: str = "[LiquidRenderer]",
+) -> Tuple[str, Optional[str]]:
+    """
+    Renders a Liquid template with data from an artifact.
+
+    Args:
+        template_content: The Liquid template string
+        data_artifact_content: The parsed data (string, dict, list, etc.)
+        data_mime_type: MIME type of the data artifact
+        jsonpath: Optional JSONPath expression to filter data
+        limit: Optional limit on number of items/rows
+        log_identifier: Identifier for logging
+
+    Returns:
+        Tuple of (rendered_output, error_message)
+        If successful, error_message is None
+        If failed, rendered_output contains error description
+    """
+    try:
+        # Prepare the template context, including parsing, filtering, and limiting
+        context, error = _prepare_template_context(
+            data=data_artifact_content,
+            data_mime_type=data_mime_type,
+            jsonpath=jsonpath,
+            limit=limit,
+            log_id=log_identifier,
+        )
+        if error:
+            log.error(
+                "%s Failed to prepare template context: %s", log_identifier, error
+            )
+            return f"[Template Error: {error}]", error
+
+        log.debug(
+            "%s Template context keys: %s",
+            log_identifier,
+            list(context.keys()) if isinstance(context, dict) else "non-dict",
+        )
+
+        # Render template
+        log.info("%s Rendering Liquid template", log_identifier)
+        env = Environment()
+        template = env.from_string(template_content)
+        rendered_output = template.render(**context)
+
+        log.info(
+            "%s Template rendered successfully. Output length: %d",
+            log_identifier,
+            len(rendered_output),
+        )
+        return rendered_output, None
+
+    except Exception as e:
+        error = f"Template rendering failed: {e}"
+        log.exception("%s %s", log_identifier, error)
+        return f"[Template Error: {error}]", error

solace_agent_mesh/common/utils/templates/template_resolver.py

@@ -0,0 +1,161 @@
+"""
+Resolves template blocks within artifact content.
+"""
+
+import logging
+import re
+from typing import Any, Dict, Optional
+
+from .liquid_renderer import render_liquid_template
+
+log = logging.getLogger(__name__)
+
+# Regex to match template blocks: «««template: params\ncontent\n»»» or «««template_liquid: params\ncontent\n»»»
+# Supports both 'template:' (legacy) and 'template_liquid:' (new)
+TEMPLATE_BLOCK_REGEX = re.compile(
+    r'«««template(?:_liquid)?:\s*([^\n]+)\n(.*?)»»»',
+    re.DOTALL
+)
+
+# Regex to parse parameters from template block header
+TEMPLATE_PARAMS_REGEX = re.compile(r'(\w+)\s*=\s*"([^"]*)"')
+
+
+async def resolve_template_blocks_in_string(
+    text: str,
+    artifact_service: Any,
+    session_context: Dict[str, str],
+    log_identifier: str = "[TemplateResolver]",
+) -> str:
+    """
+    Finds and resolves all template blocks in the given text.
+
+    Template blocks have the format:
+    «««template: data="filename.ext" jsonpath="$.path" limit="10"
+    ...template content...
+    »»»
+
+    Args:
+        text: The text containing potential template blocks
+        artifact_service: Service to load data artifacts
+        session_context: Dict with app_name, user_id, session_id
+        log_identifier: Identifier for logging
+
+    Returns:
+        Text with all template blocks resolved to their rendered output
+    """
+    # Import here to avoid circular dependency
+    from ....agent.utils.artifact_helpers import load_artifact_content_or_metadata
+
+    # Find all template blocks
+    matches = list(TEMPLATE_BLOCK_REGEX.finditer(text))
+
+    if not matches:
+        return text
+
+    log.info(
+        "%s Found %d template block(s) to resolve",
+        log_identifier,
+        len(matches),
+    )
+
+    # Process each match and collect replacements
+    replacements = []
+    for match in matches:
+        params_str = match.group(1)
+        template_content = match.group(2)
+
+        # Parse parameters
+        params = dict(TEMPLATE_PARAMS_REGEX.findall(params_str))
+
+        log.info(
+            "%s Resolving template block with params: %s",
+            log_identifier,
+            params,
+        )
+
+        data_artifact_spec = params.get("data")
+        if not data_artifact_spec:
+            error_msg = "[Template Error: Missing 'data' parameter]"
+            log.error("%s %s", log_identifier, error_msg)
+            replacements.append((match.start(), match.end(), error_msg))
+            continue
+
+        # Parse data artifact spec (filename or filename:version)
+        artifact_parts = data_artifact_spec.split(":", 1)
+        filename = artifact_parts[0]
+        version = int(artifact_parts[1]) if len(artifact_parts) > 1 else "latest"
+
+        try:
+            # Load the data artifact with a large max_content_length (2MB)
+            # to ensure full JSON/YAML content is loaded for template rendering
+            artifact_data = await load_artifact_content_or_metadata(
+                artifact_service,
+                **session_context,
+                filename=filename,
+                version=version,
+                load_metadata_only=False,
+                max_content_length=2_000_000,  # 2MB limit for template data
+            )
+
+            if artifact_data.get("status") != "success":
+                error_msg = f"[Template Error: Failed to load data artifact '{filename}']"
+                log.error("%s %s", log_identifier, error_msg)
+                replacements.append((match.start(), match.end(), error_msg))
+                continue
+
+            # Get artifact content and MIME type
+            artifact_content = artifact_data.get("content")
+            artifact_mime = artifact_data.get("mime_type", "text/plain")
+
+            # Parse optional parameters
+            jsonpath = params.get("jsonpath")
+            limit_str = params.get("limit")
+            limit = int(limit_str) if limit_str else None
+
+            # Render the template
+            rendered_output, render_error = render_liquid_template(
+                template_content=template_content,
+                data_artifact_content=artifact_content,
+                data_mime_type=artifact_mime,
+                jsonpath=jsonpath,
+                limit=limit,
+                log_identifier=log_identifier,
+            )
+
+            if render_error:
+                log.error(
+                    "%s Template rendering failed: %s",
+                    log_identifier,
+                    render_error,
+                )
+                replacements.append((match.start(), match.end(), rendered_output))
+            else:
+                log.info(
+                    "%s Template rendered successfully. Output length: %d",
+                    log_identifier,
+                    len(rendered_output),
+                )
+                replacements.append((match.start(), match.end(), rendered_output))
+
+        except Exception as e:
+            error_msg = f"[Template Error: {str(e)}]"
+            log.exception(
+                "%s Exception during template resolution: %s",
+                log_identifier,
+                e,
+            )
+            replacements.append((match.start(), match.end(), error_msg))
+
+    # Apply all replacements from end to start to maintain positions
+    result = text
+    for start, end, replacement in reversed(replacements):
+        result = result[:start] + replacement + result[end:]
+
+    log.info(
+        "%s Resolved %d template block(s)",
+        log_identifier,
+        len(replacements),
+    )
+
+    return result

solace_agent_mesh/common/utils/type_utils.py

@@ -0,0 +1,28 @@
+"""
+Utilities for robust type checking, especially in development environments.
+"""
+import inspect
+
+
+def is_subclass_by_name(cls_to_check: type, base_class_name: str) -> bool:
+    """
+    Checks if a class is a subclass of another class by looking for the
+    base class's name in the Method Resolution Order (MRO).
+
+    This is a robust workaround for development environments where the same
+    class might be loaded from two different paths (e.g., from 'src' and
+    from an editable install in 'site-packages'), causing standard
+    `issubclass()` checks to fail.
+
+    Args:
+        cls_to_check: The class to inspect.
+        base_class_name: The string name of the base class to look for.
+
+    Returns:
+        True if the base class name is found in the ancestry, False otherwise.
+    """
+    if not inspect.isclass(cls_to_check):
+        return False
+
+    # Check the name of each class in the inheritance chain
+    return any(base.__name__ == base_class_name for base in cls_to_check.__mro__)