Mailwoman β€” Neural Address Parser (en-US, v0.5.4)

Open-source neural address parser that runs entirely in the browser via ONNX Runtime Web.

Usage

import * as ort from "onnxruntime-web/webgpu"

// Load the model
const session = await ort.InferenceSession.create("https://huggingface.co/sister-software/mailwoman-en-us/resolve/main/model.onnx")

// Tokenize with the bundled SentencePiece tokenizer (see @mailwoman/neural for the wrapper)
// Run inference β†’ 21 BIO labels per token

For a high-level API see the mailwoman npm package.

Model details

Field Value
Architecture Transformer encoder (h384, 6L, 6H)
Parameters 38M (29M encoder + 9M embedding)
Vocabulary 48,000 (SentencePiece unigram, byte-fallback)
Max sequence length 128
Output labels 21 (1 O + 10 BIO tags Γ— 2)
Quantization int8 dynamic (28 MB)
FP32 size 117 MB
ONNX opset 17

Labels (Stage 2)

The model emits BIO-encoded labels for 10 address components:

  • country, region, locality, dependent_locality, postcode, subregion, cedex
  • venue, street, house_number

Stage 3 (street decomposition + unit + po_box + intersection) is planned for v0.6.0.

Training

Field Value
Corpus version 0.4.0
Tokenizer version 0.6.0-a0 (multi-script, 0% CJK byte-fallback)
Steps 100,000
Hardware NVIDIA A100-SXM4-40GB
Recipe v0.5.1 (constant LR, no smoothing, wof-admin: 2.0)

Training data sources:

  • OpenAddresses (CC-BY / public domain subsets) β€” global street-level addresses
  • Who's On First (CC-BY-4.0 + ODbL-1.0) β€” admin hierarchy for US, FR, JP, CN, KR, DE, GB
  • TIGER/Line (public domain) β€” US street segments
  • BAN (ODbL-1.0) β€” French street-level addresses

Evaluation

Test Result
Demo presets (6 canonical addresses) 6/6 correct
Golden eval exact match (4,535 entries) 17.0%

Note: exact-match metrics are not comparable across tokenizer versions. The v0.5.3 baseline (25.3%) used a different tokenizer and most "failures" are schema mismatch (golden set expects Stage 3 tags the model doesn't emit).

Limitations

  • English only: trained on US addresses primarily. French and other locales planned.
  • Non-Latin scripts: tokenizer handles CJK/Korean/Thai (0% byte-fallback) but training data is mostly Latin. CJK address parsing not yet validated.
  • Stage 2 schema: doesn't decompose streets into prefix/suffix or emit unit/po_box/intersection. Stage 3 v0.6.0 will.

Citation

@software{mailwoman2026,
  title = {Mailwoman: Neural Address Parser},
  author = {Ellis, Teffen and contributors},
  year = {2026},
  url = {https://github.com/sister-software/mailwoman},
  license = {AGPL-3.0}
}
Downloads last month

-

Downloads are not tracked for this model. How to track
Inference Providers NEW
This model isn't deployed by any Inference Provider. πŸ™‹ Ask for provider support