solace-agent-mesh 1.6.1__py3-none-any.whl → 1.13.2__py3-none-any.whl

solace_agent_mesh/common/utils/log_formatters.py

@@ -1,6 +1,7 @@
 import logging
 import json
 import os
+import warnings
 from datetime import datetime, timezone
 import traceback
 
@@ -8,9 +9,28 @@ import traceback
 class DatadogJsonFormatter(logging.Formatter):
     """
     Custom formatter to output logs in Datadog-compatible JSON format.
+    
+    . deprecated::
+        This formatter is deprecated. Please use pythonjsonlogger.json.JsonFormatter instead.
+        For details, consult https://solacelabs.github.io/solace-agent-mesh/docs/documentation/deploying/logging#structured-logging
+
+        Example:
+            formatters:
+              jsonFormatter:
+                "()": pythonjsonlogger.json.JsonFormatter
+                format: "%(timestamp)s %(levelname)s %(threadName)s %(name)s %(message)s"
     """
 
     def format(self, record):
+        # Emit deprecation warning once
+        if not hasattr(self.__class__, '_deprecation_warned'):
+            warnings.warn(
+                "DatadogJsonFormatter is deprecated and will be removed in a future version. "
+                "Please use pythonjsonlogger.json.JsonFormatter instead. For details, consult https://solacelabs.github.io/solace-agent-mesh/docs/documentation/deploying/logging#structured-logging",
+                DeprecationWarning,
+                stacklevel=2
+            )
+            self.__class__._deprecation_warned = True
         log_entry = {
             "timestamp": datetime.fromtimestamp(
                 record.created, tz=timezone.utc

solace_agent_mesh/common/utils/mime_helpers.py

@@ -23,6 +23,8 @@ _TEXT_BASED_SUBTYPE_WHOLE = {
     "json",
     "xml",
     "yaml",
+    "x-yaml",
+    "yml",
     "csv",
     "javascript",
     "ecmascript",
@@ -48,6 +50,7 @@ _TEXT_BASED_SUBTYPE_SUFFIXES_AFTER_PLUS = {
     "xhtml",
 }
 
+
 def is_text_based_mime_type(mime_type: Optional[str]) -> bool:
     """
     Checks if a given MIME type is considered text-based.
@@ -72,7 +75,9 @@ def is_text_based_mime_type(mime_type: Optional[str]) -> bool:
     return False
 
 
-def is_text_based_file(mime_type: Optional[str], content_bytes: Optional[bytes] = None) -> bool:
+def is_text_based_file(
+    mime_type: Optional[str], content_bytes: Optional[bytes] = None
+) -> bool:
     """
     Determines if a file is text-based based on its MIME type and content.
     Args:
@@ -83,10 +88,10 @@ def is_text_based_file(mime_type: Optional[str], content_bytes: Optional[bytes]
     """
     if not mime_type:
         return False
-        
+
     normalized_mime_type = mime_type.lower().strip()
     primary_type, _, subtype = normalized_mime_type.partition("/")
-    
+
     if primary_type in _TEXT_BASED_PRIMARY_TYPES:
         return True
     elif subtype in _TEXT_BASED_SUBTYPE_WHOLE:
@@ -95,14 +100,16 @@ def is_text_based_file(mime_type: Optional[str], content_bytes: Optional[bytes]
         specific_format = subtype.split("+")[-1]
         if specific_format in _TEXT_BASED_SUBTYPE_SUFFIXES_AFTER_PLUS:
             return True
-    elif normalized_mime_type == "application/octet-stream" and content_bytes is not None:
+    elif (
+        normalized_mime_type == "application/octet-stream" and content_bytes is not None
+    ):
         try:
             sample_size = min(1024, len(content_bytes))
             content_bytes[:sample_size].decode("utf-8")
             return True
         except UnicodeDecodeError:
             return False
-        
+
     return False
 
 

solace_agent_mesh/common/utils/pydantic_utils.py

@@ -1,6 +1,7 @@
 """Provides a Pydantic BaseModel for SAM configuration with dict-like access."""
-from pydantic import BaseModel
-from typing import Any, Dict, Type, TypeVar
+from pydantic import BaseModel, ValidationError
+from typing import Any, TypeVar, Union, get_args, get_origin
+from types import UnionType
 
 T = TypeVar("T", bound="SamConfigBase")
 
@@ -13,7 +14,7 @@ class SamConfigBase(BaseModel):
     """
 
     @classmethod
-    def model_validate_and_clean(cls: Type[T], obj: Any) -> T:
+    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
@@ -24,6 +25,92 @@ class SamConfigBase(BaseModel):
             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)

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
+
+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/config_portal/backend/common.py

@@ -19,6 +19,8 @@ INIT_DEFAULT = {
     "webui_fastapi_host": "127.0.0.1",
     "webui_fastapi_port": 8000,
     "webui_enable_embed_resolution": True,
+    "platform_api_host": "127.0.0.1",
+    "platform_api_port": 8001,
 }
 
 USE_DEFAULT_SHARED_SESSION = "use_default_shared_session"
@@ -71,6 +73,16 @@ GATEWAY_DEFAULTS = {
     ),
 }
 
+PROXY_DEFAULTS = {
+    "namespace": "${NAMESPACE}",
+    "artifact_service_type": "filesystem",
+    "artifact_service_base_path": "/tmp/samv2",
+    "artifact_service_scope": "namespace",
+    "artifact_handling_mode": "reference",
+    "discovery_interval_seconds": 5,
+    "proxied_agents": [],
+}
+
 
 port_55555 = "-p 55554:55555" if sys.platform == "darwin" else "-p 55555:55555"