@framers/agentos 0.1.55 → 0.1.56

package/dist/extensions/packs/pii-redaction/EntityMerger.js

@@ -0,0 +1,263 @@
+/**
+ * @file EntityMerger.ts
+ * @description Post-processing step that de-duplicates, filters, and merges
+ * {@link PiiEntity} spans emitted by the multi-tier detection pipeline.
+ *
+ * When multiple recognisers (regex, NER, LLM judge) run over the same text
+ * they frequently emit overlapping or duplicate spans.  This module resolves
+ * those conflicts deterministically so that downstream redaction always
+ * receives a clean, non-overlapping, sorted list of entities.
+ *
+ * ## Processing pipeline
+ * 1. **Denylist boost** — entities whose text matches a denylist entry are
+ *    promoted to score `1.0`, guaranteeing they survive threshold filtering.
+ * 2. **Allowlist filter** — entities whose text matches an allowlist entry are
+ *    unconditionally removed before any other processing.
+ * 3. **Sort** — remaining entities are sorted by start offset; ties are broken
+ *    by span length descending so that longer (more specific) spans are
+ *    processed first in the overlap-resolution pass.
+ * 4. **Overlap resolution** — a single-pass scan collapses overlapping and
+ *    adjacent spans into the best representative entity (details below).
+ * 5. **Threshold filter** — entities whose final score is below
+ *    `confidenceThreshold` are removed.
+ * 6. **Final sort** — output is sorted by start offset for stable iteration.
+ *
+ * @module pii-redaction/EntityMerger
+ */
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Returns `true` when the two entities overlap or one is fully contained
+ * within the other.
+ *
+ * Two spans overlap when `a.start < b.end && b.start < a.end` (the standard
+ * half-open interval overlap test).
+ *
+ * @param a - First entity.
+ * @param b - Second entity (must have `start >= a.start` after sorting).
+ */
+function overlaps(a, b) {
+    return a.start < b.end && b.start < a.end;
+}
+/**
+ * Returns `true` when entity `b` is fully contained within entity `a`
+ * (i.e. `a` is a superset span of `b`).
+ *
+ * @param a - The candidate superset entity.
+ * @param b - The candidate subset entity.
+ */
+function isSubset(a, b) {
+    return a.start <= b.start && a.end >= b.end;
+}
+/**
+ * Returns the length in UTF-16 code units of an entity span.
+ *
+ * @param entity - Entity whose span length to compute.
+ */
+function spanLength(entity) {
+    return entity.end - entity.start;
+}
+/**
+ * Creates a merged entity from two adjacent (or near-adjacent) entities of
+ * the same type, bridging any gap between them with the corresponding
+ * characters from the original text.
+ *
+ * The merged entity inherits the **maximum** score of the two inputs and the
+ * `source` from the higher-scoring input (first one wins on a tie).
+ *
+ * @param a    - The earlier (lower start offset) entity.
+ * @param b    - The later entity.
+ * @param text - The original full input text used to fill the gap chars.
+ * @returns A new {@link PiiEntity} spanning from `a.start` to `b.end`.
+ */
+function mergeAdjacent(a, b, text) {
+    // The merged text is the contiguous slice of the original string that covers
+    // both spans, including any gap characters between them.
+    const mergedText = text.slice(a.start, b.end);
+    const mergedScore = Math.max(a.score, b.score);
+    // Preserve the source of the higher-confidence detector; tie goes to `a`.
+    const mergedSource = a.score >= b.score ? a.source : b.source;
+    return {
+        entityType: a.entityType,
+        text: mergedText,
+        start: a.start,
+        end: b.end,
+        score: mergedScore,
+        source: mergedSource,
+        // Merge metadata objects shallowly; later keys overwrite earlier ones.
+        metadata: a.metadata || b.metadata
+            ? { ...(a.metadata ?? {}), ...(b.metadata ?? {}) }
+            : undefined,
+    };
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Merges a raw list of {@link PiiEntity} detections produced by one or more
+ * recognisers into a clean, non-overlapping, threshold-filtered output list.
+ *
+ * The function is **pure** — it does not mutate any of its inputs.
+ *
+ * ### Merge rules (applied in order)
+ *
+ * 1. **Denylist boost**: If an entity's `.text` (lowercased) appears in
+ *    `options.denylist` (lowercased), its `score` is set to `1.0`.
+ *
+ * 2. **Allowlist filter**: If an entity's `.text` (lowercased) appears in
+ *    `options.allowlist` (lowercased), the entity is removed entirely.
+ *
+ * 3. **Sort**: Entities are sorted by `start` offset ascending; ties broken
+ *    by span length descending so longer spans are preferred in step 4.
+ *
+ * 4. **Overlap resolution** (single-pass, left-to-right):
+ *    - *Exact or subset overlap* (current span is fully inside last span, or
+ *      they share the same offsets): keep whichever has the higher score.
+ *    - *Current is longer AND score ≥ last*: the current span replaces the
+ *      last accumulated span (it provides more context at equal or better
+ *      confidence).
+ *    - *Adjacent spans* (gap between end of last and start of current is ≤ 2
+ *      characters **and** both have the same `entityType`): the two spans are
+ *      merged into a single entity whose text bridges the gap.
+ *    - *Otherwise*: both spans are kept as separate entities.
+ *
+ * 5. **Confidence threshold filter**: Entities with `score <
+ *    options.confidenceThreshold` are removed.
+ *
+ * 6. **Final sort**: Output is sorted by `start` offset ascending.
+ *
+ * @param entities - Raw (possibly overlapping, unsorted) entity list from the
+ *                   detection pipeline.
+ * @param options  - Optional filtering / merging knobs.  Safe to omit.
+ * @param text     - The original input string.  Required only when adjacent
+ *                   merging may occur (needed to fill gap characters).
+ *                   Defaults to `''` which produces a gap of spaces.
+ * @returns A new array of non-overlapping {@link PiiEntity} objects sorted by
+ *          `start` offset.
+ *
+ * @example
+ * ```ts
+ * const clean = mergeEntities(rawEntities, {
+ *   allowlist: ['support@example.com'],
+ *   denylist: ['secret-project'],
+ *   confidenceThreshold: 0.6,
+ * }, originalText);
+ * ```
+ */
+export function mergeEntities(entities, options = {}, text = '') {
+    const { allowlist = [], denylist = [], confidenceThreshold } = options;
+    // Normalise allow/denylist values once for O(1) lookup per entity.
+    const allowSet = new Set(allowlist.map((s) => s.toLowerCase()));
+    const denySet = new Set(denylist.map((s) => s.toLowerCase()));
+    // -------------------------------------------------------------------------
+    // Step 1 & 2: Apply denylist boost and allowlist filter in a single pass.
+    // -------------------------------------------------------------------------
+    let working = [];
+    for (const entity of entities) {
+        const lower = entity.text.toLowerCase();
+        // Step 1 — denylist boost: entities in the denylist always score 1.0.
+        if (denySet.has(lower)) {
+            working.push({ ...entity, score: 1.0 });
+            continue;
+        }
+        // Step 2 — allowlist filter: entities in the allowlist are dropped.
+        if (allowSet.has(lower)) {
+            continue;
+        }
+        // Neither boosted nor filtered — keep as-is.
+        working.push({ ...entity });
+    }
+    // -------------------------------------------------------------------------
+    // Step 3: Sort by start offset ascending; break ties by span length desc
+    //         so that wider (more informative) spans come first.
+    // -------------------------------------------------------------------------
+    working.sort((a, b) => {
+        if (a.start !== b.start)
+            return a.start - b.start;
+        // Longer span first on a tie.
+        return spanLength(b) - spanLength(a);
+    });
+    // -------------------------------------------------------------------------
+    // Step 4: Overlap resolution — single left-to-right pass.
+    // -------------------------------------------------------------------------
+    const resolved = [];
+    for (const current of working) {
+        if (resolved.length === 0) {
+            // First entity — nothing to compare against yet.
+            resolved.push(current);
+            continue;
+        }
+        // Always compare against the most recently accumulated entity.
+        const last = resolved[resolved.length - 1];
+        if (overlaps(last, current)) {
+            // The two spans overlap.
+            if (isSubset(current, last)) {
+                // `last` fully contains `current` — `last` is the wider (superset)
+                // span.  Prefer the wider span when it scores at least as well.
+                // Replace only if `current` has a strictly higher confidence score.
+                if (current.score > last.score) {
+                    resolved[resolved.length - 1] = current;
+                }
+                // Otherwise keep `last` (wider span with equal or better confidence).
+            }
+            else if (isSubset(last, current)) {
+                // `current` fully contains `last` — `current` is the wider span.
+                // For equal-confidence spans we prefer the wider span (`current`),
+                // but only replace when `current` is genuinely wider than `last`
+                // (same offsets = identical span; identical score = prefer last to
+                // avoid a no-op swap).
+                //
+                // Concrete rules:
+                //   • current strictly longer → replace if current.score >= last.score
+                //   • same length (identical span) → keep higher score (last wins tie)
+                const currentIsWider = (current.end - current.start) > (last.end - last.start);
+                if (currentIsWider ? current.score >= last.score : current.score > last.score) {
+                    resolved[resolved.length - 1] = current;
+                }
+                // Otherwise `last` had equal/better confidence for the same span, or
+                // `last` is already the wider span — keep it.
+            }
+            else {
+                // Partial overlap — neither is a strict subset of the other.
+                // Prefer the longer span when its score is at least as high.
+                if (spanLength(current) > spanLength(last) &&
+                    current.score >= last.score) {
+                    // Current is longer with equal or better confidence — replace.
+                    resolved[resolved.length - 1] = current;
+                }
+                // Otherwise keep `last`.
+            }
+        }
+        else {
+            // No overlap.  Check whether the two spans are adjacent (gap ≤ 2 chars)
+            // and share the same entity type, in which case merging makes sense
+            // (e.g. a name split across a hyphen: "O'-Brien" → two PERSON spans).
+            const gap = current.start - last.end;
+            if (gap >= 0 &&
+                gap <= 2 &&
+                current.entityType === last.entityType) {
+                // Merge the two adjacent spans into one, bridging the gap with the
+                // original text characters.
+                const merged = mergeAdjacent(last, current, text);
+                resolved[resolved.length - 1] = merged;
+            }
+            else {
+                // Genuinely separate entities — keep both.
+                resolved.push(current);
+            }
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Step 5: Confidence threshold filter.
+    // -------------------------------------------------------------------------
+    const thresholded = confidenceThreshold === undefined
+        ? resolved
+        : resolved.filter((e) => e.score >= confidenceThreshold);
+    // -------------------------------------------------------------------------
+    // Step 6: Final sort by start offset (the overlap pass may have produced
+    //         out-of-order entries in edge cases involving replacements).
+    // -------------------------------------------------------------------------
+    return thresholded.slice().sort((a, b) => a.start - b.start);
+}
+//# sourceMappingURL=EntityMerger.js.map

package/dist/extensions/packs/pii-redaction/EntityMerger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntityMerger.js","sourceRoot":"","sources":["../../../../src/extensions/packs/pii-redaction/EntityMerger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AA0DH,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;;;;;GASG;AACH,SAAS,QAAQ,CAAC,CAAY,EAAE,CAAY;IAC1C,OAAO,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC;AAC5C,CAAC;AAED;;;;;;GAMG;AACH,SAAS,QAAQ,CAAC,CAAY,EAAE,CAAY;IAC1C,OAAO,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC;AAC9C,CAAC;AAED;;;;GAIG;AACH,SAAS,UAAU,CAAC,MAAiB;IACnC,OAAO,MAAM,CAAC,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC;AACnC,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAS,aAAa,CAAC,CAAY,EAAE,CAAY,EAAE,IAAY;IAC7D,6EAA6E;IAC7E,yDAAyD;IACzD,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;IAC9C,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;IAC/C,0EAA0E;IAC1E,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAE9D,OAAO;QACL,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,IAAI,EAAE,UAAU;QAChB,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,GAAG,EAAE,CAAC,CAAC,GAAG;QACV,KAAK,EAAE,WAAW;QAClB,MAAM,EAAE,YAAY;QACpB,uEAAuE;QACvE,QAAQ,EACN,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,QAAQ;YACtB,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE;YAClD,CAAC,CAAC,SAAS;KAChB,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,MAAM,UAAU,aAAa,CAC3B,QAAqB,EACrB,UAAwB,EAAE,EAC1B,IAAI,GAAG,EAAE;IAET,MAAM,EAAE,SAAS,GAAG,EAAE,EAAE,QAAQ,GAAG,EAAE,EAAE,mBAAmB,EAAE,GAAG,OAAO,CAAC;IAEvE,mEAAmE;IACnE,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;IAChE,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;IAE9D,4EAA4E;IAC5E,0EAA0E;IAC1E,4EAA4E;IAE5E,IAAI,OAAO,GAAgB,EAAE,CAAC;IAC9B,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;QAC9B,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;QAExC,sEAAsE;QACtE,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;YACxC,SAAS;QACX,CAAC;QAED,oEAAoE;QACpE,IAAI,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YACxB,SAAS;QACX,CAAC;QAED,6CAA6C;QAC7C,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;IAC9B,CAAC;IAED,4EAA4E;IAC5E,yEAAyE;IACzE,6DAA6D;IAC7D,4EAA4E;IAE5E,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACpB,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK;YAAE,OAAO,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;QAClD,8BAA8B;QAC9B,OAAO,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;IAEH,4EAA4E;IAC5E,0DAA0D;IAC1D,4EAA4E;IAE5E,MAAM,QAAQ,GAAgB,EAAE,CAAC;IAEjC,KAAK,MAAM,OAAO,IAAI,OAAO,EAAE,CAAC;QAC9B,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,iDAAiD;YACjD,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACvB,SAAS;QACX,CAAC;QAED,+DAA+D;QAC/D,MAAM,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAE3C,IAAI,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,CAAC;YAC5B,yBAAyB;YAEzB,IAAI,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,CAAC;gBAC5B,mEAAmE;gBACnE,gEAAgE;gBAChE,oEAAoE;gBACpE,IAAI,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;oBAC/B,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,OAAO,CAAC;gBAC1C,CAAC;gBACD,sEAAsE;YACxE,CAAC;iBAAM,IAAI,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,CAAC;gBACnC,iEAAiE;gBACjE,mEAAmE;gBACnE,iEAAiE;gBACjE,mEAAmE;gBACnE,uBAAuB;gBACvB,EAAE;gBACF,kBAAkB;gBAClB,uEAAuE;gBACvE,uEAAuE;gBACvE,MAAM,cAAc,GAAG,CAAC,OAAO,CAAC,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;gBAC/E,IAAI,cAAc,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;oBAC9E,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,OAAO,CAAC;gBAC1C,CAAC;gBACD,qEAAqE;gBACrE,8CAA8C;YAChD,CAAC;iBAAM,CAAC;gBACN,6DAA6D;gBAC7D,6DAA6D;gBAC7D,IACE,UAAU,CAAC,OAAO,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC;oBACtC,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,EAC3B,CAAC;oBACD,+DAA+D;oBAC/D,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,OAAO,CAAC;gBAC1C,CAAC;gBACD,yBAAyB;YAC3B,CAAC;QACH,CAAC;aAAM,CAAC;YACN,wEAAwE;YACxE,oEAAoE;YACpE,sEAAsE;YACtE,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC;YAErC,IACE,GAAG,IAAI,CAAC;gBACR,GAAG,IAAI,CAAC;gBACR,OAAO,CAAC,UAAU,KAAK,IAAI,CAAC,UAAU,EACtC,CAAC;gBACD,mEAAmE;gBACnE,4BAA4B;gBAC5B,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;gBAClD,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC;YACzC,CAAC;iBAAM,CAAC;gBACN,2CAA2C;gBAC3C,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;IACH,CAAC;IAED,4EAA4E;IAC5E,uCAAuC;IACvC,4EAA4E;IAE5E,MAAM,WAAW,GACf,mBAAmB,KAAK,SAAS;QAC/B,CAAC,CAAC,QAAQ;QACV,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,mBAAmB,CAAC,CAAC;IAE7D,4EAA4E;IAC5E,yEAAyE;IACzE,sEAAsE;IACtE,4EAA4E;IAE5E,OAAO,WAAW,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;AAC/D,CAAC"}

package/dist/extensions/packs/pii-redaction/PiiDetectionPipeline.d.ts

@@ -0,0 +1,199 @@
+/**
+ * @file PiiDetectionPipeline.ts
+ * @description Orchestrates the four-tier PII detection pipeline: Regex →
+ * NLP pre-filter → NER model → LLM judge.  Each tier is gated by the
+ * previous tier's output or configuration flags so that only the work needed
+ * is performed, keeping median latency low for clean or simple inputs.
+ *
+ * ## Tier overview
+ *
+ * | Tier | Class                  | Always runs?                                  |
+ * |------|------------------------|-----------------------------------------------|
+ * | 1    | RegexRecognizer        | Yes                                           |
+ * | 2    | NlpPrefilterRecognizer | Yes (when available / compromise installed)   |
+ * | 3    | NerModelRecognizer     | Only when Tier 2 found PERSON/ORG/LOC         |
+ * | 4    | LlmJudgeRecognizer     | Only for ambiguous entities (0.3 < score < 0.7)|
+ *
+ * After tiers 1–3 produce raw candidates, {@link mergeEntities} collapses
+ * overlapping spans.  Tier 4 then re-examines the ambiguous slice.  Finally
+ * the merged list is threshold-filtered and sorted by start offset.
+ *
+ * @module pii-redaction/PiiDetectionPipeline
+ */
+import type { ISharedServiceRegistry } from '../../ISharedServiceRegistry';
+import type { PiiDetectionResult, PiiRedactionPackOptions } from './types';
+/**
+ * Four-tier PII detection pipeline that orchestrates Regex, NLP pre-filter,
+ * NER model, and LLM judge recognisers into a single `detect()` call.
+ *
+ * ### Construction
+ * ```ts
+ * const pipeline = new PiiDetectionPipeline(serviceRegistry, packOptions, getSecret);
+ * const result = await pipeline.detect('Call me at 555-123-4567');
+ * ```
+ *
+ * ### Lifecycle
+ * The pipeline is designed to be constructed once at pack startup and reused
+ * across many `detect()` calls.  Recognisers are constructed eagerly but load
+ * their heavy dependencies (NLP models, NER weights) lazily on first use.
+ *
+ * ### Concurrency
+ * `detect()` is safe to call concurrently from multiple async contexts:
+ * - Regex and NLP recognisers create fresh scoped instances per call.
+ * - The NER model pipeline is shared and thread-safe via the service registry.
+ * - The LLM judge uses an internal semaphore to cap concurrent requests.
+ */
+export declare class PiiDetectionPipeline {
+    /**
+     * Tier 1: Regex-based recogniser backed by the `openredaction` library.
+     * Always runs regardless of configuration.
+     */
+    private readonly regexRecognizer;
+    /**
+     * Tier 2: NLP pre-filter using the `compromise` library.
+     * Catches person names, locations, and organisations that regex misses.
+     * Returns low-confidence candidates (0.3–0.6) for higher-tier confirmation.
+     */
+    private readonly nlpPrefilter;
+    /**
+     * Tier 3: HuggingFace BERT NER model for high-accuracy named-entity
+     * recognition.  Only runs when Tier 2 found at least one NER-class
+     * candidate (PERSON, ORGANIZATION, or LOCATION).
+     */
+    private readonly nerRecognizer;
+    /**
+     * Tier 4: LLM-powered judge that re-examines ambiguous entities.
+     * Only created when {@link PiiRedactionPackOptions.llmJudge} is provided.
+     */
+    private readonly llmJudge;
+    /** Resolved entity types to detect (defaults to all types). */
+    private readonly entityTypes;
+    /** Allowlist passed through to {@link mergeEntities} (string values). */
+    private readonly allowlist;
+    /** Denylist passed through to {@link mergeEntities} (string values). */
+    private readonly denylist;
+    /**
+     * Minimum confidence score for the final output.
+     * @default {@link DEFAULT_CONFIDENCE_THRESHOLD}
+     */
+    private readonly confidenceThreshold;
+    /**
+     * Whether to load and run the NER model tier.
+     * `false` means Tier 3 is unconditionally skipped.
+     * @default true (when the option is absent, NER is allowed to run)
+     */
+    private readonly enableNerModel;
+    /**
+     * Construct a new PiiDetectionPipeline.
+     *
+     * All recognisers are instantiated here but do not load their heavy
+     * dependencies (NLP libraries, transformer models) until the first call
+     * to {@link detect}.
+     *
+     * @param services   - Shared service registry for lazy-loading NLP/NER
+     *                     models so they are shared across the agent.
+     * @param options    - Pack-level configuration including entity type
+     *                     filter, confidence threshold, allow/denylists, and
+     *                     optional LLM judge config.
+     * @param getSecret  - Optional function to look up credential secrets by
+     *                     ID (e.g. `'openai.apiKey'`, `'pii.llm.apiKey'`).
+     *                     Used to resolve the LLM judge API key when not
+     *                     provided explicitly in {@link LlmJudgeConfig.apiKey}.
+     */
+    constructor(services: ISharedServiceRegistry, options: PiiRedactionPackOptions, getSecret?: (id: string) => string | undefined);
+    /**
+     * Run all applicable detection tiers over `text` and return a
+     * {@link PiiDetectionResult} with the merged, threshold-filtered entity
+     * list and pipeline metadata.
+     *
+     * ### Processing steps
+     * 1. **Tier 1 (Regex)** — Always executed.  Deterministic pattern matching.
+     * 2. **Context enhancement** — Scans ±{@link CONTEXT_WINDOW_CHARS} chars
+     *    around each Tier 1 entity for keyword signals and boosts scores.
+     * 3. **Tier 2 (NLP)** — Always attempted; degrades gracefully if `compromise`
+     *    is not installed.
+     * 4. **Tier 3 (NER)** — Runs only when:
+     *    - `enableNerModel !== false`, AND
+     *    - Tier 2 found at least one PERSON, ORGANIZATION, or LOCATION candidate.
+     * 5. **Merge** — {@link mergeEntities} collapses overlapping spans and applies
+     *    allow/denylists.  Threshold is NOT applied yet.
+     * 6. **Tier 4 (LLM judge)** — Applied only to entities in the ambiguous score
+     *    band (0.3 < score < 0.7) and only when `llmJudge` is configured.
+     *    `null` results (NOT_PII) are discarded.
+     * 7. **Threshold filter** — Entities with `score < confidenceThreshold` are
+     *    removed from the final output.
+     * 8. **Sort + summary** — Sorted by start offset; summary string built.
+     *
+     * @param text - The raw input text to analyse.
+     * @returns A {@link PiiDetectionResult} containing detected entities and
+     *          pipeline execution metadata.
+     */
+    detect(text: string): Promise<PiiDetectionResult>;
+    /**
+     * Applies context enhancement to Tier 1 regex entities.
+     *
+     * For each entity, a window of ±{@link CONTEXT_WINDOW_CHARS} characters
+     * around the entity is scanned for known context keywords.  When a
+     * matching keyword is found for that entity's type, the entity's score is
+     * boosted by the keyword's associated {@link CONTEXT_BOOST_STRONG} or
+     * {@link CONTEXT_BOOST_WEAK} amount, capped at 1.0.
+     *
+     * Entities whose type has no context-keyword mapping are returned
+     * unchanged.  A new array of entities is returned — the originals are not
+     * mutated.
+     *
+     * @param entities - Raw Tier 1 entities to enhance.
+     * @param text     - Full input text (used to extract context windows).
+     * @returns New array of entities with potentially boosted scores.
+     */
+    private applyContextEnhancement;
+    /**
+     * Runs the LLM judge over entities in the ambiguous score band
+     * (LLM_JUDGE_SCORE_LOW < score < LLM_JUDGE_SCORE_HIGH).
+     *
+     * Entities outside the ambiguous band are passed through as-is.
+     * For ambiguous entities, `judge()` is awaited in parallel (up to the
+     * semaphore limit configured in LlmJudgeRecognizer).  Entities judged to
+     * be NOT_PII (null return) are discarded.
+     *
+     * @param entities - Merged entity list from Steps 5.
+     * @param text     - Full input text passed to the judge for context.
+     * @returns Updated entity list after LLM judgement.
+     */
+    private runLlmJudge;
+    /**
+     * Resolves the API key for the LLM judge using a three-level fallback:
+     *
+     * 1. Explicit `config.apiKey` (highest priority — caller-supplied).
+     * 2. Provider-specific secret via `getSecret('<provider>.apiKey')`.
+     * 3. Pack-specific generic secret via `getSecret('pii.llm.apiKey')`.
+     *
+     * Returns a new {@link LlmJudgeConfig} with `apiKey` set to the resolved
+     * value (or the original value if a key was already present).
+     *
+     * @param config    - Original LLM judge configuration.
+     * @param getSecret - Optional secret resolver function.
+     * @returns Config with `apiKey` resolved to the best available value.
+     */
+    private resolveJudgeApiKey;
+    /**
+     * Builds a human-readable summary string from the final entity list.
+     *
+     * Format: `"<n> entities found: <count>×<TYPE>, ..."` or
+     * `"No PII detected"` when the list is empty.
+     *
+     * Entity types are sorted alphabetically for deterministic output, and
+     * only types that are actually present appear in the summary.
+     *
+     * @example
+     * ```
+     * "3 entities found: 1×EMAIL, 1×PERSON, 1×PHONE"
+     * "No PII detected"
+     * ```
+     *
+     * @param entities - Final threshold-filtered, sorted entity list.
+     * @returns Human-readable summary string.
+     */
+    private buildSummary;
+}
+//# sourceMappingURL=PiiDetectionPipeline.d.ts.map

package/dist/extensions/packs/pii-redaction/PiiDetectionPipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PiiDetectionPipeline.d.ts","sourceRoot":"","sources":["../../../../src/extensions/packs/pii-redaction/PiiDetectionPipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAC3E,OAAO,KAAK,EAGV,kBAAkB,EAClB,uBAAuB,EAExB,MAAM,SAAS,CAAC;AAwGjB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,oBAAoB;IAK/B;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAElD;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyB;IAEtD;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqB;IAEnD;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IAMrD,+DAA+D;IAC/D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAkB;IAE9C,yEAAyE;IACzE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAW;IAErC,wEAAwE;IACxE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAW;IAEpC;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAE7C;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAU;IAMzC;;;;;;;;;;;;;;;;OAgBG;gBAED,QAAQ,EAAE,sBAAsB,EAChC,OAAO,EAAE,uBAAuB,EAChC,SAAS,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS;IAwChD;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACU,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAuH9D;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,uBAAuB;IAwC/B;;;;;;;;;;;;OAYG;YACW,WAAW;IAqCzB;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,kBAAkB;IAsB1B;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,YAAY;CAiBrB"}