@openai/guardrails

Enables developers to define safety policies, content filters, and validation rules using declarative YAML or JSON configuration files rather than imperative code. The framework parses these schemas at runtime and compiles them into executable guardrail chains that intercept and validate LLM inputs/outputs before they reach users or downstream systems. Supports conditional logic, regex patterns, semantic matching, and custom validator functions within a unified policy language.

Implements a composable pipeline architecture that chains multiple validation stages (pre-processing, semantic analysis, syntactic checks, custom validators) to sanitize and validate both user inputs and LLM outputs. Each stage can apply different validation strategies: regex-based pattern matching, semantic similarity scoring against prohibited content vectors, PII detection, token-level analysis, and custom JavaScript functions. Stages execute sequentially with early exit on failure, and results include detailed violation metadata for logging and user feedback.

Automatically logs all guardrail violations with detailed metadata (timestamp, user ID, violation type, severity, enforcement action, conversation context) to enable compliance auditing and threat analysis. Supports structured logging to external systems (databases, logging services) and generates compliance reports summarizing violation patterns, enforcement actions, and policy effectiveness. Includes PII-safe logging that redacts sensitive information from logs while maintaining audit trail integrity.

Provides TypeScript interfaces and type definitions for guardrail configuration, enabling compile-time validation of policy definitions and IDE autocomplete for configuration options. Supports both YAML/JSON configuration files (with TypeScript schema validation) and programmatic configuration using TypeScript objects. Type safety extends to custom validator functions, ensuring they conform to expected signatures and receive properly typed context objects.

Provides middleware adapters for popular Node.js frameworks (Express, Next.js, Fastify, etc.) that integrate guardrails into request/response pipelines. Middleware intercepts requests before they reach route handlers, applies guardrails to user input, and intercepts responses to validate LLM output before sending to clients. Supports both synchronous and asynchronous middleware patterns and integrates with framework-specific error handling and logging.

Detects prompt injection attempts by analyzing input structure, token patterns, and semantic anomalies that indicate attempts to override system instructions or manipulate model behavior. Uses techniques including delimiter detection (looking for common injection markers like 'ignore previous instructions'), instruction-like pattern recognition, and comparison against baseline input distributions. Can be configured with custom injection patterns and severity thresholds, and provides detailed reports on detected injection vectors.

Implements semantic content moderation by embedding user inputs and LLM outputs, then computing cosine similarity against pre-built vectors representing prohibited topics (violence, hate speech, sexual content, etc.). Uses OpenAI embeddings or custom embedding models to generate vector representations, compares against a configurable library of harmful content vectors, and returns similarity scores with configurable thresholds for blocking. Supports category-specific thresholds and allows whitelisting of legitimate uses of sensitive topics.

Validates LLM outputs against JSON schemas or TypeScript interfaces to ensure responses conform to expected structure, data types, and constraints. Parses LLM text output, attempts to extract JSON, validates against provided schema using JSON Schema validators, and returns structured validation results with detailed error messages indicating which fields failed validation. Supports nested schemas, array validation, enum constraints, and custom validation functions for business logic (e.g., 'price must be positive').

Detects and redacts personally identifiable information (names, email addresses, phone numbers, SSNs, credit card numbers, etc.) from both user inputs and LLM outputs using pattern matching, named entity recognition, and configurable regex rules. Supports multiple redaction strategies: masking (replacing with asterisks), tokenization (replacing with placeholder tokens), removal, or encryption. Provides detailed reports on detected PII types and locations, enabling audit trails and compliance logging.

Allows developers to register custom JavaScript/TypeScript validation functions that execute as stages in the guardrail pipeline, enabling domain-specific validation logic beyond built-in checks. Custom validators receive input/output context (including conversation history, user metadata, LLM model info) and return validation results with pass/fail status and optional violation metadata. Validators are composable — multiple custom validators can be chained together, with early exit on failure and configurable error handling (fail-open vs fail-closed).

Applies guardrails with awareness of conversation history and context, enabling detection of policy violations that span multiple turns or depend on prior messages. Validators receive full conversation history, allowing detection of patterns like: repeated attempts to bypass guardrails, gradual escalation of harmful requests, or context-dependent violations (e.g., 'tell me a joke' is fine, but 'tell me a joke about [protected group]' is not). Supports conversation state tracking and can enforce per-user or per-session policies.

Supports multiple enforcement modes (block, warn, log, custom) with configurable severity levels for different violation types, enabling graduated responses to policy violations. Violations can be categorized by severity (critical, high, medium, low) and enforcement mode (hard block, soft warning, audit logging only, custom handler). Allows different rules to have different enforcement modes — e.g., prompt injection attempts are hard-blocked while mild toxicity triggers warnings. Supports A/B testing of policy strictness through configuration without code changes.

Provides native integration with OpenAI's API for semantic validation tasks including embeddings (for similarity-based content filtering), moderation endpoint (for toxicity/hate speech detection), and chat completions (for complex reasoning-based validation). Handles API authentication, rate limiting, retry logic, and error handling transparently. Supports fallback strategies when OpenAI APIs are unavailable and caching of embedding results to reduce API calls.