README

High-performance PII detection, redaction, and reversible pseudonymization engine for Agentoom.

Important

Post-Splitting Versioning & Pre-Release Notice (v0.8.0) Version 0.8.0 represents the initial standalone release following the modular package extraction and architectural splitting from the Agentoom core monorepo. This package is currently in a pre-release state undergoing integration testing and requires appropriate validation and test coverage across target environments before being designated as production-stable (1.0.0).

🌟 Overview

The agentoom/core-privacy package protects Personally Identifiable Information (PII) across the Agentoom platform. It ensures sensitive personal data (such as emails, phone numbers, credit cards, social security numbers, IP addresses, and IBANs) is redacted or pseudonymized before prompts are sent to external LLMs, and safely de-pseudonymized when answers are returned to authenticated end-users. It also integrates into Laravel's logging pipeline to prevent PII leakage into log files.

Package Name: agentoom/core-privacy
Version: 0.8.0 (Pre-release / Post-split testing)
Namespace: Agentoom\Privacy\
Service Provider: Agentoom\Privacy\PrivacyServiceProvider

🚀 Key Features

1. Deterministic PII Detection

Pattern & Regex Recognizers: High-speed local regex engine (DeterministicPiiDetector) identifying structured identifiers:
- Email addresses, telephone numbers, IP addresses, credit cards, bank accounts (IBAN), national IDs, and tax codes.
Configurable Recognizer Catalog: Pre-configured catalog in config/privacy-recognizers.php, customizable via database records (PrivacyRecognizer, PiiMaskingRule).

2. Reversible Pseudonymization & De-anonymization

Context-Preserving Tokens: Replaces sensitive data with typed placeholders (e.g. [EMAIL_1], [PHONE_1]) via Pseudonymizer and AgpiiTagProcessor.
Mapping Store: Securely retains placeholder-to-value mappings in temporary storage (MappingStore) during the conversation turn.
Automatic De-anonymization: Re-inserts original personal data into the final assistant response before displaying it to the authorized user, ensuring LLMs reason about data without ever observing sensitive raw values.

3. Log Scrubbing & Leakage Prevention

Monolog Processor: Includes PrivacyLogProcessor and PrivacyLogTap that automatically scrub PII from Laravel application log files, stack traces, and debug dumps.

4. Hybrid Architecture & Remote Extension

Hybrid PII Detector: Combines local deterministic pattern matching with remote semantic engines (such as agentoom/core-privacy-pro) via HybridPiiDetector and SpanMerger.
Fault-Tolerant Fallback: If remote services are unavailable, the deterministic detector gracefully handles privacy filtering without breaking user requests.

5. Administration & Inspection

Livewire Management: Administrative panel for creating custom regex rules, adjusting confidence thresholds, and testing sample inputs in real time.
Multi-Language Support: Fully localized in English (en), German (de), Spanish (es), French (fr), and Italian (it).

📁 Package Structure

core-privacy/
├── config/
│   ├── agentoom-privacy.php        # General privacy pipeline settings
│   └── privacy-recognizers.php     # Built-in regex recognizers
├── database/
│   ├── migrations/                 # Tables for privacy_recognizers and pii_masking_rules
│   └── seeders/                    # PiiMaskingRuleSeeder
├── resources/
│   ├── lang/                       # Translations (de, en, es, fr, it)
│   └── views/livewire/admin/       # Livewire admin management views
├── routes/
│   └── web.php                     # Admin configuration routes
└── src/
    ├── Contracts/
    │   ├── PiiDetector.php         # Detector interface
    │   └── PiiDetectorAvailability.php
    ├── Logging/
    │   ├── PrivacyLogProcessor.php # Monolog log scrubber
    │   └── PrivacyLogTap.php
    ├── Models/
    │   ├── PiiMaskingRule.php      # Custom masking rules
    │   └── PrivacyRecognizer.php   # Recognizer entities
    ├── AgpiiTagProcessor.php       # Tag manipulation
    ├── DeterministicAnonymizer.php # Text replacement engine
    ├── DeterministicPiiDetector.php # Regex scanner
    ├── HybridPiiDetector.php       # Deterministic + Remote merger
    ├── MappingStore.php            # Token replacement memory
    ├── PrivacyService.php          # Core privacy orchestrator
    ├── Pseudonymizer.php           # Two-way pseudonymizer
    └── PrivacyServiceProvider.php

🛠️ Usage Example

use Agentoom\Privacy\PrivacyService;

$privacy = app(PrivacyService::class);

$rawPrompt = "Please email John Doe at john.doe@example.com or call +1 555-0199.";

// 1. Redact / Pseudonymize before sending to LLM
$cleanPrompt = $privacy->pseudonymize($rawPrompt);
// Output: "Please email John Doe at [EMAIL_1] or call [PHONE_1]."

// 2. Re-substitute original values when returning response to user
$llmResponse = "We have scheduled a meeting and sent confirmation to [EMAIL_1].";
$finalResponse = $privacy->depseudonymize($llmResponse);
// Output: "We have scheduled a meeting and sent confirmation to john.doe@example.com."

agentoom / core-privacy

Package info

Security

Statistics