isomorphism 0.1.0__tar.gz

isomorphism-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv venv --python ${{ matrix.python }}
+      - run: uv pip install -e . pytest ruff mypy
+      - run: .venv/bin/ruff check .
+      - run: .venv/bin/ruff format --check .
+      - run: .venv/bin/mypy
+      - run: .venv/bin/pytest -q

isomorphism-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,38 @@
+name: Release
+
+# Tag v<version> -> tests, build, publish to PyPI (trusted publishing, no token in the repo).
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Tag matches pyproject version
+        run: test "v$(grep -m1 '^version' pyproject.toml | cut -d'"' -f2)" = "${GITHUB_REF_NAME}"
+      - run: uv venv && uv pip install -e . pytest ruff mypy
+      - run: .venv/bin/ruff check . && .venv/bin/mypy && .venv/bin/pytest -q
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

isomorphism-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

isomorphism-0.1.0/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0
+
+First release.
+
+- Recognisers for AHV numbers (EAN-13), IBANs of Switzerland and Liechtenstein (mod 97), UID numbers (mod 11), Swiss phone numbers and email addresses.
+- `anonymize(text, lang=None, keep=())` returns the text with placeholders and a mapping; `restore(text, mapping)` reverses it; `detect(text)` returns the hits only.
+- Same value, same placeholder. Findings carry kind, position, confidence, recogniser and checksum result, never the value.
+- Invented test texts in German, French, Italian and English with hit rate and false alarms per kind.

isomorphism-0.1.0/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.

isomorphism-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,71 @@
+# 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/RELEASE_CHECKLIST.md

@@ -0,0 +1,22 @@
+# Release checklist (package-launch)
+
+| Item | Status |
+|---|---|
+| Repo `Weber-Development/isomorphism` | private; make it public before docs can render (read from GitHub) |
+| PyPI `isomorphism` 0.1.0 | waits for the PyPI account and a trusted publisher (see below) |
+| packages.sweber.dev | entry, docs config, demo, blog post: sxwxbxr/portfoliov3 PR |
+| Pro | not planned for 0.1; core is MIT |
+| Polar | not needed (free only) |
+
+## Publishing (Seya)
+
+1. Create the PyPI account (2FA on) if there is none.
+2. On pypi.org: Your projects, Publishing, **Add a new pending publisher**: project `isomorphism`,
+   owner `Weber-Development`, repository `isomorphism`, workflow `release.yml`, environment `pypi`.
+3. In GitHub, repo Settings, Environments: create `pypi`.
+4. Tag `v0.1.0` on `main` (the Release workflow builds, tests and publishes). No token is stored anywhere.
+
+## Next version (0.2.0)
+
+Names, addresses, company names, dates of birth, account and card numbers, streaming `restore`,
+optional Presidio backend for names in running text.

isomorphism-0.1.0/docs/getting-started.md

@@ -0,0 +1,40 @@
+---
+title: Getting started
+description: Install Isomorphism, anonymise a text, call a model and restore the answer.
+---
+
+```sh
+pip install isomorphism
+```
+
+Python 3.12 or newer.
+
+## Anonymise and restore
+
+```python
+from isomorphism import anonymize, restore
+
+text = "AHV 756.1234.5678.97, IBAN CH93 0076 2011 6238 5295 7, UID CHE-123.456.788 MWST"
+safe, mapping = anonymize(text, lang="de")
+print(safe)  # AHV [AHV_1], IBAN [IBAN_1], UID [UID_1] MWST
+
+answer = call_your_model(safe)
+print(restore(answer, mapping))
+```
+
+Keep the mapping for as long as the request runs, for example in a variable or your request context. If you need to keep it longer, `dict(mapping)` gives you a plain dictionary to store. The package never writes it anywhere.
+
+## Keep some values
+
+```python
+safe, mapping = anonymize(text, keep=["info@gemeinde.example"])
+```
+
+## Audit log
+
+```python
+for f in mapping.findings:
+    print(f.kind, f.start, f.end, f.confidence, f.detector, f.checksum_ok)
+```
+
+Positions refer to the original text. The findings contain no values, so they are safe to log.

isomorphism-0.1.0/docs/introduction.md

@@ -0,0 +1,21 @@
+---
+title: Why Isomorphism
+description: Replace Swiss personal data with placeholders before a model call and restore it afterwards, fully local.
+---
+
+A language model does not need to know a client's AHV number, IBAN or phone number to summarise a letter or answer a question about it. Isomorphism replaces such values with placeholders like `[AHV_1]` before the text leaves your system, and puts the real values back into the answer.
+
+- **Swiss formats first.** AHV numbers, IBANs of Switzerland and Liechtenstein, UID numbers, Swiss phone numbers and email addresses, with the check digits that Swiss documents carry.
+- **Reversible.** The same value always gets the same placeholder, so the model can follow who is meant. `restore` swaps the real values back in.
+- **Local.** Pure Python, no dependencies, no network calls, no telemetry. The mapping with the real values never leaves your process unless you send it somewhere.
+- **Audit-friendly.** Each hit reports kind, position, confidence and recogniser, never the value.
+
+## Limits
+
+Isomorphism recognises patterns. It does not understand context, and it cannot promise that a text is free of personal data. Names and postal addresses are not recognised in this version. See [Legal notes](legal.md).
+
+## Packages
+
+| Package | License | Content |
+|---|---|---|
+| `isomorphism` (PyPI) | MIT | Recognisers, `anonymize`, `restore`, `detect` |

isomorphism-0.1.0/docs/legal.md

@@ -0,0 +1,12 @@
+---
+title: Legal notes
+description: What Isomorphism does and does not promise.
+---
+
+Isomorphism is a technical tool. It does not provide legal advice, and using it does not by itself make a processing operation compliant with the Swiss Federal Act on Data Protection (FADP/DSG), the GDPR or professional secrecy rules.
+
+- Recognition is pattern based. A value written in an unusual way, or a kind of data the version does not cover yet, stays in the text.
+- Placeholders replace values, but the surrounding text can still identify a person.
+- The mapping contains the real values. Treat it as personal data.
+
+You remain responsible for what you send to a model.

isomorphism-0.1.0/docs/nav.json

@@ -0,0 +1,7 @@
+{
+  "sections": [
+    { "label": "Start", "items": ["introduction", "getting-started"] },
+    { "label": "Reference", "items": ["reference/api", "reference/recognisers"] },
+    { "label": "Legal", "items": ["legal"] }
+  ]
+}

isomorphism-0.1.0/docs/reference/api.md

@@ -0,0 +1,38 @@
+---
+title: API
+description: anonymize, restore, detect, Finding and Mapping.
+---
+
+## `anonymize(text, lang=None, *, keep=())`
+
+Returns `(text_with_placeholders, mapping)`.
+
+- `lang`: `"de"`, `"fr"`, `"it"`, `"en"` or `None` (a region such as `"de-CH"` is accepted). Anything else raises `ValueError`. It has no effect yet; it will select context words for names and addresses.
+- `keep`: values that stay in the text. Matching is exact and case-insensitive.
+
+Identical values get the same placeholder inside one call. A placeholder that already stands in the input text, like a literal `[AHV_1]`, is never reused.
+
+## `restore(text, mapping)`
+
+Replaces placeholders with the real values in one pass. Models sometimes change the case or add spaces inside the brackets (`[ahv_1]`, `[ AHV_1 ]`); both still match. Placeholders that are not in the mapping stay unchanged. `mapping` can be any `dict[str, str]`, for example one you loaded from your own storage.
+
+## `detect(text, lang=None, *, keep=())`
+
+Returns `list[Finding]` without changing the text.
+
+## `Finding`
+
+| Field | Meaning |
+|---|---|
+| `kind` | `AHV`, `IBAN`, `UID`, `PHONE`, `EMAIL` |
+| `start`, `end` | Position in the original text |
+| `confidence` | 0 to 1 |
+| `detector` | Name of the recogniser, for example `ahv-ean13` |
+| `checksum_ok` | `True` or `False` for AHV, IBAN and UID, `None` for the others |
+| `placeholder` | The placeholder used (empty from `detect`) |
+
+A `Finding` holds no value.
+
+## `Mapping`
+
+A `dict` from placeholder to real value with a `findings` list. `repr()` and `str()` show only the number of placeholders, so the values do not end up in logs by accident. The package does not log anything.

isomorphism-0.1.0/docs/reference/recognisers.md

@@ -0,0 +1,18 @@
+---
+title: Recognisers
+description: Formats, checks and confidence per kind.
+---
+
+| Kind | Confidence | Notes |
+|---|---|---|
+| `AHV` | 0.99 valid, 0.60 wrong check digit | Dotted form. Without dots: 0.90 and 0.40 |
+| `IBAN` | 0.99 valid, 0.60 wrong check digit | `CH` and `LI`, 21 characters |
+| `UID` | 0.98 valid, 0.60 wrong check digit | `CHE` and nine digits. `MWST`, `TVA`, `IVA`, `HR` are not part of the match |
+| `PHONE` | 0.95 with `+41` or `0041`, 0.85 with separators, 0.60 for ten bare digits | Area code 2 to 9 |
+| `EMAIL` | 0.95 | |
+
+Wrong check digits are reported on purpose: a typo in a document is still personal data.
+
+When two hits overlap, the higher confidence wins, then the longer match. This is why the digits inside an IBAN do not also come out as a phone number.
+
+Not recognised: foreign IBANs, the old 11-digit AHV format, service numbers such as `0800 …`.

isomorphism-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "isomorphism"
+version = "0.1.0"
+description = "Reversible anonymisation of Swiss personal data (AHV, IBAN, UID, phone, email) before text goes to a language model. Fully local, no dependencies."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Seya Weber" }]
+keywords = ["anonymization", "pseudonymization", "pii", "switzerland", "ahv", "iban", "llm", "privacy", "dsg"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Security",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://packages.sweber.dev/isomorphism"
+Documentation = "https://packages.sweber.dev/isomorphism/docs"
+Repository = "https://github.com/Weber-Development/isomorphism"
+Changelog = "https://github.com/Weber-Development/isomorphism/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.8", "mypy>=1.13"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/isomorphism"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/cases.py" = ["E501"]  # fixture lines are long on purpose
+
+[tool.mypy]
+strict = true
+files = ["src", "tests"]

isomorphism-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/tests/cases.py

@@ -0,0 +1,140 @@
+"""Invented Swiss texts with the expected hits marked inline as ⟦KIND|value⟧.
+
+Everything here is made up. Names, street addresses and companies appear in the texts but are not
+marked yet: those kinds arrive with the next version. Numbers with a wrong check digit are marked
+too, because they must be found as well.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+_MARK = re.compile(r"⟦([A-Z]+)\|([^⟧]*)⟧")
+
+
+@dataclass(frozen=True)
+class Case:
+    name: str
+    lang: str
+    text: str  # without markup
+    expected: frozenset[tuple[str, int, int]]  # kind, start, end
+
+
+def _parse(name: str, lang: str, marked: str) -> Case:
+    out, expected, pos = [], set(), 0
+    for m in _MARK.finditer(marked):
+        out.append(marked[pos : m.start()])
+        start = sum(len(p) for p in out)
+        out.append(m[2])
+        expected.add((m[1], start, start + len(m[2])))
+        pos = m.end()
+    out.append(marked[pos:])
+    return Case(name, lang, "".join(out), frozenset(expected))
+
+
+_RAW = [
+    (
+        "lohnausweis",
+        "de",
+        """\
+Lohnausweis 2025 (Auszug)
+Arbeitnehmerin: Anna Muster, Musterstrasse 12, 9000 St. Gallen
+AHV-Nr.: ⟦AHV|756.5260.1815.91⟧
+Arbeitgeberin: Beispiel Treuhand AG, ⟦UID|CHE-937.865.795⟧ MWST
+Bruttolohn 78'450.00, Nettolohn 66'918.40, Auszahlung auf ⟦IBAN|CH10 7971 1471 0497 4650 7⟧.
+Rückfragen: Lohnbuchhaltung, ⟦PHONE|071 123 45 67⟧, ⟦EMAIL|lohn@beispiel-treuhand.example⟧
+""",
+    ),
+    (
+        "mandanten-mail",
+        "de",
+        """\
+Grüezi Frau Keller
+
+Wir haben die Unterlagen für die Steuererklärung erhalten. Meine Mobilnummer ist
+⟦PHONE|+41 79 123 45 67⟧, erreichbar bin ich auch unter ⟦PHONE|079 123 45 67⟧.
+Die Rückzahlung bitte auf ⟦IBAN|CH21 5291 7034 2366 7127 6⟧ überweisen.
+Meine AHV-Nummer: ⟦AHV|756.0830.1661.38⟧ (die Nummer meines Mannes: ⟦AHV|756.1860.9139.07⟧).
+Freundliche Grüsse
+Hans Muster, ⟦EMAIL|hans.muster@mail.example⟧
+""",
+    ),
+    (
+        "beleg",
+        "de",
+        """\
+Beleg 2025-0417, Rechnung Nr. 20250417, Referenz 21 00000 00003 13947 14300 09017
+Lieferant: Muster Garage GmbH, ⟦UID|CHE-754.323.198⟧ HR, ⟦UID|CHE-487.574.914⟧ MWST
+Betrag CHF 1'234.50 inkl. 8.1% MWST, fällig am 30.11.2026
+Zahlbar an ⟦IBAN|CH19 8426 8465 6321 2233 0⟧ (kein Barzahlung), Tel. ⟦PHONE|+41 (0)71 987 65 43⟧
+""",
+    ),
+    (
+        "steuerrueckfrage",
+        "de",
+        """\
+Betreff: Steuerrückfrage Veranlagung 2025
+Das Steueramt St. Gallen fragt nach dem Beleg zu Kontonummer ⟦IBAN|CH67 7924 4026 8599 5289 0⟧.
+Bitte melden Sie sich unter ⟦PHONE|058 123 45 67⟧ oder per Mail an ⟦EMAIL|steueramt.anfrage@kanton.example⟧.
+Die AHV-Nummer ⟦AHV|756.9960.3082.41⟧ stimmt nicht mit den Unterlagen überein.
+""",
+    ),
+    (
+        "courrier",
+        "fr",
+        """\
+Madame, Monsieur,
+Veuillez trouver ci-joint le décompte pour M. Jean Dupont, n° AVS ⟦AHV|756.6281.9482.17⟧.
+Le montant est à verser sur ⟦IBAN|CH35 7866 6617 6031 3721 5⟧. Numéro IDE: ⟦UID|CHE-186.252.760⟧ TVA.
+Contact: ⟦PHONE|+41 21 123 45 67⟧ ou ⟦PHONE|021 123 45 67⟧, ⟦EMAIL|contact@fiduciaire.example⟧
+""",
+    ),
+    (
+        "lettera",
+        "it",
+        """\
+Gentile signora Bianchi,
+il suo numero AVS è ⟦AHV|756.9935.1819.09⟧. Il pagamento va fatto sul conto ⟦IBAN|LI27 9010 9281 5901 3962 4⟧.
+Numero IDI: ⟦UID|CHE-018.955.594⟧ IVA. Può chiamarci al ⟦PHONE|0041 91 123 45 67⟧ oppure scrivere a ⟦EMAIL|info@studio-fiduciario.example⟧.
+""",
+    ),
+    (
+        "mail-en",
+        "en",
+        """\
+Hi Anna,
+please transfer the refund to ⟦IBAN|CH93 0076 2011 6238 5295 7⟧ (I cannot find my ⟦AHV|756.1234.5678.97⟧ card).
+Our company is ⟦UID|CHE-123.456.788⟧; reach me on ⟦PHONE|+41 71 123 45 67⟧ or ⟦EMAIL|anna.muster@example.ch⟧.
+""",
+    ),
+    (
+        "formate",
+        "de",
+        """\
+Schreibweisen: ⟦AHV|7561234567897⟧, ⟦AHV|756 1234 5678 97⟧, ⟦IBAN|CH9300762011623852957⟧, ⟦IBAN|ch93 0076 2011 6238 5295 7⟧,
+⟦UID|CHE123456788⟧, ⟦UID|CHE-123.456.788⟧, ⟦PHONE|0711234567⟧, ⟦PHONE|071/123 45 67⟧, ⟦PHONE|(071) 123 45 67⟧,
+⟦PHONE|+41711234567⟧, ⟦PHONE|0041 71 123 45 67⟧, ⟦PHONE|071.123.45.67⟧
+""",
+    ),
+    (
+        "falsche-pruefziffer",
+        "de",
+        """\
+Tippfehler müssen trotzdem gefunden werden:
+AHV ⟦AHV|756.1234.5678.98⟧, IBAN ⟦IBAN|CH93 0076 2011 6238 5295 8⟧, UID ⟦UID|CHE-123.456.789⟧.
+""",
+    ),
+    (
+        "keine-treffer",
+        "de",
+        """\
+Rechnung 2026-1102, Kunde 756-20, Artikel 0711234, Menge 12 Stk. zu CHF 1'290.00.
+Datum 03.04.1981, Zeit 08.30 Uhr, PLZ 9000 St. Gallen, Seite 4 von 12, Version 3.13.1.
+Tarif 5.2.0, Konto 1020, Debitoren 1100, Kreditoren 2000, Anzahl 12345678901.
+Referenz 21 00000 00003 13947 14300 09017, Kontakt: siehe Impressum, Kapital 100'000.
+""",
+    ),
+]
+
+CASES = [_parse(*row) for row in _RAW]

isomorphism-0.1.0/tests/measure.py

@@ -0,0 +1,38 @@
+"""Hit rate and false alarms per kind over tests/cases.py.
+
+`python -m tests.measure` prints the README table.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+
+from isomorphism import detect
+
+from .cases import CASES
+
+KINDS = ("AHV", "IBAN", "UID", "PHONE", "EMAIL")
+
+
+def measure() -> dict[str, Counter[str]]:
+    stats: dict[str, Counter[str]] = {k: Counter() for k in KINDS}
+    for case in CASES:
+        found = {(f.kind, f.start, f.end) for f in detect(case.text, case.lang)}
+        for hit in case.expected & found:
+            stats[hit[0]]["tp"] += 1
+        for miss in case.expected - found:
+            stats[miss[0]]["fn"] += 1
+        for extra in found - case.expected:
+            stats[extra[0]]["fp"] += 1
+    return stats
+
+
+def table() -> str:
+    rows = ["| Kind | Expected | Found | Missed | False alarms |", "|---|---|---|---|---|"]
+    for kind, c in measure().items():
+        rows.append(f"| {kind} | {c['tp'] + c['fn']} | {c['tp']} | {c['fn']} | {c['fp']} |")
+    return "\n".join(rows)
+
+
+if __name__ == "__main__":
+    print(table())

isomorphism-0.1.0/tests/test_checks.py

@@ -0,0 +1,22 @@
+from isomorphism._checks import ahv_ok, iban_ok, uid_ok
+
+
+def test_ahv() -> None:
+    assert ahv_ok("7561234567897")
+    assert not ahv_ok("7561234567898")  # wrong check digit
+    assert not ahv_ok("7551234567897")  # wrong prefix
+    assert not ahv_ok("756123456789")  # too short
+
+
+def test_iban() -> None:
+    assert iban_ok("CH9300762011623852957")
+    assert iban_ok("LI21088100002324013AA")
+    assert not iban_ok("CH9300762011623852958")
+    assert not iban_ok("CH93")
+
+
+def test_uid() -> None:
+    assert uid_ok("123456788")
+    assert not uid_ok("123456789")
+    assert not uid_ok("12345678")
+    assert not uid_ok("100000007")  # mod-11 check would be 10, never valid

isomorphism-0.1.0/tests/test_core.py

@@ -0,0 +1,109 @@
+import logging
+import pickle
+
+import pytest
+
+from isomorphism import anonymize, detect, restore
+from tests.cases import CASES
+from tests.measure import KINDS, measure
+
+AHV = "756.1234.5678.97"
+IBAN = "CH93 0076 2011 6238 5295 7"
+
+
+def test_roundtrip_all_cases() -> None:
+    for case in CASES:
+        anon, mapping = anonymize(case.text, case.lang)
+        assert restore(anon, mapping) == case.text, case.name
+
+
+def test_same_value_same_placeholder() -> None:
+    anon, mapping = anonymize(f"{AHV} und {AHV} und 756.9960.3082.41")
+    assert anon == "[AHV_1] und [AHV_1] und [AHV_2]"
+    assert mapping["[AHV_1]"] == AHV
+
+
+def test_no_original_value_left() -> None:
+    for case in CASES:
+        anon, mapping = anonymize(case.text, case.lang)
+        for value in mapping.values():
+            assert value not in anon, case.name
+        assert len(mapping.findings) == len(case.expected), case.name
+
+
+def test_findings_carry_no_value() -> None:
+    _, mapping = anonymize(f"{AHV}, {IBAN}")
+    f = mapping.findings[0]
+    assert (f.kind, f.start, f.end, f.detector, f.checksum_ok) == ("AHV", 0, 16, "ahv-ean13", True)
+    assert 0 < f.confidence <= 1
+    for secret in (AHV, IBAN, "7561234567897"):
+        assert secret not in repr(mapping) + str(mapping) + repr(mapping.findings)
+
+
+def test_invalid_checksum_reported_with_lower_confidence() -> None:
+    good, bad = detect("756.1234.5678.97 756.1234.5678.98")
+    assert good.checksum_ok and not bad.checksum_ok
+    assert bad.confidence < good.confidence
+
+
+def test_keep_exceptions() -> None:
+    text = "Mail an Steueramt.SG@Kanton.example oder anna@muster.example"
+    anon, _ = anonymize(text, keep=["steueramt.sg@kanton.example"])
+    assert anon == "Mail an Steueramt.SG@Kanton.example oder [EMAIL_1]"
+
+
+def test_literal_placeholder_in_text_is_not_reused() -> None:
+    anon, mapping = anonymize(f"Vorlage [AHV_1]: {AHV}")
+    assert anon == "Vorlage [AHV_1]: [AHV_2]"
+    assert restore(anon, mapping) == f"Vorlage [AHV_1]: {AHV}"
+
+
+def test_restore_tolerates_model_changes_and_keeps_unknown() -> None:
+    _, mapping = anonymize(AHV)
+    assert restore("[ahv_1] / [ AHV_01 ] / [AHV_2] / [OTHER_1]", mapping) == (
+        f"{AHV} / {AHV} / [AHV_2] / [OTHER_1]"
+    )
+
+
+def test_restore_is_single_pass() -> None:
+    assert restore("[A_1] [B_1]", {"[A_1]": "[B_1]", "[B_1]": "x"}) == "[B_1] x"
+
+
+def test_overlap_prefers_checksum_match() -> None:
+    # The digits inside an IBAN must not also come out as a phone number.
+    anon, _ = anonymize("CH93 0076 2011 6238 5295 7")
+    assert anon == "[IBAN_1]"
+
+
+def test_lang() -> None:
+    anonymize("x", "de-CH")
+    with pytest.raises(ValueError, match="unsupported lang"):
+        anonymize("x", "xx")
+
+
+def test_nothing_is_logged(caplog: pytest.LogCaptureFixture) -> None:
+    with caplog.at_level(logging.DEBUG):
+        anon, mapping = anonymize(f"{AHV} {IBAN}")
+        restore(anon, mapping)
+    assert caplog.records == []
+
+
+def test_mapping_survives_pickle() -> None:
+    _, mapping = anonymize(AHV)
+    assert dict(pickle.loads(pickle.dumps(mapping))) == {"[AHV_1]": AHV}  # noqa: S301
+
+
+def test_acceptance_numbers() -> None:
+    stats = measure()
+    for kind in KINDS:
+        assert stats[kind]["fn"] == 0, f"{kind}: a listed value slipped through"
+        assert stats[kind]["fp"] == 0, f"{kind}: false alarm"
+
+
+def test_readme_table_is_current() -> None:
+    from pathlib import Path
+
+    from tests.measure import table
+
+    readme = Path(__file__).parent.parent / "README.md"
+    assert f"<!-- measure:start -->\n{table()}\n<!-- measure:end -->" in readme.read_text()