Packages
Scope
This page is curated rather than exhaustive. Mailwoman is 52 workspaces and 48 of them are on npm, but most arrive as a dependency of something else and are never named in an install command. Listed here are the packages a consumer installs on purpose.
For the full workspace inventory, including the build tooling and the 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. stagesstageOne 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). this page
leaves out, read
AGENTS.md in the repository. For
the sizes of everything here, see Footprints.
Every published package releases in lockstep on one version number, 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.' bundlesevidence 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. included, so a
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 version tracks the release rather than 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 own lineage. All packages are ESM
only. Eight of the 49 publishable manifests declare a Node floor of 24.18: the mailwoman entry
package and seven data-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. packages, @mailwoman/spatial among them. The rest declare no
engines field, so nothing stops npm installing them under an older Node — the floor is real for
all of them, and only eight state it.
Every package declares AGPL-3.0-only OR LicenseRef-Commercial except two:
@mailwoman/neural-weights-es-es and @mailwoman/neural-weights-it-it declare AGPL-3.0, both in
the repository and in what the registry serves. Verify any package's declaration with
npm view <package> license rather than assuming the project-wide string.
Start here
| Package | What it is | Install it when |
|---|---|---|
mailwoman | The CLI and createRuntimePipeline | Always. This is the entry point |
@mailwoman/neural-weights-en-us | The trained 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.' 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. | Always. Nothing 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. without a 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 |
Those two are the whole install for 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.. mailwoman pulls @mailwoman/core, @mailwoman/neural
and the 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. stagesstageOne 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). behind it, so you do not name them.
Locale bundles
Each adds a localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. to a running install. All of them overlay the en-us encoderencoderThe part of a transformer that turns input tokens into contextualized vector representations. Mailwoman's classifier is a small encoder-only transformer (~30M parameters). rather than replacing
it, so installing several costs localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. data rather than several modelsneural 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.'.
| Package | LocalelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. | What the overlay adds |
|---|---|---|
@mailwoman/neural-weights-en-us | United States | 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., 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., and US localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. data |
@mailwoman/neural-weights-fr-fr | France | Postcode anchorsanchor 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., a pair index, a localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. 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. |
@mailwoman/neural-weights-en-gb | Great Britain | Postcode anchorsanchor 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., a pair index, a localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. 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. |
@mailwoman/neural-weights-en-nz | New Zealand | A pair index, plus the shared surface lexicons |
@mailwoman/neural-weights-de-de | Germany | A pair index |
@mailwoman/neural-weights-es-es | Spain | A pair index |
@mailwoman/neural-weights-it-it | Italy | A pair index |
@mailwoman/neural-weights-en-in | India | A pair index |
What each overlay contains, and what a localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. claim means, is on Locales and tiers.
Geocoding
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. needs none of these. Turning a 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. into a coordinate needs 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. and a backend.
| Package | What it is | Install it when |
|---|---|---|
@mailwoman/resolver | Walks a 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. and decorates nodes with coordinates and attribution | You geocode. It is backend-agnostic |
@mailwoman/resolver-wof-sqlite | The Node 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. backend, over node:sqlite | You geocode on a server |
@mailwoman/resolver-wof-wasm | The browser 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. backend, over @sqlite.org/sqlite-wasm | You geocode in a browser |
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. database itself is a separate download and is in no package. Run
mailwoman data pull candidate — see Geocode a CSV.
Browser
| Package | What it is | Install it when |
|---|---|---|
@mailwoman/neural | Carries the browser runtime too, at ./web-loader and ./web-onnx-runner | You 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. client-side. WebGPU, with a WebAssembly fallback |
onnxruntime-web | The inferenceinferenceRunning 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. runtime itself — an optional peer, so install it yourself | You 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. client-side |
@mailwoman/resolver-wof-wasm | The browser 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. backend | You also geocode client-side |
Both ONNX runtimesONNX (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. are optional peer dependencies of @mailwoman/neural: a browser app installs
onnxruntime-web, a Node service installs onnxruntime-node, and neither pays for the other's
binaries. Neither is installed for you.
@mailwoman/neural-web still publishes, and is now a deprecated re-export shim over those two
subpaths. Existing imports keep working — every name is re-exported at its original identity — but new
code should import from @mailwoman/neural.
Parse in the browser wires it up.
Servers
| Package | Serves | Install it when |
|---|---|---|
@mailwoman/api | The native /v1 surface | You want the shape this project controls |
@mailwoman/nominatim | /search, /reverse, /lookup, /status | You are replacing a Nominatim deployment |
@mailwoman/photon | /api, /reverse | You are replacing a Photon deployment |
@mailwoman/libpostal | /parse, /expand | You are replacing a libpostallibpostalAn open-source C address parser used by Pelias. Mailwoman's rule-based v0 and neural classifier supersede it. HTTP deployment |
@mailwoman/mcp | An MCP server over stdio: 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., geocode, 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. search, and more | You are giving an agent a spatial toolset |
The three drop-ins each declare one unscoped binary, so npx @mailwoman/nominatim serve reaches it
without naming the binary, and an install puts nominatim, photon and libpostal in
node_modules/.bin. @mailwoman/mcp declares mailwoman-mcp. @mailwoman/api declares none: it is
a library, and mailwoman serve is its command. The endpoint tables are on
HTTP APIs.
Record work
| Package | What it is | Install it when |
|---|---|---|
@mailwoman/registry | The record-matching application: resolve messy records to geocoded entities | You are deduplicating a customer or vendor list |
@mailwoman/match | The matcher itself: blockingblockingThe 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., scoring, 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. | You are building your own matching 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. |
@mailwoman/record | The record schema and its per-field normalizers | You are feeding @mailwoman/match directly |
@mailwoman/formatter | The inverse of the parser: components to a string and a canonical match keycanonical keyA 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. | You render addresses, or you need a comparison key |
@mailwoman/address-id | A stable address primary key | You need exact-match joins rather than fuzzy ones |
Match messy records is the worked example.
Data and annotations
| Package | What it is | Install it when |
|---|---|---|
@mailwoman/annotations | The annotation contract, with a native shape and an OpenCage-compatible one | You want timezone, currency, or code annotations |
@mailwoman/codex | Per-address-system postal reference data and branded types | You validate 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. or street suffixesstreet affixA 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. yourself |
@mailwoman/spatial | Distance, bounding box, projection, point-in-polygon | You do spatial math beside a geocode |
@mailwoman/timezone-lookup | Server-side IANA timezone lookup by point | You need a timezone and are not using annotations |
@mailwoman/nuts-lookup | EU NUTS regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. lookup by point | You report against EU statistical regionsregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. |
@mailwoman/un-locode-lookup | Nearest UN/LOCODE | You work with trade or logistics codes |
The three lookup packages read databases built like 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., so each needs its data file as
well as its package. @mailwoman/annotations is the seam the drop-in servers already use, so a
Nominatim-shaped response carries these without your installing anything.
Errors
| Condition | Meaning | Next step |
|---|---|---|
Could not resolve @mailwoman/neural-weights-<locale> | The 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 for that localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. is not installed | Install it, or run mailwoman parse --download-weights |
ERR_REQUIRE_ESM or a require() failure | Every package is ESM only | Use import, or a dynamic import() from CommonJS |
A 503 from a geocodinggeocodingThe 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. endpoint | 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. package or 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. database is missing | Install @mailwoman/resolver-wof-sqlite and run mailwoman data pull candidate |
Versions differ across @mailwoman/* packages after an update | The release is lockstep; a partial update is a mixed tree | Update them together, or run mailwoman doctor |
Rationale
Lockstep versioning means one number answers "which release do I have" across every package at once. The cost is that the release number says nothing about 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.': most releases are code-only, so consecutive releases can carry the same 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.'. 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 carries its own model cardmodel cardA 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. with the lineage.
The 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. stagesstageOne 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). are published but unlisted here because naming them in an install is a signal you are building a 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. rather than using one. They are real packages with real contracts; they are just not the install surface.
See also
- Footprints — measured sizes for everything on this page.
- Locales and tiers — what each localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. 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. carries a claim for.
- What ships today — the current release and its limits.
- Install and first parse — the two-package install, executed.