Phase 5 — Studio (Human-in-the-Loop Correction)

Goal: a web UI where humans can paste an address, see the 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., correct spansspanA contiguous range of characters or tokens in the input string, tagged with an address component type (street, locality, postcode, etc.). Parsed addresses are represented as collections of spans, possibly nested in a tree., and submit corrections. Corrections feed back into corpuscorpusThe BIO-labeled training data used to train Mailwoman's neural classifier. Assembled from real sources (OpenAddresses, National Address Database) and synthetic shards (boundary stress, order variants, negative space). Managed by @mailwoman/corpus. retraining. This is the commercial differentiator — enterprises will pay for the ability to correct their own address data.

Status: deferred until PhasephaseA milestone in the implementation plan (Foundation, Corpus, Training, Integration, and forward-looking phases). Distinct from stage (runtime pipeline) and tier (model vocabulary). 3 has shipped and gathered usage. Do not begin PhasephaseA milestone in the implementation plan (Foundation, Corpus, Training, Integration, and forward-looking phases). Distinct from stage (runtime pipeline) and tier (model vocabulary). 5 without explicit confirmation.

This document is a sketch. Detailed plan will be written when PhasephaseA milestone in the implementation plan (Foundation, Corpus, Training, Integration, and forward-looking phases). Distinct from stage (runtime pipeline) and tier (model vocabulary). 5 begins.

Why this matters

• Address 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. has a long tail of localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.-specific edge cases that no amount of pretraining catches
• Customers with their own address datasets (real estate, logistics, government compliance) need to fix 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.' output for their data
• The studio is what turns a free library into a commercial product line

Sketch of components

Frontend

• React or Svelte (project creator's call)
• Paste address → see live 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. with spanspanA contiguous range of characters or tokens in the input string, tagged with an address component type (street, locality, postcode, etc.). Parsed addresses are represented as collections of spans, possibly nested in a tree. boundaries
• Drag spanspanA contiguous range of characters or tokens in the input string, tagged with an address component type (street, locality, postcode, etc.). Parsed addresses are represented as collections of spans, possibly nested in a tree. edges to adjust boundaries
• Right-click spanspanA contiguous range of characters or tokens in the input string, tagged with an address component type (street, locality, postcode, etc.). Parsed addresses are represented as collections of spans, possibly nested in a tree. to relabel component
• Submit correction with optional notes

Backend

• Postgres table: corrections { id, raw, original_parse, corrected_parse, user_id, project_id, created_at, notes }
• API: POST /corrections, GET /corrections?project_id=...
• Auth: minimal — project tokenstokenOne word or subword in the tokenized input. For the neural classifier, tokens come from SentencePiece (subword units); for the rule classifiers, tokens are whitespace- and punctuation-separated words., no full user system v1

Retraining loop

• Nightly job: dump new corrections to /data/corpus/sources/corrections/
• Tag with high sample weightparameterA 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.
• Trigger retraining (manual confirmation, not automatic — corrections can be adversarial)

What Phase 3 should leave in good shape

• ClassificationProposal carries enough info to round-trip through human correction
• The output format includes character offsets (it does) so spanspanA contiguous range of characters or tokens in the input string, tagged with an address component type (street, locality, postcode, etc.). Parsed addresses are represented as collections of spans, possibly nested in a tree. editing is mechanical
• Telemetry hooks exist to count "user accepted the 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. as-is" vs "user corrected" — informs which components most need correction

Open questions for when Phase 5 begins

• Is this open source or commercial-only?
• How does the correction format become 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. data? (BIO labelsBIO tagging (Begin-Inside-Outside). A token-level labeling scheme where each token is tagged as B-X (beginning of an entity of type X), I-X (inside an entity of type X), or O (outside any entity). Mailwoman uses BIO over SentencePiece tokens to annotate address components. need to be re-derived from corrected components)
• Quality gating: are all corrections trusted equally, or does each project's corrections only affect that project's 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.'?
• Does the studio host its own 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.' fine-tuned on the project's corrections?