feat: unified tools= parameter for tool calling

[Kamilbenkirane]

Context

Closes #191. Builds on the rescoped #150 (which separated primitives from framework concerns) and supersedes #147 (closed — auto-execution is a framework concern).

Philosophy: Celeste is primitives, not a framework. Tools are a parameter — celeste passes schemas to providers, normalizes responses into ToolCall objects, and returns them. It never auto-executes. This mirrors how the Anthropic SDK, OpenAI SDK, and Google GenAI SDK all work: they return raw tool calls and stop.

Sub-issues

Critical

• Fix silent item dropping in ToolsMapper for non-dict/non-Tool items #218 — Validate dict tools before sending to provider
• Remove duplicate tool call parsing in OpenResponses provider #219 — Remove duplicate tool call parsing in OpenResponses provider
• Add tests for deprecated tool parameter shims #221 — Add tests for deprecated tool parameter shims

High

• Expand tool calling test coverage across providers and error paths #222 — Expand tool calling test coverage across providers and error paths
• Tool mappers silently drop unsupported WebSearch config fields #231 — Tool mappers silently drop unsupported WebSearch config fields
• ToolSupport constraint doesn't validate dict tools #224 — ToolSupport constraint does not validate dict tools
• Fix model ToolSupport declarations for capable models #225 — Fix model ToolSupport declarations for capable models

Medium

• Model declarations, ToolDefinition export, and minor tool fixes #226 — Model declarations, ToolDefinition export, and minor tool fixes

Low

• Tool calling polish: streaming docs, error consistency, typing #227 — Tool calling polish: streaming docs, error consistency, typing

---

What changed

Replace three boolean parameters (web_search=True, x_search=True, code_execution=True) with a single tools= list parameter that accepts three tool shapes:

1. Tool classes — server-side tools mapped automatically

from celeste import WebSearch

output = await celeste.text.generate(
    "Search for latest Python release",
    model="claude-4-sonnet",
    tools=[WebSearch(blocked_domains=["reddit.com"])],
)

Tool class	Anthropic	OpenAI	Google	xAI
WebSearch	web_search_20250305	web_search	google_search	web_search
XSearch	—	x_search	—	x_search
CodeExecution	—	code_execution	code_execution	code_execution

2. User-defined function tools — dict with name

from pydantic import BaseModel

class WeatherParams(BaseModel):
    city: str

output = await celeste.text.generate(
    "What is the weather in Paris?",
    model="gpt-4.1",
    tools=[{"name": "get_weather", "description": "Get weather", "parameters": WeatherParams}],
)

output.tool_calls  # [ToolCall(id="call_xxx", name="get_weather", arguments={"city": "Paris"})]

3. Raw passthrough — dict without name

tools=[{"type": "bash_20250124"}]  # Anthropic computer use

Multi-turn tool use

from celeste import ToolResult
from celeste.types import Message, Role

tool_call = output.tool_calls[0]
weather = get_weather(tool_call.arguments["city"])

output2 = await celeste.text.generate(
    model="gpt-4.1",
    messages=[
        Message(role=Role.USER, content="What is the weather in Paris?"),
        Message(role=Role.ASSISTANT, content=output.content),
        ToolResult(content=weather, tool_call_id=tool_call.id, name="get_weather"),
    ],
    tools=[{"name": "get_weather", "description": "Get weather", "parameters": WeatherParams}],
)

Architecture

ToolMapper (parallel to ParameterMapper)

Each provider defines ToolMapper subclasses for the tools it supports. A single ToolsMapper (a ParameterMapper) dispatches to the right ToolMapper based on tool_type.

ToolSupport constraint

Model-level validation. Each model declares which Tool classes it supports:

TextParameter.TOOLS: ToolSupport(tools=[WebSearch, XSearch, CodeExecution])

Output parsing

• Non-streaming: _parse_tool_calls(response_data) — template method on base ModalityClient
• Streaming: _aggregate_tool_calls(chunks, raw_events) — template method on base Stream

Migration

# Before
output = await celeste.text.generate("...", model="claude-4-sonnet", web_search=True)

# After
from celeste import WebSearch
output = await celeste.text.generate("...", model="claude-4-sonnet", tools=[WebSearch()])

Test plan

• 507 unit tests pass
• All pre-commit hooks pass (ruff, mypy, bandit)
• Integration: tools=[WebSearch()] on each provider
• Integration: user-defined function tools with ToolCall parsing
• Integration: multi-turn ToolResult round-trip

[claude]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

[Kamilbenkirane]

Code review

Found 1 issue:

1. Multi-turn tool calling sends malformed assistant messages in OpenAI, xAI, and OpenResponses provider clients. When an assistant Message with tool_calls is passed back for multi-turn (e.g. output1.message), the else branch in _init_request calls msg.model_dump(), which produces {"role": "assistant", "content": "...", "tool_calls": [...]}. The Responses API expects assistant tool calls as separate {"type": "function_call", "name": ..., "arguments": ..., "call_id": ...} items in the input array. The protocol-level serialize_messages() in protocols/openresponses/tools.py handles this correctly (lines 96-113) but the provider-specific clients do not use it.

celeste-python/src/celeste/modalities/text/providers/openai/client.py

Lines 75 to 78 in 065a599

	)
	else:
	items.append(msg.model_dump())
	return {"input": items}

celeste-python/src/celeste/modalities/text/providers/xai/client.py

Lines 73 to 76 in 065a599

	)
	else:
	items.append(msg.model_dump())
	return {"input": items}

celeste-python/src/celeste/modalities/text/providers/openresponses/client.py

Lines 122 to 125 in 065a599

	)
	else:
	items.append(msg.model_dump())
	return {"input": items}

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}