Skip to content
Factum ParseFactum ParseFactum Parse

Rizzo PII Sidecar

Overview

Section titled “Overview”

Rizzo is a local sidecar process that performs pseudonymization of Italian PII before the payload reaches any external LLM provider. It runs as a separate container within the same pod/network namespace as the API backend.

Architecture

Section titled “Architecture”
Client → API Backend → Rizzo Sidecar (pseudonymize) → LLM Provider → Rizzo (restore) → Response
  1. Pseudonymize: the backend sends the raw document text to Rizzo via local HTTP. Rizzo returns a masked version with all detected PII replaced by placeholders (e.g. [NOME-1], [CF-2], [INDIRIZZO-3]), plus a mapping dictionary.
  2. External extraction: the masked text is sent to the LLM provider for semantic extraction.
  3. Restore: the LLM result (which may contain hallucinated or modified PII placeholders) is processed by Rizzo’s restore() function, running locally within the backend process. The mapping is replaced back with original values.

Detected entities (22 categories)

Section titled “Detected entities (22 categories)”
Category Example
Person names (NOME) Mario Rossi
Fiscal codes (CF) RSSMRA85M01A001X
VAT numbers (IVA) IT01234567890
Addresses (INDIRIZZO) Via Roma 1, Milano
Phone numbers +39 02 12345678
Email addresses mario@example.com
Bank account details (IBAN) IT60X0542811101000000123456
Tax registration numbers
Company names ACME S.p.A.
Document identifiers
Social Security numbers
Passport numbers
Driver’s license numbers
Health card numbers
Professional license numbers
Vehicle registration plates
Insurance policy numbers
Contract numbers
Invoice numbers (as PII only when tied to individual)
PEC addresses
IP addresses
Digital signature references

Configuration

Section titled “Configuration”
Environment variable Default Description
RIZZO_PII_REQUIRED true Fail-closed: if true, Rizzo unavailability → 503
RIZZO_PII_SIDECAR_HOST rizzo-sidecar Sidecar hostname
RIZZO_PII_SIDECAR_PORT 8081 Sidecar HTTP port
RIZZO_PII_TIMEOUT 5.0 HTTP timeout in seconds
RIZZO_PII_MAX_TEXT_CHARS 200000 Maximum text length for pseudonymization

Prometheus metrics

Section titled “Prometheus metrics”
Metric Type Description
rizzo_pii_up Gauge Sidecar reachability (1=up, 0=down)
rizzo_pii_calls_total Counter Total pseudonymization calls
rizzo_pii_timeout_total Counter Total timeout errors
rizzo_pii_entities_detected Gauge Entities detected in last call
rizzo_pii_pseudonymize_duration_seconds Histogram Pseudonymization latency
rizzo_pii_restore_duration_seconds Histogram Restoration latency