solace-agent-mesh 1.6.3__py3-none-any.whl → 1.7.0__py3-none-any.whl

solace_agent_mesh/common/utils/embeds/resolver.py

@@ -5,6 +5,7 @@ Contains the main embed resolution functions, including the chain executor.
 import logging
 import asyncio
 import json
+import uuid
 from typing import Any, Callable, Dict, Optional, Set, Tuple, List, Union
 from .constants import (
     EMBED_REGEX,
@@ -20,7 +21,7 @@ from .converter import (
     serialize_data,
     _parse_string_to_list_of_dicts,
 )
-from .types import DataFormat
+from .types import DataFormat, ResolutionMode
 from ..mime_helpers import is_text_based_mime_type
 
 log = logging.getLogger(__name__)
@@ -85,10 +86,11 @@ async def _evaluate_artifact_content_embed_with_chain(
     output_format_from_directive: Optional[str],
     context: Any,
     log_identifier: str,
+    resolution_mode: "ResolutionMode",
     config: Optional[Dict] = None,
     current_depth: int = 0,
     visited_artifacts: Optional[Set[Tuple[str, int]]] = None,
-) -> Tuple[str, Optional[str], int]:
+) -> Union[Tuple[str, Optional[str], int], Tuple[None, str, Any]]:
     """
     Loads artifact content, recursively resolves its internal embeds if text-based,
     applies a chain of modifiers, and serializes the final result.
@@ -167,6 +169,7 @@ async def _evaluate_artifact_content_embed_with_chain(
                 context=context,
                 resolver_func=evaluate_embed,
                 types_to_resolve=EARLY_EMBED_TYPES.union(LATE_EMBED_TYPES),
+                resolution_mode=ResolutionMode.RECURSIVE_ARTIFACT_CONTENT,
                 log_identifier=log_identifier,
                 config=config,
                 max_depth=config.get("gateway_recursive_embed_depth", 12),
@@ -422,6 +425,26 @@ async def _evaluate_artifact_content_embed_with_chain(
             err_msg = f"Unexpected error in modifier '{prefix}': {mod_err}"
             return f"[Error: {err_msg}]", err_msg, 0
 
+    if (
+        current_format == DataFormat.BYTES
+        and resolution_mode == ResolutionMode.A2A_MESSAGE_TO_USER
+    ):
+        log.info(
+            "%s [Depth:%d] Result is binary data in A2A_MESSAGE_TO_USER mode. Signaling for inline binary content.",
+            log_identifier,
+            current_depth,
+        )
+        filename_for_signal = artifact_spec_from_directive.split(":", 1)[0]
+        return (
+            None,
+            "SIGNAL_INLINE_BINARY_CONTENT",
+            {
+                "bytes": current_data,
+                "mime_type": original_mime_type,
+                "name": filename_for_signal,
+            },
+        )
+
     target_string_format = output_format_from_directive
     if target_string_format is None:
         log.warning(
@@ -486,9 +509,10 @@ async def resolve_embeds_in_string(
         ..., Union[Tuple[str, Optional[str], int], Tuple[None, str, Any]]
     ],
     types_to_resolve: Set[str],
+    resolution_mode: "ResolutionMode",
     log_identifier: str = "[EmbedUtil]",
     config: Optional[Dict[str, Any]] = None,
-) -> Tuple[str, int, List[Tuple[int, Any]]]:
+) -> Tuple[str, int, List[Tuple[int, Any, str]]]:
     """
     Resolves specified embed types within a string using a provided resolver function.
     This is the TOP-LEVEL resolver called by gateways. It handles signals and buffering.
@@ -520,7 +544,7 @@ async def resolve_embeds_in_string(
           The index corresponds to the start index of the embed directive in the original string.
     """
     resolved_parts = []
-    signals_found: List[Tuple[int, Any]] = []
+    signals_found: List[Tuple[int, Any, str]] = []
     last_end = 0
     original_length = len(text)
 
@@ -550,6 +574,7 @@ async def resolve_embeds_in_string(
                 format_spec,
                 context,
                 log_identifier,
+                resolution_mode,
                 config,
             )
 
@@ -566,10 +591,13 @@ async def resolve_embeds_in_string(
                     signal_type,
                     start,
                 )
+                placeholder = f"__EMBED_SIGNAL_{uuid.uuid4().hex}__"
+                resolved_parts.append(placeholder)
                 signals_found.append(
                     (
                         start,
                         resolved_value,
+                        placeholder,
                     )
                 )
             elif (
@@ -657,6 +685,7 @@ async def resolve_embeds_recursively_in_string(
     context: Any,
     resolver_func: Callable[..., Tuple[str, Optional[str], int]],
     types_to_resolve: Set[str],
+    resolution_mode: "ResolutionMode",
     log_identifier: str,
     config: Optional[Dict],
     max_depth: int,
@@ -709,6 +738,7 @@ async def resolve_embeds_recursively_in_string(
             format_spec,
             context,
             log_identifier,
+            resolution_mode,
             config,
             current_depth,
             visited_artifacts,
@@ -776,6 +806,7 @@ async def evaluate_embed(
     format_spec: Optional[str],
     context: Dict[str, Any],
     log_identifier: str,
+    resolution_mode: "ResolutionMode",
     config: Optional[Dict] = None,
     current_depth: int = 0,
     visited_artifacts: Optional[Set[Tuple[str, int]]] = None,
@@ -812,6 +843,26 @@ async def evaluate_embed(
         log.info("%s Detected 'status_update' embed. Signaling.", log_identifier)
         return (None, "SIGNAL_STATUS_UPDATE", status_text)
 
+    elif embed_type == "artifact_return":
+        if resolution_mode == ResolutionMode.A2A_MESSAGE_TO_USER:
+            parts = expression.strip().split(":", 1)
+            filename = parts[0]
+            version = parts[1] if len(parts) > 1 else "latest"
+            log.info("%s Detected 'artifact_return' embed. Signaling.", log_identifier)
+            return (
+                None,
+                "SIGNAL_ARTIFACT_RETURN",
+                {"filename": filename, "version": version},
+            )
+        else:
+            log.warning(
+                "%s Ignoring 'artifact_return' embed in unsupported context: %s",
+                log_identifier,
+                resolution_mode.name,
+            )
+            original_embed_text = f"«{embed_type}:{expression}»"
+            return original_embed_text, None, len(original_embed_text.encode("utf-8"))
+
     elif embed_type == "artifact_content":
         artifact_spec, modifiers, output_format = _parse_modifier_chain(expression)
         if output_format is None and format_spec is not None:
@@ -822,17 +873,18 @@ async def evaluate_embed(
             )
             output_format = format_spec
 
-        final_string, error, size = await _evaluate_artifact_content_embed_with_chain(
+        result = await _evaluate_artifact_content_embed_with_chain(
             artifact_spec_from_directive=artifact_spec,
             modifiers_from_directive=modifiers,
             output_format_from_directive=output_format,
             context=context,
             log_identifier=log_identifier,
+            resolution_mode=resolution_mode,
             config=config,
             current_depth=current_depth,
             visited_artifacts=visited_artifacts or set(),
         )
-        return final_string, error, size
+        return result
 
     else:
         evaluator = EMBED_EVALUATORS.get(embed_type)

solace_agent_mesh/common/utils/embeds/types.py

@@ -5,6 +5,14 @@ Defines types used within the embed processing system, like DataFormat.
 from enum import Enum, auto
 
 
+class ResolutionMode(Enum):
+    """Defines the context in which embed resolution is occurring."""
+
+    A2A_MESSAGE_TO_USER = auto()
+    TOOL_PARAMETER = auto()
+    RECURSIVE_ARTIFACT_CONTENT = auto()
+
+
 class DataFormat(Enum):
     """Represents internal data formats during modifier chain execution."""
 

solace_agent_mesh/common/utils/utils_llm.txt

@@ -1,3 +1,5 @@
+# DEVELOPER GUIDE: utils
+
 ## Quick Summary
 The `utils` directory provides essential utility functions and tools for the Solace Agent Mesh system. It contains both direct utility files for common operations (MIME type handling, caching, message validation, authentication) and a sophisticated `embeds` subdirectory that implements a dynamic expression evaluation system. The utilities work together to provide platform compatibility, security features, data processing capabilities, and dynamic content generation for agent workflows.
 
@@ -119,6 +121,7 @@ The `utils` directory provides essential utility functions and tools for the Sol
   - `__setitem__(key: str, value: Any)` - Dict-like ['key'] = value assignment
   - `__contains__(key: str) -> bool` - Dict-like 'in' support
   - `keys()`, `values()`, `items()`, `__iter__()` - Dict-like iteration methods
+  - `pop(key: str, default: Any = None) -> Any` - Dict-like .pop() method
 
 #### type_utils.py
 **Purpose:** Utilities for robust type checking, especially in development environments
@@ -327,10 +330,6 @@ async def webhook_handler(request: Request):
             data = await request.json()
             # Process authenticated notification
             print(f"Received verified notification: {data}")
-            return Response("OK")
-        else:
-            return Response("Unauthorized", status_code=401)
-    except Exception as e:
-        print(f"
+            return Response
 
-# content_hash: d80ffe631ca180ea5aacca592313af42838960a949c8664559a957c2492fa86f
+# content_hash: c5bd94fc53429706fd6649d3dcf489665da150cfed54fd6961472c7b57dfc910

solace_agent_mesh/core_a2a/core_a2a_llm.txt

@@ -87,4 +87,4 @@ agent_card = AgentCard(name="new_agent", description="A new agent")
 service.process_discovery_message(agent_card)
 ```
 
-# content_hash: fcc947b32fa06db11f6cdf1064dfd9a68ee152373677a574602c182fc8c62f56
+# content_hash: 64e02756b1b097e39257e8e52df701d758df0f8d022ea6d6b088057f7025a6d9

solace_agent_mesh/gateway/adapter/__init__.py

@@ -0,0 +1 @@
+"""Abstract base classes and types for the Generic Gateway Adapter Framework."""

solace_agent_mesh/gateway/adapter/base.py

@@ -0,0 +1,143 @@
+"""
+Defines the abstract base class for Generic Gateway Adapters.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Generic, Optional, Type, TypeVar
+
+from pydantic import BaseModel
+
+from .types import (
+    AuthClaims,
+    GatewayContext,
+    ResponseContext,
+    SamDataPart,
+    SamError,
+    SamFilePart,
+    SamTask,
+    SamTextPart,
+    SamUpdate,
+)
+
+T_ExternalInput = TypeVar("T_ExternalInput", bound=Any)
+T_PlatformContext = TypeVar("T_PlatformContext", bound=Dict[str, Any])
+T_AdapterConfig = TypeVar("T_AdapterConfig", bound=BaseModel)
+
+
+class GatewayAdapter(
+    ABC, Generic[T_ExternalInput, T_PlatformContext, T_AdapterConfig]
+):
+    """
+    Abstract base class for gateway adapter plugins.
+
+    Gateway adapters handle platform-specific communication while the
+    GenericGatewayComponent manages A2A protocol complexity.
+    """
+
+    ConfigModel: Optional[Type[BaseModel]] = None
+
+    # --- Lifecycle ---
+    async def init(self, context: GatewayContext) -> None:
+        """
+        Initialize the gateway adapter.
+
+        This is where you should:
+        - Start platform listeners (WebSocket, HTTP server, stdin reader, etc.)
+        - Connect to external services and store the context for later use.
+        """
+        pass
+
+    async def cleanup(self) -> None:
+        """
+        Clean up resources on shutdown.
+
+        This is where you should:
+        - Stop platform listeners, close connections, and release resources.
+        """
+        pass
+
+    # --- Authentication ---
+    async def extract_auth_claims(
+        self,
+        external_input: T_ExternalInput,
+        endpoint_context: Optional[Dict[str, Any]] = None,
+    ) -> Optional[AuthClaims]:
+        """
+        Extract authentication claims from platform input.
+
+        Return AuthClaims with user info/tokens, or None to use config-based auth.
+        """
+        return None
+
+    # --- Inbound: Platform -> A2A ---
+    @abstractmethod
+    async def prepare_task(
+        self,
+        external_input: T_ExternalInput,
+        endpoint_context: Optional[Dict[str, Any]] = None,
+    ) -> SamTask:
+        """
+        Prepare a task from platform input.
+
+        This method is called after authentication succeeds. Convert your
+        platform's event format into a SamTask with parts.
+        """
+        pass
+
+    # --- Outbound: A2A -> Platform ---
+    async def handle_update(self, update: SamUpdate, context: ResponseContext) -> None:
+        """
+        Handle an update from the agent (batch handler).
+
+        By default, this method dispatches to individual part handlers.
+        Override for custom batch processing.
+        """
+        for part in update.parts:
+            if isinstance(part, SamTextPart):
+                await self.handle_text_chunk(part.text, context)
+            elif isinstance(part, SamFilePart):
+                await self.handle_file(part, context)
+            elif isinstance(part, SamDataPart):
+                # Check for special data part types that have their own handlers
+                if part.data.get("type") == "agent_progress_update":
+                    status_text = part.data.get("status_text")
+                    if status_text:
+                        await self.handle_status_update(status_text, context)
+                else:
+                    # Fallback to the generic data part handler
+                    await self.handle_data_part(part, context)
+
+    async def handle_text_chunk(self, text: str, context: ResponseContext) -> None:
+        """
+        Handle streaming text chunk from the agent.
+
+        This is called by the default `handle_update` implementation.
+        An adapter can override this method to process text parts individually.
+        """
+        pass
+
+    async def handle_file(
+        self, file_part: SamFilePart, context: ResponseContext
+    ) -> None:
+        """Handle file/artifact from the agent."""
+        pass
+
+    async def handle_data_part(
+        self, data_part: SamDataPart, context: ResponseContext
+    ) -> None:
+        """Handle structured data part from the agent."""
+        pass
+
+    async def handle_status_update(
+        self, status_text: str, context: ResponseContext
+    ) -> None:
+        """Handle agent status update (progress indicator)."""
+        pass
+
+    async def handle_task_complete(self, context: ResponseContext) -> None:
+        """Handle task completion notification."""
+        pass
+
+    async def handle_error(self, error: SamError, context: ResponseContext) -> None:
+        """Handle error from the agent or gateway."""
+        pass

solace_agent_mesh/gateway/adapter/types.py

@@ -0,0 +1,221 @@
+"""
+Defines the Pydantic models for the Generic Gateway Adapter framework.
+
+These types create a stable abstraction layer, decoupling gateway adapters from the
+underlying A2A protocol specifics.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable, Dict, List, Literal, Optional, Union
+
+from pydantic import BaseModel, Field, model_validator
+
+if TYPE_CHECKING:
+    from google.adk.artifacts import BaseArtifactService
+    from ...common.a2a.types import ArtifactInfo
+
+
+# --- Content Part Models ---
+
+
+class SamTextPart(BaseModel):
+    """Text content in a SAM task."""
+
+    type: Literal["text"] = "text"
+    text: str
+
+
+class SamFilePart(BaseModel):
+    """File content in a SAM task, with either inline bytes or a URI."""
+
+    type: Literal["file"] = "file"
+    name: str
+    content_bytes: Optional[bytes] = None
+    uri: Optional[str] = None
+    mime_type: Optional[str] = None
+
+    @model_validator(mode="after")
+    def validate_content_or_uri(self) -> "SamFilePart":
+        """Ensures that either content_bytes or uri is set, but not both."""
+        if not self.content_bytes and not self.uri:
+            raise ValueError("SamFilePart must have either 'content_bytes' or 'uri'.")
+        if self.content_bytes and self.uri:
+            raise ValueError("SamFilePart cannot have both 'content_bytes' and 'uri'.")
+        return self
+
+
+class SamDataPart(BaseModel):
+    """Structured data in a SAM task."""
+
+    type: Literal["data"] = "data"
+    data: Dict[str, Any]
+    metadata: Optional[Dict[str, Any]] = None
+
+
+SamContentPart = Union[SamTextPart, SamFilePart, SamDataPart]
+
+
+# --- Task and Update Models ---
+
+
+class SamTask(BaseModel):
+    """A task prepared for submission to the SAM agent mesh."""
+
+    parts: List[SamContentPart]
+    session_id: Optional[str] = None
+    target_agent: str = Field(..., description="Target agent name (required).")
+    is_streaming: bool = Field(default=True, description="Enable streaming responses.")
+    platform_context: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Platform-specific data for response routing.",
+    )
+
+
+class SamUpdate(BaseModel):
+    """An update event from the agent containing one or more parts."""
+
+    parts: List[SamContentPart] = Field(default_factory=list)
+    is_final: bool = Field(
+        default=False,
+        description="True if this is the final update before task completion.",
+    )
+
+
+# --- Auth and Error Models ---
+
+
+class AuthClaims(BaseModel):
+    """Authentication claims extracted from a platform event."""
+
+    id: Optional[str] = Field(
+        default=None,
+        description="Primary user identifier. If None, generic gateway uses auth_config default.",
+    )
+    email: Optional[str] = None
+    token: Optional[str] = Field(
+        default=None, description="Bearer token or API key for token-based auth flows."
+    )
+    token_type: Optional[Literal["bearer", "api_key"]] = None
+    source: str = Field(default="platform", description="Authentication source.")
+    raw_context: Dict[str, Any] = Field(
+        default_factory=dict, description="Platform-specific auth context."
+    )
+
+
+class SamError(BaseModel):
+    """A structured error object for outbound error handling."""
+
+    message: str
+    code: int
+    category: Literal[
+        "FAILED", "CANCELED", "TIMED_OUT", "PROTOCOL_ERROR", "GATEWAY_ERROR"
+    ]
+
+
+class SamFeedback(BaseModel):
+    """A structured model for submitting user feedback."""
+
+    task_id: str
+    session_id: str
+    rating: Literal["up", "down"]
+    comment: Optional[str] = None
+    user_id: str
+
+
+# --- Context Models ---
+
+
+class ResponseContext(BaseModel):
+    """Context provided with each outbound response callback."""
+
+    task_id: str
+    session_id: Optional[str]
+    user_id: str
+    platform_context: Dict[str, Any]
+
+
+class GatewayContext:
+    """
+    Context provided to gateway adapter during initialization.
+
+    Provides access to gateway services and helper methods.
+    This is an abstract class definition; the concrete implementation is the
+    GenericGatewayComponent.
+    """
+
+    gateway_id: str
+    namespace: str
+    config: Dict[str, Any]
+    adapter_config: Any  # Can be a Pydantic model or a dict
+    artifact_service: "BaseArtifactService"
+
+    async def handle_external_input(
+        self, external_input: Any, endpoint_context: Optional[Dict[str, Any]] = None
+    ) -> str:
+        raise NotImplementedError
+
+    async def cancel_task(self, task_id: str) -> None:
+        raise NotImplementedError
+
+    async def submit_feedback(self, feedback: "SamFeedback") -> None:
+        """Submits user feedback related to a task."""
+        raise NotImplementedError
+
+    async def load_artifact_content(
+        self, context: "ResponseContext", filename: str, version: Union[int, str] = "latest"
+    ) -> Optional[bytes]:
+        """Loads the raw byte content of an artifact."""
+        raise NotImplementedError
+
+    async def list_artifacts(
+        self, context: "ResponseContext"
+    ) -> List["ArtifactInfo"]:
+        """Lists all artifacts available in the user's context."""
+        raise NotImplementedError
+
+    def add_timer(
+        self, delay_ms: int, callback: "Callable", interval_ms: Optional[int] = None
+    ) -> str:
+        raise NotImplementedError
+
+    def cancel_timer(self, timer_id: str) -> None:
+        raise NotImplementedError
+
+    def get_task_state(self, task_id: str, key: str, default: Any = None) -> Any:
+        raise NotImplementedError
+
+    def set_task_state(self, task_id: str, key: str, value: Any) -> None:
+        raise NotImplementedError
+
+    def get_session_state(self, session_id: str, key: str, default: Any = None) -> Any:
+        raise NotImplementedError
+
+    def set_session_state(self, session_id: str, key: str, value: Any) -> None:
+        raise NotImplementedError
+
+    def create_text_part(self, text: str) -> SamTextPart:
+        return SamTextPart(text=text)
+
+    def create_file_part_from_bytes(
+        self, name: str, content_bytes: bytes, mime_type: str
+    ) -> SamFilePart:
+        return SamFilePart(name=name, content_bytes=content_bytes, mime_type=mime_type)
+
+    def create_file_part_from_uri(
+        self, uri: str, name: str, mime_type: Optional[str] = None
+    ) -> SamFilePart:
+        return SamFilePart(name=name, uri=uri, mime_type=mime_type)
+
+    def create_data_part(self, data: Dict[str, Any]) -> SamDataPart:
+        return SamDataPart(data=data)
+
+    def process_sac_template(
+        self,
+        template: str,
+        payload: Any = None,
+        headers: Optional[Dict[str, str]] = None,
+        query_params: Optional[Dict[str, str]] = None,
+        user_data: Optional[Dict[str, Any]] = None,
+    ) -> str:
+        raise NotImplementedError

solace_agent_mesh/gateway/base/app.py

@@ -39,6 +39,27 @@ BASE_GATEWAY_APP_SCHEMA: Dict[str, List[Dict[str, Any]]] = {
             "default": None,
             "description": "Unique ID for this gateway instance. Auto-generated if omitted.",
         },
+        {
+            "name": "default_agent_name",
+            "required": False,
+            "type": "string",
+            "default": None,
+            "description": "Default agent to route messages to if not specified by the platform or user.",
+        },
+        {
+            "name": "system_purpose",
+            "required": False,
+            "type": "string",
+            "default": "",
+            "description": "Detailed description of the system's overall purpose, to be optionally used by agents.",
+        },
+        {
+            "name": "response_format",
+            "required": False,
+            "type": "string",
+            "default": "",
+            "description": "General guidelines on how agent responses should be structured, to be optionally used by agents.",
+        },
         {
             "name": "artifact_service",
             "required": True,
@@ -144,8 +165,14 @@ class BaseGatewayApp(App):
 
         base_params = BaseGatewayApp.app_schema.get("config_parameters", [])
 
-        merged_config_parameters = list(base_params)
-        merged_config_parameters.extend(specific_params)
+        # Start with the child's parameters to give them precedence.
+        merged_config_parameters = list(specific_params)
+        specific_param_names = {p["name"] for p in specific_params}
+
+        # Add base parameters only if they are not already defined in the child.
+        for base_param in base_params:
+            if base_param["name"] not in specific_param_names:
+                merged_config_parameters.append(base_param)
 
         cls.app_schema = {"config_parameters": merged_config_parameters}
         log.debug(