[Guardrails] Add guardrail pipeline support for conditional sequential execution

[ishaan-jaff]

Summary

• Adds pipeline support to the policy engine, enabling conditional sequential guardrail execution (e.g., if a cheap guardrail fails, escalate to an expensive one before blocking)
• Pipelines are configured via pipeline: field in policies with ordered steps and conditional actions (allow, block, next, modify_response)
• Supports data forwarding between steps (e.g., PII masking step passes redacted data to next step)
• Pipeline-managed guardrails are excluded from the normal independent callback loop to avoid double execution

Example Config

guardrails:
  - guardrail_name: "simple-content-filter"
    litellm_params:
      guardrail: litellm_content_filter
      mode: "pre_call"
  - guardrail_name: "permissive-filter"
    litellm_params:
      guardrail: my_custom_guardrails.PermissiveFilter
      mode: "pre_call"

policies:
  content-safety:
    description: "Multi-tier: simple filter with permissive fallback"
    guardrails:
      add: [simple-content-filter, permissive-filter]
    pipeline:
      mode: "pre_call"
      steps:
        - guardrail: simple-content-filter
          on_fail: next       # if simple filter fails, escalate
          on_pass: allow      # if it passes, allow the request
        - guardrail: permissive-filter
          on_fail: block      # if both fail, block
          on_pass: allow      # if permissive passes, allow

policy_attachments:
  - policy: content-safety
    models: [gpt-4o, claude-sonnet]

How it works

1. Request comes in → simple-content-filter runs first
2. If it passes → request is allowed immediately (step 2 never runs)
3. If it fails → escalates to permissive-filter (step 2)
4. If permissive-filter passes → request is allowed
5. If permissive-filter fails → request is blocked

Available actions

Action	Behavior
allow	Request proceeds (terminal)
block	Reject with HTTP 400 (terminal)
next	Continue to next step
modify_response	Return custom 200 response (terminal)

Data forwarding

Steps can forward modified data (e.g., PII masking) to the next step with pass_data: true:

steps:
  - guardrail: pii-masker
    on_pass: next
    pass_data: true        # masked data forwarded to next step
  - guardrail: content-check
    on_fail: block
    on_pass: allow

Test plan

• 15 unit tests for pipeline type validation (defaults, valid/invalid actions, modes, extra fields)
• 9 unit tests for pipeline executor (escalation, early allow, data forwarding, guardrail not found, single step, duration tracking)
• E2E validated with proxy: clean content passes, blocked content escalates correctly
• E2E validated with real litellm content filter as guardrail A with custom guardrail B fallback
• All 24 new tests pass, pre-commit hooks pass on all files

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
litellm	Error		Feb 14, 2026 2:24am

[greptile-apps]

Greptile Overview

Greptile Summary

This PR adds guardrail pipeline support to the policy engine, enabling conditional sequential guardrail execution (e.g., if a cheap guardrail fails, escalate to an expensive one before blocking). Pipelines are defined as ordered steps within a policy's pipeline: field, each with configurable on_pass/on_fail actions (allow, block, next, modify_response). Pipeline-managed guardrails are excluded from the normal independent callback loop to avoid double execution.

• New PipelineExecutor class handles sequential step execution with data forwarding between steps
• New Pydantic types (PipelineStep, GuardrailPipeline, PipelineExecutionResult, PipelineStepResult) with proper validation
• Policy resolver, validator, and registry extended to support pipeline configuration
• Integration into pre_call_hook in ProxyLogging to execute pipelines before the normal callback loop
• 24 unit tests covering type validation, executor logic, escalation, early allow, data forwarding, and error handling — all mock-based with no real network calls
• Example config and test guardrails provided for E2E validation

The implementation follows existing codebase patterns (e.g., "apply_guardrail" in type(callback).__dict__ check for unified guardrail path). The shallow copy in execute_steps and the silent fallthrough for unrecognized terminal actions are minor concerns noted in inline comments.

Confidence Score: 4/5

• This PR is safe to merge with minor improvements recommended — no critical bugs, well-tested, follows existing patterns.
• The PR is well-structured with comprehensive test coverage (24 tests, all mock-based). It follows existing codebase patterns consistently. The main concerns are minor: shallow copy of data dict (latent mutation risk), silent fallthrough for unrecognized terminal actions, and error outcomes using the on_fail path without differentiation. None of these are blocking issues — they are defensive improvements that could be addressed in follow-up.
• litellm/proxy/policy_engine/pipeline_executor.py (shallow copy and error handling concerns), litellm/proxy/utils.py (silent fallthrough in _handle_pipeline_result)

Important Files Changed

Filename	Overview
litellm/proxy/policy_engine/pipeline_executor.py	New pipeline executor with ordered guardrail execution. Shallow copy of data dict could cause subtle bugs with nested mutations; data["guardrail_to_apply"] mutation leaks into working_data between steps.
litellm/types/proxy/policy_engine/pipeline_types.py	Well-structured Pydantic type definitions for pipeline steps, execution results, and guardrail pipelines with proper validation. No issues found.
litellm/proxy/policy_engine/policy_resolver.py	Adds pipeline resolution methods to existing PolicyResolver. Clean code, follows existing patterns. No issues found.
litellm/proxy/policy_engine/policy_validator.py	Adds pipeline validation that checks guardrails exist in both the policy's add list and registry. Well-structured, follows existing patterns.
litellm/proxy/policy_engine/policy_registry.py	Adds pipeline parsing to policy registry's YAML config loading. Clean implementation matching existing patterns.
litellm/proxy/utils.py	Integrates pipeline execution into pre_call_hook with pipeline-managed guardrail skipping. _handle_pipeline_result has a silent fallthrough for unrecognized terminal_action values.
litellm/proxy/litellm_pre_call_utils.py	Resolves pipelines from policies and stores them in metadata. Properly excludes pipeline-managed guardrails from the flat guardrail list to avoid double execution.
tests/test_litellm/proxy/policy_engine/test_pipeline_executor.py	Thorough mock-based unit tests covering escalation, early allow, data forwarding, error handling, and duration tracking. No real network calls.
tests/test_litellm/types/proxy/policy_engine/test_pipeline_types.py	Complete Pydantic validation tests for pipeline types: defaults, valid/invalid actions, modes, extra fields, and policy integration.

Sequence Diagram

sequenceDiagram
    participant Client
    participant PreCallUtils as Pre-Call Utils
    participant PolicyResolver as Policy Resolver
    participant ProxyLogging as ProxyLogging.pre_call_hook
    participant PipelineExec as PipelineExecutor
    participant GuardrailA as Guardrail A (cheap)
    participant GuardrailB as Guardrail B (expensive)
    participant CallbackLoop as Normal Callback Loop

    Client->>PreCallUtils: Request with model/team context
    PreCallUtils->>PolicyResolver: resolve_pipelines_for_context()
    PolicyResolver-->>PreCallUtils: [(policy_name, pipeline)]
    PreCallUtils->>PreCallUtils: Store pipelines + managed guardrails in metadata
    PreCallUtils->>PreCallUtils: Exclude pipeline guardrails from flat list

    PreCallUtils->>ProxyLogging: pre_call_hook(data)
    ProxyLogging->>PipelineExec: _maybe_execute_pipelines()

    PipelineExec->>GuardrailA: Step 1: async_pre_call_hook()
    alt Guardrail A passes (on_pass: allow)
        GuardrailA-->>PipelineExec: pass
        PipelineExec-->>ProxyLogging: allow (skip Step 2)
    else Guardrail A fails (on_fail: next)
        GuardrailA-->>PipelineExec: fail (HTTPException 400)
        PipelineExec->>GuardrailB: Step 2: async_pre_call_hook()
        alt Guardrail B passes (on_pass: allow)
            GuardrailB-->>PipelineExec: pass
            PipelineExec-->>ProxyLogging: allow
        else Guardrail B fails (on_fail: block)
            GuardrailB-->>PipelineExec: fail
            PipelineExec-->>ProxyLogging: block
            ProxyLogging-->>Client: HTTPException 400
        end
    end

    ProxyLogging->>CallbackLoop: Run non-pipeline guardrails
    Note over CallbackLoop: Skips guardrails managed by pipeline

Loading

_{Last reviewed commit: 31e3e61}

[greptile-apps]

_{16 files reviewed, 3 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

"error" outcome silently uses on_fail action

When outcome is "error" (e.g., guardrail not found, unexpected exception), the code falls into the else branch and uses step.on_fail. This means if on_fail is "next", unexpected runtime errors (not guardrail interventions) will be silently swallowed and the pipeline will continue to the next step.

This is a design choice, but it means a misconfigured guardrail name or a transient error could be invisible to the operator when on_fail: next is set. Consider either logging at warning level when outcome == "error" and action is "next", or introducing a separate on_error action field.