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

solace_agent_mesh/common/rag_dto.py

@@ -0,0 +1,156 @@
+"""
+Pydantic models for RAG (Retrieval-Augmented Generation) metadata.
+Handles automatic conversion between snake_case (backend) and camelCase (frontend).
+
+This module is placed in common/ to be shared across different components
+(agent tools, gateway, etc.) without creating cross-layer dependencies.
+"""
+
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel, Field
+
+
+class RAGSourceResponse(BaseModel):
+    """Schema for RAG source with automatic snake_case to camelCase conversion"""
+    citation_id: str = Field(..., alias="citationId", description="Unique citation ID")
+    file_id: Optional[str] = Field(None, alias="fileId", description="File identifier")
+    filename: Optional[str] = Field(None, description="Filename or title")
+    title: Optional[str] = Field(None, description="Source title")
+    source_type: Optional[str] = Field(None, alias="sourceType", description="Type of source (web, kb, etc.)")
+    source_url: Optional[str] = Field(None, alias="sourceUrl", description="Source URL")
+    url: Optional[str] = Field(None, description="Alternative URL field")
+    content_preview: str = Field(..., alias="contentPreview", description="Preview of content")
+    relevance_score: float = Field(..., alias="relevanceScore", description="Relevance score (0-1)")
+    retrieved_at: Optional[str] = Field(None, alias="retrievedAt", description="Timestamp when retrieved")
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
+    
+    class Config:
+        from_attributes = True
+        populate_by_name = True  # Accept both snake_case and camelCase
+        by_alias = True  # Serialize using aliases (camelCase)
+
+
+class RAGQueryInfo(BaseModel):
+    """Schema for query information in RAG metadata"""
+    query: str = Field(..., description="Search query")
+    timestamp: str = Field(..., description="Query timestamp")
+    source_citation_ids: List[str] = Field(..., alias="sourceCitationIds", description="Citation IDs for this query")
+    
+    class Config:
+        populate_by_name = True
+        by_alias = True
+
+
+class RAGMetadata(BaseModel):
+    """Schema for RAG metadata"""
+    queries: Optional[List[RAGQueryInfo]] = Field(None, description="Query breakdown for timeline")
+    
+    class Config:
+        populate_by_name = True
+        by_alias = True
+        extra = "allow"  # Allow additional fields
+
+
+class RAGSearchResultResponse(BaseModel):
+    """Schema for RAG search result with automatic snake_case to camelCase conversion"""
+    query: str = Field(..., description="Search query")
+    title: Optional[str] = Field(None, description="Human-readable title for the research (generated by LLM)")
+    search_type: str = Field(..., alias="searchType", description="Type of search (file_search, kb_search, deep_research, web_search)")
+    turn_number: Optional[int] = Field(None, alias="turnNumber", description="Turn number for citation tracking")
+    timestamp: str = Field(..., description="Search timestamp")
+    sources: List[RAGSourceResponse] = Field(default_factory=list, description="List of sources")
+    task_id: Optional[str] = Field(None, alias="taskId", description="Associated task ID")
+    metadata: Optional[RAGMetadata] = Field(None, description="Additional metadata")
+    
+    class Config:
+        from_attributes = True
+        populate_by_name = True
+        by_alias = True
+
+
+def create_rag_source(
+    citation_id: str,
+    content_preview: str,
+    relevance_score: float,
+    file_id: Optional[str] = None,
+    filename: Optional[str] = None,
+    title: Optional[str] = None,
+    source_type: Optional[str] = None,
+    source_url: Optional[str] = None,
+    url: Optional[str] = None,
+    retrieved_at: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None
+) -> Dict[str, Any]:
+    """
+    Helper function to create a RAG source dict that will be automatically
+    converted to camelCase when serialized through RAGSourceResponse.
+    
+    Returns a dict that can be passed to RAGSourceResponse for serialization.
+    """
+    source = RAGSourceResponse(
+        citation_id=citation_id,
+        file_id=file_id,
+        filename=filename,
+        title=title,
+        source_type=source_type,
+        source_url=source_url,
+        url=url,
+        content_preview=content_preview,
+        relevance_score=relevance_score,
+        retrieved_at=retrieved_at,
+        metadata=metadata or {}
+    )
+    return source.model_dump(by_alias=True)
+
+
+def create_rag_search_result(
+    query: str,
+    search_type: str,
+    timestamp: str,
+    sources: List[Dict[str, Any]],
+    task_id: Optional[str] = None,
+    turn_number: Optional[int] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+    title: Optional[str] = None
+) -> Dict[str, Any]:
+    """
+    Helper function to create a RAG search result dict that will be automatically
+    converted to camelCase when serialized through RAGSearchResultResponse.
+    
+    Args:
+        query: Search query
+        search_type: Type of search (file_search, kb_search, deep_research, web_search)
+        timestamp: Search timestamp
+        sources: List of source dicts (will be converted to RAGSourceResponse)
+        task_id: Optional task ID
+        turn_number: Optional turn number
+        metadata: Optional metadata dict
+        title: Optional human-readable title (generated by LLM for deep research)
+    
+    Returns a dict with camelCase keys ready for frontend consumption.
+    """
+    # Convert source dicts to RAGSourceResponse for proper serialization
+    source_responses = [RAGSourceResponse(**src) for src in sources]
+    
+    # Create metadata if provided
+    rag_metadata = None
+    if metadata:
+        # Convert queries if present
+        if "queries" in metadata:
+            query_infos = [RAGQueryInfo(**q) for q in metadata["queries"]]
+            rag_metadata = RAGMetadata(queries=query_infos, **{k: v for k, v in metadata.items() if k != "queries"})
+        else:
+            rag_metadata = RAGMetadata(**metadata)
+    
+    result = RAGSearchResultResponse(
+        query=query,
+        title=title,
+        search_type=search_type,
+        timestamp=timestamp,
+        sources=source_responses,
+        task_id=task_id,
+        turn_number=turn_number,
+        metadata=rag_metadata
+    )
+    
+    return result.model_dump(by_alias=True)

solace_agent_mesh/common/sac/sam_component_base.py

@@ -5,13 +5,15 @@ Base Component class for SAM implementations in the Solace AI Connector.
 import logging
 import abc
 import asyncio
+import concurrent.futures
 import threading
 import functools
+import time
 from typing import Any, Optional
 
 from solace_ai_connector.components.component_base import ComponentBase
 
-from ..exceptions import MessageSizeExceededError
+from ..exceptions import ComponentInitializationError, MessageSizeExceededError
 from ..utils.message_utils import validate_message_size
 
 log = logging.getLogger(__name__)
@@ -219,6 +221,50 @@ class SamComponentBase(ComponentBase, abc.ABC):
                     self.log_identifier,
                     timer_id,
                 )
+        elif event.event_type == EventType.CACHE_EXPIRY:  
+            import asyncio
+            import inspect
+
+            cache_data = event.data
+            handler = self.handle_cache_expiry_event
+
+            # Check if the handler is async
+            if inspect.iscoroutinefunction(handler):
+                # Schedule async handler on the event loop
+                if self._async_loop and self._async_loop.is_running():
+                    async def handle_async():
+                        await handler(cache_data)
+
+                    try:
+                        future = asyncio.run_coroutine_threadsafe(
+                            handle_async(),
+                            self._async_loop
+                        )
+
+                        def on_done(f):
+                            try:
+                                f.result()
+                            except Exception as e:
+                                log.error(
+                                    "%s Error in async cache expiry handler: %s",
+                                    self.log_identifier,
+                                    e,
+                                    exc_info=True
+                                )
+                        future.add_done_callback(on_done)
+                    except RuntimeError as e:
+                        log.error(
+                            "%s Failed to schedule async CACHE_EXPIRY handler (event loop may be stopping): %s",
+                            self.log_identifier,
+                            e
+                        )
+                else:
+                    log.error(
+                        "%s Cannot handle async CACHE_EXPIRY: event loop not available",
+                        self.log_identifier
+                    )
+            else:
+                handler(cache_data)
         else:
             # Pass other event types to parent class
             super().process_event(event)
@@ -357,6 +403,12 @@ class SamComponentBase(ComponentBase, abc.ABC):
                 list(payload.keys()) if isinstance(payload, dict) else "not_dict"
             )
 
+            # Create user_properties if it doesn't exist
+            if user_properties is None:
+                user_properties = {}
+            
+            user_properties["timestamp"] = int(time.time() * 1000)
+
             # Validate message size
             is_valid, actual_size = validate_message_size(
                 payload, self.max_message_size_bytes, self.log_identifier
@@ -508,6 +560,26 @@ class SamComponentBase(ComponentBase, abc.ABC):
                 "%s Async operations thread already running.", self.log_identifier
             )
 
+        # Monitor async initialization without blocking (critical for multi-agent processes)
+        if hasattr(self, '_async_init_future') and self._async_init_future is not None:
+            log.info("%s Setting up async initialization monitoring...", self.log_identifier)
+
+            def handle_init_completion(future):
+                """Non-blocking callback for initialization completion."""
+                try:
+                    future.result()  # Raises if init failed
+                    log.info("%s Async initialization completed successfully.", self.log_identifier)
+                except Exception as init_error:
+                    error_msg = f"{self.log_identifier} Async initialization failed: {init_error}"
+                    log.error(error_msg, exc_info=init_error)
+                    self.stop_signal.set()
+                    self._async_init_error = ComponentInitializationError(
+                        self.log_identifier, init_error, error_msg
+                    )
+
+            self._async_init_future.add_done_callback(handle_init_completion)
+            log.info("%s Async initialization monitoring active (non-blocking).", self.log_identifier)
+
         super().run()
         log.info("%s SamComponentBase run method finished.", self.log_identifier)
 

solace_agent_mesh/common/sam_events/event_service.py

@@ -45,9 +45,9 @@ class SamEvent:
 @dataclass
 class SessionDeletedEvent(SamEvent):
     """System event for session deletion."""
-    
+
     @classmethod
-    def create(cls, namespace: str, source_component: str, session_id: str, 
+    def create(cls, namespace: str, source_component: str, session_id: str,
                user_id: str, agent_id: str, gateway_id: str) -> "SessionDeletedEvent":
         """Create a session deleted event."""
         data = {

solace_agent_mesh/common/utils/embeds/converter.py

@@ -14,12 +14,7 @@ from ..mime_helpers import is_text_based_mime_type
 
 log = logging.getLogger(__name__)
 
-try:
-    import yaml
-
-    PYYAML_AVAILABLE = True
-except ImportError:
-    PYYAML_AVAILABLE = False
+import yaml
 
 
 def _parse_string_to_list_of_dicts(
@@ -63,8 +58,6 @@ def _parse_string_to_list_of_dicts(
             reader = csv.DictReader(string_io)
             return list(reader), None
         elif "yaml" in normalized_mime_type or "yml" in normalized_mime_type:
-            if not PYYAML_AVAILABLE:
-                return None, "YAML parsing skipped: 'PyYAML' not installed."
             parsed_yaml = yaml.safe_load(data_string)
             if isinstance(parsed_yaml, list) and all(
                 isinstance(item, dict) for item in parsed_yaml

solace_agent_mesh/common/utils/embeds/modifiers.py

@@ -10,19 +10,8 @@ from .constants import EARLY_EMBED_TYPES, LATE_EMBED_TYPES
 
 log = logging.getLogger(__name__)
 
-try:
-    from jsonpath_ng.ext import parse as jsonpath_parse
-
-    JSONPATH_NG_AVAILABLE = True
-except ImportError:
-    JSONPATH_NG_AVAILABLE = False
-
-try:
-    import pystache
-
-    PYSTACHE_AVAILABLE = True
-except ImportError:
-    PYSTACHE_AVAILABLE = False
+from jsonpath_ng.ext import parse as jsonpath_parse
+import pystache
 
 from google.adk.artifacts import BaseArtifactService
 
@@ -45,13 +34,6 @@ def _apply_jsonpath(
         Tuple: (result_data, original_mime_type, error_string)
                result_data is typically a list of matched values.
     """
-    if not JSONPATH_NG_AVAILABLE:
-        return (
-            current_data,
-            mime_type,
-            "JSONPath modifier skipped: 'jsonpath-ng' not installed.",
-        )
-
     if not isinstance(current_data, (dict, list)):
         return (
             current_data,
@@ -457,13 +439,6 @@ async def _apply_template(
     """
     from .resolver import resolve_embeds_recursively_in_string, evaluate_embed
 
-    if not PYSTACHE_AVAILABLE:
-        return (
-            current_data,
-            mime_type,
-            "Template modifier skipped: 'pystache' not installed.",
-        )
-
     if not isinstance(current_data, (dict, list, str)):
         return (
             current_data,

solace_agent_mesh/common/utils/embeds/resolver.py

@@ -26,11 +26,7 @@ from ..mime_helpers import is_text_based_mime_type
 
 log = logging.getLogger(__name__)
 
-try:
-    import yaml
-    from .converter import PYYAML_AVAILABLE
-except ImportError:
-    PYYAML_AVAILABLE = False
+import yaml
 
 
 def _log_data_state(
@@ -184,7 +180,7 @@ async def _evaluate_artifact_content_embed_with_chain(
             current_format = DataFormat.STRING
             _log_data_state(
                 log_identifier,
-                f"[Depth:{current_depth}] After Recursive Resolution",
+                f"[Depth:{current_depth}] After Recursive Resolution (including templates)",
                 current_data,
                 current_format,
                 original_mime_type,
@@ -232,25 +228,17 @@ async def _evaluate_artifact_content_embed_with_chain(
                     original_mime_type,
                 )
         elif "yaml" in normalized_mime_type or "yml" in normalized_mime_type:
-            if PYYAML_AVAILABLE:
-                try:
-                    current_data = yaml.safe_load(current_data)
-                    current_format = DataFormat.JSON_OBJECT
-                    log.info(
-                        "%s [Depth:%d] Pre-parsed string as YAML (now JSON_OBJECT).",
-                        log_identifier,
-                        current_depth,
-                    )
-                except yaml.YAMLError:
-                    log.warning(
-                        "%s [Depth:%d] Failed to pre-parse as YAML despite MIME type '%s'. Content will be treated as STRING.",
-                        log_identifier,
-                        current_depth,
-                        original_mime_type,
-                    )
-            else:
+            try:
+                current_data = yaml.safe_load(current_data)
+                current_format = DataFormat.JSON_OBJECT
+                log.info(
+                    "%s [Depth:%d] Pre-parsed string as YAML (now JSON_OBJECT).",
+                    log_identifier,
+                    current_depth,
+                )
+            except yaml.YAMLError:
                 log.warning(
-                    "%s [Depth:%d] Skipping YAML pre-parsing for MIME type '%s' because PyYAML is not installed.",
+                    "%s [Depth:%d] Failed to pre-parse as YAML despite MIME type '%s'. Content will be treated as STRING.",
                     log_identifier,
                     current_depth,
                     original_mime_type,
@@ -677,6 +665,34 @@ async def resolve_embeds_in_string(
             len(final_text),
         )
 
+    # If resolving late embeds, also resolve template blocks
+    # Templates are considered late embeds since they need artifact service access
+    if LATE_EMBED_TYPES.intersection(types_to_resolve):
+        try:
+            from ..templates import resolve_template_blocks_in_string
+
+            artifact_service = context.get("artifact_service")
+            session_context = context.get("session_context")
+
+            if artifact_service and session_context:
+                log.debug(
+                    "%s Resolving template blocks after late embed resolution.",
+                    log_identifier,
+                )
+                final_text = await resolve_template_blocks_in_string(
+                    text=final_text,
+                    artifact_service=artifact_service,
+                    session_context=session_context,
+                    log_identifier=f"{log_identifier}[TemplateResolve]",
+                )
+        except Exception as template_err:
+            log.warning(
+                "%s Failed to resolve template blocks: %s",
+                log_identifier,
+                template_err,
+            )
+            # Continue with final_text as-is
+
     return final_text, processed_until_index, signals_found
 
 
@@ -797,7 +813,39 @@ async def resolve_embeds_recursively_in_string(
         last_end = end
 
     resolved_parts.append(text[last_end:])
-    return "".join(resolved_parts)
+    result_text = "".join(resolved_parts)
+
+    # If resolving late embeds, also resolve template blocks
+    # Templates are considered late embeds since they need artifact service access
+    if LATE_EMBED_TYPES.intersection(types_to_resolve):
+        try:
+            from ..templates import resolve_template_blocks_in_string
+
+            artifact_service = context.get("artifact_service")
+            session_context = context.get("session_context")
+
+            if artifact_service and session_context:
+                log.debug(
+                    "%s [Depth:%d] Resolving template blocks after late embed resolution.",
+                    log_identifier,
+                    current_depth,
+                )
+                result_text = await resolve_template_blocks_in_string(
+                    text=result_text,
+                    artifact_service=artifact_service,
+                    session_context=session_context,
+                    log_identifier=f"{log_identifier}[TemplateResolve]",
+                )
+        except Exception as template_err:
+            log.warning(
+                "%s [Depth:%d] Failed to resolve template blocks: %s",
+                log_identifier,
+                current_depth,
+                template_err,
+            )
+            # Continue with result_text as-is
+
+    return result_text
 
 
 async def evaluate_embed(
@@ -873,6 +921,27 @@ async def evaluate_embed(
             )
             output_format = format_spec
 
+        # Check if this is a deep research report artifact
+        # Deep research reports should be rendered by the frontend component, not resolved inline
+        filename_part = artifact_spec.split(":")[0] if ":" in artifact_spec else artifact_spec
+        is_deep_research_report = filename_part.lower().endswith("_report.md")
+        
+        if is_deep_research_report and resolution_mode == ResolutionMode.A2A_MESSAGE_TO_USER:
+            # Parse version from artifact_spec
+            parts = artifact_spec.strip().split(":", 1)
+            filename = parts[0]
+            version = parts[1] if len(parts) > 1 else "latest"
+            log.info(
+                "%s Detected deep research report artifact '%s'. Signaling for frontend rendering instead of inline resolution.",
+                log_identifier,
+                filename,
+            )
+            return (
+                None,
+                "SIGNAL_DEEP_RESEARCH_REPORT",
+                {"filename": filename, "version": version},
+            )
+
         result = await _evaluate_artifact_content_embed_with_chain(
             artifact_spec_from_directive=artifact_spec,
             modifiers_from_directive=modifiers,

solace_agent_mesh/common/utils/embeds/types.py

@@ -11,6 +11,7 @@ class ResolutionMode(Enum):
     A2A_MESSAGE_TO_USER = auto()
     TOOL_PARAMETER = auto()
     RECURSIVE_ARTIFACT_CONTENT = auto()
+    ARTIFACT_STREAMING = auto()  # For streaming artifact chunks to browser
 
 
 class DataFormat(Enum):

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/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,
+    )