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

* 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

* test: add integration tests for tools= parameter

- WebSearch (non-streaming + streaming) across all 4 providers
- User-defined function tool with ToolCall parsing across all 4 providers
- xAI XSearch server-side tool
- Fix grok-3-mini model config: remove server-side tool support
  (xAI API only supports server-side tools on grok-4+ family)

* feat: add multi-turn tool calling support

* feat: shared tool call parsing for Chat Completions and OpenResponses protocols

Add protocol-level shared helpers so providers don't duplicate parsing logic:
- Chat Completions: parse_tool_calls, serialize_messages, ToolsMapper, streaming tool call deltas
- OpenResponses: parse_tool_calls, parse_text_content, serialize_messages
- ToolCall extra="allow" for provider-specific fields (e.g. Google thoughtSignature)
- Accept ToolResult in message lists for multi-turn tool conversations

* refactor: add ChatCompletionsTextClient protocol base class

Mirrors OpenResponsesTextClient — shared generate(), analyze(),
_init_request(), _parse_content(), _parse_tool_calls() for all Chat
Completions providers. DeepSeek, Groq, HuggingFace, Mistral, Moonshot
now inherit from it, keeping only parameter_mappers() and _stream_class()
overrides (Mistral also keeps _parse_content for thinking models).

Also renames parse_text_content → parse_content in OpenResponses tools.

* fix: correct Groq WebSearch wire format and add model tool support

Map WebSearch to browser_search (Groq's native format) and add
ToolSupport constraints to all Groq models. GPT-OSS models support
WebSearch and CodeExecution; others support user-defined function tools only.

* feat: add tool calling support for DeepSeek, Groq, HuggingFace, Mistral, Moonshot

Add ToolSupport constraints to all models and ToolsMapper parameter
mappers for the 5 Chat Completions providers. Groq GPT-OSS models
support WebSearch + CodeExecution, Moonshot models support WebSearch,
all others support user-defined function tools only.

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

* fix: use serialize_messages in OpenResponses provider _init_request methods

* refactor: remove provider-level OpenResponses text client, use protocol (#229)

OpenResponses is a protocol, not a provider. The provider-level
`modalities/text/providers/openresponses/` was a parallel hierarchy
that reimplemented tool call parsing inline instead of delegating to
the canonical `parse_tool_calls()` from the protocol layer. The inline
versions were also less robust (KeyError vs .get() with fallback).

OpenAI, xAI, and Ollama now inherit from the protocol-level
`OpenResponsesTextClient`, matching the ChatCompletions pattern where
DeepSeek, Groq, Mistral etc. inherit from `ChatCompletionsTextClient`.

Fixes #219

* fix: raise InvalidToolError for non-dict/non-Tool items in tools list (#218) (#228)

ToolsMapper.map() silently dropped items that were neither Tool instances
nor dicts (e.g. tools=[WebSearch] without ()). Add InvalidToolError and
else clause in all 4 ToolsMapper implementations.

* fix: add ToolSupport declarations to legacy OpenAI and xAI models (#232)

gpt-4-turbo, gpt-4, gpt-3.5-turbo, and grok-2-vision-1212 all support
tool calling but were missing TextParameter.TOOLS in their parameter
constraints. Added ToolSupport(tools=[]) so they properly advertise
tool support in model metadata.

Fixes #225

* fix: improve tool error messages (#226) (#234)

- Name the protocol in ChatCompletions error: "not supported by Chat Completions"
- ToolSupport with empty tools list now says "not supported by this model"
  instead of "Supported: []"

* fix: warn when WebSearch config fields are dropped by provider (#235)

Tool mappers now emit UnsupportedParameterWarning when a non-None
WebSearch field (e.g. blocked_domains, max_uses) is not supported by
the target provider. Each mapper declares _supported_fields so new
WebSearch fields automatically trigger warnings on providers that
don't map them.

Closes #231

* chore: bump version to 0.11.0

Unified tool calling across all providers — the bridge between LLM
reasoning and real-world action.

This release adds a single tools= parameter that works across 11
providers, replacing web_search/x_search/code_execution booleans.
Three tool shapes: built-in (WebSearch, XSearch, CodeExecution),
user-defined function dicts, and raw passthrough for provider-specific
tools. Streaming tool call deltas, multi-turn via ToolResult, and
full backward compatibility with deprecated param shims.

68 files changed, 8 new types, 2 protocol implementations.

Author: Kamilbenkirane

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "celeste-ai"
-version = "0.10.2"
+version = "0.11.0"
 description = "Open source, type-safe primitives for multi-modal AI. All capabilities, all providers, one interface"
 authors = [{name = "Kamilbenkirane", email = "kamil@withceleste.ai"}]
 readme = "README.md"

src/celeste/__init__.py

@@ -52,6 +52,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
 
@@ -246,6 +247,7 @@ def create_client(
     "Authentication",
     "Capability",
     "ClientNotFoundError",
+    "CodeExecution",
     "ConstraintViolationError",
     "Content",
     "Error",
@@ -271,15 +273,20 @@ def create_client(
     "StreamingNotSupportedError",
     "StrictJsonSchemaGenerator",
     "StrictRefResolvingJsonSchemaGenerator",
+    "Tool",
+    "ToolCall",
+    "ToolResult",
     "UnsupportedCapabilityError",
     "UnsupportedParameterError",
     "UnsupportedParameterWarning",
     "UnsupportedProviderError",
     "Usage",
     "UsageField",
     "ValidationError",
+    "WebSearch",
     "WebSocketClient",
     "WebSocketConnection",
+    "XSearch",
     "audio",
     "close_all_http_clients",
     "close_all_ws_clients",

src/celeste/client.py

@@ -19,6 +19,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
 
 
@@ -206,13 +207,19 @@ async def _predict(
         )
         content = self._parse_content(response_data)
         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,29 @@ 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:
+                if self.tools:
+                    supported = [t.__name__ for t in self.tools]
+                    msg = f"Tool '{type(item).__name__}' not supported. Supported: {supported}"
+                else:
+                    msg = f"Tool '{type(item).__name__}' is not supported by this model"
+                raise ConstraintViolationError(msg)
+        return value
+
+
 __all__ = [
     "AudioConstraint",
     "AudiosConstraint",
@@ -382,6 +406,7 @@ class AudiosConstraint(_MediaListConstraint[AudioMimeType]):
     "Range",
     "Schema",
     "Str",
+    "ToolSupport",
     "VideoConstraint",
     "VideosConstraint",
 ]

src/celeste/exceptions.py

@@ -233,6 +233,15 @@ def __init__(self, provider: str) -> None:
         )
 
 
+class InvalidToolError(ValidationError):
+    """Raised when a tool item is not a Tool instance or dict."""
+
+    def __init__(self, item: object) -> None:
+        """Initialize with the invalid item."""
+        self.item = item
+        super().__init__(f"Expected Tool instance or dict, got {type(item).__name__}")
+
+
 class UnsupportedParameterError(ValidationError):
     """Raised when a parameter is not supported by a model."""
 
@@ -253,6 +262,7 @@ class UnsupportedParameterWarning(UserWarning):
     "ClientNotFoundError",
     "ConstraintViolationError",
     "Error",
+    "InvalidToolError",
     "MissingCredentialsError",
     "MissingDependencyError",
     "ModalityNotFoundError",

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/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/io.py

@@ -10,14 +10,22 @@
 from pydantic import Field
 
 from celeste.io import Chunk, FinishReason, Input, Output, Usage
-from celeste.types import AudioContent, ImageContent, Message, TextContent, VideoContent
+from celeste.tools import ToolResult
+from celeste.types import (
+    AudioContent,
+    ImageContent,
+    Message,
+    Role,
+    TextContent,
+    VideoContent,
+)
 
 
 class TextInput(Input):
     """Input for text operations."""
 
     prompt: str | None = None
-    messages: list[Message] | None = None
+    messages: list[ToolResult | Message] | None = None
     text: str | list[str] | None = None
     image: ImageContent | None = None
     video: VideoContent | None = None
@@ -46,6 +54,15 @@ class TextOutput(Output[TextContent]):
     usage: TextUsage = Field(default_factory=TextUsage)
     finish_reason: TextFinishReason | None = None
 
+    @property
+    def message(self) -> Message:
+        """The assistant message for multi-turn conversations."""
+        return Message(
+            role=Role.ASSISTANT,
+            content=self.content,
+            tool_calls=self.tool_calls if self.tool_calls else None,
+        )
+
 
 class TextChunk(Chunk[str]):
     """Chunk for text streaming."""

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,8 +24,12 @@ class TextParameter(StrEnum):
     THINKING_BUDGET = "thinking_budget"
     THINKING_LEVEL = "thinking_level"
     OUTPUT_SCHEMA = "output_schema"
-    WEB_SEARCH = "web_search"
+    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"
 
@@ -46,8 +51,12 @@ class TextParameters(Parameters):
     thinking_budget: int | str
     thinking_level: str
     output_schema: type[BaseModel]
-    web_search: bool
+    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
 

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

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