gheim 0.1.2 → 0.1.3

package/README.md

@@ -38,33 +38,38 @@ The core package itself has no runtime dependencies.
 
 `LocalDetector` loads a token-classification model via
 [`@huggingface/transformers`](https://www.npmjs.com/package/@huggingface/transformers)
-(transformers.js). Two models are recommended depending on the
-deployment context. Both implement the same 33-class BIOES output
-schema and are interchangeable.
+(transformers.js). The package's default model is
+[`joelbarmettler/gheim-ch-560m`](https://huggingface.co/joelbarmettler/gheim-ch-560m)
+— a 560M xlm-roberta-large fine-tune optimised for Swiss-market PII
+(strict-span F1 0.916 on Swiss text, see
+[MODEL_CARD.md](https://github.com/joelbarmettlerUZH/gheim/blob/main/MODEL_CARD.md)).
+Any HuggingFace token-classification model that emits the same 33-class
+BIOES schema can be substituted via `model:`.
 
 | Model | Best for | Parameters | Notes |
 |---|---|---:|---|
-| [`joelbarmettler/gheim-ch-560m`](https://huggingface.co/joelbarmettler/gheim-ch-560m) | Swiss-market text (de_CH, fr_CH, it_CH, rm, en) with CH-format account numbers (IBAN, AHV, VAT-CHE) | 560M | Apache 2.0. Test F1 = 0.916 on Swiss text. ONNX export ships in the `onnx/` subfolder. |
+| [`joelbarmettler/gheim-ch-560m`](https://huggingface.co/joelbarmettler/gheim-ch-560m) **(default)** | Swiss-market text (de_CH, fr_CH, it_CH, rm, en) with CH-format account numbers (IBAN, AHV, VAT-CHE) | 560M | Apache 2.0. Test F1 0.916. Hub repo ships `onnx/model_quantized.onnx` only — load with `dtype: "q8"`. |
 | [`openai/privacy-filter`](https://huggingface.co/openai/privacy-filter) | English-first or general use, long-context (up to 128k tokens) | 1.4B (50M active, MoE) | Apache 2.0. Wider language coverage, larger weights. |
 
 ```ts
 import { LocalDetector } from "gheim";
 
-// Recommended for Swiss-market text:
-const det = new LocalDetector({ model: "joelbarmettler/gheim-ch-560m" });
+// Default — Swiss-tuned, q8 ONNX. `device: "auto"` probes WebGPU in
+// the browser and falls back to WASM; in Node it's WASM directly.
+const det = new LocalDetector({ dtype: "q8" });
 
 // Alternative for English or general use:
 const detEn = new LocalDetector({ model: "openai/privacy-filter" });
 ```
 
-The package default `model` is `openai/privacy-filter`. Pass `model`
-explicitly to opt into the Swiss model.
-
 ## Drop-in OpenAI client
 
 ```ts
 import { OpenAI } from "gheim/openai";
 
+// Same constructor shape as `openai`. `apiKey`, `baseURL`, etc. work
+// at the top level (forwarded to the inner client). gheim-specific
+// keys: `gheimDetector`, `gheimStrict`, `openaiClient`, `clientOptions`.
 const client = new OpenAI();
 const r = await client.chat.completions.create({
   model: "gpt-4o",
@@ -74,6 +79,17 @@ const r = await client.chat.completions.create({
 // OpenAI only ever saw "<PERSON_1>".
 ```
 
+Custom endpoint or key (e.g. OpenRouter, local vLLM):
+
+```ts
+import { OpenAI } from "gheim/openai";
+
+const client = new OpenAI({
+  apiKey: process.env.OPENROUTER_API_KEY,
+  baseURL: "https://openrouter.ai/api/v1",
+});
+```
+
 Streaming:
 
 ```ts
@@ -104,9 +120,9 @@ All non-chat OpenAI resources are on `client.raw` once `await client.ready()` re
 import { Session, LocalDetector, anonymizeText, deanonymizeText } from "gheim";
 
 const session = new Session();
-(session as any).detector = new LocalDetector({
-  model: "joelbarmettler/gheim-ch-560m",
-});
+(session as any).detector = new LocalDetector({ dtype: "q8" });
+//                                 ^ defaults to joelbarmettler/gheim-ch-560m
+
 const clean = await anonymizeText("Hi, my name is Joel", session);
 // ... call any LLM with clean ...
 const final = deanonymizeText(responseText, session);
@@ -155,12 +171,18 @@ client.raw.beta.assistants.create(...);  // always works regardless of strict mo
 ```ts
 import { LocalDetector, RemoteDetector, defaultDetector } from "gheim";
 
-// Local: via @huggingface/transformers, on Node and Bun.
+// Local: via @huggingface/transformers, on Node, Bun, and browsers.
+// `device: "auto"` (default) probes navigator.gpu in the browser and
+// falls back to WASM if WebGPU isn't usable; in Node it's WASM only.
 const local = new LocalDetector({
-  model: "joelbarmettler/gheim-ch-560m",
   device: "auto",
-  dtype: "fp32",
+  dtype: "q8",
+  onProgress: (e) => {
+    if (e.fraction != null) console.log(`loading: ${(e.fraction * 100) | 0}%`);
+  },
 });
+await local.load();
+console.log("backend in use:", local.actualDevice);  // "webgpu" or "wasm"
 
 // Remote: against your own gheim-server or api.gheim.ch.
 const remote = new RemoteDetector({
@@ -174,10 +196,9 @@ const auto = defaultDetector();
 
 ## Runtime support
 
-Tested on Node 18+ and Bun 1.1+ with `device: "cpu"` (the default). The
-underlying transformers.js library also supports `device: "webgpu"` in
-modern browsers; the WebGPU path is not exercised in CI and should be
-considered best-effort.
+Tested on Node 18+, Bun 1.1+, and modern browsers (Chrome 113+, Edge,
+Safari 17+, Firefox via flag). Browser builds use WebGPU when available
+and fall back to WebAssembly automatically.
 
 For Node servers, installing `onnxruntime-node` alongside
 `@huggingface/transformers` enables the native ONNX backend, which is

package/dist/cjs/index.cjs

@@ -57,7 +57,8 @@ __export(exports_src, {
   REMOTE_DEFAULT_MODEL: () => DEFAULT_MODEL,
   LocalDetector: () => LocalDetector,
   LABEL_TO_TAG: () => LABEL_TO_TAG,
-  DEFAULT_BASE_URL: () => DEFAULT_BASE_URL
+  DEFAULT_BASE_URL: () => DEFAULT_BASE_URL,
+  CompositeDetector: () => CompositeDetector
 });
 module.exports = __toCommonJS(exports_src);
 
@@ -619,6 +620,214 @@ async function loadTransformersJs() {
     throw new Error("LocalDetector requires `@huggingface/transformers`. Install with: bun add @huggingface/transformers");
   }
 }
+// src/detectors/composite.ts
+function luhnOk(s) {
+  const digits = [];
+  for (const c of s) {
+    if (c >= "0" && c <= "9")
+      digits.push(Number(c));
+  }
+  if (digits.length < 13 || digits.length > 19)
+    return false;
+  let total = 0;
+  for (let i = 0;i < digits.length; i++) {
+    let d = digits[digits.length - 1 - i] ?? 0;
+    if (i % 2 === 1) {
+      d *= 2;
+      if (d > 9)
+        d -= 9;
+    }
+    total += d;
+  }
+  return total % 10 === 0;
+}
+function ibanChOk(raw) {
+  const s = raw.replace(/[\s-]/g, "");
+  if (s.length !== 21 || !s.startsWith("CH") || !/^\d+$/.test(s.slice(2))) {
+    return false;
+  }
+  const rearranged = s.slice(4) + s.slice(0, 4);
+  let numeric = "";
+  for (const c of rearranged) {
+    numeric += c >= "A" && c <= "Z" ? String(c.charCodeAt(0) - 55) : c;
+  }
+  let rem = 0;
+  for (const ch of numeric) {
+    rem = (rem * 10 + Number(ch)) % 97;
+  }
+  return rem === 1;
+}
+function ahvOk(s) {
+  const digits = [];
+  for (const c of s) {
+    if (c >= "0" && c <= "9")
+      digits.push(Number(c));
+  }
+  if (digits.length !== 13)
+    return false;
+  if (digits[0] !== 7 || digits[1] !== 5 || digits[2] !== 6)
+    return false;
+  let total = 0;
+  for (let i = 0;i < 12; i++) {
+    total += (digits[i] ?? 0) * (i % 2 === 0 ? 1 : 3);
+  }
+  const check = (10 - total % 10) % 10;
+  return digits[12] === check;
+}
+function vatCheOk(s) {
+  const digits = [];
+  for (const c of s) {
+    if (c >= "0" && c <= "9")
+      digits.push(Number(c));
+  }
+  if (digits.length < 9)
+    return false;
+  const weights = [5, 4, 3, 2, 7, 6, 5, 4];
+  let total = 0;
+  for (let i = 0;i < 8; i++) {
+    total += (digits[i] ?? 0) * (weights[i] ?? 0);
+  }
+  let expected = 11 - total % 11;
+  if (expected === 11)
+    expected = 0;
+  else if (expected === 10)
+    return false;
+  return digits[8] === expected;
+}
+var REGEXES = [
+  {
+    label: "private_email",
+    pattern: /\b[\w._%+\-]+@[\w.\-]+\.[A-Za-z]{2,}\b/g
+  },
+  {
+    label: "private_url",
+    pattern: /https?:\/\/[^\s)>\]]+/g
+  },
+  {
+    label: "private_phone",
+    pattern: /(?:\+41|0041|0)\s?(?:\(0\)\s?)?\d{2}[\s\-/.]?\d{3}[\s\-/.]?\d{2}[\s\-/.]?\d{2}\b/g
+  },
+  {
+    label: "account_number",
+    pattern: /\bCH\d{2}(?:[\s-]?\d){17}\b/g,
+    validator: ibanChOk
+  },
+  {
+    label: "account_number",
+    pattern: /\b756\.\d{4}\.\d{4}\.\d{2}\b/g,
+    validator: ahvOk
+  },
+  {
+    label: "account_number",
+    pattern: /\b756\d{10}\b/g,
+    validator: ahvOk
+  },
+  {
+    label: "account_number",
+    pattern: /\bCHE-\d{3}\.\d{3}\.\d{3}(?:\s+(?:MWST|TVA|IVA))?\b/g,
+    validator: vatCheOk
+  },
+  {
+    label: "account_number",
+    pattern: /\b(?:\d[\s-]?){15,16}\d\b/g,
+    validator: luhnOk
+  },
+  {
+    label: "private_date",
+    pattern: /\b(?:\d{1,2}[./]\d{1,2}[./]\d{4}|\d{4}[./-]\d{1,2}[./-]\d{1,2})\b/g
+  },
+  {
+    label: "secret",
+    pattern: /\bsk-(?:proj-)?[A-Za-z0-9_\-]{20,}\b/g
+  },
+  {
+    label: "secret",
+    pattern: /\bghp_[A-Za-z0-9]{36}\b/g
+  },
+  {
+    label: "secret",
+    pattern: /\bAKIA[A-Z0-9]{16}\b/g
+  }
+];
+var URL_TRAIL_TRIM = '.,;:!?")>]';
+function trimUrl(text, start, end) {
+  while (end > start && URL_TRAIL_TRIM.includes(text[end - 1] ?? ""))
+    end--;
+  return [start, end];
+}
+function findRegexSpans(text) {
+  const candidates = [];
+  for (const { label, pattern, validator } of REGEXES) {
+    pattern.lastIndex = 0;
+    let m;
+    while ((m = pattern.exec(text)) !== null) {
+      let start = m.index;
+      let end = m.index + m[0].length;
+      if (label === "private_url")
+        [start, end] = trimUrl(text, start, end);
+      const value = text.slice(start, end);
+      if (!value.trim())
+        continue;
+      if (validator && !validator(value))
+        continue;
+      candidates.push({
+        start,
+        end,
+        label,
+        text: value,
+        score: 1
+      });
+    }
+  }
+  candidates.sort((a, b) => a.start !== b.start ? a.start - b.start : b.end - b.start - (a.end - a.start));
+  const out = [];
+  let lastEnd = -1;
+  for (const sp of candidates) {
+    if (sp.start < lastEnd)
+      continue;
+    out.push(sp);
+    lastEnd = sp.end;
+  }
+  return out;
+}
+function maskSpans(text, spans) {
+  if (spans.length === 0)
+    return text;
+  const chars = [...text];
+  for (const sp of spans) {
+    for (let i = sp.start;i < sp.end && i < chars.length; i++) {
+      chars[i] = " ";
+    }
+  }
+  return chars.join("");
+}
+
+class CompositeDetector {
+  model;
+  constructor(opts) {
+    if (!opts || !opts.model) {
+      throw new Error("CompositeDetector requires { model: Detector } — pass any object with " + "a .detect(text) method (e.g. new LocalDetector({...})).");
+    }
+    this.model = opts.model;
+  }
+  async detect(text, opts) {
+    if (!text)
+      return [];
+    const regexSpans = findRegexSpans(text);
+    const masked = maskSpans(text, regexSpans);
+    const modelSpans = await this.model.detect(masked, opts);
+    const out = [...regexSpans];
+    const regexRanges = regexSpans.map((s) => [s.start, s.end]);
+    for (const sp of modelSpans) {
+      const overlaps = regexRanges.some(([rs, re]) => sp.start < re && rs < sp.end);
+      if (overlaps)
+        continue;
+      out.push(sp);
+    }
+    out.sort((a, b) => a.start !== b.start ? a.start - b.start : b.end - b.start - (a.end - a.start));
+    return out;
+  }
+}
 // src/detectors/index.ts
 function defaultDetector() {
   const hasKey = typeof process !== "undefined" && Boolean(process.env?.GHEIM_API_KEY);
@@ -673,4 +882,4 @@ async function* deanonymizeStream(chunks, session) {
 }
 
 // src/index.ts
-var VERSION = "0.1.2";
+var VERSION = "0.1.3";

package/dist/cjs/openai/index.cjs

@@ -543,6 +543,214 @@ async function loadTransformersJs() {
     throw new Error("LocalDetector requires `@huggingface/transformers`. Install with: bun add @huggingface/transformers");
   }
 }
+// src/detectors/composite.ts
+function luhnOk(s) {
+  const digits = [];
+  for (const c of s) {
+    if (c >= "0" && c <= "9")
+      digits.push(Number(c));
+  }
+  if (digits.length < 13 || digits.length > 19)
+    return false;
+  let total = 0;
+  for (let i = 0;i < digits.length; i++) {
+    let d = digits[digits.length - 1 - i] ?? 0;
+    if (i % 2 === 1) {
+      d *= 2;
+      if (d > 9)
+        d -= 9;
+    }
+    total += d;
+  }
+  return total % 10 === 0;
+}
+function ibanChOk(raw) {
+  const s = raw.replace(/[\s-]/g, "");
+  if (s.length !== 21 || !s.startsWith("CH") || !/^\d+$/.test(s.slice(2))) {
+    return false;
+  }
+  const rearranged = s.slice(4) + s.slice(0, 4);
+  let numeric = "";
+  for (const c of rearranged) {
+    numeric += c >= "A" && c <= "Z" ? String(c.charCodeAt(0) - 55) : c;
+  }
+  let rem = 0;
+  for (const ch of numeric) {
+    rem = (rem * 10 + Number(ch)) % 97;
+  }
+  return rem === 1;
+}
+function ahvOk(s) {
+  const digits = [];
+  for (const c of s) {
+    if (c >= "0" && c <= "9")
+      digits.push(Number(c));
+  }
+  if (digits.length !== 13)
+    return false;
+  if (digits[0] !== 7 || digits[1] !== 5 || digits[2] !== 6)
+    return false;
+  let total = 0;
+  for (let i = 0;i < 12; i++) {
+    total += (digits[i] ?? 0) * (i % 2 === 0 ? 1 : 3);
+  }
+  const check = (10 - total % 10) % 10;
+  return digits[12] === check;
+}
+function vatCheOk(s) {
+  const digits = [];
+  for (const c of s) {
+    if (c >= "0" && c <= "9")
+      digits.push(Number(c));
+  }
+  if (digits.length < 9)
+    return false;
+  const weights = [5, 4, 3, 2, 7, 6, 5, 4];
+  let total = 0;
+  for (let i = 0;i < 8; i++) {
+    total += (digits[i] ?? 0) * (weights[i] ?? 0);
+  }
+  let expected = 11 - total % 11;
+  if (expected === 11)
+    expected = 0;
+  else if (expected === 10)
+    return false;
+  return digits[8] === expected;
+}
+var REGEXES = [
+  {
+    label: "private_email",
+    pattern: /\b[\w._%+\-]+@[\w.\-]+\.[A-Za-z]{2,}\b/g
+  },
+  {
+    label: "private_url",
+    pattern: /https?:\/\/[^\s)>\]]+/g
+  },
+  {
+    label: "private_phone",
+    pattern: /(?:\+41|0041|0)\s?(?:\(0\)\s?)?\d{2}[\s\-/.]?\d{3}[\s\-/.]?\d{2}[\s\-/.]?\d{2}\b/g
+  },
+  {
+    label: "account_number",
+    pattern: /\bCH\d{2}(?:[\s-]?\d){17}\b/g,
+    validator: ibanChOk
+  },
+  {
+    label: "account_number",
+    pattern: /\b756\.\d{4}\.\d{4}\.\d{2}\b/g,
+    validator: ahvOk
+  },
+  {
+    label: "account_number",
+    pattern: /\b756\d{10}\b/g,
+    validator: ahvOk
+  },
+  {
+    label: "account_number",
+    pattern: /\bCHE-\d{3}\.\d{3}\.\d{3}(?:\s+(?:MWST|TVA|IVA))?\b/g,
+    validator: vatCheOk
+  },
+  {
+    label: "account_number",
+    pattern: /\b(?:\d[\s-]?){15,16}\d\b/g,
+    validator: luhnOk
+  },
+  {
+    label: "private_date",
+    pattern: /\b(?:\d{1,2}[./]\d{1,2}[./]\d{4}|\d{4}[./-]\d{1,2}[./-]\d{1,2})\b/g
+  },
+  {
+    label: "secret",
+    pattern: /\bsk-(?:proj-)?[A-Za-z0-9_\-]{20,}\b/g
+  },
+  {
+    label: "secret",
+    pattern: /\bghp_[A-Za-z0-9]{36}\b/g
+  },
+  {
+    label: "secret",
+    pattern: /\bAKIA[A-Z0-9]{16}\b/g
+  }
+];
+var URL_TRAIL_TRIM = '.,;:!?")>]';
+function trimUrl(text, start, end) {
+  while (end > start && URL_TRAIL_TRIM.includes(text[end - 1] ?? ""))
+    end--;
+  return [start, end];
+}
+function findRegexSpans(text) {
+  const candidates = [];
+  for (const { label, pattern, validator } of REGEXES) {
+    pattern.lastIndex = 0;
+    let m;
+    while ((m = pattern.exec(text)) !== null) {
+      let start = m.index;
+      let end = m.index + m[0].length;
+      if (label === "private_url")
+        [start, end] = trimUrl(text, start, end);
+      const value = text.slice(start, end);
+      if (!value.trim())
+        continue;
+      if (validator && !validator(value))
+        continue;
+      candidates.push({
+        start,
+        end,
+        label,
+        text: value,
+        score: 1
+      });
+    }
+  }
+  candidates.sort((a, b) => a.start !== b.start ? a.start - b.start : b.end - b.start - (a.end - a.start));
+  const out = [];
+  let lastEnd = -1;
+  for (const sp of candidates) {
+    if (sp.start < lastEnd)
+      continue;
+    out.push(sp);
+    lastEnd = sp.end;
+  }
+  return out;
+}
+function maskSpans(text, spans) {
+  if (spans.length === 0)
+    return text;
+  const chars = [...text];
+  for (const sp of spans) {
+    for (let i = sp.start;i < sp.end && i < chars.length; i++) {
+      chars[i] = " ";
+    }
+  }
+  return chars.join("");
+}
+
+class CompositeDetector {
+  model;
+  constructor(opts) {
+    if (!opts || !opts.model) {
+      throw new Error("CompositeDetector requires { model: Detector } — pass any object with " + "a .detect(text) method (e.g. new LocalDetector({...})).");
+    }
+    this.model = opts.model;
+  }
+  async detect(text, opts) {
+    if (!text)
+      return [];
+    const regexSpans = findRegexSpans(text);
+    const masked = maskSpans(text, regexSpans);
+    const modelSpans = await this.model.detect(masked, opts);
+    const out = [...regexSpans];
+    const regexRanges = regexSpans.map((s) => [s.start, s.end]);
+    for (const sp of modelSpans) {
+      const overlaps = regexRanges.some(([rs, re]) => sp.start < re && rs < sp.end);
+      if (overlaps)
+        continue;
+      out.push(sp);
+    }
+    out.sort((a, b) => a.start !== b.start ? a.start - b.start : b.end - b.start - (a.end - a.start));
+    return out;
+  }
+}
 // src/detectors/index.ts
 function defaultDetector() {
   const hasKey = typeof process !== "undefined" && Boolean(process.env?.GHEIM_API_KEY);

package/dist/esm/index.js

@@ -564,6 +564,214 @@ async function loadTransformersJs() {
     throw new Error("LocalDetector requires `@huggingface/transformers`. Install with: bun add @huggingface/transformers");
   }
 }
+// src/detectors/composite.ts
+function luhnOk(s) {
+  const digits = [];
+  for (const c of s) {
+    if (c >= "0" && c <= "9")
+      digits.push(Number(c));
+  }
+  if (digits.length < 13 || digits.length > 19)
+    return false;
+  let total = 0;
+  for (let i = 0;i < digits.length; i++) {
+    let d = digits[digits.length - 1 - i] ?? 0;
+    if (i % 2 === 1) {
+      d *= 2;
+      if (d > 9)
+        d -= 9;
+    }
+    total += d;
+  }
+  return total % 10 === 0;
+}
+function ibanChOk(raw) {
+  const s = raw.replace(/[\s-]/g, "");
+  if (s.length !== 21 || !s.startsWith("CH") || !/^\d+$/.test(s.slice(2))) {
+    return false;
+  }
+  const rearranged = s.slice(4) + s.slice(0, 4);
+  let numeric = "";
+  for (const c of rearranged) {
+    numeric += c >= "A" && c <= "Z" ? String(c.charCodeAt(0) - 55) : c;
+  }
+  let rem = 0;
+  for (const ch of numeric) {
+    rem = (rem * 10 + Number(ch)) % 97;
+  }
+  return rem === 1;
+}
+function ahvOk(s) {
+  const digits = [];
+  for (const c of s) {
+    if (c >= "0" && c <= "9")
+      digits.push(Number(c));
+  }
+  if (digits.length !== 13)
+    return false;
+  if (digits[0] !== 7 || digits[1] !== 5 || digits[2] !== 6)
+    return false;
+  let total = 0;
+  for (let i = 0;i < 12; i++) {
+    total += (digits[i] ?? 0) * (i % 2 === 0 ? 1 : 3);
+  }
+  const check = (10 - total % 10) % 10;
+  return digits[12] === check;
+}
+function vatCheOk(s) {
+  const digits = [];
+  for (const c of s) {
+    if (c >= "0" && c <= "9")
+      digits.push(Number(c));
+  }
+  if (digits.length < 9)
+    return false;
+  const weights = [5, 4, 3, 2, 7, 6, 5, 4];
+  let total = 0;
+  for (let i = 0;i < 8; i++) {
+    total += (digits[i] ?? 0) * (weights[i] ?? 0);
+  }
+  let expected = 11 - total % 11;
+  if (expected === 11)
+    expected = 0;
+  else if (expected === 10)
+    return false;
+  return digits[8] === expected;
+}
+var REGEXES = [
+  {
+    label: "private_email",
+    pattern: /\b[\w._%+\-]+@[\w.\-]+\.[A-Za-z]{2,}\b/g
+  },
+  {
+    label: "private_url",
+    pattern: /https?:\/\/[^\s)>\]]+/g
+  },
+  {
+    label: "private_phone",
+    pattern: /(?:\+41|0041|0)\s?(?:\(0\)\s?)?\d{2}[\s\-/.]?\d{3}[\s\-/.]?\d{2}[\s\-/.]?\d{2}\b/g
+  },
+  {
+    label: "account_number",
+    pattern: /\bCH\d{2}(?:[\s-]?\d){17}\b/g,
+    validator: ibanChOk
+  },
+  {
+    label: "account_number",
+    pattern: /\b756\.\d{4}\.\d{4}\.\d{2}\b/g,
+    validator: ahvOk
+  },
+  {
+    label: "account_number",
+    pattern: /\b756\d{10}\b/g,
+    validator: ahvOk
+  },
+  {
+    label: "account_number",
+    pattern: /\bCHE-\d{3}\.\d{3}\.\d{3}(?:\s+(?:MWST|TVA|IVA))?\b/g,
+    validator: vatCheOk
+  },
+  {
+    label: "account_number",
+    pattern: /\b(?:\d[\s-]?){15,16}\d\b/g,
+    validator: luhnOk
+  },
+  {
+    label: "private_date",
+    pattern: /\b(?:\d{1,2}[./]\d{1,2}[./]\d{4}|\d{4}[./-]\d{1,2}[./-]\d{1,2})\b/g
+  },
+  {
+    label: "secret",
+    pattern: /\bsk-(?:proj-)?[A-Za-z0-9_\-]{20,}\b/g
+  },
+  {
+    label: "secret",
+    pattern: /\bghp_[A-Za-z0-9]{36}\b/g
+  },
+  {
+    label: "secret",
+    pattern: /\bAKIA[A-Z0-9]{16}\b/g
+  }
+];
+var URL_TRAIL_TRIM = '.,;:!?")>]';
+function trimUrl(text, start, end) {
+  while (end > start && URL_TRAIL_TRIM.includes(text[end - 1] ?? ""))
+    end--;
+  return [start, end];
+}
+function findRegexSpans(text) {
+  const candidates = [];
+  for (const { label, pattern, validator } of REGEXES) {
+    pattern.lastIndex = 0;
+    let m;
+    while ((m = pattern.exec(text)) !== null) {
+      let start = m.index;
+      let end = m.index + m[0].length;
+      if (label === "private_url")
+        [start, end] = trimUrl(text, start, end);
+      const value = text.slice(start, end);
+      if (!value.trim())
+        continue;
+      if (validator && !validator(value))
+        continue;
+      candidates.push({
+        start,
+        end,
+        label,
+        text: value,
+        score: 1
+      });
+    }
+  }
+  candidates.sort((a, b) => a.start !== b.start ? a.start - b.start : b.end - b.start - (a.end - a.start));
+  const out = [];
+  let lastEnd = -1;
+  for (const sp of candidates) {
+    if (sp.start < lastEnd)
+      continue;
+    out.push(sp);
+    lastEnd = sp.end;
+  }
+  return out;
+}
+function maskSpans(text, spans) {
+  if (spans.length === 0)
+    return text;
+  const chars = [...text];
+  for (const sp of spans) {
+    for (let i = sp.start;i < sp.end && i < chars.length; i++) {
+      chars[i] = " ";
+    }
+  }
+  return chars.join("");
+}
+
+class CompositeDetector {
+  model;
+  constructor(opts) {
+    if (!opts || !opts.model) {
+      throw new Error("CompositeDetector requires { model: Detector } — pass any object with " + "a .detect(text) method (e.g. new LocalDetector({...})).");
+    }
+    this.model = opts.model;
+  }
+  async detect(text, opts) {
+    if (!text)
+      return [];
+    const regexSpans = findRegexSpans(text);
+    const masked = maskSpans(text, regexSpans);
+    const modelSpans = await this.model.detect(masked, opts);
+    const out = [...regexSpans];
+    const regexRanges = regexSpans.map((s) => [s.start, s.end]);
+    for (const sp of modelSpans) {
+      const overlaps = regexRanges.some(([rs, re]) => sp.start < re && rs < sp.end);
+      if (overlaps)
+        continue;
+      out.push(sp);
+    }
+    out.sort((a, b) => a.start !== b.start ? a.start - b.start : b.end - b.start - (a.end - a.start));
+    return out;
+  }
+}
 // src/detectors/index.ts
 function defaultDetector() {
   const hasKey = typeof process !== "undefined" && Boolean(process.env?.GHEIM_API_KEY);
@@ -618,7 +826,7 @@ async function* deanonymizeStream(chunks, session) {
 }
 
 // src/index.ts
-var VERSION = "0.1.2";
+var VERSION = "0.1.3";
 export {
   renderSentinel,
   parseSentinel,
@@ -638,5 +846,6 @@ export {
   DEFAULT_MODEL as REMOTE_DEFAULT_MODEL,
   LocalDetector,
   LABEL_TO_TAG,
-  DEFAULT_BASE_URL
+  DEFAULT_BASE_URL,
+  CompositeDetector
 };

package/dist/esm/openai/index.js

@@ -500,6 +500,214 @@ async function loadTransformersJs() {
     throw new Error("LocalDetector requires `@huggingface/transformers`. Install with: bun add @huggingface/transformers");
   }
 }
+// src/detectors/composite.ts
+function luhnOk(s) {
+  const digits = [];
+  for (const c of s) {
+    if (c >= "0" && c <= "9")
+      digits.push(Number(c));
+  }
+  if (digits.length < 13 || digits.length > 19)
+    return false;
+  let total = 0;
+  for (let i = 0;i < digits.length; i++) {
+    let d = digits[digits.length - 1 - i] ?? 0;
+    if (i % 2 === 1) {
+      d *= 2;
+      if (d > 9)
+        d -= 9;
+    }
+    total += d;
+  }
+  return total % 10 === 0;
+}
+function ibanChOk(raw) {
+  const s = raw.replace(/[\s-]/g, "");
+  if (s.length !== 21 || !s.startsWith("CH") || !/^\d+$/.test(s.slice(2))) {
+    return false;
+  }
+  const rearranged = s.slice(4) + s.slice(0, 4);
+  let numeric = "";
+  for (const c of rearranged) {
+    numeric += c >= "A" && c <= "Z" ? String(c.charCodeAt(0) - 55) : c;
+  }
+  let rem = 0;
+  for (const ch of numeric) {
+    rem = (rem * 10 + Number(ch)) % 97;
+  }
+  return rem === 1;
+}
+function ahvOk(s) {
+  const digits = [];
+  for (const c of s) {
+    if (c >= "0" && c <= "9")
+      digits.push(Number(c));
+  }
+  if (digits.length !== 13)
+    return false;
+  if (digits[0] !== 7 || digits[1] !== 5 || digits[2] !== 6)
+    return false;
+  let total = 0;
+  for (let i = 0;i < 12; i++) {
+    total += (digits[i] ?? 0) * (i % 2 === 0 ? 1 : 3);
+  }
+  const check = (10 - total % 10) % 10;
+  return digits[12] === check;
+}
+function vatCheOk(s) {
+  const digits = [];
+  for (const c of s) {
+    if (c >= "0" && c <= "9")
+      digits.push(Number(c));
+  }
+  if (digits.length < 9)
+    return false;
+  const weights = [5, 4, 3, 2, 7, 6, 5, 4];
+  let total = 0;
+  for (let i = 0;i < 8; i++) {
+    total += (digits[i] ?? 0) * (weights[i] ?? 0);
+  }
+  let expected = 11 - total % 11;
+  if (expected === 11)
+    expected = 0;
+  else if (expected === 10)
+    return false;
+  return digits[8] === expected;
+}
+var REGEXES = [
+  {
+    label: "private_email",
+    pattern: /\b[\w._%+\-]+@[\w.\-]+\.[A-Za-z]{2,}\b/g
+  },
+  {
+    label: "private_url",
+    pattern: /https?:\/\/[^\s)>\]]+/g
+  },
+  {
+    label: "private_phone",
+    pattern: /(?:\+41|0041|0)\s?(?:\(0\)\s?)?\d{2}[\s\-/.]?\d{3}[\s\-/.]?\d{2}[\s\-/.]?\d{2}\b/g
+  },
+  {
+    label: "account_number",
+    pattern: /\bCH\d{2}(?:[\s-]?\d){17}\b/g,
+    validator: ibanChOk
+  },
+  {
+    label: "account_number",
+    pattern: /\b756\.\d{4}\.\d{4}\.\d{2}\b/g,
+    validator: ahvOk
+  },
+  {
+    label: "account_number",
+    pattern: /\b756\d{10}\b/g,
+    validator: ahvOk
+  },
+  {
+    label: "account_number",
+    pattern: /\bCHE-\d{3}\.\d{3}\.\d{3}(?:\s+(?:MWST|TVA|IVA))?\b/g,
+    validator: vatCheOk
+  },
+  {
+    label: "account_number",
+    pattern: /\b(?:\d[\s-]?){15,16}\d\b/g,
+    validator: luhnOk
+  },
+  {
+    label: "private_date",
+    pattern: /\b(?:\d{1,2}[./]\d{1,2}[./]\d{4}|\d{4}[./-]\d{1,2}[./-]\d{1,2})\b/g
+  },
+  {
+    label: "secret",
+    pattern: /\bsk-(?:proj-)?[A-Za-z0-9_\-]{20,}\b/g
+  },
+  {
+    label: "secret",
+    pattern: /\bghp_[A-Za-z0-9]{36}\b/g
+  },
+  {
+    label: "secret",
+    pattern: /\bAKIA[A-Z0-9]{16}\b/g
+  }
+];
+var URL_TRAIL_TRIM = '.,;:!?")>]';
+function trimUrl(text, start, end) {
+  while (end > start && URL_TRAIL_TRIM.includes(text[end - 1] ?? ""))
+    end--;
+  return [start, end];
+}
+function findRegexSpans(text) {
+  const candidates = [];
+  for (const { label, pattern, validator } of REGEXES) {
+    pattern.lastIndex = 0;
+    let m;
+    while ((m = pattern.exec(text)) !== null) {
+      let start = m.index;
+      let end = m.index + m[0].length;
+      if (label === "private_url")
+        [start, end] = trimUrl(text, start, end);
+      const value = text.slice(start, end);
+      if (!value.trim())
+        continue;
+      if (validator && !validator(value))
+        continue;
+      candidates.push({
+        start,
+        end,
+        label,
+        text: value,
+        score: 1
+      });
+    }
+  }
+  candidates.sort((a, b) => a.start !== b.start ? a.start - b.start : b.end - b.start - (a.end - a.start));
+  const out = [];
+  let lastEnd = -1;
+  for (const sp of candidates) {
+    if (sp.start < lastEnd)
+      continue;
+    out.push(sp);
+    lastEnd = sp.end;
+  }
+  return out;
+}
+function maskSpans(text, spans) {
+  if (spans.length === 0)
+    return text;
+  const chars = [...text];
+  for (const sp of spans) {
+    for (let i = sp.start;i < sp.end && i < chars.length; i++) {
+      chars[i] = " ";
+    }
+  }
+  return chars.join("");
+}
+
+class CompositeDetector {
+  model;
+  constructor(opts) {
+    if (!opts || !opts.model) {
+      throw new Error("CompositeDetector requires { model: Detector } — pass any object with " + "a .detect(text) method (e.g. new LocalDetector({...})).");
+    }
+    this.model = opts.model;
+  }
+  async detect(text, opts) {
+    if (!text)
+      return [];
+    const regexSpans = findRegexSpans(text);
+    const masked = maskSpans(text, regexSpans);
+    const modelSpans = await this.model.detect(masked, opts);
+    const out = [...regexSpans];
+    const regexRanges = regexSpans.map((s) => [s.start, s.end]);
+    for (const sp of modelSpans) {
+      const overlaps = regexRanges.some(([rs, re]) => sp.start < re && rs < sp.end);
+      if (overlaps)
+        continue;
+      out.push(sp);
+    }
+    out.sort((a, b) => a.start !== b.start ? a.start - b.start : b.end - b.start - (a.end - a.start));
+    return out;
+  }
+}
 // src/detectors/index.ts
 function defaultDetector() {
   const hasKey = typeof process !== "undefined" && Boolean(process.env?.GHEIM_API_KEY);

package/dist/types/detectors/composite.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Composite detector: regex front-end + model on the remainder.
+ *
+ * Production-ready Swiss PII detector that combines two complementary
+ * strategies — a port of the Python sibling
+ * (`gheim.detectors.composite.CompositeDetector`) with parity-tested
+ * regexes and checksum validators.
+ *
+ * 1. Deterministic regex front-end for structured PII categories where
+ *    shape is unambiguous and checksums verify identity:
+ *    - IBAN-CH (mod-97-10), AHV (EAN-13 mod-10), VAT-CHE (mod-11-10),
+ *      Visa/Mastercard (Luhn)
+ *    - Email, URL, Swiss phone (+41 / 0041 / 0...), explicit dates
+ *      (DD.MM.YYYY, YYYY-MM-DD)
+ *    - API tokens (sk-, ghp_, AKIA...)
+ *
+ *    Spans found here are "trusted" — checksums catch most surface-form
+ *    imitations; the model is never asked.
+ *
+ * 2. The fine-tuned model on whatever's left after regex masking.
+ *    Persons, addresses, and edge-case dates fall here. The model's
+ *    "single-category mode" failure (where an IBAN/phone-shaped
+ *    sequence suppresses person/date detection in the same input) is
+ *    bypassed because the regex already absorbed those tokens — the
+ *    model sees them as whitespace.
+ *
+ * Wraps the same `Detector` interface (`detect(text) → Span[]`) as
+ * `LocalDetector` so it drops into any code path that already accepts a
+ * detector.
+ */
+import type { Detector, Span } from "./base.ts";
+/** Options for {@link CompositeDetector}. */
+export interface CompositeDetectorOptions {
+    /** Inner detector — usually a {@link LocalDetector}. Anything with
+     *  a `detect(text) → Promise<Span[]>` method works. */
+    model: Detector;
+}
+/** Regex front-end (with checksum validation) + model on the remainder.
+ *
+ * @example
+ * import { LocalDetector, CompositeDetector } from "gheim";
+ * const composite = new CompositeDetector({
+ *   model: new LocalDetector({ dtype: "q8" }),
+ * });
+ * const spans = await composite.detect(swissLetter);
+ * // → IBAN/phone/email caught by regex (checksum-validated);
+ * //   person/address/dates caught by the model on the masked remainder.
+ */
+export declare class CompositeDetector implements Detector {
+    readonly model: Detector;
+    constructor(opts: CompositeDetectorOptions);
+    /** Two-pass detection: regex first (with checksum), then model on
+     *  the masked remainder. Returns a single overlap-resolved span list. */
+    detect(text: string, opts?: {
+        model?: string;
+    }): Promise<Span[]>;
+}
+//# sourceMappingURL=composite.d.ts.map

package/dist/types/detectors/composite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composite.d.ts","sourceRoot":"","sources":["../../../src/detectors/composite.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAiNhD,6CAA6C;AAC7C,MAAM,WAAW,wBAAwB;IACvC;2DACuD;IACvD,KAAK,EAAE,QAAQ,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,iBAAkB,YAAW,QAAQ;IAChD,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;gBAEb,IAAI,EAAE,wBAAwB;IAU1C;6EACyE;IACnE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;CAmBvE"}

package/dist/types/detectors/index.d.ts

@@ -3,6 +3,8 @@ export { DEFAULT_BASE_URL, DEFAULT_MODEL as REMOTE_DEFAULT_MODEL, RemoteDetector
 export type { RemoteDetectorOptions } from "./remote.ts";
 export { LocalDetector } from "./local.ts";
 export type { LocalDetectorOptions, LocalDetectorLoadEvent } from "./local.ts";
+export { CompositeDetector } from "./composite.ts";
+export type { CompositeDetectorOptions } from "./composite.ts";
 import type { Detector } from "./base.ts";
 /** Pick a reasonable default: remote if `GHEIM_API_KEY` is set in env, else local. */
 export declare function defaultDetector(): Detector;

package/dist/types/detectors/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/detectors/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EACL,gBAAgB,EAChB,aAAa,IAAI,oBAAoB,EACrC,cAAc,GACf,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,YAAY,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAE/E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAI1C,sFAAsF;AACtF,wBAAgB,eAAe,IAAI,QAAQ,CAI1C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/detectors/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EACL,gBAAgB,EAChB,aAAa,IAAI,oBAAoB,EACrC,cAAc,GACf,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,YAAY,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAC/E,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,YAAY,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAE/D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAI1C,sFAAsF;AACtF,wBAAgB,eAAe,IAAI,QAAQ,CAI1C"}

package/dist/types/index.d.ts

@@ -13,11 +13,11 @@ export { LABEL_TO_TAG, SENTINEL_RE, isPossibleSentinelPrefix, labelTag, parseSen
 export type { Sentinel } from "./core/sentinels.ts";
 export { StreamDeanonymizer } from "./core/stream.ts";
 export type { Detector, Span } from "./detectors/base.ts";
-export { DEFAULT_BASE_URL, REMOTE_DEFAULT_MODEL, RemoteDetector, LocalDetector, defaultDetector, } from "./detectors/index.ts";
-export type { RemoteDetectorOptions, LocalDetectorOptions, LocalDetectorLoadEvent, } from "./detectors/index.ts";
+export { DEFAULT_BASE_URL, REMOTE_DEFAULT_MODEL, RemoteDetector, LocalDetector, CompositeDetector, defaultDetector, } from "./detectors/index.ts";
+export type { RemoteDetectorOptions, LocalDetectorOptions, LocalDetectorLoadEvent, CompositeDetectorOptions, } from "./detectors/index.ts";
 export { anonymizeMessages, anonymizeText, deanonymizeStream, deanonymizeText, } from "./plain.ts";
 export type { ChatMessage } from "./plain.ts";
-export declare const VERSION = "0.1.2";
+export declare const VERSION = "0.1.3";
 export { mergeAdjacent } from "./core/session.ts";
 export type { MergedSpan } from "./core/session.ts";
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC5C,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACpE,OAAO,EACL,YAAY,EACZ,WAAW,EACX,wBAAwB,EACxB,QAAQ,EACR,aAAa,EACb,cAAc,GACf,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,cAAc,EACd,aAAa,EACb,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAK9C,eAAO,MAAM,OAAO,UAAU,CAAC;AAE/B,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC5C,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACpE,OAAO,EACL,YAAY,EACZ,WAAW,EACX,wBAAwB,EACxB,QAAQ,EACR,aAAa,EACb,cAAc,GACf,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAK9C,eAAO,MAAM,OAAO,UAAU,CAAC;AAE/B,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gheim",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "PII round-trip for LLM APIs: anonymize before the request, de-anonymize the stream on the way back.",
   "license": "Apache-2.0",
   "author": "Joel Barmettler <joel.barmettler@gmail.com>",