@mailwoman/neural 2.1.0 → 4.0.0

package/out/unit-repair.js

@@ -0,0 +1,147 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Secondary-unit regex repair pass — parser-improvement backlog (2026-05-30).
+ *
+ *   The three-arena capability eval surfaced a persistent neural weakness: the
+ *   model DROPS secondary units. "123 Main St Apt 456" → no unit label; the
+ *   postal-standards secondary-unit edge class scored 0% neural. Units have a
+ *   rigid surface shape (a designator keyword + an identifier), so — exactly
+ *   like the postcode-repair pass (#35) — we can detect them deterministically
+ *   and repair the BIO labels AFTER decode but BEFORE `buildAddressTree`. The
+ *   model is untouched; this is a decoder-side correction, the same "lowest
+ *   risk" lever family as postcode-repair.
+ *
+ *   PRECISION GUARDS (mirror postcode-repair — never regress a confident parse):
+ *     - We only fire on EXPLICIT designators (Apt, Ste, Suite, Unit, Rm, Floor,
+ *       Bldg, Flat, … + bare "#<n>"). Ambiguous tokens are deliberately excluded:
+ *       "Box" (that's po_box), bare "F"/"No" (too greedy), "Space"/"Stop" (common
+ *       words).
+ *     - ADD path (model emitted no unit over the matched run): allowed ONLY over
+ *       `O` tokens — never over house_number / street* / postcode / po_box / a
+ *       geographic container. So a confidently-labeled street or number is safe.
+ *     - SNAP path: when the model already started a unit span inside the match,
+ *       we expand/clip it to the full detected shape.
+ *     - Local smear-clip: unit tokens immediately flanking a snapped run are
+ *       cleared (mirrors postcode-repair) so "Apt 4 Springfield" can't leave a
+ *       stray I-unit on "Springfield".
+ *
+ *   Opt-in via `ParseOpts.unitRepair` (postcode-repair earned default-on only
+ *   after a measured +135/0; unit-repair stays opt-in until the v0.7.2 arena
+ *   re-run quantifies its delta).
+ */
+/**
+ * Secondary-unit shape patterns, ordered most-specific → least. Case-insensitive
+ * (unit designators appear in every casing in real data). The identifier is a
+ * 1-5 digit number with an optional trailing letter ("4B"), a single letter
+ * ("STE D"), or a letter+digits — kept tight so we don't swallow following words.
+ */
+const UNIT_DESIGNATORS = "APARTMENT|APT|SUITE|STE|UNIT|ROOM|RM|FLOOR|FLR|FL|BUILDING|BLDG|DEPARTMENT|DEPT|LOT|TRAILER|TRLR|SLIP|HANGAR|PIER|FLAT|PH|PENTHOUSE";
+const UNIT_PATTERNS = [
+    // Designator + optional "#"/"No." + identifier, e.g. "Apt 4B", "Ste 12", "STE D",
+    // "Unit 9400", "Suite 100", "Rm 5", "Flat 2", "Apartment #3", "Bldg C".
+    // The `\b` after the designator is load-bearing: it stops "Unit" matching inside
+    // "United", "Fl" inside "Florida", etc. The trailing `\b` on the identifier stops
+    // "Apt Main" capturing the "M" of "Main" (single-letter ident only fires on a
+    // standalone token like "STE D").
+    {
+        label: "designator",
+        re: new RegExp(`\\b(?:${UNIT_DESIGNATORS})\\b\\.?\\s*#?\\s*(?:No\\.?\\s*)?(?:\\d{1,5}[A-Za-z]?|[A-Za-z]\\d{0,4})\\b`, "gi"),
+    },
+    // Bare hash + identifier, e.g. "#104", "# 4B". Common US secondary-unit form.
+    { label: "hash", re: /#\s*\d{1,5}[A-Za-z]?\b/g },
+];
+const UNIT_B = "B-unit";
+const UNIT_I = "I-unit";
+const OUTSIDE = "O";
+/**
+ * Tags a unit span is allowed to overwrite on the ADD path. The v0.7.2 arena
+ * showed the dominant failure for bare designator-led units ("Flat 2  14 Smith
+ * St", "APT 2 …") is the model labeling the WHOLE designator+identifier run as
+ * `locality` — not leaving it `O`. An explicit designator + identifier is a
+ * high-confidence "this is a unit" shape (a real locality/suburb name never has
+ * that form), so — exactly like postcode-repair's ADD_OVER_TAGS — we let it
+ * reclaim a `locality`/`dependent_locality` span. Structural tags
+ * (house_number, street*, postcode, po_box, region, country, venue) stay off the
+ * list so a confident parse is never clobbered. (`O` is always eligible.)
+ */
+const ADD_OVER_TAGS = new Set(["locality", "dependent_locality"]);
+function isUnitLabel(label) {
+    return label === "B-unit" || label === "I-unit";
+}
+/** Extract the bare tag from a BIO label ("B-locality" → "locality", "O" → null). */
+function tagOf(label) {
+    return label === "O" ? null : label.slice(2);
+}
+/** Collect non-overlapping unit matches, preferring more-specific (earlier) patterns + longest. */
+function collectMatches(text) {
+    const candidates = [];
+    UNIT_PATTERNS.forEach((pat, priority) => {
+        pat.re.lastIndex = 0;
+        for (let m = pat.re.exec(text); m; m = pat.re.exec(text)) {
+            candidates.push({ start: m.index, end: m.index + m[0].length, priority });
+        }
+    });
+    // Longest-match-wins, then most-specific; reject anything overlapping an accepted match.
+    candidates.sort((a, b) => b.end - b.start - (a.end - a.start) || a.priority - b.priority);
+    const accepted = [];
+    for (const c of candidates) {
+        if (accepted.some((a) => c.start < a.end && a.start < c.end))
+            continue;
+        accepted.push(c);
+    }
+    return accepted;
+}
+/**
+ * Repair secondary-unit label spans in a decoded token sequence using designator
+ * regexes. Returns a NEW token array (inputs are not mutated) plus a change count.
+ */
+export function repairUnitLabels(text, input) {
+    const matches = collectMatches(text);
+    const tokens = input.map((t) => ({ ...t }));
+    if (matches.length === 0)
+        return { tokens, changed: 0 };
+    let changed = 0;
+    const setLabel = (i, label) => {
+        if (tokens[i].label !== label) {
+            tokens[i].label = label;
+            changed++;
+        }
+    };
+    for (const m of matches) {
+        // Tokens whose char span intersects the match.
+        const overlap = [];
+        for (let i = 0; i < tokens.length; i++) {
+            const t = tokens[i];
+            if (t.start < m.end && m.start < t.end)
+                overlap.push(i);
+        }
+        if (overlap.length === 0)
+            continue;
+        const hasUnit = overlap.some((i) => isUnitLabel(tokens[i].label));
+        if (!hasUnit) {
+            // ADD path — explicit designators are high-confidence, but only ever over O or a
+            // geographic-container tag (locality/dependent_locality — the tags the model
+            // mislabels bare units as). Never clobber a confident house_number/street/postcode/
+            // po_box/region/country/venue.
+            const safe = overlap.every((i) => {
+                const tag = tagOf(tokens[i].label);
+                return tag === null || ADD_OVER_TAGS.has(tag);
+            });
+            if (!safe)
+                continue;
+        }
+        // SNAP/ADD: relabel the matched run as a single unit span.
+        overlap.forEach((i, k) => setLabel(i, k === 0 ? UNIT_B : UNIT_I));
+        // Local smear clip: clear unit tokens immediately flanking the snapped run.
+        for (let j = overlap[0] - 1; j >= 0 && isUnitLabel(tokens[j].label); j--)
+            setLabel(j, OUTSIDE);
+        for (let j = overlap[overlap.length - 1] + 1; j < tokens.length && isUnitLabel(tokens[j].label); j++) {
+            setLabel(j, OUTSIDE);
+        }
+    }
+    return { tokens, changed };
+}
+//# sourceMappingURL=unit-repair.js.map

package/out/unit-repair.js.map

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

package/out/viterbi.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Linear-chain CRF Viterbi decoder in TypeScript.
+ *
+ *   Replaces per-token argmax in the classifier when transition scores are available. Mirrors the
+ *   Python training-time / eval-time path so JS runtime decode agrees with the model card's
+ *   metrics.
+ *
+ *   Two transition matrix modes:
+ *
+ *   1. **Structural-only** (no weights changes required) — build from the BIO label vocabulary using
+ *        `buildBioTransitionMask()`. Forbids `O → I-X`, `B-X → I-Y` (X ≠ Y), and sequence-start →
+ *        `I-X`. Permits everything else. This alone prevents orphan-I decoding ("Saint Petersburg →
+ *        Petersburg" bug) at runtime — a strict improvement over argmax.
+ *   2. **Learned** (requires a future weights release that ships `crf-transitions.json`) — load the
+ *        trained transition matrix from the model card. Adds learned soft priors on top of the
+ *        structural mask. Currently not exported from the training-side ONNX bundle.
+ */
+/**
+ * Build the BIO structural transition mask given the label vocabulary in order.
+ *
+ * Rules:
+ *
+ * - `X → O` always permitted (0)
+ * - `X → B-Y` always permitted (0)
+ * - `X → I-Y` permitted only if `X` is `B-Y` or `I-Y` (0); otherwise -inf
+ *
+ * Returns a `numLabels × numLabels` matrix where `mask[from][to]` is the additive log-score (0 for
+ * permitted, NEG_INF for forbidden).
+ */
+export declare function buildBioTransitionMask(labels: readonly string[]): number[][];
+/** Returns the per-label vector of valid start-of-sequence transitions (0 or -inf). */
+export declare function buildBioStartMask(labels: readonly string[]): number[];
+/**
+ * End-of-sequence transitions. By default all labels are valid endings (returns zeros). Override if
+ * the trained model has learned end transitions.
+ */
+export declare function buildBioEndMask(labels: readonly string[]): number[];
+export interface ViterbiInput {
+    /** `emissions[t][k]` — log-emission for label k at timestep t. Pass raw logits or log-softmaxes. */
+    emissions: number[][];
+    /** `transitions[from][to]` — additive log-score. Use `buildBioTransitionMask` if unsure. */
+    transitions: number[][];
+    /** Per-label log-score for being the FIRST label. */
+    startTransitions?: number[];
+    /** Per-label log-score for being the LAST label. */
+    endTransitions?: number[];
+}
+export interface ViterbiResult {
+    /** Best label index per timestep. */
+    path: number[];
+    /** Total path score (log-prob). */
+    score: number;
+}
+/**
+ * Viterbi decode: find the highest-scoring label sequence under the CRF.
+ *
+ * Time: O(seq_len × num_labels²). Space: O(seq_len × num_labels) for the backpointer table.
+ */
+export declare function viterbi(input: ViterbiInput): ViterbiResult;
+/**
+ * Convenience: argmax over per-token softmax (existing behavior). Provided so callers can opt in to
+ * Viterbi only when transitions are available, falling back to this cleanly.
+ */
+export declare function perTokenArgmax(emissions: readonly number[][]): number[];
+/**
+ * Softmax of a logit row (returns probabilities summing to 1).
+ *
+ * Used to compute per-token confidence after Viterbi picks the label sequence — the confidence is
+ * the softmax probability of the Viterbi-chosen label at that timestep.
+ */
+export declare function softmax(row: readonly number[]): number[];
+//# sourceMappingURL=viterbi.d.ts.map

package/out/viterbi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"viterbi.d.ts","sourceRoot":"","sources":["../viterbi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,EAAE,CAa5E;AAED,uFAAuF;AACvF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAErE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAEnE;AAYD,MAAM,WAAW,YAAY;IAC5B,oGAAoG;IACpG,SAAS,EAAE,MAAM,EAAE,EAAE,CAAA;IACrB,4FAA4F;IAC5F,WAAW,EAAE,MAAM,EAAE,EAAE,CAAA;IACvB,qDAAqD;IACrD,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC3B,oDAAoD;IACpD,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;CACzB;AAED,MAAM,WAAW,aAAa;IAC7B,qCAAqC;IACrC,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAA;CACb;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,aAAa,CA4D1D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE,CAYvE;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAMxD"}

package/out/viterbi.js

@@ -0,0 +1,163 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Linear-chain CRF Viterbi decoder in TypeScript.
+ *
+ *   Replaces per-token argmax in the classifier when transition scores are available. Mirrors the
+ *   Python training-time / eval-time path so JS runtime decode agrees with the model card's
+ *   metrics.
+ *
+ *   Two transition matrix modes:
+ *
+ *   1. **Structural-only** (no weights changes required) — build from the BIO label vocabulary using
+ *        `buildBioTransitionMask()`. Forbids `O → I-X`, `B-X → I-Y` (X ≠ Y), and sequence-start →
+ *        `I-X`. Permits everything else. This alone prevents orphan-I decoding ("Saint Petersburg →
+ *        Petersburg" bug) at runtime — a strict improvement over argmax.
+ *   2. **Learned** (requires a future weights release that ships `crf-transitions.json`) — load the
+ *        trained transition matrix from the model card. Adds learned soft priors on top of the
+ *        structural mask. Currently not exported from the training-side ONNX bundle.
+ */
+const NEG_INF = -1e9;
+/**
+ * Build the BIO structural transition mask given the label vocabulary in order.
+ *
+ * Rules:
+ *
+ * - `X → O` always permitted (0)
+ * - `X → B-Y` always permitted (0)
+ * - `X → I-Y` permitted only if `X` is `B-Y` or `I-Y` (0); otherwise -inf
+ *
+ * Returns a `numLabels × numLabels` matrix where `mask[from][to]` is the additive log-score (0 for
+ * permitted, NEG_INF for forbidden).
+ */
+export function buildBioTransitionMask(labels) {
+    const n = labels.length;
+    const mask = [];
+    for (let from = 0; from < n; from++) {
+        const row = new Array(n);
+        const fromLabel = labels[from];
+        for (let to = 0; to < n; to++) {
+            const toLabel = labels[to];
+            row[to] = isValidTransition(fromLabel, toLabel) ? 0 : NEG_INF;
+        }
+        mask.push(row);
+    }
+    return mask;
+}
+/** Returns the per-label vector of valid start-of-sequence transitions (0 or -inf). */
+export function buildBioStartMask(labels) {
+    return labels.map((l) => (l.startsWith("I-") ? NEG_INF : 0));
+}
+/**
+ * End-of-sequence transitions. By default all labels are valid endings (returns zeros). Override if
+ * the trained model has learned end transitions.
+ */
+export function buildBioEndMask(labels) {
+    return labels.map(() => 0);
+}
+function isValidTransition(from, to) {
+    if (to === "O")
+        return true;
+    if (to.startsWith("B-"))
+        return true;
+    if (to.startsWith("I-")) {
+        const tag = to.slice(2);
+        return from === `B-${tag}` || from === `I-${tag}`;
+    }
+    return true;
+}
+/**
+ * Viterbi decode: find the highest-scoring label sequence under the CRF.
+ *
+ * Time: O(seq_len × num_labels²). Space: O(seq_len × num_labels) for the backpointer table.
+ */
+export function viterbi(input) {
+    const { emissions, transitions } = input;
+    const T = emissions.length;
+    if (T === 0)
+        return { path: [], score: 0 };
+    const numLabels = emissions[0].length;
+    const startTrans = input.startTransitions ?? new Array(numLabels).fill(0);
+    const endTrans = input.endTransitions ?? new Array(numLabels).fill(0);
+    // dp[t][k] = best log-score ending at (timestep t, label k)
+    const dp = [];
+    const back = [];
+    // t = 0
+    const first = new Array(numLabels);
+    for (let k = 0; k < numLabels; k++) {
+        first[k] = startTrans[k] + emissions[0][k];
+    }
+    dp.push(first);
+    back.push(new Array(numLabels).fill(-1));
+    for (let t = 1; t < T; t++) {
+        const cur = new Array(numLabels);
+        const ptr = new Array(numLabels);
+        for (let k = 0; k < numLabels; k++) {
+            let bestScore = NEG_INF;
+            let bestPrev = 0;
+            for (let j = 0; j < numLabels; j++) {
+                const s = dp[t - 1][j] + transitions[j][k];
+                if (s > bestScore) {
+                    bestScore = s;
+                    bestPrev = j;
+                }
+            }
+            cur[k] = bestScore + emissions[t][k];
+            ptr[k] = bestPrev;
+        }
+        dp.push(cur);
+        back.push(ptr);
+    }
+    // Pick the best ending state.
+    let bestEndScore = NEG_INF;
+    let bestEnd = 0;
+    for (let k = 0; k < numLabels; k++) {
+        const s = dp[T - 1][k] + endTrans[k];
+        if (s > bestEndScore) {
+            bestEndScore = s;
+            bestEnd = k;
+        }
+    }
+    // Trace back.
+    const path = new Array(T);
+    path[T - 1] = bestEnd;
+    for (let t = T - 1; t > 0; t--) {
+        path[t - 1] = back[t][path[t]];
+    }
+    return { path, score: bestEndScore };
+}
+/**
+ * Convenience: argmax over per-token softmax (existing behavior). Provided so callers can opt in to
+ * Viterbi only when transitions are available, falling back to this cleanly.
+ */
+export function perTokenArgmax(emissions) {
+    return emissions.map((row) => {
+        let bestIdx = 0;
+        let bestVal = row[0];
+        for (let k = 1; k < row.length; k++) {
+            if (row[k] > bestVal) {
+                bestVal = row[k];
+                bestIdx = k;
+            }
+        }
+        return bestIdx;
+    });
+}
+/**
+ * Softmax of a logit row (returns probabilities summing to 1).
+ *
+ * Used to compute per-token confidence after Viterbi picks the label sequence — the confidence is
+ * the softmax probability of the Viterbi-chosen label at that timestep.
+ */
+export function softmax(row) {
+    let max = row[0];
+    for (let i = 1; i < row.length; i++)
+        if (row[i] > max)
+            max = row[i];
+    const exps = row.map((v) => Math.exp(v - max));
+    const sum = exps.reduce((a, b) => a + b, 0);
+    return exps.map((e) => e / sum);
+}
+//# sourceMappingURL=viterbi.js.map

package/out/viterbi.js.map

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

package/out/vitest.config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vitest.config.d.ts","sourceRoot":"","sources":["../vitest.config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;;AAUH,wBAiBE"}
+{"version":3,"file":"vitest.config.d.ts","sourceRoot":"","sources":["../vitest.config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;;AAUH,wBAoBE"}

package/out/vitest.config.js

@@ -22,6 +22,9 @@ export default defineConfig({
             },
             { find: /^@mailwoman\/core\/(.+)$/, replacement: resolve(here, "../core/$1/index.ts") },
             { find: /^@mailwoman\/core$/, replacement: resolve(here, "../core/index.ts") },
+            // @mailwoman/codex resolves to source too (per-address-system postal reference data).
+            { find: /^@mailwoman\/codex\/(.+)$/, replacement: resolve(here, "../codex/$1/index.ts") },
+            { find: /^@mailwoman\/codex$/, replacement: resolve(here, "../codex/index.ts") },
         ],
     },
     test: {

package/out/vitest.config.js.map

@@ -1 +1 @@
-{"version":3,"file":"vitest.config.js","sourceRoot":"","sources":["../vitest.config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,uCAAuC;AAEvC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,MAAM,CAAA;AAEnC,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;AAEzD,eAAe,YAAY,CAAC;IAC3B,OAAO,EAAE;QACR,KAAK,EAAE;YACN,+EAA+E;YAC/E,0EAA0E;YAC1E;gBACC,IAAI,EAAE,0CAA0C;gBAChD,WAAW,EAAE,OAAO,CAAC,IAAI,EAAE,qCAAqC,CAAC;aACjE;YACD,EAAE,IAAI,EAAE,0BAA0B,EAAE,WAAW,EAAE,OAAO,CAAC,IAAI,EAAE,qBAAqB,CAAC,EAAE;YACvF,EAAE,IAAI,EAAE,oBAAoB,EAAE,WAAW,EAAE,OAAO,CAAC,IAAI,EAAE,kBAAkB,CAAC,EAAE;SAC9E;KACD;IACD,IAAI,EAAE;QACL,OAAO,EAAE,KAAK;QACd,OAAO,EAAE,CAAC,oBAAoB,EAAE,WAAW,EAAE,YAAY,CAAC;KAC1D;CACD,CAAC,CAAA"}
+{"version":3,"file":"vitest.config.js","sourceRoot":"","sources":["../vitest.config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,uCAAuC;AAEvC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,MAAM,CAAA;AAEnC,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;AAEzD,eAAe,YAAY,CAAC;IAC3B,OAAO,EAAE;QACR,KAAK,EAAE;YACN,+EAA+E;YAC/E,0EAA0E;YAC1E;gBACC,IAAI,EAAE,0CAA0C;gBAChD,WAAW,EAAE,OAAO,CAAC,IAAI,EAAE,qCAAqC,CAAC;aACjE;YACD,EAAE,IAAI,EAAE,0BAA0B,EAAE,WAAW,EAAE,OAAO,CAAC,IAAI,EAAE,qBAAqB,CAAC,EAAE;YACvF,EAAE,IAAI,EAAE,oBAAoB,EAAE,WAAW,EAAE,OAAO,CAAC,IAAI,EAAE,kBAAkB,CAAC,EAAE;YAC9E,sFAAsF;YACtF,EAAE,IAAI,EAAE,2BAA2B,EAAE,WAAW,EAAE,OAAO,CAAC,IAAI,EAAE,sBAAsB,CAAC,EAAE;YACzF,EAAE,IAAI,EAAE,qBAAqB,EAAE,WAAW,EAAE,OAAO,CAAC,IAAI,EAAE,mBAAmB,CAAC,EAAE;SAChF;KACD;IACD,IAAI,EAAE;QACL,OAAO,EAAE,KAAK;QACd,OAAO,EAAE,CAAC,oBAAoB,EAAE,WAAW,EAAE,YAAY,CAAC;KAC1D;CACD,CAAC,CAAA"}

package/out/weights.d.ts

@@ -28,12 +28,54 @@ export interface ResolveWeightsOpts {
     modelPath?: string;
     /** Explicit tokenizer.model path; takes precedence over package auto-resolve. */
     tokenizerPath?: string;
+    /**
+     * Explicit `model-card.json` path (for the label vocab) on the explicit model+tokenizer path.
+     * When omitted, falls back to a `model-card.json` co-located with `modelPath`. Without a card,
+     * labels default to `STAGE2_BIO_LABELS` — which silently mis-decodes a STAGE3 (33-label) model
+     * into empty/garbage parses. Pass this (or co-locate the card) when evaluating a custom STAGE3
+     * checkpoint via explicit paths.
+     */
+    modelCardPath?: string;
 }
 export interface ResolvedWeights {
     modelPath: string;
     tokenizerPath: string;
+    /**
+     * Path to `model-card.json` for the resolved model. On the package path, the card co-located in
+     * the package dir. On the explicit path, `opts.modelCardPath` or a card co-located with
+     * `modelPath`. `undefined` only when no card is found. Read by `loadFromWeights` to thread the
+     * trained label vocabulary into the classifier — see {@link readLabelsFromModelCard}.
+     */
+    modelCardPath?: string;
+    /**
+     * Path to `crf-transitions.json` alongside the resolved model. `undefined` when the file doesn't
+     * exist (pre-v0.6.0 bundles or CE-only training).
+     */
+    crfTransitionsPath?: string;
     /** "explicit" if both paths came from opts; "package:<name>" if resolved via require.resolve. */
     source: string;
 }
 export declare function resolveWeights(opts: ResolveWeightsOpts): ResolvedWeights;
+/**
+ * Read the `labels` array from a `model-card.json` file. Returns `undefined` when the file is
+ * missing, unreadable, malformed, or has no `labels` field — callers should fall back to their
+ * compile-time default in that case (the loader contract: the JS-side default tracks the most
+ * recent shipped stage, so a card without `labels` is always a pre-v0.4.0 card whose label vocab
+ * matches that default by construction).
+ *
+ * Validates shape: must be a non-empty array of strings. Throws on a present-but-malformed `labels`
+ * field — a card that emits e.g. `labels: 21` rather than `labels: [...]` is a corrupted artifact
+ * and should be loud, not silently re-defaulted.
+ */
+export declare function readLabelsFromModelCard(modelCardPath: string | undefined): readonly string[] | undefined;
+export interface CrfTransitions {
+    transitions: number[][];
+    startTransitions: number[];
+    endTransitions: number[];
+}
+/**
+ * Read learned CRF transition parameters from `crf-transitions.json`. Returns `undefined` when the
+ * file is missing or malformed — callers fall back to the structural BIO mask only.
+ */
+export declare function readCrfTransitions(crfPath: string | undefined): CrfTransitions | undefined;
 //# sourceMappingURL=weights.d.ts.map

package/out/weights.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"weights.d.ts","sourceRoot":"","sources":["../weights.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAQH,MAAM,WAAW,kBAAkB;IAClC,wFAAwF;IACxF,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,iFAAiF;IACjF,aAAa,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,eAAe;IAC/B,SAAS,EAAE,MAAM,CAAA;IACjB,aAAa,EAAE,MAAM,CAAA;IACrB,iGAAiG;IACjG,MAAM,EAAE,MAAM,CAAA;CACd;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,kBAAkB,GAAG,eAAe,CAoCxE"}
+{"version":3,"file":"weights.d.ts","sourceRoot":"","sources":["../weights.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAQH,MAAM,WAAW,kBAAkB;IAClC,wFAAwF;IACxF,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,iFAAiF;IACjF,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,eAAe;IAC/B,SAAS,EAAE,MAAM,CAAA;IACjB,aAAa,EAAE,MAAM,CAAA;IACrB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,iGAAiG;IACjG,MAAM,EAAE,MAAM,CAAA;CACd;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,kBAAkB,GAAG,eAAe,CAkDxE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAwBxG;AAED,MAAM,WAAW,cAAc;IAC9B,WAAW,EAAE,MAAM,EAAE,EAAE,CAAA;IACvB,gBAAgB,EAAE,MAAM,EAAE,CAAA;IAC1B,cAAc,EAAE,MAAM,EAAE,CAAA;CACxB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,cAAc,GAAG,SAAS,CA0B1F"}

package/out/weights.js

@@ -21,7 +21,7 @@
  *   The resolver checks for both files and throws a single actionable error when neither is findable,
  *   naming all the paths it tried.
  */
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, resolve } from "node:path";
 const req = createRequire(import.meta.url);
@@ -32,9 +32,17 @@ export function resolveWeights(opts) {
             throw new Error(`Explicit modelPath does not exist: ${opts.modelPath}`);
         if (!existsSync(opts.tokenizerPath))
             throw new Error(`Explicit tokenizerPath does not exist: ${opts.tokenizerPath}`);
-        return { modelPath: opts.modelPath, tokenizerPath: opts.tokenizerPath, source: "explicit" };
+        // Resolve a model-card for the label vocab: explicit opt first, else one co-located with the
+        // model. Omitting it makes the classifier fall back to STAGE2_BIO_LABELS, which mis-decodes a
+        // STAGE3 (33-label) checkpoint into empty parses — the trap that broke eval-matrix --model-path.
+        const coLocatedCard = resolve(dirname(opts.modelPath), "model-card.json");
+        const modelCardPath = opts.modelCardPath ?? (existsSync(coLocatedCard) ? coLocatedCard : undefined);
+        return { modelPath: opts.modelPath, tokenizerPath: opts.tokenizerPath, modelCardPath, source: "explicit" };
     }
-    const locale = opts.locale ?? "en-us";
+    // Package names follow the all-lowercase BCP-47 convention (`neural-weights-en-us`,
+    // `neural-weights-fr-fr`). The CLI's locale validation accepts canonical `en-US` / `fr-FR`
+    // casing, so we normalize here rather than at the callsite.
+    const locale = (opts.locale ?? "en-us").toLowerCase();
     const packageName = `@mailwoman/neural-weights-${locale}`;
     let packageDir;
     try {
@@ -54,6 +62,86 @@ export function resolveWeights(opts) {
             `Run \`scripts/link-dev-weights.sh\` inside the package to symlink dev weights, ` +
             `or pass --model + --tokenizer with explicit paths.`);
     }
-    return { modelPath, tokenizerPath, source: `package:${packageName}` };
+    const modelCardCandidate = resolve(packageDir, "model-card.json");
+    const modelCardPath = existsSync(modelCardCandidate) ? modelCardCandidate : undefined;
+    const crfCandidate = resolve(packageDir, "crf-transitions.json");
+    const crfTransitionsPath = existsSync(crfCandidate) ? crfCandidate : undefined;
+    return { modelPath, tokenizerPath, modelCardPath, crfTransitionsPath, source: `package:${packageName}` };
+}
+/**
+ * Read the `labels` array from a `model-card.json` file. Returns `undefined` when the file is
+ * missing, unreadable, malformed, or has no `labels` field — callers should fall back to their
+ * compile-time default in that case (the loader contract: the JS-side default tracks the most
+ * recent shipped stage, so a card without `labels` is always a pre-v0.4.0 card whose label vocab
+ * matches that default by construction).
+ *
+ * Validates shape: must be a non-empty array of strings. Throws on a present-but-malformed `labels`
+ * field — a card that emits e.g. `labels: 21` rather than `labels: [...]` is a corrupted artifact
+ * and should be loud, not silently re-defaulted.
+ */
+export function readLabelsFromModelCard(modelCardPath) {
+    if (!modelCardPath || !existsSync(modelCardPath))
+        return undefined;
+    let raw;
+    try {
+        raw = readFileSync(modelCardPath, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return undefined;
+    const labels = parsed.labels;
+    if (labels === undefined)
+        return undefined;
+    if (!Array.isArray(labels) || labels.length === 0 || !labels.every((l) => typeof l === "string")) {
+        throw new Error(`model-card.json at ${modelCardPath} has a malformed \`labels\` field — ` +
+            `expected a non-empty array of strings, got ${JSON.stringify(labels)}.`);
+    }
+    return Object.freeze(labels.slice());
+}
+/**
+ * Read learned CRF transition parameters from `crf-transitions.json`. Returns `undefined` when the
+ * file is missing or malformed — callers fall back to the structural BIO mask only.
+ */
+export function readCrfTransitions(crfPath) {
+    if (!crfPath || !existsSync(crfPath))
+        return undefined;
+    let raw;
+    try {
+        raw = readFileSync(crfPath, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return undefined;
+    const obj = parsed;
+    const transitions = obj.transitions;
+    const start = obj.start_transitions;
+    const end = obj.end_transitions;
+    if (!Array.isArray(transitions) || !Array.isArray(start) || !Array.isArray(end))
+        return undefined;
+    if (transitions.length === 0 || start.length === 0 || end.length === 0)
+        return undefined;
+    return {
+        transitions: transitions,
+        startTransitions: start,
+        endTransitions: end,
+    };
 }
 //# sourceMappingURL=weights.js.map

package/out/weights.js.map

@@ -1 +1 @@
-{"version":3,"file":"weights.js","sourceRoot":"","sources":["../weights.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAE5C,MAAM,GAAG,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAkB1C,MAAM,UAAU,cAAc,CAAC,IAAwB;IACtD,MAAM,KAAK,GAAa,EAAE,CAAA;IAE1B,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;QAC1C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAA;QACxG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,aAAa,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,0CAA0C,IAAI,CAAC,aAAa,EAAE,CAAC,CAAA;QACpH,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,MAAM,EAAE,UAAU,EAAE,CAAA;IAC5F,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,OAAO,CAAA;IACrC,MAAM,WAAW,GAAG,6BAA6B,MAAM,EAAE,CAAA;IACzD,IAAI,UAAkB,CAAA;IACtB,IAAI,CAAC;QACJ,MAAM,WAAW,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,WAAW,eAAe,CAAC,CAAA;QAC9D,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IAClC,CAAC;IAAC,MAAM,CAAC;QACR,MAAM,IAAI,KAAK,CACd,qBAAqB,WAAW,iCAAiC,WAAW,IAAI;YAC/E,oDAAoD,CACrD,CAAA;IACF,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,OAAO,CAAC,UAAU,EAAE,YAAY,CAAC,CAAA;IACrE,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,IAAI,OAAO,CAAC,UAAU,EAAE,iBAAiB,CAAC,CAAA;IAClF,KAAK,CAAC,IAAI,CAAC,SAAS,EAAE,aAAa,CAAC,CAAA;IAEpC,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;QAC1D,MAAM,IAAI,KAAK,CACd,mBAAmB,WAAW,gBAAgB,UAAU,gCAAgC;YACvF,aAAa,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI;YACnC,iFAAiF;YACjF,oDAAoD,CACrD,CAAA;IACF,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,EAAE,WAAW,WAAW,EAAE,EAAE,CAAA;AACtE,CAAC"}
+{"version":3,"file":"weights.js","sourceRoot":"","sources":["../weights.ts"],"names":[],"mappings":"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"}