simstudioai--sim/apps/sim/lib/guardrails/README.md

Guardrails Validators

Validation scripts for the Guardrails block.

Validators

• JSON Validation - Validates if content is valid JSON (TypeScript)
• Regex Validation - Validates content against regex patterns (TypeScript)
• Hallucination Detection - Validates LLM output against knowledge base using RAG + LLM scoring (TypeScript)
• PII Detection - Detects personally identifiable information using Microsoft Presidio (Python)

Setup

TypeScript Validators (JSON, Regex, Hallucination)

No additional setup required! These validators work out of the box.

For hallucination detection, you'll need:

• A knowledge base with documents
• An LLM provider API key (or use hosted models)

PII Detection (Presidio service)

PII detection runs against a standalone Presidio service — a combined analyzer + anonymizer (built from docker/pii.Dockerfile, source in apps/pii/server.py) that constructs a warm AnalyzerEngine + AnonymizerEngine once and exposes /analyze, /anonymize, and /health on a single port. In deployment it is its own ECS service (a dedicated task/service, not a sidecar in the app task), reached over the network via PII_URL and scaled independently of the app. The app (both the Next.js server and the trigger.dev runtime) is a thin HTTP client (validate_pii.ts) — no Python, no local venv.

Locally, build and run it as a container:

docker build -f docker/pii.Dockerfile -t sim-pii .
docker run -d -p 5001:5001 sim-pii

Point the app at it with PII_URL:

• Local: PII_URL=http://localhost:5001 (the default)
• Deployed: PII_URL points to the Presidio ECS service's internal endpoint (service-discovery DNS / internal load balancer) — never localhost, since the service runs in a separate task

The image bakes in the recognizers itself — a check-digit-validated VIN recognizer and multi-language NLP models (en/es/it/pl/fi). The redaction language is configured per rule (Data Retention) and defaults to English.

Deploy requirement: the execution-altering redaction stages (workflow input + block outputs) fail-fast and abort a run if the Presidio service is unreachable. Every environment that can run workflows must have a reachable Presidio service at PII_URL.

Usage

JSON & Regex Validation

These are implemented in TypeScript and work out of the box - no additional dependencies needed.

Hallucination Detection

The hallucination detector uses a modern RAG + LLM confidence scoring approach:

1. RAG Query - Calls the knowledge base search API to retrieve relevant chunks
2. LLM Confidence Scoring - Uses an LLM to score how well the user input is supported by the retrieved context on a 0-10 confidence scale:
   • 0-2: Full hallucination - completely unsupported by context, contradicts the context
   • 3-4: Low confidence - mostly unsupported, significant claims not in context
   • 5-6: Medium confidence - partially supported, some claims not in context
   • 7-8: High confidence - mostly supported, minor details not in context
   • 9-10: Very high confidence - fully supported by context, all claims verified
3. Threshold Check - Compares the confidence score against your threshold (default: 3)
4. Result - Returns passed: true/false with confidence score and reasoning

Configuration:

• knowledgeBaseId (required): Select from dropdown of available knowledge bases
• threshold (optional): Confidence threshold 0-10, default 3 (scores below 3 fail)
• topK (optional): Number of chunks to retrieve, default 10
• model (required): Select from dropdown of available LLM models, default gpt-4o-mini
• apiKey (conditional): API key for the LLM provider (hidden for hosted models and Ollama)

PII Detection

The PII detector uses Microsoft Presidio to identify personally identifiable information:

1. Analysis - Scans text for PII entities using pattern matching, NER, and context
2. Detection - Identifies PII types like names, emails, phone numbers, SSNs, credit cards, etc.
3. Action - Either blocks the request or masks the PII based on mode

Modes:

• Block Mode (default): Fails validation if any PII is detected
• Mask Mode: Passes validation and returns text with PII replaced by <ENTITY_TYPE> placeholders

Configuration:

• piiEntityTypes (optional): Array of PII types to detect (empty = detect all)
• piiMode (optional): block or mask, default block
• piiLanguage (optional): Language code, default en

Supported PII Types:

• Common: Person name, Email, Phone, Credit card, Location, IP address, Date/time, URL
• USA: SSN, Passport, Driver license, Bank account, ITIN
• UK: NHS number, National Insurance Number
• Other: Spanish NIF/NIE, Italian fiscal code, Polish PESEL, Singapore NRIC, Australian ABN/TFN, Indian Aadhaar/PAN, and more

See Presidio documentation for full list.

Files

• validate_json.ts - JSON validation (TypeScript)
• validate_regex.ts - Regex validation (TypeScript)
• validate_hallucination.ts - Hallucination detection with RAG + LLM scoring (TypeScript)
• validate_pii.ts - PII detection client: calls the Presidio service's /analyze + /anonymize (TypeScript)
• pii-entities.ts - Client-safe PII entity + language catalog (shared by the block and Data Retention)
• mask-client.ts - Internal HTTP client for batch PII masking from the log-redaction persist path
• validate.test.ts - Test suite for JSON and regex validators