feat: unified tools= parameter for tool calling (#191)

Replace individual boolean parameters (web_search, x_search, code_execution)
with a single tools= list parameter that accepts Tool instances, user-defined
dicts, and raw passthrough dicts.

- Add Tool, WebSearch, XSearch, CodeExecution classes with provider-specific
  ToolMappers that translate to wire format
- Add ToolCall on Output and ToolResult(Message) for multi-turn tool use
- Add ToolSupport constraint for model-level tool validation
- Add _parse_tool_calls to all providers (Anthropic, OpenAI, xAI, Google,
  OpenResponses) for non-streaming tool call extraction
- Add _aggregate_tool_calls to streaming for all providers
- Update templates for new tools parameter pattern

Author: Kamilbenkirane

src/celeste/__init__.py

@@ -51,6 +51,7 @@
     StrictJsonSchemaGenerator,
     StrictRefResolvingJsonSchemaGenerator,
 )
+from celeste.tools import CodeExecution, Tool, ToolCall, ToolResult, WebSearch, XSearch
 from celeste.types import Content, JsonValue, Message, Role
 from celeste.websocket import WebSocketClient, WebSocketConnection, close_all_ws_clients
 
@@ -245,6 +246,7 @@ def create_client(
     "Authentication",
     "Capability",
     "ClientNotFoundError",
+    "CodeExecution",
     "ConstraintViolationError",
     "Content",
     "Error",
@@ -270,14 +272,19 @@ def create_client(
     "StreamingNotSupportedError",
     "StrictJsonSchemaGenerator",
     "StrictRefResolvingJsonSchemaGenerator",
+    "Tool",
+    "ToolCall",
+    "ToolResult",
     "UnsupportedCapabilityError",
     "UnsupportedParameterError",
     "UnsupportedProviderError",
     "Usage",
     "UsageField",
     "ValidationError",
+    "WebSearch",
     "WebSocketClient",
     "WebSocketConnection",
+    "XSearch",
     "audio",
     "close_all_http_clients",
     "close_all_ws_clients",

src/celeste/client.py

@@ -17,6 +17,7 @@
 from celeste.models import Model
 from celeste.parameters import ParameterMapper, Parameters
 from celeste.streaming import Stream, enrich_stream_errors
+from celeste.tools import ToolCall
 from celeste.types import RawUsage
 
 
@@ -200,13 +201,19 @@ async def _predict(
         )
         content = self._parse_content(response_data, **parameters)
         content = self._transform_output(content, **parameters)
+        tool_calls = self._parse_tool_calls(response_data)
         return self._output_class()(
             content=content,
             usage=self._get_usage(response_data),
             finish_reason=self._get_finish_reason(response_data),
             metadata=self._build_metadata(response_data),
+            tool_calls=tool_calls,
         )
 
+    def _parse_tool_calls(self, response_data: dict[str, Any]) -> list[ToolCall]:
+        """Parse tool calls from response. Override in providers that support tools."""
+        return []
+
     def _stream(
         self,
         inputs: In,

src/celeste/constraints.py

@@ -5,11 +5,12 @@
 from abc import ABC, abstractmethod
 from typing import Any, ClassVar, get_args, get_origin
 
-from pydantic import BaseModel, Field, computed_field
+from pydantic import BaseModel, Field, computed_field, field_serializer
 
 from celeste.artifacts import AudioArtifact, ImageArtifact, VideoArtifact
 from celeste.exceptions import ConstraintViolationError
 from celeste.mime_types import AudioMimeType, ImageMimeType, MimeType, VideoMimeType
+from celeste.tools import Tool
 
 
 class Constraint(BaseModel, ABC):
@@ -367,6 +368,26 @@ class AudiosConstraint(_MediaListConstraint[AudioMimeType]):
     _media_label = "audio"
 
 
+class ToolSupport(Constraint):
+    """Tool support constraint - validates Tool instances are supported by the model."""
+
+    tools: list[type[Tool]]
+
+    @field_serializer("tools")
+    @classmethod
+    def _serialize_tools(cls, v: list[type[Tool]]) -> list[str]:
+        return [t.__name__ for t in v]
+
+    def __call__(self, value: list) -> list:
+        """Validate tools list against supported tools."""
+        for item in value:
+            if isinstance(item, Tool) and type(item) not in self.tools:
+                supported = [t.__name__ for t in self.tools]
+                msg = f"Tool '{type(item).__name__}' not supported. Supported: {supported}"
+                raise ConstraintViolationError(msg)
+        return value
+
+
 __all__ = [
     "AudioConstraint",
     "AudiosConstraint",
@@ -382,6 +403,7 @@ class AudiosConstraint(_MediaListConstraint[AudioMimeType]):
     "Range",
     "Schema",
     "Str",
+    "ToolSupport",
     "VideoConstraint",
     "VideosConstraint",
 ]

src/celeste/io.py

@@ -9,6 +9,7 @@
 from celeste.artifacts import AudioArtifact, ImageArtifact, VideoArtifact
 from celeste.constraints import Constraint
 from celeste.core import InputType
+from celeste.tools import ToolCall
 
 
 class Input(BaseModel):
@@ -38,6 +39,7 @@ class Output[Content](BaseModel):
     usage: Usage = Field(default_factory=Usage)
     finish_reason: FinishReason | None = None
     metadata: dict[str, Any] = Field(default_factory=dict)
+    tool_calls: list[ToolCall] = Field(default_factory=list)
 
 
 class Chunk[Content](BaseModel):

src/celeste/modalities/text/parameters.py

@@ -9,6 +9,7 @@
 from pydantic import BaseModel
 
 from celeste.parameters import Parameters
+from celeste.tools import ToolDefinition
 
 
 class TextParameter(StrEnum):
@@ -23,10 +24,8 @@ class TextParameter(StrEnum):
     THINKING_BUDGET = "thinking_budget"
     THINKING_LEVEL = "thinking_level"
     OUTPUT_SCHEMA = "output_schema"
-    WEB_SEARCH = "web_search"
+    TOOLS = "tools"
     VERBOSITY = "verbosity"
-    X_SEARCH = "x_search"
-    CODE_EXECUTION = "code_execution"
 
     # Media input declarations (for optional_input_types)
     IMAGE = "image"
@@ -46,10 +45,8 @@ class TextParameters(Parameters):
     thinking_budget: int | str
     thinking_level: str
     output_schema: type[BaseModel]
-    web_search: bool
+    tools: list[ToolDefinition]
     verbosity: str
-    x_search: bool
-    code_execution: bool
 
 
 __all__ = [

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

@@ -1,6 +1,7 @@
 """Anthropic text client (modality)."""
 
 import base64
+import contextlib
 from typing import Any, Unpack
 
 from celeste.artifacts import ImageArtifact
@@ -10,6 +11,7 @@
 from celeste.providers.anthropic.messages.streaming import (
     AnthropicMessagesStream as _AnthropicMessagesStream,
 )
+from celeste.tools import ToolCall, ToolResult
 from celeste.types import ImageContent, Message, TextContent, VideoContent
 from celeste.utils import detect_mime_type
 
@@ -30,15 +32,31 @@ class AnthropicTextStream(_AnthropicMessagesStream, TextStream):
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         super().__init__(*args, **kwargs)
         self._message_start: dict[str, Any] | None = None
+        self._tool_calls: dict[int, dict[str, Any]] = {}
 
     def _parse_chunk(self, event_data: dict[str, Any]) -> TextChunk | None:
-        """Parse one SSE event into a typed chunk (captures message_start)."""
+        """Parse one SSE event into a typed chunk (captures message_start and tool_use)."""
         event_type = event_data.get("type")
         if event_type == "message_start":
             message = event_data.get("message")
             if isinstance(message, dict):
                 self._message_start = message
             return None
+        if event_type == "content_block_start":
+            block = event_data.get("content_block", {})
+            if block.get("type") == "tool_use":
+                idx = event_data.get("index", len(self._tool_calls))
+                self._tool_calls[idx] = {
+                    "id": block.get("id", ""),
+                    "name": block.get("name", ""),
+                    "input_json": "",
+                }
+        elif event_type == "content_block_delta":
+            delta = event_data.get("delta", {})
+            if delta.get("type") == "input_json_delta":
+                idx = event_data.get("index", -1)
+                if idx in self._tool_calls:
+                    self._tool_calls[idx]["input_json"] += delta.get("partial_json", "")
         return super()._parse_chunk(event_data)
 
     def _aggregate_event_data(self, chunks: list[TextChunk]) -> list[dict[str, Any]]:
@@ -49,6 +67,21 @@ def _aggregate_event_data(self, chunks: list[TextChunk]) -> list[dict[str, Any]]
         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]:
+        """Reconstruct tool calls from accumulated content_block events."""
+        import json as _json
+
+        result: list[ToolCall] = []
+        for tc in self._tool_calls.values():
+            arguments = {}
+            if tc["input_json"]:
+                with contextlib.suppress(ValueError, TypeError):
+                    arguments = _json.loads(tc["input_json"])
+            result.append(ToolCall(id=tc["id"], name=tc["name"], arguments=arguments))
+        return result
+
 
 class AnthropicTextClient(AnthropicMessagesClient, TextClient):
     """Anthropic text client."""
@@ -86,10 +119,12 @@ def _init_request(self, inputs: TextInput) -> dict[str, Any]:
         if inputs.messages is not None:
             system_blocks: list[dict[str, Any]] = []
             messages: list[dict[str, Any]] = []
+            pending_tool_results: list[dict[str, Any]] = []
 
             for message in inputs.messages:
                 role = message.role
                 content = message.content
+
                 if role in {"system", "developer"}:
                     if isinstance(content, list):
                         for block in content:
@@ -105,8 +140,27 @@ def _init_request(self, inputs: TextInput) -> dict[str, Any]:
                         system_blocks.append({"type": "text", "text": str(content)})
                     continue
 
+                if isinstance(message, ToolResult):
+                    pending_tool_results.append(
+                        {
+                            "type": "tool_result",
+                            "tool_use_id": message.tool_call_id,
+                            "content": str(content),
+                        }
+                    )
+                    continue
+
+                # Flush pending tool results as a single user message
+                if pending_tool_results:
+                    messages.append({"role": "user", "content": pending_tool_results})
+                    pending_tool_results = []
+
                 messages.append({"role": role, "content": content})
 
+            # Flush remaining tool results
+            if pending_tool_results:
+                messages.append({"role": "user", "content": pending_tool_results})
+
             request: dict[str, Any] = {"messages": messages}
             if system_blocks:
                 request["system"] = system_blocks
@@ -166,6 +220,16 @@ def _parse_content(
 
         return text_content
 
+    def _parse_tool_calls(self, response_data: dict[str, Any]) -> list[ToolCall]:
+        """Parse tool calls from Anthropic response."""
+        return [
+            ToolCall(
+                id=block["id"], name=block["name"], arguments=block.get("input", {})
+            )
+            for block in response_data.get("content", [])
+            if block.get("type") == "tool_use"
+        ]
+
     def _stream_class(self) -> type[TextStream]:
         """Return the Stream class for this provider."""
         return AnthropicTextStream

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

@@ -1,8 +1,9 @@
 """Anthropic models for text modality."""
 
-from celeste.constraints import Bool, ImagesConstraint, Range, Schema
+from celeste.constraints import ImagesConstraint, Range, Schema, ToolSupport
 from celeste.core import Modality, Operation, Parameter, Provider
 from celeste.models import Model
+from celeste.tools import WebSearch
 
 from ...parameters import TextParameter
 
@@ -17,7 +18,7 @@
             Parameter.MAX_TOKENS: Range(min=1, max=64000),
             TextParameter.THINKING_BUDGET: Range(min=-1, max=64000),
             TextParameter.OUTPUT_SCHEMA: Schema(),
-            TextParameter.WEB_SEARCH: Bool(),
+            TextParameter.TOOLS: ToolSupport(tools=[WebSearch]),
             TextParameter.IMAGE: ImagesConstraint(),
         },
     ),
@@ -31,7 +32,7 @@
             Parameter.MAX_TOKENS: Range(min=1, max=64000),
             TextParameter.THINKING_BUDGET: Range(min=-1, max=32000),
             TextParameter.OUTPUT_SCHEMA: Schema(),
-            TextParameter.WEB_SEARCH: Bool(),
+            TextParameter.TOOLS: ToolSupport(tools=[WebSearch]),
             TextParameter.IMAGE: ImagesConstraint(),
         },
     ),
@@ -45,7 +46,7 @@
             Parameter.MAX_TOKENS: Range(min=1, max=32000),
             TextParameter.THINKING_BUDGET: Range(min=-1, max=32000),
             TextParameter.OUTPUT_SCHEMA: Schema(),
-            TextParameter.WEB_SEARCH: Bool(),
+            TextParameter.TOOLS: ToolSupport(tools=[WebSearch]),
             TextParameter.IMAGE: ImagesConstraint(),
         },
     ),
@@ -59,7 +60,7 @@
             Parameter.MAX_TOKENS: Range(min=1, max=64000),
             TextParameter.THINKING_BUDGET: Range(min=-1, max=32000),
             TextParameter.OUTPUT_SCHEMA: Schema(),
-            TextParameter.WEB_SEARCH: Bool(),
+            TextParameter.TOOLS: ToolSupport(tools=[WebSearch]),
             TextParameter.IMAGE: ImagesConstraint(),
         },
     ),
@@ -73,7 +74,7 @@
             Parameter.MAX_TOKENS: Range(min=1, max=64000),
             TextParameter.THINKING_BUDGET: Range(min=-1, max=32000),
             TextParameter.OUTPUT_SCHEMA: Schema(),
-            TextParameter.WEB_SEARCH: Bool(),
+            TextParameter.TOOLS: ToolSupport(tools=[WebSearch]),
             TextParameter.IMAGE: ImagesConstraint(),
         },
     ),
@@ -87,7 +88,7 @@
             Parameter.MAX_TOKENS: Range(min=1, max=64000),
             TextParameter.THINKING_BUDGET: Range(min=-1, max=64000),
             TextParameter.OUTPUT_SCHEMA: Schema(),
-            TextParameter.WEB_SEARCH: Bool(),
+            TextParameter.TOOLS: ToolSupport(tools=[WebSearch]),
             TextParameter.IMAGE: ImagesConstraint(),
         },
     ),
@@ -100,7 +101,7 @@
         parameter_constraints={
             Parameter.MAX_TOKENS: Range(min=1, max=64000),
             TextParameter.THINKING_BUDGET: Range(min=-1, max=64000),
-            TextParameter.WEB_SEARCH: Bool(),
+            TextParameter.TOOLS: ToolSupport(tools=[WebSearch]),
             TextParameter.IMAGE: ImagesConstraint(),
         },
     ),
@@ -113,7 +114,7 @@
         parameter_constraints={
             Parameter.MAX_TOKENS: Range(min=1, max=32000),
             TextParameter.THINKING_BUDGET: Range(min=-1, max=32000),
-            TextParameter.WEB_SEARCH: Bool(),
+            TextParameter.TOOLS: ToolSupport(tools=[WebSearch]),
             TextParameter.IMAGE: ImagesConstraint(),
         },
     ),