What the model cannot do

The question

Everything else on this shelf explains how the parser reads an address. This page is the other half: the inputs where it is wrong, the questions it is not answering, and the cases where the rule-based approach you were about to replace is still the better tool.

Every claim below was produced by running the shipped parser. The wrong answers are real output, not constructed examples.

The analog

A postal sorting machine reads what it can and passes the rest to a person. The machine's designers did not consider that a defect, because the machine's job was never to be right about everything — it was to be right about most things, fast, and clear about which envelopes it was handing over.

The parser has no equivalent hand-off, and that is the single most important thing to know about it. There is no envelope it declines. Everything below follows from that.

It never abstains

Every stagestageOne of the dataflow stages in the runtime pipeline (normalize, locale gate, kind classify, phrase group, token classify, sequence correct, reconcile, resolve). Distinct from tier (model vocabulary) and phase (plan milestone). produces scores, and a set of scores always has a maximum, so there is always an answer. The parser has no "this is not an address" output and no failure mode that looks like a failure.

the blue house past the church     →  locality = "The Blue House Past The Church"

That is a working address in places where houses have no numbers, and it is not malformed. The parser returns the best address-shaped reading of it, with a score attached, and the score is about how confidently it read the string that way — not about whether reading it that way was sensible. A string of product SKUs will parseaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates.. So will a sentence.

If your input can contain things that are not addresses, that classification is yours to make upstream, and the parseaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates. result is not the place to make it.

It says nothing about existence or delivery

What Mailwoman is states the boundary and it is worth restating with the mechanism: a parseaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates. tells you a string reads like an address and where the components sit. It does not consult a registerinput modeThe Decision-A register switch: 'fragmented' (human-typed fragments — feeds the evidence channels) vs 'formatted' (complete records — runs the trained absence identity). Explicit on CLI/API; per-endpoint defaults (batch→formatted, autocomplete→fragmented); kind-derived otherwise. of real delivery points, because it does not have one — those are licensed products from postal authorities, and open data does not substitute for them.

The failure mode is specific. A completely invented address parsesaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates. with high scores on every component:

42 Nonexistent Ln, Zzyzx Falls, ZZ, 00000
  locality       0.923
  street         0.921
  postcode       0.914
  house_number   0.908
  street_suffix  0.891
  region         0.462

Five of the six components are scored like a correct parseaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates., because as a piece of reading the parseaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates. is correct — Zzyzx Falls really is where a localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy. goes. Only ZZ is scored down, and only because it does not look like a state code. Those figures are the raw scan on Tune confidence thresholds, where the same row is used to show that the signal is there and the scale is what needs fixing.

Existence is a different question with a different tool. Validate an address before you use it covers what can be checked, and geocodinggeocodingThe process of converting an address into geographic coordinates (latitude and longitude). Mailwoman geocodes in a multi-tier cascade: exact address-point match → street interpolation → locality centroid. Each tier is progressively coarser but more widely available.'s resolution tier tells you what the coordinate is grounded in.

Some ambiguity cannot be removed by anything

A share of inputs do not contain the information required to parseaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates. them, and no modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.', gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture. or rule fixes that. Three shapes recur.

A bare name. springfield returns a localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy., which is a reasonable reading and could be any of dozens of places. The parseaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates. is not wrong; the input is under-determined, and the right response is a result that says so rather than a better guess.

A digit with no owner. A number beside a name has at least two readings, and a short input carries no evidence for either:

1600 Pennsylvania    →  postcode = "1600",  region = "Pennsylvania"

Both readings of that pair are defensible. Pennsylvania is a state, and a four-digit leading number is a postcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one. shape in several countries. Add the one tokentokenOne word or subword in the tokenized input. For the neural classifier, tokens come from SentencePiece (subword units); for the rule classifiers, tokens are whitespace- and punctuation-separated words. that decides it — 1600 Pennsylvania Ave — and the reading changes, because the evidence arrived. This is the general shape of the hardest class: the number's owner is determined by the tokenstokenOne word or subword in the tokenized input. For the neural classifier, tokens come from SentencePiece (subword units); for the rule classifiers, tokens are whitespace- and punctuation-separated words. around it, and when they are absent nothing recovers it.

A name doing a job other than naming its own place. A venuevenueA named, non-address place — a business, building, park, or stadium. Mailwoman's free-text point-of-interest component, added as a Tier 2 fine label. called after a citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy., a streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. named after a state. Why addresses are hard is the full treatment of why this is structural rather than a backlog.

Locale and script boundaries are hard, and quiet

The modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' was trained on Latin-script text, and its trainingtrainingThe process of adjusting a model's parameters so its predictions match labeled examples, by repeatedly measuring error and nudging the weights to reduce it. Distinct from inference, when the trained model is run on new input. corpuscorpusThe BIO-labeled training data used to train Mailwoman's neural classifier. Assembled from real sources (OpenAddresses, National Address Database) and synthetic shards (boundary stress, order variants, negative space). Managed by @mailwoman/corpus. is uneven across the countries it does cover. Two different limits follow.

A localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. with thin trainingtrainingThe process of adjusting a model's parameters so its predictions match labeled examples, by repeatedly measuring error and nudging the weights to reduce it. Distinct from inference, when the trained model is run on new input. data reads worse, and does not say so. The tier table is the map: a localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. is claimed when a coordinate-graded evaluationevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. exists for it, and trained exposure is not a claim. Reading down the tiers tells you how much of a measurement sits behind any given countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head..

A script outside the trainingtrainingThe process of adjusting a model's parameters so its predictions match labeled examples, by repeatedly measuring error and nudging the weights to reduce it. Distinct from inference, when the trained model is run on new input. data produces a confident wrong reading, not an error. The tokenizertokenizerThe component that converts a raw address string into a sequence of numeric token IDs the model can process. Mailwoman's tokenizer is a SentencePiece unigram model trained specifically on postal addresses. encodes unknown characters byte by byte, so the pipelinestaged pipelineMailwoman's runtime architecture: a sequence of pure-function stages (normalize → query-shape → locale-gate → kind-classifier → phrase-grouper → classifier → decoder) connected by typed handoffs. Each stage is published as its own npm package. never crashes — and the piecesECE (Expected Calibration Error). A metric that measures how well a model's confidence scores align with its actual accuracy. Lower is better. Mailwoman's held-out ECE drops from 0.067 (raw) to 0.0035 (calibrated). it produces carry no learned meaning:

東京都千代田区丸の内1丁目      →  locality = "東京都千代田区丸の内1丁目"
서울특별시 중구 세종대로 110    →  locality = "서울특별시 중구 세종대로 110"
Тверская улица 7, Москва      →  locality = "Москва",  street = "Тверская улица 7"

The first two collapse the whole address into one localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy.. The third gets the citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy. right and leaves the house numberhouse numberThe numeric or alphanumeric identifier of a building on a street. Mailwoman's house_number component; its position relative to the street name flips between locales. inside the streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.. Every one of them returns a well-formed tree with a confidence on it. Byte fallbackbyte fallbackA tokenization strategy where characters not seen during training are encoded as raw UTF-8 byte sequences rather than mapped to an unknown token. Mailwoman's tokenizer uses byte fallback so non-Latin scripts (CJK, Cyrillic) produce real token sequences even though training data was Latin-dominant. is what stops a crash; it is not coveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present. of the script, and the two are easy to mistake for each other because they look identical from the outside.

The input register is bridged, and the bridge is narrow

Users type in lowercase. The trainingtrainingThe process of adjusting a model's parameters so its predictions match labeled examples, by repeatedly measuring error and nudging the weights to reduce it. Distinct from inference, when the trained model is run on new input. corpuscorpusThe BIO-labeled training data used to train Mailwoman's neural classifier. Assembled from real sources (OpenAddresses, National Address Database) and synthetic shards (boundary stress, order variants, negative space). Managed by @mailwoman/corpus. is labeled in mixed case. The parser closes that gap deterministically before the modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' runs: a fully lowercase pure-ASCII input is restored to canonical mixed case, with words of three or more letters title-cased and words of one or two letters uppercased, so dc reaches the modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' as DC. A shouting all-caps input is handled by the mirror of the same pass, which title-cases the long words and leaves the short ones shouting, since those are already the form the corpuscorpusThe BIO-labeled training data used to train Mailwoman's neural classifier. Assembled from real sources (OpenAddresses, National Address Database) and synthetic shards (boundary stress, order variants, negative space). Managed by @mailwoman/corpus. uses for state codes and directionals.

The restriction is in the phrase pure ASCII. Case conversion outside ASCII is language-dependent and can change a string's length, which would break the character offsets the whole result is built on, so an input containing any non-ASCII character is left exactly as typed. The consequence is visible:

montreal qc     →  locality = "Montreal",   region = "QC"
montréal qc     →  locality = "montréal"

One accent, and the regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. is gone — the restoration did not run, so qc reached the modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' in a form it has little trainingtrainingThe process of adjusting a model's parameters so its predictions match labeled examples, by repeatedly measuring error and nudging the weights to reduce it. Distinct from inference, when the trained model is run on new input. signal for, and there was no comma to supply the structure instead. Add the comma back and montréal, qc recovers the regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality., in the lowercase form it arrived in.

Lowercase is the registerinput modeThe Decision-A register switch: 'fragmented' (human-typed fragments — feeds the evidence channels) vs 'formatted' (complete records — runs the trained absence identity). Explicit on CLI/API; per-endpoint defaults (batch→formatted, autocomplete→fragmented); kind-derived otherwise. real users type, not degraded input. The bridge covers the ASCII majority of it. Accented lowercase is the gap, and it is largest in exactly the languages that use accents most.

Long input is truncated in silence

The modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' reads a fixed window of 128 piecesECE (Expected Calibration Error). A metric that measures how well a model's confidence scores align with its actual accuracy. Lower is better. Mailwoman's held-out ECE drops from 0.067 (raw) to 0.0035 (calibrated).. Beyond that, the input is cut, and nothing in the result records that it happened. A 408-character input with a mail-stop preamble in front of the address produced 128 piecesECE (Expected Calibration Error). A metric that measures how well a model's confidence scores align with its actual accuracy. Lower is better. Mailwoman's held-out ECE drops from 0.067 (raw) to 0.0035 (calibrated). covering the first 328 characters, and the parseaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates. contained nothing from the address at the end:

{"street":"Mail Stop 7 Attn Accounts Payable Department Of Very Long Names",
 "unit":"Suite 100","venue":"Building A"}

The tail of the string was never seen. Fragmentedinput modeThe Decision-A register switch: 'fragmented' (human-typed fragments — feeds the evidence channels) vs 'formatted' (complete records — runs the trained absence identity). Explicit on CLI/API; per-endpoint defaults (batch→formatted, autocomplete→fragmented); kind-derived otherwise. words spend the window faster than common ones, so the effective character limit is lower for languages that fragment more. If your input can carry long routing preambles, trim them before the parseaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates. rather than after.

Where rules still win

The rule-based approach is not a worse version of this one. It is better at a specific set of jobs, and it is worth being precise about which.

A closed vocabularyvocabularyThe fixed set of tokens a tokenizer can produce. Mailwoman's SentencePiece vocabulary is tens of thousands of subword pieces, with byte fallback for anything outside it. in a fixed slot, with no homographshomonymyOne surface, many referents: 'Georgia' is a US state in 'Atlanta, Georgia' and a country in 'Tbilisi, Georgia.' Handled by disambiguation, split across two stages — the parser resolves the tag from in-string context; the resolver late-binds the referent with geographic context.. If the value must be one of a known list and the list has no collisions with other components, a lookup is exact, instant, and needs no trainingtrainingThe process of adjusting a model's parameters so its predictions match labeled examples, by repeatedly measuring error and nudging the weights to reduce it. Distinct from inference, when the trained model is run on new input. data. The modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' is the right tool where the same surface means different things in different contexts — Georgia as a state and as a countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. is the canonical case — and a lookup cannot be right about both without a hand-written guard. Where the collision does not exist, the lookup wins.

Format validation. Whether a string is a well-formed United Kingdom postcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one. is a question about a grammar, answerable exactly by a pattern. The modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' has no notion of validity — it labelscomponent tagOne of the 25 labels in Mailwoman's address schema — street, locality, region, postcode, house_number, unit, po_box, country, venue, intersection, and others. Each parsed span carries exactly one component tag. a spanspanA contiguous range of characters or tokens in the input string, tagged with an address component type (street, locality, postcode, etc.). Parsed addresses are represented as collections of spans, possibly nested in a tree. postcode because that is where a postcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one. goes, and 00000 scores as well as a real one.

Rendering. Turning components back into a correctly ordered address string for a countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. is deterministic, and a rule table is the right implementation. The inverse of a hard problem is not always hard.

Anything needing a guarantee rather than a score. A rule can promise never to emit a tag. A modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' can be measured at never having emitted it on the data anyone tried, which is a different and weaker statement.

Auditability. A rule is readable, and the fix for a wrong rule is a diff a reviewer can evaluate. A wrong labelcomponent tagOne of the 25 labels in Mailwoman's address schema — street, locality, region, postcode, house_number, unit, po_box, country, venue, intersection, and others. Each parsed span carries exactly one component tag. is a property of a weightparameterA single learned number inside a model — one weight or bias. Mailwoman's encoder has roughly 30 million of them; training is the search for good values. matrix, and the fix is trainingtrainingThe process of adjusting a model's parameters so its predictions match labeled examples, by repeatedly measuring error and nudging the weights to reduce it. Distinct from inference, when the trained model is run on new input. data, a run, and a gate. The first loop is minutes and the second is a release cycle, and that difference is a real engineering cost the accuracy comparison does not show.

The composition is the practical answer, and it is what this system does: labelcomponent tagOne of the 25 labels in Mailwoman's address schema — street, locality, region, postcode, house_number, unit, po_box, country, venue, intersection, and others. Each parsed span carries exactly one component tag. with the modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.', constrain with tables where a constraint is exact, and check with rules where a guarantee is required.

Related

• Why addresses are hard — why the ambiguity is structural.
• Falsehoods about addresses — twenty-five assumptions, each with a counterexample.
• Locales and tiers — what is measured, and what is only trained.
• Validate an address before you use it — the checks that answer the existence question.
• Handle messy input — what the pipelinestaged pipelineMailwoman's runtime architecture: a sequence of pure-function stages (normalize → query-shape → locale-gate → kind-classifier → phrase-grouper → classifier → decoder) connected by typed handoffs. Each stage is published as its own npm package. absorbs before you write any cleanup.