Merge remote-tracking branch 'origin/main' into hugo/adk-upgrade

Author: Hugo-Pare

Dockerfile

@@ -11,7 +11,7 @@ RUN apt-get update && \
     curl \
     ffmpeg && \
     rm -rf /var/lib/apt/lists/* && \
-    curl -sL https://deb.nodesource.com/setup_24.x | bash - && \
+    curl -sL https://deb.nodesource.com/setup_20.x | bash - && \
     apt-get install -y --no-install-recommends nodejs && \
     apt-get purge -y --auto-remove && \
     apt-get clean && \

cli/commands/init_cmd/orchestrator_step.py

@@ -382,8 +382,7 @@ def create_orchestrator_config(
            c. Direct Execution: If the task is not suitable for delegation (neither to a single agent nor a multi-agent sequence) and falls within your own capabilities, execute the task yourself.
 
         Artifact Management Guidelines:
-        - If an artifact was created during the task (either by yourself or a delegated agent), you must use the `list_artifacts` tool to get the details of the created artifacts.
-        - You must then review the list of artifacts and return the ones that are important for the user by using artifact_return embed.
+        - You must review your artifacts and return the ones that are important for the user by using artifact_return embed. You can use list_artifacts to see all available artifacts.
         - Provide regular progress updates using `status_update` embed directives, especially before initiating any tool call."""
 
         session_service_lines = [

docs/docs/documentation/components/builtin-tools/builtin-tools.md

@@ -65,11 +65,9 @@ The following sections detail the available tool groups and the individual tools
 **Description**: Tools for creating, loading, and managing file artifacts.
 
 **Individual Tools**:
-- `create_artifact`
 - `append_to_artifact`
 - `list_artifacts`
 - `load_artifact`
-- `signal_artifact_for_return`
 - `apply_embed_and_create_artifact`
 - `extract_content_from_artifact`
 

docs/docs/documentation/deploying/logging.md

@@ -57,7 +57,8 @@ formatters:
   # JSON format for structured logging
   jsonFormatter:
     "()": pythonjsonlogger.json.JsonFormatter # The python-json-logger package is used for JSON formatting
-    format: "%(asctime)s %(levelname)s %(threadName)s %(name)s %(message)s"
+    format: "%(timestamp)s %(levelname)s %(threadName)s %(name)s %(message)s"
+    timestamp: "timestamp" # Generates ISO 8601-formatted timestamps for %(timestamp)s placeholder
 
 # Handlers determine where log messages go
 handlers:

docs/docs/documentation/installing-and-configuring/installation.md

@@ -20,6 +20,12 @@ The [Solace Agent Mesh Module](https://pypi.org/project/solace-agent-mesh) inclu
 
 Installing the PyPI package provides both the Agent Mesh CLI and the framework (which is built on the Python SDK).
 
+First, create a project directory and navigate into it:
+
+```sh
+mkdir my-sam && cd my-sam
+```
+
 :::tip
 We recommend installing the package in a virtual environment to avoid conflicts with other Python packages.
 :::

preset/logging_config.yaml

@@ -6,8 +6,9 @@ formatters:
     format: "%(asctime)s | %(levelname)-5s | %(threadName)s | %(name)s | %(message)s"
 
   jsonFormatter:
-    "()": pythonjsonlogger.jsonlogger.JsonFormatter
-    format: "%(asctime)s %(levelname)s %(threadName)s %(name)s %(message)s"
+    "()": pythonjsonlogger.json.JsonFormatter
+    format: "%(timestamp)s %(levelname)s %(threadName)s %(name)s %(message)s"
+    timestamp: "timestamp"
 
 handlers:
   streamHandler:

pyproject.toml

@@ -32,6 +32,7 @@ dependencies = [
     "python-jwt==4.1.0",
     "asteval==1.0.6",
     "pystache==0.6.8",
+    "python-liquid==2.1.0",
     "pandas==2.3.2",
     "numpy==2.2.6",
     "plotly==6.3.0",

src/solace_agent_mesh/agent/adk/callbacks.py

@@ -540,7 +540,7 @@ def _get_text_mime_type_and_extension(
 
         format_mapping = {
             TextFormat.JSON: ("application/json", ".json"),
-            TextFormat.YAML: ("application/x-yaml", ".yaml"),
+            TextFormat.YAML: ("application/yaml", ".yaml"),
             TextFormat.CSV: ("text/csv", ".csv"),
             TextFormat.MARKDOWN: ("text/markdown", ".md"),
             TextFormat.PLAIN: ("text/plain", ".txt"),

src/solace_agent_mesh/agent/adk/mcp_content_processor.py

@@ -3,18 +3,24 @@
 from an LLM's text stream.
 """
 
+import logging
 import re
 from enum import Enum, auto
 from dataclasses import dataclass, field
 from typing import List, Dict, Any
 
+log = logging.getLogger(__name__)
+
 # --- 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:"
+# The full sequences that must be matched to start a block.
+SAVE_ARTIFACT_START_SEQUENCE = f"{ARTIFACT_BLOCK_DELIMITER_OPEN}save_artifact:"
+TEMPLATE_START_SEQUENCE = f"{ARTIFACT_BLOCK_DELIMITER_OPEN}template:"
+# For backward compatibility
+BLOCK_START_SEQUENCE = SAVE_ARTIFACT_START_SEQUENCE
 # Regex to parse parameters from a confirmed start line.
 PARAMS_REGEX = re.compile(r'(\w+)\s*=\s*"(.*?)"')
 
@@ -66,6 +72,21 @@ class BlockInvalidatedEvent(ParserEvent):
     rolled_back_text: str
 
 
+@dataclass
+class TemplateBlockStartedEvent(ParserEvent):
+    """Emitted when a template block's start is confirmed."""
+
+    params: Dict[str, Any]
+
+
+@dataclass
+class TemplateBlockCompletedEvent(ParserEvent):
+    """Emitted when a template block is successfully closed."""
+
+    params: Dict[str, Any]
+    template_content: str
+
+
 @dataclass
 class ParserResult:
     """The result of processing a single text chunk."""
@@ -93,6 +114,10 @@ def __init__(self, progress_update_interval_bytes: int = 4096):
         self._block_params: Dict[str, Any] = {}
         self._progress_update_interval = progress_update_interval_bytes
         self._last_progress_update_size = 0
+        # Track block type and nesting for template handling
+        self._current_block_type: str = None  # "save_artifact" or "template"
+        self._nesting_depth = 0  # Track if we're inside a block
+        self._previous_state: ParserState = None  # Track state before POTENTIAL_BLOCK
 
     def _reset_state(self):
         """Resets the parser to its initial IDLE state."""
@@ -101,6 +126,9 @@ def _reset_state(self):
         self._artifact_buffer = ""
         self._block_params = {}
         self._last_progress_update_size = 0
+        self._current_block_type = None
+        self._nesting_depth = 0
+        self._previous_state = None
 
     def process_chunk(self, text_chunk: str) -> ParserResult:
         """
@@ -142,21 +170,36 @@ def finalize(self) -> ParserResult:
             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 (callback) will see this and know to fail the artifact/template.
+            # We emit the appropriate completion event 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
-                )
+            log.warning(
+                "[StreamParser] finalize() found unterminated block! Type: %s, buffer length: %d, nesting_depth: %d",
+                self._current_block_type,
+                len(self._artifact_buffer),
+                self._nesting_depth,
             )
+            if self._current_block_type == "template":
+                events.append(
+                    TemplateBlockCompletedEvent(
+                        params=self._block_params,
+                        template_content=self._artifact_buffer,
+                    )
+                )
+            else:
+                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._previous_state = ParserState.IDLE
             self._state = ParserState.POTENTIAL_BLOCK
             self._speculative_buffer += char
         else:
@@ -168,59 +211,145 @@ def _process_potential(
         """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):
+        # Check if we match save_artifact or template start sequences
+        matched_sequence = None
+        matched_type = None
+
+        if self._speculative_buffer.startswith(SAVE_ARTIFACT_START_SEQUENCE):
+            matched_sequence = SAVE_ARTIFACT_START_SEQUENCE
+            matched_type = "save_artifact"
+        elif self._speculative_buffer.startswith(TEMPLATE_START_SEQUENCE):
+            matched_sequence = TEMPLATE_START_SEQUENCE
+            matched_type = "template"
+
+        if matched_sequence:
             if char == "\n":
                 # We found the newline, the block is officially started.
+
+                # If we're already inside a save_artifact block and this is a template,
+                # we need to pass it through as literal text (preserve nesting)
+                if self._nesting_depth > 0 and matched_type == "template":
+                    # Preserve template literally inside artifact
+                    self._artifact_buffer += self._speculative_buffer
+                    # Increment nesting depth so we know to skip the next »»»
+                    # (it will close the nested template, not the outer artifact)
+                    self._nesting_depth += 1
+                    # Don't reset state! We're still inside the save_artifact block.
+                    # Just clear the speculative buffer and stay IN_BLOCK to continue
+                    # buffering the rest of the artifact content.
+                    self._speculative_buffer = ""
+                    self._state = ParserState.IN_BLOCK
+                    return
+
                 self._state = ParserState.IN_BLOCK
+                self._current_block_type = matched_type
+                self._nesting_depth += 1
+
                 # Extract the parameters string between the start sequence and the newline
-                params_str = self._speculative_buffer[len(BLOCK_START_SEQUENCE) : -1]
+                params_str = self._speculative_buffer[len(matched_sequence) : -1]
                 self._block_params = dict(PARAMS_REGEX.findall(params_str))
-                events.append(BlockStartedEvent(params=self._block_params))
+
+                if matched_type == "save_artifact":
+                    events.append(BlockStartedEvent(params=self._block_params))
+                elif matched_type == "template":
+                    events.append(TemplateBlockStartedEvent(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):
+        # If we are still building up a start sequence (could be either)
+        if SAVE_ARTIFACT_START_SEQUENCE.startswith(
+            self._speculative_buffer
+        ) or TEMPLATE_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()
+
+        # Check if we were IN_BLOCK before transitioning to POTENTIAL_BLOCK
+        # If so, add the rolled-back text to the artifact buffer, not user-visible text
+        if self._previous_state == ParserState.IN_BLOCK:
+            log.debug(
+                "[StreamParser] Invalid sequence '%s' detected while IN_BLOCK. Adding to artifact buffer.",
+                repr(rolled_back_text),
+            )
+            self._artifact_buffer += rolled_back_text
+            self._speculative_buffer = ""
+            self._state = ParserState.IN_BLOCK
+            # Don't emit BlockInvalidatedEvent - this is just normal artifact content
+        else:
+            # We were IDLE, so this is user-facing text
+            user_text_parts.append(rolled_back_text)
+            events.append(BlockInvalidatedEvent(rolled_back_text=rolled_back_text))
+            self._speculative_buffer = ""
+            self._state = ParserState.IDLE
+
+        self._previous_state = None
 
     def _process_in_block(self, char: str, events: List[ParserEvent]):
         """State handler for when the parser is inside a block, buffering content."""
+        # Check if this might be the start of a nested block
+        if char == BLOCK_START_SEQUENCE[0]:
+            # This might be the start of a nested template block
+            # Transition to POTENTIAL_BLOCK to check
+            self._previous_state = ParserState.IN_BLOCK
+            self._state = ParserState.POTENTIAL_BLOCK
+            self._speculative_buffer += char
+            return
+
         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:
-                new_chunk = self._artifact_buffer[
-                    self._last_progress_update_size : current_size
+            # Check if this is closing a nested block or the current block
+            if self._nesting_depth > 1:
+                # This »»» is closing a nested template block, not the outer save_artifact
+                # Keep it in the buffer and just decrement nesting
+                self._nesting_depth -= 1
+                # Don't emit events, don't strip the delimiter, just continue buffering
+            else:
+                # This is closing the outermost block (nesting_depth == 1)
+                # Block is complete.
+                final_content = self._artifact_buffer[
+                    : -len(ARTIFACT_BLOCK_DELIMITER_CLOSE)
                 ]
-                events.append(
-                    BlockProgressedEvent(
-                        params=self._block_params,
-                        buffered_size=current_size,
-                        chunk=new_chunk,
+
+                # Emit the appropriate completion event based on block type
+                if self._current_block_type == "template":
+                    events.append(
+                        TemplateBlockCompletedEvent(
+                            params=self._block_params, template_content=final_content
+                        )
                     )
-                )
-                self._last_progress_update_size = current_size
+                else:
+                    # Default to save_artifact behavior
+                    events.append(
+                        BlockCompletedEvent(
+                            params=self._block_params, content=final_content
+                        )
+                    )
+
+                # Decrement nesting depth
+                self._nesting_depth = max(0, self._nesting_depth - 1)
+                self._reset_state()
+        else:
+            # Check if we should emit a progress update (only for save_artifact blocks)
+            if self._current_block_type == "save_artifact":
+                current_size = len(self._artifact_buffer.encode("utf-8"))
+                if (
+                    current_size - self._last_progress_update_size
+                ) >= self._progress_update_interval:
+                    new_chunk = self._artifact_buffer[
+                        self._last_progress_update_size : current_size
+                    ]
+                    events.append(
+                        BlockProgressedEvent(
+                            params=self._block_params,
+                            buffered_size=current_size,
+                            chunk=new_chunk,
+                        )
+                    )
+                    self._last_progress_update_size = current_size