Guardrails AI

Common errors

• pydantic.v1.error_wrappers.ValidationError: 1 validation error for MyModel

  cause Your environment is using Pydantic v1, but Guardrails AI now requires Pydantic v2.
  fix Upgrade Pydantic to version 2: `pip install "pydantic>=2"`. You may also need to update your Pydantic models to be compatible with v2 syntax if you used deprecated features.

• guardrails.errors.ValidationError: Output validation failed:

  cause The Large Language Model's output did not conform to the schema or validation rules defined in your RAIL specification.
  fix Review your prompt to better guide the LLM towards the desired output format. Examine the detailed error message to identify which validator failed. Consider using `OnFail.reask` or `OnFail.fix` for validators to automatically attempt correction.

• openai.error.AuthenticationError: Incorrect API key provided: None. You can find your API key at https://platform.openai.com.

  cause The `OPENAI_API_KEY` environment variable is not set or contains an invalid key, preventing Guardrails from authenticating with OpenAI.
  fix Set your `OPENAI_API_KEY` environment variable with a valid OpenAI API key. For example: `export OPENAI_API_KEY='your-key-here'` in your terminal before running the script.

• ModuleNotFoundError: No module named 'guardrails_ai'

  cause You are attempting to import from `guardrails_ai` instead of the correct package name `guardrails`, or the package is not installed.
  fix Ensure the package is installed via `pip install guardrails-ai`. Then, import classes and functions from the `guardrails` package: `from guardrails import Guard`.

Warnings

• breaking Guardrails AI now strictly requires Pydantic v2. Projects using Pydantic v1 will encounter `ValidationError` or `ImportError`.
  Fix: Upgrade Pydantic to version 2 (`pip install "pydantic>=2"`). If your project heavily relies on Pydantic v1, consider creating a separate virtual environment or adapting your Pydantic models to v2 syntax.
• deprecated Directly passing Python dictionaries or Pydantic models as `output_schema` to `Guard` is deprecated. RAILLPEC strings are now the standard for defining schemas.
  Fix: Migrate to defining your output schema using RAILLPEC strings (XML-like syntax) and initialize Guard with `Guard.from_string()` or `Guard.from_file()`.
• gotcha The default `OnFail` action for validators is `OnFail.exception`, meaning any validation failure will raise a `ValidationError` and stop execution.
  Fix: Explicitly define `on_fail` for your validators to control behavior, e.g., `OnFail.reask` (re-prompt LLM), `OnFail.fix` (attempt to fix the output), `OnFail.refrain` (return None), or `OnFail.noop` (return original output). Wrap `guard()` calls in `try...except guardrails.errors.ValidationError` for robust error handling.
• gotcha When using `llm_api='openai'` (or other string providers), ensure the corresponding API key (e.g., `OPENAI_API_KEY`) is set as an environment variable or passed directly to `guard()`.
  Fix: Set the API key as an environment variable (`export OPENAI_API_KEY='...'`) or pass it directly in the `llm_api` argument if using a custom client (e.g., `guard(llm_api=your_openai_client)`).

Install

• pip install guardrails-ai Install core library

Imports

• Guard
  wrong:

  import guardrails
  guardrails.Guard

  correct:

  from guardrails import Guard

  The main Guard class is imported directly from the top-level 'guardrails' package, not from the imported module itself.
• OnFail
  wrong:

  from guardrails.actions import OnFail

  correct:

  from guardrails import OnFail

  While 'OnFail' is an action, it is exposed directly from the top-level 'guardrails' package for convenience.
• PydanticValidation

  from guardrails.validators import PydanticValidation

• BaseModel

  from pydantic import BaseModel

  Pydantic models are typically used to define output schemas.

Quickstart

This quickstart defines a simple Pydantic model for a joke, creates a RAILLPEC string to instruct the LLM and define the output schema, then uses `Guard.from_string` to initialize Guardrails. It then calls the OpenAI LLM, passing the Pydantic schema for structured output and automatically validating the response.

import os
from guardrails import Guard
from pydantic import BaseModel, Field

# 1. Define your desired output structure using Pydantic
class Joke(BaseModel):
    setup: str = Field(description="The setup of the joke")
    punchline: str = Field(description="The punchline of the joke")

# 2. Define the Guardrails RAIL specification as a string
# Guardrails automatically infers the output type and generates a prompt
# based on the Pydantic model and ${gr.complete_json_object_prompt}.
rail_spec = f'''
<rail version="0.1">
    <output type="object" name="joke" model="Joke" />
    <prompt>
        Tell me a joke.\n
        {{gr.complete_json_object_prompt}}
    </prompt>
</rail>
'''

# 3. Initialize Guard with the RAIL specification
guard = Guard.from_string(rail_spec)

# 4. Call the LLM with Guardrails
# Ensure OPENAI_API_KEY is set in your environment
openai_api_key = os.environ.get("OPENAI_API_KEY")
if not openai_api_key:
    print("Please set the OPENAI_API_KEY environment variable to run this example.")
else:
    try:
        # The llm_api='openai' string automatically uses the OpenAI API client
        # configured via the OPENAI_API_KEY environment variable.
        raw_llm_output, validated_output = guard(
            llm_api="openai",
            prompt_params={"gr.complete_json_object_prompt": Joke.schema_json()}
        )
        print("\n--- Raw LLM Output ---")
        print(raw_llm_output)
        print("\n--- Validated Output (Pydantic Model) ---")
        print(validated_output)
        print(f"Setup: {validated_output.setup}")
        print(f"Punchline: {validated_output.punchline}")
    except Exception as e:
        print(f"An error occurred: {e}. Check your API key and network connection.")