noirdoc 0.1.0__tar.gz

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

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint (pre-commit)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: pre-commit/action@v3.0.1
+
+  test:
+    name: Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+      - name: Install baseline + dev deps
+        run: pip install -e ".[dev]"
+      - name: Download spaCy model
+        run: python -m spacy download de_core_news_lg
+      - name: Run tests
+        run: pytest -m "not slow" --tb=short

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

@@ -0,0 +1,130 @@
+name: Release
+
+# Tag-triggered publish. Pre-release tags (a/b/rc/dev) go to TestPyPI;
+# final tags (vX.Y.Z, optionally .postN) go to PyPI. Auth via PyPI Trusted
+# Publishing (OIDC) — no secrets stored in GitHub. See docs/RELEASING.md.
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  determine:
+    name: Determine channel
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    outputs:
+      channel: ${{ steps.pick.outputs.channel }}
+      repository-url: ${{ steps.pick.outputs.repository-url }}
+      prerelease: ${{ steps.pick.outputs.prerelease }}
+    steps:
+      - id: pick
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          if [[ "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(\.post[0-9]+)?$ ]]; then
+            echo "channel=pypi"                                          >> "$GITHUB_OUTPUT"
+            echo "repository-url=https://upload.pypi.org/legacy/"        >> "$GITHUB_OUTPUT"
+            echo "prerelease=false"                                      >> "$GITHUB_OUTPUT"
+          else
+            echo "channel=testpypi"                                      >> "$GITHUB_OUTPUT"
+            echo "repository-url=https://test.pypi.org/legacy/"          >> "$GITHUB_OUTPUT"
+            echo "prerelease=true"                                       >> "$GITHUB_OUTPUT"
+          fi
+
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    needs: determine
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # hatch-vcs needs the full history to resolve the tag
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build tooling
+        run: pip install --upgrade build
+      - name: Build sdist and wheel
+        run: python -m build
+      - name: Confirm version matches tag
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          expected="${TAG#v}"
+          built=$(ls dist/*.whl | head -n1 | sed -E 's|.*/noirdoc-([^-]+)-.*|\1|')
+          echo "Tag expects: $expected"
+          echo "Wheel reports: $built"
+          test "$expected" = "$built"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish to ${{ needs.determine.outputs.channel }}
+    runs-on: ubuntu-latest
+    needs: [determine, build]
+    timeout-minutes: 10
+    environment:
+      name: ${{ needs.determine.outputs.channel }}
+    permissions:
+      id-token: write      # OIDC for Trusted Publishing
+      attestations: write  # PEP 740 build provenance
+      contents: read
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: ${{ needs.determine.outputs.repository-url }}
+          attestations: true
+
+  github-release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    needs: [determine, publish]
+    timeout-minutes: 5
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Extract changelog section for this tag
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          version="${TAG#v}"
+          # Pull the section between `## [<version>]` and the next `## [`.
+          awk -v ver="$version" '
+            $0 ~ "^## \\[" ver "\\]" {found=1; next}
+            found && /^## \[/ {exit}
+            found {print}
+          ' CHANGELOG.md > release-notes.md
+          if [ ! -s release-notes.md ]; then
+            echo "Release $TAG — see CHANGELOG.md for details." > release-notes.md
+          fi
+      - name: Create release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref_name }}
+          name: ${{ github.ref_name }}
+          body_path: release-notes.md
+          prerelease: ${{ needs.determine.outputs.prerelease }}
+          files: dist/*
+          fail_on_unmatched_files: true

noirdoc-0.1.0/.gitignore

@@ -0,0 +1,69 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Virtual environments
+.venv/
+venv/
+env/
+.env
+.env.*
+!.env.example
+
+# Packaging
+build/
+dist/
+*.egg-info/
+*.egg
+wheels/
+.eggs/
+pip-wheel-metadata/
+
+# Lock files (library — downstream should re-resolve)
+poetry.lock
+
+# Test / type / coverage artefacts
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.pyre/
+.pytype/
+.tox/
+.nox/
+.hypothesis/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# OS
+.DS_Store
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# Editors / IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+*.bak
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Local model cache and user data
+.noirdoc/
+
+# Build backends
+.hatch/
+
+# hatch-vcs generated version file
+src/noirdoc/_version.py
+
+# Claude Code working notes (brainstorm plans + specs)
+docs/superpowers/

noirdoc-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,33 @@
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+    -   id: trailing-whitespace
+    -   id: end-of-file-fixer
+    -   id: check-yaml
+    -   id: debug-statements
+    -   id: name-tests-test
+        args: [--pytest-test-first]
+-   repo: https://github.com/asottile/add-trailing-comma
+    rev: v4.0.0
+    hooks:
+    -   id: add-trailing-comma
+-   repo: https://github.com/asottile/pyupgrade
+    rev: v3.21.2
+    hooks:
+    -   id: pyupgrade
+        args: [--py312-plus]
+-   repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.19.1
+    hooks:
+    -   id: mypy
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.15.2
+  hooks:
+    - id: ruff-check
+      args: [--fix]
+    - id: ruff-format
+- repo: https://github.com/gitleaks/gitleaks
+  rev: v8.30.1
+  hooks:
+    - id: gitleaks

noirdoc-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12.12

noirdoc-0.1.0/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-04-24
+
+First public alpha on PyPI.
+
+### Added
+- Initial scaffold: pyproject, MIT LICENSE, README, package skeleton.
+- Detection ensemble (Presidio + optional GLiNER + Flair) extracted from the
+  Noirdoc Cloud reverse proxy.
+- File extractors for PDF (with optional OCR fallback), DOCX, XLSX, images, and
+  plain text formats (TXT/CSV/MD/HTML).
+- Reversible pseudonymization: `PseudonymMapper` with `to_dict`/`from_dict`
+  serialization, `PseudonymizationEngine`, `ReidentificationEngine`, and
+  `file_reidentification.service.reidentify_file_bytes` (DOCX/XLSX/plaintext
+  roundtrip; PDF/PPTX/images return `None`).
+- `MappingStore` with a pluggable `MappingBackend` protocol; concrete
+  `MemoryMappingBackend`, `FileMappingBackend`, and `RedisMappingBackend`
+  (via `noirdoc[redis]`).
+- Persistent namespaces under `~/.noirdoc/namespaces/<name>/` with a per-
+  namespace Fernet key (`0600`).
+- High-level SDK: `noirdoc.redact(...)` and `noirdoc.Redactor(namespace=...)`.
+- `noirdoc` CLI (Click) with `redact`, `reveal`, `lookup`, `ns {list,show,delete}`,
+  and `models pull` subcommands.
+- Project URLs in `pyproject.toml` (Repository, Issues, Changelog) for PyPI sidebar.
+
+### Fixed
+- Baseline install (`pip install noirdoc`) crashed with `ModuleNotFoundError:
+  gliner` because the default `detector="ensemble"` eagerly imported GLiNER.
+  The ensemble now detects an absent GLiNER, falls back to Presidio-only with
+  a `UserWarning`, and keeps working. Explicit `--detector gliner` still fails
+  loudly when the `[full]` extra isn't installed.
+
+[Unreleased]: https://github.com/nextaim-de/noirdoc/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/nextaim-de/noirdoc/releases/tag/v0.1.0

noirdoc-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing to noirdoc
+
+Thanks for your interest. Noirdoc is early — API will change — but contributions are welcome, especially around detectors, formats, and German-language coverage.
+
+## Prerequisites
+
+- Python 3.12 or 3.13
+- [Poetry](https://python-poetry.org/) 2.0 or later — `pipx install poetry` if you don't have it.
+- ~1 GB free disk for the `full` extra (GLiNER + Flair weights).
+
+## Dev setup
+
+```bash
+git clone https://github.com/nextaim-de/noirdoc.git
+cd noirdoc
+poetry env use 3.12                              # or 3.13
+poetry install --all-extras                      # dev + full + redis
+poetry run python -m spacy download de_core_news_lg
+poetry run pre-commit install
+```
+
+Poetry manages the local environment and resolves dependencies fresh from `pyproject.toml` on each checkout — noirdoc is a library, so the lockfile is not tracked (downstream consumers re-resolve). The build backend is `hatchling`; the published wheel is built from `[project]` metadata. CI uses plain `pip install -e ".[dev]"` for speed.
+
+## Running tests
+
+```bash
+poetry run pytest                 # fast tier (CI default)
+poetry run pytest -m slow         # includes model-loading tests
+poetry run pytest -m "not slow"   # same as CI
+```
+
+Prefer `poetry shell` if you'd rather not prefix every command.
+
+## Lint and formatting
+
+`pre-commit` runs ruff (check + format), mypy, pyupgrade, gitleaks, and a few hygiene hooks. CI enforces the same config.
+
+```bash
+poetry run pre-commit run --all-files
+```
+
+## Adding a detector
+
+Custom Presidio recognizers live in `src/noirdoc/detection/presidio_detector.py`. The German set — `GermanPhoneRecognizer`, `GermanSVNRRecognizer`, `GermanSteuerIDRecognizer`, `InvertedNameRecognizer` — is the reference pattern. Each one sets `supported_language="de"`; multi-language detectors register twice, once per language (see the `InvertedNameRecognizer` registration in the same file).
+
+Tests go in `tests/test_presidio_detector.py`. Add both positive and negative cases, and cover the German edge cases you're designing for — lowercase terms, IBAN formatting, Steuer-ID checksums.
+
+## Pull requests
+
+- Keep PRs small and focused. One detector per PR beats a mega-PR.
+- Every PR includes a test.
+- Update `CHANGELOG.md` under `## [Unreleased]` with a one-line entry in the appropriate subsection (`### Added`, `### Changed`, `### Fixed`).
+- CI must be green before review.
+
+## Releasing
+
+Only maintainers cut releases. The flow is tag-driven and uses PyPI Trusted Publishing — see [docs/RELEASING.md](docs/RELEASING.md) for the per-release checklist, the first-release rehearsal, and the one-time PyPI setup.
+
+## Reporting bugs
+
+Open an issue at <https://github.com/nextaim-de/noirdoc/issues>. Include Python version, OS, the command or code that triggered the bug, and the traceback if any. A minimal reproducer helps a lot.
+
+For security-sensitive bugs, see [SECURITY.md](SECURITY.md) — do not open a public issue.

noirdoc-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Antonio Maiolo / Nextaim GmbH
+
+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.

noirdoc-0.1.0/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: noirdoc
+Version: 0.1.0
+Summary: Local PII redaction and pseudonymization for documents.
+Project-URL: Homepage, https://noirdoc.de
+Project-URL: Repository, https://github.com/nextaim-de/noirdoc
+Project-URL: Documentation, https://github.com/nextaim-de/noirdoc#readme
+Project-URL: Issues, https://github.com/nextaim-de/noirdoc/issues
+Project-URL: Changelog, https://github.com/nextaim-de/noirdoc/blob/main/CHANGELOG.md
+Author: Antonio Maiolo
+Maintainer-email: Nextaim GmbH <hello@noirdoc.de>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: anonymization,gdpr,nlp,pii,presidio,privacy,pseudonymization,redaction
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: <3.14,>=3.12
+Requires-Dist: click>=8.1.0
+Requires-Dist: cryptography>=46.0.0
+Requires-Dist: openpyxl>=3.1.0
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: presidio-analyzer>=2.2.361
+Requires-Dist: presidio-anonymizer>=2.2.361
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pypdfium2>=4.0.0
+Requires-Dist: pytesseract>=0.3.10
+Requires-Dist: python-docx>=1.1.0
+Requires-Dist: python-magic>=0.4.27
+Requires-Dist: spacy>=3.8
+Requires-Dist: structlog>=25.0.0
+Provides-Extra: dev
+Requires-Dist: fakeredis>=2.21.0; extra == 'dev'
+Requires-Dist: mypy>=1.19.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.15.0; extra == 'dev'
+Provides-Extra: full
+Requires-Dist: flair>=0.14; extra == 'full'
+Requires-Dist: gliner>=0.2.25; extra == 'full'
+Provides-Extra: redis
+Requires-Dist: redis[hiredis]>=7.0.0; extra == 'redis'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/nextaim-de/noirdoc/main/docs/assets/banner.svg" alt="noirdoc — German-first PII redaction, local by default." width="800">
+</p>
+
+<p align="center">
+  <a href="https://github.com/nextaim-de/noirdoc/actions/workflows/ci.yml"><img src="https://github.com/nextaim-de/noirdoc/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <img src="https://img.shields.io/badge/python-3.12%20%7C%203.13-blue" alt="Python 3.12 | 3.13">
+  <img src="https://img.shields.io/badge/license-MIT-green" alt="License: MIT">
+  <a href="https://github.com/pre-commit/pre-commit"><img src="https://img.shields.io/badge/pre--commit-enabled-brightgreen" alt="pre-commit enabled"></a>
+</p>
+
+# noirdoc
+
+**German-first PII redaction and pseudonymization for documents. Local by default. Reversible when you need it.**
+
+Noirdoc redacts names, addresses, phone numbers, IBANs, Steuer-IDs, SVNRs, and the rest — from PDFs, DOCX, XLSX, and plain text — without sending anything to a third party. Under the hood it's a rules-based Presidio pipeline by default, and an ensemble (Presidio + GLiNER + Flair) when the `[full]` extra is installed. It's built for real-world German documents and mixed DE/EN text — the kind of stuff Mittelstand actually runs through an LLM.
+
+> **Status:** alpha (`0.1.x`). API will change before `1.0`. Pin the minor version.
+
+## Prerequisites
+
+- Python **3.12** or **3.13**
+- ~1 GB free disk if you install the `[full]` extra (spaCy + Flair + GLiNER weights)
+- Optional: a Redis instance if you want shared mapping storage across workers (`[redis]` extra)
+
+## Install
+
+```bash
+# Baseline — Presidio + all file extractors + reversible mapper.
+pip install noirdoc
+
+# Full ensemble (adds GLiNER + Flair, large ML weights). Recommended for real work.
+pip install noirdoc[full]
+noirdoc models pull
+
+# Optional distributed mapper backend.
+pip install noirdoc[redis]
+```
+
+For anything beyond toy examples, use `noirdoc[full]` — the ensemble catches what the baseline misses, especially on German lowercase text.
+
+## Quickstart
+
+```bash
+# One-shot redact (ephemeral mapping, discarded on exit).
+noirdoc redact vertrag.pdf -o vertrag-clean.pdf
+
+# Persistent namespace — placeholders stay consistent across files and sessions.
+noirdoc redact --namespace mandant-mueller brief.docx -o brief-clean.docx
+noirdoc reveal --namespace mandant-mueller brief-clean.docx -o brief-revealed.docx
+noirdoc lookup --namespace mandant-mueller "<<PERSON_3>>"
+```
+
+```python
+from noirdoc import Redactor
+
+r = Redactor(namespace="mandant-mueller")
+r.redact_file("vertrag.pdf", output="vertrag-clean.pdf")
+r.redact_file("brief.docx", output="brief-clean.docx")
+r.reveal_text(llm_response)  # un-redact the model's reply
+```
+
+Input:
+
+> Anna Müller, geboren am 12.03.1981 in München, erreichbar unter 0171-2345678, Steuer-ID 12 345 678 901, IBAN DE89 3704 0044 0532 0130 00.
+
+Output:
+
+> `<<PERSON_1>>`, geboren am `<<DATE_TIME_1>>` in `<<LOCATION_1>>`, erreichbar unter `<<PHONE_NUMBER_1>>`, Steuer-ID `<<DE_STEUER_ID_1>>`, IBAN `<<IBAN_CODE_1>>`.
+
+## Commands
+
+| Command                      | What it does                                                                           |
+|------------------------------|----------------------------------------------------------------------------------------|
+| `noirdoc redact <files>`     | Redact one or more files (accepts directories; `-o FILE` or `--output-dir DIR`).       |
+| `noirdoc reveal <file>`      | Reverse pseudonyms back to originals (DOCX / XLSX / plain; `--namespace` required).    |
+| `noirdoc lookup <token>`     | Resolve a pseudonym like `<<PERSON_1>>` to its original value.                         |
+| `noirdoc ns list`            | List persistent namespaces under `~/.noirdoc/namespaces/`.                             |
+| `noirdoc ns show <name>`     | Print the mapping summary for a namespace as JSON.                                     |
+| `noirdoc ns delete <name>`   | Delete a namespace (prompts for confirmation).                                         |
+| `noirdoc models pull`        | Download spaCy models and (optionally) GLiNER weights up front.                        |
+
+Run `noirdoc <cmd> --help` for the full flag list on any subcommand.
+
+## Before you start
+
+A few honest caveats before you ship this into a pipeline:
+
+- **Best results need `[full]`.** On first use (or via `noirdoc models pull`) the full extra downloads roughly **560 MB** of weights: spaCy `de_core_news_lg`, Flair `ner-german-large`, and a GLiNER multilingual model. Budget disk and bandwidth.
+- **PDF reveal is not supported yet.** Round-tripping placeholders back into a PDF is a hard problem (position drift, font metrics, image-based redactions). PDFs redact cleanly; reveal is pass-through. DOCX, XLSX, and plain text round-trip fully.
+- **Alpha API.** Classes and CLI flags may change between `0.1.x` and `0.2.x`. Pin accordingly.
+- **Detector quality depends on the upstream models.** Presidio + Flair + GLiNER do the heavy lifting. Noirdoc adds German-specific recognizers on top, but it does not train models.
+
+## German-first
+
+Noirdoc defaults to German (`language="de"`) with fallback to `["de", "en"]` for mixed documents. What that actually means:
+
+- **Custom recognizers** in `src/noirdoc/detection/presidio_detector.py`:
+  - `GermanPhoneRecognizer` — German phone formats (0171-..., +49...)
+  - `GermanSVNRRecognizer` — Sozialversicherungsnummer with checksum
+  - `GermanSteuerIDRecognizer` — 11-digit Steuer-ID with checksum
+  - `InvertedNameRecognizer` — registered for both `de` and `en` to catch "Nachname, Vorname" patterns
+- **Flair `ner-german-large`** (XLM-R, F1 92.3 % on CoNLL-03 DE) handles lowercase German text — the case where spaCy tends to drop names.
+- **GLiNER multilingual** catches entity types the others miss.
+- **German-style lowercase** financial terms, German IBANs, German date formats, and German address patterns are covered in the test suite (`tests/test_presidio_detector.py`).
+
+If you're working with German legal, medical, HR, or financial documents, this is what the defaults are tuned for.
+
+## Supported formats
+
+| Format                       | Redact | Reveal (round-trip) |
+|------------------------------|--------|---------------------|
+| PDF                          | ✓      | ✗ (pass-through)    |
+| DOCX                         | ✓      | ✓                   |
+| XLSX                         | ✓      | ✓                   |
+| Plain text / CSV / MD / HTML | ✓      | ✓                   |
+| PPTX / images                | ✓      | ✗ (pass-through)    |
+
+PDF reveal is an open contribution target — see [CONTRIBUTING.md](https://github.com/nextaim-de/noirdoc/blob/main/CONTRIBUTING.md).
+
+## Advanced: shared mapping storage
+
+The `[redis]` extra ships a `RedisMappingBackend` that plugs into the lower-level `MappingStore` — the same primitive Noirdoc Cloud uses for request-scoped, encrypted, TTL-bounded mapping persistence across workers. It is **not** wired into `Redactor(namespace=...)`, which persists to the local filesystem under `~/.noirdoc/namespaces/`. Use `MappingStore` when you have multiple workers that need to share pseudonym mappings for the same request, or when you want encrypted-at-rest mappings with automatic expiry.
+
+```python
+import asyncio
+from cryptography.fernet import Fernet
+from redis.asyncio import Redis
+
+from noirdoc.mappings.backends.redis_backend import RedisMappingBackend
+from noirdoc.mappings.store import MappingStore
+
+async def main() -> None:
+    redis = Redis.from_url("redis://localhost:6379")
+    store = MappingStore(
+        backend=RedisMappingBackend(redis),
+        encryption_key=Fernet.generate_key(),  # keep stable across workers
+    )
+    # store.save(request_id=..., tenant_id=..., mapper=...)
+    # mappings = await store.load(request_id)
+
+asyncio.run(main())
+```
+
+The `encryption_key` must be identical across workers that need to read the same mappings. `MappingStore.save()` accepts a `ttl_days` kwarg (default 30).
+
+## Noirdoc Cloud
+
+Don't want to run this yourself? **[Noirdoc Cloud](https://noirdoc.de)** is the hosted API wrapper: a privacy-preserving reverse proxy for LLM calls that uses this exact pipeline, plus multi-tenancy, audit, and provider key management. Compliance story: what's on GitHub is what the cloud runs.
+
+## Contributing
+
+Bug reports, detectors, and format support are all welcome. See [CONTRIBUTING.md](https://github.com/nextaim-de/noirdoc/blob/main/CONTRIBUTING.md) for dev setup, tests, and the recognizer pattern.
+
+## Security
+
+Report vulnerabilities via GitHub's private vulnerability reporting — see [SECURITY.md](https://github.com/nextaim-de/noirdoc/blob/main/SECURITY.md). Please don't open public issues for security bugs.
+
+## Changelog
+
+See [CHANGELOG.md](https://github.com/nextaim-de/noirdoc/blob/main/CHANGELOG.md). Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](https://semver.org/).
+
+## License
+
+MIT © 2026 Antonio Maiolo / [Nextaim GmbH](https://nextaim.de). See [LICENSE](https://github.com/nextaim-de/noirdoc/blob/main/LICENSE).
+
+---
+
+<p align="center">
+  Built by <a href="https://nextaim.de">Nextaim GmbH</a> · <a href="https://noirdoc.de">noirdoc.de</a>
+</p>