edgepiityped character spans
taxonomy 2026.11 GitHub

edgepii specification

Start with the 5 November research update and the grounded improvement plan for the current research, implementation status, and validation evidence. The earlier landscape and catalog remain historical inputs; model-card numbers are not release gates. Continue with next-stage AI engineering for the next priorities, corrected PII-Tracer availability, and additional candidates. The protection implementation and new measurements record the subsequent code and Modal experiments. The 0.4.0 release guide covers PyPI installation and verification of the protection APIs from the distributed package. Continue with improvement research after 0.4.0 for compact models, measured int4 parity, paired coverage, and revised priorities. The 0.5.0 protection readiness update implements output-path gates and traces the observed projection losses on Modal.

Status: implemented. This set records the problem, the research, the public API, and the build plan. The library, the tests, and the demo now follow this set. See the project README for install and quickstart.

edgepii is a Python library that locates personally identifiable information (PII) in text. The library returns typed character spans on the same string the caller passed. The library does not decide that a whole document is sensitive.

This set records the problem, the research, the public API, and the build plan. Card scores in the research notes are not ship gates. See the evaluation spec.

Read this set in order

  1. Five whys. The problem, one cause at a time.
  2. Span contract. The only result the library can return.
  3. First principles. Rules that stay true when models change.
  4. AI engineering. How the team chooses and rejects a model.
  5. Research landscape. Papers and lanes, as of November 2026.
  6. Model catalog. Hugging Face and ModelScope candidates.
  7. Taxonomy. The versioned type list and the label maps.
  8. Public API. Call shapes and errors.
  9. Examples. Fake text that shows each preset.
  10. Public corpora. The pinned PII sets and the label fold.
  11. First public score. Two lanes, two corpora, measured.
  12. Architecture. Modules, DRY, and SOLID.
  13. Implementation plan. Build order and acceptance tests.
  14. Evaluation. Exact-span F1, slices, and ship gates.
  15. Glossary. One name for each concept.
  16. Research update, 5 November 2026. Verified papers, current model candidates, and benchmark qualifications.
  17. Grounded improvement plan. First-principles acceptance criteria and Modal validation.
  18. Next-stage AI engineering. Coverage policy, calibration, and the next model experiments.
  19. Protection and model results. Opt-in protection API and measured new candidates.
  20. Release 0.4.0. PyPI installation, upgrade, and artifact verification.
  21. Improvement research after 0.4.0. Actual Modal compact-model and complementary-coverage experiments.
  22. Protection readiness and 0.5.0. Emitted-output gates, stage attribution, and release verification.

Decisions:

Decision in one page

Keep a locator that returns {type, start, end, text, score} on the source string. Ship two default lanes after a frozen golden set, not before it.

LanePresetWeightsUse when
Closed encoderen-closedantoniogr7/pii-identifier-v0.1The team freezes the type list, the text is English, and latency matters
Open schemamulti-openfastino/gliner2-privacy-filter-PII-multiThe caller must change types at call time

A classic BERT control stays available as preset en-bert (ab-ai/pii_model). BERT-family token classification is enough when the taxonomy and the domain stay fixed. See when the encoder is enough.

Rules for email, phone, IBAN, and payment cards run beside the model. They do not replace it for names. Chinese schema extraction is an optional ModelScope adapter, not a default. See the catalog.

Assessment, November 2026

The current release is 0.5.0. It locates spans, masks them, restores reversible values, and offers opt-in coverage-preserving protection. The span contract holds. The assessment records what is measured, three defects that a reader can reproduce, and where the field moved ahead of the library: the tool-call plane, surrogate replacement, and quasi-identifier combinations. The latest research audit qualifies the SPY government-ID and author-only evaluation semantics; read that erratum before interpreting the older scores as deployment measurements.

What v1 will not do

V1 will not send the source string to a cloud PII API. V1 will not ask a chat model to rewrite the text. V1 will not treat a document label as success. V1 will not copy a leaderboard F1 into a ship gate. The numeric floors stay open until the golden set exists. Call that open state UNCONFIRMED.

Terms

Use the names in the glossary. Do not rename a span to an entity, a hit, or a finding in this set.