@desert-ant-labs/redact 0.2.0

package/dist/model.js

@@ -0,0 +1,177 @@
+import { env, AutoTokenizer, AutoModelForTokenClassification, } from "@huggingface/transformers";
+import { deterministicDetect, OWNED_LABELS } from "./deterministic.js";
+import { bioesToSpans, snapSpans, bridgeNameGaps, extendParticleNames, attachBuildingNumbers, redactUsStreet, attachStateCodes, redactSecondaryAddress, relabelByContext, cleanSpans, hysteresis, mergeSpansPriority, resolve, maskText, } from "./pipeline.js";
+const MIN_SCORE = 0.6;
+const LOW_SCORE = 0.3;
+const MAX_LENGTH = 256;
+const KNOWN_LABELS = new Set([
+    "GIVEN_NAME", "SURNAME", "STREET_NAME", "BUILDING_NUMBER", "SECONDARY_ADDRESS",
+    "CITY", "STATE", "ZIP_CODE", "EMAIL", "PHONE", "CREDIT_CARD", "BANK_ACCOUNT",
+    "ROUTING_NUMBER", "IP_ADDRESS", "URL", "GOVERNMENT_ID", "PASSPORT",
+    "DRIVERS_LICENSE", "TAX_ID", "SSN", "IMEI",
+]);
+/**
+ * On-device multilingual PII redaction. A tiny BIOES token classifier (via
+ * transformers.js / ONNX Runtime) reconciled with a dependency-free deterministic
+ * recognizer layer. Load once with {@link Redact.load} and reuse.
+ */
+export class Redact {
+    tokenizer;
+    model;
+    id2label;
+    specialIds;
+    constructor(tokenizer, model) {
+        this.tokenizer = tokenizer;
+        this.model = model;
+        this.id2label = model.config.id2label;
+        this.specialIds = new Set((tokenizer.all_special_ids ?? []).map(Number));
+    }
+    /** Loads the model from the Hugging Face Hub (cached) or a local directory. */
+    static async load(options = {}) {
+        const repo = options.repo ?? "desert-ant-labs/redact";
+        const revision = options.revision ?? "v0.2.0";
+        if (options.localPath) {
+            env.allowRemoteModels = false;
+            env.allowLocalModels = true;
+            env.localModelPath = options.localPath;
+        }
+        if (options.useCache === false)
+            env.useBrowserCache = false;
+        if (options.cacheDir)
+            env.cacheDir = options.cacheDir;
+        const src = options.localPath ?? repo;
+        const cfg = options.localPath ? {} : { revision };
+        const tokenizer = await AutoTokenizer.from_pretrained(src, cfg);
+        const model = await AutoModelForTokenClassification.from_pretrained(src, {
+            ...cfg, dtype: (options.dtype ?? "fp32"),
+        });
+        return new Redact(tokenizer, model);
+    }
+    // Reconstruct char offsets for each subword by aligning the metaspace-prefixed
+    // surface against the source (the XLM-R unigram tokenizer keeps it verbatim).
+    reconstructOffsets(text) {
+        const pieces = this.tokenizer.tokenize(text);
+        let cursor = 0;
+        const out = [];
+        for (const piece of pieces) {
+            const core = piece.replace(/^\u2581/, "");
+            if (core === "") {
+                out.push([cursor, cursor]);
+                continue;
+            }
+            const idx = text.indexOf(core, cursor);
+            if (idx < 0) {
+                out.push([cursor, cursor]);
+                continue;
+            }
+            out.push([idx, idx + core.length]);
+            cursor = idx + core.length;
+        }
+        return out;
+    }
+    async mlSpans(text, minScore) {
+        const enc = this.tokenizer(text, { truncation: true, max_length: MAX_LENGTH });
+        const ids = enc.input_ids.tolist()[0];
+        const out = await this.model({ input_ids: enc.input_ids, attention_mask: enc.attention_mask });
+        const { dims, data } = out.logits;
+        const T = dims[1], C = dims[2];
+        const bestId = new Array(T);
+        const bestProb = new Array(T);
+        for (let t = 0; t < T; t++) {
+            let mx = -Infinity;
+            for (let c = 0; c < C; c++) {
+                const v = data[t * C + c];
+                if (v > mx)
+                    mx = v;
+            }
+            let sum = 0, top = 0, tv = -Infinity;
+            for (let c = 0; c < C; c++) {
+                sum += Math.exp(data[t * C + c] - mx);
+                if (data[t * C + c] > tv) {
+                    tv = data[t * C + c];
+                    top = c;
+                }
+            }
+            bestId[t] = top;
+            bestProb[t] = Math.exp(tv - mx) / sum;
+        }
+        const pieceOffsets = this.reconstructOffsets(text);
+        const offsets = new Array(T);
+        let pi = 0;
+        for (let t = 0; t < T; t++) {
+            offsets[t] = this.specialIds.has(Number(ids[t])) ? [0, 0] : (pieceOffsets[pi++] ?? [0, 0]);
+        }
+        const low = Math.min(LOW_SCORE, minScore);
+        const tags = bestId.map((id, t) => (bestProb[t] >= low ? this.id2label[id] : "O"));
+        const scored = [];
+        for (const span of bioesToSpans(tags, offsets)) {
+            let mx = 0;
+            for (let t = 0; t < T; t++) {
+                const [a, b] = offsets[t];
+                if (b > a && Math.max(a, span.start) < Math.min(b, span.end))
+                    mx = Math.max(mx, bestProb[t]);
+            }
+            scored.push([span, mx]);
+        }
+        let kept = hysteresis(text, scored, minScore);
+        kept = mergeSpansPriority(kept);
+        kept = attachBuildingNumbers(text, extendParticleNames(text, bridgeNameGaps(text, snapSpans(text, kept))));
+        kept = redactSecondaryAddress(text, attachStateCodes(text, redactUsStreet(text, kept)));
+        return mergeSpansPriority(kept);
+    }
+    /** Detect PII spans (the full deterministic-owner hybrid pipeline). */
+    async detect(text, options = {}) {
+        const minScore = options.minimumConfidence ?? MIN_SCORE;
+        const det = deterministicDetect(text, OWNED_LABELS);
+        const ml = await this.mlSpans(maskText(text, det), minScore);
+        const corr = deterministicDetect(text, ["PHONE"]).filter((s) => !OWNED_LABELS.has(s.label));
+        let spans = cleanSpans(text, relabelByContext(text, resolve(det.concat(corr), ml)));
+        if (options.labels) {
+            const allow = new Set(options.labels);
+            spans = spans.filter((s) => allow.has(s.label));
+        }
+        return spans;
+    }
+    /**
+     * Detect and redact the PII in `text`. Each entity is replaced by a unique,
+     * numbered placeholder (`[EMAIL_1]`, `[GIVEN_NAME_1]`, ...) so the result is
+     * safe to hand to an LLM and restore afterwards via {@link Redaction.restore}.
+     */
+    async redaction(text, options = {}) {
+        const spans = (await this.detect(text, options))
+            .slice()
+            .sort((a, b) => a.start - b.start || a.end - b.end);
+        const counts = {};
+        const items = [];
+        let out = "";
+        let last = 0;
+        for (const span of spans) {
+            if (!KNOWN_LABELS.has(span.label))
+                continue;
+            const s = span.start, e = span.end;
+            if (s < last || s >= e || e > text.length)
+                continue; // in order, non-overlapping
+            const n = (counts[span.label] ?? 0) + 1;
+            counts[span.label] = n;
+            const placeholder = `[${span.label}_${n}]`;
+            items.push({
+                label: span.label,
+                original: text.slice(s, e),
+                placeholder,
+                confidence: span.score ?? 1,
+                start: s,
+                end: e,
+            });
+            out += text.slice(last, s) + placeholder;
+            last = e;
+        }
+        out += text.slice(last);
+        const restore = (processed) => {
+            let r = processed;
+            for (const item of items)
+                r = r.split(item.placeholder).join(item.original);
+            return r;
+        };
+        return { redactedText: out, items, restore };
+    }
+}

package/dist/pipeline.d.ts

@@ -0,0 +1,15 @@
+import type { Span } from "./types.js";
+export declare function bioesToSpans(tags: string[], offsets: [number, number][]): Span[];
+export declare function snapSpans(text: string, spans: Span[]): Span[];
+export declare function bridgeNameGaps(text: string, spans: Span[]): Span[];
+export declare function extendParticleNames(text: string, spans: Span[]): Span[];
+export declare function attachBuildingNumbers(text: string, spans: Span[]): Span[];
+export declare function redactUsStreet(text: string, spans: Span[]): Span[];
+export declare function attachStateCodes(text: string, spans: Span[]): Span[];
+export declare function redactSecondaryAddress(text: string, spans: Span[]): Span[];
+export declare function relabelByContext(text: string, spans: Span[]): Span[];
+export declare function cleanSpans(text: string, spans: Span[]): Span[];
+export declare function hysteresis(text: string, scored: [Span, number][], high: number): Span[];
+export declare function mergeSpansPriority(spans: Span[]): Span[];
+export declare function resolve(detSpans: Span[], mlSpans: Span[]): Span[];
+export declare function maskText(text: string, spans: Span[], maskChar?: string): string;

package/dist/pipeline.js

@@ -0,0 +1,353 @@
+// Port of redact_training.pipeline + labels.bioes_to_spans. Span post-processing
+// (BIOES decode, word snapping, name bridging, deterministic-owner merge).
+const NAME_FAMILIES = new Set(["GIVEN_NAME", "SURNAME"]);
+const CONNECT = "-'\u2019";
+function splitTag(t) {
+    if (t === "O")
+        return ["O", null];
+    const i = t.indexOf("-");
+    return [t.slice(0, i), t.slice(i + 1)];
+}
+// ── BIOES → char spans (tolerant) ────────────────────────────────────────
+export function bioesToSpans(tags, offsets) {
+    const out = [];
+    let label = null, start = null, end = null;
+    const close = () => {
+        if (label !== null && start !== null && end !== null && end > start)
+            out.push({ start, end, label });
+        label = start = end = null;
+    };
+    for (let i = 0; i < tags.length; i++) {
+        const [prefix, lab] = splitTag(tags[i]);
+        const [a, b] = offsets[i];
+        if (b <= a)
+            continue;
+        if (prefix === "O") {
+            close();
+            continue;
+        }
+        if (prefix === "S") {
+            close();
+            out.push({ start: a, end: b, label: lab });
+        }
+        else if (prefix === "B") {
+            close();
+            label = lab;
+            start = a;
+            end = b;
+        }
+        else if (prefix === "I") {
+            if (label === lab)
+                end = b;
+            else {
+                close();
+                label = lab;
+                start = a;
+                end = b;
+            }
+        }
+        else if (prefix === "E") {
+            if (label === lab) {
+                end = b;
+                close();
+            }
+            else {
+                close();
+                out.push({ start: a, end: b, label: lab });
+            }
+        }
+    }
+    close();
+    return out;
+}
+const isWordChar = (c) => /[\p{L}\p{N}]/u.test(c) || /\p{M}/u.test(c);
+function snapOne(text, s, e) {
+    const n = text.length;
+    s = Math.max(0, Math.min(s, n));
+    e = Math.max(0, Math.min(e, n));
+    while (s > 0) {
+        const c = text[s - 1];
+        if (isWordChar(c))
+            s--;
+        else if (CONNECT.includes(c) && s - 2 >= 0 && isWordChar(text[s - 2]))
+            s--;
+        else
+            break;
+    }
+    while (e < n) {
+        const c = text[e];
+        if (isWordChar(c))
+            e++;
+        else if (CONNECT.includes(c) && e + 1 < n && isWordChar(text[e + 1]))
+            e++;
+        else
+            break;
+    }
+    return [s, e];
+}
+function mergeSameLabel(spans) {
+    const ordered = spans.slice().sort((a, b) => a.start - b.start || (b.end - b.start) - (a.end - a.start) || a.label.localeCompare(b.label));
+    const out = [];
+    for (const s of ordered) {
+        if (out.length && s.label === out[out.length - 1].label && s.start <= out[out.length - 1].end)
+            out[out.length - 1] = { start: out[out.length - 1].start, end: Math.max(out[out.length - 1].end, s.end), label: s.label };
+        else if (!out.length || s.start >= out[out.length - 1].end)
+            out.push(s);
+    }
+    return out;
+}
+export function snapSpans(text, spans) {
+    return mergeSameLabel(spans.map((sp) => {
+        const [s, e] = snapOne(text, sp.start, sp.end);
+        return { start: s, end: e, label: sp.label };
+    }));
+}
+const PARTICLES = new Set(["de", "del", "della", "dell", "di", "da", "das", "dos", "du",
+    "van", "von", "der", "den", "ter", "la", "le", "el", "al", "bin", "ibn", "mac", "mc",
+    "o", "st", "of", "y", "e"]);
+const ALL_PARTICLES = new Set(["van", "von", "de", "del", "della", "dell", "di", "da", "das",
+    "dos", "du", "zu", "af", "ter", "ten", "des", "do", "der", "den", "la", "le", "el", "y"]);
+function gapIsNameLike(gap) {
+    if (!gap.trim())
+        return false;
+    if (gap.length > 20 || /[,;:/&|()\[\]{}"<>\n\t]/.test(gap))
+        return false;
+    for (const tok of gap.split(/\s+/)) {
+        const w = tok.replace(/^[.'\u2019-]+|[.'\u2019-]+$/g, "");
+        if (!w)
+            continue;
+        if (PARTICLES.has(w.toLowerCase()) || w.length === 1 || w[0] === w[0].toUpperCase())
+            continue;
+        return false;
+    }
+    return true;
+}
+export function bridgeNameGaps(text, spans) {
+    const ordered = spans.slice().sort((a, b) => a.start - b.start || a.end - b.end);
+    const out = [];
+    for (const s of ordered) {
+        const p = out[out.length - 1];
+        if (p && NAME_FAMILIES.has(p.label) && NAME_FAMILIES.has(s.label) &&
+            s.start >= p.end && gapIsNameLike(text.slice(p.end, s.start)))
+            out[out.length - 1] = { start: p.start, end: Math.max(p.end, s.end), label: p.label };
+        else
+            out.push(s);
+    }
+    return out;
+}
+export function extendParticleNames(text, spans) {
+    const ordered = spans.slice().sort((a, b) => a.start - b.start || a.end - b.end);
+    const out = [];
+    const NEXT = /^(\s+)([^\s,.;:!?)\]}"]+)/;
+    for (let sp of ordered) {
+        if (NAME_FAMILIES.has(sp.label)) {
+            const tw = /([^\s]+)\s*$/.exec(text.slice(sp.start, sp.end));
+            let consumed = !!(tw && ALL_PARTICLES.has(tw[1].replace(/^[.'\u2019]+|[.'\u2019]+$/g, "").toLowerCase()));
+            let pos = sp.end;
+            while (true) {
+                const m = NEXT.exec(text.slice(pos));
+                if (!m)
+                    break;
+                const tok = m[2];
+                if (ALL_PARTICLES.has(tok.replace(/^[.'\u2019]+|[.'\u2019]+$/g, "").toLowerCase())) {
+                    pos += m[0].length;
+                    consumed = true;
+                    continue;
+                }
+                if (consumed && tok[0] === tok[0].toUpperCase() && tok[0] !== tok[0].toLowerCase())
+                    pos += m[0].length;
+                break;
+            }
+            if (pos > sp.end)
+                sp = { start: sp.start, end: pos, label: sp.label };
+        }
+        out.push(sp);
+    }
+    return mergeSameLabel(out);
+}
+export function attachBuildingNumbers(text, spans) {
+    const out = spans.map((s) => ({ ...s }));
+    const occ = out.map((s) => [s.start, s.end]);
+    const free = (a, b) => !occ.some(([x, y]) => x < b && a < y);
+    const AFTER = /^[\s,]{0,2}(\d{1,5}[a-zA-Z]?(?:[-/]\d{1,4}[a-zA-Z]?)?)\b/;
+    const BEFORE = /(\d{1,5}[a-zA-Z]?)[\s,]{0,2}$/;
+    for (const s of spans) {
+        if (s.label !== "STREET_NAME")
+            continue;
+        const m = AFTER.exec(text.slice(s.end));
+        if (m) {
+            const a = s.end + m.index + m[0].indexOf(m[1]), b = a + m[1].length;
+            if (free(a, b)) {
+                out.push({ start: a, end: b, label: "BUILDING_NUMBER" });
+                occ.push([a, b]);
+            }
+        }
+        const base = Math.max(0, s.start - 8);
+        const m2 = BEFORE.exec(text.slice(base, s.start));
+        if (m2) {
+            const a = base + m2.index, b = a + m2[1].length;
+            if (free(a, b)) {
+                out.push({ start: a, end: b, label: "BUILDING_NUMBER" });
+                occ.push([a, b]);
+            }
+        }
+    }
+    return mergeSameLabel(out).sort((a, b) => a.start - b.start || a.end - b.end);
+}
+// US street / secondary-address / state-code recognizers (mirror pipeline.py and
+// Pipeline.swift): the model often leaves these in the clear, so redact them
+// deterministically.
+const US_STREET_RE = /\b(\d{1,6}[A-Za-z]?)\s+((?:[A-Z][A-Za-z0-9.'’-]*\s+){0,4}(?:Street|Avenue|Boulevard|Road|Lane|Drive|Court|Place|Terrace|Circle|Highway|Parkway|Square|Trail|Crescent|Alley|Loop|Way|St|Ave|Blvd|Rd|Ln|Dr|Ct|Pl|Ter|Cir|Hwy|Pkwy|Sq|Trl|Aly))\b\.?(?=$|[\s,.;:)])/gd;
+const STATE_ZIP_RE = /(?:,\s*|\s)([A-Z]{2})\s+(\d{5}(?:-\d{4})?)\b/gd;
+const SEC_ADDR_RE = /\b(?:Apartment|Apt|Suite|Ste|Unit|Building|Bldg|Floor|Fl|Room|Rm|Department|Dept|Trailer|Trlr|Space|Spc|Lot)\.?\s*#?\s*(?:\d{1,4}[A-Za-z]?|[A-Za-z]\d{1,4})\b/gi;
+const US_STATES = new Set(("AL AK AZ AR CA CO CT DE DC FL GA HI ID IL IN IA KS KY LA ME MD MA MI MN MS "
+    + "MO MT NE NV NH NJ NM NY NC ND OH OK OR PA RI SC SD TN TX UT VT VA WA WV WI WY").split(" "));
+export function redactUsStreet(text, spans) {
+    let out = spans.map((s) => ({ ...s }));
+    for (const m of text.matchAll(US_STREET_RE)) {
+        const [bnS, bnE] = m.indices[1], [stS, stE] = m.indices[2];
+        out = out.filter((s) => !((s.label === "STREET_NAME" || s.label === "BUILDING_NUMBER") && Math.max(s.start, bnS) < Math.min(s.end, stE)));
+        out.push({ start: bnS, end: bnE, label: "BUILDING_NUMBER" });
+        out.push({ start: stS, end: stE, label: "STREET_NAME" });
+    }
+    return mergeSameLabel(out).sort((a, b) => a.start - b.start || a.end - b.end);
+}
+export function attachStateCodes(text, spans) {
+    const out = spans.map((s) => ({ ...s }));
+    const occ = out.map((s) => [s.start, s.end]);
+    const add = (a, b, label) => { if (!occ.some(([x, y]) => x < b && a < y)) {
+        out.push({ start: a, end: b, label });
+        occ.push([a, b]);
+    } };
+    for (const m of text.matchAll(STATE_ZIP_RE)) {
+        const [sS, sE] = m.indices[1], [zS, zE] = m.indices[2];
+        if (US_STATES.has(text.slice(sS, sE))) {
+            add(sS, sE, "STATE");
+            add(zS, zE, "ZIP_CODE");
+        }
+    }
+    return mergeSameLabel(out).sort((a, b) => a.start - b.start || a.end - b.end);
+}
+export function redactSecondaryAddress(text, spans) {
+    let out = spans.map((s) => ({ ...s }));
+    for (const m of text.matchAll(SEC_ADDR_RE)) {
+        const s = m.index, e = m.index + m[0].length;
+        out = out.filter((sp) => !((sp.label === "SECONDARY_ADDRESS" || sp.label === "BUILDING_NUMBER") && Math.max(sp.start, s) < Math.min(sp.end, e)));
+        out.push({ start: s, end: e, label: "SECONDARY_ADDRESS" });
+    }
+    return mergeSameLabel(out).sort((a, b) => a.start - b.start || a.end - b.end);
+}
+// Final label/text tidy - mirrors pipeline.py relabel_by_context + clean_spans.
+const TRIM_TRAIL = " \t\n\r.,;:!?)]}\"\u00bb\u2019\u201d'";
+const TRIM_LEAD = " \t\n\r([{\"\u00ab\u2018\u201c";
+const ACCT_LEFT = /(?:\ba\/?c\b|acct|account|konto|compte|cuenta|rekening|conta|\biban\b)\W{0,4}#?\s*$/i;
+const STRIP_TITLES = new Set(["mr", "mrs", "ms", "miss", "mx", "master", "mstr", "dr", "prof", "professor",
+    "doctor", "dear", "sir", "madam", "madame", "monsieur", "mme", "mlle", "herr", "frau",
+    "fraulein", "frl", "mevrouw", "dhr", "signor", "signora"]);
+export function relabelByContext(text, spans) {
+    return spans.map((s) => {
+        let lab = s.label;
+        const left = text.slice(Math.max(0, s.start - 28), s.start).toLowerCase();
+        if (lab === "PHONE" && ACCT_LEFT.test(left))
+            lab = "BANK_ACCOUNT";
+        else if (lab === "GOVERNMENT_ID" && ((left.includes("driv") && left.includes("licen"))
+            || left.includes("f\u00fchrerschein") || left.includes("fuhrerschein") || left.includes("rijbewijs")
+            || (left.includes("permis") && left.includes("conduire"))))
+            lab = "DRIVERS_LICENSE";
+        return { start: s.start, end: s.end, label: lab };
+    });
+}
+export function cleanSpans(text, spans) {
+    const out = [];
+    for (const s of spans) {
+        let st = s.start, en = s.end;
+        while (en > st && TRIM_TRAIL.includes(text[en - 1]))
+            en--;
+        while (st < en && TRIM_LEAD.includes(text[st]))
+            st++;
+        if (NAME_FAMILIES.has(s.label)) {
+            while (st < en) {
+                const m = /^(\S+)\s+/.exec(text.slice(st, en));
+                if (!m || !STRIP_TITLES.has(m[1].replace(/^[.'\u2019]+|[.'\u2019]+$/g, "").toLowerCase()))
+                    break;
+                st += m[0].length;
+            }
+            const core = text.slice(st, en).replace(/^[.'\u2019 ]+|[.'\u2019 ]+$/g, "");
+            if (!core || STRIP_TITLES.has(core.toLowerCase()))
+                continue;
+        }
+        if (en > st)
+            out.push({ start: st, end: en, label: s.label });
+    }
+    return out;
+}
+function adjacentName(text, a, b) {
+    const [lo, hi] = a.start <= b.start ? [a, b] : [b, a];
+    if (hi.start < lo.end)
+        return true;
+    const gap = text.slice(lo.end, hi.start);
+    return (!gap.trim() && gap.length <= 3) || gapIsNameLike(gap);
+}
+export function hysteresis(text, scored, high) {
+    const kept = scored.filter(([, sc]) => sc >= high).map(([sp]) => sp);
+    const weak = scored.filter(([sp, sc]) => sc < high && NAME_FAMILIES.has(sp.label)).map(([sp]) => sp);
+    let changed = true;
+    while (changed && weak.length) {
+        changed = false;
+        for (const sp of [...weak]) {
+            if (kept.some((k) => NAME_FAMILIES.has(k.label) && adjacentName(text, sp, k))) {
+                kept.push(sp);
+                weak.splice(weak.indexOf(sp), 1);
+                changed = true;
+            }
+        }
+    }
+    return kept;
+}
+const DET_OWNED = new Set(["SSN", "CREDIT_CARD", "EMAIL", "URL", "IP_ADDRESS", "BANK_ACCOUNT", "ROUTING_NUMBER"]);
+export function mergeSpansPriority(spans) {
+    const prio = (s) => [DET_OWNED.has(s.label) ? 2 : 1, s.end - s.start];
+    const gt = (a, b) => a[0] > b[0] || (a[0] === b[0] && a[1] > b[1]);
+    const ordered = spans.slice().sort((a, b) => a.start - b.start || (b.end - b.start) - (a.end - a.start) || a.label.localeCompare(b.label));
+    const out = [];
+    for (const s of ordered) {
+        if (out.length && s.label === out[out.length - 1].label && s.start <= out[out.length - 1].end)
+            out[out.length - 1] = { start: out[out.length - 1].start, end: Math.max(out[out.length - 1].end, s.end), label: s.label };
+        else if (!out.length || s.start >= out[out.length - 1].end)
+            out.push(s);
+        else if (gt(prio(s), prio(out[out.length - 1])))
+            out[out.length - 1] = s;
+    }
+    return out;
+}
+const overlaps = (a0, a1, b0, b1) => Math.max(a0, b0) < Math.min(a1, b1);
+export function resolve(detSpans, mlSpans) {
+    const det = detSpans.map((s) => ({ ...s })), ml = mlSpans.map((s) => ({ ...s }));
+    const suppressed = new Set();
+    const keptMl = [];
+    for (const m of ml) {
+        let conflict = false;
+        for (let i = 0; i < det.length; i++) {
+            if (overlaps(m.start, m.end, det[i].start, det[i].end)) {
+                if (m.label === det[i].label)
+                    suppressed.add(i);
+                else
+                    conflict = true;
+            }
+        }
+        if (!conflict)
+            keptMl.push(m);
+    }
+    const keptDet = det.filter((_, i) => !suppressed.has(i));
+    return mergeSameLabel(keptDet.concat(keptMl)).sort((a, b) => a.start - b.start || a.end - b.end || a.label.localeCompare(b.label));
+}
+export function maskText(text, spans, maskChar) {
+    if (!text)
+        return text;
+    const chars = text.split("");
+    for (const s of spans)
+        for (let i = Math.max(0, s.start); i < Math.min(chars.length, s.end); i++)
+            if (chars[i] !== "\n")
+                chars[i] = " ";
+    return chars.join("");
+}

package/dist/types.d.ts

@@ -0,0 +1,39 @@
+/** A detected span with character offsets into the source text. */
+export interface Span {
+    start: number;
+    end: number;
+    label: string;
+    score?: number;
+}
+/** The 20 model labels plus the deterministic-only `IMEI` label. */
+export type RedactLabel = "GIVEN_NAME" | "SURNAME" | "STREET_NAME" | "BUILDING_NUMBER" | "SECONDARY_ADDRESS" | "CITY" | "STATE" | "ZIP_CODE" | "EMAIL" | "PHONE" | "CREDIT_CARD" | "BANK_ACCOUNT" | "ROUTING_NUMBER" | "IP_ADDRESS" | "URL" | "GOVERNMENT_ID" | "PASSPORT" | "DRIVERS_LICENSE" | "TAX_ID" | "SSN" | "IMEI";
+/** A single redacted entity, with its placeholder and original value. */
+export interface RedactionItem {
+    /** PII category, e.g. `"EMAIL"`. */
+    label: string;
+    /** The matched sensitive text. */
+    original: string;
+    /** Numbered placeholder, e.g. `"[EMAIL_1]"`. */
+    placeholder: string;
+    /** Confidence in `0..1` (deterministic recognizers report `1`). */
+    confidence: number;
+    /** Character offsets of `original` in the source text. */
+    start: number;
+    end: number;
+}
+/** The result of a redaction: masked text, the detections, and a restore helper. */
+export interface Redaction {
+    /** The input with every detection replaced by a `[LABEL_N]` placeholder. */
+    redactedText: string;
+    /** Every detection, in document order. */
+    items: RedactionItem[];
+    /** Fill original values back into text that still contains the placeholders. */
+    restore(processed: string): string;
+}
+/** Detection options. */
+export interface Options {
+    /** Neural confidence threshold, `0..1`. Default `0.6`. Deterministic recognizers always apply. */
+    minimumConfidence?: number;
+    /** Restrict detection to these labels. Omit to detect every category. */
+    labels?: Iterable<string>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@desert-ant-labs/redact",
+  "version": "0.2.0",
+  "description": "On-device multilingual PII redaction: detect and mask names, addresses, emails, phones, cards, IBANs, national IDs, VAT numbers and more across 24 EU languages.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./deterministic": {
+      "types": "./dist/deterministic.d.ts",
+      "default": "./dist/deterministic.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "node --import tsx --test test/*.test.ts",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "pii",
+    "redaction",
+    "privacy",
+    "gdpr",
+    "on-device",
+    "multilingual",
+    "token-classification",
+    "transformers.js"
+  ],
+  "license": "SEE LICENSE IN LICENSE.md",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Desert-Ant-Labs/redact-js.git"
+  },
+  "homepage": "https://github.com/Desert-Ant-Labs/redact-js",
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@huggingface/transformers": "^4.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "tsx": "^4",
+    "typescript": "^5"
+  }
+}