canpii 0.1.0__tar.gz

canpii-0.1.0/.gitignore

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

canpii-0.1.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/) (0.x: minor versions may break APIs).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-05
+
+### Added
+
+- Recognizers (English and French instances): `CaOnOhipRecognizer`,
+  `CaQcRamqRecognizer`, `CaBcPhnRecognizer`, `CaAbPhnRecognizer`
+  (`CA_HEALTH_NUMBER`); `CaPassportRecognizer` (`CA_PASSPORT`);
+  `CaBusinessNumberRecognizer` (`CA_BN`); `CaBankAccountRecognizer`
+  (`CA_BANK_ACCOUNT`); `CaOnDriverLicenseRecognizer`, `CaQcDriverLicenseRecognizer`,
+  `CaBcDriverLicenseRecognizer` (`CA_DRIVER_LICENSE`).
+- Two-tier validation: official rules reject, secondary/community rules only add score
+  (`strict=True` to reject on them too); negative context for weak matches.
+- Pure-Python `canpii.validators` module (no Presidio dependency).
+- `register_all()`, `get_recognizers()`, `create_analyzer()` and a bundled
+  `RecognizerRegistryProvider` YAML; enables upstream `CA_SIN` / `CA_POSTAL_CODE`.
+- Policy presets `pipeda`, `phipa`, `quebec_law25`.
+- CLI `canpii export` for LiteLLM (`presidio_ad_hoc_recognizers` JSON and
+  guardrail config), ContextForge `custom_patterns`, generic regex JSON and Presidio YAML.
+- Synthetic data generator, labeled bilingual benchmark, docs with sourced format table.
+
+[Unreleased]: https://github.com/ArthurJZL/canpii/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/ArthurJZL/canpii/releases/tag/v0.1.0

canpii-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,107 @@
+# Contributing to canpii
+
+Thanks for helping! This project is small on purpose: every recognizer must be
+**sourced, tested and documented**. The rules below exist so that a reviewer can
+check a contribution without having to trust it.
+
+## Ground rules
+
+1. **No real identifiers, ever.** Not in code, tests, issues, PRs, commit messages,
+   screenshots or logs. Use `canpii generate <kind>` or obviously fake values
+   (`1234-567-897`, `ZZZX 8812 2512`). PRs containing anything that looks like a real
+   identifier will be closed and the history rewritten.
+2. **Every format rule needs a source.** Official (government / regulator / payments
+   network) sources are preferred. Secondary sources (vendor DLP docs, Wikipedia) and
+   community sources (open-source validators, EMR forums) are acceptable only if marked
+   as such in `docs/entities.md` — and then the rule may *raise* a score but must not
+   *reject* a match (see `CanadianPatternRecognizer.unverified_check`).
+3. **Follow Presidio's conventions** so recognizers can be upstreamed:
+   one class per file, `COUNTRY_CODE = "ca"`, `PATTERNS` / `CONTEXT` class attributes,
+   the standard `__init__(patterns, context, supported_language, supported_entity, name)`
+   signature, a docstring with the format and a reference URL.
+4. **Portable regexes.** No look-arounds and no back-references, so that exports work
+   in Rust-based gateways (`check_contextforge_pattern` enforces this in tests).
+
+## Development setup
+
+```bash
+git clone https://github.com/ArthurJZL/canpii
+cd canpii
+uv sync
+uv pip install en_core_web_sm@https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl \
+               fr_core_news_sm@https://github.com/explosion/spacy-models/releases/download/fr_core_news_sm-3.8.0/fr_core_news_sm-3.8.0-py3-none-any.whl
+uv run ruff check . && uv run ruff format --check .
+uv run pytest
+uv run python benchmarks/run_benchmark.py
+```
+
+Tests that need spaCy models are marked `nlp` and are skipped automatically when the
+models are not installed; pattern-level tests always run.
+
+## Recipe: add a province or identifier
+
+Example: Manitoba PHIN (`CA_HEALTH_NUMBER`, province `MB`).
+
+1. **Source.** Find the format in an official document. Save the URL, the page/section,
+   and the exact wording. Decide the confidence level for each rule (official /
+   secondary / community).
+2. **Validator.** Add pure functions to `src/canpii/validators.py` — standard
+   library only, no Presidio import — with the provenance in the docstring, e.g.
+   `"""9 digits. [official]"""`.
+3. **Recognizer.** Create `src/canpii/recognizers/ca_mb_phin_recognizer.py`:
+   * subclass `CanadianPatternRecognizer`; set `ENTITY`, `PROVINCE`, `LABEL`,
+     `PATTERNS`, `CONTEXT` (English **and** French, single tokens, see `_context.py`);
+   * implement `verified_check` for official rules and `unverified_check` for the rest;
+   * choose base scores: ≥ 0.4 only for formats that are distinctive *and* validated,
+     0.05–0.3 for plausible formats, ≤ 0.01 for "any N digits" shapes (context-only).
+4. **Register.** Add the class to `ALL_RECOGNIZERS` in `recognizers/__init__.py` and a
+   `CatalogEntry` in `catalog.py`; run `uv run python scripts/generate_docs.py`.
+5. **Synthetic data.** Add a generator (and, if there is a checksum, a near-miss
+   generator) to `synthetic.py`, plus English and French templates.
+6. **Tests.** At minimum: valid / invalid / checksum cases at pattern level, English and
+   French sentences end-to-end, and collisions with phone numbers, dates, SIN and other
+   identifiers of the same length.
+7. **Docs.** Add a row to `docs/entities.md` (rule, confidence, source URL), update the
+   matrix in `docs/roadmap.md` and the table in `README.md`, and add a line to the
+   `Unreleased` section of `CHANGELOG.md`.
+8. **Benchmark.** Run `benchmarks/run_benchmark.py` and paste the table for your entity
+   into the PR description.
+
+## Pull request checklist
+
+- [ ] No real identifiers anywhere in the diff (including test data and docs).
+- [ ] Every new rule has a row in `docs/entities.md` with a source URL and confidence.
+- [ ] Unofficial rules only add score; they do not reject (unless `strict=True`).
+- [ ] English and French context words, and tests in both languages.
+- [ ] `uv run ruff check . && uv run ruff format --check .` passes.
+- [ ] `uv run pytest` passes (with spaCy models installed).
+- [ ] `CHANGELOG.md` updated under `Unreleased`.
+- [ ] Commits are signed off (`git commit -s`).
+
+## Developer Certificate of Origin (DCO)
+
+All commits must carry a `Signed-off-by:` line certifying the
+[Developer Certificate of Origin 1.1](https://developercertificate.org/): that you wrote
+the change or otherwise have the right to submit it under the project's license.
+
+```bash
+git commit -s -m "Add Manitoba PHIN recognizer"
+```
+
+The CI `dco` job checks every commit in a pull request. To fix a missing sign-off:
+`git commit --amend -s` (last commit) or `git rebase --signoff main` (several).
+
+**Do not copy code from other projects with incompatible licenses**, and do not copy
+code from open upstream Presidio pull requests: write your own implementation from the
+public specification and link the upstream PR in the description instead.
+
+## Upstreaming
+
+If your recognizer is backed by official sources and has been released here, consider
+proposing it to Presidio (`presidio-analyzer/presidio_analyzer/predefined_recognizers/country_specific/canada/`),
+following Presidio's `CONTRIBUTING.md`. Mention it in our issue tracker so we can
+deprecate the duplicate once it is merged.
+
+## Code of Conduct
+
+This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md).

canpii-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

canpii-0.1.0/NOTICE

@@ -0,0 +1,13 @@
+canpii
+Copyright 2026 Arthur Jin and canpii contributors
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).
+
+canpii extends Microsoft Presidio (https://github.com/data-privacy-stack/presidio),
+which is licensed under the MIT License. canpii does not copy Presidio source
+code; it subclasses Presidio's public APIs and, where noted, enables Presidio's own
+CaSinRecognizer and CaPostalCodeRecognizer at runtime.
+
+canpii is an independent community project. It is not affiliated with or
+endorsed by Microsoft, the Presidio maintainers, the Government of Canada, or any
+provincial government or agency named in its documentation.

canpii-0.1.0/PKG-INFO

@@ -0,0 +1,274 @@
+Metadata-Version: 2.5
+Name: canpii
+Version: 0.1.0
+Summary: Canadian PII recognizers (health numbers, passport, BN, bank, driver's licences) for Microsoft Presidio, with English/French context, LiteLLM/MCP-gateway exports and PIPEDA/PHIPA/Law 25 presets.
+Project-URL: Homepage, https://github.com/ArthurJZL/canpii
+Project-URL: Documentation, https://github.com/ArthurJZL/canpii#readme
+Project-URL: Repository, https://github.com/ArthurJZL/canpii
+Project-URL: Issues, https://github.com/ArthurJZL/canpii/issues
+Project-URL: Changelog, https://github.com/ArthurJZL/canpii/blob/main/CHANGELOG.md
+Author-email: Arthur Jin <arthurjin1998@gmail.com>
+Maintainer-email: Arthur Jin <arthurjin1998@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: anonymization,canada,de-identification,guardrails,law 25,litellm,loi 25,mcp,ohip,phipa,pii,pipeda,presidio,privacy,ramq,redaction
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Natural Language :: English
+Classifier: Natural Language :: French
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Security
+Classifier: Topic :: Text Processing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: presidio-analyzer>=2.2.365
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: anonymizer
+Requires-Dist: presidio-anonymizer>=2.2.365; extra == 'anonymizer'
+Description-Content-Type: text/markdown
+
+# canpii
+
+**Canadian PII recognizers for [Microsoft Presidio](https://github.com/data-privacy-stack/presidio):
+provincial health numbers, passport, CRA Business Number, bank routing and driver's
+licences, with English and French context, LiteLLM / MCP-gateway exports and
+PIPEDA / PHIPA / Quebec Law 25 presets.**
+
+[![CI](https://github.com/ArthurJZL/canpii/actions/workflows/ci.yml/badge.svg)](https://github.com/ArthurJZL/canpii/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/python-3.10%E2%80%933.13-blue)
+![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![Status](https://img.shields.io/badge/status-alpha-orange)
+
+## Why this exists
+
+Presidio is the de-facto open-source PII detector (the `presidio-analyzer` package has
+millions of monthly downloads), but for Canada it ships only two recognizers —
+`CA_SIN` and `CA_POSTAL_CODE` — and both are disabled by default. Canadian
+health numbers, driver's licences, passports, Business Numbers and bank details are
+not covered, while closed products (Microsoft Purview's PIPEDA/PHIPA templates, AWS
+Bedrock Guardrails' `CA_HEALTH_NUMBER`) do cover them.
+
+New country recognizers are merged into Presidio slowly, and that is reasonable for a
+project of its size. This package lets you **use Canadian recognizers today**, written
+in Presidio's own style, and we **upstream what Presidio accepts**.
+
+## Quickstart
+
+```bash
+pip install canpii
+python -m spacy download en_core_web_sm
+python -m spacy download fr_core_news_sm
+```
+
+```python
+from canpii import create_analyzer, get_preset
+
+analyzer = create_analyzer(languages=["en", "fr"])  # spaCy *_sm models, threshold 0.4
+text = "Carte RAMQ ZZZX 8812 2512, numéro d'entreprise 123456782 RT 0001."
+for r in analyzer.analyze(text, language="fr", entities=get_preset("quebec_law25").entity_list()):
+    print(r.entity_type, text[r.start : r.end], round(r.score, 2))
+```
+
+```text
+CA_BN 123456782 RT 0001 1.0
+CA_HEALTH_NUMBER ZZZX 8812 2512 0.85
+```
+
+Already have an `AnalyzerEngine`? Add the recognizers to its registry:
+
+```python
+from presidio_analyzer import AnalyzerEngine
+from presidio_anonymizer import AnonymizerEngine
+from canpii import register_all
+
+analyzer = AnalyzerEngine()  # your existing engine (Presidio's default uses en_core_web_lg)
+register_all(analyzer.registry, languages=("en",))
+text = "Patient OHIP 1234-567-897 AB, BC PHN 9000 000 018."
+results = analyzer.analyze(text, language="en", score_threshold=0.4)
+print(AnonymizerEngine().anonymize(text=text, analyzer_results=results).text)
+# Patient OHIP <CA_HEALTH_NUMBER>, BC PHN <CA_HEALTH_NUMBER>.
+```
+
+`register_all()` also enables Presidio's own `CaSinRecognizer` and
+`CaPostalCodeRecognizer`. Use a **score threshold of about 0.4**: weak,
+context-dependent patterns are scored well below it and only cross it when a
+context word ("OHIP", "carte santé", "permis de conduire", …) is nearby.
+
+No-code / YAML setup with Presidio's `RecognizerRegistryProvider`:
+
+```python
+import canpii  # registers the classes so `type: predefined` entries resolve
+from presidio_analyzer.recognizer_registry import RecognizerRegistryProvider
+
+registry = RecognizerRegistryProvider(
+    conf_file=canpii.recognizer_registry_yaml()
+).create_recognizer_registry()
+```
+
+## Supported entities
+
+| Entity | Province | Format | Validation | Format source | Languages |
+|---|---|---|---|---|---|
+| `CA_HEALTH_NUMBER` | ON (OHIP) | 10 digits + optional 1–2 letter version code | structure; Luhn as bonus only (community-sourced) | official | en, fr |
+| `CA_HEALTH_NUMBER` | QC (RAMQ / NAM) | 4 letters + 8 digits with embedded birth date | structure + birth-date check | official | en, fr |
+| `CA_HEALTH_NUMBER` | BC (PHN) | 10 digits starting with 9 | MOD-11 checksum | official | en, fr |
+| `CA_HEALTH_NUMBER` | AB (AHCIP) | 9 digits | context-only | official | en, fr |
+| `CA_PASSPORT` | federal | 2 letters + 6 digits | context-only | secondary | en, fr |
+| `CA_BN` | federal | 9 digits, or BN + RT/RP/RC/… + 4 digits | program id check; Luhn as bonus only (community-sourced) | official | en, fr |
+| `CA_BANK_ACCOUNT` | federal | `TTTTT-III` transit, `0IIITTTTT` routing, 7–12 digit account | context-only | official / secondary | en, fr |
+| `CA_DRIVER_LICENSE` | ON | 1 letter + 14 digits (`A1234-56789-01234`) | structure; birth date as bonus only | secondary | en, fr |
+| `CA_DRIVER_LICENSE` | QC | 1 letter + 12 digits | context-only | secondary | en, fr |
+| `CA_DRIVER_LICENSE` | BC | 7 digits | context-only (very weak) | secondary | en, fr |
+| `CA_SIN`, `CA_POSTAL_CODE` | federal | — | upstream Presidio recognizers, enabled by `register_all()` | — | en, fr |
+
+Every rule, with its source URL and confidence level, is in
+[`docs/entities.md`](docs/entities.md). Rules that are only **secondary** or
+**community-sourced** never reject a match on their own; they raise the score when
+they pass (pass `strict=True` to also reject on failure). Rules from **official**
+sources reject matches that fail them.
+
+Other provinces and territories are tracked in [`docs/roadmap.md`](docs/roadmap.md).
+
+## Gateways: LiteLLM, ContextForge and others
+
+```bash
+# LiteLLM presidio_ad_hoc_recognizers JSON (one copy per language)
+canpii export --format litellm --preset pipeda -l en,fr -o canpii_ad_hoc.json
+# LiteLLM config.yaml guardrail snippet (pii_entities_config for the preset, MASK)
+canpii export --format litellm-config --preset pipeda
+# IBM ContextForge PIIFilterPlugin custom_patterns (distinctive formats only)
+canpii export --format contextforge --preset phipa
+# Gateway-neutral regex + entity + score + context JSON
+canpii export --format generic
+# Presidio RecognizerRegistryProvider YAML (keeps full validation)
+canpii export --format presidio-yaml --preset quebec_law25
+```
+
+**Regex-only exports lose validation.** LiteLLM's ad-hoc recognizers and gateway
+custom patterns are plain regular expressions: BC's MOD-11 checksum, the RAMQ
+birth-date check, the Luhn bonuses and the negative-context filter do not travel with
+them. Expect more false positives than with the Python package. The ContextForge
+export keeps only patterns with a base score ≥ 0.3, because gateways without context
+support would otherwise redact every 7- to 12-digit number. All exported regexes avoid
+look-arounds and back-references so they also compile in Rust's `regex` crate.
+
+For LiteLLM, the Presidio analyzer server must have a French spaCy model loaded to use
+`presidio_language: fr`. If you can run your own analyzer image, `pip install
+canpii` into it and load the `presidio-yaml` export instead: you keep every
+check.
+
+## Policy presets
+
+| Preset | Law | Highlights |
+|---|---|---|
+| `pipeda` | PIPEDA (federal private sector) | identity, government and financial numbers, contact details |
+| `phipa` | Ontario PHIPA (health) | health numbers, names, contact details, dates and locations |
+| `quebec_law25` | Quebec P-39.1 as amended by Law 25 | as `pipeda` + dates; French first |
+
+```python
+from canpii import get_preset
+
+get_preset("phipa").entity_list()
+```
+
+Presets are **a starting point, not legal advice** — see [`docs/presets.md`](docs/presets.md).
+
+## Benchmark
+
+`benchmarks/run_benchmark.py` generates a labeled bilingual synthetic corpus (1,740
+sentences: 740 positives with and without context words, 1,000 negatives including
+phone numbers, dates, order IDs, amounts, near-miss identifiers and "hard negatives"
+that put a context word next to an unrelated number) and reports precision/recall at
+threshold 0.4.
+
+Positives **with context words** (seed 2026, `presidio-analyzer` 2.2.366, spaCy `*_sm`):
+
+| Entity | Gold | P (substring) | R (substring) | P (whole-word) | R (whole-word) |
+|---|---:|---:|---:|---:|---:|
+| CA_HEALTH_NUMBER | 160 | 0.870 | 1.000 | 0.870 | 1.000 |
+| CA_PASSPORT | 40 | 1.000 | 1.000 | 1.000 | 1.000 |
+| CA_BN | 40 | 1.000 | 1.000 | 1.000 | 1.000 |
+| CA_BANK_ACCOUNT | 100 | 0.714 | 1.000 | 0.714 | 1.000 |
+| CA_DRIVER_LICENSE | 120 | 0.909 | 1.000 | 0.909 | 1.000 |
+| CA_SIN (upstream) | 20 | 0.526 | 1.000 | 1.000 | 1.000 |
+
+All positives, including sentences **without** context words:
+
+| Entity | Gold | P (substring) | R (substring) | P (whole-word) | R (whole-word) |
+|---|---:|---:|---:|---:|---:|
+| CA_HEALTH_NUMBER | 240 | 0.896 | 0.863 | 0.896 | 0.863 |
+| CA_PASSPORT | 60 | 1.000 | 0.667 | 1.000 | 0.667 |
+| CA_BN | 60 | 1.000 | 0.933 | 1.000 | 0.933 |
+| CA_BANK_ACCOUNT | 160 | 0.714 | 0.625 | 0.714 | 0.625 |
+| CA_DRIVER_LICENSE | 180 | 0.921 | 0.778 | 0.921 | 0.778 |
+| CA_SIN (upstream) | 40 | 0.679 | 0.950 | 1.000 | 0.950 |
+
+How to read this:
+
+* **This is a regression benchmark on template sentences we wrote, not a real-world
+  accuracy estimate.** Scores and negative-context words were tuned on part of the
+  negatives; the remaining false positives come from an "untuned" set ("Patient chart
+  1234567890", "Bank statement page …", "Driver ID …") where a context word sits next
+  to an unrelated number — something no pattern recognizer can resolve.
+* Context-only identifiers (Alberta PHN, BC licence, bank account, passport) are
+  intentionally missed without context words; that is what lowers recall in the second
+  table.
+* "substring" vs "whole-word" is Presidio's context matching mode.
+  `create_analyzer()` defaults to whole-word: in substring mode, upstream `CA_SIN`'s
+  context word "sin" matches inside "**busin**ess", so every Business Number next to the
+  word "business" is also reported as a SIN.
+
+Reproduce with `uv run python benchmarks/run_benchmark.py --show-errors`.
+
+## Relationship to upstream Presidio
+
+* This is an independent community package, **not affiliated with Microsoft or the
+  Presidio maintainers**. It builds on Presidio's public APIs (`PatternRecognizer`,
+  `RecognizerRegistry`, `RecognizerRegistryProvider`) and follows its contribution
+  conventions: one recognizer class per file, `COUNTRY_CODE = "ca"`, per-language
+  instances, `invalidate_result` for checks, source URLs in docstrings.
+* Credit to the Presidio maintainers and to the upstream Canadian contributors:
+  `CA_SIN`, and `CA_POSTAL_CODE` (presidio#2204, by GitHub user watsos). We use those recognizers as
+  they are rather than reimplementing them.
+* **Business Number:** upstream issue presidio#2206 proposes a `CA_BN` recognizer and
+  PR presidio#2207 by GitHub user Joey239716 implements it (open since 2026-07-29). Our
+  `CA_BN` recognizer is an independent implementation written from the CRA
+  documentation and deliberately uses the same entity name, so switching is seamless.
+  **Once #2207 (or an equivalent) is merged, we will defer to upstream**: deprecate ours
+  for one minor release, then delegate.
+* Upstreaming plan: recognizers whose formats are backed by official sources (BC PHN,
+  RAMQ first) will be proposed to Presidio as individual PRs, in Presidio's code style,
+  once they have had real-world use here. See [`docs/roadmap.md`](docs/roadmap.md).
+
+## Disclaimer
+
+* **Not legal advice.** Presets and documentation describe engineering starting points.
+  Compliance with PIPEDA, PHIPA, Law 25 or any other law is your responsibility.
+* **Detection is probabilistic.** Pattern recognizers miss identifiers and flag
+  unrelated numbers. Do not rely on this package alone to protect sensitive data.
+* **Synthetic data only.** All identifiers in this repository, its tests and its
+  documentation are generated or obviously fake. Randomly generated values can still
+  coincide with issued identifiers; never use them as real identifiers. **Never commit,
+  paste or upload real identifiers** — not in issues, PRs, fixtures, screenshots or
+  logs. See [`SECURITY.md`](SECURITY.md).
+* Government programs and agencies are named only to describe the identifiers they
+  issue; no endorsement is implied.
+
+## Contributing
+
+Adding a province or identifier is a well-defined task — see
+[`CONTRIBUTING.md`](CONTRIBUTING.md) and the drafted good-first-issues in
+[`docs/issues/`](docs/issues/). Commits must be signed off (DCO).
+
+## License
+
+[Apache-2.0](LICENSE). Presidio is MIT-licensed; see [`NOTICE`](NOTICE).