Anchor-based parsing & multi-locale architecture — direction (2026-06-03)

Direction D. Some 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. in an address carry far more geographic information than others. The 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 the clearest case, with distinctive streetsstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. and landmarks close behind. Treat those as first-class structured anchors that condition (or bypass) the neural parser, rather than flattening them into just-another-BIO-tag. Around that sits a single self-conditioned 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.' per script shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row., a tiny always-resident coarse placer for graceful abstention, and a strict soft-prior discipline that keeps anchors from laundering errors. DeepSeek-signed across two consults (German conditioning: .agents/skills/deepseek-consult/session-notes-2026-06-02-german-conditioning.md; resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon. routing: .agents/skills/deepseek-consult/session-notes-2026-05-30-resolver.md).

Why now

The v0.8.0 German order-shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. experiment (postmortem) taught two things at once. The order is learnable cheaply: a 5,000-row shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. roughly doubled German streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. and house-number F1. But the continue-train re-triggered the Saint-AlbansBAN (Base Adresse Nationale). France's authoritative open national address register — the highest-quality training source for French addresses, with full component structure. 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.-fragmentation bug at end-of-string. 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.' bled the 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. 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. into the adjacent citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. (München → chen, Berlin → absorbed into the 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. run), which collapsed localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. and 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. and dragged the resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon. down with it. The collapse is emission-level: raw per-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. argmax already fragments, so no decoderdecoderIn a transformer encoder-decoder model, the part that produces output sequences. Mailwoman's classifier is encoder-only (no decoder); the 'CRF decoder' is a different thing — a structured-prediction layer that picks the best label sequence from the encoder's outputs. 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.-merge or CRFCRF (Conditional Random Field). A statistical modeling method that predicts structured outputs by modeling dependencies between adjacent labels. Mailwoman uses a linear-chain CRF as the Viterbi decoder at inference time to enforce BIO label consistency — a B-street must be followed by I-street or O, never I-locality.-transition table can repair it (both sit downstream of emissions, and the error is cross-tag, a citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy.'s lead piece leaking into postcode rather than a same-tag split).

The mechanism reframes the whole roadmap. Think about what 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. actually encodes: a US ZIP runs northeast to west by its first digit, a UK 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. plus a 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. nearly identifies a single building, and German PLZ and French codes are zone-hierarchical. It is the most information-dense 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. in an address, and we were asking a sequence labeler to find it and to know where it stops, in one pass, with nothing telling it the 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 different kind of thing from the citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. sitting beside it. That framing is the bug. Lift the 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. out with a dedicated high-precisionprecisionOf the spans the model labeled as a given tag, the fraction it got right. High precision means few false positives. Paired with recall to compute F1. extractor, resolve it, and feed it back as a conditioning anchor, and 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.' never gets the chance to make the cross-tag mistake. It gains the strongest available localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. signal for everything else at the same time.

This generalizes. The same "high-precisionprecisionOf the spans the model labeled as a given tag, the fraction it got right. High precision means few false positives. Paired with recall to compute F1., high-geo-load 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. as an anchor" pattern covers distinctive streetsstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. (Champs-Élysées, Shibuya 109) and landmarks (Empire State Building), which the exotic-POI understanding docs already describe as a domain the BIO parser handles poorly. The 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 just the most regular member of that family, the one a regex can catch.

The anchor layer

An anchor is 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. the system can identify with high precisionprecisionOf the spans the model labeled as a given tag, the fraction it got right. High precision means few false positives. Paired with recall to compute F1. outside the neural tagger, one that carries strong geographic information. We extract anchors in a cheap pre-pass and feed them to the parser as a soft, confidence-weighted channel that nudges rather than overrides. The raw text stays authoritative.

Postcode anchor (the first and most regular)

• Extractor: pure regex + a fuzzy 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.. Zero-GPU, always-resident, ~2 MB for 15-20 countries, microsecond latency, polyfillable in WASM. A Damerau-Levenshtein distanceedit distanceThe minimum number of single-character insertions, deletions, or substitutions needed to turn one string into another (Levenshtein distance). Used in corpus alignment and record matching. of 1 absorbs OCR, transposition, and truncationtruncationCutting an input down to the max sequence length (or an LLM response to its token limit), discarding everything past the cap. noise.
• Resolves to a country posteriorcountry posteriorA country → probability map (derived from postcodes or the coarse-placer) that re-ranks resolver candidates as a soft prior, never a hard filter.. 5-digit formats collide across US/DE/FR/ES/IT, so a single hard 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. call is wrong; the extractor returns a distribution (75001 → {FR: 0.98, US: 0.02}) plus regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. and centroid, and lets the parser settle the rest from context. The 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. membership test is the primary disambiguator; shape (alphanumeric UK/NL/CA can never be a 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.) and neighbouring 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. come second.
• Injected as a prepended [POSTCODE-ANCHOR] embeddingembeddingA vector of numbers representing a token (or other item) so that similar items sit near each other in vector space. The first thing the model does is turn each token into an embedding. encoding (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.-posterior, regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality., centroid, confidence). The raw 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. stay untouched, so 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.' can see, and recover from, a mistyped or out-of-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. code.
• Anchor-dropoutdropoutA regularization trick that randomly zeroes a fraction of activations during training, forcing the model not to rely on any single feature. Disabled at inference. ~20% during 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. (replace with a learned [NO-ANCHOR] embeddingembeddingA vector of numbers representing a token (or other item) so that similar items sit near each other in vector space. The first thing the model does is turn each token into an embedding.) so 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.' never depends on the anchor. This keeps it a soft priorsoft priorOutside knowledge fed to the model or resolver as overridable evidence (a feature, a score term) rather than a hard filter. A focus-country hint becomes an anchor feature; a focus-point becomes a ranking term. and closes the circularity (anchor conditions 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., 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. feeds the resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon.) without laundering errors.

Where position fits in

The extractor finds 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. wherever a human put it (robust to positional error), and position still counts: it feeds the candidate's confidence, because some house numbershouse 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. do look like postcodespostcodeThe 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.. The collision is narrow (only purely-numeric-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. countries, and house numbershouse 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. usually run 1-4 digits) but real. 12345 is at once a valid US ZIP (Schenectady) and a plausible 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., so 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. membership alone does not always decide. So the extractor does not try to win that call. An ambiguous candidate carries low confidence, the anchor channel propagates the doubt, and the parser plus its surrounding context makes the final decision. The extractor's job is high-recallrecallOf the spans whose gold label is a given tag, the fraction the model found. High recall means few misses. Paired with precision to compute F1. candidate generation with calibrated confidence, well short of a high-precisionprecisionOf the spans the model labeled as a given tag, the fraction it got right. High precision means few false positives. Paired with recall to compute F1. hard ruling.

Generalized anchors: distinctive streets, landmarks, districts

The same mechanism, with a salience-weighted place 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. + fuzzy/alias matching in place of a regex. Three 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. placements, decided by the router (see coarse placer), by query type:

Query type	Example	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. placement
Bare landmark / POIpoint of interest (POI). A named place that is not strictly an address — landmark, transit stop, venue, amenity, or franchise. Mailwoman tags these as venue and resolves them through the gazetteer.	Empire State Building, Shibuya 109, Odori Park	Skip the parser and resolve directly as 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.. Running BIO on it hallucinates spansspanA 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..
Distinctive streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. in an address	350 Fifth Avenue, 10 Downing Street	Anchor conditions the parser (strong citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy./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. prior); parser still runs.
Distinctive district / component	Ginza, 2-Chōme	LocalitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy./neighbourhood anchor; conditions parser + resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon..

Guardrails (these are critical):

1. Salience is data-driven, never a hand-curated VIP list. "Champs-Élysées is special" must fall out of OSMOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names./WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. popularity + uniqueness scores, not a hardcoded entry. A hand-maintained famous-list is the "just one more rule" trap with better taste, and we keep it off the table.
2. Ambiguity-aware. Champs-Élysées is near-unique (sharp prior); Broadway, Main Street, and Fifth Avenue exist in dozens of towns (weak, multi-modalModalA cloud GPU platform (modal.com) where Mailwoman trains its neural models on NVIDIA A100 GPUs. Training runs are launched via scripts/modal/train_remote.py and typically complete in ~1 hour. prior). Anchors emit a posterior over candidates and must not over-commit on a common name ("Broadway Avenue, Springfield" must not anchor to NYC).
3. Concepts are past the parser's fence. "The Hajj" refers to a place (Mecca) without being a place name; resolving it is semantic entity-linking, or concept-aliasing, a different subsystem near the resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon. (where "Macca's → McDonald's" alias logic conceptually lives). The parser stays out of it. Grow it into a general world-knowledge base and the surface becomes unbounded.

The model architecture

Script routes; address-system conditions within

Routing has to be cheap and reliable, and script is both: a Unicode-block regex, free and exact. Address-system similarity is the right clusteringclusteringThe final stage of entity resolution: resolve non-transitive pairwise match decisions (A↔B, B↔C, but not A↔C) into canonical entities via union-find with path compression. Each cluster of records becomes one resolved entity. for 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.''s job (UK and US share a script but differ in system; DE and AT share a system across a language border), yet it is not detectable pre-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., since knowing the system is most of 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., which makes routing on it circular. So the Pareto-optimal point is to route by script and specialize by address-system inside each shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. via conditioning. One Latin shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. (US, UK, DE, FR, ES, IT, NL, BR, MX… as conditioned localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.), one CJK+ shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. (JP/KR/CN share descending-localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. structure), one Arabic, one Indic. Awkward cases (UK, tri-lingual CH, ES-Spain vs ES-LatAm) are localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. within the Latin shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row..

The two axes have different jobs: script routes; address-system subdivides a shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. only on capacity overflow (see the cross-pollutioncross-pollutionAn eval tripwire for unwanted tag bleed across locales — predicting a German city as a postcode because multi-locale training let one locale's patterns hurt another. metric). That is why both came up. They operate at different layerslayerOne transformer block — attention plus a feed-forward network, with normalization and residual connections — applied to every position. Stacking layers lets the model build up richer representations; Mailwoman's encoder has 6..

Self-conditioning over a hard locale token

In production we usually receive a raw string with no reliable 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. hint, and detecting the 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. before parsingaddress 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 most of what the parser exists to do, so a hard external [locale] 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. comes close to assuming the answer. Instead 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 the whole sequence, infers a soft localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. posterior, and conditions its own per-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. labeling on it (layernormlayer normalizationA step that rescales a vector to a stable range before the next sublayer, keeping activations well-behaved and training stable. A standard ingredient of transformer layers. modulation, or posterior-as-featurefeatureAn input signal a model conditions on. Beyond the raw tokens, Mailwoman feeds soft features — gazetteer-membership channels and the postcode anchor — that inform predictions without overriding them.). That resolves the ambiguity globally, before per-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. labelscomponent tagOne of the 33 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., which is the step the implicit mixing in v0.8.0 skipped. When a postcode anchoranchor inferenceA technique where structured knowledge (postcode locations, gazetteer place names) is injected into the model as soft input features — not as deterministic overrides. The model still decides the final labels, but the anchor signal biases it toward correct admin tags. is present it is the strongest input to that posterior; when absent, 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.' falls back to text-only self-conditioningself-conditioningAn auxiliary model head that predicts the input's locale (language/country) and then FiLM-modulates the encoder so parsing adapts to the detected locale. Structural facts like word order still need explicit training on both orders.. An optional 15-20% localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.-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.-dropoutdropoutA regularization trick that randomly zeroes a fraction of activations during training, forcing the model not to rely on any single feature. Disabled at inference. lets an external hint help without becoming a dependency.

Coarse placer + graceful abstention (the "Eurasia / off-map" tier)

A tiny always-resident 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.' (a one-layerlayerOne transformer block — attention plus a feed-forward network, with normalization and residual connections — applied to every position. Stacking layers lets the model build up richer representations; Mailwoman's encoder has 6. 32-dim transformerneural 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.', or a fastText-style linear classifier, a few hundred KB) predicts (script, continent, coarse-regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality.) with a temperature-calibrated confidence, trained with a little outlier exposure (unseen scripts as an "other" class) so it knows the edge of its own competence. Below threshold it abstains, returning "probably East Asian, off my loaded map" instead of a confident mis-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.. It runs first, gives an instant coarse answer, and decides which script shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. to download. That is the selective-geography product story: ship ~28 MB that places the planet coarsely, then fetch the regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. you care about for streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.-level detail (tiered loading, no permanent whole-world footprint).

Does conditioning really isolate, or just paper over?

A conditioned shared 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 modulated, not hard-isolated: its FFNfeed-forward networkThe per-token transformation inside each transformer layer that follows attention: a small two-layer network applied independently at every position. and attentionattentionThe core mechanism inside a transformer encoder. Each token's representation is updated by looking at every other token, with learned weights deciding how much each one matters. weightsparameterA 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. are shared. The DeepSeek read is that conditioning functionally specializes up to ~20-30 localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. per shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. at ≥300-dim hidden (we have 384), so our 15-20 target sits inside the safe regime, and the German collapse was a 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.-schedule artifact rather than a shared-weightsparameterA 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. limit. Treat the capacity numbers as directional estimates, not gospel (the same source over-called 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. wall, which our own diag-tokenizer-multiscript.ts walked back). The part we trust is the falsifiable tripwire below.

Decision rules (pre-registered)

• No promotion on parser-F1 alone. The resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon. is the judge. German's pre-experiment resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon. localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy.-match was already 77.4% (v0 79.4%), a weak parser that the resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon. absorbed, so a from-scratch retrain for German alone is not justified. Keep v0.7.2 and batchbatch sizeHow many examples the model processes before each parameter update. Larger batches give smoother gradients but cost more memory; gradient accumulation simulates a big batch on a small GPU. the localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. expansion.
• Retrain trigger (resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon. terms): a localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.'s resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon. utility falls below ~80% citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. match, or adding a localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. drops an existing one's resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon. utility by more than 2pp (the 77→43 collapse).
• Cross-pollutioncross-pollutionAn eval tripwire for unwanted tag bleed across locales — predicting a German city as a postcode because multi-locale training let one locale's patterns hurt another. / capacity tripwire: per-localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for., the rate of citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy.-start 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. mis-tagged as 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. must fall below 1% by 20k steps with balanced data and conditioning present. If it will not clear 1%, that shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. has hit its interference ceiling, and we split it by address-system (not by more script).
• Coarse placer: abstain below the calibrated confidence threshold rather than emit a confident wrong placement.

Staged plan

1. Now — nothing to production. v0.7.2 stays; no urgency. Drop the decoderdecoderIn a transformer encoder-decoder model, the part that produces output sequences. Mailwoman's classifier is encoder-only (no decoder); the 'CRF decoder' is a different thing — a structured-prediction layer that picks the best label sequence from the encoder's outputs. 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.-merge and CRFCRF (Conditional Random Field). A statistical modeling method that predicts structured outputs by modeling dependencies between adjacent labels. Mailwoman uses a linear-chain CRF as the Viterbi decoder at inference time to enforce BIO label consistency — a B-street must be followed by I-street or O, never I-locality.-transition ideas for German (the diagnostic killed both).

2. This week, no GPU, highest ROI — the postcode anchoranchor inferenceA technique where structured knowledge (postcode locations, gazetteer place names) is injected into the model as soft input features — not as deterministic overrides. The model still decides the final labels, but the anchor signal biases it toward correct admin tags.. Build (a) 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. → 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.-posterior + regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. + centroid 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. for the target localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. from OpenAddressesOpenAddresses (OA). A global open aggregation of address points collected from many official sources. A primary source of component-supervised training data outside proprietary registries. (US already exists: postalcode-us.db, 42,319 codes; the global admin DB currently has zero postcodespostcodeThe 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.), and (b) the regex + fuzzy extractor with calibrated confidence. It helps the resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon. today and becomes the parser's strongest conditioning channel. In parallel: 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). ES/IT/NL order shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. (same synth-from-real-OA recipe) and clean the OpenAddressesOpenAddresses (OA). A global open aggregation of address points collected from many official sources. A primary source of component-supervised training data outside proprietary registries. CITYlocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. noise.

   Status (2026-06-03): the anchor shipped for US, NL, FR, and DE (PRs #247-#250). The 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. came from the WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. 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. repos via build-unified-wof --placetypes postalcode, not OpenAddressesOpenAddresses (OA). A global open aggregation of address points collected from many official sources. A primary source of component-supervised training data outside proprietary registries. aggregation — the operator's "extend the custom WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. build" rule, and WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. carries the centroids (or an admin ancestor to borrow one). A data-quality survey showed ES/IT are orphan-heavy in WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. and stay membership-only until a non-WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. source is approved. See resolver-wof-sqlite/POSTCODE-ANCHOR.md and docs/articles/evals/2026-06-03-night-5-postmortem.md.

3. De-risk pilot (~$3-8). From-scratch US/FR/DE with self-conditioningself-conditioningAn auxiliary model head that predicts the input's locale (language/country) and then FiLM-modulates the encoder so parsing adapts to the detected locale. Structural facts like word order still need explicit training on both orders. + the 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.-anchor channel + dropoutdropoutA regularization trick that randomly zeroes a fraction of activations during training, forcing the model not to rely on any single feature. Disabled at inference. on both signals, stopped at the 20k gate (cross-boundary error under 1%, DE localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. F1 ≥70% and rising, US/FR within 1pp, anchor/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.-free degradation ≤5pp). It validates the architecture before any scale spend. Test the postcode anchoranchor inferenceA technique where structured knowledge (postcode locations, gazetteer place names) is injected into the model as soft input features — not as deterministic overrides. The model still decides the final labels, but the anchor signal biases it toward correct admin tags. and self-conditioningself-conditioningAn auxiliary model head that predicts the input's locale (language/country) and then FiLM-modulates the encoder so parsing adapts to the detected locale. Structural facts like word order still need explicit training on both orders. together.

4. Real run. One from-scratch, balanced, self-conditioned run once the pilot passes and 4-5 localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. are staged.

5. Global. Script-shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. collection + the coarse-placercoarse-placerA lightweight int8 country classifier (~0.79 MB) that predicts which of a set of target countries an address belongs to, feeding a soft prior into resolver disambiguation. tiertierInternal versioning of which label classes the model emits. Tier 1 is the coarse components (country, region, locality, postcode); Tier 2 adds venue, street, house_number; Tier 3 (future) would add attention, po_box, and POI venue subtyping. Historically called 'Stage 1/2/3' before the runtime-pipeline naming made that ambiguous.; the generalized place-anchor 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. for distinctive streetsstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. / landmarks; subdivide a shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. by address-system only if its 20k tripwire refuses to clear.

Related

• German order-shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. postmortem — the failure that motivated this.
• Resolver routing plan — Direction C; the router this builds on.
• Exotic-POI understanding docs — the landmark / franchise / regional-variant / transit query domains the generalized anchors target.
• DeepSeek consults: German conditioning + resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon. routing (paths in the header).