Template Repository Overview
The custom guardrails template repository provides a comprehensive FastAPI application with multiple guardrail implementations. It serves as a starting point for building your own custom guardrail server with best practices and example implementations.Architecture
The template follows a modular architecture:main.py
: FastAPI application with route definitionsguardrail/
: Directory containing all guardrail implementationsentities.py
: Pydantic models for request/response validationrequirements.txt
: Dependencies and libraries
Entities and Data Models
The template defines several Pydantic models that structure the data flow between TrueFoundry AI Gateway and your custom guardrail server.RequestContext
RequestContext
is a Pydantic model that provides structured contextual information for each request processed by your custom guardrail server. It includes details about the user (as a Subject
object) and optional metadata relevant to the request lifecycle. This context is automatically populated by the TrueFoundry AI Gateway and can be leveraged for access control, auditing, or custom logic within your guardrail implementations.
InputGuardrailRequest
OutputGuardrailRequest
Available Guardrails
The template repository includes five pre-implemented guardrails that demonstrate different validation and transformation techniques.1. PII Redaction (Presidio)
1. PII Redaction (Presidio)
Info
Info
Endpoint:
Type: Input Guardrail (Mutate)
Technology: Microsoft PresidioDetects and redacts Personally Identifiable Information (PII) from incoming requests using Microsoft’s Presidio library.
POST /pii-redaction
Type: Input Guardrail (Mutate)
Technology: Microsoft PresidioDetects and redacts Personally Identifiable Information (PII) from incoming requests using Microsoft’s Presidio library.
Code Snippet
Code Snippet
Response Behavior
Response Behavior
Response Behavior:
null
- No PII detected, no transformation neededChatCompletionCreateParams
- PII detected and redacted, returns modified requestHTTP 400/500
- Error occurred during processing
2. NSFW Filtering (Local Model)
2. NSFW Filtering (Local Model)
Info
Info
Endpoint:
Type: Output Guardrail (Validate)
Technology: Hugging Face Transformers (Unitary toxic classification model)Filters out Not Safe For Work (NSFW) content from model responses using a local toxic classification model.
POST /nsfw-filtering
Type: Output Guardrail (Validate)
Technology: Hugging Face Transformers (Unitary toxic classification model)Filters out Not Safe For Work (NSFW) content from model responses using a local toxic classification model.
Code Snippet
Code Snippet
Response Behavior
Response Behavior
Response Behavior:
null
- Content is safe, no issues detectedHTTP 400
- NSFW content detected, request blocked
3. Drug Mention Detection (Guardrails AI)
3. Drug Mention Detection (Guardrails AI)
Info
Info
Endpoint:
Type: Output Guardrail (Validate)
Technology: Guardrails AIDetects and rejects responses that mention drugs using Guardrails AI’s drug detection capabilities.
POST /drug-mention
Type: Output Guardrail (Validate)
Technology: Guardrails AIDetects and rejects responses that mention drugs using Guardrails AI’s drug detection capabilities.
Code Snippet
Code Snippet
Response Behavior
Response Behavior
Response Behavior:
null
- No drug mentions detectedHTTP 400
- Drug mentions detected, request blocked
4. Web Sanitization (Guardrails AI)
4. Web Sanitization (Guardrails AI)
Info
Info
Endpoint:
Type: Input Guardrail (Validate)
Technology: Guardrails AIDetects and rejects requests that contain malicious web content using Guardrails AI’s web sanitization capabilities.
POST /web-sanitization
Type: Input Guardrail (Validate)
Technology: Guardrails AIDetects and rejects requests that contain malicious web content using Guardrails AI’s web sanitization capabilities.
Code Snippet
Code Snippet
Response Behavior
Response Behavior
Response Behavior:
null
- No malicious content detectedHTTP 400
- Malicious content detected, request blocked
5. PII Detection (Guardrails AI)
5. PII Detection (Guardrails AI)
Info
Info
Endpoint:
Type: Input Guardrail (Validate)
Technology: Guardrails AIDetects the presence of Personally Identifiable Information (PII) in incoming requests using Guardrails AI. Unlike the Presidio implementation, this only detects and reports PII without redacting it.
POST /pii-detection
Type: Input Guardrail (Validate)
Technology: Guardrails AIDetects the presence of Personally Identifiable Information (PII) in incoming requests using Guardrails AI. Unlike the Presidio implementation, this only detects and reports PII without redacting it.
Code Snippet
Code Snippet
Response Behavior
Response Behavior
Response Behavior:
null
- No PII detectedHTTP 400
- PII detected, request blocked
Request Examples
Input Guardrail Request
Input Guardrail Request
Output Guardrail Request
Output Guardrail Request
Running Locally
Adding Custom Guardrail Integration
To add Custom Guardrail to your TrueFoundry setup, follow these steps:-
Navigate to AI Gateway
- Go to AI Gateway in your TrueFoundry dashboard.
-
Access Guardrails
- Click on Guardrails.
-
Add New Guardrails Group
- Click on Add New Guardrails Group.

Navigate to Guardrails
- Fill in the Guardrails Group Form
- Name: Enter a name for your guardrails group.
- Collaborators: Add collaborators who will have access to this group.
- Custom Guardrail Config:
- Name: Enter a name for the Custom Guardrail configuration.
- Operation: The operation type to use for the guardrail.
- Validate: Guardrails with this operation are used to validate requests. These guardrails are run in parallel.
- Mutate: Guardrails with this operation can both validate and mutate requests. Mutate guardrails are run sequentially.
- URL: Enter the URL for the Guardrail Server.
- Auth Data: Provide authentication data for the Guardrail Server. This data will be sent to the Guardrail Server for authorization.
- Choose between Custom Basic Auth or Custom Bearer Auth.
- Headers (Optional): Add any headers required for the Guardrail Server. These will be forwarded as is.
- Config: Enter the configuration for the Guardrail Server. This is a JSON object that will be sent along with the request.

Fill in the Custom Guardrail Form
How Custom Guardrail Config Relates to Guardrail Requests
When you configure a Custom Guardrail in the TrueFoundry guardrails integration creation form (as described above), the settings you provide—such as the operation type, URL, authentication data, headers, and config—directly influence how the AI Gateway interacts with your guardrail server at runtime. How it works:-
Config Propagation:
TheConfig
field you specify in the integration creation form is sent as theconfig
attribute in every guardrail request payload. This allows you to parameterize your guardrail logic (e.g., set thresholds, enable/disable features, or pass secrets) without changing your server code. -
Request Structure:
When a request is routed through a guardrail, the AI Gateway constructs a request object (such asInputGuardrailRequest
orOutputGuardrailRequest
) and sends it to your server. This object includes:- The original model input (
requestBody
) - (For output guardrails) The model’s response (
responseBody
) - The
config
object (from your integration creation form) - The
context
(user, metadata, etc.)
- The original model input (
-
Example Payload:
-
Dynamic Behavior:
By updating the Custom Guardrail Config in the integration creation form, you can change the behavior of your guardrail server in real time—no code redeploy required. For example, you might adjust PII detection sensitivity, toggle logging, or update allowed user lists.
Integration Creation Form Field | Sent in Guardrail Request as |
---|---|
Config | config |
Auth Data, Headers | HTTP headers customHeaders |
Operation | Determines endpoint & method |
URL | Guardrail server endpoint |
Example: Sending a Request to Your Guardrail Server
Sample Input Guardrail Request Payload & cURL Example
Integration Form Example Values
Integration Form Example Values
Field | Example Value |
---|---|
Operation | POST /pii-redaction |
URL | https://my-guardrail-server.example.com/pii-redaction |
Auth Data | Bearer <token> |
Headers | |
Config |
Sample Output Guardrail Request Payload & cURL Example
Integration Form Example Values
Integration Form Example Values
Field | Example Value |
---|---|
Operation | POST /nsfw-filtering |
URL | https://my-guardrail-server.example.com/nsfw-filtering |
Auth Data | Bearer <token> |
Headers | |
Config |