Guardrails AI

Orchestrates a chain of validators through the Guard class that execute sequentially against LLM outputs, with each validator specifying an OnFailAction (exception, reask, fix, filter, noop, refrain) to determine how validation failures are handled. The pipeline supports both synchronous and asynchronous execution modes, with streaming variants that validate incremental output chunks. Validators are registered via @register_validator decorator and composed into Guards that manage the full validation lifecycle including re-prompting on failure.

Provides a centralized marketplace (Guardrails Hub) of pre-built validators that can be discovered, installed, and versioned via CLI commands (guardrails hub install, guardrails hub list). Validators are referenced using hub:// URIs (e.g., hub://guardrails/regex_match) and automatically resolved from the registry. The system maintains a local validator cache and supports custom validator creation via @register_validator decorator with automatic publishing back to the Hub. Validators are imported dynamically at runtime using a validator registry and import system.

Validates LLM outputs incrementally as tokens arrive from streaming APIs, rather than waiting for the complete response. The system buffers tokens and applies validators at configurable intervals (e.g., per sentence, per paragraph, or per N tokens). Streaming validation works with both synchronous (Guard.__call__(stream=True)) and asynchronous (AsyncGuard.__call__(stream=True)) execution modes. Validators that support streaming can provide partial results (e.g., PII detection on incomplete text), while others may wait for complete chunks. Streaming enables early failure detection and faster feedback loops.

Provides built-in telemetry and tracing capabilities that record execution details for every Guard call, including LLM provider calls, validator executions, re-asks, and timing information. The system tracks metrics like token usage, latency, validation pass/fail rates, and re-ask counts. Telemetry can be exported to external observability platforms (e.g., OpenTelemetry, Datadog) or stored locally. History tracking records the full execution trace including inputs, outputs, validators executed, and failure reasons. The telemetry system enables debugging, performance monitoring, and cost analysis.

Provides a standalone server mode that exposes Guards as REST API endpoints, enabling validation as a service without embedding Guardrails in application code. The server is deployed via CLI (guardrails server start) and accepts HTTP requests with LLM prompts and validation configurations. Each Guard is exposed as an endpoint that accepts POST requests with prompt and optional schema/validators. The server handles authentication, request routing, and response formatting. This enables decoupled validation services that can be shared across multiple applications or teams.

Manages execution context and state that persists across validation cycles, including re-asks and streaming chunks. The context store (guardrails/stores/context.py) maintains variables, metadata, and execution state that validators can read and write. Context is propagated through the validation pipeline and re-ask cycles, enabling validators to access previous attempts, user metadata, and application-specific state. The system supports both in-memory and persistent context stores, enabling stateful validation workflows.

Converts unstructured LLM outputs into validated, typed data structures by defining schemas in three formats: RAIL (Guardrails' XML-based specification language), Pydantic models, or JSON Schema. The Guard class accepts a schema and uses it to constrain LLM generation (via function calling or prompt engineering) and validate outputs. The schema system includes a type registry that maps Python types to JSON Schema representations, enabling automatic serialization/deserialization and type coercion. When validation fails, the system can use the schema to guide re-prompting with structured feedback.

Implements a re-asking loop where validation failures trigger automatic LLM re-prompting with structured feedback about what failed and why. The system tracks iteration history (number of re-asks, failure reasons, previous attempts) and maintains context across re-ask cycles through a context store. The Guard class manages the iteration lifecycle, including configurable max re-ask limits and exponential backoff strategies. History tracking enables debugging and telemetry, recording each validation attempt and the actions taken.

Abstracts LLM provider differences (OpenAI, Anthropic, LiteLLM, HuggingFace) behind a unified Guard interface that works with any compatible provider. The system handles provider-specific details like function calling schemas, streaming protocols, and authentication. LLM provider selection is configured via Guard initialization parameters (model name, API key, provider type). The framework supports both synchronous and asynchronous LLM calls, with streaming variants that validate outputs incrementally as tokens arrive.

Provides built-in validators for detecting and redacting personally identifiable information (PII) such as email addresses, phone numbers, social security numbers, and credit card numbers. The validators use pattern matching and NLP-based detection to identify PII in text, with configurable sensitivity levels and redaction strategies (mask, remove, replace with placeholder). PII detection is available as a pre-built Hub validator (hub://guardrails/pii_detection) and can be composed into validation pipelines with custom failure handling (e.g., filter to remove PII, reask to regenerate without PII).

Provides validators for detecting toxic language, bias, and harmful content in LLM outputs using semantic analysis and pre-trained models. Validators analyze text for offensive language, discriminatory content, and bias against protected groups. Available as Hub validators (e.g., hub://guardrails/toxicity) that can be configured with sensitivity thresholds. Detection uses transformer-based models (e.g., Detoxify, Perspective API) to understand context and semantic meaning rather than simple keyword matching. Failures can trigger reask (regenerate without toxicity) or filter (remove toxic segments).

Provides validators for detecting hallucinations (false or unsupported claims) in LLM outputs by comparing against external knowledge sources or fact-checking APIs. Validators can check if claims are supported by provided context, verify facts against knowledge bases, or use external fact-checking services. The system supports custom validators that integrate with knowledge retrieval systems (RAG) to validate that LLM outputs are grounded in retrieved documents. Hallucination detection can trigger reask with additional context or filter to remove unsupported claims.

Enables developers to define custom validators using the @register_validator decorator, which registers validation logic in the global validator registry. Custom validators implement a validate() method that receives the value to validate and returns a ValidationResult with pass/fail status and optional error messages. Validators support lifecycle hooks (init, pre_validation, post_validation) for setup and cleanup. The registration system enables validators to be referenced by name in RAIL specs or code, and supports both synchronous and asynchronous validation logic. Custom validators can be published to the Guardrails Hub for sharing.

Defines a domain-specific XML language (RAIL) for declaratively specifying validation schemas, validators, and failure handling strategies. RAIL specs define the expected output structure (elements, attributes, types), attach validators to specific fields, and configure OnFailAction for each validator. The Guard class can be instantiated from a RAIL spec file, which is parsed and compiled into a validation pipeline. RAIL supports embedding Pydantic models and JSON Schema definitions, enabling hybrid schema definitions. The system includes a RAIL parser and compiler that converts specs into executable validation logic.