Skip to main content

Adding guardrails to large language models.

Project description

Guardrails AI Logo Guardrails AI Logo

License PyPI - Python Version Downloads CI codecov Checked with pyright X (formerly Twitter) Follow Discord Static Badge Static Badge

What is Guardrails?

Guardrails is a Python framework that helps build reliable AI applications by performing two key functions:

  1. Guardrails runs Input/Output Guards in your application that detect, quantify and mitigate the presence of specific types of risks. To look at the full suite of risks, check out Guardrails Hub.
  2. Guardrails help you generate structured data from LLMs.
Guardrails in your application

Guardrails Hub

Guardrails Hub is a collection of pre-built measures of specific types of risks (called 'validators'). Multiple validators can be combined together into Input and Output Guards that intercept the inputs and outputs of LLMs. Visit Guardrails Hub to see the full list of validators and their documentation.

Guardrails Hub gif

Installation

pip install guardrails-ai

Getting Started

Create Input and Output Guards for LLM Validation

  1. Download and configure the Guardrails Hub CLI.

    pip install guardrails-ai
    guardrails configure
    
  2. Install a guardrail from Guardrails Hub.

    guardrails hub install hub://guardrails/regex_match
    
  3. Create a Guard from the installed guardrail.

    from guardrails import Guard, OnFailAction
    from guardrails.hub 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)
    

    Output:

    Validation failed for field with errors: Result must match \(?\d{3}\)?-? *\d{3}-? *-?\d{4}
    
  4. Run multiple guardrails within a Guard. First, install the necessary guardrails from Guardrails Hub.

    guardrails hub install hub://guardrails/competitor_check
    guardrails hub install hub://guardrails/toxic_language
    

    Then, create a Guard from the installed guardrails.

    from guardrails import Guard, OnFailAction
    from guardrails.hub import CompetitorCheck, ToxicLanguage
    
    guard = Guard().use_many(
        CompetitorCheck(["Apple", "Microsoft", "Google"], on_fail=OnFailAction.EXCEPTION),
        ToxicLanguage(threshold=0.5, validation_method="sentence", on_fail=OnFailAction.EXCEPTION)
    )
    
    guard.validate(
        """An apple a day keeps a doctor away.
        This is good advice for keeping your health."""
    )  # Both the guardrails pass
    
    try:
        guard.validate(
            """Shut the hell up! Apple just released a new iPhone."""
        )  # Both the guardrails fail
    except Exception as e:
        print(e)
    

    Output:

    Validation failed for field with errors: Found the following competitors: [['Apple']]. Please avoid naming those competitors next time, The following sentences in your response were found to be toxic:
    
    - Shut the hell up!
    

Use Guardrails to generate structured data from LLMs

Let's go through an example where we ask an LLM to generate fake pet names. To do this, we'll create a Pydantic BaseModel that represents the structure of the output we want.

from pydantic import BaseModel, Field

class Pet(BaseModel):
    pet_type: str = Field(description="Species of pet")
    name: str = Field(description="a unique pet name")

Now, create a Guard from the Pet class. The Guard can be used to call the LLM in a manner so that the output is formatted to the Pet class. Under the hood, this is done by either of two methods:

  1. Function calling: For LLMs that support function calling, we generate structured data using the function call syntax.
  2. Prompt optimization: For LLMs that don't support function calling, we add the schema of the expected output to the prompt so that the LLM can generate structured data.
from guardrails import Guard
import openai

prompt = """
    What kind of pet should I get and what should I name it?

    ${gr.complete_json_suffix_v2}
"""
guard = Guard.for_pydantic(output_class=Pet, prompt=prompt)

raw_output, validated_output, *rest = guard(
    llm_api=openai.completions.create,
    engine="gpt-3.5-turbo-instruct"
)

print(validated_output)

This prints:

{
    "pet_type": "dog",
    "name": "Buddy
}

Guardrails Server

Guardrails can be set up as a standalone service served by Flask with guardrails start, allowing you to interact with it via a REST API. This approach simplifies development and deployment of Guardrails-powered applications.

  1. Install: pip install "guardrails-ai"
  2. Configure: guardrails configure
  3. Create a config: guardrails create --validators=hub://guardrails/two_words --name=two-word-guard
  4. Start the dev server: guardrails start --config=./config.py
  5. Interact with the dev server via the snippets below
# with the guardrails client
import guardrails as gr

gr.settings.use_server = True
guard = gr.Guard(name='two-word-guard')
guard.validate('this is more than two words')

# or with the openai sdk
import openai
openai.base_url = "http://localhost:8000/guards/two-word-guard/openai/v1/"
os.environ["OPENAI_API_KEY"] = "youropenaikey"

messages = [
        {
            "role": "user",
            "content": "tell me about an apple with 3 words exactly",
        },
    ]

completion = openai.chat.completions.create(
    model="gpt-4o-mini",
    messages=messages,
)

For production deployments, we recommend using Docker with Gunicorn as the WSGI server for improved performance and scalability.

FAQ

I'm running into issues with Guardrails. Where can I get help?

You can reach out to us on Discord or Twitter.

Can I use Guardrails with any LLM?

Yes, Guardrails can be used with proprietary and open-source LLMs. Check out this guide on how to use Guardrails with any LLM.

Can I create my own validators?

Yes, you can create your own validators and contribute them to Guardrails Hub. Check out this guide on how to create your own validators.

Does Guardrails support other languages?

Guardrails can be used with Python and JavaScript. Check out the docs on how to use Guardrails from JavaScript. We are working on adding support for other languages. If you would like to contribute to Guardrails, please reach out to us on Discord or Twitter.

Contributing

We welcome contributions to Guardrails!

Get started by checking out Github issues and check out the Contributing Guide. Feel free to open an issue, or reach out if you would like to add to the project!

Project details


Release history Release notifications | RSS feed

This version

0.6.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

guardrails_ai-0.6.0.tar.gz (168.9 kB view details)

Uploaded Source

Built Distribution

guardrails_ai-0.6.0-py3-none-any.whl (227.8 kB view details)

Uploaded Python 3

File details

Details for the file guardrails_ai-0.6.0.tar.gz.

File metadata

  • Download URL: guardrails_ai-0.6.0.tar.gz
  • Upload date:
  • Size: 168.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.4 CPython/3.11.10 Linux/6.5.0-1025-azure

File hashes

Hashes for guardrails_ai-0.6.0.tar.gz
Algorithm Hash digest
SHA256 6bd634b56ef34c6027ea066ea411f895261f14204e0592bdefb446875ce68eea
MD5 1f22d50b004c5e46c57cb14f5b7b28fd
BLAKE2b-256 c837568e434a76519bd72c060696f0c26eeacffd4ccdfa1a1d85876d74f8f970

See more details on using hashes here.

File details

Details for the file guardrails_ai-0.6.0-py3-none-any.whl.

File metadata

  • Download URL: guardrails_ai-0.6.0-py3-none-any.whl
  • Upload date:
  • Size: 227.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.4 CPython/3.11.10 Linux/6.5.0-1025-azure

File hashes

Hashes for guardrails_ai-0.6.0-py3-none-any.whl
Algorithm Hash digest
SHA256 a11a0aad96ecbb412bce58533fcaaa03ca6d21872f5bad02babffe4959a13e17
MD5 bd8491a48aa45f841ee50b92a38d7b3c
BLAKE2b-256 c03a1d44b42640135c31b0004f0e4ed114bb8a1675ad3f58d0f7c14bd4584c36

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page