solace-agent-mesh 1.11.2__py3-none-any.whl

solace_agent_mesh/common/utils/embeds/converter.py

@@ -0,0 +1,447 @@
+"""
+Contains the Central Data Converter and Serializer functions.
+"""
+
+import logging
+import json
+import csv
+import io
+import base64
+from typing import Any, Tuple, Optional, List, Dict
+
+from .types import DataFormat
+from ..mime_helpers import is_text_based_mime_type
+
+log = logging.getLogger(__name__)
+
+import yaml
+
+
+def _parse_string_to_list_of_dicts(
+    data_string: str, mime_type: Optional[str], log_id: str
+) -> Tuple[Optional[List[Dict[str, Any]]], Optional[str]]:
+    """
+    Parses a string into a list of dictionaries based on its MIME type.
+    Supports JSON, CSV, and YAML.
+
+    Args:
+        data_string: The string to parse.
+        mime_type: The MIME type of the string data.
+        log_id: Identifier for logging.
+
+    Returns:
+        A tuple (parsed_data, error_message).
+        parsed_data is List[Dict[str, Any]] on success, None on failure.
+        error_message is a string on failure, None on success.
+    """
+    normalized_mime_type = (mime_type or "").lower()
+    log.debug(
+        "%s Parsing string to LIST_OF_DICTS, MIME: '%s'", log_id, normalized_mime_type
+    )
+
+    try:
+        if "json" in normalized_mime_type:
+            parsed_json = json.loads(data_string)
+            if isinstance(parsed_json, list) and all(
+                isinstance(item, dict) for item in parsed_json
+            ):
+                return parsed_json, None
+            elif isinstance(parsed_json, dict):
+                return [parsed_json], None
+            else:
+                return (
+                    None,
+                    "Parsed JSON is not a list of dictionaries or a single dictionary.",
+                )
+        elif "csv" in normalized_mime_type:
+            string_io = io.StringIO(data_string)
+            reader = csv.DictReader(string_io)
+            return list(reader), None
+        elif "yaml" in normalized_mime_type or "yml" in normalized_mime_type:
+            parsed_yaml = yaml.safe_load(data_string)
+            if isinstance(parsed_yaml, list) and all(
+                isinstance(item, dict) for item in parsed_yaml
+            ):
+                return parsed_yaml, None
+            elif isinstance(parsed_yaml, dict):
+                return [parsed_yaml], None
+            else:
+                return (
+                    None,
+                    "Parsed YAML is not a list of dictionaries or a single dictionary.",
+                )
+        else:
+            return (
+                None,
+                f"Unsupported MIME type '{mime_type}' for direct conversion to LIST_OF_DICTS from string.",
+            )
+    except json.JSONDecodeError:
+        return None, "Failed to parse string as JSON"
+    except csv.Error:
+        return None, "Failed to parse string as CSV (DictReader)"
+    except yaml.YAMLError:
+        return None, "Failed to parse string as YAML"
+    except Exception as e:
+        return (
+            None,
+            f"Unexpected error parsing string to list of dicts (MIME: {mime_type}): {e}",
+        )
+
+
+def convert_data(
+    current_data: Any,
+    current_format: Optional[DataFormat],
+    target_format: DataFormat,
+    log_id: str = "[Converter]",
+    original_mime_type: Optional[str] = None,
+) -> Tuple[Any, DataFormat, Optional[str]]:
+    """
+    Converts data between different internal DataFormat types, using original
+    MIME type as context where necessary (e.g., BYTES -> structured).
+
+    Args:
+        current_data: The data to convert.
+        current_format: The current DataFormat of the data, or None if unknown/numeric.
+        target_format: The desired DataFormat.
+        log_id: Identifier for logging.
+        original_mime_type: The original MIME type of the data, used as a hint
+                            for parsing BYTES or STRING into structured formats.
+
+    Returns:
+        A tuple containing:
+        - The converted data (or original data if conversion failed).
+        - The resulting DataFormat (target_format on success, current_format on failure).
+        - An optional error message string if conversion failed.
+    """
+    current_format_name = current_format.name if current_format else "Unknown/Numeric"
+    log.debug(
+        "%s Attempting conversion: %s -> %s (Hint: MimeType=%s)",
+        log_id,
+        current_format_name,
+        target_format.name,
+        original_mime_type,
+    )
+
+    if current_format == target_format:
+        log.debug(
+            "%s No conversion needed: %s -> %s",
+            log_id,
+            current_format_name,
+            target_format.name,
+        )
+        return current_data, current_format, None
+
+    normalized_mime_type = (original_mime_type or "").lower()
+
+    try:
+        if current_format is None:
+            if target_format == DataFormat.STRING:
+                try:
+                    return str(current_data), DataFormat.STRING, None
+                except Exception as e:
+                    return (
+                        current_data,
+                        current_format,
+                        f"Failed to convert unknown/numeric type to string: {e}",
+                    )
+            else:
+                return (
+                    current_data,
+                    current_format,
+                    f"Cannot convert from unknown/numeric format to {target_format.name}",
+                )
+
+        elif current_format == DataFormat.BYTES:
+            if target_format == DataFormat.STRING:
+                if original_mime_type and is_text_based_mime_type(original_mime_type):
+                    try:
+                        return current_data.decode("utf-8"), DataFormat.STRING, None
+                    except UnicodeDecodeError as e:
+                        return (
+                            current_data,
+                            current_format,
+                            f"Failed to decode bytes (MIME: {original_mime_type}) as UTF-8: {e}",
+                        )
+                else:
+                    error_msg = f"Cannot convert binary data (MIME: {original_mime_type or 'unknown'}) to a general string. This conversion is only supported for text-based MIME types."
+                    log.warning("%s %s", log_id, error_msg)
+                    return current_data, current_format, error_msg
+            elif target_format == DataFormat.JSON_OBJECT:
+                if not normalized_mime_type.startswith(
+                    "application/json"
+                ) and not normalized_mime_type.startswith("text/json"):
+                    return (
+                        current_data,
+                        current_format,
+                        f"Cannot convert BYTES to JSON_OBJECT: Original MIME type '{original_mime_type}' is not JSON.",
+                    )
+                try:
+                    string_data = current_data.decode("utf-8")
+                    return json.loads(string_data), DataFormat.JSON_OBJECT, None
+                except UnicodeDecodeError as e:
+                    return (
+                        current_data,
+                        current_format,
+                        f"Failed to decode bytes as UTF-8 before JSON parsing: {e}",
+                    )
+                except json.JSONDecodeError as e:
+                    return (
+                        current_data,
+                        current_format,
+                        f"Failed to parse decoded bytes as JSON: {e}",
+                    )
+            elif target_format == DataFormat.LIST_OF_DICTS:
+                if not normalized_mime_type.startswith("text/csv"):
+                    return (
+                        current_data,
+                        current_format,
+                        f"Cannot convert BYTES to LIST_OF_DICTS: Original MIME type '{original_mime_type}' is not CSV.",
+                    )
+                try:
+                    string_data = current_data.decode("utf-8")
+                    string_io = io.StringIO(string_data)
+                    reader = csv.DictReader(string_io)
+                    return list(reader), DataFormat.LIST_OF_DICTS, None
+                except UnicodeDecodeError as e:
+                    return (
+                        current_data,
+                        current_format,
+                        f"Failed to decode bytes as UTF-8 before CSV parsing: {e}",
+                    )
+                except csv.Error as e:
+                    return (
+                        current_data,
+                        current_format,
+                        f"Failed to parse decoded bytes as CSV (DictReader): {e}",
+                    )
+                except Exception as e:
+                    return (
+                        current_data,
+                        current_format,
+                        f"Unexpected error parsing decoded bytes as CSV: {e}",
+                    )
+
+        elif current_format == DataFormat.STRING:
+            if target_format == DataFormat.BYTES:
+                try:
+                    return current_data.encode("utf-8"), DataFormat.BYTES, None
+                except Exception as e:
+                    return (
+                        current_data,
+                        current_format,
+                        f"Failed to encode string to UTF-8 bytes: {e}",
+                    )
+            elif target_format == DataFormat.JSON_OBJECT:
+                try:
+                    return json.loads(current_data), DataFormat.JSON_OBJECT, None
+                except json.JSONDecodeError:
+                    return (
+                        current_data,
+                        current_format,
+                        "Failed to parse string as JSON",
+                    )
+            elif target_format == DataFormat.LIST_OF_DICTS:
+                parsed_data, error_msg = _parse_string_to_list_of_dicts(
+                    data_string=current_data,
+                    mime_type=original_mime_type,
+                    log_id=log_id,
+                )
+                if error_msg:
+                    return current_data, current_format, error_msg
+                return parsed_data, DataFormat.LIST_OF_DICTS, None
+
+        elif current_format == DataFormat.JSON_OBJECT:
+            if target_format == DataFormat.STRING:
+                try:
+                    return (
+                        json.dumps(current_data, separators=(",", ":")),
+                        DataFormat.STRING,
+                        None,
+                    )
+                except TypeError as e:
+                    return (
+                        current_data,
+                        current_format,
+                        f"Failed to serialize JSON object to string: {e}",
+                    )
+            elif target_format == DataFormat.LIST_OF_DICTS:
+                if isinstance(current_data, list) and all(
+                    isinstance(item, dict) for item in current_data
+                ):
+                    return current_data, DataFormat.LIST_OF_DICTS, None
+                else:
+                    return (
+                        current_data,
+                        current_format,
+                        "JSON object is not a list of dictionaries",
+                    )
+
+        elif current_format == DataFormat.LIST_OF_DICTS:
+            if target_format == DataFormat.STRING:
+                try:
+                    if not current_data:
+                        return "", DataFormat.STRING, None
+                    output_io = io.StringIO()
+                    fieldnames = list(current_data[0].keys())
+                    writer = csv.DictWriter(output_io, fieldnames=fieldnames)
+                    writer.writeheader()
+                    writer.writerows(current_data)
+                    return output_io.getvalue().strip("\r\n"), DataFormat.STRING, None
+                except IndexError:
+                    return "", DataFormat.STRING, None
+                except Exception as e:
+                    return (
+                        current_data,
+                        current_format,
+                        f"Failed to format list of dicts as CSV string: {e}",
+                    )
+            elif target_format == DataFormat.JSON_OBJECT:
+                return current_data, DataFormat.JSON_OBJECT, None
+
+        error_msg = f"Unsupported conversion requested: {current_format_name} -> {target_format.name}"
+        log.warning("%s %s", log_id, error_msg)
+        return current_data, current_format, error_msg
+
+    except Exception as e:
+        error_msg = f"Unexpected error during conversion from {current_format_name} to {target_format.name}: {e}"
+        log.exception("%s %s", log_id, error_msg)
+        return current_data, current_format, error_msg
+
+
+def serialize_data(
+    data: Any,
+    data_format: Optional[DataFormat],
+    target_string_format: Optional[str],
+    original_mime_type: Optional[str],
+    log_id: str = "[Serializer]",
+) -> Tuple[str, Optional[str]]:
+    """
+    Converts data from its internal DataFormat into the target string representation.
+    Handles Python format specifiers for numeric types.
+
+    Args:
+        data: The data to serialize.
+        data_format: The current DataFormat of the data, or None if unknown/numeric.
+        target_string_format: The desired final string format (e.g., "text", "json", "datauri", or Python format spec like ".2f").
+                              If None or empty, defaults to "text".
+        original_mime_type: The original MIME type of the artifact (needed for datauri).
+        log_id: Identifier for logging.
+
+    Returns:
+        A tuple containing:
+        - The final serialized string.
+        - An optional error message string if serialization failed.
+    """
+    target_fmt = (target_string_format or "text").strip()
+    log.debug(
+        "%s Serializing data from %s to format '%s'",
+        log_id,
+        data_format.name if data_format else "Unknown/Numeric",
+        target_fmt,
+    )
+
+    try:
+        if isinstance(data, (int, float)) and target_string_format:
+            is_format_spec = target_fmt.startswith(".") or any(
+                c in target_fmt for c in "defg%"
+            )
+            if is_format_spec:
+                try:
+                    formatted_string = format(data, target_fmt)
+                    log.debug(
+                        "%s Applied Python format specifier '%s' to numeric data.",
+                        log_id,
+                        target_fmt,
+                    )
+                    return formatted_string, None
+                except ValueError as fmt_err:
+                    err_msg = f"Invalid format specifier '{target_fmt}' for numeric data type {type(data).__name__}: {fmt_err}"
+                    log.warning("%s %s", log_id, err_msg)
+                except Exception as e:
+                    err_msg = f"Error applying format specifier '{target_fmt}': {e}"
+                    log.warning("%s %s", log_id, err_msg)
+        target_fmt_lower = target_fmt.lower()
+
+        if target_fmt_lower == "text":
+            string_data, _, error = convert_data(
+                data, data_format, DataFormat.STRING, log_id, original_mime_type
+            )
+            if error:
+                return f"[Serialization Error: {error}]", error
+            return string_data, None
+
+        elif target_fmt_lower == "json":
+            json_obj, _, error = convert_data(
+                data, data_format, DataFormat.JSON_OBJECT, log_id, original_mime_type
+            )
+            if error:
+                return f"[Serialization Error: {error}]", error
+            try:
+                return json.dumps(json_obj, separators=(",", ":")), None
+            except TypeError as e:
+                err_msg = f"Failed to serialize to JSON string: {e}"
+                return f"[Serialization Error: {err_msg}]", err_msg
+
+        elif target_fmt_lower == "json_pretty":
+            json_obj, _, error = convert_data(
+                data, data_format, DataFormat.JSON_OBJECT, log_id, original_mime_type
+            )
+            if error:
+                return f"[Serialization Error: {error}]", error
+            try:
+                return json.dumps(json_obj, indent=2), None
+            except TypeError as e:
+                err_msg = f"Failed to serialize to pretty JSON string: {e}"
+                return f"[Serialization Error: {err_msg}]", err_msg
+
+        elif target_fmt_lower == "csv":
+            list_of_dicts, _, error1 = convert_data(
+                data, data_format, DataFormat.LIST_OF_DICTS, log_id, original_mime_type
+            )
+            if error1:
+                return f"[Serialization Error: {error1}]", error1
+            csv_string, _, error2 = convert_data(
+                list_of_dicts,
+                DataFormat.LIST_OF_DICTS,
+                DataFormat.STRING,
+                log_id,
+                "text/csv",
+            )
+            if error2:
+                return f"[Serialization Error: {error2}]", error2
+            return csv_string, None
+
+        elif target_fmt_lower == "datauri":
+            byte_data, _, error = convert_data(
+                data, data_format, DataFormat.BYTES, log_id, original_mime_type
+            )
+            if error:
+                return f"[Serialization Error: {error}]", error
+
+            if not original_mime_type:
+                err_msg = "Original MIME type required for datauri format"
+                return f"[Serialization Error: {err_msg}]", err_msg
+            try:
+                encoded = base64.b64encode(byte_data).decode("utf-8")
+                return f"data:{original_mime_type};base64,{encoded}", None
+            except Exception as e:
+                err_msg = f"Failed to encode datauri: {e}"
+                return f"[Serialization Error: {err_msg}]", err_msg
+
+        else:
+            log.warning(
+                "%s Unknown target format '%s'. Defaulting to 'text'.",
+                log_id,
+                target_fmt,
+            )
+            string_data, _, error = convert_data(
+                data, data_format, DataFormat.STRING, log_id, original_mime_type
+            )  # Pass mime type hint
+            if error:
+                return f"[Serialization Error: {error}]", error
+            return string_data, None
+
+    except Exception as e:
+        error_msg = f"Unexpected error during serialization to '{target_fmt}': {e}"
+        log.exception("%s %s", log_id, error_msg)
+        return f"[Serialization Error: {error_msg}]", error_msg

solace_agent_mesh/common/utils/embeds/embeds_llm.txt

@@ -0,0 +1,220 @@
+# DEVELOPER GUIDE: embeds
+
+## Quick Summary
+The `embeds` directory provides a comprehensive system for finding, parsing, and resolving embedded expressions within strings. These expressions use `«...»` syntax and can represent dynamic values like mathematical calculations, datetimes, UUIDs, or content from stored artifacts. The system supports multi-step data transformation pipelines, recursive embed resolution, and includes safety features like depth and size limits. It's designed as a core component for dynamic content generation and data processing in agent workflows.
+
+## Files Overview
+- `__init__.py` - Main public entry point exporting key functions and constants
+- `constants.py` - Defines embed syntax (delimiters, separators), regex patterns, and type classifications
+- `converter.py` - Data format conversion and serialization functions
+- `evaluators.py` - Specific evaluation logic for simple embed types (math, datetime, uuid, etc.)
+- `modifiers.py` - Data transformation functions that can be chained together (jsonpath, slice, grep, etc.)
+- `resolver.py` - Core orchestration engine handling embed resolution, modifier chains, and recursion
+- `types.py` - DataFormat enum for tracking data types during transformations
+
+## Developer API Reference
+
+### __init__.py
+**Purpose:** Main public entry point that exports the most commonly used functions and constants from other modules.
+
+**Import:** `from solace_agent_mesh.common.utils.embeds import resolve_embeds_recursively_in_string, evaluate_embed, EMBED_REGEX`
+
+**Functions:**
+- `evaluate_embed(embed_type: str, expression: str, format_spec: Optional[str], context: Dict[str, Any], log_identifier: str, config: Optional[Dict] = None, current_depth: int = 0, visited_artifacts: Optional[Set[Tuple[str, int]]] = None) -> Union[Tuple[str, Optional[str], int], Tuple[None, str, Any]]` - Evaluates a single parsed embed expression
+- `resolve_embeds_in_string(text: str, context: Any, resolver_func: Callable, types_to_resolve: Set[str], log_identifier: str = "[EmbedUtil]", config: Optional[Dict[str, Any]] = None) -> Tuple[str, int, List[Tuple[int, Any]]]` - Resolves embeds in a string for a single pass (non-recursive)
+- `resolve_embeds_recursively_in_string(text: str, context: Any, resolver_func: Callable, types_to_resolve: Set[str], log_identifier: str, config: Optional[Dict], max_depth: int, current_depth: int = 0, visited_artifacts: Optional[Set[Tuple[str, int]]] = None, accumulated_size: int = 0, max_total_size: int = -1) -> str` - Recursively resolves all embeds in a string with depth and size limits
+
+**Constants/Variables:**
+- `EMBED_DELIMITER_OPEN: str` - Opening delimiter (`«`)
+- `EMBED_DELIMITER_CLOSE: str` - Closing delimiter (`»`)
+- `EMBED_TYPE_SEPARATOR: str` - Type/expression separator (`:`)
+- `EMBED_FORMAT_SEPARATOR: str` - Format specifier separator (`|`)
+- `EMBED_CHAIN_DELIMITER: str` - Modifier chain separator (`>>>`)
+- `EMBED_REGEX: re.Pattern` - Compiled regex for finding embeds
+- `EARLY_EMBED_TYPES: Set[str]` - Types resolved in initial pass
+- `LATE_EMBED_TYPES: Set[str]` - Types resolved in subsequent pass
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.common.utils.embeds import resolve_embeds_recursively_in_string, evaluate_embed, EMBED_REGEX
+
+# Basic embed resolution
+context = {
+    "artifact_service": my_artifact_service,
+    "session_context": {"app_name": "myapp", "user_id": "user123", "session_id": "sess456"}
+}
+
+text = "The result is «math:10 * 1.15 | .2f» and ID is «uuid:new»"
+resolved = await resolve_embeds_recursively_in_string(
+    text=text,
+    context=context,
+    resolver_func=evaluate_embed,
+    types_to_resolve={"math", "uuid"},
+    log_identifier="[MyApp]",
+    config={},
+    max_depth=5
+)
+```
+
+### constants.py
+**Purpose:** Defines all static constants governing embed syntax and classification.
+
+**Import:** `from solace_agent_mesh.common.utils.embeds.constants import EMBED_REGEX, EARLY_EMBED_TYPES`
+
+**Constants/Variables:**
+- `EMBED_DELIMITER_OPEN: str` - Opening delimiter (`«`)
+- `EMBED_DELIMITER_CLOSE: str` - Closing delimiter (`»`)
+- `EMBED_TYPE_SEPARATOR: str` - Type/expression separator (`:`)
+- `EMBED_FORMAT_SEPARATOR: str` - Format specifier separator (`|`)
+- `EMBED_CHAIN_DELIMITER: str` - Modifier chain separator (`>>>`)
+- `EMBED_REGEX: re.Pattern` - Compiled regex with capture groups for type, expression, and format
+- `EARLY_EMBED_TYPES: Set[str]` - Simple embed types resolved first (`math`, `datetime`, `uuid`, `artifact_meta`, `status_update`)
+- `LATE_EMBED_TYPES: Set[str]` - Complex embed types resolved later (`artifact_content`)
+- `TEXT_CONTAINER_MIME_TYPES: Set[str]` - MIME types considered text-based
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.common.utils.embeds.constants import EMBED_REGEX
+
+text = "Price: «math:10 * 1.15 | .2f» ID: «uuid:new»"
+for match in EMBED_REGEX.finditer(text):
+    embed_type = match.group(1)      # "math" or "uuid"
+    expression = match.group(2)      # "10 * 1.15 " or "new"
+    format_spec = match.group(3)     # " .2f" or None
+    print(f"Type: {embed_type}, Expr: '{expression}', Format: '{format_spec}'")
+```
+
+### converter.py
+**Purpose:** Provides data conversion between different formats and serialization to final string representations.
+
+**Import:** `from solace_agent_mesh.common.utils.embeds.converter import convert_data, serialize_data`
+
+**Functions:**
+- `convert_data(current_data: Any, current_format: Optional[DataFormat], target_format: DataFormat, log_id: str = "[Converter]", original_mime_type: Optional[str] = None) -> Tuple[Any, DataFormat, Optional[str]]` - Converts data between DataFormat types using MIME type hints
+- `serialize_data(data: Any, data_format: Optional[DataFormat], target_string_format: Optional[str], original_mime_type: Optional[str], log_id: str = "[Serializer]") -> Tuple[str, Optional[str]]` - Serializes data to final string format (text, json, csv, datauri, or Python format specs)
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.common.utils.embeds.converter import convert_data, serialize_data
+from solace_agent_mesh.common.utils.embeds.types import DataFormat
+
+# Convert CSV bytes to list of dictionaries
+csv_bytes = b"id,name\n1,Alice\n2,Bob"
+list_data, new_format, err = convert_data(
+    current_data=csv_bytes,
+    current_format=DataFormat.BYTES,
+    target_format=DataFormat.LIST_OF_DICTS,
+    original_mime_type="text/csv"
+)
+
+# Serialize to pretty JSON
+json_str, err = serialize_data(
+    data=list_data,
+    data_format=DataFormat.LIST_OF_DICTS,
+    target_string_format="json_pretty",
+    original_mime_type=None
+)
+```
+
+### evaluators.py
+**Purpose:** Contains evaluation logic for simple embed types and the evaluator registry.
+
+**Import:** `from solace_agent_mesh.common.utils.embeds.evaluators import EMBED_EVALUATORS`
+
+**Functions:**
+- `_evaluate_math_embed(expression: str, context: Any, log_identifier: str, format_spec: Optional[str] = None) -> Tuple[str, Optional[str], int]` - Evaluates mathematical expressions using asteval
+- `_evaluate_datetime_embed(expression: str, context: Any, log_identifier: str, format_spec: Optional[str] = None) -> Tuple[str, Optional[str], int]` - Formats current datetime
+- `_evaluate_uuid_embed(expression: str, context: Any, log_identifier: str, format_spec: Optional[str] = None) -> Tuple[str, Optional[str], int]` - Generates UUID4 strings
+- `_evaluate_artifact_meta_embed(expression: str, context: Dict[str, Any], log_identifier: str, format_spec: Optional[str] = None) -> Tuple[str, Optional[str], int]` - Loads and formats artifact metadata
+- `_evaluate_artifact_content_embed(expression: str, context: Any, log_identifier: str, config: Optional[Dict] = None) -> Tuple[Optional[bytes], Optional[str], Optional[str]]` - Loads raw artifact content
+
+**Constants/Variables:**
+- `EMBED_EVALUATORS: Dict[str, Callable]` - Registry mapping embed types to evaluator functions
+- `MATH_SAFE_SYMBOLS: Dict[str, Any]` - Safe mathematical functions and constants for math embeds
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.common.utils.embeds.evaluators import EMBED_EVALUATORS
+
+# Math evaluation
+result, error, size = EMBED_EVALUATORS["math"]("2 + 3 * 4", {}, "[Test]", ".2f")
+# result: "14.00", error: None, size: 5
+
+# DateTime formatting  
+result, error, size = EMBED_EVALUATORS["datetime"]("%Y-%m-%d", {}, "[Test]")
+# result: "2024-01-15", error: None, size: 10
+```
+
+### modifiers.py
+**Purpose:** Implements data transformation functions that can be chained together in artifact_content embeds.
+
+**Import:** `from solace_agent_mesh.common.utils.embeds.modifiers import MODIFIER_DEFINITIONS, _parse_modifier_chain`
+
+**Functions:**
+- `_apply_jsonpath(current_data: Any, expression: str, mime_type: Optional[str], log_id: str) -> Tuple[Any, Optional[str], Optional[str]]` - Applies JSONPath expressions to JSON data
+- `_apply_select_cols(current_data: List[Dict], cols_str: str, mime_type: Optional[str], log_id: str) -> Tuple[Any, Optional[str], Optional[str]]` - Selects specific columns from tabular data
+- `_apply_filter_rows_eq(current_data: List[Dict], filter_spec: str, mime_type: Optional[str], log_id: str) -> Tuple[Any, Optional[str], Optional[str]]` - Filters rows by column value equality
+- `_apply_slice_rows(current_data: List[Dict], slice_spec: str, mime_type: Optional[str], log_id: str) -> Tuple[Any, Optional[str], Optional[str]]` - Slices rows using Python slice notation
+- `_apply_slice_lines(current_data: str, slice_spec: str, mime_type: Optional[str], log_id: str) -> Tuple[Any, Optional[str], Optional[str]]` - Slices text lines
+- `_apply_grep(current_data: str, pattern: str, mime_type: Optional[str], log_id: str) -> Tuple[Any, Optional[str], Optional[str]]` - Filters lines matching regex pattern
+- `_apply_head(current_data: str, n_str: str, mime_type: Optional[str], log_id: str) -> Tuple[Any, Optional[str], Optional[str]]` - Returns first N lines
+- `_apply_tail(current_data: str, n_str: str, mime_type: Optional[str], log_id: str) -> Tuple[Any, Optional[str], Optional[str]]` - Returns last N lines
+- `_apply_template(current_data: Any, template_spec: str, mime_type: Optional[str], log_id: str, context: Any) -> Tuple[Any, Optional[str], Optional[str]]` - Applies Mustache templates from artifacts
+- `_parse_modifier_chain(expression: str) -> Tuple[str, List[Tuple[str, str]], Optional[str]]` - Parses artifact_content expression into components
+
+**Constants/Variables:**
+- `MODIFIER_IMPLEMENTATIONS: Dict[str, Callable]` - Registry of modifier functions
+- `MODIFIER_DEFINITIONS: Dict[str, Dict[str, Any]]` - Modifier metadata including accepted/produced formats
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.common.utils.embeds.modifiers import _parse_modifier_chain
+
+# Parse a complex artifact_content expression
+expression = "data.csv:1 >>> select_cols:name,age >>> filter_rows_eq:age:25 >>> format:json"
+artifact_spec, modifiers, output_format = _parse_modifier_chain(expression)
+# artifact_spec: "data.csv:1"
+# modifiers: [("select_cols", "name,age"), ("filter_rows_eq", "age:25")]
+# output_format: "json"
+```
+
+### resolver.py
+**Purpose:** Core orchestration engine that handles the complete embed resolution process including modifier chains and recursion.
+
+**Import:** `from solace_agent_mesh.common.utils.embeds.resolver import resolve_embeds_in_string, evaluate_embed`
+
+**Functions:**
+- `resolve_embeds_in_string(text: str, context: Any, resolver_func: Callable, types_to_resolve: Set[str], log_identifier: str = "[EmbedUtil]", config: Optional[Dict[str, Any]] = None) -> Tuple[str, int, List[Tuple[int, Any]]]` - Single-pass embed resolution with buffering support
+- `resolve_embeds_recursively_in_string(text: str, context: Any, resolver_func: Callable, types_to_resolve: Set[str], log_identifier: str, config: Optional[Dict], max_depth: int, current_depth: int = 0, visited_artifacts: Optional[Set[Tuple[str, int]]] = None, accumulated_size: int = 0, max_total_size: int = -1) -> str` - Recursive embed resolution with safety limits
+- `evaluate_embed(embed_type: str, expression: str, format_spec: Optional[str], context: Dict[str, Any], log_identifier: str, config: Optional[Dict] = None, current_depth: int = 0, visited_artifacts: Optional[Set[Tuple[str, int]]] = None) -> Union[Tuple[str, Optional[str], int], Tuple[None, str, Any]]` - Main embed evaluation dispatcher
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.common.utils.embeds.resolver import resolve_embeds_in_string, evaluate_embed
+
+# Single-pass resolution
+text = "Result: «math:2+3» and «uuid:new»"
+context = {"artifact_service": service, "session_context": session_ctx}
+
+resolved_text, processed_index, signals = await resolve_embeds_in_string(
+    text=text,
+    context=context,
+    resolver_func=evaluate_embed,
+    types_to_resolve={"math", "uuid"},
+    log_identifier="[MyApp]",
+    config={}
+)
+
+# Complex artifact content with modifiers
+result, error, size = await evaluate_embed(
+    embed_type="artifact_content",
+    expression="sales.csv >>> select_cols:product,revenue >>> format:json",
+    format_spec=None,
+    context=context,
+    log_identifier="[Sales]"
+)
+```
+
+### types.py
+
+# content_hash: b2c6bea4995d4d68f8cad84016e236560d091897ba1b8502f1532bf84eb813f7