diff --git a/src/conclave/adapters/__init__.py b/src/conclave/adapters/__init__.py index 114aa71..1add4be 100644 --- a/src/conclave/adapters/__init__.py +++ b/src/conclave/adapters/__init__.py @@ -25,7 +25,17 @@ from ..registry import PROVIDER_ENV_VARS, provider_prefix from .anthropic import AnthropicAdapter -from .base import OutputContract, ProviderAdapter, ProviderError, redact +from .base import ( + AgenticResponse, + OutputContract, + ProviderAdapter, + ProviderError, + ToolCall, + ToolSpec, + assistant_tool_call_message, + redact, + tool_result_message, +) from .gemini import GeminiAdapter from .openai_compat import OPENAI_COMPAT_URLS, OpenAICompatAdapter @@ -36,6 +46,11 @@ "ProviderAdapter", "ProviderError", "OutputContract", + "ToolSpec", + "ToolCall", + "AgenticResponse", + "assistant_tool_call_message", + "tool_result_message", "redact", "resolve_adapter", "OpenAICompatAdapter", diff --git a/src/conclave/adapters/anthropic.py b/src/conclave/adapters/anthropic.py index 7c64c16..1d199a3 100644 --- a/src/conclave/adapters/anthropic.py +++ b/src/conclave/adapters/anthropic.py @@ -33,7 +33,15 @@ from ..models import TokenUsage, categorize_http_status from ..provider_catalog import capabilities_for from ..registry import PROVIDER_ENV_VARS -from .base import OutputContract, ProviderError, SSEDelta, status_error +from .base import ( + AgenticResponse, + OutputContract, + ProviderError, + SSEDelta, + ToolCall, + ToolSpec, + status_error, +) logger = get_logger("adapters.anthropic") @@ -55,6 +63,7 @@ class AnthropicAdapter: prefix = "anthropic" completions_url = ANTHROPIC_URL supports_streaming = True + supports_tool_calls = True def __init__(self, max_tokens: int = DEFAULT_MAX_TOKENS) -> None: self.max_tokens = max_tokens @@ -112,15 +121,118 @@ def _tool_for_contract( "input_schema": output_contract.schema, } + @staticmethod + def _content_to_anthropic(content: object) -> object: + """Translate conclave's neutral content into Anthropic's block shape. + + A plain string passes through unchanged so every existing free-prose and + structured-output call builds a byte-identical body. A block list is + translated per block: + + * ``text`` -> ``{"type": "text", "text": ...}`` + * ``tool_call`` -> ``{"type": "tool_use", "id", "name", "input"}`` + * ``tool_result`` -> ``{"type": "tool_result", "tool_use_id", "content", + "is_error"}`` + + Anthropic correlates a result to its call by ``tool_use_id``; the id is + carried opaquely from the :class:`ToolCall` the model emitted and is + never reconstructed here. + """ + if not isinstance(content, list): + return content + blocks: list[dict] = [] + for block in content: + if not isinstance(block, dict): + blocks.append({"type": "text", "text": str(block)}) + continue + kind = block.get("type") + if kind == "tool_call": + blocks.append( + { + "type": "tool_use", + "id": block.get("id", ""), + "name": block.get("name", ""), + "input": block.get("arguments") or {}, + } + ) + elif kind == "tool_result": + result: dict = { + "type": "tool_result", + "tool_use_id": block.get("tool_call_id", ""), + "content": block.get("content", ""), + } + # Anthropic treats a missing is_error as False; send it only when + # True so a success result body stays minimal. + if block.get("is_error"): + result["is_error"] = True + blocks.append(result) + else: + blocks.append({"type": "text", "text": block.get("text", "")}) + return blocks + + @staticmethod + def _tools_to_anthropic(tools: list[ToolSpec]) -> list[dict]: + """Translate :class:`ToolSpec` declarations into Anthropic ``tools``.""" + return [ + {"name": t.name, "description": t.description, "input_schema": t.input_schema} + for t in tools + ] + + @staticmethod + def _tool_choice_to_anthropic(tool_choice: str | None) -> dict | None: + """Translate the neutral ``tool_choice`` into Anthropic's object form. + + ``None``/``"auto"`` -> omit (Anthropic's default is auto). ``"required"`` + -> ``{"type": "any"}``. ``"none"`` -> ``{"type": "none"}``. Anything else + is read as a specific tool name. + """ + if tool_choice in (None, "auto"): + return None + if tool_choice == "required": + return {"type": "any"} + if tool_choice == "none": + return {"type": "none"} + return {"type": "tool", "name": tool_choice} + + def _apply_agentic_tools( + self, + body: dict, + tools: list[ToolSpec] | None, + tool_choice: str | None, + output_contract: OutputContract | None, + ) -> None: + """Attach agentic tools to ``body`` in place, or leave it untouched. + + Raises: + ValueError: When ``tools`` and ``output_contract`` are both present. + Forced-tool structured output and model-chooses tool calling are + different modes; silently preferring one would make the caller's + intent unrecoverable. + """ + if not tools: + return + if output_contract is not None: + raise ValueError( + "tools and output_contract are mutually exclusive: " + "structured output uses a forced tool and cannot share the " + "tool slot with agentic tool calling" + ) + body["tools"] = self._tools_to_anthropic(tools) + choice = self._tool_choice_to_anthropic(tool_choice) + if choice is not None: + body["tool_choice"] = choice + def build_request( self, model_id: str, - messages: list[dict[str, str]], + messages: list[dict], temperature: float | None, timeout: float, api_key: str, output_contract: OutputContract | None = None, max_output_tokens: int | None = None, + tools: list[ToolSpec] | None = None, + tool_choice: str | None = None, ) -> tuple[str, dict[str, str], dict]: """Build the Messages POST, hoisting system out of the message array. @@ -147,10 +259,15 @@ def build_request( turns: list[dict[str, str]] = [] for msg in messages: role = msg.get("role") - content = msg.get("content", "") + content = self._content_to_anthropic(msg.get("content", "")) if role == "system": - if content: + # Only prose can be hoisted into the top-level system field; a + # block list in a system message is not representable there, so + # it stays in the array rather than being silently dropped. + if content and isinstance(content, str): system_parts.append(content) + elif content: + turns.append({"role": "user", "content": content}) elif role in ("user", "assistant"): turns.append({"role": role, "content": content}) else: # unknown role -> treat as user content so nothing is dropped @@ -178,6 +295,11 @@ def build_request( # Clear any stale flag from a prior build on this instance so a later # free-prose call never mistakenly parses a tool_use block. self._forced_tool_name = None + + # Agentic tools are the other tool-slot consumer. Mutually exclusive with + # the forced-contract tool above; _apply_agentic_tools raises rather than + # resolving the conflict silently. + self._apply_agentic_tools(body, tools, tool_choice, output_contract) return self.completions_url, headers, body def parse_response(self, status: int, payload: object) -> tuple[str, TokenUsage | None]: @@ -256,15 +378,85 @@ def _extract_tool_input(self, content: list, tool_name: str) -> str: raise ProviderError("anthropic: malformed tool_use block (input is not an object)") return json.dumps(tool_input, sort_keys=True) + # Anthropic stop_reason -> conclave's normalized vocabulary. Anything absent + # from this map is reported as "end_turn": an unrecognized reason means the + # turn ended for a reason we do not model, not that an error occurred. + _STOP_REASONS = { + "end_turn": "end_turn", + "tool_use": "tool_use", + "max_tokens": "max_tokens", + "stop_sequence": "end_turn", + "refusal": "refusal", + "pause_turn": "end_turn", + } + + def parse_agentic_response(self, status: int, payload: object) -> AgenticResponse: + """Parse a Messages response into an :class:`AgenticResponse`. + + Walks ``content[*]`` once, collecting ``text`` blocks into the prose and + ``tool_use`` blocks into :class:`ToolCall` records in emission order, so + parallel tool calls keep both their ordering and their ids. + + Unlike :meth:`parse_response`, this never consults + ``self._forced_tool_name``: a ``tool_use`` block here is a real agentic + call, not a structured-output smuggling channel. + + See :meth:`ProviderAdapter.parse_agentic_response`. + """ + if status >= 400 or not isinstance(payload, dict): + raise ProviderError( + status_error("anthropic", status, payload), + category=categorize_http_status(status), + http_status=status, + ) + + content = payload.get("content") + if not isinstance(content, list): + raise ProviderError( + "anthropic: response has no content blocks", + category="malformed_response", + http_status=status, + ) + + text_parts: list[str] = [] + calls: list[ToolCall] = [] + for block in content: + if not isinstance(block, dict): + continue + kind = block.get("type") + if kind == "text": + text_parts.append(block.get("text", "")) + elif kind == "tool_use": + arguments = block.get("input") + calls.append( + ToolCall( + id=str(block.get("id", "")), + name=str(block.get("name", "")), + arguments=arguments if isinstance(arguments, dict) else {}, + ) + ) + + raw_stop = payload.get("stop_reason") + stop_reason = self._STOP_REASONS.get(str(raw_stop), "end_turn") + + return AgenticResponse( + text="".join(text_parts), + tool_calls=tuple(calls), + usage=_parse_usage(payload.get("usage")), + stop_reason=stop_reason, + ) + def stream_request( self, model_id: str, - messages: list[dict[str, str]], + messages: list[dict], temperature: float | None, timeout: float, api_key: str, output_contract: OutputContract | None = None, max_output_tokens: int | None = None, + tools: list[ToolSpec] | None = None, + tool_choice: str | None = None, ) -> tuple[str, dict[str, str], dict]: """Build the streaming POST: ``build_request`` + ``stream: true``. @@ -282,6 +474,8 @@ def stream_request( api_key, output_contract=output_contract, max_output_tokens=max_output_tokens, + tools=tools, + tool_choice=tool_choice, ) body["stream"] = True return url, headers, body diff --git a/src/conclave/adapters/base.py b/src/conclave/adapters/base.py index e2d19b1..a27c25d 100644 --- a/src/conclave/adapters/base.py +++ b/src/conclave/adapters/base.py @@ -211,6 +211,129 @@ class OutputContract(BaseModel): repair_attempts: int = 1 +@dataclass(frozen=True) +class ToolSpec: + """One tool offered to the model for agentic (multi-turn) tool calling. + + This is conclave's provider-neutral tool declaration. Each adapter translates + it into its own wire shape (Anthropic ``tools[*]`` with ``input_schema``, + OpenAI ``tools[*].function.parameters``, Gemini ``functionDeclarations``). + + Distinct from :class:`OutputContract`, which uses a *forced* single tool as a + structured-output mechanism and expects exactly one result. A ``ToolSpec`` + list is the agentic surface: the model chooses whether and which to call, may + call several, and the caller is expected to execute them and send results + back for another turn. + + Attributes: + name: Tool identifier the model emits in its call. Provider-safe + characters only (letters, digits, underscore, hyphen). + description: What the tool does. This is prompt surface -- the model + selects on it, so it carries real weight. + input_schema: JSON Schema (object type) describing the arguments. + """ + + name: str + description: str + input_schema: dict + + +@dataclass(frozen=True) +class ToolCall: + """One tool invocation requested by the model. + + Attributes: + id: The provider's opaque call identifier. Carried end-to-end and echoed + back on the matching result so parallel calls stay correlated; never + parsed or reconstructed by conclave. + name: The :class:`ToolSpec` name being invoked. + arguments: Decoded argument object. Providers that stream arguments as a + JSON *string* (OpenAI shape) are decoded by their adapter, so callers + always receive a dict. + """ + + id: str + name: str + arguments: dict + + +@dataclass +class AgenticResponse: + """A parsed assistant turn that may contain tool calls as well as text. + + The agentic counterpart to :meth:`ProviderAdapter.parse_response`'s + ``(text, usage)`` tuple, which cannot represent a tool call. Returned by + :meth:`ProviderAdapter.parse_agentic_response`. + + Attributes: + text: Any assistant prose in this turn. May be empty when the model went + straight to a tool call. + tool_calls: Every tool call in this turn, in emission order. Empty when + the model answered directly. + usage: Token usage when the provider reported it. + stop_reason: Normalized stop reason -- one of ``"end_turn"``, + ``"tool_use"``, ``"max_tokens"``, ``"refusal"``, or ``"error"``. + Normalized by the adapter so the caller never branches on a + provider-specific string. + """ + + text: str = "" + tool_calls: tuple[ToolCall, ...] = () + usage: TokenUsage | None = None + stop_reason: str = "end_turn" + + +def assistant_tool_call_message( + text: str, tool_calls: tuple[ToolCall, ...] | list[ToolCall] +) -> dict: + """Build the assistant message that records a turn's tool calls. + + Appended to the message list before the matching tool results so the next + request carries the full call/result pairing the provider requires. Emits + conclave's neutral block form; the adapter translates it. + + Args: + text: Assistant prose from that turn, or ``""``. + tool_calls: The calls the model made, in emission order. + + Returns: + A message dict with ``role: "assistant"`` and a neutral content block list. + """ + blocks: list[dict] = [] + if text: + blocks.append({"type": "text", "text": text}) + for call in tool_calls: + blocks.append( + {"type": "tool_call", "id": call.id, "name": call.name, "arguments": call.arguments} + ) + return {"role": "assistant", "content": blocks} + + +def tool_result_message(results: list[tuple[str, str, bool]]) -> dict: + """Build the user-role message carrying tool results back to the model. + + Args: + results: ``(tool_call_id, content, is_error)`` triples, one per call being + answered. ``tool_call_id`` MUST equal the :class:`ToolCall` ``id`` the + model emitted; providers reject or mis-correlate otherwise. + + Returns: + A message dict with ``role: "user"`` and a neutral content block list. + """ + return { + "role": "user", + "content": [ + { + "type": "tool_result", + "tool_call_id": call_id, + "content": content, + "is_error": is_error, + } + for call_id, content, is_error in results + ], + } + + @dataclass class SSEDelta: """The result of interpreting one Server-Sent Event from a stream (issue #7). @@ -278,16 +401,24 @@ class ProviderAdapter(Protocol): env_vars: tuple[str, ...] completions_url: str supports_streaming: bool + # Whether this adapter implements the agentic tool-calling surface: the + # ``tools`` / ``tool_choice`` parameters below and + # :meth:`parse_agentic_response`. Adapters default to False and the agent + # loop must check this before offering tools -- never infer capability from + # a model name. + supports_tool_calls: bool def build_request( self, model_id: str, - messages: list[dict[str, str]], + messages: list[dict], temperature: float | None, timeout: float, api_key: str, output_contract: OutputContract | None = None, max_output_tokens: int | None = None, + tools: list[ToolSpec] | None = None, + tool_choice: str | None = None, ) -> tuple[str, dict[str, str], dict]: """Build ``(url, headers, json_body)`` for this provider. @@ -308,9 +439,24 @@ def build_request( ignores it. max_output_tokens: Optional per-call output ceiling. ``None`` keeps the adapter's existing provider default unchanged. + tools: Optional agentic tool declarations. ``None`` (default) keeps + the existing non-agentic behavior. Mutually exclusive with + ``output_contract`` -- a forced-tool structured-output call and + a model-chooses tool-calling call are different modes and + combining them is a caller error, not something to silently + resolve. Adapters reporting ``supports_tool_calls = False`` + raise :class:`ProviderError` when this is non-empty. + tool_choice: ``None`` or ``"auto"`` lets the model decide; + ``"required"`` forces some tool call; ``"none"`` forbids one. + A bare tool name forces that specific tool. Returns: A ``(url, headers, json_body)`` tuple ready for ``post_json``. + + Raises: + ValueError: When both ``tools`` and ``output_contract`` are given. + ProviderError: When ``tools`` is non-empty and this adapter reports + ``supports_tool_calls = False``. """ ... @@ -333,12 +479,14 @@ def parse_response(self, status: int, payload: object) -> tuple[str, TokenUsage def stream_request( self, model_id: str, - messages: list[dict[str, str]], + messages: list[dict], temperature: float | None, timeout: float, api_key: str, output_contract: OutputContract | None = None, max_output_tokens: int | None = None, + tools: list[ToolSpec] | None = None, + tool_choice: str | None = None, ) -> tuple[str, dict[str, str], dict]: """Build ``(url, headers, json_body)`` for a STREAMING request (issue #7). @@ -356,6 +504,28 @@ def stream_request( """ ... + def parse_agentic_response(self, status: int, payload: object) -> AgenticResponse: + """Parse a provider response into an :class:`AgenticResponse`. + + The agentic counterpart to :meth:`parse_response`, whose + ``(text, usage)`` return cannot represent a tool call. Adapters + reporting ``supports_tool_calls = False`` raise. + + Args: + status: HTTP status code returned by the transport. + payload: Decoded JSON object (or raw text on non-JSON responses). + + Returns: + An :class:`AgenticResponse` carrying text, any tool calls in + emission order, usage, and a normalized ``stop_reason``. + + Raises: + ProviderError: On non-2xx status, a malformed payload, or when this + adapter does not support agentic tool calling. The message is + already scrubbed of secrets. + """ + ... + def parse_sse_event(self, event: str, data: str) -> SSEDelta: """Interpret one raw SSE ``(event, data)`` pair into an :class:`SSEDelta`. diff --git a/src/conclave/adapters/gemini.py b/src/conclave/adapters/gemini.py index c5b629e..2615335 100644 --- a/src/conclave/adapters/gemini.py +++ b/src/conclave/adapters/gemini.py @@ -41,7 +41,14 @@ from ..models import TokenUsage, categorize_http_status from ..provider_catalog import capabilities_for from ..registry import PROVIDER_ENV_VARS -from .base import OutputContract, ProviderError, SSEDelta, status_error +from .base import ( + AgenticResponse, + OutputContract, + ProviderError, + SSEDelta, + ToolSpec, + status_error, +) GEMINI_BASE = "https://generativelanguage.googleapis.com/v1beta/models" DEFAULT_MAX_OUTPUT_TOKENS = 4096 @@ -212,6 +219,7 @@ class GeminiAdapter: # exposed for parity with the protocol's ``completions_url`` attribute. completions_url = GEMINI_BASE supports_streaming = True + supports_tool_calls = False def __init__(self, max_output_tokens: int = DEFAULT_MAX_OUTPUT_TOKENS) -> None: self.max_output_tokens = max_output_tokens @@ -285,12 +293,14 @@ def _apply_output_contract( def build_request( self, model_id: str, - messages: list[dict[str, str]], + messages: list[dict], temperature: float | None, timeout: float, api_key: str, output_contract: OutputContract | None = None, max_output_tokens: int | None = None, + tools: list[ToolSpec] | None = None, + tool_choice: str | None = None, ) -> tuple[str, dict[str, str], dict]: """Build the generateContent POST. @@ -302,6 +312,13 @@ def build_request( ``output_contract is None`` the body is byte-for-byte the legacy shape. See :meth:`ProviderAdapter.build_request`. """ + if tools: + raise ProviderError( + f"{self.prefix}: agentic tool calling is not implemented for this " + "provider yet (CAC-02 covers Anthropic first); check " + "adapter.supports_tool_calls before offering tools", + category="malformed_response", + ) model = self._bare_model(model_id) url = f"{GEMINI_BASE}/{model}:generateContent" headers = { @@ -371,12 +388,14 @@ def parse_response(self, status: int, payload: object) -> tuple[str, TokenUsage def stream_request( self, model_id: str, - messages: list[dict[str, str]], + messages: list[dict], temperature: float | None, timeout: float, api_key: str, output_contract: OutputContract | None = None, max_output_tokens: int | None = None, + tools: list[ToolSpec] | None = None, + tool_choice: str | None = None, ) -> tuple[str, dict[str, str], dict]: """Build the streaming POST against ``streamGenerateContent?alt=sse``. @@ -387,6 +406,13 @@ def stream_request( against the Gemini API streaming reference). See :meth:`ProviderAdapter.stream_request`. """ + if tools: + raise ProviderError( + f"{self.prefix}: agentic tool calling is not implemented for this " + "provider yet (CAC-02 covers Anthropic first); check " + "adapter.supports_tool_calls before offering tools", + category="malformed_response", + ) # output_contract flows into build_request, which performs the # capability-gated responseMimeType/responseSchema injection. _url, headers, body = self.build_request( @@ -402,6 +428,20 @@ def stream_request( url = f"{GEMINI_BASE}/{model}:streamGenerateContent?alt=sse" return url, headers, body + def parse_agentic_response(self, status: int, payload: object) -> AgenticResponse: + """Not implemented for this provider; see :attr:`supports_tool_calls`. + + Raises: + ProviderError: Always. Agentic tool calling lands provider by + provider (CAC-02-OAI / CAC-02-GEM); callers must gate on + ``supports_tool_calls`` rather than calling this speculatively. + """ + raise ProviderError( + f"{self.prefix}: parse_agentic_response is not implemented for this " + "provider yet; gate on adapter.supports_tool_calls", + category="malformed_response", + ) + def parse_sse_event(self, event: str, data: str) -> SSEDelta: """Parse one Gemini SSE frame (a partial ``GenerateContentResponse``). diff --git a/src/conclave/adapters/openai_compat.py b/src/conclave/adapters/openai_compat.py index 3d826dd..d3e89dd 100644 --- a/src/conclave/adapters/openai_compat.py +++ b/src/conclave/adapters/openai_compat.py @@ -28,7 +28,14 @@ from ..logging import get_logger from ..models import TokenUsage, categorize_http_status from ..provider_catalog import capabilities_for -from .base import OutputContract, ProviderError, SSEDelta, status_error +from .base import ( + AgenticResponse, + OutputContract, + ProviderError, + SSEDelta, + ToolSpec, + status_error, +) logger = get_logger(__name__) @@ -69,6 +76,7 @@ class OpenAICompatAdapter: # Every OpenAI-compatible vendor conclave ships speaks the standard # streaming protocol (``stream: true`` -> SSE deltas -> ``[DONE]``). supports_streaming = True + supports_tool_calls = False def __init__( self, @@ -173,12 +181,14 @@ def _apply_output_contract( def build_request( self, model_id: str, - messages: list[dict[str, str]], + messages: list[dict], temperature: float | None, timeout: float, api_key: str, output_contract: OutputContract | None = None, max_output_tokens: int | None = None, + tools: list[ToolSpec] | None = None, + tool_choice: str | None = None, ) -> tuple[str, dict[str, str], dict]: """Build the OpenAI-style POST. @@ -187,6 +197,13 @@ def build_request( reject an explicit ``temperature`` with a 400). See :meth:`ProviderAdapter.build_request`. """ + if tools: + raise ProviderError( + f"{self.prefix}: agentic tool calling is not implemented for this " + "provider yet (CAC-02 covers Anthropic first); check " + "adapter.supports_tool_calls before offering tools", + category="malformed_response", + ) headers = { "Authorization": f"Bearer {api_key}", "Content-Type": "application/json", @@ -239,12 +256,14 @@ def parse_response(self, status: int, payload: object) -> tuple[str, TokenUsage def stream_request( self, model_id: str, - messages: list[dict[str, str]], + messages: list[dict], temperature: float | None, timeout: float, api_key: str, output_contract: OutputContract | None = None, max_output_tokens: int | None = None, + tools: list[ToolSpec] | None = None, + tool_choice: str | None = None, ) -> tuple[str, dict[str, str], dict]: """Build the streaming POST: ``build_request`` + ``stream`` flags. @@ -254,6 +273,13 @@ def stream_request( (verified against the OpenAI chat-completions streaming reference). See :meth:`ProviderAdapter.stream_request`. """ + if tools: + raise ProviderError( + f"{self.prefix}: agentic tool calling is not implemented for this " + "provider yet (CAC-02 covers Anthropic first); check " + "adapter.supports_tool_calls before offering tools", + category="malformed_response", + ) # output_contract is passed through to build_request, which applies the # capability-gated ``response_format`` shaping (compatible with # stream:true). Stream flags are layered on top of the shaped body. @@ -270,6 +296,20 @@ def stream_request( body["stream_options"] = {"include_usage": True} return url, headers, body + def parse_agentic_response(self, status: int, payload: object) -> AgenticResponse: + """Not implemented for this provider; see :attr:`supports_tool_calls`. + + Raises: + ProviderError: Always. Agentic tool calling lands provider by + provider (CAC-02-OAI / CAC-02-GEM); callers must gate on + ``supports_tool_calls`` rather than calling this speculatively. + """ + raise ProviderError( + f"{self.prefix}: parse_agentic_response is not implemented for this " + "provider yet; gate on adapter.supports_tool_calls", + category="malformed_response", + ) + def parse_sse_event(self, event: str, data: str) -> SSEDelta: """Parse one OpenAI-style SSE frame. diff --git a/tests/test_agentic_tools.py b/tests/test_agentic_tools.py new file mode 100644 index 0000000..365a304 --- /dev/null +++ b/tests/test_agentic_tools.py @@ -0,0 +1,323 @@ +"""Agentic tool-calling surface (CAC-02, DSE-1807). + +Covers the additive surface only: :class:`ToolSpec` declarations, the neutral +content-block helpers, Anthropic's wire translation, and +``parse_agentic_response``. The pre-existing ``build_request`` / +``parse_response`` contract is asserted unchanged here too, because the whole +point of making this surface additive is that the 468 existing tests keep +passing untouched. +""" + +from __future__ import annotations + +import pytest + +from conclave.adapters import ( + AgenticResponse, + ToolCall, + ToolSpec, + assistant_tool_call_message, + tool_result_message, +) +from conclave.adapters.anthropic import AnthropicAdapter +from conclave.adapters.base import OutputContract, ProviderError +from conclave.adapters.gemini import GeminiAdapter +from conclave.adapters.openai_compat import OpenAICompatAdapter + +WEATHER = ToolSpec( + name="get_weather", + description="Look up the current weather for a city.", + input_schema={ + "type": "object", + "properties": {"city": {"type": "string"}}, + "required": ["city"], + }, +) +READ = ToolSpec( + name="read_file", + description="Read a file from disk.", + input_schema={"type": "object", "properties": {"path": {"type": "string"}}}, +) + + +@pytest.fixture +def anthropic() -> AnthropicAdapter: + return AnthropicAdapter() + + +@pytest.fixture +def openai() -> OpenAICompatAdapter: + return OpenAICompatAdapter( + prefix="openai", + completions_url="https://api.openai.com/v1/chat/completions", + env_vars=("OPENAI_API_KEY",), + ) + + +def _build(adapter, messages, **kw): + return adapter.build_request( + "anthropic/claude-sonnet-5", messages, None, 30.0, "test-key", **kw + ) + + +# -------------------------------------------------------------------------- +# Capability flags +# -------------------------------------------------------------------------- + + +def test_only_anthropic_advertises_tool_calls(anthropic, openai): + """Capability is declared, never inferred from a model name.""" + assert anthropic.supports_tool_calls is True + assert openai.supports_tool_calls is False + assert GeminiAdapter().supports_tool_calls is False + + +# -------------------------------------------------------------------------- +# Neutral block helpers +# -------------------------------------------------------------------------- + + +def test_assistant_tool_call_message_orders_text_then_calls(): + call = ToolCall(id="toolu_01", name="get_weather", arguments={"city": "Atlanta"}) + msg = assistant_tool_call_message("Let me check.", [call]) + assert msg["role"] == "assistant" + assert msg["content"] == [ + {"type": "text", "text": "Let me check."}, + { + "type": "tool_call", + "id": "toolu_01", + "name": "get_weather", + "arguments": {"city": "Atlanta"}, + }, + ] + + +def test_assistant_tool_call_message_omits_empty_text(): + """A model that goes straight to a call must not emit an empty text block.""" + call = ToolCall(id="toolu_01", name="get_weather", arguments={}) + assert assistant_tool_call_message("", [call])["content"] == [ + {"type": "tool_call", "id": "toolu_01", "name": "get_weather", "arguments": {}} + ] + + +def test_tool_result_message_preserves_ids_and_order(): + msg = tool_result_message([("toolu_01", "72F", False), ("toolu_02", "boom", True)]) + assert msg["role"] == "user" + assert [b["tool_call_id"] for b in msg["content"]] == ["toolu_01", "toolu_02"] + assert msg["content"][1]["is_error"] is True + + +# -------------------------------------------------------------------------- +# Anthropic request translation +# -------------------------------------------------------------------------- + + +def test_tools_translate_to_anthropic_input_schema(anthropic): + _, _, body = _build(anthropic, [{"role": "user", "content": "hi"}], tools=[WEATHER, READ]) + assert body["tools"] == [ + { + "name": "get_weather", + "description": WEATHER.description, + "input_schema": WEATHER.input_schema, + }, + {"name": "read_file", "description": READ.description, "input_schema": READ.input_schema}, + ] + # auto is Anthropic's default; the key is omitted rather than sent explicitly. + assert "tool_choice" not in body + + +@pytest.mark.parametrize( + ("neutral", "expected"), + [ + ("required", {"type": "any"}), + ("none", {"type": "none"}), + ("get_weather", {"type": "tool", "name": "get_weather"}), + ], +) +def test_tool_choice_translation(anthropic, neutral, expected): + _, _, body = _build( + anthropic, [{"role": "user", "content": "hi"}], tools=[WEATHER], tool_choice=neutral + ) + assert body["tool_choice"] == expected + + +def test_tool_call_and_result_blocks_reach_the_wire(anthropic): + """A full call/result round trip keeps ids correlated end-to-end.""" + call = ToolCall(id="toolu_abc", name="get_weather", arguments={"city": "Atlanta"}) + messages = [ + {"role": "user", "content": "weather?"}, + assistant_tool_call_message("Checking.", [call]), + tool_result_message([("toolu_abc", "72F and clear", False)]), + ] + _, _, body = _build(anthropic, messages, tools=[WEATHER]) + + assistant = body["messages"][1] + assert assistant["content"][1] == { + "type": "tool_use", + "id": "toolu_abc", + "name": "get_weather", + "input": {"city": "Atlanta"}, + } + result = body["messages"][2]["content"][0] + assert result == { + "type": "tool_result", + "tool_use_id": "toolu_abc", + "content": "72F and clear", + } + # is_error is omitted on success so a normal result body stays minimal. + assert "is_error" not in result + + +def test_error_result_carries_is_error(anthropic): + messages = [tool_result_message([("toolu_abc", "ENOENT", True)])] + _, _, body = _build(anthropic, messages, tools=[READ]) + assert body["messages"][0]["content"][0]["is_error"] is True + + +def test_tools_and_output_contract_are_mutually_exclusive(anthropic): + """Silently preferring one mode would make the caller's intent unrecoverable.""" + with pytest.raises(ValueError, match="mutually exclusive"): + _build( + anthropic, + [{"role": "user", "content": "hi"}], + tools=[WEATHER], + output_contract=OutputContract(schema={"type": "object"}), + ) + + +def test_string_content_body_is_unchanged_by_the_new_surface(anthropic): + """The additive guarantee: no tools means a byte-identical legacy body.""" + messages = [{"role": "system", "content": "be brief"}, {"role": "user", "content": "hi"}] + _, _, before = _build(anthropic, messages) + _, _, after = _build(anthropic, messages, tools=None) + assert before == after + assert before["system"] == "be brief" + assert before["messages"] == [{"role": "user", "content": "hi"}] + assert "tools" not in before + + +def test_stream_request_forwards_tools(anthropic): + _, _, body = anthropic.stream_request( + "anthropic/claude-sonnet-5", + [{"role": "user", "content": "hi"}], + None, + 30.0, + "test-key", + tools=[WEATHER], + ) + assert body["stream"] is True + assert body["tools"][0]["name"] == "get_weather" + + +# -------------------------------------------------------------------------- +# Anthropic response parsing +# -------------------------------------------------------------------------- + + +def test_parse_agentic_response_extracts_parallel_calls_in_order(anthropic): + payload = { + "content": [ + {"type": "text", "text": "Checking both."}, + {"type": "tool_use", "id": "toolu_1", "name": "get_weather", "input": {"city": "ATL"}}, + {"type": "tool_use", "id": "toolu_2", "name": "read_file", "input": {"path": "/x"}}, + ], + "stop_reason": "tool_use", + "usage": {"input_tokens": 100, "output_tokens": 20}, + } + out = anthropic.parse_agentic_response(200, payload) + assert isinstance(out, AgenticResponse) + assert out.text == "Checking both." + assert [c.id for c in out.tool_calls] == ["toolu_1", "toolu_2"] + assert out.tool_calls[0].arguments == {"city": "ATL"} + assert out.stop_reason == "tool_use" + assert out.usage is not None + + +def test_parse_agentic_response_plain_answer(anthropic): + out = anthropic.parse_agentic_response( + 200, {"content": [{"type": "text", "text": "42"}], "stop_reason": "end_turn"} + ) + assert out.text == "42" + assert out.tool_calls == () + assert out.stop_reason == "end_turn" + + +@pytest.mark.parametrize( + ("raw", "normalized"), + [ + ("end_turn", "end_turn"), + ("tool_use", "tool_use"), + ("max_tokens", "max_tokens"), + ("stop_sequence", "end_turn"), + ("refusal", "refusal"), + ("something_new", "end_turn"), + ], +) +def test_stop_reason_is_normalized(anthropic, raw, normalized): + """An unrecognized reason means unmodelled, not failed.""" + out = anthropic.parse_agentic_response(200, {"content": [], "stop_reason": raw}) + assert out.stop_reason == normalized + + +def test_parse_agentic_response_ignores_forced_tool_state(anthropic): + """A tool_use block here is a real call, not structured-output smuggling.""" + _build( + anthropic, + [{"role": "user", "content": "hi"}], + output_contract=OutputContract(schema={"type": "object"}), + ) + out = anthropic.parse_agentic_response( + 200, + { + "content": [{"type": "tool_use", "id": "t1", "name": "get_weather", "input": {}}], + "stop_reason": "tool_use", + }, + ) + assert out.tool_calls[0].name == "get_weather" + + +def test_parse_agentic_response_raises_on_http_error(anthropic): + with pytest.raises(ProviderError): + anthropic.parse_agentic_response(429, {"error": {"message": "slow down"}}) + + +def test_parse_agentic_response_raises_on_missing_content(anthropic): + with pytest.raises(ProviderError, match="no content blocks"): + anthropic.parse_agentic_response(200, {"stop_reason": "end_turn"}) + + +def test_malformed_tool_input_degrades_to_empty_dict(anthropic): + """A non-object input must not crash the loop; callers always get a dict.""" + out = anthropic.parse_agentic_response( + 200, + { + "content": [{"type": "tool_use", "id": "t1", "name": "x", "input": "not-an-object"}], + "stop_reason": "tool_use", + }, + ) + assert out.tool_calls[0].arguments == {} + + +# -------------------------------------------------------------------------- +# Unimplemented providers fail loudly, not silently +# -------------------------------------------------------------------------- + + +def test_unsupported_provider_rejects_tools(openai): + with pytest.raises(ProviderError, match="supports_tool_calls"): + openai.build_request( + "openai/gpt-5.6", [{"role": "user", "content": "hi"}], None, 30.0, "k", tools=[WEATHER] + ) + + +def test_unsupported_provider_rejects_agentic_parse(openai): + with pytest.raises(ProviderError, match="supports_tool_calls"): + openai.parse_agentic_response(200, {"choices": []}) + + +def test_unsupported_provider_without_tools_still_works(openai): + """The guard must not disturb the existing non-agentic path.""" + _, _, body = openai.build_request( + "openai/gpt-5.6", [{"role": "user", "content": "hi"}], None, 30.0, "k" + ) + assert body["messages"] == [{"role": "user", "content": "hi"}]