isomorphism 0.1.0__py3-none-any.whl

isomorphism/__init__.py

@@ -0,0 +1,8 @@
+"""Reversible anonymisation of Swiss personal data. Local only: no network, no telemetry."""
+
+from importlib.metadata import version
+
+from .core import Finding, Mapping, anonymize, detect, restore
+
+__version__ = version("isomorphism")
+__all__ = ["Finding", "Mapping", "__version__", "anonymize", "detect", "restore"]

isomorphism/_checks.py

@@ -0,0 +1,29 @@
+"""Check-digit algorithms. Pure functions on digit strings, no I/O."""
+
+from __future__ import annotations
+
+
+def ahv_ok(digits: str) -> bool:
+    """AHV number: 13 digits, prefix 756, EAN-13 check digit."""
+    if len(digits) != 13 or not digits.startswith("756"):
+        return False
+    total = sum(int(c) * (3 if i % 2 else 1) for i, c in enumerate(digits[:12]))
+    return (10 - total % 10) % 10 == int(digits[12])
+
+
+def iban_ok(compact: str) -> bool:
+    """ISO 13616 mod-97 on an IBAN without spaces."""
+    if len(compact) < 5 or not compact.isalnum():
+        return False
+    rearranged = compact[4:] + compact[:4]
+    return int("".join(str(int(c, 36)) for c in rearranged)) % 97 == 1
+
+
+def uid_ok(digits: str) -> bool:
+    """UID (CHE) number: 9 digits, mod-11 check digit with weights 5,4,3,2,7,6,5,4."""
+    if len(digits) != 9:
+        return False
+    check = (
+        11 - sum(int(c) * w for c, w in zip(digits[:8], (5, 4, 3, 2, 7, 6, 5, 4), strict=True)) % 11
+    )
+    return check != 10 and check % 11 == int(digits[8])

isomorphism/core.py

@@ -0,0 +1,115 @@
+"""anonymize / restore. The mapping holds real values: this module never logs or stores it."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from collections.abc import Mapping as AbstractMapping
+from dataclasses import dataclass, replace
+
+from .detectors import DETECTORS
+
+LANGS = frozenset({"de", "fr", "it", "en"})
+
+# Tolerant on restore: models sometimes change case or add spaces inside the brackets.
+_TOKEN = re.compile(r"\[\s*([A-Za-z]+)\s*_\s*(\d+)\s*\]")
+
+
+@dataclass(frozen=True, slots=True)
+class Finding:
+    """One hit for the audit log. Positions refer to the original text; the value is not kept."""
+
+    kind: str
+    start: int
+    end: int
+    confidence: float
+    detector: str
+    checksum_ok: bool | None = None
+    placeholder: str = ""
+
+
+class Mapping(dict[str, str]):
+    """placeholder -> real value, plus the findings. repr() hides the values."""
+
+    findings: list[Finding]
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.findings = []
+
+    def __repr__(self) -> str:
+        return f"Mapping(<{len(self)} placeholders, values hidden>)"
+
+
+def _check_lang(lang: str | None) -> None:
+    # shortcut: lang has no effect yet (the checksum recognisers are language-neutral);
+    # it selects context words once names and addresses arrive.
+    if lang is not None and lang.lower().split("-")[0] not in LANGS:
+        raise ValueError(f"unsupported lang {lang!r}, expected one of {sorted(LANGS)}")
+
+
+def detect(text: str, lang: str | None = None, *, keep: Iterable[str] = ()) -> list[Finding]:
+    """Find personal data. Overlaps go to the higher confidence, then the longer match.
+
+    ``keep``: exact values (case-insensitive) that must stay in the text.
+    """
+    _check_lang(lang)
+    kept = {k.casefold() for k in keep}
+    found = sorted(
+        (c for d in DETECTORS for c in d(text) if text[c.start : c.end].casefold() not in kept),
+        key=lambda c: (-c.confidence, c.start - c.end, c.start),
+    )
+    taken: list[tuple[int, int]] = []
+    out: list[Finding] = []
+    for c in found:
+        if all(c.end <= s or c.start >= e for s, e in taken):
+            taken.append((c.start, c.end))
+            out.append(Finding(c.kind, c.start, c.end, c.confidence, c.detector, c.checksum_ok))
+    return sorted(out, key=lambda f: f.start)
+
+
+def anonymize(
+    text: str, lang: str | None = None, *, keep: Iterable[str] = ()
+) -> tuple[str, Mapping]:
+    """Replace personal data by placeholders like ``[AHV_1]``.
+
+    Identical values get the same placeholder. Returns ``(text, mapping)``; the mapping has
+    the real values and a ``findings`` list. Storing the mapping is up to the caller.
+    """
+    # Never reuse a placeholder that already stands in the text.
+    in_text = {_name(m) for m in _TOKEN.finditer(text)}
+    mapping = Mapping()
+    by_value: dict[tuple[str, str], str] = {}
+    counters: dict[str, int] = {}
+    parts: list[str] = []
+    pos = 0
+    for f in detect(text, lang, keep=keep):
+        value = text[f.start : f.end]
+        ph = by_value.get((f.kind, value))
+        if ph is None:
+            n = counters.get(f.kind, 0)
+            while True:
+                n += 1
+                ph = f"[{f.kind}_{n}]"
+                if ph not in in_text:
+                    break
+            counters[f.kind] = n
+            by_value[(f.kind, value)] = ph
+            mapping[ph] = value
+        mapping.findings.append(replace(f, placeholder=ph))
+        parts += (text[pos : f.start], ph)
+        pos = f.end
+    parts.append(text[pos:])
+    return "".join(parts), mapping
+
+
+def _name(m: re.Match[str]) -> str:
+    return f"[{m[1].upper()}_{int(m[2])}]"
+
+
+def restore(text: str, mapping: AbstractMapping[str, str]) -> str:
+    """Put the real values back. Single pass, so restored values are never rescanned.
+
+    Unknown placeholders stay unchanged.
+    """
+    return _TOKEN.sub(lambda m: mapping.get(_name(m), m[0]), text)

isomorphism/detectors.py

@@ -0,0 +1,85 @@
+"""Swiss recognisers. Each yields candidates; overlaps are resolved in core."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass, replace
+
+from ._checks import ahv_ok, iban_ok, uid_ok
+
+
+@dataclass(frozen=True, slots=True)
+class Candidate:
+    kind: str
+    start: int
+    end: int
+    confidence: float
+    detector: str
+    checksum_ok: bool | None = None
+
+
+def _digits(s: str) -> str:
+    return "".join(c for c in s if c.isdigit())
+
+
+def _checked(
+    kind: str,
+    detector: str,
+    pattern: re.Pattern[str],
+    ok: Callable[[str], bool],
+    clean: Callable[[str], str],
+    text: str,
+    valid: float,
+    invalid: float,
+) -> Iterator[Candidate]:
+    # Invalid check digits are still reported, with lower confidence (better too many than too few).
+    for m in pattern.finditer(text):
+        good = ok(clean(m[0]))
+        yield Candidate(kind, m.start(), m.end(), valid if good else invalid, detector, good)
+
+
+_AHV = re.compile(r"(?<!\d)756[ .\-]?\d{4}[ .\-]?\d{4}[ .\-]?\d{2}(?!\d)")
+_IBAN = re.compile(r"(?<![A-Za-z0-9])(?:CH|LI)\d{2}(?: ?[0-9A-Z]){17}(?![A-Za-z0-9])", re.I)
+_UID = re.compile(r"(?<![A-Za-z0-9])CHE[- ]?\d{3}[. ]?\d{3}[. ]?\d{3}(?!\d)", re.I)
+_EMAIL = re.compile(r"(?<![\w.+\-])[\w.+\-]+@[\w\-]+(?:\.[\w\-]+)*\.[^\W\d_]{2,}")
+_PHONE = re.compile(
+    r"""(?<![\w+])(?<!\d[ .\-/])
+    (?:(?:\+|00)41[ .\-]?(?:\(0\)[ .\-]?)?|\(?0)
+    [1-9]\d\)?
+    [ .\-/]?\d{3}[ .\-]?\d{2}[ .\-]?\d{2}(?!\d)""",
+    re.X,
+)
+
+
+def ahv(text: str) -> Iterator[Candidate]:
+    for c in _checked("AHV", "ahv-ean13", _AHV, ahv_ok, _digits, text, 0.99, 0.6):
+        if "." not in text[c.start : c.end]:  # bare digits are weaker evidence than the dotted form
+            c = replace(c, confidence=0.9 if c.checksum_ok else 0.4)
+        yield c
+
+
+def iban(text: str) -> Iterator[Candidate]:
+    yield from _checked(
+        "IBAN", "iban-mod97", _IBAN, iban_ok, lambda s: s.replace(" ", "").upper(), text, 0.99, 0.6
+    )
+
+
+def uid(text: str) -> Iterator[Candidate]:
+    yield from _checked("UID", "uid-mod11", _UID, uid_ok, _digits, text, 0.98, 0.6)
+
+
+def email(text: str) -> Iterator[Candidate]:
+    for m in _EMAIL.finditer(text):
+        yield Candidate("EMAIL", m.start(), m.end(), 0.95, "email-regex")
+
+
+def phone(text: str) -> Iterator[Candidate]:
+    for m in _PHONE.finditer(text):
+        s = m[0]
+        international = s.startswith(("+", "00"))
+        confidence = 0.95 if international else 0.85 if not s.isdigit() else 0.6
+        yield Candidate("PHONE", m.start(), m.end(), confidence, "phone-ch")
+
+
+DETECTORS: tuple[Callable[[str], Iterator[Candidate]], ...] = (ahv, iban, uid, email, phone)

isomorphism-0.1.0.dist-info/METADATA

@@ -0,0 +1,94 @@
+Metadata-Version: 2.5
+Name: isomorphism
+Version: 0.1.0
+Summary: Reversible anonymisation of Swiss personal data (AHV, IBAN, UID, phone, email) before text goes to a language model. Fully local, no dependencies.
+Project-URL: Homepage, https://packages.sweber.dev/isomorphism
+Project-URL: Documentation, https://packages.sweber.dev/isomorphism/docs
+Project-URL: Repository, https://github.com/Weber-Development/isomorphism
+Project-URL: Changelog, https://github.com/Weber-Development/isomorphism/blob/main/CHANGELOG.md
+Author: Seya Weber
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ahv,anonymization,dsg,iban,llm,pii,privacy,pseudonymization,switzerland
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# isomorphism
+
+Reversible anonymisation of Swiss personal data for Python. It replaces AHV numbers, IBANs, UID numbers, phone numbers and email addresses with placeholders before a text goes to a language model, and puts the real values back into the answer.
+
+- **Local only.** No network calls, no telemetry, no dependencies, nothing downloaded at runtime.
+- **Reversible.** `anonymize(text)` returns the text with placeholders and a mapping, `restore(text, mapping)` undoes it.
+- **Same value, same placeholder.** The model can follow that `[AHV_1]` appears three times.
+- **Checksums.** AHV (EAN-13), IBAN (mod 97) and UID (mod 11) are verified. Numbers that look right but fail the check are reported anyway, with lower confidence.
+- **Audit-friendly.** Every hit comes back as kind, position, confidence and recogniser, without the value.
+
+Python 3.12 or newer. MIT license.
+
+```sh
+pip install isomorphism
+```
+
+```python
+from isomorphism import anonymize, restore
+
+text = "Anna Muster, AHV 756.1234.5678.97, IBAN CH93 0076 2011 6238 5295 7, Tel. 071 123 45 67"
+safe, mapping = anonymize(text, lang="de")
+# 'Anna Muster, AHV [AHV_1], IBAN [IBAN_1], Tel. [PHONE_1]'
+
+answer = call_your_model(safe)  # the model only sees placeholders
+print(restore(answer, mapping))  # real values are back
+```
+
+The mapping holds the real values. This package never logs or stores it; keeping it (in memory, per request) is up to you. `repr(mapping)` shows only the number of placeholders.
+
+## What it finds
+
+| Kind | Placeholder | Formats | Check |
+|---|---|---|---|
+| AHV number | `[AHV_n]` | `756.1234.5678.97`, with spaces or without separators | prefix 756, EAN-13 |
+| IBAN (CH, LI) | `[IBAN_n]` | with or without spaces, upper or lower case | mod 97 |
+| UID number | `[UID_n]` | `CHE-123.456.788`, `CHE123456788`; `MWST`/`TVA`/`IVA`/`HR` stay in the text | mod 11 |
+| Phone (Switzerland) | `[PHONE_n]` | `+41 71 123 45 67`, `0041 …`, `+41 (0)71 …`, `071 123 45 67`, `071/123 45 67`, `(071) …`, `0711234567` | format |
+| Email | `[EMAIL_n]` | | format |
+
+`detect(text)` returns the hits without changing the text. Passing `keep=["info@gemeinde.example"]` leaves exact values untouched (case-insensitive), for example the address of an authority.
+
+## Measured on the test cases
+
+`tests/cases.py` holds invented Swiss texts (payslip extract, client email, receipt, tax query, French and Italian letters, written-out variants, numbers with wrong check digits, and a text full of look-alikes that must not match). The numbers below come from `python -m tests.measure`, and a test fails if they are out of date or if a listed value slips through.
+
+<!-- measure:start -->
+| Kind | Expected | Found | Missed | False alarms |
+|---|---|---|---|---|
+| AHV | 10 | 10 | 0 | 0 |
+| IBAN | 10 | 10 | 0 | 0 |
+| UID | 9 | 9 | 0 | 0 |
+| PHONE | 15 | 15 | 0 | 0 |
+| EMAIL | 6 | 6 | 0 | 0 |
+<!-- measure:end -->
+
+This is a small invented set, not a benchmark on real documents. Read it as a regression guard, and test with your own (invented) samples before you rely on it.
+
+## Not in this version
+
+Personal names, postal addresses, company names, dates of birth, account and card numbers, and restoring a streamed answer arrive in the next version. Until then names and addresses stay in the text. `lang` ("de", "fr", "it", "en") is accepted and checked already but has no effect yet. Foreign IBANs and the old 11-digit AHV format are not recognised.
+
+No tool finds all personal data. Treat the result as one protective layer, not as a guarantee of anonymity.
+
+## Development
+
+```sh
+uv venv && uv pip install -e . pytest ruff mypy
+ruff check . && ruff format --check . && mypy && pytest
+```
+
+Docs: <https://packages.sweber.dev/isomorphism/docs>

isomorphism-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+isomorphism/__init__.py,sha256=T8_xkinGuGhYmu3TuRRyFaoNprtMlHLAOXqrgtBTut0,317
+isomorphism/_checks.py,sha256=jk1ziyCxfEqlDCfFwpNZcTgyxYwXZqdIIiZg-DnjiBw,1041
+isomorphism/core.py,sha256=Ci6Vwh7WlSW8XftZ87R0E3xi0UCYVYcap4B_YBhc-Kk,3944
+isomorphism/detectors.py,sha256=ijxEpzXUbUu_LKGjEYsQSaY9gxc4gWT2DzGSJyYkG50,2699
+isomorphism/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+isomorphism-0.1.0.dist-info/METADATA,sha256=0S9Bvtwe-wfMfhTq9mcMYvlKjwXtoUfXVsbDpXuObgM,4798
+isomorphism-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+isomorphism-0.1.0.dist-info/licenses/LICENSE,sha256=QFF5JWsp6cFDT2lWuxtdGEbj3QbvysjcM5Rj15Prk2U,1061
+isomorphism-0.1.0.dist-info/RECORD,,

isomorphism-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

isomorphism-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Seya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.