@framers/agentos 0.1.56 → 0.1.57

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

@@ -1,263 +0,0 @@
-/**
- * @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

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

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

@@ -1,199 +0,0 @@
-/**
- * @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

@@ -1 +0,0 @@
-{"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"}