repository·main·Indexed 27 days ago
https://github.com/guardrails-ai/guardrailsA Python framework for building reliable AI applications by providing input/output validation and structured data generation from LLMs. It enables the creation of Guards using validators from the Guardrails Hub, Pydantic models, or RAIL files to detect and mitigate risks. The framework supports ReAsk actions for LLM corrections, a standalone Flask-based REST API server, and specialized formatters like JsonFormatter for Hugging Face models.
RAIL is an XML-based dialect used to define the structure, types, quality criteria, and corrective actions for LLM outputs.
A .RAIL specification consists of two main components:
<output>: Defines the expected structure (e.g., JSON), field types, validation formats, and on-fail-* corrective actions.<messages>: Contains the prompt template and high-level instructions sent to the LLM.Key features include being language-agnostic, supporting complex nested structures, and providing built-in validation and correction mechanisms.
Guardrails provides native support and integrations for multiple LLM providers:
For unsupported models, you can build Custom LLM Wrappers.
To use a .RAIL file to validate and correct LLM outputs, create a Guard object using gd.Guard.for_rail(). You can then wrap your LLM API call (e.g., openai.Completion.create) with this guard object. The guard will return a validated and corrected JSON object instead of raw text.
import guardrails as gd
# Create a Guard object from a RAIL spec file
guard = gd.Guard.for_rail('path/to/rail/spec.xml')
# Wrap the LLM API call
_, validated_output, *rest = guard(
openai.Completion.create,
**prompt_args,
*args,
**kwargs
)Guardrails helps ensure LLMs return valid structured data through several mechanisms:
JSONFormer to enforce structure during generation.Within the <messages> element of a RAIL spec, you can use several components to build dynamic prompts:
| Component | Syntax | Description |
|---|---|---|
| Variables | ${variable_name} | User-provided values substituted at runtime. |
| Output Schema | ${output_schema} | The compiled schema based on the <output> element. |
| Prompt Primitives | ${gr.prompt_primitive_name} | Pre-constructed prompts for common tasks (e.g., ${gr.xml_prefix_prompt}, ${gr.json_suffix_prompt}). |
Example usage in a <message>:
<message role="user">
Given the following document: ${document}
${gr.xml_prefix_prompt}
${output_schema}
${gr.json_suffix_prompt}
</message>The <output> element in a RAIL specification defines the expected structure, data types, quality criteria, and corrective actions for LLM outputs. You can specify complex structures like JSON objects, lists, or simple strings.
string, integer) inside <output>.<object> element. Children of an <object> represent keys in the resulting JSON. If no children are provided, the LLM generates keys based on the name and description attributes.<list> element. A list can contain exactly one child element type (e.g., a list of strings). If no child is provided, the LLM generates values based on the name and description attributes.<output type="string" ... /> to specify a direct string output instead of a JSON object.<!-- Example of a complex JSON RAIL Spec -->
<rail version="0.1">
<output>
<string name="text" description="The generated text" format="two-words" on-fail-two-words="reask"/>
<float name="score" description="The score of the generated text" format="min-val: 0" on-fail-min-val="fix"/>
<object name="metadata" description="The metadata associated with the generated text">
<string name="key_1" description="description of key_1" />
</object>
</output>
</rail>Validators are now imported from the PEP 420 guardrails_ai namespace instead of guardrails.hub.
Migration Pattern:
from guardrails.hub import <Export>from guardrails_ai.<name> import <Export>Example for the DetectPII validator:
from guardrails.hub import DetectPIIfrom guardrails_ai.detect_pii import DetectPIIGuardrails can automatically attempt to correct LLM outputs through 'reasking'.
Reask Types:
You can configure the Num Reasks limit to prevent infinite loops during correction attempts.
You can deploy Guardrails as a standalone Flask server to execute guards via API. Key features include:
use_server setting to route guard execution to the server.The <output> element specifies the schema for the LLM's response. You can define types like string, float, integer, list, and object.
For each field, you can specify:
format: The validation criteria (e.g., format="two-words" or format="min-val: 0").on-fail-*: The corrective action to take if the format is not met (e.g., reask, fix, or noop).Example of a JSON output specification:
<rail version="0.1">
<output>
<string name="text" description="The generated text" format="two-words" on-fail-two-words="reask"/>
<float name="score" description="The score" format="min-val: 0" on-fail-min-val="fix"/>
<object name="metadata">
<string name="key_1" description="description" />
</object>
</output>
</rail>You can create a Guard by combining one or more validators from the Guardrails Hub.
pip install guardrails-ai-regex-match).Guard().use().OnFailAction to define behavior when validation fails (e.g., OnFailAction.EXCEPTION).Example using a single validator:
from guardrails import Guard, OnFailAction
from guardrails_ai.regex_match import RegexMatch
guard = Guard().use(
RegexMatch, regex="\(?\d{3}\)?-? *\d{3}-? *-?\d{4}", on_fail=OnFailAction.EXCEPTION
)
guard.validate("123-456-7890") # Guardrail passesfrom guardrails import Guard, OnFailAction
from guardrails_ai.regex_match import RegexMatch
guard = Guard().use(
RegexMatch, regex="\(?\d{3}\)?-? *\d{3}-? *-?\d{4}", on_fail=OnFailAction.EXCEPTION
)
guard.validate("123-456-7890") # Guardrail passes
try:
guard.validate("1234-789-0000") # Guardrail fails
except Exception as e:
print(e)