This commit is contained in:
Joshua Hoblitt 2026-10-26 12:20:58 -04:00 • committed by GitHub
commit eddcf7c2c1
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 135 additions and 3 deletions

View file

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

View file

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

View file

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