32 docs tagged with "Architecture"

The knowledge ladder explains why the v0.5.0 pipeline grew two new information layers (Stage 2.7 phrase grouper, expanded Stage 5 reconcile). This article walks through what they actually do on one concrete input, end-to-end.

The neural classifier's encoder is a 6-layer transformer with bidirectional

After the encoder produces emissions, the FST priors add their biases, and

The empirical-learner nature of the neural parser

A Conditional Random Field (CRF) is a structured-prediction layer that finds the best whole-sequence label assignment instead of picking each token's label independently. Mailwoman's model card carries crfatinference a Viterbi search over a frozen, hand-coded validity table, with no learned transition scores anywhere in the loop. This page explains what ships, and how it got here.

A short lineage for readers who already know Pelias.

The FST (finite-state transducer) gazetteer prior is the structure that lets the neural classifier benefit from everything Who's On First already knows. The neural model knows grammar; the gazetteer knows places. The FST is the bridge — pre-computed at build time so the classifier can consult it at inference time without paying gazetteer-lookup costs per token.

The neural classifier doesn't know what Boston is. It knows that the

Mailwoman started as the answer to a record-matching problem, not a parsing one.

Mailwoman v1 (the pre-2026 version, still living on as the rule classifiers inside v2) parses an address in four steps. This article walks through each one with a concrete example.

This is a roadmap snapshot, current as of May 2026. For current state, see the scope declaration, How Mailwoman parses an address, How Mailwoman resolves a place, and How it works now.

Mailwoman runs addresses through a staged pipeline. Each stage adds one kind of knowledge the stages below it cannot easily derive. Two models are involved, not one: a small coarse-placer that guesses the country up front (Stage 1.5), and the main neural classifier that labels the tokens (Stage 3). Rule classifiers run alongside the neural classifier, and a policy registry decides whose vote wins for each address component. Outside knowledge — postcodes, the gazetteer — reaches the model as soft hints called anchors, which inform a decision but never override it.

What kind of computation does mailwoman's neural parser do? When it looks at

_The target this document sets: an address should resolve to wherever its spans are jointly

This page used to be the primary explanation of Mailwoman's transformer encoder. It's been superseded — How the model reasons says so in its own See Also, and this page's numbers had drifted out of date besides. Rather than maintain two competing descriptions of the same architecture, here's where to go instead:

ONNX (Open Neural Network Exchange) is a standardized format for serializing trained neural networks. ONNX Runtime is the family of inference engines that consume those files. Mailwoman uses ONNX so the same trained model can run in Node.js, browsers, mobile devices, or anywhere else with an ONNX Runtime build.

A short article on the one non-obvious knob inside Stage 5's joint decoder. If you skip it the reconciler converges on the empty parse for every input.

Parsing answers "what kind of thing is each part of this string?". Resolving answers "where is the resulting place?". They are different jobs and Mailwoman keeps them apart on purpose.

A rule classifier is a small piece of hand-written code that labels tokens. Pelias and Mailwoman v1 are built almost entirely on rule classifiers. Mailwoman v2 keeps them and adds the neural classifier alongside — see How it works now for the hybrid.

There is one instinct hiding at two different scales in this system, and it is worth naming before you run into it twice and think you're looking at two different things.

This is the design reference for the work that fills the WOF hierarchy gap. It synthesizes the architectural decisions reached during the v0.6.1 postmortem and the subsequent design consult. Code in neural/, resolver-wof-sqlite/, and core/ refers back here; this article tells you why each piece looks the way it does.

An address parser has to hold two facts at once that feel contradictory until you

The staged pipeline is a contract for decomposition by what each layer knows. Every stage is the rightful home of a particular kind of information; pushing work to the wrong stage produces fragile systems that try to learn things from data that they could have looked up, or look up things that they could have learned. This article catalogues the layers, what each one knows, and the two layers we don't ship yet but should.

You don't have to take Mailwoman's pipeline as-is. The runtime coordinator (createRuntimePipeline) accepts each pipeline stage as an injectable function or interface; an integrator can swap any of them for a custom implementation without forking the core.

Reading Addresses that break geocoders makes one thing obvious: no single model handles every failure class well. Different failures want different fixes. Some want preprocessing rules, some want a small classifier, some want a transformer, some want a resolver that returns candidates instead of pretending to be sure.

Traditional address parsers split the input into tokens, classify each token independently, then try to reassemble the pieces into a coherent parse. This sequence contains a structural circularity: you cannot group tokens correctly without knowing their types, and you cannot type them correctly without knowing their groups. The traditional architecture resolves this with heuristics, exceptions, and solver post-processing. The exception pile grows without bound.

Who's On First is a place gazetteer. Mailwoman is an address parser. The two are misaligned at one specific point in the hierarchy — and that misalignment shapes how the neural model fails on street-level inputs.

Tokenization is the step that turns an input string into a list of small pieces called tokens. Every downstream component — rule classifiers, the neural classifier, the solver, the resolver — works with tokens, not with raw strings.

After the encoder produces per-token emission logits and the FST priors

In Mailwoman's architecture, a concordance is the resolver's answer to the question: "Do these parsed components form a coherent place in the real world?" It is the mechanism that prevents the parser from emitting a parse that is structurally valid but geographically impossible — like "Paris, Texas" labelled as "Paris, Île-de-France" or "NY-NY Steakhouse, Houston TX" with "NY" tagged as a region.

If you've tried to describe Mailwoman to someone and reached for "it's like

The first five articles in this track established the problem: