cloakrs 0.1.0a1__tar.gz

cloakrs-0.1.0a1/Cargo.toml

@@ -0,0 +1,46 @@
+[workspace]
+members = [
+    "crates/cloakrs-core",
+    "crates/cloakrs-patterns",
+    "crates/cloakrs-locales",
+    "crates/cloakrs-adapters",
+    "crates/cloakrs-tracing",
+    "crates/cloakrs-cli",
+]
+exclude = ["bindings/python"]
+resolver = "2"
+
+[workspace.package]
+version = "0.4.0"
+edition = "2021"
+rust-version = "1.75.0"
+license = "MIT"
+repository = "https://github.com/kadir/cloakrs"
+homepage = "https://github.com/kadir/cloakrs"
+documentation = "https://docs.rs/cloakrs-core"
+readme = "README.md"
+keywords = ["pii", "redaction", "privacy", "masking", "cli"]
+categories = ["command-line-utilities", "text-processing"]
+
+[workspace.dependencies]
+aes-gcm = "0.10"
+base64 = "0.22"
+clap = { version = "4", features = ["derive", "env"] }
+criterion = "0.5"
+csv = "1"
+indicatif = "0.17"
+ignore = "0.4"
+once_cell = "1"
+proptest = "1"
+rayon = "1"
+regex = "1"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+same-file = "1"
+tempfile = "3"
+sha2 = "0.10"
+thiserror = "2"
+tokio = { version = "1", features = ["full"] }
+toml = "0.8"
+tracing = "0.1"
+tracing-subscriber = "0.3"

cloakrs-0.1.0a1/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cloakrs contributors
+
+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.

cloakrs-0.1.0a1/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: cloakrs
+Version: 0.1.0a1
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Rust
+License-File: LICENSE.md
+Summary: Local PII detection, redaction, and prompt sanitization powered by Rust
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/kadir/cloakrs
+Project-URL: Issues, https://github.com/kadir/cloakrs/issues
+Project-URL: Repository, https://github.com/kadir/cloakrs
+
+# cloakrs for Python
+
+An alpha Python interface to the cloakrs 0.4.0 Rust engine, with local scanning,
+redaction, and reversible prompt sanitization. Input stays in your process;
+the library makes no network requests and does not invoke the CLI.
+
+## Install the prerelease
+
+```sh
+python -m pip install --only-binary=:all: 'cloakrs==0.1.0a1'
+```
+
+Requires regular CPython 3.11–3.14. Wheels include the compiled Rust engine;
+installation needs no Rust compiler or additional Python runtime dependencies.
+
+| Platform | Wheel support |
+| --- | --- |
+| Linux with glibc 2.17+ | x86_64 and ARM64 |
+| macOS 11+ | Intel and Apple Silicon |
+| Windows | x86_64 |
+
+Alpine/musl, Windows ARM64, free-threaded Python, and alternative interpreters
+do not have validated wheels. A source install requires Rust 1.83 or newer:
+`python -m pip install --no-binary=cloakrs 'cloakrs==0.1.0a1'`.
+This is an early prerelease; evaluate it on representative data before adoption.
+
+## Use
+
+```python
+from cloakrs import Scanner
+
+scanner = Scanner(locale="us")
+result = scanner.scan("Email jane@example.com")
+assert result.masked_text == "Email [EMAIL]"
+
+finding = result.findings[0]
+assert finding.entity_type == "email"
+assert finding.text == "jane@example.com"
+assert scanner.mask("Email jane@example.com") == "Email [EMAIL]"
+```
+
+`Scanner` and `Sanitizer` accept the same keyword-only options:
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `locale` | `"universal"` | One of `universal`, `us`, `uk`, `nl`, `de`, `fr`, `in`, `br`, `eu` |
+| `min_confidence` | `0.0` | Finite threshold from 0 to 1, matching the Rust library default |
+| `exclude_entities` | `()` | Sequence of canonical entity names; see `cloakrs.ENTITY_TYPES` |
+| `allow_list` | `()` | Literal values whose overlapping findings are suppressed |
+| `deny_list` | `()` | Literal values added as `deny-list` findings |
+
+All options are explicit; no configuration files are discovered. Duplicate
+exclusions have no additional effect. Deny-list rules survive entity exclusions;
+allow-list precedence still applies to deny-list findings. `passport-number` and
+`drivers-license` are reserved entity names without bundled recognizers.
+
+```python
+scanner = Scanner(locale="us", exclude_entities=["url"])
+assert scanner.mask("https://example.com?email=jane%40example.com") == (
+    "https://example.com?email=[EMAIL]"
+)
+```
+
+Excluding URLs can leave embedded credentials visible, including userinfo
+passwords and unsupported encoded query secrets. Default URL detection remains
+enabled. Pattern-based detection does not guarantee that arbitrary text contains
+no secrets; choose a locale and check representative input for your application.
+
+## Sanitize a prompt and restore a response
+
+```python
+from cloakrs import Mapping, Sanitizer
+
+sanitizer = Sanitizer(locale="us")
+clean, mapping = sanitizer.sanitize("Email jane@example.com")
+assert clean == "Email [EMAIL_1]"
+assert len(mapping) == 1
+assert repr(mapping) == "Mapping(entries=1)"
+
+# Send only clean to your model; keep mapping inside your application.
+response = "Reply to [ email_1 ]"
+assert mapping.restore(response) == "Reply to jane@example.com"
+assert mapping.restore(response, strict=True) == response
+
+# Explicit export contains original values. Keep this JSON private too.
+mapping_json = mapping.to_json()
+loaded = Mapping.from_json(mapping_json)
+assert loaded.restore(clean) == "Email jane@example.com"
+```
+
+Use `sanitize(text, placeholder_style="braces")` for `{EMAIL_1}` placeholders;
+the default is `"brackets"`. Repeated values of the same entity type share one
+placeholder within a call. Existing placeholders are preserved, with new ones
+using available numbers. Each call returns an independent mapping. Nested
+findings are replaced once at their outermost span.
+
+Restoration tolerates ASCII case changes and whitespace immediately inside
+numbered placeholders. `strict=True` requires exact spelling. Unknown
+placeholders remain untouched, and restored values are not expanded recursively.
+
+`Mapping` is opaque: its representation shows only the entry count, and pickling
+is disabled. It does not automatically write files or log values. `to_json()`
+explicitly exports sensitive originals using the Rust CLI mapping schema;
+`from_json()` can import files produced by `cloakrs sanitize`. The CLI's
+`cloakrs restore` can read Python exports. Mapping spans remain **UTF-8 byte
+offsets** of the first occurrence, while Python `Finding` indices count code
+points. JSON import rejects invalid schema, empty or ambiguous duplicate
+placeholders, confidence outside 0–1, and spans whose byte lengths do not match
+their originals. Unknown extra JSON fields are ignored, as in the Rust CLI.
+
+## Results and errors
+
+`ScanResult` and `Finding` are immutable typed dataclasses. Findings include
+`entity_type`, `start`, `end`, `confidence`, `recognizer_id`, and `text`.
+`source[finding.start:finding.end]` selects the matched original text. Indices
+count Python Unicode code points, not Rust UTF-8 bytes or visual graphemes.
+Nested URL findings can overlap; use `masked_text` for Rust's redaction policy.
+
+Representations omit original and masked text. Accessing `.text`, `.masked_text`,
+or explicitly serializing a result can expose sensitive values. Masked text may
+still contain unsupported or intentionally excluded values.
+
+Unknown locale, entity, or placeholder-style names and invalid confidence values
+raise `ValueError`; wrong argument types raise `TypeError`. Lone Unicode
+surrogates are rejected with `ValueError`.
+Internal scanning failures raise a generic `RuntimeError` without source values.
+
+Reuse scanners and sanitizers for repeated calls. Scanning, sanitization,
+restoration, and mapping JSON processing release the Python interpreter lock
+while Rust runs. Instances can be shared between Python threads.
+`mask()` avoids allocating Python finding objects when only redacted text is needed.
+
+## Build and test from this repository
+
+Requires regular CPython 3.11–3.14 and Rust 1.83 or newer for building this binding.
+The Rust library and CLI retain their independent Rust 1.75 minimum. A built wheel
+does not require a Rust compiler or additional Python runtime dependencies.
+Free-threaded Python and alternative interpreters are not validated yet.
+
+From the repository root:
+
+```sh
+python3 -m venv .venv-python
+# Linux/macOS; on Windows activate .venv-python\Scripts\Activate.ps1 instead.
+. .venv-python/bin/activate
+python -m pip install 'maturin>=1.15,<2' 'pytest>=8,<10' 'mypy>=1.15,<3'
+cd bindings/python
+maturin build --release --locked --out dist
+python -m pip install --no-deps --force-reinstall dist/*.whl
+cargo build --manifest-path ../../Cargo.toml --locked -p cloakrs-cli
+python -m pytest tests
+python -m mypy python/cloakrs tests/typing_smoke.py
+```
+
+In PowerShell, install the wheel with
+`python -m pip install --no-deps --force-reinstall (Get-ChildItem dist/*.whl)`.
+The test suite runs against the installed wheel and compares all 58 existing
+evaluation cases against the Rust detection snapshot. It also checks exact
+sanitizer round trips in both placeholder styles and exchanges mappings with the
+real CLI in both directions. These tests require the repository checkout and the
+CLI built above. Python binding changes have a separate CI workflow.
+
+## Releasing
+
+Python releases use `python-v<version>` tags and the dedicated
+`python-release.yml` workflow with PyPI Trusted Publishing. Branch pushes and
+pull requests validate packages without publishing. See the repository's
+[Python release guide](https://github.com/kadir/cloakrs/blob/master/docs/python-releases.md)
+for account setup, artifact checks, tagging, and verification after upload.
+

cloakrs-0.1.0a1/README.md

@@ -0,0 +1,169 @@
+# cloakrs for Python
+
+An alpha Python interface to the cloakrs 0.4.0 Rust engine, with local scanning,
+redaction, and reversible prompt sanitization. Input stays in your process;
+the library makes no network requests and does not invoke the CLI.
+
+## Install the prerelease
+
+```sh
+python -m pip install --only-binary=:all: 'cloakrs==0.1.0a1'
+```
+
+Requires regular CPython 3.11–3.14. Wheels include the compiled Rust engine;
+installation needs no Rust compiler or additional Python runtime dependencies.
+
+| Platform | Wheel support |
+| --- | --- |
+| Linux with glibc 2.17+ | x86_64 and ARM64 |
+| macOS 11+ | Intel and Apple Silicon |
+| Windows | x86_64 |
+
+Alpine/musl, Windows ARM64, free-threaded Python, and alternative interpreters
+do not have validated wheels. A source install requires Rust 1.83 or newer:
+`python -m pip install --no-binary=cloakrs 'cloakrs==0.1.0a1'`.
+This is an early prerelease; evaluate it on representative data before adoption.
+
+## Use
+
+```python
+from cloakrs import Scanner
+
+scanner = Scanner(locale="us")
+result = scanner.scan("Email jane@example.com")
+assert result.masked_text == "Email [EMAIL]"
+
+finding = result.findings[0]
+assert finding.entity_type == "email"
+assert finding.text == "jane@example.com"
+assert scanner.mask("Email jane@example.com") == "Email [EMAIL]"
+```
+
+`Scanner` and `Sanitizer` accept the same keyword-only options:
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `locale` | `"universal"` | One of `universal`, `us`, `uk`, `nl`, `de`, `fr`, `in`, `br`, `eu` |
+| `min_confidence` | `0.0` | Finite threshold from 0 to 1, matching the Rust library default |
+| `exclude_entities` | `()` | Sequence of canonical entity names; see `cloakrs.ENTITY_TYPES` |
+| `allow_list` | `()` | Literal values whose overlapping findings are suppressed |
+| `deny_list` | `()` | Literal values added as `deny-list` findings |
+
+All options are explicit; no configuration files are discovered. Duplicate
+exclusions have no additional effect. Deny-list rules survive entity exclusions;
+allow-list precedence still applies to deny-list findings. `passport-number` and
+`drivers-license` are reserved entity names without bundled recognizers.
+
+```python
+scanner = Scanner(locale="us", exclude_entities=["url"])
+assert scanner.mask("https://example.com?email=jane%40example.com") == (
+    "https://example.com?email=[EMAIL]"
+)
+```
+
+Excluding URLs can leave embedded credentials visible, including userinfo
+passwords and unsupported encoded query secrets. Default URL detection remains
+enabled. Pattern-based detection does not guarantee that arbitrary text contains
+no secrets; choose a locale and check representative input for your application.
+
+## Sanitize a prompt and restore a response
+
+```python
+from cloakrs import Mapping, Sanitizer
+
+sanitizer = Sanitizer(locale="us")
+clean, mapping = sanitizer.sanitize("Email jane@example.com")
+assert clean == "Email [EMAIL_1]"
+assert len(mapping) == 1
+assert repr(mapping) == "Mapping(entries=1)"
+
+# Send only clean to your model; keep mapping inside your application.
+response = "Reply to [ email_1 ]"
+assert mapping.restore(response) == "Reply to jane@example.com"
+assert mapping.restore(response, strict=True) == response
+
+# Explicit export contains original values. Keep this JSON private too.
+mapping_json = mapping.to_json()
+loaded = Mapping.from_json(mapping_json)
+assert loaded.restore(clean) == "Email jane@example.com"
+```
+
+Use `sanitize(text, placeholder_style="braces")` for `{EMAIL_1}` placeholders;
+the default is `"brackets"`. Repeated values of the same entity type share one
+placeholder within a call. Existing placeholders are preserved, with new ones
+using available numbers. Each call returns an independent mapping. Nested
+findings are replaced once at their outermost span.
+
+Restoration tolerates ASCII case changes and whitespace immediately inside
+numbered placeholders. `strict=True` requires exact spelling. Unknown
+placeholders remain untouched, and restored values are not expanded recursively.
+
+`Mapping` is opaque: its representation shows only the entry count, and pickling
+is disabled. It does not automatically write files or log values. `to_json()`
+explicitly exports sensitive originals using the Rust CLI mapping schema;
+`from_json()` can import files produced by `cloakrs sanitize`. The CLI's
+`cloakrs restore` can read Python exports. Mapping spans remain **UTF-8 byte
+offsets** of the first occurrence, while Python `Finding` indices count code
+points. JSON import rejects invalid schema, empty or ambiguous duplicate
+placeholders, confidence outside 0–1, and spans whose byte lengths do not match
+their originals. Unknown extra JSON fields are ignored, as in the Rust CLI.
+
+## Results and errors
+
+`ScanResult` and `Finding` are immutable typed dataclasses. Findings include
+`entity_type`, `start`, `end`, `confidence`, `recognizer_id`, and `text`.
+`source[finding.start:finding.end]` selects the matched original text. Indices
+count Python Unicode code points, not Rust UTF-8 bytes or visual graphemes.
+Nested URL findings can overlap; use `masked_text` for Rust's redaction policy.
+
+Representations omit original and masked text. Accessing `.text`, `.masked_text`,
+or explicitly serializing a result can expose sensitive values. Masked text may
+still contain unsupported or intentionally excluded values.
+
+Unknown locale, entity, or placeholder-style names and invalid confidence values
+raise `ValueError`; wrong argument types raise `TypeError`. Lone Unicode
+surrogates are rejected with `ValueError`.
+Internal scanning failures raise a generic `RuntimeError` without source values.
+
+Reuse scanners and sanitizers for repeated calls. Scanning, sanitization,
+restoration, and mapping JSON processing release the Python interpreter lock
+while Rust runs. Instances can be shared between Python threads.
+`mask()` avoids allocating Python finding objects when only redacted text is needed.
+
+## Build and test from this repository
+
+Requires regular CPython 3.11–3.14 and Rust 1.83 or newer for building this binding.
+The Rust library and CLI retain their independent Rust 1.75 minimum. A built wheel
+does not require a Rust compiler or additional Python runtime dependencies.
+Free-threaded Python and alternative interpreters are not validated yet.
+
+From the repository root:
+
+```sh
+python3 -m venv .venv-python
+# Linux/macOS; on Windows activate .venv-python\Scripts\Activate.ps1 instead.
+. .venv-python/bin/activate
+python -m pip install 'maturin>=1.15,<2' 'pytest>=8,<10' 'mypy>=1.15,<3'
+cd bindings/python
+maturin build --release --locked --out dist
+python -m pip install --no-deps --force-reinstall dist/*.whl
+cargo build --manifest-path ../../Cargo.toml --locked -p cloakrs-cli
+python -m pytest tests
+python -m mypy python/cloakrs tests/typing_smoke.py
+```
+
+In PowerShell, install the wheel with
+`python -m pip install --no-deps --force-reinstall (Get-ChildItem dist/*.whl)`.
+The test suite runs against the installed wheel and compares all 58 existing
+evaluation cases against the Rust detection snapshot. It also checks exact
+sanitizer round trips in both placeholder styles and exchanges mappings with the
+real CLI in both directions. These tests require the repository checkout and the
+CLI built above. Python binding changes have a separate CI workflow.
+
+## Releasing
+
+Python releases use `python-v<version>` tags and the dedicated
+`python-release.yml` workflow with PyPI Trusted Publishing. Branch pushes and
+pull requests validate packages without publishing. See the repository's
+[Python release guide](https://github.com/kadir/cloakrs/blob/master/docs/python-releases.md)
+for account setup, artifact checks, tagging, and verification after upload.

cloakrs-0.1.0a1/bindings/python/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Python changelog
+
+## 0.1.0a1
+
+First Python prerelease, powered by the cloakrs 0.4.0 Rust engine.
+
+- Local scanning and masking with typed findings and Python string indices.
+- Prompt sanitization with bracket/brace placeholders and tolerant or strict restoration.
+- Explicit mapping JSON import/export interoperable with the Rust CLI.
+- Locale, confidence, entity exclusion, and literal allow/deny options.
+- Sensitive values omitted from mapping representations; automatic mapping pickling disabled.
+- CPython 3.11–3.14 wheels for Linux x86_64/ARM64, macOS Intel/Apple Silicon,
+  and Windows x86_64, plus a source distribution.