From 838e51f903698eb8e9c1ff4ee851ec85f45b1f7e Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Wed, 28 Oct 2026 01:59:29 -0700 Subject: [PATCH] fix(tool_choice): accept allowed_tools in both OpenAI shapes and translate it per endpoint The chat completions validator now takes the nested chat shape and the flat Responses shape and returns the nested one. The Responses bridge sends the flat shape. Providers other than openai, azure and litellm_proxy raise UnsupportedParamsError, or drop the choice under drop_params. --- .../transformation.py | 17 ++- .../allowed_tools_tool_choice.py | 83 ++++++++++++++ litellm/utils.py | 33 ++++-- ...responses_transformation_transformation.py | 26 +++++ tests/unit/test_utils.py | 102 ++++++++++++++++++ tests/unit/test_validate_tool_choice.py | 93 ---------------- 6 files changed, 252 insertions(+), 102 deletions(-) create mode 100644 litellm/litellm_core_utils/allowed_tools_tool_choice.py delete mode 100644 tests/unit/test_validate_tool_choice.py diff --git a/litellm/completion_extras/litellm_responses_transformation/transformation.py b/litellm/completion_extras/litellm_responses_transformation/transformation.py index 98322aecf6a..ac86833d3f5 100644 --- a/litellm/completion_extras/litellm_responses_transformation/transformation.py +++ b/litellm/completion_extras/litellm_responses_transformation/transformation.py @@ -5,6 +5,7 @@ Handler for transforming /chat/completions api requests to litellm.responses req import json import os from collections.abc import AsyncIterator, Callable, Iterable, Iterator, Mapping, Sequence +from contextlib import suppress from itertools import accumulate, chain from types import MappingProxyType from typing import TYPE_CHECKING, Any, Final, Literal, TypedDict, TypeVar, Union, cast @@ -17,6 +18,7 @@ from openai.types.responses.response_input_param import ( ResponseCustomToolCallOutputParam, ResponseCustomToolCallParam, ) +from openai.types.responses.tool_choice_allowed_param import ToolChoiceAllowedParam from openai.types.responses.tool_choice_custom_param import ToolChoiceCustomParam from openai.types.responses.tool_choice_function_param import ToolChoiceFunctionParam from openai.types.responses.tool_param import FunctionToolParam @@ -26,6 +28,10 @@ import litellm from litellm import ModelResponse from litellm._logging import verbose_logger from litellm.integrations.anthropic_cache_control_hook import supports_openai_prompt_cache_breakpoint +from litellm.litellm_core_utils.allowed_tools_tool_choice import ( + ALLOWED_TOOL_CHOICE_ADAPTER, + to_responses_allowed_tool_choice, +) from litellm.litellm_core_utils.hidden_params import get_hidden_params, get_or_create_hidden_params from litellm.litellm_core_utils.prompt_templates.common_utils import ( responses_reasoning_items_from_thinking_blocks, @@ -732,13 +738,22 @@ class LiteLLMResponsesTransformationHandler(CompletionTransformationBridge): def _normalize_tool_choice_for_responses_api( self, tool_choice: _ToolChoiceT - ) -> _ToolChoiceT | ToolChoiceFunctionParam | ToolChoiceCustomParam | Literal["auto", "none", "required"]: + ) -> ( + _ToolChoiceT + | ToolChoiceFunctionParam + | ToolChoiceCustomParam + | ToolChoiceAllowedParam + | Literal["auto", "none", "required"] + ): """Chat tool_choice nests the name under function/custom; Responses API expects top-level name.""" if not isinstance(tool_choice, dict): return tool_choice choice_type: Final = tool_choice.get("type") if isinstance(choice_type, str) and choice_type in ("auto", "none", "required"): return choice_type + if choice_type == "allowed_tools": + with suppress(ValidationError): + return to_responses_allowed_tool_choice(ALLOWED_TOOL_CHOICE_ADAPTER.validate_python(tool_choice)) if choice_type not in ("function", "custom"): return tool_choice if isinstance(tool_choice.get("name"), str) and tool_choice.get("name"): diff --git a/litellm/litellm_core_utils/allowed_tools_tool_choice.py b/litellm/litellm_core_utils/allowed_tools_tool_choice.py new file mode 100644 index 00000000000..a8b670eed1f --- /dev/null +++ b/litellm/litellm_core_utils/allowed_tools_tool_choice.py @@ -0,0 +1,83 @@ +from collections.abc import Mapping +from typing import Final, Literal, TypeAlias + +from openai.types.chat.chat_completion_allowed_tool_choice_param import ChatCompletionAllowedToolChoiceParam +from openai.types.chat.chat_completion_allowed_tools_param import ChatCompletionAllowedToolsParam +from openai.types.responses.tool_choice_allowed_param import ToolChoiceAllowedParam +from pydantic import BaseModel, ConfigDict, TypeAdapter + +PROVIDERS_ACCEPTING_ALLOWED_TOOLS: Final = frozenset({"openai", "azure", "litellm_proxy"}) + + +class _AllowedTools(BaseModel): + model_config = ConfigDict(frozen=True) + + mode: Literal["auto", "required"] + tools: tuple[Mapping[str, object], ...] + + +class _ChatAllowedToolChoice(BaseModel): + model_config = ConfigDict(frozen=True) + + type: Literal["allowed_tools"] + allowed_tools: _AllowedTools + + +class _ResponsesAllowedToolChoice(BaseModel): + model_config = ConfigDict(frozen=True) + + type: Literal["allowed_tools"] + mode: Literal["auto", "required"] + tools: tuple[Mapping[str, object], ...] + + +AllowedToolChoice: TypeAlias = _ChatAllowedToolChoice | _ResponsesAllowedToolChoice + +ALLOWED_TOOL_CHOICE_ADAPTER: Final[TypeAdapter[AllowedToolChoice]] = TypeAdapter(AllowedToolChoice) + + +def _allowed_tools(choice: AllowedToolChoice) -> _AllowedTools: + match choice: + case _ChatAllowedToolChoice(allowed_tools=allowed_tools): + return allowed_tools + case _ResponsesAllowedToolChoice(mode=mode, tools=tools): + return _AllowedTools(mode=mode, tools=tools) + + +def _chat_tool(tool: Mapping[str, object]) -> Mapping[str, object]: + match tool: + case {"type": "function", "name": str() as function_name}: + return {"type": "function", "function": {"name": function_name}} + case {"type": "custom", "name": str() as custom_name}: + return {"type": "custom", "custom": {"name": custom_name}} + case _: + return tool + + +def _responses_tool(tool: Mapping[str, object]) -> Mapping[str, object]: + match tool: + case {"type": "function", "function": {"name": str() as function_name}}: + return {"type": "function", "name": function_name} + case {"type": "custom", "custom": {"name": str() as custom_name}}: + return {"type": "custom", "name": custom_name} + case _: + return tool + + +def to_chat_allowed_tool_choice(choice: AllowedToolChoice) -> ChatCompletionAllowedToolChoiceParam: + allowed_tools: Final = _allowed_tools(choice) + return ChatCompletionAllowedToolChoiceParam( + type="allowed_tools", + allowed_tools=ChatCompletionAllowedToolsParam( + mode=allowed_tools.mode, tools=[dict(_chat_tool(tool)) for tool in allowed_tools.tools] + ), + ) + + +def to_responses_allowed_tool_choice(choice: AllowedToolChoice) -> ToolChoiceAllowedParam: + allowed_tools: Final = _allowed_tools(choice) + return ToolChoiceAllowedParam( + type="allowed_tools", + mode=allowed_tools.mode, + tools=[dict(_responses_tool(tool)) for tool in allowed_tools.tools], + ) diff --git a/litellm/utils.py b/litellm/utils.py index a04b3109d7a..58b1e40f744 100644 --- a/litellm/utils.py +++ b/litellm/utils.py @@ -82,6 +82,11 @@ from litellm.constants import ( PROVIDERS_THAT_AUTHENTICATE_ON_PROVIDER_INFO, TOOL_CHOICE_OBJECT_TOKEN_COUNT, ) +from litellm.litellm_core_utils.allowed_tools_tool_choice import ( + ALLOWED_TOOL_CHOICE_ADAPTER, + PROVIDERS_ACCEPTING_ALLOWED_TOOLS, + to_chat_allowed_tool_choice, +) from litellm.litellm_core_utils.core_helpers import ( bind_budget_reservation_to_callbacks, normalize_drop_params, @@ -5102,6 +5107,17 @@ def get_optional_params( _check_valid_arg( supported_params=supported_params or [], ) + match non_default_params: + case {"tool_choice": {"type": "allowed_tools"}} if custom_llm_provider not in PROVIDERS_ACCEPTING_ALLOWED_TOOLS: + if litellm.drop_params is not True and drop_params is not True: + raise UnsupportedParamsError( + message=f"{custom_llm_provider} does not support an allowed_tools tool_choice, for model={model}. To drop it, set `litellm.drop_params=True` or for proxy:\n\n`litellm_settings:\n drop_params: true`\n", + model=model, + llm_provider=custom_llm_provider, + ) + del non_default_params["tool_choice"] + case dict(): + pass ## raise exception if provider doesn't support passed in param if custom_llm_provider == "anthropic": ## check if unsupported param passed in @@ -9015,14 +9031,15 @@ def validate_chat_completion_tool_choice( if tool_choice_type in ("auto", "none", "required") and "function" not in tool_choice: return tool_choice_type - # OpenAI also allows constraining which tools the model may call: - # {"type": "allowed_tools", "allowed_tools": {"mode": ..., "tools": [...]}}. - # Pass it through untouched so downstream providers see the full payload. - if tool_choice_type == "allowed_tools" and isinstance( - tool_choice.get("allowed_tools"), # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType] # raw dict payload - dict, - ): - return tool_choice # pyright: ignore[reportUnknownVariableType] # narrowed raw dict payload + if tool_choice_type == "allowed_tools": + try: + return dict(to_chat_allowed_tool_choice(ALLOWED_TOOL_CHOICE_ADAPTER.validate_python(tool_choice))) + except ValidationError as exc: + raise BadRequestError( + message=f"Invalid tool choice, tool_choice={tool_choice}. Please ensure tool_choice follows the OpenAI spec. {exc}", + model=model, + llm_provider="", + ) from exc # Standard OpenAI format: {"type": "function", "function": {...}} if tool_choice.get("type") is None or tool_choice.get("function") is None: diff --git a/tests/unit/completion_extras/litellm_responses_transformation/test_completion_extras_litellm_responses_transformation_transformation.py b/tests/unit/completion_extras/litellm_responses_transformation/test_completion_extras_litellm_responses_transformation_transformation.py index 9aa494c1aab..bee3f025533 100644 --- a/tests/unit/completion_extras/litellm_responses_transformation/test_completion_extras_litellm_responses_transformation_transformation.py +++ b/tests/unit/completion_extras/litellm_responses_transformation/test_completion_extras_litellm_responses_transformation_transformation.py @@ -4015,6 +4015,32 @@ def test_output_item_done_with_stream_map_keeps_empty_delta(): ({"type": "required"}, "required"), ("auto", "auto"), ({"type": "function", "function": {"name": "get_weather"}}, {"type": "function", "name": "get_weather"}), + ( + { + "type": "allowed_tools", + "allowed_tools": { + "mode": "required", + "tools": [ + {"type": "function", "function": {"name": "get_weather"}}, + {"type": "custom", "custom": {"name": "apply_patch"}}, + {"type": "mcp", "server_label": "deepwiki"}, + ], + }, + }, + { + "type": "allowed_tools", + "mode": "required", + "tools": [ + {"type": "function", "name": "get_weather"}, + {"type": "custom", "name": "apply_patch"}, + {"type": "mcp", "server_label": "deepwiki"}, + ], + }, + ), + ( + {"type": "allowed_tools", "mode": "auto", "tools": [{"type": "function", "name": "get_weather"}]}, + {"type": "allowed_tools", "mode": "auto", "tools": [{"type": "function", "name": "get_weather"}]}, + ), ], ) async def test_acompletion_bridge_normalizes_tool_choice_on_the_wire( diff --git a/tests/unit/test_utils.py b/tests/unit/test_utils.py index 38287b25169..0100883687c 100644 --- a/tests/unit/test_utils.py +++ b/tests/unit/test_utils.py @@ -101,6 +101,7 @@ from litellm.utils import ( calculate_max_parallel_requests, client, get_non_default_completion_params, + get_optional_params, get_optional_params_image_gen, get_prompt_cache_min_tokens, get_supported_openai_params, @@ -8265,6 +8266,107 @@ def test_validate_tool_choice_without_model_is_still_a_400(): assert exc_info.value.model == "" +CHAT_ALLOWED_TOOLS: Final = { + "type": "allowed_tools", + "allowed_tools": { + "mode": "required", + "tools": [ + {"type": "function", "function": {"name": "get_weather"}}, + {"type": "custom", "custom": {"name": "apply_patch"}}, + {"type": "mcp", "server_label": "deepwiki"}, + ], + }, +} + + +@pytest.mark.usefixtures("_vcr_outcome_gate", "setup_and_teardown") +@pytest.mark.parametrize( + "tool_choice", + [ + CHAT_ALLOWED_TOOLS, + { + "type": "allowed_tools", + "mode": "required", + "tools": [ + {"type": "function", "name": "get_weather"}, + {"type": "custom", "name": "apply_patch"}, + {"type": "mcp", "server_label": "deepwiki"}, + ], + }, + ], + ids=["chat_nested", "responses_flat"], +) +def test_validate_tool_choice_allowed_tools_takes_the_chat_shape(tool_choice): + """Both OpenAI allowed_tools shapes are accepted and come out in the chat completions shape.""" + assert validate_chat_completion_tool_choice(tool_choice, model=MODEL) == CHAT_ALLOWED_TOOLS + + +@pytest.mark.usefixtures("_vcr_outcome_gate", "setup_and_teardown") +@pytest.mark.parametrize( + "tool_choice", + [ + {"type": "allowed_tools"}, + {"type": "allowed_tools", "mode": "required"}, + {"type": "allowed_tools", "allowed_tools": {"mode": "sometimes", "tools": []}}, + {"type": "allowed_tools", "allowed_tools": "get_weather", "mode": "auto"}, + ], +) +def test_validate_tool_choice_malformed_allowed_tools_is_a_400(tool_choice): + with pytest.raises(litellm.BadRequestError, match="Invalid tool choice") as exc_info: + validate_chat_completion_tool_choice(tool_choice, model=MODEL) + assert exc_info.value.status_code == 400 + + +ALLOWED_TOOLS_REQUEST_TOOLS: Final = [ + {"type": "function", "function": {"name": "get_weather", "parameters": {"type": "object", "properties": {}}}} +] + + +@pytest.mark.usefixtures("_vcr_outcome_gate", "setup_and_teardown") +@pytest.mark.parametrize(("model", "custom_llm_provider"), [("gpt-5.5", "openai"), ("gpt-5.5", "azure")]) +def test_get_optional_params_keeps_allowed_tools_for_openai_shaped_providers(model, custom_llm_provider): + optional_params = get_optional_params( + model=model, + custom_llm_provider=custom_llm_provider, + tools=ALLOWED_TOOLS_REQUEST_TOOLS, + tool_choice=CHAT_ALLOWED_TOOLS, + ) + assert optional_params["tool_choice"] == CHAT_ALLOWED_TOOLS + + +@pytest.mark.usefixtures("_vcr_outcome_gate", "setup_and_teardown") +@pytest.mark.parametrize( + ("model", "custom_llm_provider"), + [("claude-haiku-4-5", "anthropic"), ("gemini-2.5-flash", "gemini"), ("deepseek-chat", "deepseek")], +) +def test_get_optional_params_rejects_allowed_tools_a_provider_cannot_take(model, custom_llm_provider): + with pytest.raises(litellm.UnsupportedParamsError, match="does not support an allowed_tools tool_choice") as exc_info: + get_optional_params( + model=model, + custom_llm_provider=custom_llm_provider, + tools=ALLOWED_TOOLS_REQUEST_TOOLS, + tool_choice=CHAT_ALLOWED_TOOLS, + ) + assert exc_info.value.status_code == 400 + + +@pytest.mark.usefixtures("_vcr_outcome_gate", "setup_and_teardown") +@pytest.mark.parametrize( + ("model", "custom_llm_provider"), + [("claude-haiku-4-5", "anthropic"), ("gemini-2.5-flash", "gemini"), ("deepseek-chat", "deepseek")], +) +def test_get_optional_params_drops_allowed_tools_under_drop_params(model, custom_llm_provider): + optional_params = get_optional_params( + model=model, + custom_llm_provider=custom_llm_provider, + tools=ALLOWED_TOOLS_REQUEST_TOOLS, + tool_choice=CHAT_ALLOWED_TOOLS, + drop_params=True, + ) + assert "tool_choice" not in optional_params + assert optional_params["tools"] + + @pytest.fixture() def _vcr_outcome_gate_local_testing(request, vcr): install_live_call_probe(request, vcr) diff --git a/tests/unit/test_validate_tool_choice.py b/tests/unit/test_validate_tool_choice.py deleted file mode 100644 index a28aee87c48..00000000000 --- a/tests/unit/test_validate_tool_choice.py +++ /dev/null @@ -1,93 +0,0 @@ -import re -from typing import Final - -import pytest - -import litellm -from litellm.utils import validate_chat_completion_tool_choice - -MODEL: Final = "anthropic/claude-haiku-4-5" - - -def test_validate_tool_choice_none(): - """Test that None is returned as-is.""" - result = validate_chat_completion_tool_choice(None, model=MODEL) - assert result is None - - -def test_validate_tool_choice_string(): - """Test that string values are returned as-is.""" - assert validate_chat_completion_tool_choice("auto", model=MODEL) == "auto" - assert validate_chat_completion_tool_choice("none", model=MODEL) == "none" - assert validate_chat_completion_tool_choice("required", model=MODEL) == "required" - - -def test_validate_tool_choice_standard_dict(): - """Test standard OpenAI format with function.""" - tool_choice = {"type": "function", "function": {"name": "my_function"}} - result = validate_chat_completion_tool_choice(tool_choice, model=MODEL) - assert result == tool_choice - - -def test_validate_tool_choice_cursor_format(): - """Cursor IDE format {"type": "auto"} is unwrapped to the bare string.""" - assert validate_chat_completion_tool_choice({"type": "auto"}, model=MODEL) == "auto" - assert validate_chat_completion_tool_choice({"type": "none"}, model=MODEL) == "none" - assert validate_chat_completion_tool_choice({"type": "required"}, model=MODEL) == "required" - - -def test_validate_tool_choice_allowed_tools_passthrough(): - """Chat completions accepts the allowed_tools shape and keeps its payload intact.""" - tool_choice = { - "type": "allowed_tools", - "allowed_tools": { - "mode": "required", - "tools": [{"type": "function", "function": {"name": "get_time"}}], - }, - } - assert validate_chat_completion_tool_choice(tool_choice, model=MODEL) is tool_choice - - -def test_validate_tool_choice_allowed_tools_without_payload_is_a_400(): - """allowed_tools without its nested object stays a caller error.""" - tool_choice = {"type": "allowed_tools"} - with pytest.raises(litellm.BadRequestError, match="Invalid tool choice"): - validate_chat_completion_tool_choice(tool_choice, model=MODEL) - - -@pytest.mark.parametrize( - "tool_choice", - [ - {}, - {"type": "invalid"}, - {"type": "function"}, - {"name": "lookup_fruit"}, - {"type": "file_search"}, - ], -) -def test_validate_tool_choice_invalid_dict_is_a_400(tool_choice): - """A dict shape chat completions cannot carry is the caller's mistake: a 400 that names the field, never a 500.""" - with pytest.raises( - litellm.BadRequestError, match=f"Invalid tool choice, tool_choice={re.escape(str(tool_choice))}\\. Please ensure" - ) as exc_info: - validate_chat_completion_tool_choice(tool_choice, model=MODEL) - assert exc_info.value.status_code == 400 - assert exc_info.value.model == MODEL - - -@pytest.mark.parametrize("tool_choice", [123, []]) -def test_validate_tool_choice_invalid_type_is_a_400(tool_choice): - """A non-str, non-dict tool_choice is rejected as a 400 that names the type it got.""" - with pytest.raises( - litellm.BadRequestError, match=f"Got={re.escape(str(type(tool_choice)))}\\. Expecting str, or dict\\." - ) as exc_info: - validate_chat_completion_tool_choice(tool_choice, model=MODEL) - assert exc_info.value.status_code == 400 - - -def test_validate_tool_choice_without_model_is_still_a_400(): - """Callers that predate the model argument keep getting a 400, with an empty model on the error.""" - with pytest.raises(litellm.BadRequestError, match="Invalid tool choice") as exc_info: - validate_chat_completion_tool_choice({"type": "bogus"}) - assert exc_info.value.status_code == 400 - assert exc_info.value.model == ""