Deployment options
Every shape below runs the same engine. The shapes differ in what has to be resident on the machine and what you give up to get it there. Choose by the constraint you cannot change.
As a library
Run npm install and call a function. This shape has the fewest moving parts, and every other shape
is built on it. It opens no port, needs no supervised process, and makes no network calls that 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.
could fail on.
Choose it when Mailwoman runs inside an application you already deploy. You operate no second service, and the call pays no serialization cost.
As a self-hosted server
mailwoman serve gives you /v1/parse, /v1/geocode, /v1/batch, /v1/resolve and /v1/format
over HTTP, with an OpenAPI document the server emits itself. Run it in a container and mount 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. read-only.
Choose it when several services need addresses and you would rather run one geocoder than embed one
in each. Check two constraints before you commit. The published image is linux/amd64 only, because
onnxruntime-node has no musl prebuild and arm64 has not been verified. The :latest tag also lags
the npm releases, so pin a digest instead of assuming the tag is current.
On a serverless runtime
The engine fits on a serverless runtime after trimming. On the host the guide measured,
node_modules installed at 746 MB. Of that, 500 MB was ONNX RuntimeONNX (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. builds for hardware the machine
did not have, and deleting them reduced the install to 303 MB. A cold start on that host took about
1.1 s, and the one-time 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.' load accounted for 70% of it.
Those two numbers differ from the 707 MB and 523 MB that
Footprints and Overview report because
the hosts differ. The serverless guide measured a different machine, and npm selected different
runtime builds for its platform and Node version. Both figures are du on a real install. They show
that most of the install is runtime binaries you do not execute. Re-measure your own target before
you size a 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. to either number.
Choose it for spiky traffic that does not justify keeping a machine warm. The install size is the
main constraint. At 303 MB before 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., the install exceeds AWS Lambda's 250 MB unzipped limit, so
Lambda requires a container image or a layerlayerOne 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.. The data root must also be a real filesystem, because
SQLite needs pread on a local file descriptor.
Deploy on a serverless runtime
In the browser
@mailwoman/neural's browser runtime 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. in the tab, with the query text never leaving the page. The load is
about 50.4 MB of 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.' files plus one onnxruntime-web build between 12.5 MB and 25.4 MB, and a cold
load measured 1.7 s from 127.0.0.1.
Choose it for form autofill and validation while someone types. Two constraints decide whether it
suits you. First, you host 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. yourself. public.mailwoman.ai answers cross-origin
requests only for the demo's own domain, so a page on your domain receives no
Access-Control-Allow-Origin header and the fetch fails. Second, the browser runtime 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. but does
not resolve. To geocode in the tab, you need either a slim database built for your own coveragecoverageThe 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. or a
server call with the parsed components.
As an MCP server
@mailwoman/mcp exposes nine tools to a coding agent 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 the
layerlayerOne 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. readers among them. It opens no port and needs no deployment.
Choose it when the consumer is an agent rather than an application. The server communicates over
stdio only, so a client that cannot launch a subprocess cannot use it. It loads only the en-US
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..
Use the MCP server from an agent
What every shape shares
A worker runs one 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. at a time. 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. blocks the JavaScript threadthreadA parallel workstream within a release. Threads compose; they are not sequential milestones like phases. in all five shapes, so a single process serves one request at a time regardless of queue depth. Concurrency comes from running more instances, containers or processes.