custmatch 0.1.0__tar.gz

custmatch-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.

custmatch-0.1.0/NOTICE

@@ -0,0 +1,29 @@
+custmatch
+Copyright 2026 Andrew Goodchild
+
+Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+patches/ditto-mps-and-fixes.patch modifies Ditto (https://github.com/megagonlabs/ditto),
+Copyright Megagon Labs, licensed under the Apache License, Version 2.0. The patch contains
+lines of Ditto's source as diff context.
+
+No third-party datasets are included in the current tree. (Earlier commits in the history
+contained the nickname list below and a Wikidata name list, CC0, since removed.) custmatch
+downloads it into ~/.cache/custmatch (or $CUSTMATCH_DATA) when first needed:
+
+- nicknames.csv: the carltonnorthern/nicknames list (https://github.com/carltonnorthern/nicknames,
+  commit ed160b3), Copyright its contributors, licensed under the Apache License, Version 2.0.
+  Downloaded unmodified on first use and checked against its SHA-256.
+- profanity_en.txt: the English list of LDNOOBW, the List of Dirty, Naughty, Obscene, and
+  Otherwise Bad Words (https://github.com/LDNOOBW/List-of-Dirty-Naughty-Obscene-and-Otherwise-Bad-Words,
+  commit 5faf2ba), Copyright its contributors, licensed under CC BY 4.0. Downloaded unmodified
+  on first use and checked against its SHA-256; custmatch uses it without the words that are
+  real names (custmatch/suspect.py).
+
+
+Other datasets used by the research scripts are not included either. Scripts download or generate them (FEBRL and
+historical_50k via recordlinkage and splink, the Magellan / DeepMatcher and MatchGPT
+benchmarks from their own repositories, synthetic people via pseudopeople, name frequencies
+from the US Census and Social Security via the FiveThirtyEight data repository (CC BY 4.0)
+for the Australian test file), each under its own licence; see docs/reproducing.md. Files in results/ are metrics and logs computed from
+them.

custmatch-0.1.0/PKG-INFO

@@ -0,0 +1,277 @@
+Metadata-Version: 2.4
+Name: custmatch
+Version: 0.1.0
+Summary: Customer matching: contact profiling, blocking, a forest matcher tuned on clusters, households and golden records
+Author: Andrew Goodchild
+License-Expression: Apache-2.0
+Project-URL: Repository, https://github.com/andrewgoodchild/custmatch
+Project-URL: Documentation, https://github.com/andrewgoodchild/custmatch/blob/main/docs/guide.md
+Project-URL: Issues, https://github.com/andrewgoodchild/custmatch/issues
+Keywords: entity resolution,record linkage,deduplication,customer matching,householding
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+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: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: scipy
+Requires-Dist: scikit-learn
+Requires-Dist: rapidfuzz
+Requires-Dist: certifi
+Requires-Dist: pyarrow
+Requires-Dist: phonenumbers
+Requires-Dist: anyascii
+Requires-Dist: networkx
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: tomli; python_version < "3.11" and extra == "test"
+Provides-Extra: catboost
+Requires-Dist: catboost>=1.2; extra == "catboost"
+Dynamic: license-file
+
+# custmatch
+
+[![tests](https://github.com/andrewgoodchild/custmatch/actions/workflows/tests.yml/badge.svg)](https://github.com/andrewgoodchild/custmatch/actions/workflows/tests.yml)
+[![licence: Apache 2.0](https://img.shields.io/badge/licence-Apache%202.0-blue.svg)](https://github.com/andrewgoodchild/custmatch/blob/main/LICENSE)
+![python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)
+
+Find the records that are the same customer - across your CRM, billing and web sign-ups -
+group them into households, and write one golden record per customer.
+
+![One customer in the steward dashboard: the golden record, and the links between four records from three sources](https://raw.githubusercontent.com/andrewgoodchild/custmatch/main/docs/images/dashboard-customer.png)
+
+*One customer, John Citizen, found in four records from a web sign-up, the app and a store.
+The golden record at the top takes the best value of each field; "2 value(s)" marks where the
+records disagree, and a steward can pin the right one. Below it, each line is a link the model
+made between two records, green for a score of 0.9 or more, with the evidence in the table:
+"jack" in the app joined through the same email and phone. The dashed line is a* bridge *- the
+only link holding app:a003772 to the rest - so it is the one to check if the customer ever
+looks wrong.*
+
+## Why
+
+Customer-matching projects stumble on the same problems. Records arrive in different formats,
+with typos, nicknames and swapped names, and web sign-ups carry little more than a first name
+and an email. Contact details lie: "noemail@noemail.com" is on a hundred records, a family shares
+one email, a call centre typed in its own phone number. Spouses, parents and children, twins
+and two John Smiths look like one person; one weak link chains strangers into a giant customer;
+nobody can say why two records were merged; a steward's correction is lost on the next run;
+customer IDs churn downstream; and the data is personal. custmatch is built around those
+problems: junk and shared contacts are recognised rather than trusted, households are kept
+apart from people, the match threshold is judged on whole customers so it cannot chain, every
+link is explained, decisions and IDs survive reruns, and contacts can be matched hashed.
+
+## How it works
+
+```
+records ─► clean & normalise ─► profile contacts ─► blocking ─► compare pairs ─► random forest
+                                                                                      │
+golden records ◄─ households ◄─ customers ◄─ threshold chosen on whole customers ◄────┘
+```
+
+- **Clean and normalise** names, phones, dates, emails and addresses by country (US, AU, NZ, GB,
+  CA): nicknames, transliteration, Gmail dots, phone formats.
+- **Profile contacts**: each email and phone is personal, a household's, or junk - judged by who
+  shares it, so junk and shared values stop counting as proof.
+- **Blocking** compares only records that share a key (a surname and street, an email...), so a
+  million records make millions of pairs, not half a trillion.
+- **Compare pairs** with name similarity, rarity and graded dates; a **random forest** learns
+  from a few hundred labelled pairs (active learning picks the useful ones).
+- **Threshold on whole customers**: links are joined into customers, and the threshold is the
+  one whose *customers*, not pairs, are most accurate - the project's central finding.
+- **Households** group customers by address and shared contacts; a **golden record** takes the
+  best value of each field.
+
+[docs/guide.md](https://github.com/andrewgoodchild/custmatch/blob/main/docs/guide.md) explains each step.
+
+## Results
+
+| 10 million records | 1 million records | Messy customer data | Ensemble option |
+| :---: | :---: | :---: | :---: |
+| **31 minutes** on one 16-core machine, **96.89** clustered F1 | **71 seconds** on a laptop, **97.99** clustered F1 | **97.3** clustered F1, against [Splink](https://github.com/moj-analytical-services/splink)'s 84.4 | **+0.41** F1 on average, **+1.8** on sparse records |
+
+<sub>The two sizes ran on different machines: per record the laptop was about 2 to 2.6 times faster than
+the cloud machine. On one machine, time per million records rose by about a quarter from 2 to
+10 million, most of it in the household and golden-record stage.</sub>
+
+**Where it is stronger**
+
+- **Messy customer data.** Placeholder, shared and household contacts are recognised, not
+  trusted, so they stop chaining strangers together: at a million records custmatch scores
+  97.99 clustered F1 where Splink scores 78.88, and against a CDP's exact-identifier matching it
+  finds 22 to 26 more points of the true matches.
+- **It keeps going.** Accuracy holds as the file grows - 97.99 at a million records, 96.89 at
+  ten million, on one machine. [dedupe](https://github.com/dedupeio/dedupe), about as accurate on 20,134 records (97.75), took 499
+  seconds and 8.5 GB there against custmatch's 5.4 seconds and 0.35 GB, so a million records was
+  out of reach on the same 16 GB laptop.
+- **Modest memory.** A million records peak at 3.64 GB on a laptop (Splink: 5.96 GB); ten million
+  at 34.0 GB, about 3.4 GB per million, so a 16 GB laptop holds about four million. dedupe
+  needed 8.5 GB for 20,134 records.
+- **An ensemble for hard files.** `"matcher_model": "forest_catboost"` averages the random forest
+  with CatBoost: +0.41 clustered F1 on average over six datasets, +1.3 on dense genealogy records
+  and +1.8 on sparse sign-ups, never more than 0.03 behind on any dataset, for runs about 30%
+  longer.
+
+**Where others win.** Splink needs no labels and is faster once its large blocks are skipped
+(21.6 seconds at a million records), and it can run on Spark across a cluster: its developers
+matched a billion records that way. custmatch runs on one machine - about 3.4 GB per million
+records, so tens of millions, not hundreds. On clean records with names and places only, the tools
+are close.
+
+The [report](https://github.com/andrewgoodchild/custmatch/tree/main/docs/report) has the full
+comparison - against Splink, dedupe and a CDP's exact matching, on these files and on each tool's
+own datasets - with every caveat: the synthetic and Australian files were generated for this
+project, so their errors are ones the tool was designed around, and it needs good labels. The
+test suite checks every number against `results/*.json`.
+
+## Quick start
+
+```bash
+pip install custmatch                 # Python 3.10+ (or from a clone: pip install -e .)
+# try it on the bundled demo (1,766 synthetic records, 600 pairs already labelled):
+custmatch run examples/demo/config.json --labels examples/demo/labels.csv --out demo_out/
+
+# on your own files: map the columns in a config, label pairs 1 or 0, run
+custmatch sample config.json --n 300 --out to_label.csv
+custmatch sample config.json --active to_label.csv --n 100 --out more.csv   # the most useful pairs next
+custmatch run config.json --labels labels.csv --out results/
+```
+
+`config.json` maps your files' columns onto custmatch's fields; `examples/demo/config.json` is a
+small working example, and all example data is synthetic (`examples/README.md`). For sparse
+records - only a first name plus an email or mobile - add `"country": "AU"` (or your country's
+code) and label with `sample --active`: on a sparse Australian test file that took clustered F1
+from 54.9 to 81.7 (`examples/au/config.json`). The run writes `clusters.csv` (customer and
+household per record), `golden_records.csv`, `links.csv` (every link with its evidence, weakest
+first), `suspect_records.csv` and a `summary.json` with warnings.
+
+## The service: custmatch-server
+
+The library runs a batch over files. **custmatch-server** runs it as a self-hosted service next to
+your data - one Docker image, one database (Postgres, or SQLite for a trial):
+
+- **Source records and their loads** kept in the database, every version of every record; files
+  dropped in an inbox loaded and the batch run on a schedule, with health checks and alerts.
+- **Real-time matching and lookups** over HTTP (`POST /match`, `GET /records/...`), consistent
+  with the batch run, which reconciles every real-time decision.
+- **A steward dashboard**: the review queue with a breakdown of every score, customers as a
+  network of links, merge and split with previews, pinned golden-record values, decisions that
+  train the next run, approval by a second steward, the model's accuracy and the data's quality
+  - every chart with an explanation of how it is calculated and what good looks like.
+- API keys with roles, an audit log of every steward action.
+
+```bash
+docker compose -f server/docker-compose.yml up -d --build db api   # then see server/README.md
+```
+
+![The review queue: two records side by side, and why the model scored them 53%](https://raw.githubusercontent.com/andrewgoodchild/custmatch/main/docs/images/dashboard-review.png)
+
+*The review queue shows the pairs the model was least sure of, closest calls first. Both records
+here say Jane, but the web sign-up has only an email and a postcode, the app record a
+surname, a birth date and a mobile, and they share nothing else. The chart explains the 53%:
+from the base rate, the agreeing first name pushes the score up, and the missing surname and
+unshared contacts pull it back below the threshold (the yellow line), where the model kept them
+apart. A steward answers* Same person *or* Different
+people*; the answer applies at once and teaches the next run.*
+
+![The model's accuracy against the threshold, and how its scores are spread](https://raw.githubusercontent.com/andrewgoodchild/custmatch/main/docs/images/dashboard-model.png)
+
+*How well the model is doing, and where its line is drawn. Each pair of records gets a score from
+0 to 1, and the* threshold *is the score above which two records count as one person. The left
+chart moves that threshold from 0 to 1: raise it and* precision *(blue - of the records joined,
+the share that truly are one person) rises while* recall *(green - of the true matches, the share
+found) falls. The dashed line is where custmatch set it, the point where the two balance best
+(F1, white), judged on whole customers: here an estimated 91.65% precision and 93.51% recall.
+The right chart counts the pairs at each score. A confident model puts most pairs near 0
+(clearly different) or near 1 (clearly the same); the few in the middle are the ones it sends
+to the review queue.*
+
+[server/README.md](https://github.com/andrewgoodchild/custmatch/blob/main/server/README.md) is the operator guide;
+[the report's chapter on the service](https://github.com/andrewgoodchild/custmatch/blob/main/docs/report/12-the-service.md) what it was measured at.
+
+## Features
+
+**Key:** ✅ done and measured · ◐ opt-in · ❌ not built yet.
+
+### Matching
+
+| Feature | Status | Notes |
+| --- | --- | --- |
+| Learns from your labelled pairs; the threshold is chosen on whole customers, which stops chaining | ✅ | The project's central finding |
+| Active learning: it picks the pairs worth labelling | ✅ | Essential on sparse records |
+| Country profiles: US, AU, NZ, GB, CA, several per file | ✅ | Phones, dates, emails, postcodes, SSN checks, nicknames |
+| Name variation: nicknames, typos, swapped names, accents, Chinese and Arabic script | ✅ | |
+| Junk and placeholder contacts ignored (test@test.com, 0400 000 000) | ✅ | Bought "gold" numbers kept; placeholder names and addresses opt-in |
+| Sparse records: a first name and an email or mobile | ✅ | |
+| Households: couples, families, shared phones and emails | ✅ | |
+| Large entities that share every key (an organisation with hundreds of records) | ✅ | Checked by the model, not skipped as junk |
+| Suspect records flagged for review: profanity, disposable or random-looking emails | ✅ | `suspect_records.csv`; never changes a match |
+| Twins kept apart | ◐ | `"twin_guard"` |
+| Safe contact details: a precision target, and contacts taken only through certain links | ◐ | `"min_precision"`, `"contact_confidence"`, `contacts.csv` |
+| One record per person in a duplicate-free source (a voter roll, a loyalty scheme) | ◐ | `"unique_sources"` |
+| Trusted IDs: same loyalty or customer number, same person | ✅ | `"trusted_ids"` |
+| Record dates: moves, name changes, reissued mobiles | ◐ | `"record_dates"` |
+| Cookie and device-ID stitching, with shared-device and call-centre guards | ✅ | `"identity_events"` |
+| A forest and CatBoost averaged, for hard and sparse files | ◐ | `"matcher_model": "forest_catboost"` |
+| Address verification against official files (G-NAF, USPS) | ❌ | Needs licensed reference data |
+| Business (B2B) matching: companies and their contacts | ❌ | People and households |
+
+### Golden records
+
+| Feature | Status | Notes |
+| --- | --- | --- |
+| A golden record per customer, with survivorship rules per field | ✅ | Most recent, most common, preferred sources with a fallback |
+
+### Operating over time
+
+| Feature | Status | Notes |
+| --- | --- | --- |
+| New, updated and deleted records without a full rerun | ✅ | `custmatch add`, `--delete` |
+| Stable customer IDs with a history of merges and splits | ✅ | Records stop swapping between people as data arrives |
+| Review queue for uncertain pairs | ✅ | `review.csv` |
+| Steward overrides and unmerge, kept across runs | ✅ | `"overrides"` |
+| Monitoring: match rates and drift across runs | ✅ | `custmatch monitor` |
+| Real-time matching and lookup | ✅ | custmatch-server: `POST /match`, `GET /records/...` |
+| Steward dashboard, scheduled runs, health checks and alerts | ✅ | custmatch-server |
+
+### Trust and privacy
+
+| Feature | Status | Notes |
+| --- | --- | --- |
+| Why two records were, or were not, matched | ✅ | `links.csv`, `custmatch explain` |
+| Matching on hashed emails, phones and IDs | ✅ | `"hash_fields"` |
+| Result files without names or contacts: record keys and evidence only | ◐ | `"minimal_outputs"`; the saved state that `custmatch add` needs still holds the records |
+| Erasure requests | ✅ | `custmatch forget` |
+
+## Documentation
+
+| | |
+| --- | --- |
+| [docs/guide.md](https://github.com/andrewgoodchild/custmatch/blob/main/docs/guide.md) | Using custmatch: how it works, step by step; your config, labels and a run; running it over time; every option; a glossary |
+| [docs/report/](https://github.com/andrewgoodchild/custmatch/tree/main/docs/report) | The research: what was found, then one chapter per question - whole customers not pairs, which matcher, labels, fake contacts and households, blocking and scale, golden records, CDPs, other tools - and reproductions of published work |
+| [docs/reproducing.md](https://github.com/andrewgoodchild/custmatch/blob/main/docs/reproducing.md) | Rebuilding the datasets, rerunning every experiment, the test suite, and reproduction traps |
+| [server/README.md](https://github.com/andrewgoodchild/custmatch/blob/main/server/README.md) | Running custmatch-server: start it, load data, keys, schedules, the dashboard, monitoring, backup, upgrades |
+
+## Tests
+
+```bash
+pip install -e '.[test]' && pytest tests/
+pip install -e ./server httpx              # the service's tests too
+```
+
+The suite includes a check that every number quoted in the docs still matches `results/*.json`.
+
+## License
+
+[Apache 2.0](https://github.com/andrewgoodchild/custmatch/blob/main/LICENSE).