diff --git a/litellm/proxy/guardrails/guardrail_hooks/generic_guardrail_api/generic_guardrail_api.py b/litellm/proxy/guardrails/guardrail_hooks/generic_guardrail_api/generic_guardrail_api.py index ecd23d86540..999b13daeb4 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/generic_guardrail_api/generic_guardrail_api.py +++ b/litellm/proxy/guardrails/guardrail_hooks/generic_guardrail_api/generic_guardrail_api.py @@ -7,6 +7,7 @@ import fnmatch import os +import time from collections.abc import Callable, Mapping, Sequence from typing import TYPE_CHECKING, Final, Literal, Optional @@ -35,7 +36,7 @@ from litellm.types.proxy.guardrails.guardrail_hooks.generic_guardrail_api import GenericGuardrailAPIResponse, GuardrailToolParam, ) -from litellm.types.utils import GenericGuardrailAPIInputs +from litellm.types.utils import GenericGuardrailAPIInputs, GuardrailTracingDetail if TYPE_CHECKING: from litellm.litellm_core_utils.litellm_logging import Logging as LiteLLMLoggingObj @@ -260,6 +261,8 @@ class GenericGuardrailAPI(CustomGuardrail): { "action": "BLOCKED" | "NONE" | "GUARDRAIL_INTERVENED", "blocked_reason": str (optional, only if action is BLOCKED), + "intervention_reason": str (optional, only if action is GUARDRAIL_INTERVENED; logged and recorded + as a guardrail_intervened entry), "text": str (optional, modified text if action is GUARDRAIL_INTERVENED) } """ @@ -550,6 +553,7 @@ class GenericGuardrailAPI(CustomGuardrail): Raises: Exception: If the guardrail blocks the request """ + start_time: Final = time.time() verbose_proxy_logger.debug("Generic Guardrail API: Applying guardrail to text") # Extract texts and images from inputs @@ -626,6 +630,25 @@ class GenericGuardrailAPI(CustomGuardrail): blocked_content=True, ) + if guardrail_response.action == "GUARDRAIL_INTERVENED" and guardrail_response.intervention_reason: + end_time: Final = time.time() + verbose_proxy_logger.warning( + "Generic Guardrail API intervened: %s", guardrail_response.intervention_reason + ) + self.add_standard_logging_guardrail_information_to_request_data( + guardrail_json_response={ + "action": "GUARDRAIL_INTERVENED", + "intervention_reason": guardrail_response.intervention_reason, + }, + request_data=request_data, + guardrail_status="guardrail_intervened", + start_time=start_time, + end_time=end_time, + duration=end_time - start_time, + guardrail_provider=GUARDRAIL_NAME, + tracing_detail=GuardrailTracingDetail(guardrail_action="GUARDRAIL_INTERVENED"), + ) + return self._build_guardrail_return_inputs( texts=texts, images=images, diff --git a/litellm/types/proxy/guardrails/guardrail_hooks/generic_guardrail_api.py b/litellm/types/proxy/guardrails/guardrail_hooks/generic_guardrail_api.py index d38e54986b9..1a980d1b638 100644 --- a/litellm/types/proxy/guardrails/guardrail_hooks/generic_guardrail_api.py +++ b/litellm/types/proxy/guardrails/guardrail_hooks/generic_guardrail_api.py @@ -197,6 +197,7 @@ class GenericGuardrailAPIResponse: structured_messages: Sequence[AllMessageValues] | None action: str blocked_reason: str | None + intervention_reason: str | None stream_holdback_chars: list[int] | None def __init__( @@ -208,9 +209,11 @@ class GenericGuardrailAPIResponse: tools: list[GuardrailToolParam] | None = None, stream_holdback_chars: list[int] | None = None, structured_messages: Sequence[AllMessageValues] | None = None, + intervention_reason: str | None = None, ) -> None: self.action = action self.blocked_reason = blocked_reason + self.intervention_reason = intervention_reason self.texts = texts self.images = images self.tools = tools @@ -221,14 +224,16 @@ class GenericGuardrailAPIResponse: self.stream_holdback_chars = stream_holdback_chars @classmethod - def from_dict(cls, data: dict) -> "GenericGuardrailAPIResponse": + def from_dict(cls, data: dict[str, Any]) -> "GenericGuardrailAPIResponse": raw_holdback: Final = data.get("stream_holdback_chars") stream_holdback_chars: Final = ( [coerce_stream_holdback_value(value) for value in raw_holdback] if isinstance(raw_holdback, list) else None ) + raw_intervention_reason: Final = data.get("intervention_reason") return cls( action=data.get("action", "NONE"), blocked_reason=data.get("blocked_reason"), + intervention_reason=raw_intervention_reason if isinstance(raw_intervention_reason, str) else None, texts=data.get("texts"), images=data.get("images"), tools=data.get("tools"), diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/test_generic_guardrail_api.py b/tests/unit/proxy/guardrails/guardrail_hooks/test_generic_guardrail_api.py index 8308a7ba386..800308062f6 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/test_generic_guardrail_api.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/test_generic_guardrail_api.py @@ -29,7 +29,7 @@ from litellm.proxy.guardrails.guardrail_hooks.generic_guardrail_api import ( from litellm.proxy.guardrails.guardrail_hooks.generic_guardrail_api.generic_guardrail_api import ( _HEADER_PRESENT_PLACEHOLDER, ) -from litellm.types.utils import Choices, GenericGuardrailAPIInputs, Message +from litellm.types.utils import Choices, GenericGuardrailAPIInputs, Message, StandardLoggingGuardrailInformation @pytest.fixture @@ -1783,6 +1783,24 @@ class TestGenericGuardrailAPIStreamingConfig: class TestGenericGuardrailAPIResponseParsing: """GenericGuardrailAPIResponse.from_dict handling of the streaming holdback field.""" + def test_intervention_reason_parsed(self): + from litellm.types.proxy.guardrails.guardrail_hooks.generic_guardrail_api import ( + GenericGuardrailAPIResponse, + ) + + with_reason = GenericGuardrailAPIResponse.from_dict( + {"action": "GUARDRAIL_INTERVENED", "texts": ["a"], "intervention_reason": "why"} + ) + without_reason = GenericGuardrailAPIResponse.from_dict({"action": "GUARDRAIL_INTERVENED", "texts": ["a"]}) + + non_string_reason = GenericGuardrailAPIResponse.from_dict( + {"action": "GUARDRAIL_INTERVENED", "texts": ["a"], "intervention_reason": {"why": 1}} + ) + + assert with_reason.intervention_reason == "why" + assert without_reason.intervention_reason is None + assert non_string_reason.intervention_reason is None + def test_from_dict_parses_stream_holdback_chars(self): from litellm.types.proxy.guardrails.guardrail_hooks.generic_guardrail_api import ( GenericGuardrailAPIResponse, @@ -2621,3 +2639,89 @@ class TestNumRetries: assert sent.qsize() == num_retries + 1 assert result == {"texts": ["hi"]} + + +def _mock_api_response(payload: dict[str, object]) -> MagicMock: + response: Final = MagicMock() + response.json.return_value = payload + response.raise_for_status = MagicMock() + return response + + +TIMING_FIELDS: Final = frozenset({"start_time", "end_time", "duration"}) + + +def _without_timing(entry: StandardLoggingGuardrailInformation) -> dict[str, object]: + return {key: value for key, value in entry.items() if key not in TIMING_FIELDS} + + +def _assert_timed(entry: StandardLoggingGuardrailInformation) -> None: + start_time: Final = entry.get("start_time") + end_time: Final = entry.get("end_time") + duration: Final = entry.get("duration") + assert isinstance(start_time, float) + assert isinstance(end_time, float) + assert isinstance(duration, float) + assert end_time >= start_time + assert duration >= 0 + + +@pytest.mark.asyncio +async def test_intervened_with_reason_logs_and_records( + generic_guardrail: GenericGuardrailAPI, caplog: pytest.LogCaptureFixture +): + """An intervention_reason must be warned about and recorded as one timed guardrail_intervened entry.""" + response: Final = _mock_api_response( + {"action": "GUARDRAIL_INTERVENED", "texts": ["a"], "intervention_reason": "why"} + ) + metadata: Final[dict[str, list[StandardLoggingGuardrailInformation]]] = {} + request_data: Final[dict[str, object]] = {"metadata": metadata} + + with patch.object(generic_guardrail.async_handler, "post", return_value=response), caplog.at_level(logging.WARNING): + await generic_guardrail.apply_guardrail( + inputs={"texts": ["b"]}, request_data=request_data, input_type="request" + ) + + assert [(record.levelname, record.getMessage()) for record in caplog.records] == [ + ("WARNING", "Generic Guardrail API intervened: why") + ] + entries: Final = metadata["standard_logging_guardrail_information"] + assert [_without_timing(entry) for entry in entries] == [ + { + "guardrail_name": "test-generic-guardrail", + "guardrail_provider": "generic_guardrail_api", + "guardrail_mode": "pre_call", + "guardrail_response": {"action": "GUARDRAIL_INTERVENED", "intervention_reason": "why"}, + "guardrail_status": "guardrail_intervened", + "masked_entity_count": None, + "guardrail_action": "GUARDRAIL_INTERVENED", + } + ] + _assert_timed(entries[0]) + + +@pytest.mark.asyncio +async def test_intervened_without_reason_unchanged( + generic_guardrail: GenericGuardrailAPI, caplog: pytest.LogCaptureFixture +): + """Without an intervention_reason the decorator's success entry must be the only record, with no warning.""" + response: Final = _mock_api_response({"action": "GUARDRAIL_INTERVENED", "texts": ["a"]}) + metadata: Final[dict[str, list[StandardLoggingGuardrailInformation]]] = {} + request_data: Final[dict[str, object]] = {"metadata": metadata} + + with patch.object(generic_guardrail.async_handler, "post", return_value=response), caplog.at_level(logging.WARNING): + await generic_guardrail.apply_guardrail( + inputs={"texts": ["b"]}, request_data=request_data, input_type="request" + ) + + assert [(record.levelname, record.getMessage()) for record in caplog.records] == [] + assert [_without_timing(entry) for entry in metadata["standard_logging_guardrail_information"]] == [ + { + "guardrail_name": "test-generic-guardrail", + "guardrail_provider": None, + "guardrail_mode": "pre_call", + "guardrail_response": "mask", + "guardrail_status": "success", + "masked_entity_count": None, + } + ]