Validators - Guardrails AI

Validators are how we apply quality controls to the outputs of LLMs. They specify the criteria to measure whether an output is valid, as well as what actions to take when an output does not meet those criteria.

How do Validators work?

Each validator is a method that encodes some criteria, and checks if a given value meets that criteria.

If the value passes the criteria defined, the validator returns PassResult. In most cases this means returning that value unchanged. In very few advanced cases, there may be a a value override (the specific validator will document this).
If the value does not pass the criteria, a FailResult is returned. In this case, the validator applies the user-configured on_fail policies (see On-Fail Policies).

Runtime Metadata

Occasionally, validators need additional metadata that is only available during runtime. Metadata could be data generated during the execution of a validator (important if you’re writing your own validators), or could just be a container for runtime arguments. As an example, the ExtractedSummarySentencesMatch validator accepts a filepaths property in the metadata dictionary to specify what source files to compare the summary against to ensure similarity. Unlike arguments which are specified at validator initialization, metadata is specified when calling guard.validate or guard.__call__ (this is the guard() function).

guard = Guard.for_rail("my_railspec.rail")

outcome = guard(
    llm_api=openai.chat.completions.create,
    model="gpt-3.5-turbo",
    num_reasks=3,
    metadata={
        "filepaths": [
            "./my_data/article1.txt",
            "./my_data/article2.txt",
        ]
    }
)

If multiple validators require metadata, create a single metadata dictionary that contains the metadata keys for each validator. In the example below, both the Provenance_LLM and DetectPII validators require metadata.

from guardrails import Guard
from guardrails_ai.detect_pii import DetectPII
from guardrails_ai.provenance_llm import ProvenanceLLM

from sentence_transformers import SentenceTransformer


# Setup Guard with multiple validators
guard = Guard().use(
    ProvenanceLLM(validation_method="sentence"),
    DetectPII()
)

# Setup metadata for provenance validator
sources = [
    "The sun is a star.",
    "The sun rises in the east and sets in the west."
]
model = SentenceTransformer('paraphrase-MiniLM-L6-v2')

def embed_function(sources: list[str]) -> np.array:
    return model.encode(sources)

# Setup metadata for PII validator
pii_entities = ["EMAIL_ADDRESS", "PHONE_NUMBER"]

# Create a single metadata dictionary containing metadata keys for each validator
metadata = {
    'pii_entities': pii_entities,
    'sources': sources,
    'embed_function': embed_function
}

# Pass the metadata to the guard.validate method
guard.validate("some text", metadata=metadata)

Custom Validators

Custom validators let you extend the ability of Guardrails with your own validation logic. Documentation for them can be found here.

Installing Validators

Validators can be combined together into Input and Output Guards that intercept the inputs and outputs of LLMs. Guardrails-AI validators are published to public PyPI as guardrails-ai-<name> and can be installed with pip.

Using CLI

You can install a validator with pip. For example, the Toxic Language validator can be installed with:

pip install guardrails-ai-toxic-language

After installing the validator you can start to use the validator in your guards:

from guardrails_ai.toxic_language import ToxicLanguage
from guardrails import Guard

guard = Guard().use(
    ToxicLanguage, threshold=0.5, validation_method="sentence", on_fail="exception"
)

guard.validate("My landlord is an asshole!") 

In Code Installs

The in-code guardrails.install(...) SDK is deprecated. Install a validator from PyPI with pip (or uv), then import it:

pip install guardrails-ai-toxic-language

from guardrails import Guard
from guardrails_ai.toxic_language import ToxicLanguage

guard = Guard().use(
    ToxicLanguage, threshold=0.5, validation_method="sentence", on_fail="exception"
)

guard.validate("My landlord is an asshole!")

​How do Validators work?

​Runtime Metadata

​Custom Validators

​Installing Validators

​Using CLI

​In Code Installs

How do Validators work?

Runtime Metadata

Custom Validators

Installing Validators

Using CLI

In Code Installs