Namesake
A bank screens its customers against sanctions, PEP and adverse-media lists. Most alerts are namesakes: someone else with a similar name. Namesake reads each alert, works out who the customer really is and who the listed person really is, and answers one question per hit: same person, different person, or not sure.
It clears a hit only when it can prove the two are different people. Everything else goes to a human.
system/run <data folder> <output file> # macOS, Linux; Python 3.9+, nothing to install
python system/run <data folder> <output file> # Windows, or machines with only "python"
OPENROUTER_API_KEY is optional. Without it the system still writes a valid answer for every hit.
Live: https://dev-87520--namesake-web.us-east.modal.run
Try it in two minutes
You need Python 3.9 or later and nothing else: no pip, no npm. The dev dataset, the built UI and the last run's results are all in the repo.
git clone https://github.com/1337Xcode/namesake.git && cd namesake
python3 start.py test # runs the engine on the dev data and scores it: expect 50/50 right, 0 unsafe
python3 start.py # opens the analyst UI at http://127.0.0.1:8787
The first time you run it, start.py creates .env. Paste an OPENROUTER_API_KEY there for the full run. Without a key, everything still runs; free-text notes just go unread, so more hits stay in REVIEW. On Windows, use python instead of python3. In the UI, Run starts the engine for real and shows its progress live.
You can also call the engine directly with system/run <data folder> <output file>. To host it yourself on Modal, run modal deploy modal_app.py (needs modal and python-dotenv). To change the UI, run npm install && npm run build in ui/.
What it does, in plain terms
Think of an analyst with a rulebook (the bank's POLICY.md) and five filing cabinets: customer records, accounts, onboarding, ID checks and support notes. For each hit they:
- find every record that belongs to this customer, and trust the passport check over what the customer typed in;
- collect what the watchlist knows about the listed person: names, birth dates, countries, dated reports;
- look for one fact that rules the match out (born too late, wrong country, a different verified name);
- if nothing rules it out, check whether the name and birth date actually agree;
- write down the answer, the reason, and the record IDs it relied on.
Namesake does exactly that, in code. A language model helps with one step only: reading free-text notes and sentences, the way a junior analyst might highlight the date in a paragraph. It never makes the call.
How it works
flowchart LR
A[Alert] --> R[Who is the customer?<br/>links, search, merged records,<br/>verified beats declared]
H[Hit] --> F[Who is the listed person?<br/>names, birth dates,<br/>countries, dated reports]
T[Notes, profile text,<br/>search snippets] --> X
subgraph X[Read free text]
P[Patterns] --> M[[Model, two prompts<br/>must agree]]
end
X --> R
X --> F
R --> C[Checks from POLICY.md<br/>with safety gates]
F --> C
C --> D{Decision}
D --> DE[Different person]
D --> SE[Same person]
D --> RV[Review]
| Decision |
When |
Cost if wrong |
| Different person (cleared) |
A fact contradicts the match and every safety gate passed |
60, the costly mistake |
| Same person |
Name and birth date agree (companies: name and country) and nothing contradicts |
2 or 3 |
| Review |
Anything else |
2 or 3 |
One wrong clearance costs as much as twenty missed ones. Every design choice follows from that ratio.
The ontology
The system keeps a small, explicit model of the world, so every answer traces back to a record.
erDiagram
ALERT ||--o{ HIT : raises
ALERT }o--o| ACCOUNT : "links by account or login"
ALERT }o--o| CUSTOMER_RECORD : "links by email"
PERSON ||--|{ CUSTOMER_RECORD : "merges"
CUSTOMER_RECORD ||--o{ ACCOUNT : holds
CUSTOMER_RECORD ||--o{ KYC_CHECK : "verified by"
CUSTOMER_RECORD ||--o{ NOTE : "filed under email"
HIT ||--o{ SEARCH_RESULT : "found by name"
PERSON ||--o{ FACT : has
HIT ||--o{ FACT : has
CHECK }o--|| PERSON : compares
CHECK }o--|| HIT : compares
- A person is not a record. Records that share a phone and the same full birth date, or the same approved document number, become one person. A shared phone alone merges nothing, because families share phones.
- Facts carry provenance: the value, the ID it came from, the quoted text, and how it was read (
structured, regex or llm).
- Checks are relations between facts. Type, Death, Time, DOB, Name and Location each return
CONTRADICTS, AGREES, UNKNOWN or BLOCKED.
- The decision is a function of the checks, written once, in
decide.py.
Details in docs/ONTOLOGY.md.
Why the policy is the source of truth
The organisers labelled the data by applying POLICY.md, so the best possible system is that policy executed exactly, clause by clause. Each check in the code cites its clause (P2 to P9). Where the policy is ambiguous we take the reading that does not clear, and switch only when a practice label shows otherwise. Those choices are the interpretation register in system/README.md.
Questions we get asked
Why not let a language model decide?
It reads well and combines badly. A 2026 study of fast decision models found most of their errors came after they had read every fact correctly, at the step where facts are combined (arXiv:2610.18579). Models are also not reproducible enough for a score that needs five identical runs. Here the model only copies values out of text. Code checks that each value appears in the text, and two differently worded prompts must return the same value before it is used.
Why not a fuzzy-matching score, like Splink or a weighted similarity?
A score answers "how similar are these?", and the bank asks something else: is there a fact that proves they differ? The policy defines matching exactly, down to edit distances and which name variants count. A learned weight would drift from it, and a score cannot cite the record that decided it.
Isn't a rule engine brittle on messy real data?
The rules are the bank's, so the risk is in reading the data. That is where the hardening went: ambiguous dates, assigned 1 January birthdays, transliterations, US state codes in addresses, translated country names, malformed files. Each of those guards can only turn a clearance into a review. A stress suite of 277 synthetic cases with known answers, plus 13 model-fault modes, tests them.
Why so many reviews?
On dev about 55% of hits are cleared, 15% confirmed and 30% reviewed. A review costs 3 if the hit really was a namesake; a wrong clearance costs 60. We clear what we can prove.
Why not fine-tune a model on the labels?
There are 50 labels. A model tuned on them would learn this folder's wording, and the unseen set is reworded.
What happens without an API key, or if the provider is blocked?
A startup probe notices in one call, and the run continues without the model. Text the patterns cannot read stays unread, which can only keep hits in review.
How do you know it works?
Practice labels: 50 of 50, with 0 unsafe clearances. Five runs are byte-identical, and shuffled input gives identical output. Reworded notes leave 98.9% of decisions unchanged with no new clearances, and messier formats leave all 819 unchanged. The stress suite still has 13 open unsafe cases. Each one is written up with a proposed fix in docs/REDTEAM.md.
What would you do next?
Close those 13 cases (most are reading errors, such as a relative's age read as the listed person's), and add candidate blocking so the customer search stays fast past a million records.
Results
| Measure (dev set) |
Result |
| Practice labels |
50 of 50, 0 unsafe clearances |
| Five runs, shuffled input |
identical, identical |
| Reworded free text |
98.9% unchanged, 0 new clearances |
| Format perturbation |
819 of 819 unchanged |
| Time and cost |
about 64 s and $0.02 for 819 hits |
Every number is generated by tools/report.py into docs/RESULTS.md.

Where to look next
The organisers' data is not in this repository (participant access only).