@desert-ant-labs/redact 0.2.0

package/LICENSE.md

@@ -0,0 +1,136 @@
+# Desert Ant Labs Source-Available License
+
+Version 1.0 · 2026-06-15
+
+Copyright © 2026 Studio Company B.V., trading as Desert Ant Labs (`desertant.ai`).
+
+This license governs Your use of the software, model weights, datasets, documentation, and associated assets in this repository (collectively, the **"Licensed Materials"**). It is a **source-available license intended for professional and business use**; it is not an OSI-approved open-source license. The rights granted here are subject to a per-Model usage cap and the other terms set out below.
+
+## Definitions
+
+- **"Desert Ant Labs"** (also "We", "Us", "Our") — Studio Company B.V., a private limited liability company (*besloten vennootschap*) incorporated under the laws of the Netherlands, with statutory seat in Amsterdam, registered with the Dutch Chamber of Commerce (KvK) under number **81228112**, trading as Desert Ant Labs.
+- **"Model"** — a set of trained weights published by Desert Ant Labs under a single HuggingFace repository (for example, `huggingface.co/desert-ant-labs/eye`). Each Model is a distinct work under this license.
+- **"Monthly Active User"** or **"MAU"** — a unique end user who interacts with a feature powered by a Model during a calendar month. Internal use by Your own employees and contractors does not count.
+- **"You"** — the individual or legal entity exercising rights under this license.
+
+## 0. Acceptance
+
+By downloading, accessing, using, copying, modifying, or distributing the Licensed Materials, You agree to be bound by this license. If You do not agree, You may not use the Licensed Materials.
+
+## 1. Grant
+
+Subject to Your continued compliance with this license, Desert Ant Labs grants You a worldwide, royalty-free, non-exclusive, non-transferable, non-sublicensable license to use, reproduce, modify, and distribute the Licensed Materials.
+
+## 2. Free-tier use
+
+You may use the Licensed Materials free of charge, including for commercial purposes, subject to the following per-Model threshold:
+
+> **For each Desert Ant Labs Model that Your products incorporate, the aggregate Monthly Active Users across all Your products must not exceed 100,000 in any calendar month.**
+
+The threshold applies independently to each Model. Two Models at 50,000 MAU each do not combine into 100,000 MAU; each is independently within its own free-tier limit.
+
+If a repository contains only software (no trained Model weights), no MAU threshold applies to that software on its own. The threshold attaches to the Models the software is used with.
+
+## 3. Research and academic use
+
+Use of the Licensed Materials for non-commercial scientific research and academic publications is exempt from the MAU threshold in Section 2, provided that any resulting publication credits "Desert Ant Labs" and links to the relevant Model repository.
+
+## 4. Commercial license
+
+If Your aggregate MAU for any Model exceeds 100,000 (or You expect it to within the next calendar month), You must obtain a commercial license from Desert Ant Labs before continuing to distribute or operate any product that incorporates that Model. A commercial license covers only the Models named in it; other Models remain under the free tier subject to their own thresholds.
+
+Contact: <licensing@desertant.ai>.
+
+## 5. Patent grant
+
+Each contributor to the Licensed Materials grants You a perpetual, worldwide, non-exclusive, royalty-free, irrevocable (except as stated in this Section) patent license to make, use, sell, offer to sell, and import the Licensed Materials, where such license applies only to those patent claims licensable by that contributor that are necessarily infringed by the Licensed Materials.
+
+**If You institute patent litigation against any entity** (including a cross-claim or counterclaim in a lawsuit) alleging that the Licensed Materials infringe a patent, **all patent licenses granted to You under this license terminate as of the date such litigation is filed.**
+
+## 6. Restrictions
+
+You may not:
+
+1. Sell, sublicense, or otherwise distribute the Licensed Materials themselves, or any substantially unmodified derivative of them, as a standalone product or hosted service.
+2. Use the Licensed Materials to train, distill, fine-tune, or otherwise derive a model that You release or distribute under any license more permissive than this license, including any OSI-approved open-source license. Internal research, personal fine-tuning, and use of derivative models that remain under this license are not restricted.
+3. Remove or alter the copyright, license, attribution, or third-party notices in the Licensed Materials.
+
+You may freely embed the Licensed Materials in Your own product, subject to Section 2 and the rest of this license.
+
+## 7. Attribution
+
+You must retain this LICENSE file and the copyright notice in all copies and substantial portions of the Licensed Materials. Where Your product surfaces acknowledgements, third-party notices, or "About" / "Credits" screens, please credit **"Desert Ant Labs (`desertant.ai`)"**.
+
+## 8. Modifications
+
+You may modify the Licensed Materials. If You distribute modified Licensed Materials, You must:
+
+(a) include a prominent notice stating that You have modified them, with the date of modification; and
+(b) ensure that Your distributed modifications are licensed under this license.
+
+This license governs the Licensed Materials and modifications to them. Applications and products that merely incorporate, link to, or call the Licensed Materials are Your own work; their structure, source, and license are not constrained by this license, subject only to Sections 2, 6, and 7.
+
+## 9. Reporting
+
+To enable Desert Ant Labs to administer the free tier, You agree:
+
+(a) to maintain reasonable records of Your aggregate MAU per Model; and
+(b) upon written request from Desert Ant Labs, to provide a reasonable summary of those records sufficient to confirm compliance with Section 2. Such requests will be made no more than once per calendar year per licensee, except in the case of a reasonable, specific suspicion of breach.
+
+You are encouraged — but not required — to notify Desert Ant Labs at <licensing@desertant.ai> when Your aggregate MAU for any Model first exceeds 80,000.
+
+## 10. Trademarks
+
+This license does not grant You any right to use the trade names, trademarks, service marks, or product names of Desert Ant Labs, except for the limited attribution use specified in Section 7. All goodwill arising from such attribution use inures to the benefit of Desert Ant Labs.
+
+## 11. Third-party components
+
+The Licensed Materials may include or derive from components licensed by third parties. Those components remain subject to their own licenses; nothing in this license overrides those terms. Notices for such components are provided in the model card or in a `THIRD_PARTY_NOTICES.md` file alongside the Licensed Materials.
+
+## 12. Termination
+
+This license terminates automatically and immediately upon any of the following:
+
+(a) Your aggregate MAU for any Model exceeds 100,000 and You do not obtain a commercial license within thirty (30) days;
+(b) Your breach of Section 6 (Restrictions); or
+(c) Your institution of patent litigation as described in Section 5.
+
+For any other curable breach, Desert Ant Labs will provide written notice; if the breach is not cured within thirty (30) days of receipt of that notice, this license terminates as of the date the notice was sent.
+
+Upon termination, You must cease using and distributing the Licensed Materials. Sections 7 (Attribution, with respect to copies already in the field), 10 (Trademarks), 11 (Third-Party Components), 13 (No Warranty), 14 (Limitation of Liability), and 15 (Governing Law) survive termination.
+
+## 13. No warranty
+
+THE LICENSED MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. Desert Ant Labs makes no representation that the Licensed Materials are error-free, secure, or suitable for any particular use.
+
+## 14. Limitation of liability
+
+IN NO EVENT SHALL DESERT ANT LABS BE LIABLE FOR ANY INDIRECT, INCIDENTAL, CONSEQUENTIAL, SPECIAL, OR EXEMPLARY DAMAGES (INCLUDING LOST PROFITS, LOSS OF DATA, OR BUSINESS INTERRUPTION) ARISING FROM OR IN CONNECTION WITH THE LICENSED MATERIALS, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+DESERT ANT LABS' TOTAL CUMULATIVE LIABILITY UNDER OR IN CONNECTION WITH THIS LICENSE SHALL NOT EXCEED THE GREATER OF (A) ONE HUNDRED EUROS (€100) OR (B) THE TOTAL FEES PAID BY YOU TO DESERT ANT LABS UNDER A SEPARATE COMMERCIAL LICENSE IN THE TWELVE (12) MONTHS PRECEDING THE CLAIM.
+
+Nothing in this license limits or excludes liability to the extent such limitation or exclusion is not permitted by applicable mandatory law, including liability for willful misconduct (*opzet*) or gross negligence (*bewuste roekeloosheid*) and any mandatory provision of Dutch consumer-protection law.
+
+## 15. Governing law and jurisdiction
+
+This license is governed by the laws of the Netherlands, without regard to its conflict-of-laws provisions. The competent courts of Amsterdam, the Netherlands, have exclusive jurisdiction over any dispute arising under or in connection with this license, subject to mandatory provisions of applicable consumer-protection law.
+
+The United Nations Convention on Contracts for the International Sale of Goods (CISG, 1980) does not apply to this license.
+
+## 16. Miscellaneous
+
+(a) **Severability.** If any provision of this license is held unenforceable by a court of competent jurisdiction, the remaining provisions remain in full force and effect, and the unenforceable provision shall be interpreted to give effect to its intent to the greatest extent permitted by law.
+
+(b) **No waiver.** Failure or delay by Desert Ant Labs to enforce any right under this license is not a waiver of that right.
+
+(c) **Assignment.** You may not assign this license without Desert Ant Labs' prior written consent. Desert Ant Labs may freely assign this license to a successor in interest. This license binds and benefits each party's successors and permitted assigns.
+
+(d) **Entire agreement.** This license, together with any separate commercial license referenced in Section 4, is the entire agreement between You and Desert Ant Labs regarding the Licensed Materials and supersedes all prior agreements on the same subject matter.
+
+(e) **Language.** The authoritative version of this license is in English. Any translation is for convenience only; in the event of any conflict, the English version controls.
+
+---
+
+Commercial licensing inquiries: <licensing@desertant.ai>.
+
+© 2026 Studio Company B.V., trading as Desert Ant Labs. Statutory seat: Amsterdam, the Netherlands. KvK: **81228112**.

package/README.md

@@ -0,0 +1,143 @@
+# @desert-ant-labs/redact
+
+On-device multilingual PII redaction for JavaScript and TypeScript. Detects and
+masks personal data (names, addresses, emails, phone numbers, cards, IBANs,
+national IDs, VAT numbers and more) in text across **all 24 official EU
+languages** (Latin, Greek and Cyrillic scripts). Runs in Node and the browser via
+[transformers.js](https://github.com/huggingface/transformers.js); the text never
+leaves the device.
+
+```js
+import { Redact } from "@desert-ant-labs/redact";
+
+const redact = await Redact.load();
+const r = await redact.redaction("Email Anna Kovács at anna@example.hu.");
+
+r.redactedText;           // "Email [GIVEN_NAME_1] [SURNAME_1] at [EMAIL_1]."
+r.items[0].original;      // "Anna"
+r.restore(r.redactedText); // back to the original
+```
+
+A tiny 6-layer BIOES token classifier handles contextual PII (names, streets,
+messy natural-language data) while a dependency-free deterministic layer owns the
+structured fields with real validation (Luhn cards, ISO-13616 IBANs, checksum-
+validated national IDs for all 24 EU countries, all 27 EU VAT numbers, IMEI, and
+per-country driving licences). It mirrors the Python training pipeline and the
+Swift SDK span-for-span.
+
+## Install
+
+```sh
+npm install @desert-ant-labs/redact
+```
+
+The model (int8 ONNX, ~23 MB) and tokenizer are fetched from the
+[`desert-ant-labs/redact`](https://huggingface.co/desert-ant-labs/redact) Hugging
+Face repo on first load and cached locally (on disk in Node, in Cache Storage in
+the browser).
+
+## Usage
+
+Create one `Redact` and reuse it. The model loads lazily on first call.
+
+### Redact and restore (LLM round-trip)
+
+Mask PII to unique placeholders, hand the placeholdered text to an LLM or any
+external service, then fill the originals back in on-device. The sensitive values
+never leave the machine.
+
+```js
+const r = await redact.redaction(userText);
+// r.redactedText: "Email [EMAIL_1] and [EMAIL_2] about [BANK_ACCOUNT_1]."
+
+const reply = await myLLM.rewrite(r.redactedText);   // sees only placeholders
+const final = r.restore(reply);                       // originals filled back in
+```
+
+Placeholders are numbered per category (`[EMAIL_1]`, `[EMAIL_2]`, ...), so two
+emails never collapse into one and restoration is order-independent. Instruct
+your LLM to keep the `[LABEL_N]` tokens verbatim.
+
+### Inspect detections
+
+```js
+const r = await redact.redaction(text);
+for (const item of r.items) {
+  console.log(item.label, item.original, item.confidence, item.start, item.end);
+}
+```
+
+### Filter by category
+
+```js
+const r = await redact.redaction(text, { labels: ["EMAIL", "PHONE", "CREDIT_CARD"] });
+```
+
+### Just the spans
+
+```js
+const spans = await redact.detect(text); // [{ start, end, label }]
+```
+
+### Module-level convenience
+
+```js
+import { redaction, detect, env } from "@desert-ant-labs/redact";
+
+env.revision = "v0.2.0";                       // pin a model revision (optional)
+const r = await redaction("Call +49 30 1234567"); // model loaded + cached lazily
+```
+
+## API
+
+```ts
+class Redact {
+  static load(options?: LoadOptions): Promise<Redact>;
+  redaction(text: string, options?: Options): Promise<Redaction>;
+  detect(text: string, options?: Options): Promise<Span[]>;
+}
+
+interface Options {
+  minimumConfidence?: number;   // neural threshold, default 0.6
+  labels?: Iterable<string>;    // restrict categories; omit for all
+}
+
+interface Redaction {
+  redactedText: string;         // "[LABEL_N]" placeholders
+  items: RedactionItem[];       // { label, original, placeholder, confidence, start, end }
+  restore(processed: string): string;
+}
+
+interface LoadOptions {
+  repo?: string;        // default "desert-ant-labs/redact"
+  revision?: string;    // default "v0.2.0"
+  localPath?: string;   // load from a local dir instead of the Hub
+  useCache?: boolean;   // default true
+  cacheDir?: string;    // on-disk cache dir (Node)
+  dtype?: string;       // transformers.js weight dtype, default "fp32"
+}
+```
+
+## Categories
+
+`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`, and `IMEI` (deterministic-only).
+
+## Example
+
+A tiny browser demo is in [`Examples/RedactExample`](./Examples/RedactExample):
+`cd Examples/RedactExample && node server.js`, then open the printed URL and type
+some text.
+
+## Other platforms
+
+- **Swift (iOS/macOS/tvOS/visionOS):** [`redact-swift`](https://github.com/Desert-Ant-Labs/redact-swift)
+- **Model + weights + card:** [`desert-ant-labs/redact`](https://huggingface.co/desert-ant-labs/redact)
+
+## License
+
+[Desert Ant Labs Source-Available License](https://license.desertant.ai/1.0). Free
+for most apps; a commercial license is required at scale. Full terms are in
+[`LICENSE.md`](./LICENSE.md). Licensing: <licensing@desertant.ai>.

package/dist/deterministic.d.ts

@@ -0,0 +1,4 @@
+import type { Span } from "./types.js";
+declare const OWNED: Set<string>;
+export declare function deterministicDetect(text: string, enabled?: Iterable<string>): Span[];
+export { OWNED as OWNED_LABELS };