Overview#
The PII Detection evaluator screens a conversation string for personally identifiable information (PII). Pass whatever slice of the interaction you want judged — user and assistant turns only, or a fuller record that also includes system instructions, tool calls, tool results, or retrieved documents. The judge classifies whether any identifying personal data is present in that string.
Use it to audit agent traces, experiment runs, and logged conversations for privacy exposure. When include_explanation is True (the default on ClassificationEvaluator), the judge lists each instance in a FINDINGS block on the score’s explanation so downstream filters can act on specific categories (email, national ID, API token, and so on). Set include_explanation=False to skip that reasoning and return only the label and score.
Direction is minimize: detecting PII is the undesirable outcome.
Supported Levels#
The level of an evaluator determines the scope of the evaluation in OpenTelemetry terms. Some evaluations are applicable to individual spans, some to full traces or sessions, and some are applicable at multiple levels.
| Level | Supported | Notes |
|---|---|---|
| Span | Yes | Apply when a span already contains the conversation text you want to screen. |
| Trace | Yes | Concatenate the span inputs and outputs you care about into one conversation string. Include tool results only if tool payloads are in scope for the audit. |
| Session | Yes | Screen the session transcript you assemble. Include hidden tool output or retrieved documents when those surfaces matter for privacy; omit them when you only want user-visible turns. |
Relevant span kinds: AGENT, CHAIN, and LLM spans that preserve conversation text. Include TOOL spans when you are evaluating tool payloads.
Input Requirements#
The PII Detection evaluator requires one input:
| Field | Type | Description |
|---|---|---|
conversation | string | The text to screen. Typically user and assistant turns; optionally include system instructions, tool calls, tool results, or retrieved content when those are part of what you want evaluated. |
Formatting Tips#
For best results:
- Include every turn that is in scope, not just the final assistant message.
- Add tool calls, tool results, or retrieved documents when you care about PII in those payloads. Leave them out when you only want to score the visible dialogue.
- Use human-readable strings rather than raw JSON when you can.
- For multi-turn conversations, format turns as:
Output Interpretation#
The evaluator returns a Score object with the following properties:
| Property | Value | Description |
|---|---|---|
label | "pii_detected" or "no_pii_detected" | Classification result |
score | 1.0 or 0.0 | Numeric score (1.0 = PII found) |
explanation | string or omitted | Present when include_explanation is True (default). Contains the judge’s reasoning and a FINDINGS list of each instance (see below). |
direction | "minimize" | Lower aggregate scores are better |
metadata | object | Additional information such as the model name. When tracing is enabled, includes the trace_id for the evaluation. |
Interpretation:
- PII detected (1.0): The record contains at least one instance of identifying personal data
- No PII detected (0.0): The record contains none of the rubric categories
Findings#
When explanations are enabled, each detected instance appears as one line in a FINDINGS block:
If nothing is found, the judge writes FINDINGS: none.
| Field | Meaning |
|---|---|
type | Rubric category for that instance, such as person_name, email_address, phone_number, national_id_number, physical_address, credit_or_debit_card_number, or api_key_or_token. |
source | Where in the conversation string the instance appeared: user_message, assistant_response, tool_call_or_result, system_instructions, or retrieved_document. |
type and source are meant for downstream filters (for example, alert only on national_id_number in tool_call_or_result). They are not separate score fields; parse them from explanation.
Usage Examples#
Using Input Mapping#
Map a trace, session, or dataset row into the single conversation field. Concatenate whichever columns are in scope — messages only, or messages plus tool calls and retrieved documents.
See Input Mapping for additional mapping options.
Viewing and Modifying the Prompt#
The default prompt is maintained in the classification evaluator config. Adapt it when your product has domain-specific identifiers or a different definition of personal data.
Configuration#
PiiDetectionEvaluator is a ClassificationEvaluator. The following constructor argument controls whether the judge writes FINDINGS into the score:
| Argument | Type | Description |
|---|---|---|
include_explanation | bool (optional) | If True (default), the LLM is asked for an explanation and puts each detected instance in a FINDINGS block there. If False, the score has no explanation. |
include_explanation is a Python constructor argument. The TypeScript createPiiDetectionEvaluator always requests an explanation.
For model and provider options, see Configuring the LLM.
Using with Phoenix#
Benchmarks#
On a 40-example authored suite (24 with PII, 16 without) using gpt-4o-mini,
the default prompt achieves 0.93 accuracy, 0.94 macro precision,
0.91 macro recall, and 0.92 macro F1. See
pii_detection.synthetic.eval.ts.
On a stratified 150-record sample of
nvidia/Nemotron-PII
(all positives) using gpt-4o-mini, the same prompt achieves a 0.96
detection rate (recall). Precision cannot be measured on that fixture because
it contains effectively no negatives. See
pii_detection.eval.ts.
API Reference#
- Python: PiiDetectionEvaluator
- TypeScript: createPiiDetectionEvaluator