Implementation:Guardrails ai Guardrails Refrain Action

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

Overview

The Refrain action class and associated functions provide a mechanism for rejecting an entire LLM output when any value fails validation.

Description

This module defines the Refrain sentinel class along with two utility functions: check_for_refrain and apply_refrain. When a validator marks a value with Refrain, the entire output is deemed invalid. The check_for_refrain function recursively traverses a data structure (lists or dicts) to detect any Refrain instances. If found, apply_refrain replaces the entire output with an empty value appropriate to the output type: an empty string for STRING, an empty list for LIST, or an empty dict for DICT.

Usage

Use Refrain when any single validation failure should cause the entire LLM output to be discarded. This is more aggressive than Filter, which only removes individual offending values. Set Refrain as the on-fail action in a Guard configuration when partial outputs are unacceptable.

Code Reference

Source Location

• Repository: Guardrails
• File: guardrails/actions/refrain.py
• Lines: 1-43

Signature

class Refrain:
    pass

def check_for_refrain(value: Union[List, Dict]) -> bool:
    """Recursively check if any value is an instance of Refrain."""

def apply_refrain(value: Any, output_type: OutputTypes) -> Any:
    """Recursively check for any values that are instances of Refrain.
    If found, return an empty value of the appropriate type."""

Import

from guardrails.actions.refrain import Refrain, check_for_refrain, apply_refrain

I/O Contract

check_for_refrain

Parameter	Type	Description
value	Union[List, Dict]	The data structure to check for Refrain instances.

Return Type	Description
bool	True if any Refrain instance is found in the data structure; False otherwise.

apply_refrain

Parameter	Type	Description
value	Any	The validated output to check and potentially replace.
output_type	OutputTypes	The expected output type, used to determine the empty replacement value.

Return Type	Description
Any	The original value if no Refrain found, otherwise an empty value matching the output type.

Empty Value by OutputType

OutputType	Refrain Replacement
STRING	"" (empty string)
LIST	[] (empty list)
DICT	{} (empty dict)

Usage Examples

from guardrails.actions.refrain import Refrain, check_for_refrain, apply_refrain
from guardrails.classes.output_type import OutputTypes

# Check if refrain is present in nested data
data = {"name": "Alice", "score": Refrain()}
has_refrain = check_for_refrain(data)
# has_refrain: True

# Apply refrain to replace the entire output
result = apply_refrain(data, OutputTypes.DICT)
# result: {}

# No refrain present - output is returned as-is
clean_data = {"name": "Alice", "score": 95}
result = apply_refrain(clean_data, OutputTypes.DICT)
# result: {"name": "Alice", "score": 95}

# Refrain in a list context
list_data = ["hello", Refrain()]
result = apply_refrain(list_data, OutputTypes.LIST)
# result: []

Related Pages

• Guardrails_ai_Guardrails_Filter_Action - The complementary action that removes individual offending values instead of rejecting the entire output
• Guardrails_ai_Guardrails_OutputTypes - The output type enumeration that determines the empty replacement value