feat(guardrails): add decision model guardrail with Admin UI flow

litellm/decisions/main.py

@@ -63,7 +63,7 @@ class _DecisionsCall:
     litellm_params: Mapping[str, object] = field(repr=False)
 
 
-def _supported_providers() -> tuple[str, ...]:
+def supported_decisions_providers() -> tuple[str, ...]:
     return tuple(
         provider.value
         for provider in LlmProviders
@@ -77,7 +77,7 @@ def _provider_config(model: str, custom_llm_provider: str) -> BaseDecisionsConfi
         None if provider is None else ProviderConfigManager.get_provider_decisions_config(model, provider)
     )
     if provider_config is None:
-        supported: Final = ", ".join(_supported_providers())
+        supported: Final = ", ".join(supported_decisions_providers())
         raise litellm.BadRequestError(
             message=f"Unknown Decisions provider '{custom_llm_provider}'. Supported providers: {supported}",
             model=model,

litellm/proxy/_lazy_openapi_snapshot.json

@@ -11672,6 +11672,32 @@
               "description": "Will mask response content if guardrail makes any changes",
               "title": "Mask Response Content"
             },
+            "max_concurrent_decision_calls": {
+              "anyOf": [
+                {
+                  "exclusiveMinimum": 0.0,
+                  "type": "integer"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Maximum decisions calls in flight at once on the guardrail in each proxy worker. Implemented by guardrail='decision_model'.",
+              "title": "Max Concurrent Decision Calls"
+            },
+            "max_input_chars": {
+              "anyOf": [
+                {
+                  "exclusiveMinimum": 0.0,
+                  "type": "integer"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Character budget for each text sent to the guardrail's model. Implemented by guardrail='decision_model'.",
+              "title": "Max Input Chars"
+            },
             "model": {
               "anyOf": [
                 {
@@ -11971,7 +11997,7 @@
             },
             "unreachable_fallback": {
               "default": "fail_closed",
-              "description": "Behavior when a guardrail endpoint is unreachable due to network errors. Implemented by guardrail='generic_guardrail_api', 'agent_365', 'akto', 'vigil_guard', 'repelloai', 'headroom', 'compresr', and 'typesafe'. 'fail_closed' raises an error (default). 'fail_open' logs a critical error and allows the request to proceed.",
+              "description": "Behavior when a guardrail endpoint is unreachable due to network errors. Implemented by guardrail='generic_guardrail_api', 'agent_365', 'akto', 'vigil_guard', 'repelloai', 'headroom', 'compresr', and 'typesafe'. 'fail_closed' raises an error (default). 'fail_open' logs a critical error and allows the request to proceed. Also implemented by guardrail='decision_model'.",
               "enum": [
                 "fail_closed",
                 "fail_open"
@@ -12513,6 +12539,43 @@
           "title": "CreateGuardrailRequest",
           "type": "object"
         },
+        "DecisionModelCheck": {
+          "description": "One predicate the decision model scores the request or response against.",
+          "properties": {
+            "action": {
+              "default": "block",
+              "enum": [
+                "block",
+                "log"
+              ],
+              "title": "Action",
+              "type": "string"
+            },
+            "instructions": {
+              "minLength": 1,
+              "title": "Instructions",
+              "type": "string"
+            },
+            "name": {
+              "minLength": 1,
+              "title": "Name",
+              "type": "string"
+            },
+            "threshold": {
+              "default": 0.7,
+              "maximum": 1.0,
+              "minimum": 0.0,
+              "title": "Threshold",
+              "type": "number"
+            }
+          },
+          "required": [
+            "name",
+            "instructions"
+          ],
+          "title": "DecisionModelCheck",
+          "type": "object"
+        },
         "GUARDRAIL_DEFINITION_LOCATION": {
           "enum": [
             "db",
@@ -12845,6 +12908,13 @@
               ],
               "title": "Content Filter Settings"
             },
+            "decision_model_providers": {
+              "items": {
+                "type": "string"
+              },
+              "title": "Decision Model Providers",
+              "type": "array"
+            },
             "pii_entity_categories": {
               "items": {
                 "$ref": "#/components/schemas/PiiEntityCategoryMap"
@@ -13505,11 +13575,18 @@
                 {
                   "$ref": "#/components/schemas/BedrockChecksConfigModel"
                 },
+                {
+                  "items": {
+                    "$ref": "#/components/schemas/DecisionModelCheck"
+                  },
+                  "type": "array"
+                },
                 {
                   "type": "null"
                 }
               ],
-              "description": "Inline safeguards for the resource-less InvokeGuardrailChecks API (contentFilter / promptAttack / sensitiveInformation). When set, the guardrail calls InvokeGuardrailChecks instead of ApplyGuardrail and no guardrailIdentifier is required. Mutually exclusive with guardrailIdentifier."
+              "description": "Inline Bedrock InvokeGuardrailChecks config for guardrail='bedrock', or the predicate checks a decision_model guardrail scores for guardrail='decision_model'",
+              "title": "Checks"
             },
             "chunk_budget_chars": {
               "default": 25000,
@@ -13641,6 +13718,18 @@
               "description": "Python-like code containing the apply_guardrail function for custom guardrail logic",
               "title": "Custom Code"
             },
+            "decision_model": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "For guardrail='decision_model': the Decisions-API model that scores each check",
+              "title": "Decision Model"
+            },
             "deepkeep_firewall_id": {
               "anyOf": [
                 {
@@ -14103,6 +14192,32 @@
               "description": "Will mask response content if guardrail makes any changes",
               "title": "Mask Response Content"
             },
+            "max_concurrent_decision_calls": {
+              "anyOf": [
+                {
+                  "exclusiveMinimum": 0.0,
+                  "type": "integer"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Maximum decisions calls in flight at once on the guardrail in each proxy worker. Implemented by guardrail='decision_model'.",
+              "title": "Max Concurrent Decision Calls"
+            },
+            "max_input_chars": {
+              "anyOf": [
+                {
+                  "exclusiveMinimum": 0.0,
+                  "type": "integer"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Character budget for each text sent to the guardrail's model. Implemented by guardrail='decision_model'.",
+              "title": "Max Input Chars"
+            },
             "metadata": {
               "anyOf": [
                 {

litellm/proxy/guardrails/guardrail_endpoints.py

@@ -1496,6 +1496,7 @@ async def get_guardrail_ui_settings() -> GuardrailUIAddGuardrailSettings:
     - PII entity categories for UI organization
     - Content filter settings (patterns and categories)
     """
+    from litellm.decisions.main import supported_decisions_providers
     from litellm.proxy.guardrails.guardrail_hooks.litellm_content_filter.patterns import (
         PATTERN_CATEGORIES,
         get_available_content_categories,
@@ -1533,6 +1534,7 @@ async def get_guardrail_ui_settings() -> GuardrailUIAddGuardrailSettings:
         supported_modes_by_provider=supported_modes_by_provider,
         providers_without_directional_logging_only_scope=providers_without_directional_logging_only_scope,
         pii_entity_categories=category_maps,
+        decision_model_providers=supported_decisions_providers(),
         content_filter_settings={
             "prebuilt_patterns": get_pattern_metadata(),
             "pattern_categories": list(PATTERN_CATEGORIES.keys()),

litellm/proxy/guardrails/guardrail_hooks/decision_model/__init__.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Final
+
+from pydantic import TypeAdapter, ValidationError
+
+from litellm.types.guardrails import (
+    GuardrailEventHooks,
+    Mode,
+    SupportedGuardrailIntegrations,
+)
+from litellm.types.proxy.guardrails.guardrail_hooks.decision_model import (
+    DecisionModelCheck,
+)
+
+from .decision_model import DecisionModelGuardrail
+
+if TYPE_CHECKING:
+    from litellm.types.guardrails import Guardrail, LitellmParams
+
+_CHECKS_ADAPTER: Final = TypeAdapter(list[DecisionModelCheck])
+
+
+def _coerce_event_hook(
+    mode: str | Sequence[str] | Mode,
+) -> GuardrailEventHooks | tuple[GuardrailEventHooks, ...] | Mode:
+    if isinstance(mode, Mode):
+        return mode
+    if isinstance(mode, str):
+        return GuardrailEventHooks(mode)
+    return tuple(GuardrailEventHooks(item) for item in mode)
+
+
+def _parse_checks(raw_checks: object) -> tuple[DecisionModelCheck, ...]:
+    try:
+        checks: Final = _CHECKS_ADAPTER.validate_python(raw_checks)
+    except ValidationError as error:
+        raise ValueError(f"decision_model guardrail has invalid checks: {error}") from error
+    return tuple(checks)
+
+
+def _streaming_end_of_stream_only(litellm_params: LitellmParams) -> bool:
+    value: Final[object] = getattr(litellm_params, "streaming_end_of_stream_only", None)
+    if value is None:
+        return False
+    if not isinstance(value, bool):
+        raise TypeError(f"decision_model guardrail streaming_end_of_stream_only must be a boolean, got {value!r}")
+    return value
+
+
+def _streaming_sampling_rate(litellm_params: LitellmParams) -> int:
+    value: Final[object] = getattr(litellm_params, "streaming_sampling_rate", None)
+    if value is None:
+        return 5
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise TypeError(f"decision_model guardrail streaming_sampling_rate must be an integer, got {value!r}")
+    if value < 1:
+        raise ValueError(f"decision_model guardrail streaming_sampling_rate must be at least 1, got {value}")
+    return value
+
+
+def initialize_guardrail(litellm_params: LitellmParams, guardrail: Guardrail) -> DecisionModelGuardrail:
+    import litellm
+
+    decision_model: Final = litellm_params.decision_model
+    if not decision_model:
+        raise ValueError("decision_model guardrail requires decision_model in litellm_params")
+
+    checks: Final = _parse_checks(litellm_params.checks)
+
+    _callback: Final = DecisionModelGuardrail(
+        guardrail_name=guardrail["guardrail_name"],
+        decision_model=decision_model,
+        checks=checks,
+        event_hook=_coerce_event_hook(litellm_params.mode),
+        default_on=litellm_params.default_on or False,
+        unreachable_fallback=(
+            litellm_params.unreachable_fallback
+            if "unreachable_fallback" in litellm_params.model_fields_set
+            else "fail_closed"
+        ),
+        max_input_chars=litellm_params.max_input_chars or 24000,
+        timeout=litellm_params.timeout,
+        max_concurrent_decision_calls=litellm_params.max_concurrent_decision_calls or 8,
+        streaming_end_of_stream_only=_streaming_end_of_stream_only(litellm_params),
+        streaming_sampling_rate=_streaming_sampling_rate(litellm_params),
+    )
+    litellm.logging_callback_manager.add_litellm_callback(  # pyright: ignore[reportUnknownMemberType]  # callback manager is untyped
+        _callback
+    )
+    return _callback
+
+
+guardrail_initializer_registry: Final = {
+    SupportedGuardrailIntegrations.DECISION_MODEL.value: initialize_guardrail,
+}
+
+guardrail_class_registry: Final = {
+    SupportedGuardrailIntegrations.DECISION_MODEL.value: DecisionModelGuardrail,
+}
+
+
+__all__ = [
+    "DecisionModelGuardrail",
+    "guardrail_class_registry",
+    "guardrail_initializer_registry",
+    "initialize_guardrail",
+]