feat: tool call serialization, deprecated param shims, and OpenResponses protocol

Author: Kamilbenkirane

src/celeste/modalities/text/client.py

@@ -1,11 +1,13 @@
 """Text modality client."""
 
-from typing import Any, Unpack
+import warnings
+from typing import Any, ClassVar, Unpack
 
 from asgiref.sync import async_to_sync
 
 from celeste.client import ModalityClient
 from celeste.core import InputType, Modality
+from celeste.tools import CodeExecution, WebSearch, XSearch
 from celeste.types import AudioContent, ImageContent, Message, TextContent, VideoContent
 
 from .io import TextChunk, TextFinishReason, TextInput, TextOutput, TextUsage
@@ -25,11 +27,45 @@ class TextClient(
     _usage_class = TextUsage
     _finish_reason_class = TextFinishReason
 
+    # Deprecated param → Tool class mapping.
+    # TODO(deprecation): Remove on 2026-06-07.
+    _DEPRECATED_TOOL_PARAMS: ClassVar[dict[str, type]] = {
+        "web_search": WebSearch,
+        "x_search": XSearch,
+        "code_execution": CodeExecution,
+    }
+
     @classmethod
     def _output_class(cls) -> type[TextOutput]:
         """Return the Output class for text modality."""
         return TextOutput
 
+    def _build_request(
+        self,
+        inputs: TextInput,
+        extra_body: dict[str, Any] | None = None,
+        streaming: bool = False,
+        **parameters: Unpack[TextParameters],
+    ) -> dict[str, Any]:
+        """Build request, migrating deprecated boolean tool params first.
+
+        TODO(deprecation): Remove this override on 2026-06-07.
+        """
+        for old_param, tool_cls in self._DEPRECATED_TOOL_PARAMS.items():
+            value = parameters.pop(old_param, None)  # type: ignore[misc]
+            if value:
+                warnings.warn(
+                    f"'{old_param}=True' is deprecated, "
+                    f"use tools=[{tool_cls.__name__}()] instead. "
+                    "Will be removed on 2026-06-07.",
+                    DeprecationWarning,
+                    stacklevel=4,
+                )
+                parameters.setdefault("tools", []).append(tool_cls())
+        return super()._build_request(
+            inputs, extra_body=extra_body, streaming=streaming, **parameters
+        )
+
     def _check_media_support(
         self,
         image: ImageContent | None,

src/celeste/modalities/text/parameters.py

@@ -27,6 +27,12 @@ class TextParameter(StrEnum):
     TOOLS = "tools"
     VERBOSITY = "verbosity"
 
+    # Deprecated: use tools=[WebSearch()], tools=[XSearch()], tools=[CodeExecution()] instead.
+    # TODO(deprecation): Remove on 2026-06-07.
+    WEB_SEARCH = "web_search"
+    X_SEARCH = "x_search"
+    CODE_EXECUTION = "code_execution"
+
     # Media input declarations (for optional_input_types)
     IMAGE = "image"
     VIDEO = "video"
@@ -48,6 +54,12 @@ class TextParameters(Parameters):
     tools: list[ToolDefinition]
     verbosity: str
 
+    # Deprecated: use tools=[WebSearch()], tools=[XSearch()], tools=[CodeExecution()] instead.
+    # TODO(deprecation): Remove on 2026-06-07.
+    web_search: bool
+    x_search: bool
+    code_execution: bool
+
 
 __all__ = [
     "TextParameter",

src/celeste/modalities/text/protocols/__init__.py

@@ -0,0 +1 @@
+"""Text modality protocol implementations."""

src/celeste/modalities/text/protocols/openresponses/__init__.py

@@ -0,0 +1,5 @@
+"""OpenResponses protocol for text modality."""
+
+from .client import OpenResponsesTextClient, OpenResponsesTextStream
+
+__all__ = ["OpenResponsesTextClient", "OpenResponsesTextStream"]

src/celeste/modalities/text/protocols/openresponses/client.py

@@ -0,0 +1,137 @@
+"""OpenResponses text client."""
+
+from typing import Any, Unpack
+
+from celeste.parameters import ParameterMapper
+from celeste.protocols.openresponses.client import (
+    OpenResponsesClient as OpenResponsesMixin,
+)
+from celeste.protocols.openresponses.streaming import (
+    OpenResponsesStream as _OpenResponsesStream,
+)
+from celeste.protocols.openresponses.tools import (
+    parse_content,
+    parse_tool_calls,
+    serialize_messages,
+)
+from celeste.tools import ToolCall
+from celeste.types import ImageContent, Message, TextContent, VideoContent
+from celeste.utils import build_image_data_url
+
+from ...client import TextClient
+from ...io import (
+    TextChunk,
+    TextInput,
+    TextOutput,
+)
+from ...parameters import TextParameters
+from ...streaming import TextStream
+from .parameters import OPENRESPONSES_PARAMETER_MAPPERS
+
+
+class OpenResponsesTextStream(_OpenResponsesStream, TextStream):
+    """OpenResponses streaming for text modality."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._response_data: dict[str, Any] | None = None
+
+    def _parse_chunk(self, event_data: dict[str, Any]) -> TextChunk | None:
+        """Parse one SSE event into a typed chunk (captures response.completed)."""
+        event_type = event_data.get("type")
+        if event_type == "response.completed":
+            response = event_data.get("response")
+            if isinstance(response, dict):
+                self._response_data = response
+        return super()._parse_chunk(event_data)
+
+    def _aggregate_event_data(self, chunks: list[TextChunk]) -> list[dict[str, Any]]:
+        """Prepend response_data, then delegate to base."""
+        events: list[dict[str, Any]] = []
+        if self._response_data is not None:
+            events.append(self._response_data)
+        events.extend(super()._aggregate_event_data(chunks))
+        return events
+
+    def _aggregate_tool_calls(
+        self, chunks: list[TextChunk], raw_events: list[dict[str, Any]]
+    ) -> list[ToolCall]:
+        """Extract tool calls from response.completed data."""
+        if self._response_data is None:
+            return []
+        return parse_tool_calls(self._response_data)
+
+
+class OpenResponsesTextClient(OpenResponsesMixin, TextClient):
+    """OpenResponses text client using Responses API."""
+
+    @classmethod
+    def parameter_mappers(cls) -> list[ParameterMapper[TextContent]]:
+        return OPENRESPONSES_PARAMETER_MAPPERS
+
+    async def generate(
+        self,
+        prompt: str | None = None,
+        *,
+        messages: list[Message] | None = None,
+        base_url: str | None = None,
+        extra_body: dict[str, Any] | None = None,
+        **parameters: Unpack[TextParameters],
+    ) -> TextOutput:
+        """Generate text from prompt."""
+        inputs = TextInput(prompt=prompt, messages=messages)
+        return await self._predict(
+            inputs, base_url=base_url, extra_body=extra_body, **parameters
+        )
+
+    async def analyze(
+        self,
+        prompt: str | None = None,
+        *,
+        messages: list[Message] | None = None,
+        image: ImageContent | None = None,
+        video: VideoContent | None = None,
+        base_url: str | None = None,
+        extra_body: dict[str, Any] | None = None,
+        **parameters: Unpack[TextParameters],
+    ) -> TextOutput:
+        """Analyze image(s) or video(s) with prompt or messages."""
+        inputs = TextInput(prompt=prompt, messages=messages, image=image, video=video)
+        return await self._predict(
+            inputs, base_url=base_url, extra_body=extra_body, **parameters
+        )
+
+    def _init_request(self, inputs: TextInput) -> dict[str, Any]:
+        """Initialize request with input content."""
+        if inputs.messages is not None:
+            return {"input": serialize_messages(inputs.messages)}
+
+        content: list[dict[str, Any]] = []
+        if inputs.image is not None:
+            images = inputs.image if isinstance(inputs.image, list) else [inputs.image]
+            for img in images:
+                content.append(
+                    {"type": "input_image", "image_url": build_image_data_url(img)}
+                )
+
+        content.append({"type": "input_text", "text": inputs.prompt or ""})
+        return {"input": [{"role": "user", "content": content}]}
+
+    def _parse_content(
+        self,
+        response_data: dict[str, Any],
+    ) -> TextContent:
+        """Parse text content from response."""
+        output = super()._parse_content(response_data)
+        return parse_content(output)
+
+    def _parse_tool_calls(self, response_data: dict[str, Any]) -> list[ToolCall]:
+        """Parse tool calls from OpenResponses response."""
+        return parse_tool_calls(response_data)
+
+    def _stream_class(self) -> type[TextStream]:
+        """Return the Stream class for this provider."""
+        return OpenResponsesTextStream
+
+
+__all__ = ["OpenResponsesTextClient", "OpenResponsesTextStream"]

src/celeste/modalities/text/protocols/openresponses/parameters.py

@@ -0,0 +1,52 @@
+"""OpenResponses parameter mappers for text."""
+
+from celeste.parameters import ParameterMapper
+from celeste.protocols.openresponses.parameters import (
+    MaxOutputTokensMapper as _MaxOutputTokensMapper,
+)
+from celeste.protocols.openresponses.parameters import (
+    TemperatureMapper as _TemperatureMapper,
+)
+from celeste.protocols.openresponses.parameters import (
+    TextFormatMapper as _TextFormatMapper,
+)
+from celeste.protocols.openresponses.parameters import (
+    ToolsMapper as _ToolsMapper,
+)
+from celeste.types import TextContent
+
+from ...parameters import TextParameter
+
+
+class TemperatureMapper(_TemperatureMapper):
+    """Map temperature to Responses temperature parameter."""
+
+    name = TextParameter.TEMPERATURE
+
+
+class MaxTokensMapper(_MaxOutputTokensMapper):
+    """Map max_tokens to Responses max_output_tokens parameter."""
+
+    name = TextParameter.MAX_TOKENS
+
+
+class OutputSchemaMapper(_TextFormatMapper):
+    """Map output_schema to Responses text.format parameter."""
+
+    name = TextParameter.OUTPUT_SCHEMA
+
+
+class ToolsMapper(_ToolsMapper):
+    """Map tools to Responses tools parameter."""
+
+    name = TextParameter.TOOLS
+
+
+OPENRESPONSES_PARAMETER_MAPPERS: list[ParameterMapper[TextContent]] = [
+    TemperatureMapper(),
+    MaxTokensMapper(),
+    OutputSchemaMapper(),
+    ToolsMapper(),
+]
+
+__all__ = ["OPENRESPONSES_PARAMETER_MAPPERS"]

src/celeste/modalities/text/providers/cohere/client.py

@@ -59,7 +59,11 @@ def _init_request(self, inputs: TextInput) -> dict[str, Any]:
         """Initialize request from Cohere v2 Chat API messages array format."""
         # If messages provided, use them directly (messages take precedence)
         if inputs.messages is not None:
-            return {"messages": [message.model_dump() for message in inputs.messages]}
+            return {
+                "messages": [
+                    message.model_dump(exclude_none=True) for message in inputs.messages
+                ]
+            }
 
         # Fall back to prompt-based input
         if inputs.image is None:

src/celeste/modalities/text/providers/google/client.py

@@ -37,11 +37,15 @@ def _aggregate_tool_calls(
             for candidate in event.get("candidates", []):
                 for part in candidate.get("content", {}).get("parts", []):
                     if "functionCall" in part:
+                        kwargs: dict[str, Any] = {}
+                        if "thoughtSignature" in part:
+                            kwargs["thoughtSignature"] = part["thoughtSignature"]
                         tool_calls.append(
                             ToolCall(
                                 id=str(uuid4()),
                                 name=part["functionCall"]["name"],
                                 arguments=part["functionCall"].get("args", {}),
+                                **kwargs,
                             )
                         )
         return tool_calls
@@ -139,14 +143,16 @@ def content_to_parts(content: Any) -> list[dict[str, Any]]:
                     msg_parts = content_to_parts(msg.content)
                     if msg.tool_calls:
                         for tc in msg.tool_calls:
-                            msg_parts.append(
-                                {
-                                    "functionCall": {
-                                        "name": tc.name,
-                                        "args": tc.arguments,
-                                    }
+                            part: dict[str, Any] = {
+                                "functionCall": {
+                                    "name": tc.name,
+                                    "args": tc.arguments,
                                 }
-                            )
+                            }
+                            thought_sig = getattr(tc, "thoughtSignature", None)
+                            if thought_sig:
+                                part["thoughtSignature"] = thought_sig
+                            msg_parts.append(part)
                     contents.append({"role": role, "parts": msg_parts})
 
             result: dict[str, Any] = {"contents": contents}
@@ -219,24 +225,35 @@ def _parse_content(
         """Parse content from response."""
         candidates = super()._parse_content(response_data)
         parts = candidates[0].get("content", {}).get("parts", [])
-        text = parts[0].get("text") if parts else ""
-        return text or ""
+        for p in parts:
+            if p.get("thought"):
+                continue
+            text = p.get("text")
+            if text is not None:
+                return text
+        return ""
 
     def _parse_tool_calls(self, response_data: dict[str, Any]) -> list[ToolCall]:
         """Parse tool calls from Google response."""
         candidates = response_data.get("candidates", [])
         if not candidates:
             return []
         parts = candidates[0].get("content", {}).get("parts", [])
-        return [
-            ToolCall(
-                id=str(uuid4()),
-                name=p["functionCall"]["name"],
-                arguments=p["functionCall"].get("args", {}),
-            )
-            for p in parts
-            if "functionCall" in p
-        ]
+        tool_calls: list[ToolCall] = []
+        for p in parts:
+            if "functionCall" in p:
+                kwargs: dict[str, Any] = {}
+                if "thoughtSignature" in p:
+                    kwargs["thoughtSignature"] = p["thoughtSignature"]
+                tool_calls.append(
+                    ToolCall(
+                        id=str(uuid4()),
+                        name=p["functionCall"]["name"],
+                        arguments=p["functionCall"].get("args", {}),
+                        **kwargs,
+                    )
+                )
+        return tool_calls
 
     def _stream_class(self) -> type[TextStream]:
         """Return the Stream class for this provider."""

src/celeste/modalities/text/providers/google/models.py

@@ -141,8 +141,7 @@
             Parameter.TEMPERATURE: Range(min=0.0, max=2.0),
             Parameter.MAX_TOKENS: Range(min=1, max=65536),
             TextParameter.THINKING_LEVEL: Choice(options=["low", "high"]),
-            TextParameter.WEB_SEARCH: Bool(),
-            TextParameter.CODE_EXECUTION: Bool(),
+            TextParameter.TOOLS: ToolSupport(tools=[WebSearch, CodeExecution]),
             TextParameter.OUTPUT_SCHEMA: Schema(),
             # Media input support
             TextParameter.IMAGE: ImagesConstraint(),