Install Guardrails AI in Python

Guardrails AI helps you build safe and reliable AI applications. It validates outputs from large language models. This guide shows you how to install Guardrails AI in Python.

We cover setup, dependencies, and a simple example. Follow these steps to get started quickly. The process is straightforward for beginners.

What is Guardrails AI?

Guardrails AI is a Python framework. It ensures your AI outputs meet specific rules. You define validators for things like format, tone, or content safety.

It works with any language model. You can use it with OpenAI, Anthropic, or local models. This makes your apps more predictable and secure.

Prerequisites

Before you start, check your system. You need Python 3.8 or later installed. Use a virtual environment to avoid conflicts.

Install pip if it is missing. Most Python installations include it. Verify with python --version and pip --version.

A stable internet connection is required. Guardrails AI downloads dependencies from PyPI.

Step 1: Create a Virtual Environment

A virtual environment keeps your project clean. It isolates packages from other projects. Run these commands in your terminal.

# Create virtual environment
python -m venv guardrails-env

# Activate it
# On Windows:
guardrails-env\Scripts\activate

# On macOS/Linux:
source guardrails-env/bin/activate

You should see the environment name in your prompt. This means activation worked. Now you can install packages safely.

Step 2: Install Guardrails AI

Use pip to install the core library. The package name is guardrails-ai. Run this command.

pip install guardrails-ai

This installs the main framework. It also pulls in required dependencies like pydantic and openai (if needed). Wait for the process to finish.

Optional: Install specific validators later. Use pip install guardrails-ai[hub] for access to the Guardrails Hub. This adds pre-built validators.

Step 3: Verify the Installation

Check if Guardrails installed correctly. Open a Python shell or run a script. Use import guardrails as gr.

# test_install.py
import guardrails as gr

# Print version
print(gr.__version__)

Run the script with python test_install.py. You should see a version number like "0.5.0". This confirms a successful install.

# Expected output
0.5.0

If you get an error, check your environment. Make sure you activated the virtual environment. Also verify Python version compatibility.

Step 4: Install a Language Model Provider

Guardrails AI needs a language model to work. Install an API client like OpenAI. Use pip install openai.

You can also use local models with transformers. Install that with pip install transformers. Choose based on your needs.

# Install OpenAI client
pip install openai

# Or for local models
pip install transformers torch

Set your API key as an environment variable. For OpenAI, use export OPENAI_API_KEY="your-key" on macOS/Linux. On Windows, use set.

Step 5: Create a Simple Guard

A Guard is a wrapper around your model. It applies validators to outputs. Let's make one that checks for valid JSON.

# simple_guard.py
import guardrails as gr

# Define a validator for JSON format
guard = gr.Guard.from_string(
    validators=["valid-json"],
    description="Ensure output is valid JSON."
)

# Use the guard with a model
import openai

response = guard(
    llm_api=openai.chat.completions.create,
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": "List three fruits in JSON format."}],
    max_tokens=100
)

# Print validated output
print(response.validated_output)

Run the script. The guard will check the model's response. If it is valid JSON, you see the output. If not, it raises an error.

# Expected output (example)
{"fruits": ["apple", "banana", "cherry"]}

This is a basic example. You can add more validators for complex rules. The framework handles retries and corrections automatically.

Step 6: Use Guardrails Hub Validators

The Guardrails Hub offers pre-built validators. Install the hub with pip install guardrails-ai[hub]. Then import specific validators.

# Use a hub validator
from guardrails.hub import ToxicLanguage

guard = gr.Guard.from_string(
    validators=[ToxicLanguage(on_fail="fix")],
    description="Block toxic language."
)

response = guard(
    llm_api=openai.chat.completions.create,
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": "Tell me a joke."}],
    max_tokens=50
)

print(response.validated_output)

This validator filters toxic content. You can find more validators on the Guardrails Hub website. They cover topics like format, safety, and relevance.

Troubleshooting Common Issues

Installation might fail due to network issues. Use a mirror or VPN. Also ensure pip is up to date with pip install --upgrade pip.

If imports fail, check your virtual environment. Deactivate and reactivate it. Reinstall with pip install --force-reinstall guardrails-ai.

Version conflicts happen with older libraries. Use a fresh environment. Pin versions in requirements.txt for stability.

Best Practices

Always use a virtual environment. This prevents package conflicts. Keep your Guardrails AI version updated for new features.

Test validators in isolation. Use Guard.validate without a model call. This helps debug validator logic separately.

Document your validators clearly. Use comments in code and a README file. This helps other developers understand your safety rules.

Conclusion

Installing Guardrails AI in Python is simple. You set up a virtual environment, install the package, and verify it works. Then you create Guards to validate AI outputs.

This framework makes your apps safer and more reliable. Start with basic validators and expand as needed. The Guardrails Hub provides many ready-to-use options.

Now you can build AI applications with confidence. Use the code examples here to experiment. Happy coding!