Here is the developer guide for the `embeds` directory.

## Quick Summary
The `embeds` directory provides a system for finding, parsing, and resolving embedded expressions within strings. These expressions, denoted by `«...»`, can represent dynamic values like mathematical calculations, datetimes, or content from stored artifacts. The system supports multi-step data transformation pipelines on artifact content, recursive embed resolution, and safety features like depth and size limits. It is a core component for dynamic content generation and data processing.

## Files Overview
- `__init__.py`: Exports the primary public functions and constants for easy access.
- `constants.py`: Defines the syntax (delimiters, separators), regular expressions, and type classifications for embeds.
- `converter.py`: Provides functions for converting data between different formats (e.g., bytes, string, JSON) and for serializing data into a final string representation.
- `evaluators.py`: Contains the specific logic for evaluating simple embed types like `math`, `datetime`, and `uuid`.
- `modifiers.py`: Implements a library of data transformation functions (e.g., `jsonpath`, `slice_rows`, `grep`) that can be chained together.
- `resolver.py`: The core engine that orchestrates the entire embed resolution process, including handling modifier chains and recursion.
- `types.py`: Defines the `DataFormat` enum used to track data types during transformations.

## Developer API Reference

### __init__.py
**Purpose:** This module serves as the main public entry point for the `embeds` package, exporting the most commonly used functions and constants from the other modules. Developers should typically import from here.

**Import:** `from src.solace_agent_mesh.common.utils.embeds import resolve_embeds_recursively_in_string, evaluate_embed, EMBED_REGEX`

*(Note: Detailed documentation is available under each source file's section.)*

**Classes:**
- None

**Functions:**
- `evaluate_embed(...)`: Evaluates a single, parsed embed expression.
- `resolve_embeds_in_string(...)`: Resolves embeds in a string for a single pass (non-recursive).
- `resolve_embeds_recursively_in_string(...)`: Recursively finds and resolves all embeds in a string, respecting depth and size limits.

**Constants/Variables:**
- `EMBED_DELIMITER_OPEN: str`: The opening delimiter for an embed (`«`).
- `EMBED_DELIMITER_CLOSE: str`: The closing delimiter for an embed (`»`).
- `EMBED_TYPE_SEPARATOR: str`: The separator between an embed's type and its expression (`:`).
- `EMBED_FORMAT_SEPARATOR: str`: The separator for an optional format specifier (`|`).
- `EMBED_CHAIN_DELIMITER: str`: The separator for modifier steps in an `artifact_content` chain (`>>>`).
- `EMBED_REGEX: re.Pattern`: The compiled regular expression used to find embeds.
- `EARLY_EMBED_TYPES: Set[str]`: A set of embed types that are resolved in an initial pass.
- `LATE_EMBED_TYPES: Set[str]`: A set of embed types (like `artifact_content`) resolved in a subsequent pass.

---
### constants.py
**Purpose:** This file defines all the static constants that govern the syntax and classification of embeds. This includes delimiters, separators, the master regular expression for parsing, and sets that categorize embed types for phased resolution.

**Import:** `from src.solace_agent_mesh.common.utils.embeds.constants import EMBED_REGEX, EARLY_EMBED_TYPES`

**Classes:**
- None

**Functions:**
- None

**Constants/Variables:**
- `EMBED_DELIMITER_OPEN: str`: The character that marks the beginning of an embed (`«`).
- `EMBED_DELIMITER_CLOSE: str`: The character that marks the end of an embed (`»`).
- `EMBED_TYPE_SEPARATOR: str`: The character separating the embed type from its expression (`:`).
- `EMBED_FORMAT_SEPARATOR: str`: The character separating an expression from its optional format specifier (`|`).
- `EMBED_CHAIN_DELIMITER: str`: The string separating transformation steps in an `artifact_content` embed (`>>>`).
- `EMBED_REGEX: re.Pattern`: A compiled regular expression to find and capture the `type`, `expression`, and optional `format` from an embed string.
- `EARLY_EMBED_TYPES: Set[str]`: A set of embed types (`math`, `datetime`, etc.) that are resolved first, as they are generally simple, self-contained, and do not involve recursion.
- `LATE_EMBED_TYPES: Set[str]`: A set of embed types (`artifact_content`) that are resolved later, as they can be complex, involve I/O, and may contain further embeds that require recursive resolution.
- `TEXT_CONTAINER_MIME_TYPES: Set[str]`: A set of MIME types that are considered to contain text and can be safely decoded to a string.

**Usage Examples:**
```python
import re
from src.solace_agent_mesh.common.utils.embeds.constants import EMBED_REGEX

text = "The price is «math:10 * 1.15 | .2f» and the ID is «uuid:new»."

for match in EMBED_REGEX.finditer(text):
    embed_type = match.group(1)
    expression = match.group(2)
    format_spec = match.group(3) # This will be None if not present
    print(f"Type: {embed_type}, Expression: '{expression}', Format: '{format_spec}'")

# Expected Output:
# Type: math, Expression: '10 * 1.15 ', Format: ' .2f'
# Type: uuid, Expression: 'new', Format: 'None'
```

---
### converter.py
**Purpose:** This file provides the core logic for data conversion and serialization. It can transform data between different `DataFormat` representations (e.g., `BYTES` to `STRING`, `STRING` to `LIST_OF_DICTS`) and serialize any format into a final string representation (e.g., `json`, `csv`, `datauri`).

**Import:** `from src.solace_agent_mesh.common.utils.embeds.converter import convert_data, serialize_data`

**Classes:**
- None

**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 from a source format to a target format. It uses `original_mime_type` as a hint for parsing (e.g., knowing that a string is JSON or CSV). Returns a tuple of `(converted_data, resulting_format, error_message)`.
- `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 from any `DataFormat` into a final string. `target_string_format` can be a keyword like `"json"`, `"csv"`, `"datauri"`, or a Python format specifier for numbers (e.g., `".2f"`). Returns a tuple of `(serialized_string, error_message)`.

**Constants/Variables:**
- None

**Usage Examples:**
```python
from src.solace_agent_mesh.common.utils.embeds.converter import convert_data, serialize_data
from src.solace_agent_mesh.common.utils.embeds.types import DataFormat

# Example 1: Convert CSV bytes to a list of dictionaries
csv_bytes = b"id,name\n1,Alice\n2,Bob"
list_of_dicts, new_format, err = convert_data(
    current_data=csv_bytes,
    current_format=DataFormat.BYTES,
    target_format=DataFormat.LIST_OF_DICTS,
    original_mime_type="text/csv"
)
if not err:
    print(f"Converted data: {list_of_dicts}")
    # Converted data: [{'id': '1', 'name': 'Alice'}, {'id': '2', 'name': 'Bob'}]

# Example 2: Serialize the list of dictionaries back to a pretty JSON string
json_string, err = serialize_data(
    data=list_of_dicts,
    data_format=DataFormat.LIST_OF_DICTS,
    target_string_format="json_pretty",
    original_mime_type=None
)
if not err:
    print(f"Serialized JSON:\n{json_string}")