Add PII, toxicity and regex scanners

Introduce three new scanner modules and associated docs/tests:

- Add src/pytector/pii.py (PIIScanner) using a transformer NER pipeline (default: joneauxedgar/pasteproof-pii-detector-v2) to scan, redact and report PII entities.
- Add src/pytector/toxicity.py (ToxicityDetector) using a text-classification pipeline (default: citizenlab/distilbert-base-multilingual-cased-toxicity) to score/flag toxic text.
- Add src/pytector/regex_scanner.py (RegexScanner) — a pure-stdlib, rule-based scanner with sensible default patterns and runtime pattern management.

Also:
- Export the new classes from src/pytector/__init__.py and bump package version to 0.3.1.
- Add unit tests for each new scanner (tests/test_pii.py, tests/test_regex_scanner.py, tests/test_toxicity.py).
- Update README, docs (api, examples, index, quickstart), and the notebook demo with usage examples and feature descriptions.

Author: MaxMLang

README.md

@@ -47,6 +47,9 @@ Pytector provides a defence-in-depth layer for prompt injection. Always combine
 - **LangChain Guardrail Runnable**: Adds `PytectorGuard` for LCEL pipelines (`guard | prompt | llm`) so unsafe prompts can be blocked before model execution.
 - **Keyword-Based Blocking**: Provides restrictive keyword filtering for both input and output layers with customizable keyword lists for immediate security control.
 - **Input Sanitization**: Cleans user input through a six-strategy pipeline — encoding detection (Base64/hex/ROT13), unicode normalization, regex pattern removal, sentence-level heuristic scoring, fuzzy matching, and keyword stripping — with an optional prompt enforcement layer for template escaping. Zero additional dependencies.
+- **PII Detection**: Scans text for personally identifiable information using the [PasteProof PII Detector](https://huggingface.co/joneauxedgar/pasteproof-pii-detector-v2) (ModernBERT NER, F1 0.97) with 27 entity types covering financial, credential, healthcare, GDPR, identity, contact, and address data. Supports scan, redact, and report workflows.
+- **Toxicity Detection**: Classifies text as toxic or non-toxic using a multilingual [citizenlab DistilBERT](https://huggingface.co/citizenlab/distilbert-base-multilingual-cased-toxicity) model (F1 0.94, 10 languages). Returns a toxicity score mirroring the prompt injection detector API.
+- **Regex Scanner**: Rule-based pattern matching for PII and credentials (email, phone, SSN, credit card, IP, API keys, JWT) using pure Python stdlib. Fully customizable — add, remove, or replace patterns at construction or runtime.
 - **Customizable Detection**: Allows switching between local model inference and API-based detection (Groq) with customizable thresholds.
 - **Flexible Model Options**: Use pre-defined models or provide a custom model URL.
 - **Rapid Deployment**: Designed for quick integration into projects that need immediate security layers beyond foundation model defaults.
@@ -132,7 +135,7 @@ To use Pytector, import the `PromptInjectionDetector` class and create an instan
 ## Notebook Demo
 
 An end-to-end Jupyter notebook is available at `notebooks/pytector_demo.ipynb`.  
-It covers local inference, keyword blocking, Groq integration with `openai/gpt-oss-safeguard-20b`, both Prompt Guard 2 models (`meta-llama/llama-prompt-guard-2-22m` and `meta-llama/llama-prompt-guard-2-86m`), LangChain LCEL guardrail usage, and input sanitization with `PromptSanitizer`.
+It covers local inference, keyword blocking, Groq integration with `openai/gpt-oss-safeguard-20b`, both Prompt Guard 2 models (`meta-llama/llama-prompt-guard-2-22m` and `meta-llama/llama-prompt-guard-2-86m`), LangChain LCEL guardrail usage, input sanitization with `PromptSanitizer`, PII detection with `PIIScanner`, toxicity detection with `ToxicityDetector`, and regex-based scanning with `RegexScanner`.
 
 ### Groq Migration Note (March 5, 2026)
 `meta-llama/llama-guard-4-12b` was deprecated in favor of `openai/gpt-oss-safeguard-20b`.
@@ -395,6 +398,83 @@ sanitizer.remove_keywords("evil")
 print(sanitizer.get_keywords())
 ```
 
+### Example 10: PII Detection
+Scan text for personally identifiable information using a transformer NER model:
+
+```python
+from pytector import PIIScanner
+
+scanner = PIIScanner()  # defaults to pasteproof-v3
+
+# Scan returns (has_pii, entities) — same tuple style as check_input_keywords()
+has_pii, entities = scanner.scan("Contact john@acme.com, SSN 123-45-6789")
+for ent in entities:
+    print(f"  [{ent['type']}] {ent['text']} (score={ent['score']:.2f})")
+
+# Redact PII in-place
+redacted = scanner.redact("Contact john@acme.com, SSN 123-45-6789")
+print(redacted)  # "Contact [REDACTED], SSN [REDACTED]"
+
+# Human-readable report
+scanner.report("Contact john@acme.com, SSN 123-45-6789")
+
+# Filter to specific entity types
+scanner = PIIScanner(entity_types=["EMAIL", "CREDIT_CARD"])
+has_pii, entities = scanner.scan("Email: a@b.com, SSN: 123-45-6789")
+# Only EMAIL entities returned; SSN is ignored
+```
+
+### Example 11: Toxicity Detection
+Classify text as toxic or non-toxic:
+
+```python
+from pytector import ToxicityDetector
+
+detector = ToxicityDetector()  # defaults to citizenlab multilingual model
+
+# Returns (is_toxic, score) — same shape as detect_injection()
+is_toxic, score = detector.detect("You are terrible and worthless")
+print(f"Toxic: {is_toxic}, Score: {score:.2f}")
+
+# Adjust threshold per call
+is_toxic, score = detector.detect("You are terrible", threshold=0.8)
+
+# Human-readable report
+detector.report("Have a wonderful day!")
+```
+
+### Example 12: Regex Scanner (Customizable)
+Fast, rule-based pattern matching with no model downloads:
+
+```python
+from pytector import RegexScanner
+
+# Ships with defaults: EMAIL, PHONE, SSN, CREDIT_CARD, IP_ADDRESS, API_KEY, JWT_TOKEN
+scanner = RegexScanner()
+
+has_match, matches = scanner.scan("Key: sk-live-abc123def456, IP: 10.0.0.1")
+for m in matches:
+    print(f"  [{m['pattern_name']}] {m['match']}")
+
+# Redact all matches
+print(scanner.redact("Email me at user@example.com"))
+# "Email me at [REDACTED]"
+
+# Add your own patterns
+scanner.add_pattern("AWS_ACCESS_KEY", r"AKIA[0-9A-Z]{16}")
+scanner.add_pattern("INTERNAL_ID", r"INT-\d{6}")
+
+# Remove a default pattern
+scanner.remove_pattern("JWT_TOKEN")
+
+# Use only custom patterns (no defaults)
+custom = RegexScanner(
+    patterns={"ORDER_ID": r"ORD-\d{8}", "ZIP": r"\b\d{5}(?:-\d{4})?\b"},
+    use_defaults=False,
+)
+print(custom.get_patterns())  # {'ORDER_ID': ..., 'ZIP': ...}
+```
+
 
 
 ## Security Best Practices

docs/api.rst

@@ -182,3 +182,126 @@ Sanitizer Configuration
    * - sentence_threshold
      - 0.5
      - Heuristic score cutoff for sentence removal (0.0-1.0)
+
+PIIScanner
+----------
+
+.. automodule:: pytector.pii
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Uses the `PasteProof PII Detector <https://huggingface.co/joneauxedgar/pasteproof-pii-detector-v2>`_
+(ModernBERT-base, F1 0.97) for NER-based PII detection across 27 entity types.
+Requires ``transformers >= 4.48.0`` for ModernBERT support.
+
+.. code-block:: python
+
+   from pytector import PIIScanner
+
+   scanner = PIIScanner()
+   has_pii, entities = scanner.scan("Email john@acme.com, SSN 123-45-6789")
+   print(scanner.redact("Email john@acme.com, SSN 123-45-6789"))
+
+   # Filter to specific entity types
+   scanner = PIIScanner(entity_types=["EMAIL", "CREDIT_CARD"], threshold=0.7)
+
+.. list-table:: PIIScanner Parameters
+   :widths: 20 20 60
+   :header-rows: 1
+
+   * - Parameter
+     - Type
+     - Description
+   * - model_name
+     - str
+     - Predefined key (``pasteproof-v3``) or HuggingFace model ID / local path
+   * - threshold
+     - float
+     - Minimum confidence for an entity to be reported (default 0.5)
+   * - entity_types
+     - list[str] | None
+     - Filter to specific types (e.g. ``["EMAIL", "SSN"]``); ``None`` = all
+
+.. admonition:: Citation
+
+   .. code-block:: text
+
+      @model{pasteproof_pii_detector,
+        author    = {Jonathan Edgar},
+        title     = {PasteProof PII Detector},
+        year      = {2025},
+        publisher = {Hugging Face},
+        url       = {https://huggingface.co/joneauxedgar/pasteproof-pii-detector-v2}
+      }
+
+ToxicityDetector
+----------------
+
+.. automodule:: pytector.toxicity
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Uses `citizenlab/distilbert-base-multilingual-cased-toxicity <https://huggingface.co/citizenlab/distilbert-base-multilingual-cased-toxicity>`_
+(F1-micro 0.94, 10 languages) for toxicity classification.
+
+.. code-block:: python
+
+   from pytector import ToxicityDetector
+
+   detector = ToxicityDetector()
+   is_toxic, score = detector.detect("You are terrible")
+   detector.report("Have a wonderful day!")
+
+.. list-table:: ToxicityDetector Parameters
+   :widths: 20 20 60
+   :header-rows: 1
+
+   * - Parameter
+     - Type
+     - Description
+   * - model_name
+     - str
+     - Predefined key (``citizenlab``) or HuggingFace model ID / local path
+   * - threshold
+     - float
+     - Score above which text is considered toxic (default 0.5)
+
+RegexScanner
+------------
+
+.. automodule:: pytector.regex_scanner
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Pure-stdlib rule-based scanner with customizable patterns.
+
+.. code-block:: python
+
+   from pytector import RegexScanner
+
+   scanner = RegexScanner()
+   has_match, matches = scanner.scan("Key: sk-live-abc123def456")
+   print(scanner.redact("Email user@example.com"))
+
+   # Custom patterns only
+   custom = RegexScanner(
+       patterns={"ORDER_ID": r"ORD-\d{8}"},
+       use_defaults=False,
+   )
+
+.. list-table:: RegexScanner Parameters
+   :widths: 20 20 60
+   :header-rows: 1
+
+   * - Parameter
+     - Type
+     - Description
+   * - patterns
+     - dict[str, str] | None
+     - ``{NAME: regex}`` mapping merged with defaults (or used alone)
+   * - use_defaults
+     - bool
+     - Whether to include built-in patterns (EMAIL, PHONE, SSN, CREDIT_CARD, IP_ADDRESS, API_KEY, JWT_TOKEN)

docs/examples.rst

@@ -304,6 +304,107 @@ Sanitize first, then run the detector for defence in depth:
    else:
        print(f"Safe: {cleaned}")
 
+PII Detection
+-------------
+
+Scan and redact personally identifiable information:
+
+.. code-block:: python
+
+   from pytector import PIIScanner
+
+   scanner = PIIScanner()
+
+   # Scan
+   has_pii, entities = scanner.scan("Contact john@acme.com, SSN 123-45-6789")
+   for ent in entities:
+       print(f"  [{ent['type']}] {ent['text']} (score={ent['score']:.2f})")
+
+   # Redact
+   print(scanner.redact("Contact john@acme.com, SSN 123-45-6789"))
+   # "Contact [REDACTED], SSN [REDACTED]"
+
+   # Report
+   scanner.report("Contact john@acme.com, SSN 123-45-6789")
+
+Filter to specific entity types:
+
+.. code-block:: python
+
+   scanner = PIIScanner(entity_types=["EMAIL", "CREDIT_CARD"])
+   has_pii, entities = scanner.scan("Email: a@b.com, SSN: 123-45-6789")
+   # Only EMAIL entities returned
+
+Custom threshold:
+
+.. code-block:: python
+
+   scanner = PIIScanner(threshold=0.9)
+   has_pii, entities = scanner.scan("john@acme.com")
+   # Only high-confidence entities
+
+Toxicity Detection
+------------------
+
+Classify text as toxic or non-toxic:
+
+.. code-block:: python
+
+   from pytector import ToxicityDetector
+
+   detector = ToxicityDetector()
+
+   is_toxic, score = detector.detect("You are terrible and worthless")
+   print(f"Toxic: {is_toxic}, Score: {score:.2f}")
+
+   # Adjust threshold per call
+   is_toxic, score = detector.detect("Mildly rude remark", threshold=0.8)
+
+   # Human-readable report
+   detector.report("Have a wonderful day!")
+
+Regex Scanner (Customizable)
+-----------------------------
+
+Fast rule-based scanning with full pattern customization:
+
+.. code-block:: python
+
+   from pytector import RegexScanner
+
+   # Default patterns: EMAIL, PHONE, SSN, CREDIT_CARD, IP_ADDRESS, API_KEY, JWT_TOKEN
+   scanner = RegexScanner()
+
+   has_match, matches = scanner.scan("Key: sk-live-abc123def456, IP: 10.0.0.1")
+   for m in matches:
+       print(f"  [{m['pattern_name']}] {m['match']}")
+
+   # Redact
+   print(scanner.redact("Email me at user@example.com"))
+
+Add and remove patterns at runtime:
+
+.. code-block:: python
+
+   scanner = RegexScanner()
+
+   scanner.add_pattern("AWS_ACCESS_KEY", r"AKIA[0-9A-Z]{16}")
+   scanner.add_pattern("INTERNAL_ID", r"INT-\d{6}")
+   scanner.remove_pattern("JWT_TOKEN")
+
+   print(scanner.get_patterns())
+
+Use only custom patterns (no defaults):
+
+.. code-block:: python
+
+   custom = RegexScanner(
+       patterns={"ORDER_ID": r"ORD-\d{8}", "ZIP": r"\b\d{5}(?:-\d{4})?\b"},
+       use_defaults=False,
+   )
+   has_match, matches = custom.scan("Order ORD-20260330, zip 90210")
+   print(custom.redact("Order ORD-20260330, zip 90210"))
+
 Error Handling
 --------------
 

docs/index.rst

@@ -21,6 +21,9 @@ Features
 * **Content Safety**: Support for Groq-hosted safeguard models for safety detection
 * **Keyword-Based Blocking**: Restrictive keyword filtering for immediate security control
 * **Input Sanitization**: Six-strategy pipeline to clean injection content from user input (encoding detection, unicode normalization, pattern removal, sentence scoring, fuzzy matching, keyword stripping) with zero additional dependencies
+* **PII Detection**: NER-based PII scanning using PasteProof PII Detector (ModernBERT, F1 0.97) covering 27 entity types — financial, credential, healthcare, GDPR, identity, contact, and address data
+* **Toxicity Detection**: Multilingual toxicity classification using citizenlab DistilBERT (F1 0.94, 10 languages)
+* **Regex Scanner**: Customizable rule-based pattern matching for PII and credentials (email, phone, SSN, credit card, IP, API keys, JWT) using pure Python stdlib
 * **Multiple Model Backends**: Support for Hugging Face Transformers and GGUF models
 * **Rapid Deployment**: Designed for quick integration into projects needing immediate security layers
 * **Configurable**: Customizable detection parameters, thresholds, and security policies