From 3d62c4d66ef9e7008268c999bc65cd0261eca598 Mon Sep 17 00:00:00 2001 From: Luis Castillo Date: Wed, 9 Sep 2026 15:35:14 +0200 Subject: [PATCH 1/2] fix(responses): type reasoning content parts as reasoning_text A `reasoning` output item built from `reasoning_content` carried its text in an `output_text` content part. The Responses API types a reasoning item's parts as `reasoning_text` with a `text` field and no annotations, while a message's parts are `output_text` with them. The response is usable either way, so this is not a wire break, but openai-python types the field as `Literal["reasoning_text"]` and raises a PydanticSerializationUnexpectedValue warning for every affected field on every reasoning-bearing response: Expected `literal['reasoning_text']` - serialized value may not be as expected [field_name='type', input_value='output_text', input_type=str] Adds `OutputReasoningText`, widens `GenericResponseOutputItem.content` to accept either part, and emits the reasoning one from `_extract_reasoning_output_items`. Message items are untouched and keep `output_text`. The input side already round-trips this: `_reasoning_text_from_content` accepts any block carrying `text` that is not opaque, so a client replaying a `reasoning_text` part gets the same `reasoning_content` back. Its docstring now says so. Tests: the existing reasoning assertion moves to `reasoning_text`, and a new test validates the emitted part through openai-python's own `ResponseReasoningItem` with warnings captured, so the regression is caught by the same mechanism that reported it. --- .../transformation.py | 18 +++-- litellm/types/responses/main.py | 18 ++++- .../test_litellm_completion_responses.py | 67 ++++++++++++++++++- 3 files changed, 96 insertions(+), 7 deletions(-) diff --git a/litellm/responses/litellm_completion_transformation/transformation.py b/litellm/responses/litellm_completion_transformation/transformation.py index b2d1a69e0d8..4768ec5936b 100644 --- a/litellm/responses/litellm_completion_transformation/transformation.py +++ b/litellm/responses/litellm_completion_transformation/transformation.py @@ -78,6 +78,7 @@ from litellm.types.responses.main import ( OutputCodeInterpreterCall, OutputFunctionToolCall, OutputImageGenerationCall, + OutputReasoningText, OutputText, ) from litellm.types.utils import ( @@ -1305,8 +1306,9 @@ class LiteLLMCompletionResponsesConfig: Plaintext a ResponseReasoningItemParam carries in ``content``. Handles content as a string and content as a list of blocks - (output_text / summary_text / text). Returns None when the item has - no content, or only opaque blocks (e.g. encrypted_content). + (reasoning_text / output_text / summary_text / text). Returns None when + the item has no content, or only opaque blocks (e.g. + encrypted_content). """ content: Final[object] = input_item.get("content") if isinstance(content, str) and content.strip(): @@ -2401,11 +2403,17 @@ class LiteLLMCompletionResponsesConfig: choice.finish_reason ), role="assistant", + # `reasoning_text`, not `output_text`: the + # Responses API types a reasoning item's content + # parts differently from a message's. Emitting + # `output_text` here is accepted on the wire but + # makes `openai-python` raise a + # PydanticSerializationUnexpectedValue warning for + # every reasoning-bearing response. content=[ - OutputText( - type="output_text", + OutputReasoningText( + type="reasoning_text", text=text, - annotations=[], ) for text in (reasoning_content,) if text diff --git a/litellm/types/responses/main.py b/litellm/types/responses/main.py index 00635a8e1ef..35413b7dbe7 100644 --- a/litellm/types/responses/main.py +++ b/litellm/types/responses/main.py @@ -27,6 +27,20 @@ class OutputText(BaseLiteLLMOpenAIResponseObject): annotations: list[GenericResponseOutputItemContentAnnotation] | None +class OutputReasoningText(BaseLiteLLMOpenAIResponseObject): + """Reasoning text content inside a ``reasoning`` output item. + + Distinct from :class:`OutputText`: the Responses API types a reasoning + item's content parts as ``reasoning_text`` with a ``text`` field and no + annotations, while a message's content parts are ``output_text``. Emitting + the latter inside a reasoning item makes ``openai-python`` warn on every + reasoning-bearing response. + """ + + type: Literal["reasoning_text"] + text: str | None + + class OutputFunctionToolCall(BaseLiteLLMOpenAIResponseObject): """A tool call to run a function""" @@ -110,7 +124,9 @@ class GenericResponseOutputItem(BaseLiteLLMOpenAIResponseObject): id: str status: str # "completed", "in_progress", etc. role: str # "assistant", "user", etc. - content: list[OutputText] + # `reasoning` items carry `reasoning_text` parts; `message` items carry + # `output_text` ones. + content: list[Union[OutputText, OutputReasoningText]] phase: Phase = None diff --git a/tests/test_litellm/responses/litellm_completion_transformation/test_litellm_completion_responses.py b/tests/test_litellm/responses/litellm_completion_transformation/test_litellm_completion_responses.py index 2068f10ea2d..54d66705bce 100644 --- a/tests/test_litellm/responses/litellm_completion_transformation/test_litellm_completion_responses.py +++ b/tests/test_litellm/responses/litellm_completion_transformation/test_litellm_completion_responses.py @@ -1,6 +1,8 @@ import json +import warnings import pytest +from openai.types.responses.response_reasoning_item import ResponseReasoningItem from litellm.responses.litellm_completion_transformation.transformation import ( @@ -332,7 +334,7 @@ class TestLiteLLMCompletionResponsesConfig: assert reasoning_item.status == "completed" assert reasoning_item.role == "assistant" assert len(reasoning_item.content) == 1 - assert reasoning_item.content[0].type == "output_text" + assert reasoning_item.content[0].type == "reasoning_text" assert "step by step" in reasoning_item.content[0].text assert "42" in reasoning_item.content[0].text @@ -343,6 +345,69 @@ class TestLiteLLMCompletionResponsesConfig: message_item = message_items[0] assert message_item.content[0].text == "The answer is 42." + # A message's parts stay `output_text`; only the reasoning item changes. + assert message_item.content[0].type == "output_text" + + def test_reasoning_content_part_validates_against_the_openai_reasoning_item(self): + """A reasoning item must survive openai-python's own model without warnings. + + The Responses API types a reasoning item's content parts as + `reasoning_text` with a `text` field, while a message's parts are + `output_text` with annotations. Emitting the latter inside a reasoning + item is accepted on the wire, so the response is usable, but + `openai-python` then raises a PydanticSerializationUnexpectedValue + warning for every affected field on every reasoning-bearing response: + + Expected `literal['reasoning_text']` - serialized value may not be + as expected [field_name='type', input_value='output_text'] + """ + chat_completion_response = ModelResponse( + id="test-response-id", + created=1234567890, + model="test-model", + object="chat.completion", + choices=[ + Choices( + finish_reason="stop", + index=0, + message=Message( + content="42.", + role="assistant", + reasoning_content="Working it out.", + ), + ) + ], + ) + + responses_api_response = LiteLLMCompletionResponsesConfig.transform_chat_completion_response_to_responses_api_response( + request_input="What is the meaning of life?", + responses_api_request={}, + chat_completion_response=chat_completion_response, + ) + + reasoning_item = next( + item for item in responses_api_response.output if item.type == "reasoning" + ) + part = reasoning_item.content[0].model_dump() + + assert part["type"] == "reasoning_text" + assert part["text"] == "Working it out." + # `annotations` belongs to `output_text`, not to a reasoning part. + assert "annotations" not in part + + with warnings.catch_warnings(record=True) as caught: + warnings.simplefilter("always") + ResponseReasoningItem.model_validate( + { + "id": "rs_test", + "type": "reasoning", + "summary": [], + "content": [part], + } + ).model_dump() + + unexpected = [w for w in caught if "reasoning_text" in str(w.message)] + assert not unexpected, f"openai-python warned on the reasoning part: {unexpected}" def test_transform_chat_completion_response_without_reasoning_content(self): """Test that transformation works normally when no reasoning content is present""" From 5419935698b791be95ed6ead92a335debb52a124 Mon Sep 17 00:00:00 2001 From: Luis Castillo Date: Mon, 21 Sep 2026 14:12:14 +0200 Subject: [PATCH 2/2] fix(responses): keep reasoning text inside guardrail inspection Review findings from the automated reviewers on #40407, plus the lint failure. The important one: typing reasoning parts as `reasoning_text` removed them from output guardrails. `_has_text_content`, `_extract_output_text_and_images` and `_apply_guardrail_responses_to_output` each tested `isinstance(content_item, OutputText)`, and reasoning parts used to be `OutputText`, so they were inspected. `OutputReasoningText` is not, so a guardrail would have kept reporting success while no longer reading the content it was configured to check. That fails open, which is the wrong direction for a guardrail. All four checks now accept both parts through one `GUARDRAIL_TEXT_CONTENT_PARTS` tuple, so a future content-part type is added in one place rather than in four checks that can drift apart. Both classes carry `text`, so the extraction and rewrite paths need no other change. Also in this commit: - ruff UP007: `list[Union[OutputText, OutputReasoningText]]` becomes `list[OutputText | OutputReasoningText]`, matching the rest of the module. - Dropped the comment above it that restated the types. - `Union` stays imported in `types/responses/main.py` even though unused there: `llms/base_llm/image_edit/transformation.py` does `import *` from it and annotates with `Union`, so removing it breaks that module at class-definition time. Comment added so the next cleanup does not repeat it. Verified: ruff clean on both files; new guardrail test red with the tuple narrowed back to `(OutputText,)`, green with both; `tests/test_litellm/responses/` fails the same 14 pre-existing tests before and after, identical sets. Co-Authored-By: Claude Opus 5 --- .../guardrail_translation/handler.py | 15 ++-- litellm/types/responses/main.py | 8 ++- .../test_reasoning_text_guardrails.py | 70 +++++++++++++++++++ 3 files changed, 86 insertions(+), 7 deletions(-) create mode 100644 tests/test_litellm/llms/openai/responses/guardrail_translation/test_reasoning_text_guardrails.py diff --git a/litellm/llms/openai/responses/guardrail_translation/handler.py b/litellm/llms/openai/responses/guardrail_translation/handler.py index b0f79552bc5..ba9bd3274af 100644 --- a/litellm/llms/openai/responses/guardrail_translation/handler.py +++ b/litellm/llms/openai/responses/guardrail_translation/handler.py @@ -85,10 +85,17 @@ from litellm.types.llms.openai import ( from litellm.types.responses.main import ( GenericResponseOutputItem, OutputFunctionToolCall, + OutputReasoningText, OutputText, ) from litellm.types.utils import GenericGuardrailAPIInputs +# Content parts a guardrail inspects and may rewrite. Both carry ``text``. +# ``reasoning`` items type their parts as ``reasoning_text``; until that type +# existed they were emitted as ``output_text``, so checking ``OutputText`` +# alone would silently stop scanning reasoning content. +GUARDRAIL_TEXT_CONTENT_PARTS: Final = (OutputText, OutputReasoningText) + if TYPE_CHECKING: from fastapi import HTTPException @@ -1020,7 +1027,7 @@ class OpenAIResponsesHandler(BaseTranslation): if content: for content_item in content: # Check if it's an OutputText with text - if isinstance(content_item, OutputText): + if isinstance(content_item, GUARDRAIL_TEXT_CONTENT_PARTS): if content_item.text: return True elif isinstance(content_item, dict): @@ -1100,7 +1107,7 @@ class OpenAIResponsesHandler(BaseTranslation): # Iterate through content items (list of OutputText objects) for content_idx, content_item in enumerate(content): # Handle both OutputText objects and dicts - if isinstance(content_item, OutputText): + if isinstance(content_item, GUARDRAIL_TEXT_CONTENT_PARTS): text_content = content_item.text elif isinstance(content_item, dict): text_content = content_item.get("text") @@ -1144,7 +1151,7 @@ class OpenAIResponsesHandler(BaseTranslation): if isinstance(output_item, GenericResponseOutputItem): if output_item.content and content_idx < len(output_item.content): content_item = output_item.content[content_idx] - if isinstance(content_item, OutputText): + if isinstance(content_item, GUARDRAIL_TEXT_CONTENT_PARTS): content_item.text = guardrail_response elif isinstance(content_item, dict): content_item["text"] = guardrail_response @@ -1154,7 +1161,7 @@ class OpenAIResponsesHandler(BaseTranslation): generic_item = GenericResponseOutputItem.model_validate(output_item.model_dump()) if generic_item.content and content_idx < len(generic_item.content): content_item = generic_item.content[content_idx] - if isinstance(content_item, OutputText): + if isinstance(content_item, GUARDRAIL_TEXT_CONTENT_PARTS): content_item.text = guardrail_response # Update the original response output if hasattr(output_item, "content") and output_item.content: diff --git a/litellm/types/responses/main.py b/litellm/types/responses/main.py index 35413b7dbe7..1abe5ccf162 100644 --- a/litellm/types/responses/main.py +++ b/litellm/types/responses/main.py @@ -1,3 +1,7 @@ +# `Union` is no longer referenced in this module, but +# `litellm/llms/base_llm/image_edit/transformation.py` does +# `from litellm.types.responses.main import *` and annotates with it, so +# dropping it here breaks that import at class-definition time. from typing import Final, Literal, Optional, Union from openai.types.responses.response_function_tool_call import ResponseFunctionToolCall @@ -124,9 +128,7 @@ class GenericResponseOutputItem(BaseLiteLLMOpenAIResponseObject): id: str status: str # "completed", "in_progress", etc. role: str # "assistant", "user", etc. - # `reasoning` items carry `reasoning_text` parts; `message` items carry - # `output_text` ones. - content: list[Union[OutputText, OutputReasoningText]] + content: list[OutputText | OutputReasoningText] phase: Phase = None diff --git a/tests/test_litellm/llms/openai/responses/guardrail_translation/test_reasoning_text_guardrails.py b/tests/test_litellm/llms/openai/responses/guardrail_translation/test_reasoning_text_guardrails.py new file mode 100644 index 00000000000..d0063f43411 --- /dev/null +++ b/tests/test_litellm/llms/openai/responses/guardrail_translation/test_reasoning_text_guardrails.py @@ -0,0 +1,70 @@ +"""Reasoning content parts must stay visible to output guardrails. + +Before `reasoning_text` existed, a reasoning item's parts were emitted as +`output_text`, so the guardrail handler's `isinstance(..., OutputText)` checks +saw them. Introducing `OutputReasoningText` would have silently removed +reasoning text from guardrail inspection and rewriting, which fails open: the +guardrail keeps reporting success while no longer reading the content. +""" + +from litellm.llms.openai.responses.guardrail_translation.handler import ( + GUARDRAIL_TEXT_CONTENT_PARTS, + OpenAIResponsesHandler, +) +from litellm.types.responses.main import ( + GenericResponseOutputItem, + OutputReasoningText, + OutputText, +) + + +def _reasoning_item(text: str) -> GenericResponseOutputItem: + return GenericResponseOutputItem( + type="reasoning", + id="rs_1", + status="completed", + role="assistant", + content=[OutputReasoningText(type="reasoning_text", text=text)], + ) + + +def _message_item(text: str) -> GenericResponseOutputItem: + return GenericResponseOutputItem( + type="message", + id="msg_1", + status="completed", + role="assistant", + content=[OutputText(type="output_text", text=text, annotations=None)], + ) + + +def test_both_content_part_types_are_inspected(): + assert OutputText in GUARDRAIL_TEXT_CONTENT_PARTS + assert OutputReasoningText in GUARDRAIL_TEXT_CONTENT_PARTS + + +def test_reasoning_text_is_extracted_for_checking(): + handler = OpenAIResponsesHandler() + texts: list[str] = [] + images: list[str] = [] + mappings: list[tuple[int, int]] = [] + + handler._extract_output_text_and_images( + _reasoning_item("secret chain of thought"), 0, texts, images, mappings + ) + + assert texts == ["secret chain of thought"] + assert mappings == [(0, 0)] + + +def test_message_text_is_still_extracted(): + handler = OpenAIResponsesHandler() + texts: list[str] = [] + images: list[str] = [] + mappings: list[tuple[int, int]] = [] + + handler._extract_output_text_and_images( + _message_item("the answer"), 0, texts, images, mappings + ) + + assert texts == ["the answer"]