Skip to main content

Research and teaching

Mailwoman is a postal-address parser and geocoder that runs inside your own process from a modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' file on your own disk. For a research group or a classroom that means an install without an API key or a per-lookup bill, and data that never leaves the machine. The AGPL-3.0 release covers the parser, the geocoder and the base modelgolden masterThe from-scratch base model every capability comes from in ONE recipe with one provenance and zero named watches at ship — the starting line every fine-tune engagement inherits, with its Fisher artifact beside it., and an academic or student declaration adds the data tiers for a year.

Install and check​

bash
npm install mailwoman @mailwoman/neural @mailwoman/neural-weights-en-us
npx mailwoman setup

setup parsesaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates. a sample address through the installed 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.', lists the data tiers for the countries you name with their size, and offers the declaration below. It ships, with license declare, in the release after 10.7.0, and npm view mailwoman version tells you which release you have. The ten-minute trial walks the same steps one at a time.

Declare academic or student use​

bash
mailwoman license declare --intent academic --name "Dr You" --organization "Your University" --email you@example.edu
mailwoman license declare --intent student --name "You" --organization "Your School" --email you@example.edu

The key arrives at the address you give, the command waits for it and writes it under your config directory, and it lasts one year. It stays on the AGPL branch: the source offer applies to a modified copy you serve over a network, and a paper that uses the unmodified software owes attribution only. The key admits every published data tier to mailwoman data pull, and a geocode that a tier would have resolved further states the tier and the command that fetches it.

A thesis project with its own public repository may declare as an open-source project instead, with the repository's URL, and receive the key in the response.

Cite it​

The repository includes a CITATION.cff. GitHub renders it as a citation in APA and BibTeX. Cite the software and the version you ran. mailwoman doctor prints the version. Cite the data tiers you used by their vintage. Each artifact's manifest records it.

bibtex
@software{mailwoman,
	author = {Ellis, Teffen},
	title = {Mailwoman},
	url = {https://github.com/sister-software/mailwoman},
	version = {10.7.0},
	year = {2026}
}

What the data terms mean for a paper​

The code license and the data license are separate questions. The reference data comes from open sources with their own terms, and a paper that redistributes a derived dataset follows those terms. mailwoman data pull prints each bundleevidence bundleThe pair of retrieval-augmented input channels (street-type + locality-surface) that feed lexicon membership as soft per-token evidence alongside the text. Shipped in 6.7.0; trained natively from step 0 in the from-scratch base line.'s publishers, terms and obligations before it transfers a byte, and mailwoman license attribution prints what the installed 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. packages owe upstream. Read Security and compliance before you publish a derived dataset.

Reproducibility​

Every artifact is sealed and dated, each 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. package records its trainingtrainingThe process of adjusting a model's parameters so its predictions match labeled examples, by repeatedly measuring error and nudging the weights to reduce it. Distinct from inference, when the trained model is run on new input. sources in PROVENANCE.json, and the published evaluation reports state the held-out sets and the numbers for each release. A result from one version and one artifact vintage can be reproduced from those records.