solace-agent-mesh 0.2.3__py3-none-any.whl → 1.0.1__py3-none-any.whl

solace_agent_mesh/common/utils/embeds/resolver.py

@@ -0,0 +1,865 @@
+"""
+Contains the main embed resolution functions, including the chain executor.
+"""
+
+import asyncio
+import json
+from solace_ai_connector.common.log import log
+from typing import Any, Callable, Dict, Optional, Set, Tuple, List, Union
+from .constants import (
+    EMBED_REGEX,
+    EMBED_DELIMITER_OPEN,
+    EMBED_DELIMITER_CLOSE,
+    EARLY_EMBED_TYPES,
+    LATE_EMBED_TYPES,
+)
+from .evaluators import EMBED_EVALUATORS, _evaluate_artifact_content_embed
+from .modifiers import MODIFIER_DEFINITIONS, _parse_modifier_chain
+from .converter import (
+    convert_data,
+    serialize_data,
+    _parse_string_to_list_of_dicts,
+)
+from .types import DataFormat
+from ..mime_helpers import is_text_based_mime_type
+
+try:
+    import yaml
+    from .converter import PYYAML_AVAILABLE
+except ImportError:
+    PYYAML_AVAILABLE = False
+
+
+def _log_data_state(
+    log_id: str,
+    step: str,
+    data: Any,
+    data_format: Optional[DataFormat],
+    mime_type: Optional[str],
+):
+    """Logs the state of the data at a specific step."""
+    data_type = type(data).__name__
+    data_size = "N/A"
+    data_preview = "N/A"
+
+    if isinstance(data, (bytes, str, list)):
+        data_size = str(len(data))
+    elif isinstance(data, dict):
+        data_size = f"{len(data)} keys"
+
+    if isinstance(data, bytes):
+        try:
+            data_preview = data[:100].decode("utf-8", errors="replace") + (
+                "..." if len(data) > 100 else ""
+            )
+        except Exception:
+            data_preview = f"Bytes[{len(data)}]"
+    elif isinstance(data, str):
+        data_preview = data[:100] + ("..." if len(data) > 100 else "")
+    elif isinstance(data, list):
+        data_preview = f"List[{len(data)} items]"
+        if data and isinstance(data[0], dict):
+            data_preview += f" (First item keys: {list(data[0].keys())[:5]}{'...' if len(data[0].keys()) > 5 else ''})"
+    elif isinstance(data, dict):
+        data_preview = f"Dict[{len(data)} keys: {list(data.keys())[:5]}{'...' if len(data.keys()) > 5 else ''}]"
+    else:
+        data_preview = str(data)[:100] + ("..." if len(str(data)) > 100 else "")
+
+    log.info(
+        "%s [%s] Format: %s, MimeType: %s, Type: %s, Size: %s, Preview: '%s'",
+        log_id,
+        step,
+        data_format.name if data_format else "None",
+        mime_type,
+        data_type,
+        data_size,
+        data_preview,
+    )
+
+
+async def _evaluate_artifact_content_embed_with_chain(
+    artifact_spec_from_directive: str,
+    modifiers_from_directive: List[Tuple[str, str]],
+    output_format_from_directive: Optional[str],
+    context: Any,
+    log_identifier: str,
+    config: Optional[Dict] = None,
+    current_depth: int = 0,
+    visited_artifacts: Optional[Set[Tuple[str, int]]] = None,
+) -> Tuple[str, Optional[str], int]:
+    """
+    Loads artifact content, recursively resolves its internal embeds if text-based,
+    applies a chain of modifiers, and serializes the final result.
+    """
+    log.info(
+        "%s [Depth:%d] Starting chain execution for artifact directive: %s",
+        log_identifier,
+        current_depth,
+        artifact_spec_from_directive,
+    )
+    visited_artifacts = visited_artifacts or set()
+    parsed_artifact_spec = artifact_spec_from_directive
+
+    loaded_content_bytes, original_mime_type, load_error = (
+        await _evaluate_artifact_content_embed(
+            parsed_artifact_spec, context, log_identifier, config
+        )
+    )
+
+    if load_error:
+        log.warning(
+            "%s [Depth:%d] Error loading initial artifact '%s': %s",
+            log_identifier,
+            current_depth,
+            parsed_artifact_spec,
+            load_error,
+        )
+        err_str = f"[Error loading artifact '{parsed_artifact_spec}': {load_error}]"
+        return err_str, load_error, len(err_str.encode("utf-8"))
+
+    if loaded_content_bytes is None:
+        err_msg = f"Internal error - Artifact load for '{parsed_artifact_spec}' returned None content without error."
+        log.error("%s %s", log_identifier, err_msg)
+        return f"[Error: {err_msg}]", err_msg, 0
+
+    current_data: Any = loaded_content_bytes
+    current_format: DataFormat = DataFormat.BYTES
+    _log_data_state(
+        log_identifier,
+        f"[Depth:{current_depth}] Initial Load",
+        current_data,
+        current_format,
+        original_mime_type,
+    )
+    if is_text_based_mime_type(original_mime_type):
+        try:
+            decoded_content = loaded_content_bytes.decode("utf-8")
+            log.debug(
+                "%s [Depth:%d] Artifact '%s' is text-based (%s). Attempting recursive embed resolution.",
+                log_identifier,
+                current_depth,
+                parsed_artifact_spec,
+                original_mime_type,
+            )
+            spec_parts = parsed_artifact_spec.split(":", 1)
+            filename_for_key = spec_parts[0]
+            version_str_for_key = spec_parts[1] if len(spec_parts) > 1 else None
+            try:
+                version_for_key = (
+                    int(version_str_for_key) if version_str_for_key else -1
+                )
+            except ValueError:
+                log.warning(
+                    "%s Could not parse version from '%s' for visited_artifacts key. Loop detection might be affected.",
+                    log_identifier,
+                    parsed_artifact_spec,
+                )
+                version_for_key = -1
+
+            artifact_key = (filename_for_key, version_for_key)
+            new_visited_artifacts = visited_artifacts.copy()
+            new_visited_artifacts.add(artifact_key)
+
+            resolved_string_content = await resolve_embeds_recursively_in_string(
+                text=decoded_content,
+                context=context,
+                resolver_func=evaluate_embed,
+                types_to_resolve=EARLY_EMBED_TYPES.union(LATE_EMBED_TYPES),
+                log_identifier=log_identifier,
+                config=config,
+                max_depth=config.get("gateway_recursive_embed_depth", 12),
+                current_depth=current_depth + 1,
+                visited_artifacts=new_visited_artifacts,
+                accumulated_size=0,
+                max_total_size=config.get(
+                    "gateway_max_artifact_resolve_size_bytes", -1
+                ),
+            )
+            current_data = resolved_string_content
+            current_format = DataFormat.STRING
+            _log_data_state(
+                log_identifier,
+                f"[Depth:{current_depth}] After Recursive Resolution",
+                current_data,
+                current_format,
+                original_mime_type,
+            )
+
+        except UnicodeDecodeError as ude:
+            err_msg = f"Failed to decode text-based artifact '{parsed_artifact_spec}' for recursion: {ude}"
+            log.warning("%s %s", log_identifier, err_msg)
+            return f"[Error: {err_msg}]", err_msg, 0
+        except Exception as recurse_err:
+            err_msg = f"Error during recursive resolution of '{parsed_artifact_spec}': {recurse_err}"
+            log.exception("%s %s", log_identifier, err_msg)
+            return f"[Error: {err_msg}]", err_msg, 0
+    else:
+        log.debug(
+            "%s [Depth:%d] Artifact '%s' is not text-based (%s). Passing raw bytes to modifier chain.",
+            log_identifier,
+            current_depth,
+            parsed_artifact_spec,
+            original_mime_type,
+        )
+
+    if current_format == DataFormat.STRING and original_mime_type:
+        normalized_mime_type = original_mime_type.lower()
+        log.debug(
+            "%s [Depth:%d] Pre-parsing string content with MIME type: %s",
+            log_identifier,
+            current_depth,
+            normalized_mime_type,
+        )
+        if "json" in normalized_mime_type:
+            try:
+                current_data = json.loads(current_data)
+                current_format = DataFormat.JSON_OBJECT
+                log.info(
+                    "%s [Depth:%d] Pre-parsed string as JSON_OBJECT.",
+                    log_identifier,
+                    current_depth,
+                )
+            except json.JSONDecodeError:
+                log.warning(
+                    "%s [Depth:%d] Failed to pre-parse as JSON despite MIME type '%s'. Content will be treated as STRING.",
+                    log_identifier,
+                    current_depth,
+                    original_mime_type,
+                )
+        elif "yaml" in normalized_mime_type or "yml" in normalized_mime_type:
+            if PYYAML_AVAILABLE:
+                try:
+                    current_data = yaml.safe_load(current_data)
+                    current_format = DataFormat.JSON_OBJECT
+                    log.info(
+                        "%s [Depth:%d] Pre-parsed string as YAML (now JSON_OBJECT).",
+                        log_identifier,
+                        current_depth,
+                    )
+                except yaml.YAMLError:
+                    log.warning(
+                        "%s [Depth:%d] Failed to pre-parse as YAML despite MIME type '%s'. Content will be treated as STRING.",
+                        log_identifier,
+                        current_depth,
+                        original_mime_type,
+                    )
+            else:
+                log.warning(
+                    "%s [Depth:%d] Skipping YAML pre-parsing for MIME type '%s' because PyYAML is not installed.",
+                    log_identifier,
+                    current_depth,
+                    original_mime_type,
+                )
+        elif "csv" in normalized_mime_type:
+            parsed_data, error_msg = _parse_string_to_list_of_dicts(
+                current_data, original_mime_type, log_identifier
+            )
+            if error_msg is None and parsed_data is not None:
+                current_data = parsed_data
+                current_format = DataFormat.LIST_OF_DICTS
+                log.info(
+                    "%s [Depth:%d] Pre-parsed string as LIST_OF_DICTS from CSV.",
+                    log_identifier,
+                    current_depth,
+                )
+            else:
+                log.warning(
+                    "%s [Depth:%d] Failed to pre-parse as CSV despite MIME type '%s': %s. Content will be treated as STRING.",
+                    log_identifier,
+                    current_depth,
+                    original_mime_type,
+                    error_msg,
+                )
+
+        _log_data_state(
+            log_identifier,
+            f"[Depth:{current_depth}] After Pre-parsing",
+            current_data,
+            current_format,
+            original_mime_type,
+        )
+
+    modifier_index = 0
+    for prefix, value in modifiers_from_directive:
+        modifier_index += 1
+        modifier_step_id = f"Modifier {modifier_index} ({prefix})"
+
+        modifier_def = MODIFIER_DEFINITIONS.get(prefix)
+        if not modifier_def:
+            err_msg = f"Unknown modifier prefix: '{prefix}'"
+            log.warning("%s %s", log_identifier, err_msg)
+            return f"[Error: {err_msg}]", err_msg, 0
+
+        modifier_func = modifier_def["function"]
+        accepts_formats: List[DataFormat] = modifier_def["accepts"]
+        produces_format: DataFormat = modifier_def["produces"]
+
+        log.info(
+            "%s [Depth:%d][%s] Applying modifier: %s:%s (Accepts: %s, Produces: %s)",
+            log_identifier,
+            current_depth,
+            modifier_step_id,
+            prefix,
+            value[:50] + "...",
+            [f.name for f in accepts_formats],
+            produces_format.name,
+        )
+
+        if current_format not in accepts_formats:
+            target_format_for_modifier = accepts_formats[0]
+            log.info(
+                "%s [Depth:%d][%s] Current format %s not accepted by %s. Converting to %s...",
+                log_identifier,
+                current_depth,
+                modifier_step_id,
+                current_format.name,
+                prefix,
+                target_format_for_modifier.name,
+            )
+            _log_data_state(
+                log_identifier,
+                f"[Depth:{current_depth}] {modifier_step_id} - Before Conversion",
+                current_data,
+                current_format,
+                original_mime_type,
+            )
+            converted_data, new_format, convert_error = convert_data(
+                current_data,
+                current_format,
+                target_format_for_modifier,
+                log_identifier,
+                original_mime_type,
+            )
+            if convert_error:
+                err_msg = (
+                    f"Failed to convert data for modifier '{prefix}': {convert_error}"
+                )
+                log.warning("%s %s", log_identifier, err_msg)
+                return f"[Error: {err_msg}]", err_msg, 0
+            current_data = converted_data
+            current_format = new_format
+            log.info(
+                "%s [Depth:%d][%s] Conversion successful. New format: %s",
+                log_identifier,
+                current_depth,
+                modifier_step_id,
+                current_format.name,
+            )
+            _log_data_state(
+                log_identifier,
+                f"[Depth:{current_depth}] {modifier_step_id} - After Conversion",
+                current_data,
+                current_format,
+                original_mime_type,
+            )
+
+        try:
+            _log_data_state(
+                log_identifier,
+                f"[Depth:{current_depth}] {modifier_step_id} - Before Execution",
+                current_data,
+                current_format,
+                original_mime_type,
+            )
+            if prefix == "apply_to_template":
+                result_data, _, exec_error = await modifier_func(
+                    current_data, value, original_mime_type, log_identifier, context
+                )
+            else:
+                if asyncio.iscoroutinefunction(modifier_func):
+                    result_data, _, exec_error = await modifier_func(
+                        current_data, value, original_mime_type, log_identifier
+                    )
+                else:
+                    result_data, _, exec_error = modifier_func(
+                        current_data, value, original_mime_type, log_identifier
+                    )
+
+            if exec_error:
+                err_msg = f"Error applying modifier '{prefix}': {exec_error}"
+                log.warning("%s %s", log_identifier, err_msg)
+                return f"[Error: {err_msg}]", err_msg, 0
+
+            current_data = result_data
+            current_format = produces_format
+            log.info(
+                "%s [Depth:%d][%s] Modifier '%s' executed. Result format: %s",
+                log_identifier,
+                current_depth,
+                modifier_step_id,
+                prefix,
+                current_format.name,
+            )
+            _log_data_state(
+                log_identifier,
+                f"[Depth:{current_depth}] {modifier_step_id} - After Execution",
+                current_data,
+                current_format,
+                original_mime_type,
+            )
+            if current_data is None or (
+                isinstance(current_data, (list, str, bytes)) and not current_data
+            ):
+                log.info(
+                    "%s [Depth:%d][%s] Modifier '%s' resulted in empty data.",
+                    log_identifier,
+                    current_depth,
+                    modifier_step_id,
+                    prefix,
+                )
+
+        except Exception as mod_err:
+            log.exception(
+                "%s [Depth:%d][%s] Unexpected error executing modifier '%s': %s",
+                log_identifier,
+                current_depth,
+                modifier_step_id,
+                prefix,
+                mod_err,
+            )
+            err_msg = f"Unexpected error in modifier '{prefix}': {mod_err}"
+            return f"[Error: {err_msg}]", err_msg, 0
+
+    target_string_format = output_format_from_directive
+    if target_string_format is None:
+        log.warning(
+            "%s [Depth:%d] Missing final 'format:' step in chain. Defaulting to 'text'.",
+            log_identifier,
+            current_depth,
+        )
+        target_string_format = "text"
+
+    log.info(
+        "%s [Depth:%d] [Final Serialization] Serializing final data (Format: %s) to target string format '%s'",
+        log_identifier,
+        current_depth,
+        current_format.name,
+        target_string_format,
+    )
+    _log_data_state(
+        log_identifier,
+        f"[Depth:{current_depth}] Before Serialization",
+        current_data,
+        current_format,
+        original_mime_type,
+    )
+
+    final_serialized_string, serialize_error = serialize_data(
+        data=current_data,
+        data_format=current_format,
+        target_string_format=target_string_format,
+        original_mime_type=original_mime_type,
+        log_id=log_identifier,
+    )
+
+    if serialize_error:
+        log.warning("%s [Depth:%d] %s", log_identifier, current_depth, serialize_error)
+        return (
+            final_serialized_string,
+            serialize_error,
+            len(final_serialized_string.encode("utf-8")),
+        )
+
+    final_size = len(final_serialized_string.encode("utf-8"))
+    log.info(
+        "%s [Depth:%d] Chain execution completed successfully. Final size: %d bytes.",
+        log_identifier,
+        current_depth,
+        final_size,
+    )
+    log.info(
+        "%s [Depth:%d] [Final Serialization] Result: '%s...'",
+        log_identifier,
+        current_depth,
+        final_serialized_string[:100]
+        + ("..." if len(final_serialized_string) > 100 else ""),
+    )
+    return final_serialized_string, None, final_size
+
+
+async def resolve_embeds_in_string(
+    text: str,
+    context: Any,
+    resolver_func: Callable[
+        ..., Union[Tuple[str, Optional[str], int], Tuple[None, str, Any]]
+    ],
+    types_to_resolve: Set[str],
+    log_identifier: str = "[EmbedUtil]",
+    config: Optional[Dict[str, Any]] = None,
+) -> Tuple[str, int, List[Tuple[int, Any]]]:
+    """
+    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.
+    It does NOT perform recursion itself but calls `evaluate_embed` which might trigger recursion.
+
+    Processes the string iteratively, resolving one embed at a time.
+    Includes buffering logic: stops processing if a partial embed delimiter is found
+    at the end, returning the processed part and the index where processing stopped.
+    Can now return special signals from the resolver function.
+
+    Args:
+        text: The input string potentially containing embeds.
+        context: The context object passed to the resolver function (now a Dict).
+        resolver_func: The function to call for evaluating each embed.
+                       Signature: (type, expression, format, context, log_id, config, ...) -> Any
+                       Can return a string for replacement, or a tuple like (None, "SIGNAL_TYPE", data)
+                       to indicate a signal instead of text replacement.
+        types_to_resolve: A set of embed types (strings) to resolve in this pass.
+        log_identifier: Identifier for logging.
+        config: Optional configuration dictionary passed to the resolver.
+
+    Returns:
+        A tuple containing:
+        - The string with specified embeds resolved (or removed if signaled).
+        - The index in the *original* string representing the end of the
+          successfully processed portion (useful for buffering). This will be
+          len(text) if the whole string was processed.
+        - A list of signals encountered during resolution, as tuples (index, signal_data).
+          The index corresponds to the start index of the embed directive in the original string.
+    """
+    resolved_parts = []
+    signals_found: List[Tuple[int, Any]] = []
+    last_end = 0
+    original_length = len(text)
+
+    log.debug(
+        "%s Checking for embeds in text: '%s'", log_identifier, text[:200] + "..."
+    )
+
+    for match in EMBED_REGEX.finditer(text):
+        start, end = match.span()
+        embed_type = match.group(1)
+        expression = match.group(2)
+        format_spec = match.group(3)
+
+        resolved_parts.append(text[last_end:start])
+
+        if embed_type in types_to_resolve:
+            log.info(
+                "%s Found embed type '%s' to resolve: expr='%s', fmt='%s'",
+                log_identifier,
+                embed_type,
+                expression,
+                format_spec,
+            )
+            resolved_value = await resolver_func(
+                embed_type,
+                expression,
+                format_spec,
+                context,
+                log_identifier,
+                config,
+            )
+
+            if (
+                isinstance(resolved_value, tuple)
+                and len(resolved_value) == 3
+                and resolved_value[0] is None
+                and isinstance(resolved_value[1], str)
+            ):
+                signal_type = resolved_value[1]
+                log.info(
+                    "%s Received signal '%s' from resolver for embed at index %d.",
+                    log_identifier,
+                    signal_type,
+                    start,
+                )
+                signals_found.append(
+                    (
+                        start,
+                        resolved_value,
+                    )
+                )
+            elif (
+                isinstance(resolved_value, tuple)
+                and len(resolved_value) == 3
+                and isinstance(resolved_value[0], str)
+                and isinstance(resolved_value[2], int)
+            ):
+                text_content, error_message, _ = resolved_value
+                if error_message:
+                    log.warning(
+                        "%s Embed resolution for '%s:%s' resulted in error: %s. Using error string as content.",
+                        log_identifier,
+                        embed_type,
+                        expression,
+                        error_message,
+                    )
+                resolved_parts.append(text_content)
+            else:
+                log.warning(
+                    "%s Resolver for type '%s' returned unexpected structure %s. Treating as error string.",
+                    log_identifier,
+                    embed_type,
+                    type(resolved_value),
+                )
+
+        else:
+            log.debug(
+                "%s Skipping embed type '%s' (not in types_to_resolve)",
+                log_identifier,
+                embed_type,
+            )
+            resolved_parts.append(match.group(0))
+
+        last_end = end
+
+    remaining_text = text[last_end:]
+    resolved_parts.append(remaining_text)
+
+    potential_partial_embed = False
+    partial_embed_start_index = -1
+
+    last_open_delimiter_index = remaining_text.rfind(EMBED_DELIMITER_OPEN)
+
+    if last_open_delimiter_index != -1:
+        closing_delimiter_index = remaining_text.find(
+            EMBED_DELIMITER_CLOSE, last_open_delimiter_index
+        )
+        if closing_delimiter_index == -1:
+            potential_partial_embed = True
+            partial_embed_start_index = last_open_delimiter_index
+            log.debug(
+                "%s Potential unclosed embed detected starting at index %d within remaining text: '%s...'",
+                log_identifier,
+                partial_embed_start_index,
+                remaining_text[
+                    partial_embed_start_index : partial_embed_start_index + 10
+                ],
+            )
+
+    if potential_partial_embed:
+        processed_until_index = last_end + partial_embed_start_index
+        final_text = (
+            "".join(resolved_parts[:-1]) + remaining_text[:partial_embed_start_index]
+        )
+        log.debug(
+            "%s Returning processed text up to index %d due to potential partial embed.",
+            log_identifier,
+            processed_until_index,
+        )
+    else:
+        final_text = "".join(resolved_parts)
+        processed_until_index = original_length
+        log.debug(
+            "%s Returning fully processed text (length %d).",
+            log_identifier,
+            len(final_text),
+        )
+
+    return final_text, processed_until_index, signals_found
+
+
+async def resolve_embeds_recursively_in_string(
+    text: str,
+    context: Any,
+    resolver_func: Callable[..., Tuple[str, Optional[str], int]],
+    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 specified embed types within a string, respecting depth,
+    loop detection (via visited_artifacts passed down), and accumulated size limits.
+    """
+    if current_depth >= max_depth:
+        log.warning(
+            "%s Max embed recursion depth (%d) reached for current processing string.",
+            log_identifier,
+            max_depth,
+        )
+        return "[Error: Max embed depth exceeded]"
+
+    visited_artifacts = visited_artifacts or set()
+    resolved_parts = []
+    last_end = 0
+
+    for match in EMBED_REGEX.finditer(text):
+        start, end = match.span()
+        embed_type = match.group(1)
+        expression = match.group(2)
+        format_spec = match.group(3)
+
+        resolved_parts.append(text[last_end:start])
+
+        if embed_type not in types_to_resolve:
+            resolved_parts.append(match.group(0))
+            last_end = end
+            continue
+
+        log.debug(
+            "%s [Depth:%d] Found embed '%s' to resolve: expr='%s', fmt='%s'",
+            log_identifier,
+            current_depth,
+            embed_type,
+            expression,
+            format_spec,
+        )
+
+        resolved_value = await resolver_func(
+            embed_type,
+            expression,
+            format_spec,
+            context,
+            log_identifier,
+            config,
+            current_depth,
+            visited_artifacts,
+        )
+
+        if (
+            isinstance(resolved_value, tuple)
+            and len(resolved_value) == 3
+            and isinstance(resolved_value[0], str)
+            and isinstance(resolved_value[2], int)
+        ):
+            resolved_string_for_embed, error_msg_from_chain, size_of_this_embed = (
+                resolved_value
+            )
+        else:
+            log.error(
+                "%s [Depth:%d] Recursive call to resolver for '%s:%s' returned unexpected signal or format. Treating as error.",
+                log_identifier,
+                current_depth,
+                embed_type,
+                expression,
+            )
+            error_msg_from_chain = "Recursive resolution returned unexpected signal."
+            resolved_string_for_embed = f"[Error: {error_msg_from_chain}]"
+            size_of_this_embed = len(resolved_string_for_embed.encode("utf-8"))
+
+        if error_msg_from_chain:
+            log.warning(
+                "%s [Depth:%d] Embed '%s:%s' resulted in error from chain: %s",
+                log_identifier,
+                current_depth,
+                embed_type,
+                expression,
+                error_msg_from_chain,
+            )
+            resolved_parts.append(resolved_string_for_embed)
+        else:
+            if (
+                max_total_size >= 0
+                and accumulated_size + size_of_this_embed > max_total_size
+            ):
+                error_str = f"[Error: Embedding '{expression}' exceeds total size limit for parent content ({accumulated_size + size_of_this_embed} > {max_total_size})]"
+                log.warning("%s %s", log_identifier, error_str)
+                resolved_parts.append(error_str)
+            else:
+                resolved_parts.append(resolved_string_for_embed)
+                accumulated_size += size_of_this_embed
+                log.debug(
+                    "%s [Depth:%d] Appended resolved embed (size: %d). Current accumulated_size: %d",
+                    log_identifier,
+                    current_depth,
+                    size_of_this_embed,
+                    accumulated_size,
+                )
+
+        last_end = end
+
+    resolved_parts.append(text[last_end:])
+    return "".join(resolved_parts)
+
+
+async def 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 embed directive.
+    For 'artifact_content', it handles the modifier chain and potential internal recursion.
+    For other types, it evaluates directly and returns a 3-tuple (text, error, size).
+    For 'status_update', it returns a signal tuple (None, "SIGNAL_STATUS_UPDATE", data).
+
+    Args:
+        embed_type: The type of the embed.
+        expression: The expression part of the embed.
+        format_spec: The optional format specifier.
+        context: The dictionary-based context (containing artifact_service, session_context, config).
+        log_identifier: Identifier for logging.
+        config: Optional configuration dictionary (now part of context or passed if needed by evaluators).
+        current_depth: Current recursion depth (for artifact_content).
+        visited_artifacts: Set of visited artifacts (for artifact_content).
+
+    Returns:
+        A 3-tuple (text_content, error_message, size) or a signal tuple (None, signal_type, data).
+    """
+    log.debug(
+        "%s Evaluating embed: type='%s', expr='%s', fmt='%s'",
+        log_identifier,
+        embed_type,
+        expression[:50] + "...",
+        format_spec,
+    )
+
+    if embed_type == "status_update":
+        status_text = expression.strip()
+        log.info("%s Detected 'status_update' embed. Signaling.", log_identifier)
+        return (None, "SIGNAL_STATUS_UPDATE", status_text)
+
+    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:
+            log.warning(
+                "%s Using format specifier '| %s' for artifact_content as chain format step was missing.",
+                log_identifier,
+                format_spec,
+            )
+            output_format = format_spec
+
+        final_string, error, size = 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,
+            config=config,
+            current_depth=current_depth,
+            visited_artifacts=visited_artifacts or set(),
+        )
+        return final_string, error, size
+
+    else:
+        evaluator = EMBED_EVALUATORS.get(embed_type)
+        if not evaluator:
+            err_msg = f"Unknown embed type: '{embed_type}'"
+            log.warning("%s %s", log_identifier, err_msg)
+            err_str = f"[Error: {err_msg}]"
+            return err_str, err_msg, len(err_str.encode("utf-8"))
+
+        try:
+            if asyncio.iscoroutinefunction(evaluator):
+                str_value, eval_error, size = await evaluator(
+                    expression, context, log_identifier, format_spec
+                )
+            else:
+                str_value, eval_error, size = evaluator(
+                    expression, context, log_identifier, format_spec
+                )
+
+            return str_value, eval_error, size
+
+        except Exception as e:
+            log.exception(
+                "%s Unexpected error evaluating %s embed '%s': %s",
+                log_identifier,
+                embed_type,
+                expression,
+                e,
+            )
+            err_msg = f"Unexpected evaluation error: {e}"
+            err_str = f"[Error: {err_msg}]"
+            return err_str, err_msg, len(err_str.encode("utf-8"))