Add content_output builder

Author: msullivan

examples/read_file_tool.py

@@ -44,13 +44,9 @@ async def read_file(path: str) -> str | ai.messages.ContentOutput:
     data = _resolve_within_allowed(path).read_bytes()
     image_type = media.detect_image_media_type(data)
     if image_type is not None:
-        return ai.messages.ContentOutput(
-            value=[
-                ai.messages.TextPart(
-                    text=f"Loaded {path} ({image_type}, {len(data)} bytes)."
-                ),
-                ai.file_part(data, media_type=image_type),
-            ]
+        return ai.content_output(
+            f"Loaded {path} ({image_type}, {len(data)} bytes).",
+            ai.file_part(data, media_type=image_type),
         )
     return data.decode("utf-8", errors="replace")
 

src/ai/__init__.py

@@ -63,8 +63,10 @@
 from .types import events, messages, tools
 from .types.builders import (
     assistant_message,
+    content_output,
     file_part,
     system_message,
+    text_part,
     thinking,
     tool_message,
     tool_result_part,
@@ -119,6 +121,7 @@
     "agent",
     "assistant_message",
     "cancel_hook",
+    "content_output",
     "errors",
     # Submodules
     "events",
@@ -137,6 +140,7 @@
     "resolve_hook",
     "stream",
     "system_message",
+    "text_part",
     "thinking",
     "tool",
     "tool_message",

src/ai/types/builders.py

@@ -13,6 +13,8 @@
     from . import events as events_
 
 from .messages import (
+    ContentOutput,
+    ContentPart,
     ErrorJsonOutput,
     ErrorTextOutput,
     ExecutionDeniedOutput,
@@ -92,6 +94,35 @@ def file_part(
     return FilePart.from_bytes(data, media_type=media_type, filename=filename)
 
 
+def text_part(
+    text: str,
+    *,
+    provider_metadata: dict[str, Any] | None = None,
+) -> TextPart:
+    """Create a :class:`TextPart`.
+
+    Bare strings passed to the ``*_message`` builders are coerced into
+    text parts automatically; reach for this when you need to attach
+    ``provider_metadata`` or build a part list directly.
+    """
+    return TextPart(text=text, provider_metadata=provider_metadata)
+
+
+def content_output(*content: str | TextPart | FilePart) -> ContentOutput:
+    """Create a multipart :class:`ContentOutput` tool result.
+
+    Bare strings become :class:`TextPart` objects, mirroring the
+    ``*_message`` builders, so a tool can return mixed text and files
+    without constructing the part list by hand.
+
+    >>> ai.content_output("Here is the chart:", ai.file_part(png_bytes))
+    """
+    parts: list[ContentPart] = []
+    for item in content:
+        parts.append(TextPart(text=item) if isinstance(item, str) else item)
+    return ContentOutput(value=parts)
+
+
 def thinking(
     text: str,
     *,

tests/types/test_builders.py

@@ -20,6 +20,25 @@ def test_user_message_mixed_content() -> None:
     assert isinstance(msg.parts[2], messages.TextPart)
 
 
+def test_text_part() -> None:
+    tp = builders.text_part("hello", provider_metadata={"k": "v"})
+    assert isinstance(tp, messages.TextPart)
+    assert tp.text == "hello"
+    assert tp.provider_metadata == {"k": "v"}
+
+
+def test_content_output_coerces_strings() -> None:
+    fp = messages.FilePart(
+        data="https://example.com/img.png", media_type="image/png"
+    )
+    out = builders.content_output("Here:", fp)
+    assert isinstance(out, messages.ContentOutput)
+    assert len(out.value) == 2
+    assert isinstance(out.value[0], messages.TextPart)
+    assert out.value[0].text == "Here:"
+    assert isinstance(out.value[1], messages.FilePart)
+
+
 def test_file_part_from_url() -> None:
     fp = builders.file_part("https://example.com/image.png")
     assert isinstance(fp, messages.FilePart)