diff --git a/litellm/llms/openai/responses/guardrail_translation/handler.py b/litellm/llms/openai/responses/guardrail_translation/handler.py index 2fe11d9f7bd..7026119abd6 100644 --- a/litellm/llms/openai/responses/guardrail_translation/handler.py +++ b/litellm/llms/openai/responses/guardrail_translation/handler.py @@ -84,10 +84,17 @@ from litellm.types.llms.openai import ( ) from litellm.types.responses.main import ( GenericResponseOutputItem, + 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 @@ -1285,7 +1292,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): @@ -1341,7 +1348,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") @@ -1385,7 +1392,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 @@ -1395,7 +1402,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/responses/litellm_completion_transformation/transformation.py b/litellm/responses/litellm_completion_transformation/transformation.py index e8aacac9e67..d47ea22d3f0 100644 --- a/litellm/responses/litellm_completion_transformation/transformation.py +++ b/litellm/responses/litellm_completion_transformation/transformation.py @@ -82,6 +82,7 @@ from litellm.types.responses.main import ( OutputCodeInterpreterCall, OutputFunctionToolCall, OutputImageGenerationCall, + OutputReasoningText, OutputText, ) from litellm.types.utils import ( @@ -1428,8 +1429,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(): @@ -2563,11 +2565,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 26cc5c4c6cc..52cc7dbb8f9 100644 --- a/litellm/types/responses/main.py +++ b/litellm/types/responses/main.py @@ -1,4 +1,9 @@ from collections.abc import Mapping, Sequence + +# `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 @@ -29,6 +34,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""" @@ -142,7 +161,7 @@ class GenericResponseOutputItem(BaseLiteLLMOpenAIResponseObject): id: str status: str # "completed", "in_progress", etc. role: str # "assistant", "user", etc. - content: list[OutputText] + 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"] 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 3c78bbf79d7..c28a0b14bde 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,4 +1,5 @@ import json +import warnings from copy import deepcopy from typing import Final, Literal @@ -10,6 +11,7 @@ from openai.types.responses.response_function_web_search import ( ActionSearchSource, ResponseFunctionWebSearch, ) +from openai.types.responses.response_reasoning_item import ResponseReasoningItem import litellm from litellm.litellm_core_utils.prompt_templates.factory import anthropic_messages_pt @@ -343,7 +345,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 @@ -354,6 +356,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"""