Documentation map

The switcher at the top of every docs page has nine sections. Here's what each one is for.

• Start here — the front door: install, your first parse, current status, releases, and how to contribute.
• Use Mailwoman — task-oriented recipes: batch geocoding, CSV ingest, timezone lookups, and the rest.
• Understand — the why and how: the problem Mailwoman solves, why address 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 hard, the alternatives, our approach, and concept deep dives.
• Reference — the contracts a build depends on: Current scope & roadmap, the ComponentTag schema, the runtime pipeline stages, and the other lookup docs kept in sync with the code. The roadmap question routes here — the Archive's plan directory is history, not the plan of record.
• Contribute — runbooks for working on the model, the trainingtrainingThe process of adjusting a model's parameters so its predictions match labeled examples, by repeatedly measuring error and nudging the weights to reduce it. Distinct from inference, when the trained model is run on new input. data, and operations, if you're extending Mailwoman itself.
• Archive — closed engineering records: dated plans, phasephaseA milestone in the implementation plan (Foundation, Corpus, Training, Integration, and forward-looking phases). Distinct from stage (runtime pipeline) and tier (model vocabulary).-by-phasephaseA milestone in the implementation plan (Foundation, Corpus, Training, Integration, and forward-looking phases). Distinct from stage (runtime pipeline) and tier (model vocabulary). build history, and superseded reference docs, kept for provenance.
• EvalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. reports — per-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.' score reports and parity scorecardsparity scorecardThe 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..
• Retrospectives — night-shift and project retrospectives.
• Legal — licensing, data provenance, and privacy.

What to trust

Only Reference is kept current with the code. Start here, Use Mailwoman, and Understand teach you how to use and reason about Mailwoman, and if something there conflicts with Reference, Reference wins.

Archive holds closed, dated records, left as they were written rather than rewritten. An archived page keeps its original URL, so old links and bookmarks still resolve; you land on a page that says it's superseded, not a dead end.

EvalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. reports and Retrospectives are records too, maintained separately from this reorganization.

If you land on an Archive page from a search result or an old link, that's expected. Check Reference or Start here for the current version of whatever it describes.