Implementation:Guardrails ai Guardrails Filter Action

Knowledge Sources	Guardrails
Domains	Validation, Actions
Last Updated	2026-02-14 00:00 GMT

Overview

The Filter action class and apply_filters function provide a mechanism for recursively removing values from LLM outputs that fail validation.

Description

This module defines the Filter sentinel class and the apply_filters utility function. When a validator determines that a particular value in the LLM output should be removed, it wraps that value as a Filter instance. The apply_filters function then recursively traverses the output data structure (lists, dicts, or scalar values) and removes any entries that are instances of Filter. For lists, filtered items are omitted entirely. For dictionaries, keys whose values are filtered are removed. Scalar Filter instances return None.

Usage

Use Filter when you want validators to silently remove offending values from the output rather than rejecting the entire response. This is particularly useful for list or dictionary outputs where partial results are acceptable. Assign Filter as the on-fail action in a Guard configuration, and the framework will automatically invoke apply_filters on the validated output.

Code Reference

Source Location

• Repository: Guardrails
• File: guardrails/actions/filter.py
• Lines: 1-38

Signature

class Filter:
    pass

def apply_filters(value: Any) -> Any:
    """Recursively filter out any values that are instances of Filter."""

Import

from guardrails.actions.filter import Filter, apply_filters

I/O Contract

apply_filters

Parameter	Type	Description
value	Any	The value or nested data structure to filter. Can be a scalar, List, Dict, or Filter instance.

Return Type	Description
Any	The filtered data structure with all Filter instances removed. Returns None for top-level Filter values.

Behavior by Type

Input Type	Behavior
Filter	Returns None (implicitly via pass).
List	Recursively filters each element; items that resolve to None are omitted from the returned list.
Dict	Recursively filters each value; keys whose values resolve to None are omitted from the returned dict.
Other	Returns the value unchanged.

Usage Examples

from guardrails.actions.filter import Filter, apply_filters

# Filtering a list with some invalid items
data = ["valid", Filter(), "also valid"]
result = apply_filters(data)
# result: ["valid", "also valid"]

# Filtering a dictionary with an invalid value
data = {"name": "Alice", "bad_field": Filter(), "age": 30}
result = apply_filters(data)
# result: {"name": "Alice", "age": 30}

# Nested filtering
data = {"users": [{"name": "Bob"}, Filter(), {"name": "Eve"}]}
result = apply_filters(data)
# result: {"users": [{"name": "Bob"}, {"name": "Eve"}]}

# Scalar Filter
result = apply_filters(Filter())
# result: None

Related Pages

• Implementation:Guardrails_ai_Guardrails_Refrain_Action - The complementary action that rejects the entire output instead of filtering individual values
• Implementation:Guardrails_ai_Guardrails_OutputTypes - Output type enumeration used in conjunction with actions