Merge pull request #23151 from BerriAI/litellm_preserve-reasoning-summary-for-responses-api

fix(openai): preserve reasoning_effort summary field for Responses API

litellm/llms/azure/chat/gpt_5_transformation.py

@@ -4,7 +4,10 @@ from typing import List
 
 import litellm
 from litellm.exceptions import UnsupportedParamsError
-from litellm.llms.openai.chat.gpt_5_transformation import OpenAIGPT5Config
+from litellm.llms.openai.chat.gpt_5_transformation import (
+    OpenAIGPT5Config,
+    _get_effort_level,
+)
 from litellm.types.llms.openai import AllMessageValues
 
 from .gpt_transformation import AzureOpenAIConfig
@@ -81,20 +84,21 @@ class AzureOpenAIGPT5Config(AzureOpenAIConfig, OpenAIGPT5Config):
             non_default_params.get("reasoning_effort")
             or optional_params.get("reasoning_effort")
         )
+        effective_effort = _get_effort_level(reasoning_effort_value)
 
         # gpt-5.1/5.2/5.4 support reasoning_effort='none', but other gpt-5 models don't
         # See: https://learn.microsoft.com/en-us/azure/ai-foundry/openai/how-to/reasoning
         supports_none = self._supports_reasoning_effort_level(model, "none")
 
-        if reasoning_effort_value == "none" and not supports_none:
+        if effective_effort == "none" and not supports_none:
             if litellm.drop_params is True or (
                 drop_params is not None and drop_params is True
             ):
                 non_default_params = non_default_params.copy()
                 optional_params = optional_params.copy()
-                if non_default_params.get("reasoning_effort") == "none":
+                if _get_effort_level(non_default_params.get("reasoning_effort")) == "none":
                     non_default_params.pop("reasoning_effort")
-                if optional_params.get("reasoning_effort") == "none":
+                if _get_effort_level(optional_params.get("reasoning_effort")) == "none":
                     optional_params.pop("reasoning_effort")
             else:
                 raise UnsupportedParamsError(
@@ -117,9 +121,19 @@ class AzureOpenAIGPT5Config(AzureOpenAIConfig, OpenAIGPT5Config):
         )
 
         # Only drop reasoning_effort='none' for models that don't support it
-        if result.get("reasoning_effort") == "none" and not supports_none:
+        result_effort = _get_effort_level(result.get("reasoning_effort"))
+        if result_effort == "none" and not supports_none:
             result.pop("reasoning_effort")
 
+        # Azure Chat Completions: gpt-5.4+ does not support tools + reasoning together.
+        # Drop reasoning_effort when both are present (OpenAI routes to Responses API; Azure does not).
+        if self.is_model_gpt_5_4_plus_model(model):
+            has_tools = bool(
+                non_default_params.get("tools") or optional_params.get("tools")
+            )
+            if has_tools and result_effort not in (None, "none"):
+                result.pop("reasoning_effort", None)
+
         return result
 
     def transform_request(

litellm/llms/openai/chat/gpt_5_transformation.py

@@ -25,6 +25,22 @@ def _normalize_reasoning_effort_for_chat_completion(
     return None
 
 
+def _get_effort_level(value: Union[str, dict, None]) -> Optional[str]:
+    """Extract the effective effort level from reasoning_effort (string or dict).
+
+    Use this for guards that compare effort level (e.g. xhigh validation, "none" checks).
+    Ensures dict inputs like {"effort": "none", "summary": "detailed"} are correctly
+    treated as effort="none" for validation purposes.
+    """
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return value
+    if isinstance(value, dict) and "effort" in value:
+        return value["effort"]
+    return None
+
+
 class OpenAIGPT5Config(OpenAIGPTConfig):
     """Configuration for gpt-5 models including GPT-5-Codex variants.
 
@@ -70,6 +86,19 @@ class OpenAIGPT5Config(OpenAIGPTConfig):
         model_name = model.split("/")[-1]
         return model_name.startswith("gpt-5.4")
 
+    @classmethod
+    def is_model_gpt_5_4_plus_model(cls, model: str) -> bool:
+        """Check if the model is gpt-5.4 or newer (5.4, 5.5, 5.6, etc., including pro)."""
+        model_name = model.split("/")[-1]
+        if not model_name.startswith("gpt-5."):
+            return False
+        try:
+            version_str = model_name.replace("gpt-5.", "").split("-")[0]
+            major = version_str.split(".")[0]
+            return int(major) >= 4
+        except (ValueError, IndexError):
+            return False
+
     @classmethod
     def _supports_reasoning_effort_level(cls, model: str, level: str) -> bool:
         """Check if the model supports a specific reasoning_effort level.
@@ -150,21 +179,32 @@ class OpenAIGPT5Config(OpenAIGPTConfig):
                 drop_params=drop_params,
             )
 
-        # Normalize reasoning_effort: chat completion API expects a string, not a dict
-        # (e.g. {'effort': 'high', 'summary': 'detailed'} -> 'high')
+        # Get raw reasoning_effort and effective effort level for all guards.
+        # Use effective_effort (extracted string) for xhigh validation, "none" checks, and
+        # tool/sampling guards — dict inputs like {"effort": "none", "summary": "detailed"}
+        # must be treated as effort="none" to avoid incorrect tool-drop or sampling errors.
         raw_reasoning_effort = (
             non_default_params.get("reasoning_effort")
             or optional_params.get("reasoning_effort")
         )
-        normalized = _normalize_reasoning_effort_for_chat_completion(raw_reasoning_effort)
-        if raw_reasoning_effort is not None and normalized is not None:
-            if "reasoning_effort" in non_default_params:
-                non_default_params["reasoning_effort"] = normalized
-            if "reasoning_effort" in optional_params:
-                optional_params["reasoning_effort"] = normalized
+        effective_effort = _get_effort_level(raw_reasoning_effort)
 
-        reasoning_effort = normalized or raw_reasoning_effort
-        if reasoning_effort is not None and reasoning_effort == "xhigh":
+        # Normalize to string for Chat Completions API when dict has only "effort".
+        # Preserve full dict (e.g. {"effort": "high", "summary": "detailed"}) for Responses API.
+        if isinstance(raw_reasoning_effort, dict) and set(raw_reasoning_effort.keys()) <= {"effort"}:
+            normalized = _normalize_reasoning_effort_for_chat_completion(raw_reasoning_effort)
+            if normalized is not None:
+                if "reasoning_effort" in non_default_params:
+                    non_default_params["reasoning_effort"] = normalized
+                if "reasoning_effort" in optional_params:
+                    optional_params["reasoning_effort"] = normalized
+
+        reasoning_effort = (
+            non_default_params.get("reasoning_effort")
+            or optional_params.get("reasoning_effort")
+            or raw_reasoning_effort
+        )
+        if effective_effort is not None and effective_effort == "xhigh":
             if not self._supports_reasoning_effort_level(model, "xhigh"):
                 if litellm.drop_params or drop_params:
                     non_default_params.pop("reasoning_effort", None)
@@ -191,17 +231,20 @@ class OpenAIGPT5Config(OpenAIGPTConfig):
             has_tools = bool(
                 non_default_params.get("tools") or optional_params.get("tools")
             )
-            if has_tools and reasoning_effort not in (None, "none"):
-                non_default_params.pop("reasoning_effort", None)
-                optional_params.pop("reasoning_effort", None)
-                reasoning_effort = None
+            if has_tools and effective_effort not in (None, "none"):
+                # Check if this will be routed to Responses API
+                # If so, keep reasoning_effort; otherwise drop it for chat completions API
+                if not self.is_model_gpt_5_4_plus_model(model):
+                    non_default_params.pop("reasoning_effort", None)
+                    optional_params.pop("reasoning_effort", None)
+                    reasoning_effort = None
 
         # gpt-5.1/5.2 support logprobs, top_p, top_logprobs only when reasoning_effort="none"
         supports_none = self._supports_reasoning_effort_level(model, "none")
         if supports_none:
             sampling_params = ["logprobs", "top_logprobs", "top_p"]
             has_sampling = any(p in non_default_params for p in sampling_params)
-            if has_sampling and reasoning_effort not in (None, "none"):
+            if has_sampling and effective_effort not in (None, "none"):
                 if litellm.drop_params or drop_params:
                     for p in sampling_params:
                         non_default_params.pop(p, None)
@@ -211,7 +254,7 @@ class OpenAIGPT5Config(OpenAIGPTConfig):
                             "gpt-5.1/5.2/5.4 only support logprobs, top_p, top_logprobs when "
                             "reasoning_effort='none'. Current reasoning_effort='{}'. "
                             "To drop unsupported params set `litellm.drop_params = True`"
-                        ).format(reasoning_effort),
+                        ).format(effective_effort),
                         status_code=400,
                     )
 
@@ -219,7 +262,7 @@ class OpenAIGPT5Config(OpenAIGPTConfig):
             temperature_value: Optional[float] = non_default_params.pop("temperature")
             if temperature_value is not None:
                 # models supporting reasoning_effort="none" also support flexible temperature
-                if supports_none and (reasoning_effort == "none" or reasoning_effort is None):
+                if supports_none and (effective_effort == "none" or effective_effort is None):
                     optional_params["temperature"] = temperature_value
                 elif temperature_value == 1:
                     optional_params["temperature"] = temperature_value

tests/test_litellm/completion_extras/litellm_responses_transformation/test_completion_extras_litellm_responses_transformation_transformation.py

@@ -1961,3 +1961,35 @@ def test_parallel_tool_calls_comprehensive_streaming_integration():
     )
 
     print("✓ Parallel tool calls with split argument deltas stream correctly end-to-end")
+
+
+def test_map_optional_params_preserves_reasoning_summary():
+    """Test that reasoning_effort dict with summary field is preserved.
+    
+    Regression test for: User reported that summary field was being dropped
+    when routing to Responses API. The dict format should be fully preserved.
+    """
+    from litellm.completion_extras.litellm_responses_transformation.transformation import (
+        LiteLLMResponsesTransformationHandler,
+    )
+    from litellm.types.llms.openai import ResponsesAPIOptionalRequestParams
+
+    handler = LiteLLMResponsesTransformationHandler()
+
+    optional_params = {
+        "stream": False,
+        "tools": [{"type": "function", "function": {"name": "test_tool"}}],
+        "tool_choice": "auto",
+        "reasoning_effort": {"effort": "high", "summary": "detailed"},
+    }
+
+    responses_api_request = ResponsesAPIOptionalRequestParams()
+    handler._map_optional_params_to_responses_api_request(
+        optional_params, responses_api_request
+    )
+
+    # Verify reasoning_effort dict with summary was fully preserved
+    assert "reasoning" in responses_api_request
+    assert responses_api_request["reasoning"] == {"effort": "high", "summary": "detailed"}
+    assert responses_api_request["reasoning"]["effort"] == "high"
+    assert responses_api_request["reasoning"]["summary"] == "detailed"

tests/test_litellm/llms/azure/chat/test_azure_gpt5_transformation.py

@@ -192,6 +192,23 @@ def test_azure_gpt5_1_series_temperature_handling(config: AzureOpenAIGPT5Config)
     assert params["temperature"] == 0.6
 
 
+def test_azure_gpt5_4_drops_reasoning_effort_when_tools_present(config: AzureOpenAIGPT5Config):
+    """Azure Chat Completions: gpt-5.4+ drops reasoning_effort when tools are present.
+
+    OpenAI routes tools+reasoning to Responses API; Azure does not, so we drop reasoning_effort.
+    """
+    tools = [{"type": "function", "function": {"name": "test", "description": "test"}}]
+    params = config.map_openai_params(
+        non_default_params={"reasoning_effort": "high", "tools": tools},
+        optional_params={},
+        model="gpt5_series/gpt-5.4",
+        drop_params=False,
+        api_version="2024-05-01-preview",
+    )
+    assert "reasoning_effort" not in params
+    assert params["tools"] == tools
+
+
 def test_azure_gpt5_reasoning_effort_none_error(config: AzureOpenAIGPT5Config):
     """Test that Azure GPT-5 (non-5.1) raises error for reasoning_effort='none' when drop_params=False."""
     with pytest.raises(litellm.utils.UnsupportedParamsError):

tests/test_litellm/llms/openai/chat/test_openai_gpt_transformation.py

@@ -13,6 +13,7 @@ from litellm.llms.openai.chat.gpt_transformation import (
     OpenAIChatCompletionStreamingHandler,
     OpenAIGPTConfig,
 )
+from litellm.llms.openai.chat.gpt_5_transformation import OpenAIGPT5Config
 
 
 class TestOpenAIGPTConfig:
@@ -324,3 +325,195 @@ class TestPromptCacheParams:
         )
         assert optional_params.get("prompt_cache_key") == "my-cache-key"
         assert optional_params.get("prompt_cache_retention") == "24h"
+
+
+class TestGPT5ReasoningEffortPreservation:
+    """Tests for GPT-5 reasoning_effort dict preservation for Responses API."""
+
+    def setup_method(self):
+        self.config = OpenAIGPT5Config()
+
+    def test_reasoning_effort_string_preserved(self):
+        """Test that reasoning_effort as string is preserved."""
+        non_default_params = {"reasoning_effort": "high"}
+        optional_params = {}
+        
+        self.config.map_openai_params(
+            non_default_params=non_default_params,
+            optional_params=optional_params,
+            model="gpt-5.4",
+            drop_params=False,
+        )
+        
+        # String format should be preserved
+        assert non_default_params.get("reasoning_effort") == "high"
+
+    def test_reasoning_effort_dict_with_only_effort_normalized(self):
+        """Test that reasoning_effort dict with only 'effort' key is normalized to string."""
+        non_default_params = {"reasoning_effort": {"effort": "high"}}
+        optional_params = {}
+        
+        self.config.map_openai_params(
+            non_default_params=non_default_params,
+            optional_params=optional_params,
+            model="gpt-5.4",
+            drop_params=False,
+        )
+        
+        # Dict with only 'effort' should be normalized to string
+        assert non_default_params.get("reasoning_effort") == "high"
+
+    def test_reasoning_effort_dict_with_summary_preserved(self):
+        """Test that reasoning_effort dict with 'summary' field is preserved for Responses API.
+        
+        Regression test for: User reported that summary field was being dropped when
+        routing to Responses API. The dict format with additional fields should be
+        preserved so it can be properly handled by the Responses API transformation.
+        """
+        non_default_params = {"reasoning_effort": {"effort": "high", "summary": "detailed"}}
+        optional_params = {}
+        
+        self.config.map_openai_params(
+            non_default_params=non_default_params,
+            optional_params=optional_params,
+            model="gpt-5.4",
+            drop_params=False,
+        )
+        
+        # Dict with additional fields should be preserved
+        assert non_default_params.get("reasoning_effort") == {"effort": "high", "summary": "detailed"}
+        assert isinstance(non_default_params.get("reasoning_effort"), dict)
+        assert non_default_params["reasoning_effort"]["effort"] == "high"
+        assert non_default_params["reasoning_effort"]["summary"] == "detailed"
+
+    def test_reasoning_effort_dict_with_generate_summary_preserved(self):
+        """Test that reasoning_effort dict with 'generate_summary' field is preserved."""
+        non_default_params = {"reasoning_effort": {"effort": "medium", "generate_summary": "auto"}}
+        optional_params = {}
+        
+        self.config.map_openai_params(
+            non_default_params=non_default_params,
+            optional_params=optional_params,
+            model="gpt-5.4",
+            drop_params=False,
+        )
+        
+        # Dict with additional fields should be preserved
+        assert non_default_params.get("reasoning_effort") == {"effort": "medium", "generate_summary": "auto"}
+        assert isinstance(non_default_params.get("reasoning_effort"), dict)
+
+    def test_reasoning_effort_dict_with_all_fields_preserved(self):
+        """Test that reasoning_effort dict with all fields is preserved."""
+        non_default_params = {
+            "reasoning_effort": {
+                "effort": "high",
+                "summary": "detailed",
+                "generate_summary": "concise"
+            }
+        }
+        optional_params = {}
+        
+        self.config.map_openai_params(
+            non_default_params=non_default_params,
+            optional_params=optional_params,
+            model="gpt-5.4",
+            drop_params=False,
+        )
+        
+        # Dict with all fields should be preserved
+        reasoning = non_default_params.get("reasoning_effort")
+        assert isinstance(reasoning, dict)
+        assert reasoning["effort"] == "high"
+        assert reasoning["summary"] == "detailed"
+        assert reasoning["generate_summary"] == "concise"
+
+    def test_reasoning_effort_dict_xhigh_triggers_validation(self):
+        """xhigh-dict: effective effort is extracted for model-support validation.
+        
+        When reasoning_effort={"effort": "xhigh", "summary": "detailed"} is passed to a model
+        that doesn't support xhigh (e.g. gpt-5.1), the xhigh guard must fire.
+        """
+        import litellm
+
+        non_default_params = {"reasoning_effort": {"effort": "xhigh", "summary": "detailed"}}
+        optional_params = {}
+
+        with pytest.raises(litellm.utils.UnsupportedParamsError):
+            self.config.map_openai_params(
+                non_default_params=non_default_params,
+                optional_params=optional_params,
+                model="gpt-5.1",
+                drop_params=False,
+            )
+
+    def test_reasoning_effort_dict_xhigh_dropped_when_requested(self):
+        """xhigh-dict with drop_params=True: reasoning_effort is dropped."""
+        non_default_params = {"reasoning_effort": {"effort": "xhigh", "summary": "detailed"}}
+        optional_params = {}
+
+        self.config.map_openai_params(
+            non_default_params=non_default_params,
+            optional_params=optional_params,
+            model="gpt-5.1",
+            drop_params=True,
+        )
+
+        assert "reasoning_effort" not in non_default_params
+
+    def test_reasoning_effort_dict_none_treated_as_none_for_tools(self):
+        """none-dict: {"effort": "none", "summary": "detailed"} is treated as effort=none.
+        
+        Tool-drop guard should NOT fire; reasoning_effort should be kept.
+        """
+        tools = [{"type": "function", "function": {"name": "test", "description": "test"}}]
+        non_default_params = {"reasoning_effort": {"effort": "none", "summary": "detailed"}, "tools": tools}
+        optional_params = {}
+
+        self.config.map_openai_params(
+            non_default_params=non_default_params,
+            optional_params=optional_params,
+            model="gpt-5.4",
+            drop_params=False,
+        )
+
+        assert non_default_params.get("reasoning_effort") == {"effort": "none", "summary": "detailed"}
+        assert non_default_params.get("tools") == tools
+
+    def test_reasoning_effort_dict_none_treated_as_none_for_sampling(self):
+        """none-dict: {"effort": "none", "summary": "detailed"} allows logprobs/top_p.
+        
+        Sampling-param guard should NOT fire; logprobs should be kept.
+        """
+        non_default_params = {
+            "reasoning_effort": {"effort": "none", "summary": "detailed"},
+            "logprobs": True,
+        }
+        optional_params = {}
+
+        self.config.map_openai_params(
+            non_default_params=non_default_params,
+            optional_params=optional_params,
+            model="gpt-5.1",
+            drop_params=False,
+        )
+
+        assert non_default_params.get("reasoning_effort") == {"effort": "none", "summary": "detailed"}
+        assert non_default_params.get("logprobs") is True
+
+    def test_reasoning_effort_dict_none_allows_temperature(self):
+        """none-dict: {"effort": "none", "summary": "detailed"} allows non-default temperature."""
+        non_default_params = {
+            "reasoning_effort": {"effort": "none", "summary": "detailed"},
+            "temperature": 0.5,
+        }
+        optional_params = {}
+
+        self.config.map_openai_params(
+            non_default_params=non_default_params,
+            optional_params=optional_params,
+            model="gpt-5.1",
+            drop_params=False,
+        )
+
+        assert optional_params.get("temperature") == 0.5
+        assert non_default_params.get("reasoning_effort") == {"effort": "none", "summary": "detailed"}

tests/test_litellm/llms/openai/test_gpt5_transformation.py

@@ -324,10 +324,11 @@ def test_gpt5_4_pro_allows_reasoning_effort_xhigh(config: OpenAIConfig):
     assert params["reasoning_effort"] == "xhigh"
 
 
-def test_gpt5_normalizes_reasoning_effort_dict_to_string(config: OpenAIConfig):
-    """Chat completion API expects reasoning_effort as a string, not a dict.
+def test_gpt5_preserves_reasoning_effort_dict_with_summary(config: OpenAIConfig):
+    """Dict with summary/generate_summary is preserved for Responses API.
 
     Config/deployments may pass Responses API format: {'effort': 'high', 'summary': 'detailed'}.
+    We preserve the full dict so it reaches the Responses API transformation.
     """
     params = config.map_openai_params(
         non_default_params={"reasoning_effort": {"effort": "high", "summary": "detailed"}},
@@ -335,18 +336,82 @@ def test_gpt5_normalizes_reasoning_effort_dict_to_string(config: OpenAIConfig):
         model="gpt-5.4",
         drop_params=False,
     )
-    assert params["reasoning_effort"] == "high"
+    assert params["reasoning_effort"] == {"effort": "high", "summary": "detailed"}
 
 
-def test_gpt5_normalizes_reasoning_effort_dict_from_optional_params(config: OpenAIConfig):
-    """reasoning_effort dict in optional_params (e.g. from model config) is normalized."""
+def test_gpt5_xhigh_dict_triggers_validation(config: OpenAIConfig):
+    """Dict with effort='xhigh' triggers xhigh model-support validation.
+
+    Regression: when reasoning_effort is a dict, effective_effort must be used for
+    the xhigh guard so validation is not silently skipped.
+    """
+    with pytest.raises(litellm.utils.UnsupportedParamsError):
+        config.map_openai_params(
+            non_default_params={"reasoning_effort": {"effort": "xhigh", "summary": "detailed"}},
+            optional_params={},
+            model="gpt-5.1",
+            drop_params=False,
+        )
+
+
+def test_gpt5_xhigh_dict_accepted_for_supported_model(config: OpenAIConfig):
+    """Dict with effort='xhigh' passes through for gpt-5.4+."""
+    params = config.map_openai_params(
+        non_default_params={"reasoning_effort": {"effort": "xhigh", "summary": "detailed"}},
+        optional_params={},
+        model="gpt-5.4",
+        drop_params=False,
+    )
+    assert params["reasoning_effort"] == {"effort": "xhigh", "summary": "detailed"}
+
+
+def test_gpt5_none_dict_with_tools_no_tool_drop(config: OpenAIConfig):
+    """Dict with effort='none' and tools: no tool-drop, reasoning_effort preserved.
+
+    Regression: effective_effort='none' must be used for tool-drop guard so
+    {"effort": "none", "summary": "detailed"} is not incorrectly treated as non-none.
+    """
+    tools = [{"type": "function", "function": {"name": "test", "description": "test"}}]
+    params = config.map_openai_params(
+        non_default_params={"reasoning_effort": {"effort": "none", "summary": "detailed"}, "tools": tools},
+        optional_params={},
+        model="gpt-5.4",
+        drop_params=False,
+    )
+    assert params["reasoning_effort"] == {"effort": "none", "summary": "detailed"}
+    assert params["tools"] == tools
+
+
+def test_gpt5_none_dict_with_sampling_params_allowed(config: OpenAIConfig):
+    """Dict with effort='none' allows logprobs/top_p/top_logprobs.
+
+    Regression: effective_effort='none' must be used for sampling guard so
+    {"effort": "none", "summary": "detailed"} does not incorrectly trigger sampling errors.
+    """
+    params = config.map_openai_params(
+        non_default_params={
+            "reasoning_effort": {"effort": "none", "summary": "detailed"},
+            "logprobs": True,
+            "top_p": 0.9,
+        },
+        optional_params={},
+        model="gpt-5.1",
+        drop_params=False,
+    )
+    assert params["reasoning_effort"] == {"effort": "none", "summary": "detailed"}
+    assert params["logprobs"] is True
+    assert params["top_p"] == 0.9
+
+
+def test_gpt5_preserves_reasoning_effort_dict_with_summary_from_optional_params(config: OpenAIConfig):
+    """reasoning_effort dict with summary in optional_params is preserved."""
     params = config.map_openai_params(
         non_default_params={},
         optional_params={"reasoning_effort": {"effort": "medium", "summary": "detailed"}},
         model="gpt-5.4",
         drop_params=False,
     )
-    assert params["reasoning_effort"] == "medium"
+    assert params["reasoning_effort"] == {"effort": "medium", "summary": "detailed"}
 
 
 def test_gpt5_4_drops_reasoning_effort_when_tools_present(config: OpenAIConfig):