Deployment options

The engine is the same in every shape below. What changes is what has to be resident on the machine, and what you give up to get it there. Pick by the constraint you cannot move.

As a library

npm install and call a function. This is the shape with the fewest moving parts and the one every other shape is built on: no port, no process to supervise, and 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. that cannot fail on a network it never touches.

Pick it when Mailwoman runs inside an application you already deploy: there is no second service to operate, and no serialization cost on the call.

Library API

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.

Pick it when several services need addresses and you would rather run one geocoder than embed one in each. Two constraints are worth knowing before you commit: the published image is linux/amd64 only, since onnxruntime-node has no musl prebuild and arm64 has not been verified, and the :latest tag is behind the npm line — pin a digest rather than assuming it tracks.

Run the API server

On a serverless runtime

It fits, with trimming. On the host the guide measured, node_modules installed at 746 MB, of which 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 that machine did not have; deleting those took it to 303 MB. A cold start ran about 1.1 s there, 70% of it 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.

Those two numbers are not the 707 MB and 523 MB that Footprints and Overview report, and the difference is the host rather than the package: the serverless guide measured a different machine, where the runtime builds npm selected for its platform and Node version differ from the ones the footprints host got. Both are du on a real install. Read the figures as the shape of the problem — most of the install is runtime binaries you do not execute — and re-measure your own target before sizing 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.

Pick it for spiky traffic you would rather not keep a box warm for. The floor is the constraint: 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. does not fit AWS Lambda's 250 MB unzipped ceiling, so that platform means 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.. And the data root has to 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.

Pick it for form autofill and validation as somebody types. Two constraints decide whether it suits you. 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.sister.software answers cross-origin requests only for the demo's own domain, so a page on your domain gets no Access-Control-Allow-Origin header and the fetch fails. And 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. without resolving: 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. in the tab means either a slim database you 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.

Parse in the browser

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. There is no port and nothing to deploy.

Pick it when the consumer is an agent rather than an application. The constraint is transport: stdio only, so a client that cannot launch a subprocess cannot use it, and 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. are the only ones loaded.

Use the MCP server from an agent

What every shape shares

One worker is 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.. 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, so a single process serves one request at a time however deep the queue gets, and concurrency comes from instances, containers or processes rather than from the runtime.

Deploy it with Docker →