dspy-guardrails 0.1.7

About

DSPy Guardrails is a comprehensive suite of AI guardrails built with DSPy. Each guardrail is implemented as a self-contained module that can be used to test and validate different types of content moderation and security checks.

• Modular design — Each guardrail type is implemented as a separate, self-contained module
• Two-stage detection — A fast regex prefilter handles known patterns before any LLM call, so most requests never reach the model
• Programmatic testing — Run guardrails directly in Python for fast iteration
• Comprehensive coverage — Covers major content moderation and security scenarios
• DSPy integration — Leverages DSPy's programmatic prompting for consistent, reliable results
• Type safety — Full type hints and dataclass definitions for robust implementations

(back to top)

Quick Start

Install

Install dspy-guardrails with uv (recommended)

uv add dspy-guardrails

Install with pip (alternative)

pip install dspy-guardrails

Continue with the usage examples below.

(back to top)

Usage

Basic Usage

import dspy
from dspy_guardrails import guardrail

# Configure DSPy (required)
lm = dspy.LM("openrouter/google/gemini-2.5-flash-preview-09-2025")
guardrail.configure(lm=lm)

# Create and run guardrails
topic_guardrail = guardrail.Topic(topic_scopes=["AI", "Machine Learning"])
result = guardrail.Run(topic_guardrail, "I want to learn about neural networks")
print(f"Allowed: {result.is_allowed}")  # True

Multiple Guardrails

Assumes guardrail.configure(lm=lm) has already been called.

all_guardrails = [
    guardrail.Topic(topic_scopes=["AI"]),
    guardrail.Nsfw(),
    guardrail.Pii(),
]
result = guardrail.Run(all_guardrails, "Safe AI content")
print(f"All passed: {result.is_allowed}")  # True

Early Return

Stop execution on the first failing guardrail.

guardrails = [guardrail.Topic(topic_scopes=["AI"]), guardrail.Nsfw()]
result = guardrail.Run(guardrails, "Risky content", early_return=True)
print(result.is_allowed)

Parallel Execution

For bulk checks with multiple guardrails, fan them out concurrently on a ThreadPoolExecutor with parallel=True. Each text's guardrail fan-out runs on its own thread, so a bulk check with N guardrails takes roughly the time of the slowest single guardrail, not the sum of all of them.

result = guardrail.Run(
    [pii_gr, secret_keys_gr, prompt_injection_gr],
    "Email me at user@example.com",
    parallel=True,
    num_threads=8,    # optional thread pool size
)
print(result.is_allowed)
print(result.metadata["parallel"])    # True
print(result.metadata["num_threads"])  # 8

parallel=True only affects the aggregated path (multiple guardrails or multiple texts). It composes with early_return=True — all guardrails still execute concurrently; the result reflects the first failure, and processing stops at the first text with any failure.

For more examples and patterns, see the complete quickstart guide and guardrail types. For the regex prefilter catalog, opt-out flags, and custom-pattern reference, see docs/REGEX_PREFILTERS.md.

(back to top)

Two-Stage Detection: Regex Prefilter + LLM

Most guardrails (Pii, PromptInjection, SecretKeys, Jailbreak, Keywords, Gibberish, Toxicity, Language, Topic) run a fast regex prefilter before calling the DSPy LLM. If the prefilter matches, the guardrail short-circuits with is_allowed=False and method="regex_prefilter" in the result metadata — no model call is made, so the request is handled deterministically and at zero API cost. Only requests that pass the prefilter are sent to the LLM.

result = guardrail.Run(pii_guardrail, "Email me at user@example.com")
result.metadata["method"]    # "regex_prefilter" (fast) or "dspy" (LLM)
result.metadata["matches"]   # list of {slug, matched_text, ...} on a prefilter hit

The prefilter is opt-out per guardrail (e.g. enable_regex_prefilter=False, enable_script_prefilter=False, enable_blocked_topic_prefilter=False) and accepts user-supplied custom patterns where the API supports them (Pii.custom_patterns, SecretKeys.custom_patterns). Custom patterns are ReDoS-screened at construction time. See Parallel Execution above for running multiple guardrails concurrently.

(back to top)

Available Guardrails

Development

Code Quality

This project uses several tools to maintain code quality:

• Ruff: Linting and formatting
• isort: Import sorting
• pytest: Testing framework

Available commands:

# Run all quality checks
uv run poe clean

# Individual checks
uv run poe lint          # Ruff linting
uv run poe format        # Ruff formatting
uv run poe sort          # Import sorting

Testing

Run tests using pytest:

# Run all tests
uv run pytest

# Run specific test
uv run pytest path/to/test.py::test_name

(back to top)

Contributing

Quick workflow:

1. Fork and branch: git checkout -b feature/name
2. Make changes
3. Run checks: uv run poe clean-full
4. Commit and push
5. Open a Pull Request

(back to top)

License

MIT (as declared in pyproject.toml).

(back to top)