fix(responses): scan refusal parts in Responses guardrails

This commit is contained in:
mateo-berri 2026-10-31 01:57:17 -07:00
parent a1b098f4c4
commit 02b2ccf32e
2 changed files with 235 additions and 44 deletions

View file

@ -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,

View file

@ -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)