iCode-TUI 0.29.1__py3-none-any.whl

chrys/foundation/i18n/localizer.py

@@ -0,0 +1,187 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Atomic catalog bundles and safe semantic-message rendering."""
+
+from __future__ import annotations
+
+import gettext
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from enum import StrEnum
+from functools import cache
+
+from chrys.foundation.i18n import formatting as _formatting
+from chrys.foundation.i18n.catalogs import CatalogLoadError, CatalogRoot, load_catalog
+from chrys.foundation.i18n.formatting import format_message, has_visible_content, validate_authored_template
+from chrys.foundation.i18n.locale import ENGLISH_LOCALE, normalize_locale
+from chrys.foundation.i18n.messages import MessageRef, _render_arguments
+
+logger = logging.getLogger(__name__)
+
+
+class CatalogWarningCode(StrEnum):
+    """Stable kinds of catalog warning returned to composition roots."""
+
+    LOAD_FAILED = "i18n_catalog_load_failed"
+
+
+@dataclass(frozen=True, slots=True)
+class CatalogLoadWarning:
+    """Typed notice that a requested catalog could not replace English."""
+
+    requested_locale: str
+    code: CatalogWarningCode = field(default=CatalogWarningCode.LOAD_FAILED, init=False)
+
+
+type _TemplateValidator = Callable[[str, bool], frozenset[str] | None]
+
+
+@dataclass(frozen=True, slots=True)
+class _CatalogBundle:
+    locale_name: str
+    translations: gettext.GNUTranslations | None
+    validate_template: _TemplateValidator | None
+
+
+@dataclass(frozen=True, slots=True)
+class _LocalizerState:
+    requested_locale: str
+    bundle: _CatalogBundle
+    first_load_warning: CatalogLoadWarning | None = None
+
+
+_ENGLISH_BUNDLE = _CatalogBundle(
+    locale_name=ENGLISH_LOCALE,
+    translations=None,
+    validate_template=None,
+)
+
+
+class Localizer:
+    """Render ``MessageRef`` values through one atomically replaceable bundle."""
+
+    __slots__ = ("_catalog_root", "_state")
+
+    def __init__(self, requested_locale: str, *, catalog_root: CatalogRoot | None = None) -> None:
+        self._catalog_root = catalog_root
+        self._state = _LocalizerState(requested_locale=requested_locale, bundle=_ENGLISH_BUNDLE)
+
+        effective_locale = normalize_locale(requested_locale)
+        if effective_locale == ENGLISH_LOCALE:
+            return
+        try:
+            bundle = self._build_bundle(effective_locale)
+        except CatalogLoadError:
+            logger.warning("Requested i18n catalog unavailable; using English.")
+            self._state = _LocalizerState(
+                requested_locale=requested_locale,
+                bundle=_ENGLISH_BUNDLE,
+                first_load_warning=CatalogLoadWarning(requested_locale=requested_locale),
+            )
+            return
+        self._state = _LocalizerState(requested_locale=requested_locale, bundle=bundle)
+
+    @property
+    def requested_locale(self) -> str:
+        """Return the persisted/requested locale value without rewriting it."""
+        return self._state.requested_locale
+
+    @property
+    def effective_locale(self) -> str:
+        """Return the locale of the currently active immutable bundle."""
+        return self._state.bundle.locale_name
+
+    @property
+    def first_load_warning(self) -> CatalogLoadWarning | None:
+        """Return the typed warning produced by a failed initial catalog load."""
+        return self._state.first_load_warning
+
+    def switch_locale(self, requested_locale: str) -> CatalogLoadWarning | None:
+        """Build and atomically install a locale bundle, retaining state on failure."""
+        prior = self._state
+        effective_locale = normalize_locale(requested_locale)
+        if effective_locale == prior.bundle.locale_name:
+            self._state = _LocalizerState(requested_locale=requested_locale, bundle=prior.bundle)
+            return None
+        if effective_locale == ENGLISH_LOCALE:
+            self._state = _LocalizerState(requested_locale=requested_locale, bundle=_ENGLISH_BUNDLE)
+            return None
+        try:
+            bundle = self._build_bundle(effective_locale)
+        except CatalogLoadError:
+            logger.warning("Requested i18n catalog unavailable; keeping active locale.")
+            return CatalogLoadWarning(requested_locale=requested_locale)
+        self._state = _LocalizerState(requested_locale=requested_locale, bundle=bundle)
+        return None
+
+    def render(self, reference: MessageRef) -> str:
+        """Render a bound semantic message through the active locale bundle."""
+        bundle = self._state.bundle
+        translations = bundle.translations
+        if translations is None:
+            return format_message(reference)
+
+        definition = reference.definition
+        plural_id = f"{definition.key}#plural"
+        try:
+            # ZeroDivisionError: a loadable MO's Plural-Forms expression may
+            # divide by zero only once ngettext evaluates it for a count.
+            if reference.count is None:
+                template = translations.gettext(definition.key)
+                lookup_ids = {definition.key}
+            else:
+                template = translations.ngettext(definition.key, plural_id, reference.count)
+                lookup_ids = {definition.key, plural_id}
+        except LookupError, OSError, TypeError, ValueError, ZeroDivisionError:
+            logger.warning("Invalid i18n catalog lookup; using English fallback.")
+            return format_message(reference)
+
+        if _formatting._normalized_lookup_candidate(template) in lookup_ids:
+            logger.debug("Missing i18n catalog entry; using English fallback.")
+            return format_message(reference)
+
+        validator = bundle.validate_template
+        if validator is None:
+            return format_message(reference)
+        names = validator(template, definition.multiline)
+        if names is None:
+            logger.warning("Invalid i18n catalog entry; using English fallback.")
+            return format_message(reference)
+
+        parameters = _render_arguments(reference)
+        parameter_names = set(parameters)
+        if names - {"count"} != parameter_names - {"count"} or ("count" in names and "count" not in parameter_names):
+            logger.warning("Invalid i18n catalog entry; using English fallback.")
+            return format_message(reference)
+        try:
+            translated = template.format_map(parameters)
+        except KeyError, ValueError:
+            logger.warning("Invalid i18n catalog entry; using English fallback.")
+            return format_message(reference)
+        if not has_visible_content(translated):
+            logger.warning("Invalid i18n catalog entry; using English fallback.")
+            return format_message(reference)
+        return translated
+
+    def _build_bundle(self, locale_name: str) -> _CatalogBundle:
+        translations = load_catalog(locale_name, catalog_root=self._catalog_root)
+        return _CatalogBundle(
+            locale_name=locale_name,
+            translations=translations,
+            validate_template=_new_template_validator(),
+        )
+
+
+def _new_template_validator() -> _TemplateValidator:
+    @cache
+    def validate(template: str, multiline: bool) -> frozenset[str] | None:
+        try:
+            names = validate_authored_template(template, multiline=multiline)
+        except TypeError, ValueError:
+            return None
+        if _formatting._is_lookup_id(template):
+            return None
+        return names
+
+    return validate

chrys/foundation/i18n/messages.py

@@ -0,0 +1,268 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Immutable locale-neutral message definitions and bound references."""
+
+from __future__ import annotations
+
+import os
+import re
+from collections.abc import Iterable
+from dataclasses import InitVar, dataclass
+
+from chrys.foundation.i18n.formatting import (
+    format_template,
+    has_visible_content,
+    parse_placeholder_names,
+    sanitize_legacy_block,
+    sanitize_legacy_scalar,
+    validate_authored_template,
+)
+from chrys.foundation.platform.files import surrogate_safe_text
+
+_CONSTRUCTION_TOKEN = object()
+_MESSAGE_KEY_RE = re.compile(r"[a-z0-9_]+(?:\.[a-z0-9_]+)+\Z")
+
+
+class _UnsetCount:
+    """Sentinel distinguishing an omitted ``count`` from an explicit ``None``."""
+
+
+_UNSET_COUNT = _UnsetCount()
+
+
+@dataclass(frozen=True, slots=True)
+class DisplayPath:
+    """A filesystem path explicitly selected for safe display conversion."""
+
+    value: str
+
+    def __init__(self, value: str | os.PathLike[str]) -> None:
+        raw_value = os.fspath(value)
+        if type(raw_value) is not str:
+            raise TypeError("DisplayPath requires a text path.")
+        object.__setattr__(self, "value", raw_value)
+
+
+@dataclass(frozen=True, slots=True)
+class DisplayBlock:
+    """Verbatim display text whose LF characters must be preserved."""
+
+    value: str
+
+    def __post_init__(self) -> None:
+        if type(self.value) is not str:
+            raise TypeError("DisplayBlock requires a string.")
+
+
+type MessageScalar = str | int
+type _DisplaySequenceItem = MessageScalar | DisplayPath
+
+
+@dataclass(frozen=True, slots=True)
+class DisplaySequence:
+    """An immutable flat sequence rendered with a fixed comma separator."""
+
+    values: tuple[_DisplaySequenceItem, ...]
+
+    def __init__(self, values: Iterable[_DisplaySequenceItem] = ()) -> None:
+        if isinstance(values, (str, bytes)):
+            raise TypeError("DisplaySequence requires an iterable of elements, not text.")
+        normalized = tuple(values)
+        object.__setattr__(self, "values", normalized)
+        for value in normalized:
+            if not _is_sequence_item(value):
+                raise TypeError("DisplaySequence element has an unsupported type.")
+            if not has_visible_content(_render_sequence_item(value)):
+                raise ValueError("Every DisplaySequence element must have visible content.")
+
+
+type MessageArg = MessageScalar | DisplayPath | DisplaySequence | DisplayBlock
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class MessageDef:
+    """One immutable, extractable semantic message definition."""
+
+    _token: InitVar[object]
+    key: str
+    fallback: str
+    plural_fallback: str | None = None
+    multiline: bool = False
+
+    def __init_subclass__(cls, **kwargs: object) -> None:
+        raise TypeError("MessageDef cannot be subclassed.")
+
+    def __post_init__(self, _token: object) -> None:
+        if _token is not _CONSTRUCTION_TOKEN:
+            raise TypeError("MessageDef values must be constructed with msg().")
+        _validate_definition(self)
+
+    def bind(self, *, count: int | _UnsetCount | None = _UNSET_COUNT, **args: MessageArg) -> MessageRef:
+        """Bind one occurrence's named arguments and optional plural count."""
+        if count is _UNSET_COUNT:
+            resolved_count = None
+        elif self.plural_fallback is None:
+            raise ValueError("count is forbidden for a singular message definition.")
+        elif type(count) is not int:
+            raise TypeError("count must be exactly int.")
+        else:
+            resolved_count = count
+        return MessageRef(
+            _token=_CONSTRUCTION_TOKEN,
+            definition=self,
+            args=tuple(sorted(args.items())),
+            count=resolved_count,
+        )
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class MessageRef:
+    """One immutable occurrence of a semantic message definition."""
+
+    _token: InitVar[object]
+    definition: MessageDef
+    args: tuple[tuple[str, MessageArg], ...] = ()
+    count: int | None = None
+
+    def __init_subclass__(cls, **kwargs: object) -> None:
+        raise TypeError("MessageRef cannot be subclassed.")
+
+    def __post_init__(self, _token: object) -> None:
+        if _token is not _CONSTRUCTION_TOKEN:
+            raise TypeError("MessageRef values must be constructed with MessageDef.bind().")
+        _validate_reference(self)
+
+
+def msg(
+    key: str,
+    *,
+    fallback: str,
+    plural_fallback: str | None = None,
+    multiline: bool = False,
+) -> MessageDef:
+    """Declare one extractable semantic message definition."""
+    return MessageDef(
+        _token=_CONSTRUCTION_TOKEN,
+        key=key,
+        fallback=fallback,
+        plural_fallback=plural_fallback,
+        multiline=multiline,
+    )
+
+
+def _validate_definition(definition: MessageDef) -> None:
+    if type(definition.key) is not str or not _MESSAGE_KEY_RE.fullmatch(definition.key):
+        raise ValueError("Message key must contain two or more lowercase dotted segments.")
+    if type(definition.multiline) is not bool:
+        raise TypeError("The multiline flag must be a bool.")
+    if type(definition.fallback) is not str:
+        raise TypeError("Message fallback must be a string.")
+    if definition.plural_fallback is not None and type(definition.plural_fallback) is not str:
+        raise TypeError("Message plural fallback must be a string or None.")
+
+    singular_names = validate_authored_template(definition.fallback, multiline=definition.multiline)
+    if not has_visible_content(definition.fallback):
+        raise ValueError("Message fallback must have visible content.")
+
+    if definition.plural_fallback is None:
+        if "count" in singular_names:
+            raise ValueError("The reserved count slot requires a plural fallback.")
+        return
+
+    plural_names = validate_authored_template(definition.plural_fallback, multiline=definition.multiline)
+    if not has_visible_content(definition.plural_fallback):
+        raise ValueError("Message plural fallback must have visible content.")
+    if singular_names - {"count"} != plural_names - {"count"}:
+        raise ValueError("Singular and plural fallbacks must share one argument schema.")
+
+
+def _validate_reference(reference: MessageRef) -> None:
+    if type(reference.definition) is not MessageDef:
+        raise TypeError("MessageRef.definition must be a MessageDef.")
+    if type(reference.args) is not tuple:
+        raise TypeError("MessageRef.args must be an immutable tuple.")
+
+    names: list[str] = []
+    has_display_block = False
+    for item in reference.args:
+        if type(item) is not tuple or len(item) != 2:
+            raise TypeError("Every bound argument must be a name/value tuple.")
+        name, value = item
+        if type(name) is not str:
+            raise TypeError("Bound argument names must be strings.")
+        if name == "count":
+            raise ValueError("count is reserved and cannot appear in bound arguments.")
+        if not _is_message_arg(value):
+            raise TypeError(f"Message argument {name!r} has an unsupported type.")
+        names.append(name)
+        has_display_block = has_display_block or type(value) is DisplayBlock
+    if names != sorted(set(names)):
+        raise ValueError("Bound arguments must have unique names in deterministic order.")
+
+    definition = reference.definition
+    if definition.plural_fallback is None:
+        if reference.count is not None:
+            raise ValueError("count is forbidden for a singular message definition.")
+    elif type(reference.count) is not int:
+        if reference.count is None:
+            raise ValueError("count is required for a plural message definition.")
+        raise TypeError("count must be exactly int.")
+    if has_display_block and not definition.multiline:
+        raise ValueError("DisplayBlock arguments require a multiline message definition.")
+
+    expected_names = parse_placeholder_names(definition.fallback) - {"count"}
+    if set(names) != expected_names:
+        raise ValueError("Bound arguments do not match the message argument schema.")
+
+    fallback = definition.fallback if reference.count is None or reference.count == 1 else definition.plural_fallback
+    if fallback is None:
+        raise ValueError("A plural reference requires a plural fallback.")
+    rendered = format_template(fallback, _render_arguments(reference), multiline=definition.multiline)
+    if not has_visible_content(rendered):
+        raise ValueError("The formatted English message must have visible content.")
+
+
+def _is_sequence_item(value: object) -> bool:
+    return type(value) in {str, int, DisplayPath}
+
+
+def _is_message_arg(value: object) -> bool:
+    return type(value) in {str, int, DisplayPath, DisplaySequence, DisplayBlock}
+
+
+def _int_display(value: int) -> str:
+    try:
+        return str(value)
+    except ValueError as error:  # CPython's int-to-str digit-count limit
+        raise ValueError("Integer message arguments must be displayable in decimal form.") from error
+
+
+def _render_sequence_item(value: _DisplaySequenceItem) -> str:
+    if type(value) is DisplayPath:
+        return sanitize_legacy_scalar(surrogate_safe_text(value.value))
+    if type(value) is int:
+        return sanitize_legacy_scalar(_int_display(value))
+    return sanitize_legacy_scalar(surrogate_safe_text(str(value)))
+
+
+def _render_message_arg(value: MessageArg) -> str:
+    # Every textual branch neutralizes lone surrogates, not just DisplayPath:
+    # scalar and block arguments routinely carry filesystem-derived values
+    # (profile names, path lists), and a surrogate that reaches a strict
+    # encode crashes the render sink.
+    if type(value) is DisplayPath:
+        return sanitize_legacy_scalar(surrogate_safe_text(value.value))
+    if type(value) is DisplaySequence:
+        return ", ".join(_render_sequence_item(element) for element in value.values)
+    if type(value) is DisplayBlock:
+        return sanitize_legacy_block(surrogate_safe_text(value.value))
+    if type(value) is int:
+        return sanitize_legacy_scalar(_int_display(value))
+    return sanitize_legacy_scalar(surrogate_safe_text(str(value)))
+
+
+def _render_arguments(reference: MessageRef) -> dict[str, str]:
+    rendered = {name: _render_message_arg(value) for name, value in reference.args}
+    if reference.count is not None:
+        rendered["count"] = _int_display(reference.count)
+    return rendered

chrys/foundation/io/__init__.py

@@ -0,0 +1,3 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""I/O result normalization helpers."""

chrys/foundation/io/result_content.py

@@ -0,0 +1,237 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Normalize rich tool results into display text and image content."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from typing import Any
+
+from chrys.foundation.text.images import is_image_media_type
+from chrys.foundation.text.model_json import model_json
+
+logger = logging.getLogger(__name__)
+
+
+# Marker prefix used by chrys to tag tool results as failures.  TUI
+# renderers check ``result.startswith(_ERROR_PREFIX)`` to apply error
+# styling, and the LLM treats it as an error signal.
+_ERROR_PREFIX = "Error: "
+
+
+def _render_attr_value(val: Any) -> str:
+    """Render a Content text-bearing attribute value to a string.
+
+    The text-bearing slots (``text``/``result``/``output``/``message``)
+    are typed ``Any`` on ``Content`` and in practice can hold non-string
+    values:
+
+    * ``Content.from_mcp_server_tool_result(output=...)`` accepts a
+      ``list[Content]`` (the Anthropic provider builds these for
+      ``mcp_tool_result`` blocks from Anthropic-managed MCP servers).
+    * Custom tools / providers may set ``result`` or ``output`` to a
+      ``dict`` (e.g. structured JSON returned from an MCP server) or
+      another nested container.
+
+    Naively calling ``str(val)`` on these renders unusable object reprs
+    because ``Content`` does not override ``__repr__``.  Instead:
+
+    * ``list``/``tuple`` -> recurse into :func:`extract_result_text` so
+      Content items inside the list are properly unwrapped.
+    * ``Mapping`` -> JSON-dump (preserves ``{"code": 500, "body": ...}``
+      style structured error payloads as readable JSON).
+    * everything else -> ``str(val)`` (numbers, bools, plain objects).
+    """
+    if isinstance(val, str):
+        return val
+    if isinstance(val, (list, tuple)):
+        return extract_result_text(list(val))
+    if isinstance(val, Mapping):
+        try:
+            return model_json(val, default=str)
+        except TypeError, ValueError:
+            return str(val)
+    return str(val)
+
+
+def _content_to_text(item: Any) -> str:
+    """Render a single ``Content``-like item to a string.
+
+    Tries the known text-bearing attributes in order (``text`` for text
+    items, ``result`` for function_result, ``output`` for
+    mcp_server_tool_result, ``message`` for error).  For data/uri items
+    (images, audio, embedded blobs) returns a ``[<media_type>: <uri...>]``
+    placeholder so the LLM still sees something meaningful instead of a
+    bare object repr.
+
+    If the item has none of those attributes (e.g. an unexpected
+    function_call / approval_request Content showing up where a result
+    was expected), logs a WARNING and returns an ``"Error: ..."`` string
+    so the failure is surfaced both in logs and to the LLM/TUI rather
+    than masquerading as a successful structured result.
+    """
+    if isinstance(item, str):
+        return item
+    if isinstance(item, Mapping):
+        return _render_attr_value(item)
+    # The first text-bearing attribute that is *present and non-None* wins,
+    # even if its value is the empty string: an empty text item should
+    # render as ``""`` (filtered upstream), not fall through to the
+    # structural-fields dump and emit ``{"type": "text", ...}``.
+    for attr in ("text", "result", "output", "message"):
+        val = getattr(item, attr, None)
+        if val is None:
+            continue
+        return _render_attr_value(val)
+    uri = getattr(item, "uri", None)
+    if uri:
+        media_type = getattr(item, "media_type", None) or "binary"
+        if _is_image_data_uri(media_type, uri):
+            return f"[{media_type} image]"
+        snippet = uri if len(uri) <= 120 else uri[:117] + "..."
+        return f"[{media_type}: {snippet}]"
+    # Unrecognized shape: every documented success path produces a
+    # Content with at least one of text/result/output/message/uri.
+    # Hitting this branch means either a framework Content schema drift
+    # or a misrouted call/state container ending up in a result list.
+    # Treat it as an error: log a warning and emit a clearly tagged
+    # diagnostic string so the LLM doesn't read raw JSON as success.
+    if hasattr(item, "__dict__"):
+        try:
+            d = {k: v for k, v in vars(item).items() if v not in (None, "") and not k.startswith("_")}
+        except TypeError:
+            d = {}
+        if not d:
+            # Object truly carries nothing: render as empty (filtered upstream).
+            return ""
+        type_hint = d.get("type", type(item).__name__)
+        logger.warning(
+            "Unrecognized tool result Content (type=%r); rendering as fallback. Fields: %s",
+            type_hint,
+            {k: _summarize_value(v) for k, v in d.items()},
+        )
+        return (
+            f"{_ERROR_PREFIX}unrecognized tool result content (type={type_hint}); fields: {model_json(d, default=str)}"
+        )
+    return str(item)
+
+
+def extract_result_text(result: Any) -> str:
+    """Extract displayable text from a tool invocation result.
+
+    Since rc5, ``FunctionTool.invoke()`` returns ``list[Content]`` instead
+    of a plain string.  This walks the list and extracts text from each
+    Content item via :func:`_content_to_text`.  When a Content item is
+    not understood, an unstructured fallback is logged at DEBUG so the
+    raw shape is recoverable from logs without crashing the tool result.
+    """
+    if result is None:
+        return ""
+    # Guard against dangling coroutines left by cancelled tool invocations.
+    # FunctionMiddlewarePipeline can leave context.result holding the handler
+    # coroutine if cancellation interrupts its await. Close it rather than
+    # rendering a coroutine object as the tool's result.
+    import inspect
+
+    if inspect.isawaitable(result):
+        close = getattr(result, "close", None)
+        if close is not None:
+            close()
+        return ""
+    if isinstance(result, str):
+        return result
+    if isinstance(result, list):
+        if logger.isEnabledFor(logging.DEBUG):
+            logger.debug(
+                "Tool result list: %d item(s); types=%s; shapes=%s",
+                len(result),
+                [getattr(item, "type", type(item).__name__) for item in result],
+                [_summarize_item_shape(item) for item in result],
+            )
+        rendered = [_content_to_text(item) for item in result]
+        parts = [p for p in rendered if p]
+        if not parts:
+            return ""
+        # If any item triggered the unrecognized-content fallback, the
+        # whole result must surface as an error so the TUI styling and
+        # the chrys "Error: ..." convention apply to the joined string.
+        any_error = any(p.startswith(_ERROR_PREFIX) for p in parts)
+        joined = "\n".join(parts)
+        if any_error and not joined.startswith(_ERROR_PREFIX):
+            joined = _ERROR_PREFIX + joined
+        return joined
+    return _content_to_text(result)
+
+
+def extract_result_images(result: Any) -> list[Any]:
+    """Extract image Content-like items from a tool invocation result."""
+    if result is None or isinstance(result, str):
+        return []
+    if isinstance(result, list):
+        images: list[Any] = []
+        for item in result:
+            images.extend(extract_result_images(item))
+        return images
+    item_type = getattr(result, "type", None)
+    if item_type == "function_result":
+        items = getattr(result, "items", None)
+        return extract_result_images(items) if isinstance(items, list) else []
+    if item_type in ("data", "uri"):
+        media_type = getattr(result, "media_type", None)
+        properties = getattr(result, "additional_properties", None)
+        property_media_type = properties.get("media_type") if isinstance(properties, Mapping) else None
+        if is_image_media_type(media_type) or is_image_media_type(property_media_type):
+            return [result]
+    return []
+
+
+def _is_image_data_uri(media_type: Any, uri: Any) -> bool:
+    return (
+        isinstance(media_type, str)
+        and media_type.lower().startswith("image/")
+        and isinstance(uri, str)
+        and uri.startswith("data:")
+    )
+
+
+_DEBUG_STR_PREVIEW_CHARS = 80
+
+
+def _summarize_value(v: Any) -> Any:
+    """Render a single value as a debug-log-safe summary.
+
+    Long strings become ``<str len=N preview='...'>`` (only the first
+    ``_DEBUG_STR_PREVIEW_CHARS`` chars previewed, via ``repr`` so any
+    binary/escape sequences stay quoted). Bytes and containers become
+    ``<typename len=N>`` (no contents). Numbers/bools pass through.
+    Other objects become ``<typename>``.
+    """
+    if isinstance(v, str):
+        if len(v) <= _DEBUG_STR_PREVIEW_CHARS:
+            return v
+        return f"<str len={len(v)} preview={v[:_DEBUG_STR_PREVIEW_CHARS]!r}>"
+    if isinstance(v, (bytes, bytearray, list, tuple, dict, set)):
+        return f"<{type(v).__name__} len={len(v)}>"
+    if isinstance(v, (int, float, bool)):
+        return v
+    return f"<{type(v).__name__}>"
+
+
+def _summarize_item_shape(item: Any) -> Any:
+    """Render a result-list item as a debug-log-safe shape descriptor.
+
+    For objects with ``__dict__`` (e.g. ``Content``):
+    returns a dict mapping field name -> :func:`_summarize_value` of the
+    value.  For plain values (``str``, ``bytes``, primitives, etc.):
+    returns the same summary directly.  Either way, large payloads:
+    base64 ``data:`` URIs, blob contents, big strings: never appear
+    verbatim in the DEBUG log.
+    """
+    if not hasattr(item, "__dict__"):
+        return _summarize_value(item)
+    try:
+        fields = {k: v for k, v in vars(item).items() if v not in (None, "") and not k.startswith("_")}
+    except TypeError:
+        return _summarize_value(item)
+    return {k: _summarize_value(v) for k, v in fields.items()}