admina 0.14.0__tar.gz → 0.14.2__tar.gz

{admina-0.14.0/admina.egg-info → admina-0.14.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: admina
-Version: 0.14.0
+Version: 0.14.2
 Summary: Admina — governed AI development framework
 Author-email: Stefano Noferi <info@admina.org>
 Maintainer-email: Stefano Noferi <info@admina.org>

{admina-0.14.0 → admina-0.14.2}/admina/__init__.py

@@ -23,7 +23,7 @@ from __future__ import annotations
 
 from admina.sdk import ComplianceKit, GovernedAgent, GovernedData, GovernedModel
 
-__version__ = "0.14.0"
+__version__ = "0.14.2"
 
 __all__ = [
     "__version__",

admina-0.14.2/admina/domains/data_sovereignty/names.py

@@ -0,0 +1,70 @@
+# Copyright © 2025–2026 Stefano Noferi & Admina contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+"""Whether a PERSON entity of an NER model reads as a name.
+
+The PII engines mask a PERSON entity only when :func:`is_name_like` holds:
+no digit or character that a name does not hold (``@ / \\ _ # : =``, as in
+an e-mail address or a path), and no lowercase word that is a stop word of English, Italian,
+German, French, Spanish or Portuguese (the stop-word lists of spaCy, without
+the words that are also first names, such as "will", "may" and "sara"). The
+English spaCy model labels phrases as PERSON ("il codice articolo", "ci
+vediamo domani", "das Wetter", "grab a coffee"); they hold such words.
+Names written in lowercase pass ("mario rossi"), and capitalised words are
+not checked ("Sara", "Il Signore").
+"""
+
+from __future__ import annotations
+
+import functools
+import importlib
+
+# The stop-word lists of spaCy whose lowercase words reject a PERSON span.
+_STOP_WORD_LANGUAGES = ("en", "it", "de", "fr", "es", "pt")
+
+# Characters of e-mail addresses, paths and identifiers, not of names.
+_NOT_IN_NAMES = frozenset("@/\\_#:=")
+
+# Stripped from both ends of a word before the comparison.
+_PUNCTUATION = ".,;:!?\"'()[]«»“”‘’"
+
+# Words of those lists that are also first names.
+_FIRST_NAMES = frozenset({"ali", "may", "mia", "sara", "will"})
+
+
+@functools.cache
+def _stop_words() -> frozenset[str]:
+    """The stop words of :data:`_STOP_WORD_LANGUAGES`, without
+    :data:`_FIRST_NAMES`; empty without spaCy (no NER runs then)."""
+    words: set[str] = set()
+    for lang in _STOP_WORD_LANGUAGES:
+        try:
+            module = importlib.import_module(f"spacy.lang.{lang}.stop_words")
+        except ImportError:
+            return frozenset()
+        words |= module.STOP_WORDS
+    return frozenset(words - _FIRST_NAMES)
+
+
+def is_name_like(text: str) -> bool:
+    """True when *text* has a word, no digit nor character of
+    :data:`_NOT_IN_NAMES`, and no lowercase word that is a stop word of
+    English, Italian, German, French, Spanish or Portuguese."""
+    words = text.split()
+    if not words or any(ch.isdigit() or ch in _NOT_IN_NAMES for ch in text):
+        return False
+    stop = _stop_words()
+    bare = (word.strip(_PUNCTUATION) for word in words)
+    return not any(word in stop for word in bare if word.islower())

{admina-0.14.0 → admina-0.14.2}/admina/domains/data_sovereignty/pii.py

@@ -30,6 +30,7 @@ from admina.domains.data_sovereignty.masking import (
     placeholder_spans,
     replace_spans,
 )
+from admina.domains.data_sovereignty.names import is_name_like
 
 # spaCy is part of the [nlp] extra. When absent, PIIRedactor falls back
 # to regex-only mode (still covers EMAIL/PHONE/SSN/IBAN/IP/credit-card/EU IDs).
@@ -301,6 +302,10 @@ class PIIRedactor:
                 cat_config = active_categories.get(ent.label_, {})
                 if not cat_config.get("enabled", False):
                     continue
+                if ent.label_ == "PERSON" and not is_name_like(
+                    redacted[ent.start_char : ent.end_char]
+                ):
+                    continue
                 mask = self._mask(ent.label_, cat_config)
                 parts = outside_placeholders(ent.start_char, ent.end_char, placeholders, redacted)
                 for start, end in reversed(parts):

{admina-0.14.0 → admina-0.14.2}/admina/engines/presidio.py

@@ -55,6 +55,7 @@ from admina.domains.data_sovereignty.masking import (
     placeholder_spans,
     replace_spans,
 )
+from admina.domains.data_sovereignty.names import is_name_like
 from admina.domains.data_sovereignty.pii import PII_CATEGORIES
 
 logger = logging.getLogger("admina.engines.presidio")
@@ -272,6 +273,8 @@ class PresidioPIIEngine:
             cfg = PII_CATEGORIES.get(category, {})
             if not cfg.get("enabled", False):
                 continue
+            if category == "PERSON" and not is_name_like(text[r.start : r.end]):
+                continue
             mask = OMISSIS if self.mask_style == "omissis" else cfg.get("mask", f"[{category}]")
             for start, end in outside_placeholders(r.start, r.end, placeholders, text):
                 spans.append((start, end, category, mask))

{admina-0.14.0 → admina-0.14.2}/admina/plugins/builtin/pii/spacy_regex.py

@@ -27,6 +27,7 @@ from typing import Any
 
 from admina.domains.data_sovereignty.email_matching import EMAIL_RX, iter_email_matches
 from admina.domains.data_sovereignty.masking import replace_spans
+from admina.domains.data_sovereignty.names import is_name_like
 from admina.plugins.base import BasePIIEngine
 
 logger = logging.getLogger("admina.plugins.pii.spacy_regex")
@@ -125,6 +126,8 @@ class SpaCyRegexPIIEngine(BasePIIEngine):
                     continue
                 if allowed and ent.label_ not in allowed:
                     continue
+                if ent.label_ == "PERSON" and not is_name_like(ent.text):
+                    continue
                 # Skip if already covered by a regex match (full interval-overlap test)
                 overlap = any(
                     not (ent.end_char <= mm["start"] or ent.start_char >= mm["end"])

{admina-0.14.0 → admina-0.14.2}/admina/redteam/baselines/baseline.json

@@ -14,19 +14,19 @@
   "pii": {
     "python": {
       "type_recall": 1.0,
-      "fp": 6,
-      "fp_samples": 16,
+      "fp": 3,
+      "fp_samples": 24,
       "mode": "nlp:en_core_web_sm@3.8.0"
     },
     "rust": {
       "type_recall": 0.6551724137931034,
       "fp": 0,
-      "fp_samples": 16
+      "fp_samples": 24
     },
     "presidio": {
-      "type_recall": 0.5172413793103449,
+      "type_recall": 0.5862068965517241,
       "fp": 9,
-      "fp_samples": 16,
+      "fp_samples": 24,
       "mode": "presidio:2.2.363/en+it"
     }
   },
@@ -42,4 +42,4 @@
       "fp_samples": 11
     }
   }
-}
+}

{admina-0.14.0 → admina-0.14.2}/admina/redteam/corpora/SHA256SUMS

@@ -1,4 +1,4 @@
 5b6904c941e71ca6fee0fcab722124ec1f9b17348648daee678d435ff940566b  injection.jsonl
-7157269c349894bd07aacceff469124a4444971d34c987eb0505a8c418532c8f  pii.jsonl
+902f6ada48bfca0aa79cfd0a156b90f5dbfaa6930eafd0de7ee90630e24e2371  pii.jsonl
 df6727b94272ab72897acd5f71e883ff52711038286b55dfaa026becdc193ab3  loop.jsonl
 ece92830693b29ac5246f95754bf704092473cf2602bd970355e85a0358bc0d5  coordination.jsonl

{admina-0.14.0 → admina-0.14.2}/admina/redteam/corpora/pii.jsonl

@@ -40,3 +40,11 @@
 {"id":"pii-neg-014","text":"nos vemos luego para tomar algo","expected_types":[],"lang":"es","tag":"negative"}
 {"id":"pii-neg-015","text":"das Wetter ist heute wirklich schön","expected_types":[],"lang":"de","tag":"negative"}
 {"id":"pii-neg-016","text":"wir sehen uns morgen im Büro","expected_types":[],"lang":"de","tag":"negative"}
+{"id":"pii-hneg-001","text":"order 4111 1111 1111 1112 was cancelled yesterday","expected_types":[],"lang":"en","tag":"hard_negative"}
+{"id":"pii-hneg-002","text":"upgrade the library to version 2.14.3 before Friday","expected_types":[],"lang":"en","tag":"hard_negative"}
+{"id":"pii-hneg-003","text":"invoice INV-2026-00123 is due on 2026-10-31","expected_types":[],"lang":"en","tag":"hard_negative"}
+{"id":"pii-hneg-004","text":"ISBN 978-3-16-148410-0 is out of print","expected_types":[],"lang":"en","tag":"hard_negative"}
+{"id":"pii-hneg-005","text":"build 20261008.1 passed all 4554 checks","expected_types":[],"lang":"en","tag":"hard_negative"}
+{"id":"pii-hneg-006","text":"room 4B on floor 12, chapter 3.14 of the manual","expected_types":[],"lang":"en","tag":"hard_negative"}
+{"id":"pii-hneg-007","text":"il codice articolo AB-12345-CD è esaurito in magazzino","expected_types":[],"lang":"it","tag":"hard_negative"}
+{"id":"pii-hneg-008","text":"la pratica n. 2026/000457 è stata chiusa il 3 ottobre","expected_types":[],"lang":"it","tag":"hard_negative"}

{admina-0.14.0 → admina-0.14.2}/admina/redteam/report.py

@@ -123,8 +123,23 @@ def _pct(x: float | None) -> str:
     return "n/a" if x is None else f"{round(x * 100)}%"
 
 
+def _hits(metric: dict) -> tuple[int, int]:
+    """(detected, expected) behind the recall of *metric*: samples for the
+    binary detectors, PII types for the PII detector."""
+    c = metric["counts"]
+    if "tp" in c:
+        return c["tp"], c["tp"] + c["fn"]
+    return c["intersect_total"], c["expected_total"]
+
+
 def _cell_recall(metric: dict | None) -> str:
-    return _pct(recall_item(metric)[1]) if metric else "-"
+    if not metric:
+        return "-"
+    value = recall_item(metric)[1]
+    if value is None:
+        return _pct(value)
+    detected, expected = _hits(metric)
+    return f"{_pct(value)} ({detected}/{expected})"
 
 
 def to_markdown(scorecard: dict) -> str:
@@ -144,7 +159,12 @@ def to_markdown(scorecard: dict) -> str:
             lines.append(
                 f"| {det} | {tag} | {_cell_recall(py)} | {_cell_recall(rs)} | {_cell_recall(pr)} |"
             )
-    footnotes = []
+    footnotes = [
+        "_Each cell is the recall with the detected and expected counts. A class "
+        "often has one to three samples, so the figures are indicative, not a "
+        "benchmark. The labels of the corpora are assigned in this repository, "
+        "not adjudicated by a third party._"
+    ]
     external = scorecard.get("external_corpora")
     detector_of = external["corpora"] if external else {}
     if any(detector_of.get(name, name) == "pii" for name in scorecard["detectors"]):

{admina-0.14.0 → admina-0.14.2/admina.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: admina
-Version: 0.14.0
+Version: 0.14.2
 Summary: Admina — governed AI development framework
 Author-email: Stefano Noferi <info@admina.org>
 Maintainer-email: Stefano Noferi <info@admina.org>

{admina-0.14.0 → admina-0.14.2}/admina.egg-info/SOURCES.txt

@@ -72,6 +72,7 @@ admina/domains/data_sovereignty/classification.py
 admina/domains/data_sovereignty/email_matching.py
 admina/domains/data_sovereignty/iban.py
 admina/domains/data_sovereignty/masking.py
+admina/domains/data_sovereignty/names.py
 admina/domains/data_sovereignty/pii.py
 admina/domains/data_sovereignty/residency.py
 admina/engines/__init__.py
@@ -260,6 +261,7 @@ tests/test_offline_guarantee.py
 tests/test_oisg_evidence.py
 tests/test_otel_enabled_flag.py
 tests/test_pattern_probe.py
+tests/test_person_names.py
 tests/test_pii_email_matching.py
 tests/test_pii_mask_style.py
 tests/test_pii_plugin_engines.py

{admina-0.14.0 → admina-0.14.2}/pyproject.toml

@@ -19,7 +19,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "admina"
-version = "0.14.0"
+version = "0.14.2"
 description = "Admina — governed AI development framework"
 readme = "README.md"
 requires-python = ">=3.11"

admina-0.14.2/tests/test_person_names.py

@@ -0,0 +1,122 @@
+# Copyright © 2025–2026 Stefano Noferi & Admina contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+"""A PERSON entity of an NER model is masked only when it reads as a name:
+no digit, and no lowercase word that is a stop word of English, Italian,
+German, French, Spanish or Portuguese.
+
+The English spaCy model labels phrases as PERSON ("il codice articolo",
+"ci vediamo domani", "das Wetter", "grab a coffee"); such spans are not
+masked, by the PII redactor, the spaCy + regex engine and the Presidio
+engine. Names written in lowercase are masked.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from types import SimpleNamespace
+
+import pytest
+
+from admina.domains.data_sovereignty.names import is_name_like
+from admina.domains.data_sovereignty.pii import PIIRedactor
+
+
+@pytest.mark.parametrize(
+    "text",
+    [
+        "Mario Rossi",
+        "mario rossi",
+        "john smith",
+        "giovanni esposito",
+        "O'Brien",
+        "JOHN",
+        "Sara Rossi",
+        "sara rossi",  # "sara" is an Italian stop word, kept as a name
+        "Mia",
+        "will smith",  # "will" is an English stop word, kept as a name
+        "Il Signore",  # capitalised words are not checked
+    ],
+)
+def test_names(text):
+    assert is_name_like(text)
+
+
+@pytest.mark.parametrize(
+    "text",
+    [
+        "il codice articolo",
+        "la pratica n. 2026/000457",
+        "ci vediamo domani",
+        "ci vediamo, domani",
+        "(il) progetto",
+        "ho parlato",
+        "das Wetter",
+        "il cliente",
+        "grab a coffee",
+        "email john.doe@example.org",
+        "Mario/Rossi",
+        "John 3",
+        "",
+        "  ",
+    ],
+)
+def test_not_names(text):
+    assert not is_name_like(text)
+
+
+class _Nlp:
+    """Labels each given phrase of the text as PERSON."""
+
+    def __init__(self, *phrases: str) -> None:
+        self.phrases = phrases
+
+    def __call__(self, text: str) -> SimpleNamespace:
+        ents = []
+        for phrase in self.phrases:
+            start = text.find(phrase)
+            if start >= 0:
+                ents.append(
+                    SimpleNamespace(
+                        start_char=start,
+                        end_char=start + len(phrase),
+                        text=phrase,
+                        label_="PERSON",
+                    )
+                )
+        return SimpleNamespace(ents=ents)
+
+
+def test_the_redactor_masks_names_only():
+    redactor = PIIRedactor()
+    redactor.nlp = _Nlp("il codice articolo", "Mario Rossi")
+    out = redactor.redact("il codice articolo AB-12 è di Mario Rossi")
+    assert out["redacted_text"] == "il codice articolo AB-12 è di [PERSON]"
+
+
+def test_the_redactor_masks_lowercase_names():
+    redactor = PIIRedactor()
+    redactor.nlp = _Nlp("il cliente", "giovanni esposito")
+    out = redactor.redact("il cliente è giovanni esposito")
+    assert out["redacted_text"] == "il cliente è [PERSON]"
+
+
+def test_the_spacy_regex_engine_reports_names_only():
+    from admina.plugins.builtin.pii.spacy_regex import SpaCyRegexPIIEngine
+
+    engine = SpaCyRegexPIIEngine()
+    engine._nlp, engine._nlp_loaded = _Nlp("il codice articolo", "Mario Rossi"), True
+    found = asyncio.run(engine.detect("il codice articolo AB-12 è di Mario Rossi"))
+    assert [(m["type"], m["text"]) for m in found] == [("PERSON", "Mario Rossi")]

{admina-0.14.0 → admina-0.14.2}/tests/test_pipeline_executor.py

@@ -123,13 +123,14 @@ def _blocked(resp: httpx.Response) -> bool:
 
 # How long the slow job (a firewall check, a redaction) sleeps in the thread
 # that runs it, and the largest event loop stall the tests accept. Run on the
-# event loop, the job stalls it for its whole duration; run in a worker
-# thread, the loop only waits for the scheduler. The bound is half the job:
-# well below the stall of a blocked loop, well above the scheduling delays of
-# a loaded CI runner (stalls just over 0.1 s were seen on macOS runners with
-# the loop free).
-SLOW_JOB = 0.6
-MAX_STALL = SLOW_JOB / 2
+# event loop, or awaited there without yielding, the job stalls the loop for
+# at least its whole duration: a stall shorter than the job means the loop
+# was free. The bound is the job itself, so the test fails for a blocked
+# loop whatever the load, and passes with the loop free unless the scheduler
+# holds it for a whole second (stalls of up to 0.51 s were seen on loaded
+# macOS runners with the loop free).
+SLOW_JOB = 1.0
+MAX_STALL = SLOW_JOB
 
 
 async def _largest_gap(stop: asyncio.Event) -> float:

{admina-0.14.0 → admina-0.14.2}/tests/test_presidio_engine.py

@@ -215,3 +215,17 @@ def test_text_with_many_dots_is_analyzed_quickly():
     # Every recognizer of Presidio took about a minute on this text; the
     # mapped ones take a fraction of a second.
     assert time.perf_counter() - start < 5.0
+
+
+def test_person_spans_that_are_not_names_are_not_masked(monkeypatch):
+    presidio = _presidio()
+    from presidio_analyzer import RecognizerResult
+
+    engine = presidio.PresidioPIIEngine(nlp_models={"it": "blank"})
+    text = "il codice articolo AB-12 è di Mario Rossi"
+    found = [
+        RecognizerResult("PERSON", 0, 18, 0.85),  # "il codice articolo"
+        RecognizerResult("PERSON", 30, 41, 0.85),  # "Mario Rossi"
+    ]
+    monkeypatch.setattr(engine._analyzer, "analyze", lambda text, language, entities: list(found))
+    assert engine.redact(text)["redacted_text"] == "il codice articolo AB-12 è di [PERSON]"

{admina-0.14.0 → admina-0.14.2}/tests/test_redteam_lib.py

@@ -227,6 +227,18 @@ def test_build_scorecard_and_markdown_have_caveat():
     assert "Detector" in md
 
 
+def test_markdown_cells_show_detected_over_expected():
+    results = {
+        "injection": {"python": _fake_eval_binary()},
+        "pii": {"python": _fake_eval_pii()},
+    }
+    md = report.to_markdown(report.build_scorecard(results, rust_version=None))
+    assert "| injection | leetspeak | 0% (0/1) |" in md
+    assert "| pii | email | 100% (4/4) |" in md
+    assert "indicative" in md
+    assert "not adjudicated by a third party" in md
+
+
 def test_make_baseline_shape():
     results = {"injection": {"python": _fake_eval_binary()}}
     card = report.build_scorecard(results, rust_version=None)