@mailwoman/neural-weights-de-de 8.5.0

package/README.md

@@ -0,0 +1,23 @@
+# @mailwoman/neural-weights-de-de
+
+German (`de-DE`) weights overlay for [mailwoman](https://mailwoman.sister.software).
+
+**Data-only.** This package ships no model of its own — it declares
+`mailwoman.baseWeights: "@mailwoman/neural-weights-en-us"` and shares that package's `model.onnx`
+and `tokenizer.model`. What it adds is the German **placetype-pair index**: 85,605
+`(Ortsteil, Gemeinde)` pairs from Who's On First, applied as a soft decode-time prior so
+`Neusser Str. 12, Nippes, 50733 Köln` resolves `Nippes` as a dependent locality instead of losing it.
+
+## Why an overlay exists at all
+
+The pair index is hard-gated on the resolved locale's country, so a German artifact shipped inside
+another locale's package could never fire. A carrier package is the only way the prior reaches
+German input — which is what blocked this locale until now, rather than any shortage of data.
+
+## Install
+
+```sh
+npm install @mailwoman/neural-weights-de-de
+```
+
+Then resolve weights for `de-DE`; `@mailwoman/neural` picks up the sibling index automatically.

package/model-card.json

@@ -0,0 +1,43 @@
+{
+	"name": "@mailwoman/neural-weights-de-de",
+	"version": "7.0.0",
+	"locale": "de-DE",
+	"license": "AGPL-3.0",
+	"$comment": "Data-only overlay. Shares model.onnx + tokenizer.model with @mailwoman/neural-weights-en-us via mailwoman.baseWeights \u2014 this package ships ONLY the DE placetype-pair index.",
+	"de_artifacts": {
+		"$comment": "Hierarchy campaign R9 (2026-08-02). The German instance of the dependent-locality prior.",
+		"pair_index_de_bin": {
+			"format": "PIX1 placetype-pair index \u2014 a retrieval-augmented (Ortsteil, Gemeinde) dependent_locality prior, e.g. (\"Nippes\", \"K\u00f6ln\")",
+			"source": "Who's On First admin hierarchy ($MAILWOMAN_DATA_ROOT/wof/admin-global-priority.db). Children: borough + neighbourhood (WOF's typing for Ortsteile/Stadtteile). Parents: locality, localadmin, borough. No postal register: Deutsche Post routes 'PLZ Stadt' and carries no Ortsteil field, so WOF is the source \u2014 the same call the US instance made and the opposite of France's, where BAN's lieu-dit field IS the postal line.",
+			"pairs": 85605,
+			"bytes": 2160665,
+			"delta_calibration": "\u03b4=10, transitionBeta=5 \u2014 inherited from the GB calibration per R5's finding that the classifier's dependent_locality deficit is uniform across locales.",
+			"country_gate": "hard-gated on the header's country (de).",
+			"requires_leading_postcode_strip": "This artifact is INERT without the `de` entries in SEGMENT_PARENT_POSTCODE_SHAPES and LEADING_POSTCODE_COUNTRIES (neural/placetype-pair-prior.ts). German addresses write '50733 K\u00f6ln', so a parent segment folds to a key no bare-Gemeinde entry matches \u2014 measured: the index alone changed nothing until both entries landed. Same dependency FR's artifact carries.",
+			"not_committed": "derived artifact, .gitignore'd \u2014 rebuilt via `mailwoman gazetteer pair-index --out neural-weights-de-de --country de --delta 10 --transition-beta 5 --pairs-jsonl <de-pairs.jsonl>`"
+		}
+	},
+	"eval": {
+		"r9_de_ortsteil": {
+			"venue_confound_board": {
+				"n": 70,
+				"false_positives": 0,
+				"fp_pct": 0.0,
+				"bar_pct": 2.0,
+				"note": "45 directional-class surfaces (Nord/S\u00fcd/Ober/Neu\u2026, from 9,406 available) + 25 others, each opening a German venue name"
+			},
+			"positive_board": {
+				"n": 60,
+				"emit": 60,
+				"tag_correct": 60,
+				"tag_correct_pct": 100.0,
+				"bar_pct": 70.0
+			},
+			"fusion_fix": "Without the index 'Venloer Str. 300, Ehrenfeld, 50823 K\u00f6ln' fused the locality as 'Ehrenfeld K\u00f6ln'; with it the two split correctly."
+		}
+	},
+	"files": {
+		"model_card": "model-card.json",
+		"pair_index": "pair-index-de.bin"
+	}
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@mailwoman/neural-weights-de-de",
+  "version": "8.5.0",
+  "description": "German (de-DE) weights overlay for mailwoman — data-only; shares the base model with @mailwoman/neural-weights-en-us and ships the DE placetype-pair index.",
+  "license": "AGPL-3.0-only OR LicenseRef-Commercial",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sister-software/mailwoman.git",
+    "directory": "neural-weights-en-nz"
+  },
+  "files": [
+    "model-card.json",
+    "pair-index-de.bin",
+    "README.md",
+    "*.ts",
+    "**/*.ts",
+    "!*.test.ts",
+    "!**/*.test.ts"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@mailwoman/neural-weights-en-us": "8.5.0"
+  },
+  "mailwoman": {
+    "baseWeights": "@mailwoman/neural-weights-en-us"
+  }
+}

package/scripts/link-dev-weights.ts

@@ -0,0 +1,117 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Dev-weights linker for `@mailwoman/neural-weights-de-de` (hierarchy campaign R9).
+ *
+ *   This overlay ships exactly ONE artifact — `pair-index-de.bin` — because it declares
+ *   `mailwoman.baseWeights` and shares the base model/tokenizer with the en-us package. There is
+ *   nothing to symlink; the only job is building the index so `resolveWeights({locale: "de-de"})`
+ *   surfaces `pairIndexPath` in local dev.
+ *
+ *   The index is INERT without the `de` entries in `SEGMENT_PARENT_POSTCODE_SHAPES` and
+ *   `LEADING_POSTCODE_COUNTRIES` (`neural/placetype-pair-prior.ts`): German addresses write
+ *   "50733 Köln", so a parent segment folds to a key no bare-Gemeinde entry matches. Measured
+ *   during R9 — the artifact alone changed nothing until both landed.
+ */
+
+import { spawnSync } from "node:child_process"
+import { existsSync, readFileSync } from "node:fs"
+import { resolve } from "node:path"
+
+import { repoRootPath } from "@mailwoman/core/utils"
+
+const PKG_DIR = String(repoRootPath("neural-weights-de-de"))
+const CLI = String(repoRootPath("mailwoman", "out", "cli.js"))
+const PAIR_INDEX_BIN_DEST = resolve(PKG_DIR, "pair-index-de.bin")
+/**
+ * Checked-in WOF-derived (Ortsteil, Gemeinde) pairs — the same posture as the GB secondary sources.
+ */
+const DE_PAIRS_JSONL = String(repoRootPath("data", "gazetteer", "de-pairs-v1.jsonl"))
+/**
+ * Calibrated magnitudes — the pair the R9 bars were measured at (0/70 confound FPs, 60/60 tag-correct).
+ */
+const PAIR_INDEX_DELTA = 10
+const PAIR_INDEX_TRANSITION_BETA = 5
+
+/**
+ * Minimal PIX1 header reader — magic + header only, reimplemented so this data-only package gains no dependency on
+ * `@mailwoman/neural` (which pulls onnxruntime-node) to read two fields.
+ */
+function peekPairIndexHeaderFields(path: string): { delta: number; transitionBeta: number | undefined } {
+	const bytes = readFileSync(path)
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+	// "PIX1" little-endian.
+	const MAGIC = 0x31_58_49_50
+
+	if (view.getUint32(0, true) !== MAGIC) {
+		throw new Error(`pair index: bad magic reading ${path}`)
+	}
+
+	const headerLen = view.getUint32(4, true)
+	const header = JSON.parse(Buffer.from(bytes.subarray(8, 8 + headerLen)).toString("utf8")) as {
+		delta: number
+		transitionBeta?: number
+	}
+
+	return { delta: header.delta, transitionBeta: header.transitionBeta }
+}
+
+if (!existsSync(CLI)) {
+	console.error(`WARNING: ${CLI} not built — run \`yarn compile\` first, then re-run for pair-index-de.bin.`)
+} else if (!existsSync(DE_PAIRS_JSONL)) {
+	console.error(`WARNING: missing ${DE_PAIRS_JSONL} — pair-index-de.bin not built.`)
+} else {
+	let needsRebuild = true
+
+	if (existsSync(PAIR_INDEX_BIN_DEST)) {
+		try {
+			const header = peekPairIndexHeaderFields(PAIR_INDEX_BIN_DEST)
+
+			if (header.delta !== PAIR_INDEX_DELTA) {
+				console.log(`rebuilding pair-index-de.bin — delta ${header.delta} → ${PAIR_INDEX_DELTA}`)
+			} else if (header.transitionBeta !== PAIR_INDEX_TRANSITION_BETA) {
+				console.log(
+					`rebuilding pair-index-de.bin — transitionBeta ${header.transitionBeta} → ${PAIR_INDEX_TRANSITION_BETA}`
+				)
+			} else {
+				needsRebuild = false
+			}
+		} catch (error) {
+			console.log(`rebuilding pair-index-de.bin — header unreadable (${(error as Error).message})`)
+		}
+	}
+
+	if (!needsRebuild) {
+		console.log(`skipped pair-index-de.bin build — ${PAIR_INDEX_BIN_DEST} is current`)
+	} else {
+		const result = spawnSync(
+			process.execPath,
+			[
+				CLI,
+				"gazetteer",
+				"pair-index",
+				"--out",
+				PKG_DIR,
+				"--country",
+				"de",
+				"--delta",
+				String(PAIR_INDEX_DELTA),
+				"--transition-beta",
+				String(PAIR_INDEX_TRANSITION_BETA),
+				"--pairs-jsonl",
+				DE_PAIRS_JSONL,
+			],
+			{ stdio: "inherit" }
+		)
+
+		if (result.status !== 0 || !existsSync(PAIR_INDEX_BIN_DEST)) {
+			console.error(`FAILED: gazetteer pair-index --country de (exit ${result.status})`)
+
+			process.exit(1)
+		}
+
+		console.log(`built pair-index-de.bin ← ${DE_PAIRS_JSONL}`)
+	}
+}