Skip to main content

Mailwoman Glossary

Key terms and concepts in the Mailwoman address parser and geocoder.

A

Acc@1 (accuracy at 1)
The share of eval rows whose top-ranked resolver candidate is the correct place, regardless of coordinate distance — 'did we pick the right place', independent of geocode precision.
additive bias
A logit adjustment added before softmax from a prior or external knowledge source, typically soft-capped so it influences but never overrides the model's prediction. The mechanism behind shallow fusion.
address ID
A stable, parseable primary key for an address in the format <state>.<H3-cell>.<hash>. Content-addressed (derives from the data), jitter-stable (absorbs small geocode differences), and partitionable by state prefix.
Address Management System (AMS)
The USPS's authoritative database of every deliverable US address (~165 million points). Licensed to commercial mailers under strict terms, not openly available — part of why an open parser can't just look every address up.
address parsing
The 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.
admin FST
A finite-state transducer encoding Who's On First admin place names (countries, regions, localities, postcodes) for fast gazetteer lookup and emission priors at inference time. Ships to the browser (~9 MB for 94K US admin places).
adversarial corpus
Eval entries chosen specifically to break the parser. Mailwoman's adversarial set covers cases like 'Buffalo Buffalo' (a venue named after a city), 'St. Petersburg' (a multi-word locality), and prefix-honorific names.
Related terms: golden set, honest eval, eval
alignment
The step in the corpus pipeline that takes a (raw, components) pair from an adapter and produces a (raw, tokens, BIO labels) row by finding each component's text inside the raw string and labeling the matching tokens.
Related terms: corpus, BIO tagging, token
amenity
A point of interest referenced by category ('gas station', 'pharmacy', 'ATM') rather than by name. Resolved by mapping the query onto a category taxonomy.
anchor inference
A 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.
annotation noise
Errors in human ground-truth labels (typically around 1%) that put an irreducible ceiling on eval metrics — no model can exceed the agreement of the labels it's graded against.
APO/FPO (Army Post Office / Fleet Post Office)
US military postal addresses for personnel stationed overseas or aboard ship. They route through military postal hubs rather than geographic locations, so they break geographic parsing assumptions.
Related terms: PO box, negative space
arbitration
A pipeline stage that compares rule-based (v0) and neural classifier output, resolving disagreements via a policy registry. Built and merged but not promoted — the coordinate gate showed label-F1 gains came at the cost of worse geocoding.
arena
A standardized test set probing one capability: libpostal (clean canonical), perturb (noisy and degraded), postal (edge formats). Each arena answers a different question about where rule vs neural wins.
argmax decoding
The simplest decoding strategy: pick the highest-scoring label independently for each token. Fast but can produce invalid BIO sequences (e.g., I-street without a preceding B-street). Mailwoman ships argmax as the default and Viterbi CRF as an option.
attention
The 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.
attention head
One of several parallel attention computations in a layer, each free to focus on a different kind of relationship between tokens. Their outputs are concatenated — 'multi-head attention'. Mailwoman uses 4 heads.
Related terms: attention, layer, encoder

B

backpropagation
The algorithm that computes the gradient of the loss with respect to every parameter by applying the chain rule backward through the network. The engine behind neural-network training.
BAN (Base Adresse Nationale)
France's authoritative open national address register — the highest-quality training source for French addresses, with full component structure.
Related terms: corpus, G-NAF, OpenAddresses
banchi
In Japanese addressing, a block within a chōme. The middle level of the chōme / banchi / gō hierarchy.
Related terms: chōme,
batch size
How 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.
bf16 (bfloat16)
A 16-bit floating-point format used during training. Half the memory of fp32 with similar numeric range, which lets the training batch fit on the lab's GPU.
bidirectional context
Letting each token attend to tokens on both its left and its right. Mailwoman's encoder is bidirectional — it reads the whole address at once, unlike a left-to-right language model.
Related terms: attention, encoder, transformer
BIO tagging (Begin-Inside-Outside)
A token-level labeling scheme where each token is tagged as B-X (beginning of an entity of type X), I-X (inside an entity of type X), or O (outside any entity). Mailwoman uses BIO over SentencePiece tokens to annotate address components.
bitter lesson
Sutton's observation that general methods which scale with compute and data ultimately beat hand-engineered systems. The rationale behind Mailwoman's Ship-of-Theseus migration from rule classifiers to a learned model.
block face
One side of a street between two intersections. Several postal systems specify delivery to block-face granularity — e.g. the USPS ZIP+4 extension.
blocking
The first stage of entity resolution: generate candidate record pairs using cheap, high-recall keys (geo cell, canonical address, phone) instead of comparing every record to every other (O(n²)). The matcher only scores pairs that survive blocking.
borough
An administrative or historical division of a city — e.g. the five boroughs of New York City. May be postal, legal, or both, and complicates the locality hierarchy.
boundary instability
A class of parser errors where the model wobbles on where one address component ends and the next begins — a street suffix swallowed into the street name, a French house number that trails instead of leads. Mailwoman's #1 weakness as of v1.5.0.
byte fallback
A 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.
Related terms: SentencePiece, tokenizer

C

canonical key
A deterministic, normalized string representation of an address produced by @mailwoman/formatter. Lowercase, abbreviation-expanded, punctuation-stripped — so '123 Main St' and '123 MAIN STREET' produce the same key. Used for blocking in the matcher.
Related terms: formatter, blocking, address ID
canonicalization
Mapping a span to its canonical value: 'St' and 'Street' both become the USPS suffix ST; 'USA' and 'United States' both become ISO US. The operation that handles synonymy. Canonical values come from @mailwoman/codex, not a hand-grown alias list.
carrier route
The delivery path one postal carrier covers on a shift. A ZIP code is fundamentally a set of carrier routes, not a geographic polygon, which is why ZIP boundaries are fuzzy and shift over time.
Cartographer
Mailwoman's mapping utilities. Composes MapLibre style specifications and builds vector source records for the demo's Protomaps basemap.
Related terms: geocoding
CEDEX (Courrier d'Entreprise à Distribution Exceptionnelle)
A French postal routing for high-volume business mail: a CEDEX code delivers directly from a sorting centre, bypassing the local post office. A common negative-space format Mailwoman must parse.
character class
A token's character category — digit, alpha, CJK, Cyrillic, Arabic, mixed — used by the query-shape stage as a structural signal for locale and kind inference.
check digit
A digit appended to a postcode or identifier and derived by modular arithmetic, used to detect transcription errors.
checkpoint
A saved snapshot of the model weights and optimizer state during training. Mailwoman saves a checkpoint periodically so training can resume after a GPU hang.
Related terms: model weights, Modal
chōme
In Japanese addressing, a district-level subdivision in the block-based chōme / banchi / gō numbering scheme, which uses area-and-block numbers instead of street names.
Related terms: banchi, , named intersection
City State Product
The USPS file mapping each ZIP to its 'preferred' and 'acceptable' city names. One ZIP can carry several city names because a post office serves multiple neighbourhoods and adjacent municipalities.
Related terms: postal city, postcode
classification proposal
The shared shape that every classifier (rule or neural) writes. The solver consumes proposals without knowing which kind of classifier produced them.
clustering
The 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.
coarse-placer
A 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.
code-switching
Mixing two languages in a single query, e.g. 'スタバ near Shibuya Station' (a Japanese brand name with an English location constraint).
coherence
The property of a parse whose resolved places form a consistent geographic hierarchy — the resolved locality really does sit inside the resolved region.
coincident roles
A precomputed Who's On First relation that pairs a region with its same-named locality (Berlin city ↔ Berlin state) so the resolver can complete the hierarchy at resolution time.
component tag
One 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.
concordance
A joint-decode signal that rewards a parse whose spans form a consistent Who's On First parent-child chain and vetoes contradictory ones — a hard veto for conflicts, a log-space bonus for full agreement.
confidence calibration
The process of adjusting model confidence scores so that '0.6' actually means the model is right about 60% of the time. Mailwoman uses isotonic regression (PAVA) to calibrate per-span confidences against held-out data. Applied opt-in via createCalibrator.
Related terms: decoder, ECE
conformal calibration
A calibration method that adjusts per-prediction uncertainty so a target coverage (e.g. 90%) is guaranteed on held-out data, without retraining the model.
context window
The span of input a model can consider at once, bounded by its max sequence length. Everything in the window can influence every token's label via attention.
conventions mask
A decode-time constraint layer keyed by the model's own address-system detection (the exported locale head): tags that are ungrammatical in the detected system are removed from the Viterbi vocabulary, and the system's postcode shape arms a snap-only repair pass. The first slice forbids USPS street-affix decomposition for French. Same knowledge-outside-the-weights property as the gazetteer anchor — add a codex conventions row, no retrain.
coord metric
The primary evaluation metric: distance from the resolved coordinate to the true address point. Measured at percentiles (p50, p90) and as 'within X meters.' Prevents the label-F1 trap where a model scores higher on token labels but geocodes worse.
corpus
The 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.
country
The 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.
country posterior
A country → probability map (derived from postcodes or the coarse-placer) that re-ranks resolver candidates as a soft prior, never a hard filter.
coverage
The 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.
CRF (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.
cross-entropy
The standard classification loss: it penalizes a model for putting low probability on the correct label. Per-token negative log-likelihood is the cross-entropy of each token's label.
Related terms: NLL, loss function, softmax
cross-pollution
An 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.
cumulative dilution
The effect where stacking many synthetic shards into one run spreads the step budget thin and weakens each shard's target tag. Shards are best proven solo, then consolidated with a larger step budget.

D

decoder
In 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.
Related terms: encoder, CRF, Viterbi decoding
delivery point code (DPBC — Delivery Point Barcode)
The full 11-digit USPS code (5-digit ZIP + 4-digit extension + 2 delivery-point digits) that uniquely identifies a single mailbox, encoded as the barcode on an envelope for automated sorting.
delta F1
The F1 difference between two model versions for a tag, used to flag a regression or a gain step-over-step.
dependent locality
A sub-locality (neighbourhood or borough) hierarchically inside a larger locality — e.g. Brooklyn within New York City. Provides finer geographic specification below the primary locality.
Related terms: locality, borough, placetype
dependent street
A secondary street name required for delivery in some postal systems (notably Royal Mail), as in '6 Elm Avenue, Runcorn Road, Birmingham' where Runcorn Road is the dependent street.
designator
The closed-vocabulary leading word of a secondary-address phrase — 'Apt', 'Suite', 'Floor', 'PO Box', 'Level' — paired with an identifier to form a complete subpremise.
Related terms: subpremise, unit, PO box
deterministic regex repair
A post-parse pass that detects patterns the tokenizer fragmented — an alphanumeric postcode shredded into subword pieces, say — and snaps label spans onto regex-matched shapes, fixing zero-F1 cases the model can't recover without retraining.
diacritic
An accent mark that modifies a letter (é, ñ, ç). Address normalization must fold diacritics for matching without discarding the information a user typed.
divergence
A training failure where loss descends through warmup, plateaus low for a while, then climbs catastrophically back to its starting magnitude — the model unlearns everything despite no obvious component failure.
dropout
A regularization trick that randomly zeroes a fraction of activations during training, forcing the model not to rely on any single feature. Disabled at inference.
dual-role place
A place that is two placetypes at once — Berlin as both a city and a state, Washington DC as city and district. Resolved using the coincident-roles relation plus hierarchy completion.

E

E911 (Enhanced 911)
County- and state-level emergency-dispatch address-point databases with full component breakdown. A lineage source for the situs and address-point layers used in geocoding.
Related terms: NG911, situs data, rooftop
ECE (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).
Related terms: confidence calibration
edit distance
The 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.
embedding
A 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.
embedding space
The high-dimensional space in which embeddings and hidden states live. Geometry there is meaningful — distance and direction encode similarity and relationships learned from data.
Related terms: embedding, hidden state
emission logit
The per-token, per-label logit the transformer encoder emits before any external prior is added — the model's own evidence for each label at each position.
emission prior
A log-probability bias injected into the model's emission logits from an external signal — gazetteer frequency, an FST, a Wikipedia-importance score — combined with the learned weights at decode time.
encoder
The part of a transformer that turns input tokens into contextualized vector representations. Mailwoman's classifier is a small encoder-only transformer (~30M parameters).
ensemble
Combining several models' predictions to cut variance and improve robustness. A general ML technique, noted in the docs as a lever Mailwoman has not needed to pull.
epsilon floor
A small cutoff (ε) below which per-country posterior entries are dropped before the resolver sees them, so implausible tail probabilities cannot influence ranking. Domain: [0, 1]; 0 disables it (the full distribution passes through — the shipped default); higher values keep only stronger beliefs, at the extreme leaving just the argmax (a one-hot). Mailwoman defaults to 0 because no nonzero value has measured benefit on the misroute battery (the 2026-07-03 floor sweep was null at 0.05–0.30); the knob exists for distribution-mode experiments (--posterior-floor).
eval
Running the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error.
exact match
The share of eval items whose every component is correct (compared per-span or per-token). Stricter than per-tag F1, which credits partial correctness.
exact-match tiering
A resolver ranking strategy that groups candidates by match quality (exact name/alias match vs partial) and ranks within each tier by secondary signals, so a strong population prior can't promote a poor name match.
Related terms: resolver, Acc@1, parent fallback
execution provider fallback
onnxruntime trying its requested backends in order (e.g. ['webgpu', 'wasm']) and silently falling back to the next on failure. Convenient, but it can mask a broken backend — headless Chromium lacks WebGPU, so tests silently ran on WASM.
Related terms: JSEP, ONNX
expectation-maximization
An iterative algorithm that estimates model parameters when some variables are unobserved. In Mailwoman's matcher, EM learns the Fellegi-Sunter m and u parameters from unlabeled data — no training labels needed.

F

F1 score
The harmonic mean of precision and recall — a single number between 0 and 1 summarizing how good a classifier is at a class. F1 = 2·P·R / (P + R).
Related terms: macro F1, eval
feature
An 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.
feed-forward network
The per-token transformation inside each transformer layer that follows attention: a small two-layer network applied independently at every position.
Related terms: layer, attention, encoder
Fellegi-Sunter
A probabilistic record linkage model that computes match probability from agreement-level log-likelihood ratios: log₂(m/u) where m is the probability of agreement given a true match and u is the probability of agreement by chance. Mailwoman learns m and u label-free via expectation-maximization.
fertility
How many tokenizer pieces it takes to spell a word: fertility 1 means whole words survive tokenization, fertility 3 means they arrive in fragments. High fertility hurts sequence labeling directly — the model has to reassemble a word before it can label it, and fragment boundaries are where labels break. Mailwoman measured this on French street names: accented words splitting at the accent ('René' → '▁Ren' + 'é') caused real geocoding misses, and lowering French fertility was worth a tokenizer revision plus a retrain.
FiLM modulation (Feature-wise Linear Modulation)
A parameter-efficient adaptation that scales and shifts feature vectors by learned per-example multipliers and biases. Used in self-conditioning to make parsing decisions locale-aware without retraining the whole model.
fine label
The Tier 2 labels added to the model vocabulary — venue, street, house_number — as opposed to the coarse labels (country, region, locality, postcode).
Related terms: tier, component tag
formula address
A descriptive, relative address given by directions and landmarks ('two blocks past where the bakery used to be, half a block toward the lake') rather than a street and number. The hardest end of the parse-difficulty spectrum.
fp32 / fp16
32-bit and 16-bit floating-point formats. Mailwoman trains in bf16 (a 16-bit variant) and exports the ONNX model in int8 for size.
Related terms: bf16, int8 quantization
franchise query
A point-of-interest query naming a brand or chain ('nearest Starbucks') rather than a category or an address.
FST (finite-state transducer)
A compact automaton that reads an input sequence and emits an output sequence. Mailwoman encodes gazetteer names and street affixes as FSTs for fast prefix matching and prior injection without search overhead.
FTS5
SQLite's built-in full-text-search module (with BM25 ranking). Mailwoman uses it for prefix and name matching against the gazetteer.
Related terms: resolver, R*Tree, SQLite-wasm

G

G-NAF (Geocoded National Address File)
Australia's authoritative open address register (CC-BY-licensed), used as a training source for Australian addresses.
Related terms: BAN, OpenAddresses, corpus
gated promotion
A release discipline where a model ships to production only if it passes pre-registered metrics (e.g. 'DE locality ≥ 70%, no tag regresses > 2pp'). Failing models can be uploaded as experiments but not promoted to default.
gazetteer
A 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.
gazetteer anchor
An input-layer feature channel that attaches a per-token candidate-tag set from the gazetteer/codex (e.g. 'this surface is a known country-and-region') so the model conditions on lexicon membership without being overruled by it. The knowledge lives outside the weights — extend the gazetteer, no retrain.
GBT (Gradient Boosted Trees)
A non-linear machine learning model that combines many weak decision trees into a strong predictor. Mailwoman uses a GBT as an optional learned scorer for single-dataset dedup, improving F1 by 5–7 percentage points over the Fellegi-Sunter baseline.
generalization
A trained model's performance on data unlike its training set — new regions, new input distributions. The property honest eval is designed to measure.
Related terms: honest eval, leakage, zero-shot
geocode cascade
Mailwoman's multi-tier coordinate resolution strategy: first try exact address-point match, then street interpolation, then locality centroid. Each tier is more widely available but progressively coarser.
geocode-first
The matcher's core design principle: resolve addresses to geographic coordinates first, then compare the resolved places — not the raw address strings. Two records at the same coordinates match even if one says '123 Main St' and the other says '123 MAIN STREET.'
geocoding
The 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.
GeoNames
A free global gazetteer combining administrative, postal, and POI data across 200+ countries. Supplements Who's On First for postcode centroids and places where WOF has gaps.
In Japanese addressing, a building or lot number within a banchi — the finest level of the chōme / banchi / gō block-based hierarchy.
Related terms: chōme, banchi
golden set
A hand-labeled evaluation dataset of US, French, and adversarial addresses used as ground truth for evals.
gradient
The direction and rate at which the loss would change if each parameter were nudged. Training follows the gradient downhill to reduce error. Huge gradients are tamed by gradient clipping.
gradient accumulation
Summing gradients over several minibatches before taking an optimizer step, to simulate a larger effective batch size under limited GPU memory.
Related terms: warmup, gradient clipping, Modal
gradient clipping
A training trick: if the gradient norm exceeds a threshold, scale it down. Stops a single bad batch from blowing up the model weights.
Related terms: warmup, label smoothing
gradient descent
The optimization method behind training: repeatedly compute the gradient on a batch and step the parameters a small amount in the downhill direction. 'Stochastic' gradient descent uses one minibatch at a time.
ground truth
The correct answer for an example, used as the standard a prediction is graded against. Mailwoman's ground truth is the hand-labeled golden set; its quality caps achievable accuracy.
grouper-audit
A validation pass checking that phrase-grouper spans are internally consistent — no overlaps, no contradictions with BIO structural rules. Audit errors must be zero on a shipping model.

H

H3
Uber's hexagonal hierarchical geospatial indexing system. Mailwoman uses H3 cells at resolution 9 (~0.03 km²) for geo-first blocking in the matcher and for stable address primary keys in @mailwoman/address-id.
Related terms: blocking, address ID, spatial
harness pass rate
Whether a full address parses end-to-end with every component correct and well-segmented and no orphan spans. Stricter than label F1 — a model can win on recall yet fail the harness if boundaries slip.
hidden dimension
The length of each token's vector inside the model — its representational width. Mailwoman's encoder uses 256. Wider models hold more information per token but cost more compute.
Related terms: embedding, hidden state, encoder
Hidden Markov Model (HMM)
A probabilistic sequence model with unobserved (hidden) states that emit observable outputs. The classical predecessor to neural sequence labelers, and conceptual kin to the CRF's transition structure.
hidden state
The model's internal vector for a token after the encoder has mixed in surrounding context. The contextualized representation the classifier head reads to assign a label.
Related terms: embedding, encoder, attention
hierarchy completion
The post-resolution step that synthesizes a dropped locality when a dual-role region resolves but the parser omitted the city (e.g. supplying 'Berlin' the city under 'Berlin' the state).
homonymy
One 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.
Related terms: synonymy, resolver, soft prior
honest eval
Mailwoman's evaluation discipline: grade the assembled pipeline output (resolved coordinate) against real-world ground truth, not raw neural label-F1 in isolation. A model can win on labels while resolving to the wrong city.
house number
The 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.
HPSA (Health Professional Shortage Area)
A US federal designation identifying areas short of health providers relative to population and need, scored 0–25. An example downstream use of geocoded address data.
hyperparameter
A training setting chosen by the engineer rather than learned by the model — learning rate, batch size, number of layers, label-smoothing strength. Tuning hyperparameters is much of the craft of training.

I

IATA code (International Air Transport Association code)
A three-letter airport code (JFK, LHR, CDG). Globally unique and machine-friendly, useful for resolving airport queries.
importance score
A precomputed per-place prominence score (blending Wikipedia importance with population) used to rank same-name gazetteer candidates.
IMU (Index of Medical Underservice)
The composite score — provider-to-population ratio, poverty rate, infant mortality, and elderly-population share — behind the Medically Underserved Area designation.
Related terms: MUA, HPSA
inclusion bonus
A per-word credit added in log space to accepted spans during reconciliation, so an empty parse can't win on multiplicative scoring just by asserting nothing.
Related terms: beam search, joint decoding
inference
Running the trained model on new input to get predictions, as opposed to training, which produces the model. In Mailwoman that means a small transformer encoder reads an address string and classifies every token — house number, street, locality, region, postcode, and the rest. A Who's On First gazetteer can feed soft location hints into the pass, but the model makes the final call on every label. Where a generative model writes text token by token, Mailwoman's output is a retrieval-augmented token classification: one label per input piece.
input-shape router
An arbitration prior that reads kind-classifier, query-shape, and coarse-placer signals to set per-component defaults (rule_preferred, neural_preferred, or abstain) according to how clean or out-of-distribution the query is.
int8 quantization
A model compression technique that stores weights as 8-bit integers instead of 32-bit floats, reducing model size (~4×) with minimal accuracy loss. Mailwoman ships int8-quantized ONNX models (~30 MB) for fast loading in browsers.
Related terms: ONNX, model weights
interpolation
A geocoding technique that estimates a coordinate along a street segment based on the house number range. Used as the middle tier of Mailwoman's geocode cascade when exact address-point data is unavailable.
intersection
An address that names a location by two crossing streets ('5th & Main') rather than a number and street. Mailwoman tags the two streets as intersection_a and intersection_b — a negative-space format that starved the early model.
isotonic calibration
A post-hoc calibration that fits a monotonic map from raw model scores to true probabilities without retraining (via PAVA). Mailwoman's confidence calibrator.
iteration log
The running record of each model release — the canonical 'what shipped when' for the neural classifier.
Related terms: parity campaign, model card

J

joint decoding
A decode strategy where the neural model's proposals and rule-based solver's output are reconciled into a single parse tree. Formerly the default (Route A Phase II), now retired in favor of argmax after it was found to break the street+house_number geocode precondition.
JSEP (JavaScript Execution Provider)
onnxruntime-web's older WebGPU backend. A kernel bug on slice operations with axis reversal corrupted int8 dequantization in the browser; it has been superseded by the native WebGPU execution provider.

K

kind classifier
Stage 2.5 of the runtime pipeline: categorizes the input into one of seven query kinds (structured_address, postcode_only, locality_only, intersection, po_box, landmark, vague) so the coordinator can route to the right parsing strategy.
known format
A recognized postcode or postal pattern (US ZIP, UK postcode, French code postal) detected by regex in the query-shape stage to arm fast paths and locale hints.

L

label smoothing
A training regularization technique: instead of putting 1.0 probability on the correct label, train to put 1 − ε on it and ε/(N−1) on each wrong label. Improves calibration; disabled in some Mailwoman runs for stability.
label vacuum
A (token, label) pairing introduced by a synthetic shard with zero support in the existing corpus — a corpus-poisoning risk, since the model has no other evidence to anchor it.
Related terms: synthetic shard, corpus, starved
language model (LM)
A model that assigns probabilities to sequences of tokens. Used here mostly as a prior — an FST or n-gram model that biases the decoder toward plausible sequences via shallow fusion.
layer
One 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.
layer normalization
A 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.
leakage
Train/test contamination that inflates reported accuracy when eval data has effectively been seen in training. Mailwoman guards it with held-out-geography evals and locality-aware splits.
learning rate (LR)
How big a step training takes along the gradient each update. Too high and training diverges; too low and it crawls. Mailwoman warms it up, then decays it on a cosine schedule.
learning-rate schedule
A plan for changing the learning rate over training — Mailwoman's is linear warmup to a peak, then cosine decay toward zero. Smooths early instability and lets the model settle at the end.
Related terms: learning rate, warmup
lever-shape taxonomy
A classification of parity-gap fixes by mechanism: distributional tags (street_prefix, unit, locality) need synthetic shards plus retraining; closed-vocab tags (country, po_box, cedex) respond better to deterministic matchers as proposal sources.
libpostal
An open-source C address parser used by Pelias. Mailwoman's rule-based v0 and neural classifier supersede it.
LLM-as-corpus-generator
Using a large language model to synthesize annotated training rows for low-data or multilingual cases, gated by alignment validation that rejects rows whose components don't substring-match the surface.
locale
The combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.
Related terms: locale gate, model weights
locale gate
Stage 2 of the runtime pipeline: rule-based locale detection from the query shape's script and known-format signals. Returns a LocaleHint with the top candidate and alternatives, surfacing disagreement with an explicit --locale flag.
locality
The city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy.
locality centroid
The representative centre point of a city or locality, used as a coarse coordinate when no exact address point is available — the coarsest tier of the geocode cascade.
locality-aware split
Partitioning the corpus so all rows from one locality land in the same train/val/test split, preventing the model from memorizing a place in training and being scored on it in test.
Related terms: leakage, honest eval, golden set
logit
A raw, unnormalized per-label score the model outputs before softmax. Priors and biases are added in logit space, then softmax turns logits into probabilities.
loss function
A number measuring how wrong the model's predictions are on a batch of examples. Training minimizes it. Mailwoman's loss combines per-token negative log-likelihood with the CRF sequence loss.

M

machine learning (ML)
Building systems that learn patterns from examples instead of following hand-written rules. Mailwoman's neural classifier is trained on millions of labeled addresses rather than programmed with parsing rules.
macro F1
The unweighted average of per-class F1 scores — treats every class equally. Mailwoman's primary label-level eval metric.
Related terms: F1 score, eval
max sequence length
The maximum number of tokens the model can process at once. Inputs longer than the cap are truncated, dropping tail context.
Related terms: truncation, tokenizer, token
Mermaid
A Markdown-friendly diagram syntax used in these docs for flowcharts.
microhood
A Who's On First placetype for a very fine-grained neighbourhood subdivision, sitting below neighbourhood in the hierarchy.
model card
A JSON metadata file (model-card.json) shipped with each weights bundle. It declares the model version, lineage, label set, required inference channels (anchor, gazetteer), calibration data, and training provenance.
model weights
The learned parameters of the neural classifier, shipped as ONNX files in the @mailwoman/neural-weights-* packages. Weights are locale-specific bundles that include the model, tokenizer, and a model-card.json metadata file.
morphology FST
A finite-state transducer encoding street-typing affixes (Avenue, rue, Calle) from libpostal dictionaries, for morphological street recognition.
MUA (Medically Underserved Area)
A US federal designation for inadequate primary-care access, scored using the Index of Medical Underservice. Another downstream consumer of accurate geocoding.
multi-order training
Synthesizing the same address in multiple word orders — native postcode-first vs international house-number-first — so the model learns to read both layouts rather than overfitting one direction.

N

n-gram
A contiguous run of n tokens (a bigram is 2, a trigram is 3). Counting n-grams is a simple, pre-neural way to model which token sequences are common.
Related terms: language model, token, corpus
NAD (National Address Database)
A US Department of Transportation dataset of structured address points, added to the training corpus as a major source of real US addresses.
Related terms: corpus, situs data, TIGER
name-form variant
A resolver 'miss' that is really a measurement artifact: the right place is found but its gazetteer-canonical name differs from the eval's expected literal — 'St. Johnsbury' vs 'Saint Johnsbury'.
named intersection
A crossing that is itself a named place — common in Japan, e.g. the Shibuya Station-front intersection — rather than a pair of street names.
Related terms: intersection, chōme
NaN (not a number)
A floating-point result for an undefined operation (log of a negative, 0/0). Appearing in the training loss usually halts the run; recovering from it follows the NaN protocol.
NaN protocol
The NaN-recovery discipline: stop, change one variable, retry, document the hypothesis — never adjust two knobs at once during recovery, or you can't tell which change fixed it.
Related terms: NaN, divergence, verdict-smoke
negative space
Address formats the neural model was never trained on because they're absent from the base training corpus — PO boxes, CEDEX, intersections, units. The parity campaign targets negative space through synthetic shards and corpus augmentation.
neural classifier
The 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.'
neural network
A model made of layers of simple numeric units whose connection strengths (weights) are learned from data. The transformer encoder at Mailwoman's core is a neural network.
Related terms: transformer, parameter, layer
NG911 (Next Generation 911)
The modern 911 data standard. States and counties publish NG911 address-point layers that Mailwoman can ingest as address data.
Related terms: E911, situs data
night shift
An autonomous overnight agent session — training launches, evals, publishing, issue triage — that ends with a structured postmortem (what shipped, regressions, open questions) committed for handoff.
NLL (Negative Log Likelihood)
The standard form of a loss function in probability-based models: loss = −log P(correct label | input). The CRF uses the NLL of the entire label sequence.
Related terms: CRF, label smoothing
normalize
Stage 1 of the runtime pipeline: deterministic input preprocessing (Unicode NFC, punctuation normalization, whitespace collapse). Returns a NormalizedInput with an offsetMap that maps normalized positions back to the raw input.

O

offset map
A data structure that tracks how each position in a normalized string maps back to the original raw input. Essential for reporting parse results (spans) in the user's original text, not the internally normalized form.
Related terms: normalize, span
one-hot encoding
Representing a category as a vector that is 1 at the category's index and 0 everywhere else. The 'hard target' a classifier is trained toward — until label smoothing softens it.
ONNX (Open Neural Network Exchange)
An open format for machine learning models that enables interoperability between training frameworks and inference runtimes. Mailwoman ships its trained model as an ONNX file so it can run in Node.js and the browser via onnxruntime.
OpenAddresses (OA)
A global open aggregation of address points collected from many official sources. A primary source of component-supervised training data outside proprietary registries.
Related terms: corpus, OpenStreetMap, NAD
OpenStreetMap (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.
optimizer
The component that decides how to update parameters from the gradient — Adam/AdamW being the common choice, adding momentum and per-parameter scaling on top of plain gradient descent.
oracle substitution
A diagnostic that hands one pipeline stage the ground-truth answer and measures the end-to-end result, to find which stage an error actually lives in. Oracle the model's tags to measure the resolver's ceiling; oracle the gazetteer hints to measure the model's. Always an optimistic upper bound.
Related terms: honest eval, resolver, eval
orphan-I
A label-sequence bug where I-X appears without a matching preceding B-X (e.g. O, I-locality). Structurally invalid in BIO; the CRF prevents it.
overfitting
When a model memorizes quirks of its training set instead of learning general patterns, so it scores well in training but poorly on new data. Guarded against with held-out evals and regularization.
Overture Maps
An open consortium (Meta, Microsoft, AWS, TomTom) publishing Places and Addresses themes with GERS entity IDs. A candidate gazetteer source for POIs and street-level addresses.

P

p50 / p90 / p99
Coordinate-error percentiles: p50 is the median error, p90 the worst 10%, p99 the tail. Reported together so a high p50 (systematic error) is distinguished from a high p90/p99 with low p50 (concentrated edge-case error).
Related terms: coord metric, honest eval, Acc@1
padding token
A filler token added to short sequences to reach a fixed length, masked out during attention so it carries no meaning.
parameter
A 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.
parcel
A property polygon or record carrying a situs (site) address and often a separate owner mailing address. County GIS parcel aggregations are a training source for address-point variety and situs-vs-owner divergence.
Related terms: situs, situs data, rooftop
parent chain
The sequence of administrative parents above a place — Springfield → Sangamon County → Illinois → United States. Used to check the geographic coherence of a parse.
parent fallback
Retrying a zero-result parent-constrained resolver lookup ('find this locality inside this region') without the parent constraint but keeping the country, so a slightly-wrong parent doesn't produce silent zero results.
parity campaign
The systematic effort to close the gap between Mailwoman's neural parser and the legacy rule-based v0 parser on every address component tag. Tracked through per-tag parity tables and gated by honest-eval probes.
parity scorecard
The authoritative per-tag table tracking neural-vs-v0/Pelias F1 and resolver accuracy across head-to-head arenas. It answers 'where are we at parity, where do we still bleed?' and governs the parity campaign's priorities.
Parquet
The open columnar file format the corpus is written and streamed in. The training pipeline reads shards row-by-row from Parquet.
Related terms: shard, corpus
parse tree
The hierarchical address structure produced by decoding BIO labels into spans and nesting them per the schema's containment rules (house_number → street → locality → region → country).
Pelias
An open-source geocoder, Mailwoman's spiritual predecessor.
per-locale F1
Per-tag accuracy computed separately for each locale (US, FR, DE…) rather than aggregated, surfacing locale-specific regressions that macro F1 would mask under the dominant locale.
perplexity
How surprised a language model is by held-out text, expressed as the effective number of choices it was weighing per token; lower means better prediction. It is the standard health metric for generative models, with a classic trap: it is computed per token, so models with different tokenizers cannot be compared on it. Mailwoman does not gate on perplexity — a token classifier is graded on labels and, ultimately, coordinates — but the same trap governs our own metrics: parse-F1 is never compared across tokenizer versions.
phase
A milestone in the implementation plan (Foundation, Corpus, Training, Integration, and forward-looking phases). Distinct from stage (runtime pipeline) and tier (model vocabulary).
Related terms: stage, tier, thread
phrase grouper
Stage 2.7 of the runtime pipeline: proposes coherent input units (street phrase, locality phrase, postcode, etc.) with structural kind hypotheses. Decouples boundary discovery from type classification so the classifier answers 'what type?' not 'where?'
phrase kind
The structural category a phrase-grouper proposal carries — NUMERIC, STREET_PHRASE, LOCALITY_PHRASE, REGION_ABBREVIATION, POSTCODE, VENUE_PHRASE, HYPHENATED_COMPOUND — a 'where, not what' hypothesis.
placetype
The Who's On First hierarchical classification of places: planet → continent → country → region → county → locality → neighbourhood. The resolver uses placetype to rank candidates — an exact locality match outranks a county-level match.
PO box
A numbered mailbox at a post office used as a delivery address instead of a physical street location. Mailwoman tags it as the po_box component; structurally the same family as a subpremise.
point 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.
Related terms: venue, amenity, franchise query
policy registry
The per-component table that decides which classifier (rule or neural) has authority for each address component. The Ship-of-Theseus dial.
postal city
The city name the postal service uses for a ZIP, which can differ from the legal municipality a resident lives in — e.g. many suburbs share a larger city's postal name. A source of locality ambiguity.
postcode
The 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.
Postcode Address File (PAF)
Royal Mail's authoritative database of valid UK postcodes and their delivery points. The UK equivalent of the USPS AMS.
posterior (country posterior)
A per-country probability map — e.g. {GB: 0.8, FR: 0.06} — expressing how likely an input belongs to each country, produced by a model (the coarse placer's softmax, or a postcode anchor's lookup) AFTER seeing the input (hence 'posterior', from Bayesian usage: the updated belief). The resolver consumes it as a soft ranking boost (anchorPosterior): each candidate's score gains weight × posterior[candidate.country]. Values lie in [0, 1] and need not sum to 1 (in-map marginals exclude the OTHER class).
Related terms: coarse placer
precision
Of 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.
Related terms: recall, F1 score, macro F1
production scorer
The canonical inference API in @mailwoman/neural. It reads the model-card.json requires block and fails closed if a declared channel (anchor, gazetteer) isn't fed — preventing silent degradation from running the model out-of-distribution.
prominence (candidate prominence)
A candidate place's combined importance for within-tier ranking: the population term (log-scaled, capped at populationBoost, default 4.0) plus the best proximity-bias term (distance-decayed, capped at biasBoost, default 4.0). Domain: [0, populationBoost + biasBoost], typically [0, 8]; higher = more prominent = ranked earlier WITHIN an exact-match tier. It exists because raw text-match scores (bm25) are length-poisoned for famous places, so ties among equally-exact matches break by prominence instead of score.
Related terms: exact-match tiering
prominence signal
A ranking input that favours the better-known place among same-named candidates — the original Eiffel Tower in Paris over a replica in Las Vegas. Closely related to the importance score.

Q

query kind
The coarse category the kind classifier assigns to the whole input — postcode_only, locality_only, structured_address, intersection, po_box, landmark, or vague — used to route processing.
query shape
Stage 1.5 of the runtime pipeline: computes a structural fingerprint of the input — script class, segmentation, known-format hits (postcode regexes, state abbreviations) — in microseconds without ML. Used by downstream stages for locale detection and kind classification.

R

R*Tree
SQLite's spatial index of bounding boxes, enabling fast geographic range and nearest-neighbour queries in the resolver.
Related terms: resolver, FTS5, H3
recall
Of 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.
Related terms: precision, F1 score, macro F1
record matching
The process of determining whether two database records refer to the same real-world entity. Mailwoman's matcher uses a geocode-first approach (match the resolved place, not the address string) with Fellegi-Sunter probabilistic scoring.
region
The first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality.
Related terms: locality, country, component tag
regional variant
A local term for an amenity or brand differing from the global name — 'servo' for a gas station in Australia, 'bodega' for a corner store in NYC.
Related terms: amenity, code-switching
regularization
Techniques that discourage a model from overfitting — label smoothing, dropout, weight decay. They trade a little training accuracy for better generalization.
reject rate
The fraction of generated or harvested rows that fail validation and are excluded from the corpus — a quality gauge for a synthesis source.
residual connection
A shortcut that adds a sublayer's input to its output, so information and gradients flow easily through deep stacks. Part of why deep transformers train at all.
resolver
The 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.
rooftop
Geocoding precision at the building or parcel level — coordinates within a few metres — the highest tier of the geocode cascade. Sourced from address-point and situs data.
rule-based classifier
Mailwoman's legacy v0 parser — a library of deterministic token classifiers (house number, street suffix, postcode, place name, etc.) composed by priority. Now primarily used for corpus labeling, fallback classification, and arbitration diagnostics.

S

sectional center facility (SCF)
A USPS regional mail-processing hub. The first three digits of a 5-digit ZIP identify the SCF, of which there are roughly 900 nationwide.
segment
A punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context.
self-conditioning
An 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.
SentencePiece
A language-independent subword tokenizer that splits text into pieces using a unigram language model. Mailwoman uses a SentencePiece tokenizer with a 48,000-token vocabulary and byte-fallback, trained on address data rather than general text.
sequence labeling
A machine learning task where a model assigns a label to each element in a sequence. In Mailwoman, the sequence is the tokenized address string and the labels are address component types (street, locality, postcode, etc.).
shallow fusion
Blending an external knowledge source (a gazetteer, an FST prior) into a model's decision as a signal, rather than retraining the model or overriding its output. Mailwoman applies it at the input layer (the gazetteer anchor as membership features) and at decode time (an FST prior biasing emissions). RAG-shaped, but the retrieval lands as feature vectors, not prompt text.
shard
A partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row.
Related terms: corpus, synthetic shard
Ship of Theseus
The migration pattern Mailwoman uses: replace rule classifiers with the neural classifier one component at a time, only when metrics justify it. Named for the philosophical thought experiment.
situs
The physical site address of a property, as opposed to the owner's mailing address. Parcel records often carry both; the divergence is a real-world data-quality challenge.
Related terms: parcel, situs data, rooftop
situs data
A dataset of exact address-point coordinates (rooftop-level). Mailwoman's geocoder uses a national situs layer (124.9M US points built from state address-point sources) as the highest-precision tier of the geocode cascade.
Related terms: geocoding, geocode cascade
soft features
Auxiliary input signals fed to the neural classifier that inform but never override the model's decisions. Mailwoman's soft features include the postcode anchor (a coordinate centroid for recognized postcodes) and gazetteer lexicon hits (known place names).
soft prior
Outside 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.
soft signal
An informative but non-authoritative input to ranking — user location, a language prior, a coarse-country guess — that biases the resolver but never hard-filters candidates. The resolver-side cousin of a soft prior.
softmax
The function that converts a vector of logits into a probability distribution summing to 1, applied after priors and biases are added to the emission logits.
source weighting
Multiplicative per-source weights applied during training to oversample underrepresented corpus sources, balancing a corpus dominated by a few large datasets.
Related terms: corpus, shard, synthetic shard
span
A 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.
SQLite-wasm
An open-source build of the SQLite library compiled to WebAssembly. Mailwoman uses it to run the WOF resolver inside the browser.
Related terms: WOF, resolver, gazetteer
stage
One 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).
Related terms: staged pipeline, tier, phase
staged pipeline
Mailwoman'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.
starved
A tag with too little training representation to learn — near-zero F1 — because the corpus adapter never emits examples of it (intersection tags sat at 0% until an intersection synthesizer existed).
station entrance
One of several access points to a large transit station. Entrances at stations like Tokyo or Shibuya can be hundreds of metres apart, so entrance-level precision matters for navigation.
street
The named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.
street affix
A modifier on a street name indicating type or direction — Street, Avenue, rue, Calle, N, East. Mailwoman tags these as street_prefix / street_suffix, recognized via a morphology FST.
street-supplement architecture
The four-layer FST stack — morphology, candidacy, identity, schema — that fills the Who's On First street-level hierarchy gap, since WOF has no street node between locality and address.
sub-brand
A branded variant within a larger franchise — Walmart Supercenter vs Walmart Neighborhood Market vs Sam's Club, all under Walmart.
Related terms: franchise query
subpremise
A secondary address unit inside a single street address (apartment, suite, floor), typically a designator plus an identifier such as 'Apt 4B'. The same proposer family as PO box.
Related terms: unit, designator, PO box
subword tokenization
Splitting words into smaller learned pieces so a fixed vocabulary can spell any word — common words stay whole, rare ones break into parts. The approach SentencePiece implements.
synonymy
Many surfaces, one referent: '123 N Main St' and '123 North Main Street' are the same place. Handled by canonicalization, never by guessing which spelling is right. The dual of homonymy.
synthetic shard
A machine-generated training dataset that augments the real-address corpus with targeted variations — reversed word order, missing punctuation, all-caps, boundary-stress patterns. Teaches the model to handle edge cases not present in the reference data.

T

thread
A parallel workstream within a release. Threads compose; they are not sequential milestones like phases.
Related terms: phase, parity campaign
tier
Internal 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.
TIGER
The US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data.
Related terms: corpus, NAD, interpolation
token
One 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.
Related terms: tokenizer, SentencePiece, span
tokenizer
The 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.
toponym
A proper name for a geographic place.
Related terms: gazetteer, venue, locality
training
The 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.
transformer
A neural-network architecture introduced in 2017 ('Attention Is All You Need'), the basis of modern NLP models. Mailwoman uses a small, encoder-only transformer.
transition matrix
The CRF's learned table of per-label-pair scores. It encodes which BIO transitions are preferred or forbidden — e.g. that an I-tag must follow a matching B- or I-.
Related terms: CRF, Viterbi decoding, orphan-I
transliteration
Converting a name from one writing system to another while preserving pronunciation (Cyrillic → Latin, for instance). Needed for multilingual address handling and corpus synthesis.
tree projection
The process of converting a flat list of labeled spans into a nested tree representation — street contains street_prefix and street_suffix, locality contains region. Enables hierarchical address operations like containment checks.
Related terms: span, decoder, containment
truncation
Cutting an input down to the max sequence length (or an LLM response to its token limit), discarding everything past the cap.
two-step floating catchment area (2SFCA)
A spatial-accessibility metric that measures provider supply against population demand within a distance threshold, with distance decay (the E2SFCA variant). Appears in Mailwoman's spatial-demand analysis of geocoded points.
Related terms: HPSA, MUA, geocoding

U

underfitting
When a model is too simple or undertrained to capture the patterns in its data, so it performs poorly even on the training set. The opposite failure from overfitting.
Related terms: overfitting, training
unit
A subdivision of a building — apartment, suite, floor — that refines a street address. Mailwoman's unit component; a designator plus identifier forms a subpremise.
unknown token
A placeholder for input not in the tokenizer's vocabulary. Byte fallback largely removes the need for one by encoding unseen characters as raw bytes instead.

V

venue
A 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.
verdict-smoke
A short diagnostic training run (≈1,500–3,000 steps) that must match the full run's gradient-noise profile, used to catch recipe instability before committing to a full 50k-step launch.
Viterbi decoding
A dynamic programming algorithm that finds the most likely sequence of hidden states (labels) given a sequence of observations (token emissions). Mailwoman uses Viterbi over a linear-chain CRF to produce globally coherent BIO label sequences from per-token model scores.
vocabulary
The 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.

W

WAL + Freeze
The SQLite build pattern for the gazetteer: ingest under WAL (write-ahead logging) for concurrent writes, then checkpoint, set journal_mode=DELETE, add indexes, ANALYZE, and VACUUM INTO to emit a clean read-only artifact with no sidecar files.
Related terms: SQLite-wasm, WOF GeoJSON, FTS5
warmup
The early phase of training where the learning rate ramps up from 0 to its peak value before cosine decay. Mailwoman uses a linear warmup.
Related terms: gradient clipping, Modal
Wikipedia importance
A place-notability score derived from the count and language spread of a place's Wikipedia articles, normalized to [0, 1]. A resolver ranking prior that helps pick the prominent same-named place.
WOF (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.
Related terms: gazetteer, resolver, placetype
WOF GeoJSON
The raw one-feature-per-file GeoJSON distributed by Who's On First repositories — the input that Mailwoman's WOF SQLite build consumes.
Related terms: WOF, SQLite-wasm, placetype

Z

ZCTA (ZIP Code Tabulation Area)
The US Census Bureau's polygon approximation of a ZIP code, generalized from census blocks rather than USPS delivery routes. Explicitly not USPS ground truth and often wrong in rural areas.
zero-shot
Evaluating or predicting on a class or geography the model never saw in training, with no in-context examples — the strongest test of generalization.

Total terms: 293