Quality and evaluation

The parsing and resolution walkthroughs both end the same way: for current accuracy, see the evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. reports. If you're deciding whether to trust this system with a workload, that pointer deserves a page of its own: what gets graded, where the numbers live, what stops a bad 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.' from shipping, and where the current line is weak. Every number should trace to a dated artifact you can open; this page is the map of those artifacts.

Two grades, and which one to watch

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. and the geocode are graded separately, because they fail separately. 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. grade is per-component: for each tag (streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels., localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy., postcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one., …), how often the labeled 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. matches a gold labelground truthThe correct answer for an example, used as the standard a prediction is graded against. Mailwoman's ground truth is the hand-labeled golden set; its quality caps achievable accuracy., scored as F1 against a fixed golden setgolden setA hand-labeled evaluation dataset of US, French, and adversarial addresses used as ground truth for evals. plus held-out real-world slices. The geocode grade is the coordinate: great-circle distance from the resolved point to a surveyed truth point, read at the median and the tail, plus resolve-rate within a stated tolerance.

Watch the coordinate grade. 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. can be flawless and the answer still useless — "Springfield" tagged perfectly as a localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. and resolved to the wrong stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality.'s Springfield is a few-hundred-kilometre error wearing a correct labelcomponent tagOne of the 33 labels in Mailwoman's address schema — street, locality, region, postcode, house_number, unit, po_box, country, venue, intersection, and others. Each parsed span carries exactly one component tag.. The project's scope declaration makes this a standing rule: "Grade the assembled coordinatecoord metricThe primary evaluation metric: distance from the resolved coordinate to the true address point. Measured at percentiles (p50, p90) and as 'within X meters.' Prevents the label-F1 trap where a model scores higher on token labels but geocodes worse., never labelcomponent tagOne of the 33 labels in Mailwoman's address schema — street, locality, region, postcode, house_number, unit, po_box, country, venue, intersection, and others. Each parsed span carries exactly one component tag.-F1 alone." Labelcomponent tagOne of the 33 labels in Mailwoman's address schema — street, locality, region, postcode, house_number, unit, po_box, country, venue, intersection, and others. Each parsed span carries exactly one component tag. metrics stay in the battery as a drift backstop, on a re-score cadence described below.

The rule was paid for. An early resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon. evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. scored 93.7% localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. name-match on a Vermont slice while the median resolved coordinate sat 326 km from the truth — right names, wrong statesregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality., invisible to a string metric. The run that surfaced this (the honest-eval harness, 2026-06-08) is why coordinate grading leads everywhere now.

The 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. also holds geography out of 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. entirely (Vermont, Wyoming, and North Dakota for the US; Corse, Lozère, and Creuse for France — corpus/src/split.ts), so evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. rows drawn there measure generalizationgeneralizationA trained model's performance on data unlike its training set — new regions, new input distributions. The property honest eval is designed to measure. rather than memory. Eval discipline covers the rest of the craft: adversarial slices, false-negative bucketing, oracle substitutionoracle substitutionA diagnostic that hands one pipeline stage the ground-truth answer and measures the end-to-end result, to find which stage an error actually lives in. Oracle the model's tags to measure the resolver's ceiling; oracle the gazetteer hints to measure the model's. Always an optimistic upper bound. to attribute error to the right pipelinestaged pipelineMailwoman's runtime architecture: a sequence of pure-function stages (normalize → query-shape → locale-gate → kind-classifier → phrase-grouper → classifier → decoder) connected by typed handoffs. Each stage is published as its own npm package. 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)..

Where the numbers live

Three artifacts, each with a different job.

The dated evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. reports (evals/) are the narrative record: gate runs, benchmarks, diagnostics, and postmortemsexpectation-maximizationAn iterative algorithm that estimates model parameters when some variables are unobserved. In Mailwoman's matcher, EM learns the Fellegi-Sunter m and u parameters from unlabeled data — no training labels needed., grouped by topic (competitive parity, 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.' versions, resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon. and geo, calibration, 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.). Reports are point-in-time and say so; each statesregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. its own evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. set, channels, and quantization, because those evolve between eras.

The score ledger (evals/scores-by-version.json, repo root) is the machine-readable spine: one row per 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. run that produced shippable 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. or a measured baseline, validated against a JSON schema. Every row pins its provenance — which 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., which evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. set, which artifact bytes. From the v5.0.0 row, verbatim:

{
	"run_id": "v193a3-anchor-absorption-step080000-rescore-20260702",
	"model_path": "@mailwoman/neural-weights-en-us@5.0.0 (model.onnx md5 4dec4f460a934949580d8e7b43adae7e; weights = the v4.15.0 line unchanged)",
	"eval_set_version": "promotion-gate battery (v4.15.0-boundary): golden v0.1.2 + real-OOD + arena perturb"
}

The ledger has a documented hole: rows for 4.5.0 through 4.16.2 were never populated — it froze at v4.4.0 and was revived at the 2026-07-02 measurement re-anchor (#885), whose full re-score produced the v5.0.0 row above. The missing versions' headlines live in the release history and each version's model-card.json, and appending is now automated at the gate, so the freeze pattern shouldn't recur.

The parity scorecardsparity scorecardThe authoritative per-tag table tracking neural-vs-v0/Pelias F1 and resolver accuracy across head-to-head arenas. It answers 'where are we at parity, where do we still bleed?' and governs the parity campaign's priorities. (evals/competitive-parity/) are the authoritative per-tag tables. Each is emitted by the gate battery rather than hand-edited, names its graded artifacts by md5-pinned path (the published npm tarball's bytes, never a dev symlink), quotes the gate's floors above its tables, and keeps failing rows in view. The latest full re-score covers the shipped 5.0.0 line: 17 of 17 floors passed, and two regressions that no floor had caught went on the record — fr.cedex_real drifting 96.1 to 89.4 across eleven promotes, and an unfloored libpostallibpostalAn open-source C address parser used by Pelias. Mailwoman's rule-based v0 and neural classifier supersede it. arenaarenaA standardized test set probing one capability: libpostal (clean canonical), perturb (noisy and degraded), postal (edge formats). Each arena answers a different question about where rule vs neural wins. slipping 36 to 30. The cedexCEDEX (Courrier d'Entreprise à Distribution Exceptionnelle). A French postal routing for high-volume business mail: a CEDEX code delivers directly from a sorting centre, bypassing the local post office. A common negative-space format Mailwoman must parse. drift was largely recovered (89.4 to 93.1) two days later, in the v5.3.0 row: recorded, then repaired, both in the open.

What gates a change

Nothing promotes on a felt improvement. The full procedure is the model-work runbook; the reader's version is three mechanisms.

Gates are pre-registered. The target numbers and no-regression bounds for a change are written into the 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. config before the first optimizeroptimizerThe component that decides how to update parameters from the gradient — Adam/AdamW being the common choice, adding momentum and per-parameter scaling on top of plain gradient descent. step runs; the runbook's phrasing is "If you can't define the gate, you aren't ready to train." Written down first, a gate can't quietly bend around the result it was meant to judge.

Every candidate runs the same battery, whatever the change touched: per-locale F1per-locale F1Per-tag accuracy computed separately for each locale (US, FR, DE…) rather than aggregated, surfacing locale-specific regressions that macro F1 would mask under the dominant locale. floors for the US and France, a German word-order check, unitunitA subdivision of a building — apartment, suite, floor — that refines a street address. Mailwoman's unit component; a designator plus identifier forms a subpremise. and affix retention, the six demo presets, coordinate metricscoord metricThe primary evaluation metric: distance from the resolved coordinate to the true address point. Measured at percentiles (p50, p90) and as 'within X meters.' Prevents the label-F1 trap where a model scores higher on token labels but geocodes worse. on held-out geography, and a metamorphic 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. where labelcomponent tagOne of the 33 labels in Mailwoman's address schema — street, locality, region, postcode, house_number, unit, po_box, country, venue, intersection, and others. Each parsed span carries exactly one component tag.-preserving perturbations (casing, punctuation, a one-letter typo) must not move the resolved coordinate (input robustness explains why that 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. can't be overfit). The battery is a CLI:

$ mailwoman eval gate --help
Usage: Mailwoman CLI eval gate [options]

Promotion gate (#479) — eval battery + gate-spec floors → verdict.json

Options:
  --model [model]                          Candidate fp32 ONNX (required)
  --int8 [int8]                            Quantized int8 sibling — adds the int8 battery + delta cap
  --gate [gate]                            Gate-spec JSON: a path, or a spec name resolved against eval-harness/gates/ (required)
  …

(Trimmed; the other flags select tokenizertokenizerThe component that converts a raw address string into a sequence of numeric token IDs the model can process. Mailwoman's tokenizer is a SentencePiece unigram model trained specifically on postal addresses., model cardmodel cardA JSON metadata file (model-card.json) shipped with each weights bundle. It declares the model version, lineage, label set, required inference channels (anchor, gazetteer), calibration data, and training provenance., lexicon, output directory.) A pass prints the pre-filled mailwoman eval ledger-append command, so clearing the gate and extending the public record are one motion.

Floors don't drift. Between re-scores a floor is a fixed contract: measured-equals-floor passes, below fails, and shipping a failure anyway requires a written, operator-approved revision noted in that version's ledger row. Two floors currently sit at zero margin on purpose (us.postcode 95.0, fr.postcode 99.3, both set to measured values in a documented trade); any lossloss functionA number measuring how wrong the model's predictions are on a batch of examples. Training minimizes it. Mailwoman's loss combines per-token negative log-likelihood with the CRF sequence loss. there fails loudly rather than eroding quietly. Because a promote only checks the floors its spec names, a cadence rule backstops them: every five promotes, or any promote that lowers a floor, triggers a full per-tag re-score, published as a dated scorecard. The rule exists because v4.4.0 to v4.15.0 went eleven promotes without one; the re-anchor that paid the debt found the drift bounded and surfaced the two unsigned declines above — the kind a per-promote gate cannot catch.

A lever that fails its gate is reverted, and the falsification is written up with its mechanism at the same standard as a featurefeatureAn input signal a model conditions on. Beyond the raw tokens, Mailwoman feeds soft features — gazetteer-membership channels and the postcode anchor — that inform predictions without overriding them.. Methodology covers that side: pinned baselines, tracked expected-failures, and the regression suite as an executable bug log.

What a confidence of 0.88 means

Each parsed 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. carries a conf= value; the 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. page noted a calibrated version exists. What calibration buys: a calibrated 0.88 means the 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. is right about 88% of the time — a frequency you can set a threshold on, rather than a report of the 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.''s mood.

The mechanism is an isotonic lookup table fitted on addresses with known answers and graded on a slice the fit never touched. Measured there, expected calibration error dropped from 0.060 to 0.0055, and the calibration page reports the real-world-only figure (0.019, on OpenAddressesOpenAddresses (OA). A global open aggregation of address points collected from many official sources. A primary source of component-supervised training data outside proprietary registries. rows) next to the combined one, because the in-domain half flatters the result, and the flattery should stay visible. A single global table also leaves error on specific localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.: raw Dutch 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. measured 0.156 against 0.005 with their own table (the per-locale report has the full set), so 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. package ships both calibration.json and calibration-per-locale.json.

It's opt-in (createCalibrator from @mailwoman/core/decoder), because silently rewriting conf= values would break any consumer that pinned to the raw ones.

The resolve side gets the same treatment through a different number: uncertainty_m. The raw interpolationinterpolationA geocoding technique that estimates a coordinate along a street segment based on the house number range. Used as the middle tier of Mailwoman's geocode cascade when exact address-point data is unavailable. radius contained the true point only about 72% of the time; a conformal calibrationconformal calibrationA calibration method that adjusts per-prediction uncertainty so a target coverage (e.g. 90%) is guaranteed on held-out data, without retraining the model. factor, fitted per regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality., makes the shipped radius a bound that holds roughly 90% of the time. How close is close enough? turns that into a decision procedure for your tolerance.

How the comparisons are run

Mailwoman is benchmarked against Nominatim, PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor., and libpostallibpostalAn open-source C address parser used by Pelias. Mailwoman's rule-based v0 and neural classifier supersede it. on the coordinate, in one harness, with identical inputs: the same raw address string and the same countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. hint, passed in each system's own dialect (Nominatim's countrycodes, PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor.'s boundary.country). The primary metric is resolve-rate within 25 km of truth, a no-result counted as a miss. That threshold is coarse deliberately: Mailwoman often resolves to centroid tierstierInternal versioning of which label classes the model emits. Tier 1 is the coarse components (country, region, locality, postcode); Tier 2 adds venue, street, house_number; Tier 3 (future) would add attention, po_box, and POI venue subtyping. Historically called 'Stage 1/2/3' before the runtime-pipeline naming made that ambiguous., and a distance-to-rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few metres — the highest tier of the geocode cascade. Sourced from address-point and situs data. metric would reward the incumbents wherever they hold a rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few metres — the highest tier of the geocode cascade. Sourced from address-point and situs data.. Right-place is the fair primary test, and secondary metrics (conditional median error, the 1 km and 5 km tierstierInternal versioning of which label classes the model emits. Tier 1 is the coarse components (country, region, locality, postcode); Tier 2 adds venue, street, house_number; Tier 3 (future) would add attention, po_box, and POI venue subtyping. Historically called 'Stage 1/2/3' before the runtime-pipeline naming made that ambiguous.) keep the centroid-versus-rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few metres — the highest tier of the geocode cascade. Sourced from address-point and situs data. trade visible. The 3-way benchmark documents the scoring choices in full (including a correction that had been understating PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor.), and the dated headattention headOne of several parallel attention computations in a layer, each free to focus on a different kind of relationship between tokens. Their outputs are concatenated — 'multi-head attention'. Mailwoman uses 4 heads.-to-headsattention headOne of several parallel attention computations in a layer, each free to focus on a different kind of relationship between tokens. Their outputs are concatenated — 'multi-head attention'. Mailwoman uses 4 heads. live in the competitive-parity reports. Scores aren't quoted here; they age, and the reports carry their dates. How Mailwoman compares holds the capability-level comparison.

Where quality drops

Outside the claimed localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.. 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. is claimed per localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. and only with evidence: in the scope declaration's words, "a localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. is only claimed when a coordinate-graded evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. exists for it." The tier table is the boundary — US and France first-class and floor-gated; fourteen more localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. trained and coordinate-paneled; Norway and Sweden thinly measured (the Swedish panel: n=173, low power); Japan resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon.-route only, with no parser 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. claim. Beyond the table, output quality is unverified (no evidence either way), and a sample of your own data settles it faster than any claim here could.

On tags the golden setgolden setA hand-labeled evaluation dataset of US, French, and adversarial addresses used as ground truth for evals. barely contains. Golden-dev per-tag numbers mislead for thin tags: unit reads 6.3 there and 92.3 on the real-world slice, because the golden setgolden setA hand-labeled evaluation dataset of US, French, and adversarial addresses used as ground truth for evals. scarcely exercises it. The runbook's rule: for campaign tags, the real-OOD column is the truth. Check which evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. column a per-tag figure came from before trusting it.

On input shapes the 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. never taught. Multi-script and transliterated addresses are a known limitation, kept in a separately-reported adversarial slice rather than mixed into headline numbers: deltas there measure whether the limitation got fixed, not whether a release regressed. The characteristic 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. failures (boundary slips, fragmented multi-word names, lookalike digit strings) are described in the parsing walkthrough.

Where the fine-grained data ends. Wherever a rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few metres — the highest tier of the geocode cascade. Sourced from address-point and situs data. shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. exists, accuracy is a property of the data. The gap is 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.: on a 1,172-address Texas facility panel, the rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few metres — the highest tier of the geocode cascade. Sourced from address-point and situs data. tiertierInternal versioning of which label classes the model emits. Tier 1 is the coarse components (country, region, locality, postcode); Tier 2 adds venue, street, house_number; Tier 3 (future) would add attention, po_box, and POI venue subtyping. Historically called 'Stage 1/2/3' before the runtime-pipeline naming made that ambiguous. fired on 47% of rows and interpolationinterpolationA geocoding technique that estimates a coordinate along a street segment based on the house number range. Used as the middle tier of Mailwoman's geocode cascade when exact address-point data is unavailable. on a further 12.5%, leaving roughly 40% at town centroids. The result says so itself (resolution_tier: "admin"), and the demo map's 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. overlay fogs exactly the places the resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon. can't yet pin.

Checking your own workload

Everything above is measured on our panels, and your addresses are not our panels. Three cheap checks, in order of effort:

1. Run the demo presets, then your own strays. The demo's six preset addresses are the same ones every release must hold stable (mailwoman eval preset-compare); paste in a dozen of your ugliest real rows after them.
2. Batchbatch sizeHow many examples the model processes before each parameter update. Larger batches give smoother gradients but cost more memory; gradient accumulation simulates a big batch on a small GPU. a sample. Point POST /v1/batch at a few hundred representative rows. If you hold known-good coordinates for any of them, grade the way this project does: distance from truth, median and tail, not string similarity.
3. Read the fields that price the answer. resolution_tier names the grain reached, uncertainty_m bounds the error, and calibrated conf= supports a threshold — accept above it, route the rest to review. Good enough is a comparison against your tolerance; those three fields make the comparison possible.

If a claim in these docs and the artifact it points to ever disagree, the artifact wins — and the disagreement is a bug worth filing.