# openai/openai-guardrails-python architecture

> Architecture diagram of the GitHub repository openai/openai-guardrails-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openai/openai-guardrails-python
- Repository: https://github.com/openai/openai-guardrails-python

## Overview

OpenAI Guardrails is a Python SDK that wraps OpenAI clients and Agents SDK agents to apply configurable safety and compliance checks to inputs and outputs. The main flow loads configured guardrails, runs checks at pipeline stages, and returns results or raises a tripwire; PII checks can also mask input. Separate capabilities include conversation-aware checks and dataset evaluation. Edges reflect the excerpts, SOURCE INDEX references, or README; unsampled wiring is omitted where it cannot be established.

Main entry points: [`src/guardrails/registry.py`](https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/registry.py) (Guardrail registry), [`src/guardrails/client.py`](https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/client.py) (OpenAI clients), [`src/guardrails/runtime.py`](https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/runtime.py) (Pipeline runtime), [`src/guardrails/_base_client.py`](https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/_base_client.py) (Client orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["API integrations"]
  node_client["OpenAI clients<br/>[client.py]"]
  node_agent["Guardrail agent<br/>[agents.py]"]
  node_chat["Chat resource<br/>[chat.py]"]
  node_responses["Responses resource<br/>[responses.py]"]
  node_streaming["Streaming support<br/>[_streaming.py]"]
  node_base_client["Client orchestration<br/>[_base_client.py]"]
end

subgraph group_execution["Guardrail execution"]
  node_runtime["Pipeline runtime<br/>[runtime.py]"]
  node_registry["Guardrail registry<br/>[registry.py]"]
  node_spec["Guardrail specs<br/>[spec.py]"]
  node_tripwires["Tripwire results<br/>[exceptions.py]"]
end

subgraph group_checks["Safety checks"]
  node_llm_checks["LLM-based checks<br/>[llm_base.py]"]
  node_hallucination["Hallucination check"]
  node_keywords["Keyword check<br/>[keywords.py]"]
  node_pii["PII check<br/>[pii.py]"]
  node_injection["Injection checks"]
  node_urls["URL check<br/>[urls.py]"]
  node_other_checks["Other built-in checks"]
end

subgraph group_support["Shared support"]
  node_context["Context validation<br/>[context.py]"]
  node_conversation["Conversation normalization<br/>[conversation.py]"]
  node_safety_id["Safety identifiers"]
end

subgraph group_evaluation["Evaluations"]
  node_evaluations["Dataset evaluations<br/>[guardrail_evals.py]"]
end

node_developer(("Application developer"))
node_openai(("OpenAI API"))
node_agents_sdk(("Agents SDK"))

node_developer -->|"configures and calls"| node_client
node_client -->|"uses shared client"| node_base_client
node_client -->|"runs guardrails"| node_runtime
node_client -->|"exposes chat"| node_chat
node_client -->|"exposes responses"| node_responses
node_client -->|"uses streaming"| node_streaming
node_openai -->|"serves API calls"| node_client
node_developer -->|"configures agent"| node_agent
node_agent -->|"runs guardrails"| node_runtime
node_agents_sdk -->|"runs agent"| node_agent
node_runtime -->|"looks up specs"| node_registry
node_registry -->|"stores specifications"| node_spec
node_registry -->|"registers check"| node_keywords
node_registry -->|"registers check"| node_pii
node_registry -->|"registers check"| node_hallucination
node_registry -->|"registers check"| node_urls
node_registry -->|"registers check"| node_injection
node_registry -->|"registers checks"| node_other_checks
node_hallucination -->|"uses LLM base"| node_llm_checks
node_injection -->|"uses LLM base"| node_llm_checks
node_runtime -->|"validates context"| node_context
node_base_client -->|"masks detected PII"| node_pii
node_base_client -->|"normalizes history"| node_conversation
node_chat -->|"uses identifier"| node_safety_id
node_responses -->|"uses identifier"| node_safety_id
node_runtime -->|"raises failures"| node_tripwires
node_developer -->|"evaluates dataset"| node_evaluations
node_evaluations -.->|"uses configured pipeline"| node_client

click node_client "https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/client.py"
click node_agent "https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/agents.py"
click node_chat "https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/resources/chat/chat.py"
click node_responses "https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/resources/responses/responses.py"
click node_streaming "https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/_streaming.py"
click node_base_client "https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/_base_client.py"
click node_runtime "https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/runtime.py"
click node_registry "https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/registry.py"
click node_spec "https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/spec.py"
click node_tripwires "https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/exceptions.py"
click node_llm_checks "https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/checks/text/llm_base.py"
click node_hallucination "https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/checks/text/hallucination_detection.py"
click node_keywords "https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/checks/text/keywords.py"
click node_pii "https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/checks/text/pii.py"
click node_injection "https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/checks/text/prompt_injection_detection.py"
click node_urls "https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/checks/text/urls.py"
click node_other_checks "https://github.com/openai/openai-guardrails-python/tree/main/src/guardrails/checks/text"
click node_context "https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/utils/context.py"
click node_conversation "https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/utils/conversation.py"
click node_safety_id "https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/utils/safety_identifier.py"
click node_evaluations "https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/evals/guardrail_evals.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client,node_agent,node_chat,node_responses,node_streaming,node_base_client toneBlue
class node_runtime,node_registry,node_spec,node_tripwires toneAmber
class node_llm_checks,node_hallucination,node_keywords,node_pii,node_injection,node_urls,node_other_checks,node_openai toneMint
class node_context,node_conversation,node_safety_id toneRose
class node_evaluations,node_developer,node_agents_sdk toneIndigo
```

## Components

### API integrations

- [OpenAI clients](https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/client.py): `src/guardrails/client.py`
- [Guardrail agent](https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/agents.py): `src/guardrails/agents.py`
- [Chat resource](https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/resources/chat/chat.py): `src/guardrails/resources/chat/chat.py`
- [Responses resource](https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/resources/responses/responses.py): `src/guardrails/resources/responses/responses.py`
- [Streaming support](https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/_streaming.py): `src/guardrails/_streaming.py`
- [Client orchestration](https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/_base_client.py): `src/guardrails/_base_client.py`

### Guardrail execution

- [Pipeline runtime](https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/runtime.py): `src/guardrails/runtime.py`
- [Guardrail registry](https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/registry.py): `src/guardrails/registry.py`
- [Guardrail specs](https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/spec.py): `src/guardrails/spec.py`
- [Tripwire results](https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/exceptions.py): `src/guardrails/exceptions.py`

### Safety checks

- [LLM-based checks](https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/checks/text/llm_base.py): `src/guardrails/checks/text/llm_base.py`
- [Hallucination check](https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/checks/text/hallucination_detection.py): `src/guardrails/checks/text/hallucination_detection.py`
- [Keyword check](https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/checks/text/keywords.py): `src/guardrails/checks/text/keywords.py`
- [PII check](https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/checks/text/pii.py): `src/guardrails/checks/text/pii.py`
- [Injection checks](https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/checks/text/prompt_injection_detection.py): `src/guardrails/checks/text/prompt_injection_detection.py`
- [URL check](https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/checks/text/urls.py): `src/guardrails/checks/text/urls.py`
- [Other built-in checks](https://github.com/openai/openai-guardrails-python/tree/main/src/guardrails/checks/text): `src/guardrails/checks/text`

### Shared support

- [Context validation](https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/utils/context.py): `src/guardrails/utils/context.py`
- [Conversation normalization](https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/utils/conversation.py): `src/guardrails/utils/conversation.py`
- [Safety identifiers](https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/utils/safety_identifier.py): `src/guardrails/utils/safety_identifier.py`

### Evaluations

- [Dataset evaluations](https://github.com/openai/openai-guardrails-python/blob/main/src/guardrails/evals/guardrail_evals.py): `src/guardrails/evals/guardrail_evals.py`

### Other components

- **Application developer**
- **OpenAI API**
- **Agents SDK**

## Connections

- Application developer → OpenAI clients: configures and calls
- OpenAI clients → Client orchestration: uses shared client (evidence: `src/guardrails/client.py`)
- OpenAI clients → Pipeline runtime: runs guardrails (evidence: `src/guardrails/client.py`)
- OpenAI clients → Chat resource: exposes chat (evidence: `src/guardrails/client.py`)
- OpenAI clients → Responses resource: exposes responses (evidence: `src/guardrails/client.py`)
- OpenAI clients → Streaming support: uses streaming (evidence: `src/guardrails/client.py`)
- OpenAI API → OpenAI clients: serves API calls
- Application developer → Guardrail agent: configures agent
- Guardrail agent → Pipeline runtime: runs guardrails (evidence: `src/guardrails/agents.py`)
- Agents SDK → Guardrail agent: runs agent
- Pipeline runtime → Guardrail registry: looks up specs (evidence: `src/guardrails/runtime.py`)
- Guardrail registry → Guardrail specs: stores specifications (evidence: `src/guardrails/registry.py`)
- Guardrail registry → Keyword check: registers check (evidence: `src/guardrails/checks/text/keywords.py`)
- Guardrail registry → PII check: registers check (evidence: `src/guardrails/checks/text/pii.py`)
- Guardrail registry → Hallucination check: registers check (evidence: `src/guardrails/checks/text/hallucination_detection.py`)
- Guardrail registry → URL check: registers check (evidence: `src/guardrails/checks/text/urls.py`)
- Guardrail registry → Injection checks: registers check (evidence: `src/guardrails/checks/text/prompt_injection_detection.py`)
- Guardrail registry → Other built-in checks: registers checks (evidence: `src/guardrails/checks/text/llm_base.py`)
- Hallucination check → LLM-based checks: uses LLM base (evidence: `src/guardrails/checks/text/hallucination_detection.py`)
- Injection checks → LLM-based checks: uses LLM base (evidence: `src/guardrails/checks/text/prompt_injection_detection.py`)
- Pipeline runtime → Context validation: validates context (evidence: `src/guardrails/utils/context.py`)
- Client orchestration → PII check: masks detected PII (evidence: `src/guardrails/_base_client.py`)
- Client orchestration → Conversation normalization: normalizes history (evidence: `src/guardrails/_base_client.py`)
- Chat resource → Safety identifiers: uses identifier (evidence: `src/guardrails/resources/chat/chat.py`)
- Responses resource → Safety identifiers: uses identifier (evidence: `src/guardrails/resources/responses/responses.py`)
- Pipeline runtime → Tripwire results: raises failures (evidence: `src/guardrails/runtime.py`)
- Application developer → Dataset evaluations: evaluates dataset
- Dataset evaluations → OpenAI clients: uses configured pipeline
