Skip to main content

PIIDetector

The PIIDetector is a hybrid processor that can be used for both input and output processing to detect and redact personally identifiable information (PII) for privacy compliance. This processor helps maintain privacy by identifying various types of PII and providing flexible strategies for handling them, including multiple redaction methods to ensure compliance with GDPR, CCPA, HIPAA, and other privacy regulations.

Usage example​

import { openai } from "@ai-sdk/openai";
import { PIIDetector } from "@mastra/core/processors";

const processor = new PIIDetector({
  model: openai("gpt-4.1-nano"),
  threshold: 0.6,
  strategy: "redact",
  detectionTypes: ["email", "phone", "credit-card", "ssn"],
});

Constructor parameters​

options:

Options
Configuration options for PII detection and redaction

Options​

model:

MastraLanguageModel
Model configuration for the detection agent

detectionTypes?:

string[]
PII types to detect. If not specified, uses default types

threshold?:

number
Confidence threshold for flagging (0-1). PII is flagged if any category score exceeds this threshold

strategy?:

'block' | 'warn' | 'filter' | 'redact'
Strategy when PII is detected: 'block' rejects with error, 'warn' logs warning but allows through, 'filter' removes flagged messages, 'redact' replaces PII with redacted versions

redactionMethod?:

'mask' | 'hash' | 'remove' | 'placeholder'
Redaction method for PII: 'mask' replaces with asterisks, 'hash' replaces with SHA256 hash, 'remove' removes entirely, 'placeholder' replaces with type placeholder

instructions?:

string
Custom detection instructions for the agent. If not provided, uses default instructions based on detection types

includeDetections?:

boolean
Whether to include detection details in logs. Useful for compliance auditing and debugging

preserveFormat?:

boolean
Whether to preserve PII format during redaction. When true, maintains structure like ***-**-1234 for phone numbers

Returns​

name:

string
Processor name set to 'pii-detector'

processInput:

(args: { messages: MastraMessageV2[]; abort: (reason?: string) => never; tracingContext?: TracingContext }) => Promise<MastraMessageV2[]>
Processes input messages to detect and redact PII before sending to LLM

processOutputStream:

(args: { part: ChunkType; streamParts: ChunkType[]; state: Record<string, any>; abort: (reason?: string) => never; tracingContext?: TracingContext }) => Promise<ChunkType | null | undefined>
Processes streaming output parts to detect and redact PII during streaming

Extended usage example​

import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";
import { PIIDetector } from "@mastra/core/processors";

export const agent = new Agent({
  name: "private-agent",
  instructions: "You are a helpful assistant",
  model: openai("gpt-4o-mini"),
  inputProcessors: [
    new PIIDetector({
      model: openai("gpt-4.1-nano"),
      detectionTypes: ["email", "phone", "credit-card", "ssn"],
      threshold: 0.6,
      strategy: "redact",
      redactionMethod: "mask",
      instructions:
        "Detect and redact personally identifiable information while preserving message intent",
      includeDetections: true,
      preserveFormat: true,
    }),
  ],
});