@mailwoman/registry 4.8.1 → 4.11.0

package/out/learned-scorer.js

@@ -0,0 +1,78 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The learned scorer (#603) — the production wiring for the gradient-boosted-tree model behind
+ *   {@link ResolveConfig.scorer}. Two pieces:
+ *
+ *   1. {@link createMatchFeaturizer} — the ONE feature extractor for a candidate pair, used identically
+ *        at train time (`scripts/record-matcher/train-gbt.ts`), eval time (the learned-scorer
+ *        evals), and inference time (here). A pair → one-hot of each comparison's agreement level +
+ *        the over-merge interaction terms (co-located × name/org disagreement) + address
+ *        crowdedness.
+ *   2. {@link createGbtScorer} — wraps a trained {@link GBT} + the featurizer into the `(a, b) => number`
+ *        the resolve pipeline's `scorer` hook expects (a logit, threshold-comparable with the
+ *        Fellegi-Sunter weight it replaces).
+ *
+ *   Both take the comparison set as INPUT (rather than importing {@link buildDefaultModel}) so this
+ *   module has no dependency cycle with `resolve.ts`. The contract that keeps train ≡ inference:
+ *   feed the comparisons from `buildDefaultModel({ collapseSpatial: true, addressFrequency })` —
+ *   the model's structure (and thus the feature layout) is fixed by that config; only the frequency
+ *   VALUES differ between the training corpus and the matched set, which is the point (the model
+ *   generalizes, as the cross-state eval showed).
+ */
+import { agreementPattern, gbtScore } from "@mailwoman/match";
+/**
+ * Build the per-pair feature extractor. The vector is: one-hot of each comparison's agreement
+ * level, then the two over-merge interaction terms (spatial-exact × name-disagree, spatial-exact ×
+ * org-disagree — the "same place, different names" signature that drives co-located over-merges),
+ * then address crowdedness scaled into [0, 1]. Deterministic and EM-independent, so it is identical
+ * across train / eval / inference.
+ */
+export function createMatchFeaturizer(config) {
+    const { comparisons, addressFrequency } = config;
+    const levelCounts = comparisons.map((c) => c.levels.length);
+    const index = Object.fromEntries(comparisons.map((c, i) => [c.name, i]));
+    const spatialI = index["spatial"];
+    const givenI = index["given"];
+    const familyI = index["family"];
+    const orgI = index["organization"];
+    const lastLevel = (i) => levelCounts[i] - 1;
+    return (a, b) => {
+        const pat = agreementPattern(comparisons, a, b);
+        const f = [];
+        for (let i = 0; i < pat.length; i++) {
+            const lvl = pat[i];
+            for (let l = 0; l < levelCounts[i]; l++)
+                f.push(lvl === l ? 1 : 0);
+        }
+        // Interaction: co-located (spatial exact = level 0) AND names/org disagree (catch-all level).
+        const spatialExact = spatialI !== undefined && pat[spatialI] === 0 ? 1 : 0;
+        const nameDisagree = givenI !== undefined &&
+            familyI !== undefined &&
+            pat[givenI] === lastLevel(givenI) &&
+            pat[familyI] === lastLevel(familyI)
+            ? 1
+            : 0;
+        const orgDisagree = orgI !== undefined && pat[orgI] === lastLevel(orgI) ? 1 : 0;
+        f.push(spatialExact * nameDisagree); // the over-merge signature: same place, names disagree
+        f.push(spatialExact * orgDisagree);
+        // Address crowdedness (how shared this address is) — high → "same address" is weak evidence.
+        const freq = a.address?.raw ? addressFrequency.frequency(a.address.raw) : 0;
+        f.push(Math.min(1, freq * 1000)); // scale into a usable range
+        return f;
+    };
+}
+/**
+ * Wrap a trained {@link GBT} into the `(a, b) => number` link scorer for
+ * {@link ResolveConfig.scorer}. The returned weight is the model's logit — same threshold-comparable
+ * units as the Fellegi-Sunter weight it replaces, so the pipeline's clustering + threshold
+ * semantics are unchanged.
+ */
+export function createGbtScorer(config) {
+    const featurize = createMatchFeaturizer(config);
+    const { model } = config;
+    return (a, b) => gbtScore(model, featurize(a, b));
+}
+//# sourceMappingURL=learned-scorer.js.map

package/out/learned-scorer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"learned-scorer.js","sourceRoot":"","sources":["../learned-scorer.ts"],"names":[],"mappings":"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"}

package/out/map-html.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Render resolved entities as a standalone map page — the visual complement to {@link toGeoJSON}'s
+ *   QGIS/analyst export. `toMapHTML(featureCollection)` returns one HTML file you open in a
+ *   browser; no server, no build.
+ *
+ *   It renders on the HOUSE stack: MapLibre GL + a Protomaps basemap (`@protomaps/basemaps` generates
+ *   the `layers()` for a named flavor) over the `basemap-v4` vector tiles served from R2 at
+ *   `tiles.sister.software` — the same basemap the demo uses. Each entity is a circle sized by
+ *   records-merged and colored by cross-dataset-link status (≥2 sources stand out), or
+ *   categorically by `bucket` when the reconciliation output carries one. Pure: GeoJSON in, HTML
+ *   string out (the Protomaps layer specs are generated at this point and inlined). The generated
+ *   page fetches MapLibre, the basemap tiles, and glyphs/sprite over the network when opened (the
+ *   house infra).
+ *
+ *   SERVE IT OVER LOCALHOST, don't open it as a file. The house tile server (`tiles.sister.software`)
+ *   CORS-restricts to localhost + the docs domains, so a `file://` page shows the (accurate)
+ *   markers on a blank basemap. `npx serve` / `python3 -m http.server` in the output directory is
+ *   enough; the page also surfaces a hint banner when it detects it's running from `file://`.
+ *
+ *   Neutral entity-resolution view: it shows what resolved to what and how confidently (cohesion).
+ *   Bucket labels render verbatim from the data, never editorialized.
+ */
+import type { GeoJsonFeatureCollection } from "./types.js";
+/** Protomaps stock flavors (shipped by `@protomaps/basemaps`). */
+export type MapFlavor = "light" | "dark" | "white" | "grayscale" | "black";
+export interface MapHTMLOptions {
+    /** Document `<title>` + on-map heading. Default: "Mailwoman — resolved entities". */
+    title?: string;
+    /** Protomaps basemap flavor. Default: "light" (data points read cleanly over it). */
+    flavor?: MapFlavor;
+    /**
+     * How to color the markers:
+     *
+     * - `"auto"` (default) — by `bucket` if any feature carries one (reconciliation output), else by
+     *   cross-dataset-link status.
+     * - `"sources"` — always by cross-dataset-link status (≥2 sources stand out).
+     * - `"bucket"` — always by the `bucket` property.
+     */
+    colorBy?: "auto" | "sources" | "bucket";
+}
+/**
+ * Render `geojson` (a {@link toGeoJSON} / reconciliation FeatureCollection) as a complete,
+ * standalone HTML document. Entities without a coordinate are already absent from those
+ * collections; an empty collection renders a friendly empty state rather than a broken map.
+ */
+export declare function toMapHTML(geojson: GeoJsonFeatureCollection, options?: MapHTMLOptions): string;
+//# sourceMappingURL=map-html.d.ts.map

package/out/map-html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"map-html.d.ts","sourceRoot":"","sources":["../map-html.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAA;AAuB1D,kEAAkE;AAClE,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,WAAW,GAAG,OAAO,CAAA;AAE1E,MAAM,WAAW,cAAc;IAC9B,qFAAqF;IACrF,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,qFAAqF;IACrF,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAA;CACvC;AAyBD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,wBAAwB,EAAE,OAAO,GAAE,cAAmB,GAAG,MAAM,CAmMjG"}

package/out/map-html.js

@@ -0,0 +1,262 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Render resolved entities as a standalone map page — the visual complement to {@link toGeoJSON}'s
+ *   QGIS/analyst export. `toMapHTML(featureCollection)` returns one HTML file you open in a
+ *   browser; no server, no build.
+ *
+ *   It renders on the HOUSE stack: MapLibre GL + a Protomaps basemap (`@protomaps/basemaps` generates
+ *   the `layers()` for a named flavor) over the `basemap-v4` vector tiles served from R2 at
+ *   `tiles.sister.software` — the same basemap the demo uses. Each entity is a circle sized by
+ *   records-merged and colored by cross-dataset-link status (≥2 sources stand out), or
+ *   categorically by `bucket` when the reconciliation output carries one. Pure: GeoJSON in, HTML
+ *   string out (the Protomaps layer specs are generated at this point and inlined). The generated
+ *   page fetches MapLibre, the basemap tiles, and glyphs/sprite over the network when opened (the
+ *   house infra).
+ *
+ *   SERVE IT OVER LOCALHOST, don't open it as a file. The house tile server (`tiles.sister.software`)
+ *   CORS-restricts to localhost + the docs domains, so a `file://` page shows the (accurate)
+ *   markers on a blank basemap. `npx serve` / `python3 -m http.server` in the output directory is
+ *   enough; the page also surfaces a hint banner when it detects it's running from `file://`.
+ *
+ *   Neutral entity-resolution view: it shows what resolved to what and how confidently (cohesion).
+ *   Bucket labels render verbatim from the data, never editorialized.
+ */
+import { layers, namedFlavor } from "@protomaps/basemaps";
+/** MapLibre GL release the page pins (CDN + SRI). Matches the workspace's `maplibre-gl` major. */
+const MAPLIBRE_VERSION = "5.24.0";
+const MAPLIBRE_JS_SRI = "sha384-5+cfbwT0iiub6VsQAdn6yz16nr6sDiQoHx6tm4O8OVYXHYOxcffFmCJBL0dgdvGp";
+const MAPLIBRE_CSS_SRI = "sha384-uTttxo/aOKbdE5RlD/SPzSDoDmNvGlUYPjONi2MN/b7c9HPSvW07OIuyP7uL6jxK";
+/**
+ * The house Protomaps basemap: `basemap-v4` PMTiles (tile-worker → R2 at `tiles.sister.software`,
+ * which sends CORS for localhost + the docs domains).
+ *
+ * Glyphs + sprite come from the UPSTREAM Protomaps assets (GitHub Pages, `ACAO: *`), not the house
+ * mirror at `public.sister.software` — that bucket sends no CORS headers, so the mirror can't be
+ * fetched cross-origin (`cartographer/base/composition.ts` flags the same: "Currently upstream
+ * URLs; we mirror these … but no public route fronts that bucket yet"). The upstream assets target
+ * the v4 schema, matching the `basemap-v4` tiles. Swap to the house mirror once it has a
+ * CORS-enabled route.
+ */
+const BASEMAP_SOURCE_ID = "basemap-v4";
+const BASEMAP_TILEJSON_URL = "https://tiles.sister.software/basemap-v4.json";
+const GLYPHS_URL = "https://protomaps.github.io/basemaps-assets/fonts/{fontstack}/{range}.pbf";
+const SPRITE_URL = "https://protomaps.github.io/basemaps-assets/sprites/v4/light";
+/** Categorical palette (reused for buckets; cycles if there are more buckets than entries). */
+const PALETTE = ["#2f9e44", "#f08c00", "#1971c2", "#e8590c", "#9c36b5", "#0c8599", "#e03131", "#5c940d"];
+const SINGLE_COLOR = "#3388ff"; // single-source entity
+const CROSS_COLOR = "#e8590c"; // cross-dataset link (≥2 sources)
+/**
+ * Escape a value for safe inlining inside a `<script>` as JSON. `JSON.stringify` alone isn't enough
+ * — a record value containing `</script>` would close the block early; escaping `<`/`>`/`&` to
+ * `\uXXXX` keeps the JSON valid and makes a breakout impossible.
+ */
+function safeJsonForScript(value) {
+    return JSON.stringify(value).replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/&/g, "\\u0026");
+}
+/** Escape text for the HTML document body (title/heading), not the inlined script. */
+function escapeHtml(text) {
+    return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function sourceCount(props) {
+    return Array.isArray(props["sources"]) ? props["sources"].length : 0;
+}
+/**
+ * Render `geojson` (a {@link toGeoJSON} / reconciliation FeatureCollection) as a complete,
+ * standalone HTML document. Entities without a coordinate are already absent from those
+ * collections; an empty collection renders a friendly empty state rather than a broken map.
+ */
+export function toMapHTML(geojson, options = {}) {
+    const title = options.title ?? "Mailwoman — resolved entities";
+    const flavorName = options.flavor ?? "light";
+    const colorBy = options.colorBy ?? "auto";
+    const hasBuckets = geojson.features.some((f) => f.properties?.["bucket"] != null);
+    const mode = colorBy === "auto" ? (hasBuckets ? "bucket" : "sources") : colorBy;
+    // Assign a color to each distinct bucket value, in first-seen order.
+    const bucketColors = {};
+    if (mode === "bucket") {
+        let i = 0;
+        for (const f of geojson.features) {
+            const b = f.properties?.["bucket"] != null ? String(f.properties["bucket"]) : "—";
+            if (!(b in bucketColors))
+                bucketColors[b] = PALETTE[i++ % PALETTE.length];
+        }
+    }
+    const colorFor = (props) => {
+        if (mode === "bucket") {
+            const b = props["bucket"] != null ? String(props["bucket"]) : "—";
+            return bucketColors[b] ?? SINGLE_COLOR;
+        }
+        return sourceCount(props) >= 2 ? CROSS_COLOR : SINGLE_COLOR;
+    };
+    // Precompute the per-feature color (`_color`) so the circle layer is a simple `["get","_color"]`,
+    // and the bounding box, both at generate time. The data is copied (not mutated in place).
+    let minLng = Infinity;
+    let minLat = Infinity;
+    let maxLng = -Infinity;
+    let maxLat = -Infinity;
+    const features = geojson.features.map((f) => {
+        const [lng, lat] = f.geometry.coordinates;
+        if (lng < minLng)
+            minLng = lng;
+        if (lat < minLat)
+            minLat = lat;
+        if (lng > maxLng)
+            maxLng = lng;
+        if (lat > maxLat)
+            maxLat = lat;
+        return { ...f, properties: { ...f.properties, _color: colorFor(f.properties) } };
+    });
+    const bbox = features.length ? [[minLng, minLat], [maxLng, maxLat]] : null;
+    // The full MapLibre style: the Protomaps basemap layers (generated here) over the house basemap-v4
+    // vector source, plus our inlined entities source + a circle layer keyed off the precomputed color.
+    const style = {
+        version: 8,
+        glyphs: GLYPHS_URL,
+        sprite: SPRITE_URL,
+        sources: {
+            [BASEMAP_SOURCE_ID]: { type: "vector", url: BASEMAP_TILEJSON_URL },
+            entities: { type: "geojson", data: { type: "FeatureCollection", features } },
+        },
+        layers: [
+            ...layers(BASEMAP_SOURCE_ID, namedFlavor(flavorName), { lang: "en" }),
+            {
+                id: "mw-entities",
+                type: "circle",
+                source: "entities",
+                paint: {
+                    "circle-radius": [
+                        "interpolate",
+                        ["linear"],
+                        ["coalesce", ["get", "recordCount"], 1],
+                        1,
+                        5,
+                        5,
+                        9,
+                        25,
+                        15,
+                        100,
+                        22,
+                    ],
+                    "circle-color": ["get", "_color"],
+                    "circle-stroke-color": "#ffffff",
+                    "circle-stroke-width": 1.2,
+                    "circle-opacity": 0.9,
+                },
+            },
+        ],
+    };
+    // Legend rows, built here so arbitrary bucket sets render without client-side guessing.
+    const legendRows = mode === "bucket"
+        ? Object.entries(bucketColors)
+            .map(([b, c]) => `<div><i style="background:${c}"></i>${escapeHtml(b)}</div>`)
+            .join("")
+        : `<div><i style="background:${CROSS_COLOR}"></i>cross-dataset link (&ge;2 sources)</div>` +
+            `<div><i style="background:${SINGLE_COLOR}"></i>single-source entity</div>` +
+            `<div class="muted" style="margin-top:4px">marker size = records merged</div>`;
+    const crossLinks = geojson.features.filter((f) => sourceCount(f.properties) >= 2).length;
+    const summary = `${geojson.features.length} entities` + (mode === "sources" ? ` &middot; ${crossLinks} cross-dataset links` : "");
+    // The client script avoids template literals and `${` so it survives this outer template verbatim.
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>${escapeHtml(title)}</title>
+<link
+	rel="stylesheet"
+	href="https://unpkg.com/maplibre-gl@${MAPLIBRE_VERSION}/dist/maplibre-gl.css"
+	integrity="${MAPLIBRE_CSS_SRI}"
+	crossorigin="anonymous" />
+<style>
+	html, body { margin: 0; height: 100%; font-family: system-ui, -apple-system, "Segoe UI", sans-serif; }
+	#map { position: absolute; inset: 0; }
+	.mw-panel {
+		position: absolute; z-index: 1; background: rgba(255,255,255,0.94); padding: 10px 12px;
+		border-radius: 8px; box-shadow: 0 1px 6px rgba(0,0,0,0.3); font-size: 12px; line-height: 1.5; color: #1a1a1a;
+	}
+	.mw-title { top: 10px; left: 10px; max-width: 60%; }
+	.mw-title h1 { font-size: 14px; margin: 0 0 4px; }
+	.mw-legend { bottom: 22px; right: 10px; }
+	.mw-legend i { display: inline-block; width: 12px; height: 12px; margin-right: 6px; border-radius: 50%; vertical-align: -1px; }
+	.muted { color: #666; }
+	.mw-popup { font-size: 12px; line-height: 1.5; max-width: 260px; }
+	.mw-popup .nm { font-weight: 600; font-size: 13px; }
+	.mw-popup dt { color: #666; display: inline; }
+	.mw-popup .link { color: ${CROSS_COLOR}; font-weight: 600; }
+	.mw-empty { position: absolute; inset: 0; display: grid; place-items: center; z-index: 1; }
+	.mw-warn { bottom: 10px; left: 10px; max-width: 52%; background: rgba(255,243,205,0.97); }
+	.mw-warn code { background: rgba(0,0,0,0.06); padding: 0 3px; border-radius: 3px; }
+</style>
+</head>
+<body>
+<div id="map"></div>
+<div class="mw-panel mw-title"><h1>${escapeHtml(title)}</h1><div class="muted">${summary}</div></div>
+${features.length ? `<div class="mw-panel mw-legend">${legendRows}</div>` : `<div class="mw-empty"><div class="mw-panel"><h1>${escapeHtml(title)}</h1><div class="muted">No geocoded entities to display.</div></div></div>`}
+<script
+	src="https://unpkg.com/maplibre-gl@${MAPLIBRE_VERSION}/dist/maplibre-gl.js"
+	integrity="${MAPLIBRE_JS_SRI}"
+	crossorigin="anonymous"></script>
+<script>
+"use strict";
+var STYLE = ${safeJsonForScript(style)};
+var BBOX = ${safeJsonForScript(bbox)};
+
+function esc(v) {
+	if (v === null || v === undefined) return "";
+	return String(v).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+
+function popupHtml(p) {
+	var rows = [];
+	var heading = p.name || p.organization || p.entityId || "entity";
+	rows.push('<div class="nm">' + esc(heading) + '</div>');
+	if (p.organization && p.organization !== p.name) rows.push('<div>' + esc(p.organization) + '</div>');
+	if (p.address) rows.push('<div class="muted">' + esc(p.address) + '</div>');
+	rows.push('<hr style="border:none;border-top:1px solid #eee;margin:6px 0" />');
+	rows.push('<div><dt>records merged:</dt> ' + esc(p.recordCount) + '</div>');
+	var srcs = Array.isArray(p.sources) ? p.sources : [];
+	if (srcs.length) {
+		var cls = srcs.length >= 2 ? ' class="link"' : '';
+		rows.push('<div><dt>sources:</dt> <span' + cls + '>' + esc(srcs.join(", ")) + '</span>'
+			+ (srcs.length >= 2 ? ' (cross-dataset link)' : '') + '</div>');
+	}
+	if (p.bucket !== null && p.bucket !== undefined) rows.push('<div><dt>bucket:</dt> ' + esc(p.bucket) + '</div>');
+	if (p.cohesion !== null && p.cohesion !== undefined) rows.push('<div><dt>cohesion:</dt> ' + esc(p.cohesion) + ' bits</div>');
+	if (p.geocodeTier) rows.push('<div><dt>geocode tier:</dt> ' + esc(p.geocodeTier) + '</div>');
+	return '<div class="mw-popup">' + rows.join("") + '</div>';
+}
+
+var map = new maplibregl.Map({ container: "map", style: STYLE, center: [-98, 39], zoom: 3, attributionControl: { compact: true } });
+map.addControl(new maplibregl.NavigationControl({ showCompass: false }), "top-right");
+
+map.on("load", function () {
+	if (BBOX) map.fitBounds(BBOX, { padding: 56, maxZoom: 15, duration: 0 });
+});
+map.on("click", "mw-entities", function (e) {
+	var f = e.features && e.features[0];
+	if (!f) return;
+	new maplibregl.Popup({ closeButton: true }).setLngLat(e.lngLat).setHTML(popupHtml(f.properties || {})).addTo(map);
+});
+map.on("mouseenter", "mw-entities", function () { map.getCanvas().style.cursor = "pointer"; });
+map.on("mouseleave", "mw-entities", function () { map.getCanvas().style.cursor = ""; });
+
+// The house basemap tiles are CORS-restricted to localhost + the docs domain, so a page opened
+// straight off disk (file://) shows the markers on a blank basemap. Make that explicit rather than
+// silent — the entity positions are correct regardless of whether the basemap paints.
+if (location.protocol === "file:") {
+	var warn = document.createElement("div");
+	warn.className = "mw-panel mw-warn";
+	warn.innerHTML = "⚠ Basemap tiles are blocked from <code>file://</code>. Serve this over "
+		+ "<code>http://localhost</code> (e.g. <code>npx serve</code> or <code>python3 -m http.server</code>) "
+		+ "to see the map background — the markers are accurate either way.";
+	document.body.appendChild(warn);
+}
+</script>
+</body>
+</html>
+`;
+}
+//# sourceMappingURL=map-html.js.map

package/out/map-html.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"map-html.js","sourceRoot":"","sources":["../map-html.ts"],"names":[],"mappings":"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"}

package/out/models/dedup-gbt-en-us.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   GENERATED by scripts/record-matcher/train-gbt.ts — DO NOT edit by hand; retrain to update.
+ *
+ *   The default learned-scorer model (#603): a gradient-boosted-tree dedup scorer trained on the
+ *   NPPES NPI-truth set (TX, 3000 NPIs → 707975 candidate pairs). Validated to generalize across
+ *   states by learned-scorer-crossstate-eval.ts. Used by resolveEntities' opt-in learnedScorer hook
+ *   via createGbtScorer. The trained {@link GBT} is plain data.
+ */
+import type { GBT } from "@mailwoman/match";
+/** Provenance for the bundled model — what it was trained on. */
+export declare const DEDUP_GBT_META: {
+    readonly version: "1.0.0";
+    readonly locale: "en-US";
+    readonly trainedOn: "2026-06-15";
+    readonly state: "TX";
+    readonly npis: 3000;
+    readonly records: 8602;
+    readonly pairs: 707975;
+    readonly posRate: 0.0088;
+    readonly hyperparams: {
+        readonly rounds: 120;
+        readonly depth: 3;
+        readonly lr: 0.3;
+        readonly minLeaf: 20;
+    };
+    readonly recommendedThreshold: 2.7143;
+    readonly features: 17;
+    readonly addressFrequencyDistinct: 3317267;
+    readonly addressFrequencyTotal: 9260504;
+};
+export declare const DEDUP_GBT_MODEL: GBT;
+//# sourceMappingURL=dedup-gbt-en-us.d.ts.map

package/out/models/dedup-gbt-en-us.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedup-gbt-en-us.d.ts","sourceRoot":"","sources":["../../models/dedup-gbt-en-us.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAA;AAE3C,iEAAiE;AACjE,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;CAmBjB,CAAA;AAGV,eAAO,MAAM,eAAe,EAAE,GAAo0vD,CAAA"}