@mailwoman/corpus 2.0.0

package/out/src/adapters/usgov-nppes/adapter.js

@@ -0,0 +1,123 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `usgov-nppes`: CMS National Plan and Provider Enumeration System (NPI registry) CSV consumer.
+ *
+ *   NPPES is the authoritative US healthcare provider registry, published monthly by CMS. Each row
+ *   carries a provider's business practice location address together with their legal business name
+ *   or individual name. At ~7M rows it is the single largest venue+address signal source
+ *   available.
+ *
+ *   The adapter consumes the monthly full-replacement CSV (operator pre-downloads via
+ *   `fetch-nppes.sh`). Column names match the canonical NPPES "Full Replacement Monthly NPI File"
+ *   header published at `https://download.cms.gov/nppes/NPI_Files.html`.
+ *
+ *   Output: one row per CSV record where the practice location address is populated. Organization
+ *   rows carry `venue` from the legal business name; individual rows compose `attention` from
+ *   last+first name. Address quad goes on `(house_number, street, locality, region, postcode)`.
+ *
+ *   License: stamped `"Public Domain"` per CMS's federal government distribution terms.
+ */
+import { parse as csvParse } from "csv-parse";
+import { createReadStream } from "node:fs";
+import { stableSourceId } from "../../adapter.js";
+import { lookupStateAbbreviation } from "../../codex/us-fips-state.js";
+import { reconcileComponents } from "../../format.js";
+export const USGOV_NPPES_ADAPTER_ID = "usgov-nppes";
+export const USGOV_NPPES_DEFAULT_LICENSE = "Public Domain";
+const HOUSE_NUMBER_PREFIX = /^(\d+(?:-\d+)?[A-Za-z]?)\s+(.+)$/;
+function splitAddress(address) {
+    const trimmed = address.trim();
+    if (!trimmed)
+        return null;
+    const m = HOUSE_NUMBER_PREFIX.exec(trimmed);
+    if (m)
+        return { house_number: m[1], street: m[2].trim() };
+    return { street: trimmed };
+}
+function composeRaw(venue, house, street, city, state, postcode) {
+    const streetPart = [house, street].filter(Boolean).join(" ").trim();
+    const cityPart = [city.trim(), [state, postcode].filter(Boolean).join(" ").trim()].filter(Boolean).join(", ");
+    return [venue, streetPart, cityPart].filter(Boolean).join(", ");
+}
+export function createUsgovNppesAdapter() {
+    return {
+        id: USGOV_NPPES_ADAPTER_ID,
+        defaultLicense: USGOV_NPPES_DEFAULT_LICENSE,
+        description: "CMS National Plan and Provider Enumeration System — 7M provider practice locations (public-domain). Venue+address co-occurrence at scale.",
+        async *rows(opts) {
+            if (opts.country && opts.country !== "US") {
+                throw new Error(`usgov-nppes adapter: only US supported, got country=${opts.country}`);
+            }
+            const stream = createReadStream(opts.inputPath, { encoding: "utf8" });
+            const parser = stream.pipe(csvParse({
+                columns: true,
+                skip_empty_lines: true,
+                relax_quotes: true,
+                relax_column_count: true,
+            }));
+            let emitted = 0;
+            try {
+                for await (const record of parser) {
+                    if (opts.signal?.aborted)
+                        break;
+                    if (opts.limit !== undefined && emitted >= opts.limit)
+                        break;
+                    const npi = (record.NPI ?? "").trim();
+                    const entityType = (record["Entity Type Code"] ?? "").trim();
+                    const orgName = (record["Provider Organization Name (Legal Business Name)"] ?? "").trim();
+                    const lastName = (record["Provider Last Name (Legal Name)"] ?? "").trim();
+                    const firstName = (record["Provider First Name"] ?? "").trim();
+                    const address1 = (record["Provider First Line Business Practice Location Address"] ?? "").trim();
+                    const address2 = (record["Provider Second Line Business Practice Location Address"] ?? "").trim();
+                    const city = (record["Provider Business Practice Location Address City Name"] ?? "").trim();
+                    const stateRaw = (record["Provider Business Practice Location Address State Name"] ?? "").trim();
+                    const postcode = (record["Provider Business Practice Location Address Postal Code"] ?? "").trim();
+                    if (!city || !postcode)
+                        continue;
+                    const state = lookupStateAbbreviation(stateRaw);
+                    if (!state)
+                        continue;
+                    const fullStreet = [address1, address2].filter(Boolean).join(" ");
+                    const split = splitAddress(fullStreet);
+                    if (!split)
+                        continue;
+                    const venue = orgName || [firstName, lastName].filter(Boolean).join(" ") || undefined;
+                    const components = {
+                        ...(venue ? { venue } : {}),
+                        ...(split.house_number ? { house_number: split.house_number } : {}),
+                        street: split.street,
+                        locality: city,
+                        region: state.abbreviation,
+                        postcode,
+                    };
+                    const raw = composeRaw(venue, split.house_number, split.street, city, state.abbreviation, postcode);
+                    if (!raw)
+                        continue;
+                    const aligned = reconcileComponents(components, raw);
+                    if (Object.keys(aligned).length <= 2)
+                        continue;
+                    const sourceId = npi ? `${USGOV_NPPES_ADAPTER_ID}-${npi}` : stableSourceId(USGOV_NPPES_ADAPTER_ID, aligned);
+                    yield {
+                        raw,
+                        components: aligned,
+                        country: "US",
+                        locale: "en-US",
+                        source: USGOV_NPPES_ADAPTER_ID,
+                        source_id: sourceId,
+                        corpus_version: "",
+                        license: USGOV_NPPES_DEFAULT_LICENSE,
+                    };
+                    emitted++;
+                }
+            }
+            finally {
+                stream.destroy();
+            }
+        },
+    };
+}
+export const usgovNppesAdapter = createUsgovNppesAdapter();
+//# sourceMappingURL=adapter.js.map

package/out/src/adapters/usgov-nppes/adapter.js.map

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

package/out/src/adapters/usgov-samhsa-treatment-locator/adapter.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `usgov-samhsa-treatment-locator`: SAMHSA Behavioral Health Treatment Services Locator CSV
+ *   consumer.
+ *
+ *   SAMHSA's Treatment Locator (`findtreatment.gov`) is the federal directory of substance-use and
+ *   mental-health treatment facilities. The published CSV carries the facility name, an optional
+ *   secondary name (typically the organizational parent), and the postal address quad split into
+ *   primary + secondary street lines. Phase 1.6 §1.2 (#22) selects this source for the same reason
+ *   it selects HRSA: facility names are hand-typed venue strings and the addresses pass through
+ *   enough human + system hands to accumulate the suite-designator + sub-tenant chaos ("Suite C,
+ *   behind main building") that pure gazetteer data does not.
+ *
+ *   SAMHSA's two-line address shape is the key adapter-specific concern. `street1` typically carries
+ *   the canonical postal address (`"123 Main St"`); `street2` carries the suite / unit / "second
+ *   floor" surface form. The adapter joins them with `", "` into a single `street` component (Phase
+ *   1 keeps `unit` as a deferred slot since the OpenCage template doesn't have a clean rendering
+ *   for it). Operators wanting a different join policy can subclass the factory.
+ *
+ *   Column names below match the canonical SAMHSA Behavioral Health Treatment Services Locator CSV
+ *   export header. Operators substituting a closely-related extract should rename columns to match;
+ *   the README has the mapping cheatsheet.
+ *
+ *   License: stamped `"Public Domain"` per the SAMHSA Open Data Foundry's federal-government
+ *   distribution terms.
+ */
+import type { CorpusAdapter } from "../../types.js";
+export declare const USGOV_SAMHSA_ADAPTER_ID = "usgov-samhsa-treatment-locator";
+export declare const USGOV_SAMHSA_DEFAULT_LICENSE = "Public Domain";
+export declare function createUsgovSamhsaTreatmentLocatorAdapter(): CorpusAdapter;
+export declare const usgovSamhsaTreatmentLocatorAdapter: CorpusAdapter;
+//# sourceMappingURL=adapter.d.ts.map

package/out/src/adapters/usgov-samhsa-treatment-locator/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../../src/adapters/usgov-samhsa-treatment-locator/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAOH,OAAO,KAAK,EAAgC,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAEjF,eAAO,MAAM,uBAAuB,mCAAmC,CAAA;AACvE,eAAO,MAAM,4BAA4B,kBAAkB,CAAA;AA2E3D,wBAAgB,wCAAwC,IAAI,aAAa,CA6ExE;AAED,eAAO,MAAM,kCAAkC,eAA6C,CAAA"}

package/out/src/adapters/usgov-samhsa-treatment-locator/adapter.js

@@ -0,0 +1,162 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `usgov-samhsa-treatment-locator`: SAMHSA Behavioral Health Treatment Services Locator CSV
+ *   consumer.
+ *
+ *   SAMHSA's Treatment Locator (`findtreatment.gov`) is the federal directory of substance-use and
+ *   mental-health treatment facilities. The published CSV carries the facility name, an optional
+ *   secondary name (typically the organizational parent), and the postal address quad split into
+ *   primary + secondary street lines. Phase 1.6 §1.2 (#22) selects this source for the same reason
+ *   it selects HRSA: facility names are hand-typed venue strings and the addresses pass through
+ *   enough human + system hands to accumulate the suite-designator + sub-tenant chaos ("Suite C,
+ *   behind main building") that pure gazetteer data does not.
+ *
+ *   SAMHSA's two-line address shape is the key adapter-specific concern. `street1` typically carries
+ *   the canonical postal address (`"123 Main St"`); `street2` carries the suite / unit / "second
+ *   floor" surface form. The adapter joins them with `", "` into a single `street` component (Phase
+ *   1 keeps `unit` as a deferred slot since the OpenCage template doesn't have a clean rendering
+ *   for it). Operators wanting a different join policy can subclass the factory.
+ *
+ *   Column names below match the canonical SAMHSA Behavioral Health Treatment Services Locator CSV
+ *   export header. Operators substituting a closely-related extract should rename columns to match;
+ *   the README has the mapping cheatsheet.
+ *
+ *   License: stamped `"Public Domain"` per the SAMHSA Open Data Foundry's federal-government
+ *   distribution terms.
+ */
+import { parse as csvParse } from "csv-parse";
+import { createReadStream } from "node:fs";
+import { stableSourceId } from "../../adapter.js";
+import { lookupStateAbbreviation } from "../../codex/us-fips-state.js";
+import { reconcileComponents } from "../../format.js";
+export const USGOV_SAMHSA_ADAPTER_ID = "usgov-samhsa-treatment-locator";
+export const USGOV_SAMHSA_DEFAULT_LICENSE = "Public Domain";
+const HOUSE_NUMBER_PREFIX = /^(\d+(?:-\d+)?[A-Za-z]?)\s+(.+)$/;
+function splitAddress(address) {
+    const trimmed = address.trim();
+    if (!trimmed)
+        return null;
+    const m = HOUSE_NUMBER_PREFIX.exec(trimmed);
+    if (m)
+        return { house_number: m[1], street: m[2].trim() };
+    return { street: trimmed };
+}
+/**
+ * Join the SAMHSA two-line street: primary street + optional secondary line (suite / unit / floor /
+ * "behind main building") on `", "`. The combined value is the `street` component surface form.
+ * Phase 1 does not break this out into the `unit` component — see the file-level comment.
+ */
+function joinTwoLineStreet(street1, street2) {
+    const s1 = street1.trim();
+    const s2 = (street2 ?? "").trim();
+    if (!s1 && !s2)
+        return "";
+    if (!s2)
+        return s1;
+    if (!s1)
+        return s2;
+    return `${s1}, ${s2}`;
+}
+/**
+ * Combine `name1` + optional `name2` into a single venue surface form. SAMHSA conventions:
+ *
+ * - `name1` is the program / clinic name ("Mountain Plains Counseling Services").
+ * - `name2` is the parent organization ("Catholic Charities of Wyoming"), if any.
+ *
+ * Both render together as `"<name1> - <name2>"` when both are present — geocoder users typically
+ * type either form, so the model benefits from the joined surface.
+ */
+function composeVenue(name1, name2) {
+    const n1 = name1.trim();
+    const n2 = (name2 ?? "").trim();
+    if (!n1 && !n2)
+        return "";
+    if (!n2)
+        return n1;
+    if (!n1)
+        return n2;
+    return `${n1} - ${n2}`;
+}
+/** Same envelope-style format as HRSA: venue prefix, street body, city/state/zip suffix. */
+function composeRaw(venue, house, street, city, state, postcode) {
+    const streetPart = [house, street].filter(Boolean).join(" ").trim();
+    const cityPart = [city.trim(), [state, postcode].filter(Boolean).join(" ").trim()].filter(Boolean).join(", ");
+    return [venue.trim(), streetPart, cityPart].filter(Boolean).join(", ");
+}
+export function createUsgovSamhsaTreatmentLocatorAdapter() {
+    return {
+        id: USGOV_SAMHSA_ADAPTER_ID,
+        defaultLicense: USGOV_SAMHSA_DEFAULT_LICENSE,
+        description: "SAMHSA Behavioral Health Treatment Services Locator (public-domain). Adversarial source: venue + two-line address co-occurrence, hand-entered.",
+        async *rows(opts) {
+            if (opts.country && opts.country !== "US") {
+                throw new Error(`usgov-samhsa adapter: only US supported, got country=${opts.country}`);
+            }
+            const stream = createReadStream(opts.inputPath, { encoding: "utf8" });
+            const parser = stream.pipe(csvParse({
+                columns: true,
+                skip_empty_lines: true,
+                relax_quotes: true,
+                relax_column_count: true,
+            }));
+            let emitted = 0;
+            try {
+                for await (const record of parser) {
+                    if (opts.signal?.aborted)
+                        break;
+                    if (opts.limit !== undefined && emitted >= opts.limit)
+                        break;
+                    const venue = composeVenue(record.name1 ?? "", record.name2);
+                    const street = joinTwoLineStreet(record.street1 ?? "", record.street2);
+                    const split = splitAddress(street);
+                    const city = (record.city ?? "").trim();
+                    const stateAbbr = (record.state ?? "").trim();
+                    const postcode = (record.zip ?? "").trim();
+                    if (!venue || !split || !city || !postcode)
+                        continue;
+                    const state = lookupStateAbbreviation(stateAbbr);
+                    if (!state)
+                        continue;
+                    // venue first — same kryptonite-defending insertion order as HRSA.
+                    const components = {
+                        venue,
+                        ...(split.house_number ? { house_number: split.house_number } : {}),
+                        street: split.street,
+                        locality: city,
+                        region: state.abbreviation,
+                        postcode,
+                    };
+                    const raw = composeRaw(venue, split.house_number, split.street, city, state.abbreviation, postcode);
+                    if (!raw)
+                        continue;
+                    const aligned = reconcileComponents(components, raw);
+                    if (Object.keys(aligned).length === 0)
+                        continue;
+                    const frId = (record.frid ?? "").trim();
+                    const sourceId = frId
+                        ? `${USGOV_SAMHSA_ADAPTER_ID}-${frId}`
+                        : stableSourceId(USGOV_SAMHSA_ADAPTER_ID, aligned);
+                    yield {
+                        raw,
+                        components: aligned,
+                        country: "US",
+                        locale: "en-US",
+                        source: USGOV_SAMHSA_ADAPTER_ID,
+                        source_id: sourceId,
+                        corpus_version: "",
+                        license: USGOV_SAMHSA_DEFAULT_LICENSE,
+                    };
+                    emitted++;
+                }
+            }
+            finally {
+                stream.destroy();
+            }
+        },
+    };
+}
+export const usgovSamhsaTreatmentLocatorAdapter = createUsgovSamhsaTreatmentLocatorAdapter();
+//# sourceMappingURL=adapter.js.map

package/out/src/adapters/usgov-samhsa-treatment-locator/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../../../src/adapters/usgov-samhsa-treatment-locator/adapter.ts"],"names":[],"mappings":"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"}

package/out/src/adapters/wof-admin-json/adapter.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `wof-admin`: Who's On First admin GeoJSON-bundle adapter.
+ *
+ *   **Phase 1.5.1 pivot.** The original Phase 1.5 SQLite adapter (formerly at
+ *   `packages/corpus/src/adapters/wof-admin/`, removed in this same change) was replaced by this
+ *   one because the SQLite distribution path was unworkable for the real corpus build:
+ *
+ *   1. `dist.whosonfirst.org/sqlite/` is dead (NXDOMAIN); the Geocode-Earth mirror is the only one.
+ *   2. The Geocode-Earth-hosted postalcode DB tags every row `mz:is_current = -1` ("unknown but treated
+ *        as active"); the SQLite adapter's `is_current = 1` predicate emitted zero rows.
+ *   3. The `names` table in the SQLite distribution is empty — localized `name:*` variants live in a
+ *        separate distribution. The St. Petersburg / Mt. Vernon / Ft. Lauderdale alternation cases
+ *        (the original Phase 1.5.1 motivator) cannot be solved on the SQLite path even with a
+ *        patched `is_current` predicate.
+ *
+ *   Input: a directory containing one or more cloned `whosonfirst-data-admin-<cc>` GitHub repos. Each
+ *   repo has `data/XXX/YYY/ZZZ/<wof-id>.geojson` files; `**\/*.geojson` walks the tree recursively.
+ *   Alternate-geometry siblings (`-alt-*`) are skipped — they're separate exports of the same
+ *   record, not new records.
+ *
+ *   Per record, the adapter emits one row per `(name-variant, hierarchy-variant)` pair:
+ *
+ *   - **Name variants**: the canonical `wof:name` (slot key `default`) plus every `name:*` localized
+ *       variant present on the feature (`name:eng_x_preferred`, `name:eng_x_colloquial`,
+ *       `name:rus_x_preferred`, ...). This is the Phase 1.5.1 fix for the St. Petersburg case:
+ *       `"Saint Petersburg"` (canonical) and `"St. Petersburg"` (eng_x_colloquial) both become
+ *       training rows for the same WOF id.
+ *   - **Hierarchy variants** (unchanged from the SQLite adapter): locality → 3 variants, region → 2,
+ *       country → 1, county → 1.
+ *
+ *   `source_id` is `wof-admin-<wof_id>-<name-slot>-<hierarchy-variant>`. The previous SQLite adapter
+ *   used `wof-admin-<wof_id>-<hierarchy-variant>` (no name slot); the new format adds a name-slot
+ *   segment so the colloquial / preferred / per-locale variants survive dedup independently.
+ *
+ *   License: CC0. The adapter stamps every row with `CC0-1.0`.
+ */
+import type { ComponentTag } from "@mailwoman/core/types";
+import type { CorpusAdapter } from "../../types.js";
+import { type WofRecord } from "../../wof-json.js";
+interface VariantSpec {
+    /** Hierarchy-variant id appended to `source_id`. */
+    suffix: string;
+    /** Component tag → display string the adapter will hand to the runner. */
+    components: Partial<Record<ComponentTag, string>>;
+}
+/**
+ * Compute the hierarchy variants for a record given its ancestry chain and the chosen `selfName`.
+ *
+ * `selfName` is the surface form to use for the record's own component (locality / region / country
+ * / subregion). Callers pass the canonical `wof:name` for the `"default"` slot and a `name:*`
+ * localized value for variant slots; ancestor names always come from the ancestor's canonical
+ * `wof:name`.
+ *
+ * Country variants substitute `COUNTRY_DISPLAY_NAME` for the default slot so the OpenCage template
+ * produces the canonicalized form (`"United States of America"`), matching the legacy SQLite
+ * adapter's behavior.
+ */
+export declare function variantsFor(row: WofRecord, ancestry: WofRecord[], selfName: string): VariantSpec[];
+/**
+ * Build the per-record name-slot list. The canonical `"default"` slot uses the OpenCage-canonical
+ * country form when the record is itself a country (matches SQLite-adapter behavior); every other
+ * placetype's default slot uses `wof:name` verbatim.
+ *
+ * Subsequent slots come from `name:*` variants, deduplicated against the default name so we don't
+ * emit a redundant `"default"`-equivalent row under a localized key.
+ */
+export declare function nameSlotsFor(rec: WofRecord): Array<{
+    key: string;
+    value: string;
+}>;
+export declare const WOF_ADMIN_ADAPTER_ID = "wof-admin";
+/**
+ * Construct the wof-admin JSON-bundle adapter. The adapter is stateless across runs; calling this
+ * twice with the same input directory produces byte-identical `canonical.jsonl` (records are
+ * emitted in sorted `wof:id` order to be insensitive to filesystem walk ordering).
+ */
+export declare function createWofAdminAdapter(): CorpusAdapter;
+/** Single shared instance, suitable for `defaultAdapterRegistry`. */
+export declare const wofAdminAdapter: CorpusAdapter;
+export {};
+//# sourceMappingURL=adapter.d.ts.map

package/out/src/adapters/wof-admin-json/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../../src/adapters/wof-admin-json/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAEzD,OAAO,KAAK,EAAgC,aAAa,EAAE,MAAM,gBAAgB,CAAA;AACjF,OAAO,EAAsD,KAAK,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAiDtG,UAAU,WAAW;IACpB,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAA;IAEd,0EAA0E;IAC1E,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAA;CACjD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,WAAW,EAAE,CA0DlG;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,SAAS,GAAG,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAclF;AAED,eAAO,MAAM,oBAAoB,cAAc,CAAA;AAE/C;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,aAAa,CA2DrD;AAED,qEAAqE;AACrE,eAAO,MAAM,eAAe,eAA0B,CAAA"}