Reference
Data Models
Reference for Finding, DetectionResult, ValidationResult, and related data structures.
Data Models
Finding
A single PII detection result.
from fastpii.models import Finding
@dataclass(frozen=True)
class Finding:
type: str
value: str
start: int
end: int
confidence: float
region: str
metadata: dict[str, Any] = field(default_factory=dict)| Field | Type | Description |
|---|---|---|
type | str | Detector type (e.g., "rodne_cislo", "email", "pesel") |
value | str | The matched text |
start | int | Character offset of match start (0-indexed) |
end | int | Character offset of match end (exclusive) |
confidence | float | Confidence score between 0.0 and 1.0 |
region | str | Region code (e.g., "cz", "pl", "de", "fr") |
metadata | dict[str, Any] | Detector-specific metadata |
Finding is frozen (immutable). Create new instances with Finding(...).
JSON representation
{
"type": "rodne_cislo",
"value": "8001011238",
"start": 10,
"end": 20,
"confidence": 1.0,
"region": "cz",
"metadata": {
"checksum_valid": true,
"birth_date": "1980-01-01",
"gender": "male",
"article_9": true
}
}Common metadata fields
| Detector | Metadata fields |
|---|---|
rodne_cislo | checksum_valid, birth_date, gender, article_9 |
pesel | sex, birth_date |
ico | checksum_valid |
dic | format, checksum_valid |
email | local_part, domain, is_czech_domain |
steuer_id | checksum_valid |
siren | checksum_valid |
siret | checksum_valid, siren_prefix |
insee | sex, department, checksum_valid |
ust_id | checksum_valid, country_code |
DetectionResult
Result of a detection scan.
from fastpii.models import DetectionResult
@dataclass
class DetectionResult:
text: str
findings: list[Finding]
detector_names: list[str]
processing_time_ms: int| Field | Type | Description |
|---|---|---|
text | str | The original input text |
findings | list[Finding] | All detected PII findings |
detector_names | list[str] | Unique list of detector types that triggered |
processing_time_ms | int | Processing time in milliseconds |
JSON representation
{
"text": "Email: jan.novak@example.cz, RČ: 8001011238",
"findings": [...],
"detector_names": ["email", "rodne_cislo"],
"processing_time_ms": 2
}ValidationResult
Result of validating a single identifier.
from fastpii.models import ValidationResult
@dataclass
class ValidationResult:
detector: str
value: str
is_valid: bool
metadata: dict[str, Any] = field(default_factory=dict)| Field | Type | Description |
|---|---|---|
detector | str | The detector name used |
value | str | The input value |
is_valid | bool | Whether the value passed validation |
metadata | dict[str, Any] | Detector-specific metadata |
JSON representation
{
"detector": "rodne_cislo",
"value": "8001011238",
"is_valid": true,
"metadata": {
"checksum_valid": true,
"birth_date": "1980-01-01",
"gender": "male"
}
}TransformationStrategy
Protocol for PII transformation strategies.
from fastpii.core.transform import TransformationStrategy
from fastpii.models import Finding
@runtime_checkable
class TransformationStrategy(Protocol):
def replace(self, finding: Finding, text: str) -> str:
"""Return the replacement string for the given finding."""
...Built-in strategies
| Strategy | Class | Output |
|---|---|---|
| Anonymize | AnonymizeStrategy(replacement="[REDACTED]") | Fixed placeholder |
| Redact | RedactStrategy() | Type label like [EMAIL] |
| Mask | MaskStrategy() | Asterisks (*) preserving span length |
| Remove | RemoveStrategy() | Empty string |
DataSource
Metadata about a data source.
from fastpii.data.base import DataSource
@dataclass(frozen=True)
class DataSource:
name: str
url: str
license: str
last_updated: datetime
entry_count: intCountryMetadata
Country metadata for a data module.
from fastpii.data.base import CountryMetadata
@dataclass(frozen=True)
class CountryMetadata:
code: str
name: str
language_codes: tuple[str, ...] = ()
currency_code: str = ""