Metadata-Version: 2.5
Name: openai-guardrails
Version: 0.3.6
Summary: OpenAI Guardrails: A framework for building safe and reliable AI systems.
Project-URL: Homepage, https://openai.github.io/openai-guardrails-python/
Project-URL: Repository, https://github.com/openai/openai-guardrails-python
Author-email: OpenAI <support@openai.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: openai-agents>=0.3.3
Requires-Dist: openai>=1.75.0
Requires-Dist: presidio-analyzer>=2.2.360
Requires-Dist: pydantic>=2.11.3
Requires-Dist: spacy==3.8.16; python_version == '3.14'
Requires-Dist: thinc<8.4.0,>=8.3.12
Provides-Extra: benchmark
Requires-Dist: matplotlib>=3.7.0; extra == 'benchmark'
Requires-Dist: numpy>=1.24.0; extra == 'benchmark'
Requires-Dist: pandas>=2.0.0; extra == 'benchmark'
Requires-Dist: scikit-learn>=1.3.0; extra == 'benchmark'
Requires-Dist: seaborn>=0.12.0; extra == 'benchmark'
Provides-Extra: examples
Requires-Dist: pillow>=11.2.1; extra == 'examples'
Requires-Dist: rich>=14.0.0; extra == 'examples'
Description-Content-Type: text/markdown

# OpenAI Guardrails: Python (Preview)

Add configurable safety and compliance checks to LLM applications. OpenAI Guardrails wraps the OpenAI Python client to validate inputs and outputs, and integrates with the OpenAI Agents SDK.

[Configure guardrails](https://guardrails.openai.com/) · [Documentation](https://openai.github.io/openai-guardrails-python/) · [Examples](./examples)

[![OpenAI Guardrails configuration screenshot](https://raw.githubusercontent.com/openai/openai-guardrails-python/main/docs/assets/images/guardrails-python-config-screenshot-100pct-q70.webp)](https://guardrails.openai.com/)

## Installation

Requires **Python 3.11+**. Install [openai-guardrails](https://pypi.org/project/openai-guardrails/):

```bash
pip install openai-guardrails
```

If your configuration uses **Contains PII**, also install its spaCy model during build or deployment:

```bash
python -m spacy download en_core_web_sm
```

For uv with spaCy 3.8, install the model wheel directly:

```bash
uv pip install https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl
```

Contains PII validates and loads this model during client initialization; a missing or unloadable model fails configuration before any request. See the [Contains PII guide](https://openai.github.io/openai-guardrails-python/ref/checks/pii/) for configuration options.

## Quickstart

1. Create and export a pipeline configuration with the [Guardrails wizard](https://guardrails.openai.com/). Save it as `guardrails_config.json` in your working directory.
2. Set the `OPENAI_API_KEY` environment variable to your OpenAI API key.
3. Use `GuardrailsOpenAI` in place of `OpenAI`:

```python
from pathlib import Path

from guardrails import GuardrailsOpenAI, GuardrailTripwireTriggered

client = GuardrailsOpenAI(config=Path("guardrails_config.json"))

try:
    # Chat Completions API
    chat = client.chat.completions.create(
        model="gpt-5",
        messages=[{"role": "user", "content": "Hello world"}],
    )
    print(chat.choices[0].message.content)

    # Responses API
    response = client.responses.create(
        model="gpt-5",
        input="What are the main features of your premium plan?",
    )
    print(response.output_text)
except GuardrailTripwireTriggered:
    print("Message blocked by guardrails.")
```

For async and Azure clients, see the [quickstart guide](https://openai.github.io/openai-guardrails-python/quickstart/). Read about [tripwire handling](https://openai.github.io/openai-guardrails-python/tripwires/) and [streaming behavior](https://openai.github.io/openai-guardrails-python/streaming_output/) before integrating those flows.

### Agents SDK

Use `GuardrailAgent` with the [OpenAI Agents SDK](https://openai.github.io/openai-agents-python/). This example uses the same config file and API key as the quickstart:

```python
import asyncio
from pathlib import Path

from agents import InputGuardrailTripwireTriggered, OutputGuardrailTripwireTriggered, Runner
from agents.run import RunConfig

from guardrails import GuardrailAgent

agent = GuardrailAgent(
    config=Path("guardrails_config.json"),
    name="Customer support agent",
    instructions="You help customers with their questions.",
)


async def main():
    try:
        result = await Runner.run(
            agent, "Hello, can you help me?", run_config=RunConfig(tracing_disabled=True)
        )
        print(result.final_output)
    except (InputGuardrailTripwireTriggered, OutputGuardrailTripwireTriggered):
        print("Message blocked by guardrails.")


if __name__ == "__main__":
    asyncio.run(main())
```

See the [Agents SDK integration guide](https://openai.github.io/openai-guardrails-python/agents_sdk_integration/) for configuration and tool guardrails.

## Evaluations

Measure guardrail performance on labeled datasets using the same exported configuration. Install the evaluation dependencies first (currently required for basic evaluation as well as benchmarking):

```bash
pip install "openai-guardrails[benchmark]"
python -m guardrails.evals.guardrail_evals \
  --config-path guardrails_config.json \
  --dataset-path data.jsonl
```

Save one JSON object per line in `data.jsonl`, with labels for the guardrails in your configuration. For a configuration containing Moderation and NSFW Text:

```json
{"id": "sample_1", "data": "Hello world", "expected_triggers": {"Moderation": false, "NSFW Text": false}}
```

For the programmatic API, model comparisons, benchmark dependencies, and dataset options, see the [evaluation guide](https://openai.github.io/openai-guardrails-python/evals/).

## Examples and Local Development

Clone the repository and install it with the example dependencies:

```bash
git clone https://github.com/openai/openai-guardrails-python.git
cd openai-guardrails-python
pip install -e ".[examples]"
```

Set `OPENAI_API_KEY` as above. Install the spaCy model from the installation section for examples that use Contains PII, including `agents_sdk.py`.

```bash
python examples/basic/hello_world.py
python examples/basic/agents_sdk.py
```

Explore the examples:

- [Basic chatbot](./examples/basic/hello_world.py) — async client with guardrails
- [Agents SDK](./examples/basic/agents_sdk.py) — agent with input and output checks
- [Local models](./examples/basic/local_model.py) — OpenAI-compatible model endpoints
- [Structured outputs](./examples/basic/structured_outputs_example.py)
- [PII masking](./examples/basic/pii_mask_example.py)
- [Tripwire suppression](./examples/basic/suppress_tripwire.py)

## Available Guardrails

| Guardrail | Checks for |
| --- | --- |
| [Keyword Filter](https://openai.github.io/openai-guardrails-python/ref/checks/keywords/) | Configured keywords and phrases |
| [Competitors](https://openai.github.io/openai-guardrails-python/ref/checks/competitors/) | Mentions of configured competitors |
| [Moderation](https://openai.github.io/openai-guardrails-python/ref/checks/moderation/) | Content flagged by OpenAI's moderation API |
| [URL Filter](https://openai.github.io/openai-guardrails-python/ref/checks/urls/) | URLs against domain allowlists or blocklists |
| [Secret Keys](https://openai.github.io/openai-guardrails-python/ref/checks/secret_keys/) | Potential API keys, secrets, and credentials |
| [Contains PII](https://openai.github.io/openai-guardrails-python/ref/checks/pii/) | Personally identifiable information |
| [Hallucination Detection](https://openai.github.io/openai-guardrails-python/ref/checks/hallucination_detection/) | Claims against reference material in vector stores |
| [Jailbreak](https://openai.github.io/openai-guardrails-python/ref/checks/jailbreak/) | Jailbreak attempts |
| [Prompt Injection Detection](https://openai.github.io/openai-guardrails-python/ref/checks/prompt_injection_detection/) | Misaligned tool calls and tool outputs |
| [NSFW Text](https://openai.github.io/openai-guardrails-python/ref/checks/nsfw/) | Workplace-inappropriate content |
| [Off Topic Prompts](https://openai.github.io/openai-guardrails-python/ref/checks/off_topic_prompts/) | Content outside a configured topic or scope |
| [Custom Prompt Check](https://openai.github.io/openai-guardrails-python/ref/checks/custom_prompt_check/) | Violations of custom instructions |

## Contributing

Please share bug reports and feature requests through [GitHub issues](https://github.com/openai/openai-guardrails-python/issues).
Pull requests are limited to repository collaborators; we do not accept pull requests from non-collaborators.
See [CONTRIBUTING.md](https://github.com/openai/openai-guardrails-python/blob/main/CONTRIBUTING.md) for the contribution policy and development guide.
For security vulnerabilities, follow [SECURITY.md](https://github.com/openai/openai-guardrails-python/blob/main/SECURITY.md).

## License

[MIT](./LICENSE).

## Disclaimers

Guardrails may use Third-Party Services such as the [Presidio open-source framework](https://github.com/microsoft/presidio), which are subject to their own terms and conditions and are not developed or verified by OpenAI.

Developers are responsible for implementing appropriate safeguards to prevent storage or misuse of sensitive or prohibited content (including but not limited to personal data, child sexual abuse material, or other illegal content). OpenAI disclaims liability for any logging or retention of such content by developers. Developers must ensure their systems comply with all applicable data protection and content safety laws, and should avoid persisting any blocked content generated or intercepted by Guardrails. Guardrails calls paid OpenAI APIs, and developers are responsible for associated charges.
