Skip to main content
The PromptGuard Python SDK provides auto-instrumentation that secures all your LLM calls — OpenAI, Anthropic, Google, Cohere, and AWS Bedrock — without changing any application code. Frameworks built on those SDKs are covered too; see Integrations.

GitHub Repository

Open source - MIT license. Star the repo, report issues, or contribute.
Release notes for each version, and where to report a bug: Versioning & support. Every public class, function and method, with signatures and parameters: Python SDK reference.

Installation

Optional extras for framework-specific integrations:
Requires Python 3.10 or later. Pin the version you tested in your own lockfile. Moving from 1.x? See Upgrade to SDK and CLI 2.0.

Quick Start

Add two lines to your application startup. Every LLM call is now protected:
Set the PROMPTGUARD_API_KEY environment variable so you don’t need to pass api_key in code. You can also set PROMPTGUARD_BASE_URL to point to a custom deployment.

Auto-Instrumentation

promptguard.init() is the recommended way to use the SDK. It monkey-patches the create() methods on popular LLM SDKs so every call is scanned by the PromptGuard Guard API — before (and optionally after) the LLM is invoked.

promptguard.init()

What gets patched

The provider SDKs and call surfaces init() patches, the libraries it does not, and how to check at runtime are on the auto-instrumentation page.

Modes

Enforce mode (default) — blocks requests that violate security policies by raising PromptGuardBlockedError:
Monitor mode — logs threats but never blocks. Useful for shadow deployment and testing:

Fail Open vs. Fail Closed

Controls behavior when the PromptGuard Guard API is unreachable:
Setting fail_open=False means your LLM calls will fail if the Guard API is unreachable. Only use this in high-security environments where blocking is preferable to unscanned requests.

Response Scanning

By default, only inputs (prompts) are scanned. Enable response scanning to also check LLM outputs:

promptguard.shutdown()

Removes all patches and closes the guard client. Call this during application shutdown:

Guard Client

The GuardClient lets you scan content directly without auto-instrumentation. Useful for custom scanning workflows or when you need fine-grained control.

Creating a Client

guard.scan()

Synchronous content scanning:

guard.scan_async()

Async version with the same interface:

GuardDecision

Both scan() and scan_async() return a GuardDecision object: Convenience properties:

Cleanup


Framework Integrations

The SDK also hooks into frameworks directly, for chain, tool and agent context in each scan. Each install below installs the latest release:

Error Handling

PromptGuardBlockedError

Raised when auto-instrumentation blocks a request in enforce mode. Contains the full GuardDecision:

GuardApiError

Raised when the Guard API is unreachable or returns an error. Only surfaced when fail_open=False — when fail_open=True (the default), API errors are caught internally and the request is allowed through.

PromptGuardError

Raised by the proxy client (PromptGuard class) for API-level errors:

Retry Configuration

Both PromptGuard and PromptGuardAsync automatically retry requests that fail with 429 (rate limited), 5xx (server error), or transient transport errors (connection resets, timeouts). Retries use exponential backoff.
Retry behavior:
  • 429 responses — retried after the Retry-After header value (if present), otherwise exponential backoff
  • 500, 502, 503, 504 responses — retried with exponential backoff
  • Transport errors (connection reset, DNS failure, timeout) — retried with exponential backoff
  • 4xx responses (other than 429) — not retried (these indicate client errors)
GuardClient does not retry and takes no retry parameters: its constructor accepts api_key, base_url and timeout only. Retry a GuardApiError in your own code if you need to.

Proxy Mode (Legacy)

The PromptGuard proxy client is the original way to use the SDK. It still works, but auto-instrumentation via promptguard.init() is the recommended approach — it requires no code changes to your LLM calls.
The PromptGuard class provides an OpenAI-compatible client that routes requests through the PromptGuard proxy for security scanning. It sends only your PromptGuard key, so chat completions reach the provider only when you have stored a provider key for it:

Streaming

The proxy holds a streamed response until the provider has finished and the output has been scanned, so the chunks arrive together (how streaming works).

Context Manager

Async Client

The PromptGuardAsync class provides full async API parity with PromptGuard. All resource namespaces are available:

Complete Example


Environment Variables


Requirements

  • Python 3.10+
  • httpx >= 0.24.0 (installed automatically)
  • LLM SDKs you want to protect (e.g., openai, anthropic) — install separately

Next steps

Python SDK reference

Every class, option and type in the Python SDK

Auto-instrumentation

Which provider calls init() patches, and which it does not

Streaming

How streamed responses are buffered, scanned and released

FastAPI

Scan prompts before your route runs
Last modified on November 16, 2026