From 02b2ccf32e3a6463db367b25461bfa88b6f56efa Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Sat, 31 Oct 2026 01:57:17 -0700 Subject: [PATCH] fix(responses): scan refusal parts in Responses guardrails --- .../guardrail_translation/handler.py | 85 ++++---- ...test_openai_responses_guardrail_handler.py | 194 +++++++++++++++++- 2 files changed, 235 insertions(+), 44 deletions(-) diff --git a/litellm/llms/openai/responses/guardrail_translation/handler.py b/litellm/llms/openai/responses/guardrail_translation/handler.py index 7c2ec411995..ddda9e7fb46 100644 --- a/litellm/llms/openai/responses/guardrail_translation/handler.py +++ b/litellm/llms/openai/responses/guardrail_translation/handler.py @@ -278,6 +278,7 @@ _TOOL_CALL_PAYLOAD_EVENT_TYPES: Final = _TOOL_CALL_PAYLOAD_DELTA_EVENT_TYPES | f ) _OUTPUT_ITEM_EVENT_TYPES: Final = frozenset({"response.output_item.added", "response.output_item.done"}) _OUTPUT_TEXT_EVENT_TYPES: Final = frozenset({"response.output_text.delta", "response.output_text.done"}) +_TEXT_DELTA_EVENT_TYPES: Final = frozenset({"response.output_text.delta", "response.refusal.delta"}) _TOOL_OUTPUT_TEXT_PART_TYPES: Final = frozenset({"input_text", "output_text", "text"}) _PATCHABLE_ITEM_FIELDS: Final[Mapping[str, str]] = MappingProxyType( {"function_call_output": "output", "custom_tool_call_output": "output", "message": "content"} @@ -538,6 +539,14 @@ def _scanned_text_field(item: Mapping[str, object]) -> str: return "output" if item.get("type") in TOOL_CALL_OUTPUT_ITEM_TYPES else "content" +def _content_part_text_field(part: object) -> str: + return "refusal" if stream_item_field(part, "type") == "refusal" else "text" + + +def _has_writable_field(part: object, field: str) -> bool: + return isinstance(part, dict) or hasattr(part, field) + + def _tool_output_part_text(part: object) -> str | None: if not isinstance(part, dict): return None @@ -994,7 +1003,7 @@ class OpenAIResponsesHandler(BaseTranslation): for content_idx, content_item in enumerate(content): if isinstance(content_item, dict): # Extract text - text_str = content_item.get("text", None) + text_str = content_item.get(_content_part_text_field(content_item), None) if text_str is not None: texts_to_check.append(text_str) task_mappings.append((msg_idx, int(content_idx))) @@ -1043,8 +1052,7 @@ class OpenAIResponsesHandler(BaseTranslation): elif isinstance(content, list): # Replace specific text item in list content - if isinstance(messages[msg_idx][field][content_idx_optional], dict): - messages[msg_idx][field][content_idx_optional]["text"] = guardrail_response + self._write_content_part_text(content[content_idx_optional], guardrail_response) async def process_output_response( self, @@ -1381,7 +1389,8 @@ class OpenAIResponsesHandler(BaseTranslation): if isinstance(output_index, int) and isinstance(content_index, int) ) if len(placeable_positions) != len(scanned_positions) or any( - stream_item_field(event, "type") not in _OUTPUT_TEXT_EVENT_TYPES for event in scanned_events + stream_item_field(event, "type") not in _OUTPUT_TEXT_EVENT_TYPES | _TEXT_DELTA_EVENT_TYPES + for event in scanned_events ): from litellm.proxy.policy_engine.pipeline_executor import UndeliverableStreamRewrite @@ -1402,6 +1411,12 @@ class OpenAIResponsesHandler(BaseTranslation): else: setattr(event, field, value) + @staticmethod + def _write_content_part_text(part: object, text: str) -> None: + field: Final = _content_part_text_field(part) + if _has_writable_field(part, field): + OpenAIResponsesHandler._write_event_field(part, field, text) + @staticmethod def _write_compaction_summary(item: object, summary: str) -> None: encrypted_content: Final = stream_item_field(item, "encrypted_content") @@ -1417,11 +1432,12 @@ class OpenAIResponsesHandler(BaseTranslation): ) -> None: """Sync pre-completion stream events with the rewritten completed response, keyed by ``(output_index, content_index)``: the first - ``output_text.delta`` for a rewritten item carries the full rewritten - text and the rest are blanked, while ``output_text.done``, - ``content_part.done``, and ``output_item.done`` events carry the full - rewritten text, so every event a client may read agrees with the - rewritten ``response.completed`` payload.""" + ``output_text.delta`` or ``refusal.delta`` for a rewritten item carries + the full rewritten text and the rest are blanked, while + ``output_text.done``, ``refusal.done``, ``content_part.done``, and + ``output_item.done`` events carry the full rewritten text, so every + event a client may read agrees with the rewritten ``response.completed`` + payload.""" delta_replacements: Final = MappingProxyType( {position: chain((rewritten,), repeat("")) for position, rewritten in rewrites_by_position.items()} ) @@ -1437,14 +1453,14 @@ class OpenAIResponsesHandler(BaseTranslation): if not isinstance(output_index, int) or not isinstance(content_index, int): continue position = (output_index, content_index) - if event_type == "response.output_text.delta" and position in delta_replacements: + if event_type in _TEXT_DELTA_EVENT_TYPES and position in delta_replacements: self._write_event_field(event, "delta", next(delta_replacements[position])) elif event_type == "response.output_text.done" and position in rewrites_by_position: self._write_event_field(event, "text", rewrites_by_position[position]) + elif event_type == "response.refusal.done" and position in rewrites_by_position: + self._write_event_field(event, "refusal", rewrites_by_position[position]) elif event_type == "response.content_part.done" and position in rewrites_by_position: - part = event.get("part") - if isinstance(part, dict) or hasattr(part, "text"): - self._write_event_field(part, "text", rewrites_by_position[position]) + self._write_content_part_text(event.get("part"), rewrites_by_position[position]) @staticmethod def _sync_output_item_done_event( @@ -1460,7 +1476,7 @@ class OpenAIResponsesHandler(BaseTranslation): for (item_idx, content_idx), rewritten in rewrites_by_position.items(): if item_idx != output_index or not 0 <= content_idx < len(content): continue - OpenAIResponsesHandler._write_event_field(content[content_idx], "text", rewritten) + OpenAIResponsesHandler._write_content_part_text(content[content_idx], rewritten) def _deliver_ended_stream_tool_call_rewrites( self, @@ -1815,7 +1831,7 @@ class OpenAIResponsesHandler(BaseTranslation): return # Handle both GenericResponseOutputItem and dict - content: list[OutputText | ResponseOutputRefusal] | list[dict] | None = None + content: list[OutputText | ResponseOutputRefusal] | list[dict[str, object]] | None = None if isinstance(output_item, BaseModel): try: output_item_dump: Final = output_item.model_dump() @@ -1838,17 +1854,9 @@ class OpenAIResponsesHandler(BaseTranslation): verbose_proxy_logger.debug("OpenAI Responses API: Processing output item: %s", output_item) - # 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): - text_content = content_item.text - elif isinstance(content_item, dict): - text_content = content_item.get("text") - else: - continue - - if text_content: + text_content = stream_item_field(content_item, _content_part_text_field(content_item)) + if isinstance(text_content, str) and text_content: texts_to_check.append(text_content) task_mappings.append((output_idx, int(content_idx))) @@ -1888,33 +1896,24 @@ class OpenAIResponsesHandler(BaseTranslation): # Handle both GenericResponseOutputItem, BaseModel, and dict 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): - content_item.text = guardrail_response - elif isinstance(content_item, dict): - content_item["text"] = guardrail_response + self._write_content_part_text(output_item.content[content_idx], guardrail_response) elif isinstance(output_item, BaseModel): # Handle other Pydantic models by converting to GenericResponseOutputItem try: 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): - content_item.text = guardrail_response - # Update the original response output - if hasattr(output_item, "content") and output_item.content: - original_content = output_item.content[content_idx] - if hasattr(original_content, "text"): - original_content.text = guardrail_response + if ( + generic_item.content + and content_idx < len(generic_item.content) + and hasattr(output_item, "content") + and output_item.content + ): + self._write_content_part_text(output_item.content[content_idx], guardrail_response) except Exception: pass elif isinstance(output_item, dict): content = output_item.get("content", []) if content and content_idx < len(content): - if isinstance(content[content_idx], dict): - content[content_idx]["text"] = guardrail_response - elif hasattr(content[content_idx], "text"): - content[content_idx].text = guardrail_response + self._write_content_part_text(content[content_idx], guardrail_response) def build_block_sse_chunks( self, diff --git a/tests/unit/llms/openai/responses/test_openai_responses_guardrail_handler.py b/tests/unit/llms/openai/responses/test_openai_responses_guardrail_handler.py index d732d922375..3eb5f544ac6 100644 --- a/tests/unit/llms/openai/responses/test_openai_responses_guardrail_handler.py +++ b/tests/unit/llms/openai/responses/test_openai_responses_guardrail_handler.py @@ -25,6 +25,9 @@ from openai.types.responses import ( ResponseCustomToolCallInputDeltaEvent, ResponseCustomToolCallInputDoneEvent, ResponseFunctionToolCall, + ResponseOutputMessage, + ResponseOutputRefusal, + ResponseOutputText, ) from litellm.integrations.custom_guardrail import CustomGuardrail @@ -39,7 +42,16 @@ from litellm.llms.custom_httpx.http_handler import AsyncHTTPHandler from litellm.proxy.guardrails.guardrail_hooks.bedrock_guardrails import BedrockGuardrail from litellm.proxy.guardrails.guardrail_hooks.litellm_content_filter.content_filter import ContentFilterGuardrail from litellm.types.guardrails import ContentFilterAction, ContentFilterPattern -from litellm.types.llms.openai import ChatCompletionToolCallChunk +from litellm.types.llms.openai import ( + ChatCompletionToolCallChunk, + ContentPartDoneEvent, + ContentPartDonePartRefusal, + OutputItemDoneEvent, + RefusalDeltaEvent, + RefusalDoneEvent, + ResponseIncompleteEvent, + ResponsesAPIStreamEvents, +) from litellm.responses.litellm_completion_transformation.compaction_items import compaction_summary from litellm.responses.litellm_completion_transformation.transformation import ( LiteLLMCompletionResponsesConfig, @@ -5017,3 +5029,183 @@ class TestCompactionOutputSummaryReachesOutputGuardrails: ) assert ended_key(self.SUMMARY) != ended_key("The user lives elsewhere.") + + +_REFUSAL: Final = "I can't share where Jane lives." +_MASKED_REFUSAL: Final = "I can't share where [NAME] lives." + + +class NameMaskingGuardrail(CustomGuardrail): + def __init__(self, guardrail_name: str) -> None: + super().__init__(guardrail_name=guardrail_name) + self.seen_texts: list[list[str]] = [] + + async def apply_guardrail( + self, + inputs: GenericGuardrailAPIInputs, + request_data: dict[str, object], + input_type: Literal["request", "response"], + logging_obj: LiteLLMLoggingObj | None = None, + ) -> GenericGuardrailAPIInputs: + texts: Final = list(inputs.get("texts", [])) + self.seen_texts.append(texts) + return {**inputs, "texts": [text.replace("Jane", "[NAME]") for text in texts]} + + +def _refused_message(*leading_text: str) -> GenericResponseOutputItem: + return GenericResponseOutputItem( + type="message", + id="msg_123", + status="incomplete", + role="assistant", + content=[ + *(OutputText(type="output_text", text=text, annotations=[]) for text in leading_text), + ResponseOutputRefusal(type="refusal", refusal=_REFUSAL), + ], + ) + + +def _refused_response(*leading_text: str) -> ResponsesAPIResponse: + return ResponsesAPIResponse( + id="resp_123", + created_at=1234567890, + model="claude-opus-5-5", + object="response", + status="incomplete", + output=[_refused_message(*leading_text)], + ) + + +class TestRefusalPartsReachTextGuardrails: + @pytest.mark.asyncio + async def test_input_refusal_part_is_scanned_and_rewritten(self) -> None: + guardrail: Final = NameMaskingGuardrail(guardrail_name="test") + data: Final = { + "model": "claude-opus-5-5", + "input": [ + {"role": "user", "content": "Where does Jane live?"}, + {"type": "message", "role": "assistant", "content": [{"type": "refusal", "refusal": _REFUSAL}]}, + ], + } + + result: Final = await OpenAIResponsesHandler().process_input_messages(data, guardrail) + + assert guardrail.seen_texts == [["Where does Jane live?", _REFUSAL]] + assert result["input"][1]["content"] == [{"type": "refusal", "refusal": _MASKED_REFUSAL}] + + @pytest.mark.asyncio + @pytest.mark.parametrize( + ("leading_text", "expected_parts"), + [ + ((), [("refusal", _MASKED_REFUSAL)]), + (("Jane asked first.",), [("output_text", "[NAME] asked first."), ("refusal", _MASKED_REFUSAL)]), + ], + ids=["refusal_only", "text_then_refusal"], + ) + async def test_output_refusal_part_is_scanned_and_rewritten( + self, leading_text: tuple[str, ...], expected_parts: list[tuple[str, str]] + ) -> None: + guardrail: Final = NameMaskingGuardrail(guardrail_name="test") + + result: Final = await OpenAIResponsesHandler().process_output_response( + _refused_response(*leading_text), guardrail + ) + + assert guardrail.seen_texts == [[*leading_text, _REFUSAL]] + assert [ + (part["type"], part.get("text") or part.get("refusal")) for part in result.model_dump()["output"][0]["content"] + ] == expected_parts + + @pytest.mark.asyncio + async def test_output_refusal_part_in_an_openai_message_is_rewritten(self) -> None: + guardrail: Final = NameMaskingGuardrail(guardrail_name="test") + openai_message: Final = ResponseOutputMessage( + type="message", + id="msg_123", + role="assistant", + status="incomplete", + content=[ + ResponseOutputText(type="output_text", text="Jane asked first.", annotations=[]), + ResponseOutputRefusal(type="refusal", refusal=_REFUSAL), + ], + ) + + result: Final = await OpenAIResponsesHandler().process_output_response( + _refused_response().model_copy(update={"output": [openai_message]}), guardrail + ) + + assert guardrail.seen_texts == [["Jane asked first.", _REFUSAL]] + assert [ + (part["type"], part.get("text") or part.get("refusal")) for part in result.model_dump()["output"][0]["content"] + ] == [("output_text", "[NAME] asked first."), ("refusal", _MASKED_REFUSAL)] + + @pytest.mark.asyncio + async def test_streamed_refusal_events_carry_the_rewrite(self) -> None: + position: Final = {"item_id": "msg_123", "output_index": 0, "content_index": 0} + events: Final = [ + RefusalDeltaEvent(type=ResponsesAPIStreamEvents.REFUSAL_DELTA, delta=_REFUSAL, **position), + RefusalDoneEvent(type=ResponsesAPIStreamEvents.REFUSAL_DONE, refusal=_REFUSAL, **position), + ContentPartDoneEvent( + type=ResponsesAPIStreamEvents.CONTENT_PART_DONE, + part=ContentPartDonePartRefusal(type="refusal", refusal=_REFUSAL), + **position, + ), + OutputItemDoneEvent(type=ResponsesAPIStreamEvents.OUTPUT_ITEM_DONE, output_index=0, item=_refused_message()), + ResponseIncompleteEvent(type=ResponsesAPIStreamEvents.RESPONSE_INCOMPLETE, response=_refused_response()), + ] + + await OpenAIResponsesHandler().process_output_streaming_response( + responses_so_far=events, + guardrail_to_apply=NameMaskingGuardrail(guardrail_name="test"), + litellm_logging_obj=None, + deliver_ended_stream_rewrites=True, + ) + + assert [json.loads(event.model_dump_json()) for event in events] == [ + json.loads(event.model_dump_json()) + for event in ( + RefusalDeltaEvent(type=ResponsesAPIStreamEvents.REFUSAL_DELTA, delta=_MASKED_REFUSAL, **position), + RefusalDoneEvent(type=ResponsesAPIStreamEvents.REFUSAL_DONE, refusal=_MASKED_REFUSAL, **position), + ContentPartDoneEvent( + type=ResponsesAPIStreamEvents.CONTENT_PART_DONE, + part=ContentPartDonePartRefusal(type="refusal", refusal=_MASKED_REFUSAL), + **position, + ), + OutputItemDoneEvent( + type=ResponsesAPIStreamEvents.OUTPUT_ITEM_DONE, + output_index=0, + item=_refused_message().model_copy( + update={"content": [ResponseOutputRefusal(type="refusal", refusal=_MASKED_REFUSAL)]} + ), + ), + ResponseIncompleteEvent( + type=ResponsesAPIStreamEvents.RESPONSE_INCOMPLETE, + response=_refused_response().model_copy( + update={ + "output": [ + _refused_message().model_copy( + update={"content": [ResponseOutputRefusal(type="refusal", refusal=_MASKED_REFUSAL)]} + ) + ] + } + ), + ), + ) + ] + + @pytest.mark.asyncio + async def test_cut_refusal_stream_carries_the_rewrite(self) -> None: + position: Final = {"item_id": "msg_123", "output_index": 0, "content_index": 0} + events: Final = [ + RefusalDeltaEvent(type=ResponsesAPIStreamEvents.REFUSAL_DELTA, delta=_REFUSAL, **position), + RefusalDoneEvent(type=ResponsesAPIStreamEvents.REFUSAL_DONE, refusal=_REFUSAL, **position), + ] + + await OpenAIResponsesHandler().process_output_streaming_response( + responses_so_far=events, + guardrail_to_apply=NameMaskingGuardrail(guardrail_name="test"), + litellm_logging_obj=None, + deliver_ended_stream_rewrites=True, + ) + + assert (events[0].delta, events[1].refusal) == (_MASKED_REFUSAL, _MASKED_REFUSAL)