solace-agent-mesh 0.2.4__py3-none-any.whl → 1.0.2__py3-none-any.whl

solace_agent_mesh/agent/adk/stream_parser.py

@@ -0,0 +1,214 @@
+"""
+A stateful stream parser for identifying and extracting fenced artifact blocks
+from an LLM's text stream.
+"""
+import re
+from enum import Enum, auto
+from dataclasses import dataclass, field
+from typing import List, Dict, Any
+
+# --- Constants ---
+# These are duplicated from callbacks for now to keep the parser self-contained.
+# They should eventually live in a shared constants module.
+ARTIFACT_BLOCK_DELIMITER_OPEN = "«««"
+ARTIFACT_BLOCK_DELIMITER_CLOSE = "»»»"
+# The full sequence that must be matched to start a block.
+BLOCK_START_SEQUENCE = f"{ARTIFACT_BLOCK_DELIMITER_OPEN}save_artifact:"
+# Regex to parse parameters from a confirmed start line.
+PARAMS_REGEX = re.compile(r'(\w+)\s*=\s*"(.*?)"')
+
+
+# --- Parser State and Events (as per design doc) ---
+class ParserState(Enum):
+    """Represents the current state of the stream parser."""
+
+    IDLE = auto()
+    POTENTIAL_BLOCK = auto()
+    IN_BLOCK = auto()
+
+
+@dataclass
+class ParserEvent:
+    """Base class for events emitted by the parser."""
+
+    pass
+
+
+@dataclass
+class BlockStartedEvent(ParserEvent):
+    """Emitted when a fenced block's start is confirmed."""
+
+    params: Dict[str, Any]
+
+
+@dataclass
+class BlockProgressedEvent(ParserEvent):
+    """Emitted periodically while content is being buffered for a block."""
+
+    buffered_size: int
+
+
+@dataclass
+class BlockCompletedEvent(ParserEvent):
+    """Emitted when a fenced block is successfully closed."""
+
+    params: Dict[str, Any]
+    content: str
+
+
+@dataclass
+class BlockInvalidatedEvent(ParserEvent):
+    """Emitted when a potential block start is found to be invalid."""
+
+    rolled_back_text: str
+
+
+@dataclass
+class ParserResult:
+    """The result of processing a single text chunk."""
+
+    user_facing_text: str = ""
+    events: List[ParserEvent] = field(default_factory=list)
+
+
+# --- The Parser Class ---
+class FencedBlockStreamParser:
+    """
+    Processes a stream of text chunks to identify and extract fenced artifact blocks.
+
+    This class implements a state machine to robustly handle partial delimiters
+    and block content that may be split across multiple chunks from an LLM stream.
+    It is designed to be side-effect-free; it emits events that an orchestrator
+    (like an ADK callback) can use to perform actions.
+    """
+
+    def __init__(self, progress_update_interval_bytes: int = 4096):
+        """Initializes the parser and its state machine."""
+        self._state = ParserState.IDLE
+        self._speculative_buffer = ""
+        self._artifact_buffer = ""
+        self._block_params: Dict[str, Any] = {}
+        self._progress_update_interval = progress_update_interval_bytes
+        self._last_progress_update_size = 0
+
+    def _reset_state(self):
+        """Resets the parser to its initial IDLE state."""
+        self._state = ParserState.IDLE
+        self._speculative_buffer = ""
+        self._artifact_buffer = ""
+        self._block_params = {}
+        self._last_progress_update_size = 0
+
+    def process_chunk(self, text_chunk: str) -> ParserResult:
+        """
+        Processes the next chunk of text from the stream.
+
+        Args:
+            text_chunk: The string content from the LLM stream.
+
+        Returns:
+            A ParserResult object containing the text to show to the user and
+            a list of any events that occurred during processing.
+        """
+        user_text_parts: List[str] = []
+        events: List[ParserEvent] = []
+
+        for char in text_chunk:
+            if self._state == ParserState.IDLE:
+                self._process_idle(char, user_text_parts)
+            elif self._state == ParserState.POTENTIAL_BLOCK:
+                self._process_potential(char, user_text_parts, events)
+            elif self._state == ParserState.IN_BLOCK:
+                self._process_in_block(char, events)
+
+        return ParserResult("".join(user_text_parts), events)
+
+    def finalize(self) -> ParserResult:
+        """
+        Call this at the end of an LLM turn to handle any unterminated blocks.
+        This will perform a rollback on any partial block and return the
+        buffered text.
+        """
+        user_text_parts: List[str] = []
+        events: List[ParserEvent] = []
+
+        if self._state == ParserState.POTENTIAL_BLOCK:
+            # The turn ended mid-potential-block. This is a rollback.
+            rolled_back_text = self._speculative_buffer
+            user_text_parts.append(rolled_back_text)
+            events.append(BlockInvalidatedEvent(rolled_back_text=rolled_back_text))
+        elif self._state == ParserState.IN_BLOCK:
+            # The turn ended while inside a block. This is an error/failure.
+            # The orchestrator (callback) will see this and know to fail the artifact.
+            # We emit a BlockCompletedEvent so the orchestrator knows what was buffered.
+            # The orchestrator is responsible for interpreting this as a failure.
+            events.append(
+                BlockCompletedEvent(
+                    params=self._block_params, content=self._artifact_buffer
+                )
+            )
+
+        self._reset_state()
+        return ParserResult("".join(user_text_parts), events)
+
+    def _process_idle(self, char: str, user_text_parts: List[str]):
+        """State handler for when the parser is outside any block."""
+        if char == BLOCK_START_SEQUENCE[0]:
+            self._state = ParserState.POTENTIAL_BLOCK
+            self._speculative_buffer += char
+        else:
+            user_text_parts.append(char)
+
+    def _process_potential(
+        self, char: str, user_text_parts: List[str], events: List[ParserEvent]
+    ):
+        """State handler for when a block might be starting."""
+        self._speculative_buffer += char
+
+        # If we have the full start sequence, we are now looking for the newline.
+        if self._speculative_buffer.startswith(BLOCK_START_SEQUENCE):
+            if char == "\n":
+                # We found the newline, the block is officially started.
+                self._state = ParserState.IN_BLOCK
+                # Extract the parameters string between the start sequence and the newline
+                params_str = self._speculative_buffer[len(BLOCK_START_SEQUENCE) : -1]
+                self._block_params = dict(PARAMS_REGEX.findall(params_str))
+                events.append(BlockStartedEvent(params=self._block_params))
+                self._speculative_buffer = ""  # Clear buffer, we are done with it.
+            # else, we are still buffering the parameters line.
+            return
+
+        # If we are still building up the start sequence itself
+        if BLOCK_START_SEQUENCE.startswith(self._speculative_buffer):
+            # It's still a potential match. Continue buffering.
+            return
+
+        # If we've reached here, the sequence is invalid.
+        # Rollback: The sequence was invalid.
+        rolled_back_text = self._speculative_buffer
+        user_text_parts.append(rolled_back_text)
+        events.append(BlockInvalidatedEvent(rolled_back_text=rolled_back_text))
+        self._reset_state()
+
+    def _process_in_block(self, char: str, events: List[ParserEvent]):
+        """State handler for when the parser is inside a block, buffering content."""
+        self._artifact_buffer += char
+
+        # Check for the closing delimiter
+        if self._artifact_buffer.endswith(ARTIFACT_BLOCK_DELIMITER_CLOSE):
+            # Block is complete.
+            final_content = self._artifact_buffer[
+                : -len(ARTIFACT_BLOCK_DELIMITER_CLOSE)
+            ]
+            events.append(
+                BlockCompletedEvent(params=self._block_params, content=final_content)
+            )
+            self._reset_state()
+        else:
+            # Check if we should emit a progress update
+            current_size = len(self._artifact_buffer.encode("utf-8"))
+            if (
+                current_size - self._last_progress_update_size
+            ) >= self._progress_update_interval:
+                events.append(BlockProgressedEvent(buffered_size=current_size))
+                self._last_progress_update_size = current_size

solace_agent_mesh/agent/adk/tool_wrapper.py

@@ -0,0 +1,139 @@
+"""
+Defines the ADKToolWrapper, a consolidated wrapper for ADK tools.
+"""
+
+import asyncio
+import functools
+import inspect
+from typing import Callable, Dict, List, Optional
+
+from solace_ai_connector.common.log import log
+
+from ...common.utils.embeds import (
+    resolve_embeds_in_string,
+    evaluate_embed,
+    EARLY_EMBED_TYPES,
+    EMBED_DELIMITER_OPEN,
+)
+
+
+class ADKToolWrapper:
+    """
+    A consolidated wrapper for ADK tools that handles:
+    1. Preserving original function metadata (__doc__, __signature__) for ADK.
+    2. Resolving early-stage embeds in string arguments before execution.
+    3. Injecting tool-specific configuration.
+    4. Providing a resilient try/except block to catch all execution errors.
+    """
+
+    def __init__(
+        self,
+        original_func: Callable,
+        tool_config: Optional[Dict],
+        tool_name: str,
+        raw_string_args: Optional[List[str]] = None,
+    ):
+        self._original_func = original_func
+        self._tool_config = tool_config or {}
+        self._tool_name = tool_name
+        self._raw_string_args = set(raw_string_args) if raw_string_args else set()
+        self._is_async = inspect.iscoroutinefunction(original_func)
+
+        functools.update_wrapper(self, original_func)
+
+        try:
+            self.__code__ = original_func.__code__
+            self.__globals__ = original_func.__globals__
+            self.__defaults__ = getattr(original_func, "__defaults__", None)
+            self.__kwdefaults__ = getattr(original_func, "__kwdefaults__", None)
+            self.__closure__ = getattr(original_func, "__closure__", None)
+        except AttributeError:
+            log.debug(
+                "Could not delegate all dunder attributes for tool '%s'. This is normal for some built-in or C-based functions.",
+                self._tool_name,
+            )
+
+        try:
+            self.__signature__ = inspect.signature(original_func)
+            self._accepts_tool_config = "tool_config" in self.__signature__.parameters
+        except (ValueError, TypeError):
+            self.__signature__ = None
+            self._accepts_tool_config = False
+            log.warning("Could not determine signature for tool '%s'.", self._tool_name)
+
+    async def __call__(self, *args, **kwargs):
+        # Allow overriding the context for embed resolution, e.g., when called from a callback
+        _override_embed_context = kwargs.pop("_override_embed_context", None)
+        log_identifier = f"[ADKToolWrapper:{self._tool_name}]"
+
+        context_for_embeds = _override_embed_context or kwargs.get("tool_context")
+        resolved_args = []
+        resolved_kwargs = kwargs.copy()
+
+        if context_for_embeds:
+            # Resolve positional args
+            for arg in args:
+                if isinstance(arg, str) and EMBED_DELIMITER_OPEN in arg:
+                    resolved_arg, _, _ = await resolve_embeds_in_string(
+                        text=arg,
+                        context=context_for_embeds,
+                        resolver_func=evaluate_embed,
+                        types_to_resolve=EARLY_EMBED_TYPES,
+                        log_identifier=log_identifier,
+                        config=self._tool_config,
+                    )
+                    resolved_args.append(resolved_arg)
+                else:
+                    resolved_args.append(arg)
+
+            for key, value in kwargs.items():
+                if key in self._raw_string_args and isinstance(value, str):
+                    log.debug(
+                        "%s Skipping embed resolution for raw string kwarg '%s'",
+                        log_identifier,
+                        key,
+                    )
+                elif isinstance(value, str) and EMBED_DELIMITER_OPEN in value:
+                    log.debug("%s Resolving embeds for kwarg '%s'", log_identifier, key)
+                    resolved_value, _, _ = await resolve_embeds_in_string(
+                        text=value,
+                        context=context_for_embeds,
+                        resolver_func=evaluate_embed,
+                        types_to_resolve=EARLY_EMBED_TYPES,
+                        log_identifier=log_identifier,
+                        config=self._tool_config,
+                    )
+                    resolved_kwargs[key] = resolved_value
+        else:
+            log.warning(
+                "%s ToolContext not found. Skipping embed resolution for all args.",
+                log_identifier,
+            )
+            resolved_args = list(args)
+
+        if self._accepts_tool_config:
+            resolved_kwargs["tool_config"] = self._tool_config
+        elif self._tool_config:
+            log.warning(
+                "%s Tool was provided a 'tool_config' but its function signature does not accept it. The config will be ignored.",
+                log_identifier,
+            )
+
+        try:
+            if self._is_async:
+                return await self._original_func(*resolved_args, **resolved_kwargs)
+            else:
+                loop = asyncio.get_running_loop()
+                return await loop.run_in_executor(
+                    None,
+                    functools.partial(
+                        self._original_func, *resolved_args, **resolved_kwargs
+                    ),
+                )
+        except Exception as e:
+            log.exception("%s Tool execution failed: %s", log_identifier, e)
+            return {
+                "status": "error",
+                "message": f"Tool '{self._tool_name}' failed with an unexpected error: {str(e)}",
+                "tool_name": self._tool_name,
+            }

solace_agent_mesh/agent/agent_llm.txt

@@ -0,0 +1,41 @@
+Here is the comprehensive developer guide for the `agent` directory.
+
+## Quick Summary
+The `agent` directory provides a comprehensive framework for hosting Google ADK (Agent Development Kit) agents within the Solace AI Connector ecosystem. It bridges ADK agents with the A2A (Agent-to-Agent) protocol over Solace messaging, enabling distributed agent communication, task delegation, and rich tool functionality.
+
+The architecture is modular, consisting of several key components:
+*   **`sac/` (Solace AI Connector):** The main entry point, providing the `SamAgentApp` and `SamAgentComponent` to host the agent and manage its lifecycle and communication over the Solace event mesh.
+*   **`adk/` (Agent Development Kit):** The core integration layer with Google's ADK. It defines the custom `AppLlmAgent`, manages asynchronous task execution, and provides a rich set of callbacks to augment agent behavior.
+*   **`tools/`:** A comprehensive and extensible library of tools available to the agent, covering data analysis, artifact management, web requests, multimedia processing, and inter-agent communication.
+*   **`protocol/`:** The underlying implementation of the A2A (Agent-to-Agent) communication protocol, handling message routing and event processing.
+*   **`utils/`:** A collection of helper modules for common tasks like artifact management, configuration parsing, and context handling.
+*   **`testing/`:** Utilities to aid in debugging and testing custom agent implementations.
+
+These components work together to create a robust environment where an ADK agent can be configured with specific instructions and tools, communicate with other agents, and execute complex tasks in a distributed, event-driven manner.
+
+## Files and Subdirectories Overview
+- **Direct files:**
+  - `__init__.py`: An empty file that marks the `agent` directory as a Python package.
+- **Subdirectories:**
+  - `adk/`: Provides the core integration layer with Google's ADK, including custom agents, services, and callbacks.
+  - `protocol/`: Implements the A2A protocol event handlers for message routing and agent communication.
+  - `sac/`: Contains the Solace AI Connector app and component implementations for hosting ADK agents.
+  - `testing/`: Provides utilities for testing the A2A framework and debugging agent behavior.
+  - `tools/`: A comprehensive, registry-based tool library for AI agents.
+  - `utils/`: Contains helper utilities for configuration, context handling, and artifact management.
+
+## Developer API Reference
+
+### Direct Files
+
+#### __init__.py
+**Purpose:** Standard Python package initializer. It allows the `agent` directory to be treated as a package.
+**Import:** `import agent`
+
+**Classes/Functions/Constants:** [None]
+
+### Subdirectory APIs
+
+#### adk/
+**Purpose:** Provides the core integration layer between the Solace AI Connector and Google's ADK.
+**Key Exports:** `App