Contributing & feedback

This page covers how to obtain Mailwoman, how to report bugs or request enhancements, and what a contribution needs to be accepted. It mirrors the repository's CONTRIBUTING.md; where the two differ, the repository copy governs code contributions and this page will be corrected.

Obtaining Mailwoman

• Install from npm: npm install mailwoman (the CLI + library), or any of the scoped packages at https://www.npmjs.com/org/mailwoman. Model weightsmodel weightsThe learned parameters of the neural classifier, shipped as ONNX files in the @mailwoman/neural-weights-* packages. Weights are locale-specific bundles that include the model, tokenizer, and a model-card.json metadata file. ship as data-only packages (@mailwoman/neural-weights-en-us, -fr-fr).
• Try it without installing: the in-browser demo at mailwoman.sister.software/demo, or the hosted Photon-compatible trial endpoint at photon.sister.software (e.g. /api?q=berlin&limit=3).
• Getting-started guide: /docs/getting-started.

Feedback: bugs and enhancement requests

• Email, always answered: teffen@sister.software — bug reports, enhancement requests, and questions. For 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. bugs, include the input string, the result you got (the trial endpoint is fine for reproduction), and the result you expected.
• The full issue tracker accompanies the source repository, which is in the final stagestageOne 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). of preparation for public release; until then, email is the front door and every report is triaged into the tracker.
• A useful bug report for a parser/geocoder is small: one address in, one wrong answer out. Reports like that routinely become permanent regression tests within days.

Contributing

For anything larger than a typo or an obvious fix, get in touch first so we can agree on the approach before you spend the 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.'-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. work (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., 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. shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row., evalsevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error.) has its own gates and runbook: Contributing model work.

Requirements for acceptable contributions

1. Contribution terms — DCO + license grant. Mailwoman is dual-licensed (AGPL-3.0-only or commercial; see Licensing). Every contribution must arrive under terms that permit both: you certify the Developer Certificate of Origin 1.1 and sign off each commit (git commit -s), you retain your copyright, and you grant Teffen Ellis (DBA Sister Software) a perpetual, worldwide, non-exclusive, royalty-free, irrevocable license to use, modify, distribute, sublicense, and relicense the contribution — including under the AGPL and the commercial license — plus a patent license on AGPL §11 terms. Corporate CLA needed instead? Email teffen@sister.software. The complete legal text lives in the repository's CONTRIBUTING.md.
2. Coding standard. TypeScript throughout; linting and formatting are enforced by oxlint + oxfmt (yarn lint must pass — the pre-commit hook runs it on staged files and CI runs it repo-wide). Source runs directly under Node (erasable-syntax-only TypeScript: no enum, no parameterparameterA 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. properties); relative imports carry explicit .ts extensions. House conventions that lint can't express — acronym casing (parseJSON, not parseJson), workspace layout, database idioms — are documented in the repository's AGENTS.md and apply to all contributions.
3. Tests. Tests are co-located (*.test.ts, vitest) and yarn ci:test must pass. A bug fix should arrive with the test that would have caught it. Changes that can move 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. result face the release gauntlet — the executable regression log, metamorphic invariants, and held-out statistical gates described in Methodology.
4. Commits and PRs. Conventional-commit messages (fix(scope): …), branched off main, one concept per PR, CI green (Test + Docs workflows).

Questions that fit none of the above: teffen@sister.software.