@floatingsidewal/bulkhead-core 0.3.0

package/dist/index-BNiM_sPB.d.mts

@@ -0,0 +1,237 @@
+/** Confidence level for a detection */
+type Confidence = "high" | "medium" | "low";
+/** Which cascade layer produced this detection */
+type DetectionSource = "regex" | "bert" | "llm";
+/** Whether this detection is final or needs escalation */
+type Disposition = "confirmed" | "escalate" | "dismissed" | "informational";
+/** A detected entity in text */
+interface Detection {
+    /** Entity type (e.g., "CREDIT_CARD", "US_SSN", "AWS_KEY") */
+    entityType: string;
+    /** Start offset in the input text */
+    start: number;
+    /** End offset in the input text */
+    end: number;
+    /** The matched text */
+    text: string;
+    /** Detection confidence */
+    confidence: Confidence;
+    /** Numeric score 0-1 */
+    score: number;
+    /** Which guard produced this detection */
+    guardName: string;
+    /** Which cascade layer produced this detection */
+    source: DetectionSource;
+    /** Surrounding text window for context */
+    context: string;
+    /** Whether this detection is final or needs escalation */
+    disposition: Disposition;
+}
+/** Result from a single guard's analysis */
+interface GuardResult {
+    /** Whether the text passed this guard (no issues found) */
+    passed: boolean;
+    /** Human-readable reason for the result */
+    reason: string;
+    /** Name of the guard that produced this result */
+    guardName: string;
+    /** Overall score 0-1 (0 = safe, 1 = maximum threat) */
+    score: number;
+    /** Individual detections found */
+    detections: Detection[];
+    /** Modified text with redactions applied (if applicable) */
+    redactedText?: string;
+}
+/** Guard mode: block rejects the input, redact sanitizes it */
+type GuardMode = "block" | "redact";
+/** Configuration for a guard */
+interface GuardConfig {
+    /** Whether this guard is enabled */
+    enabled: boolean;
+    /** Detection threshold 0-1 (detections below this score are ignored) */
+    threshold: number;
+    /** What to do when a detection occurs */
+    mode: GuardMode;
+}
+/** A guard analyzes text and returns results */
+interface Guard {
+    /** Unique name for this guard */
+    readonly name: string;
+    /** Analyze text and return results */
+    analyze(text: string, config?: Partial<GuardConfig>): Promise<GuardResult>;
+}
+/** Configuration for the guardrails engine */
+interface EngineConfig {
+    /** Guard-specific configuration overrides */
+    guards: Record<string, Partial<GuardConfig>>;
+}
+/** A PII pattern definition */
+interface PiiPattern {
+    /** Entity type name (e.g., "CREDIT_CARD") */
+    entityType: string;
+    /** Regex patterns to match */
+    patterns: RegExp[];
+    /** Optional validation function (e.g., Luhn check) */
+    validate?: (match: string) => boolean;
+    /** Context words that boost confidence when found nearby */
+    contextWords?: string[];
+    /** Base confidence without context boost */
+    baseConfidence: Confidence;
+    /** Base score without context boost */
+    baseScore: number;
+}
+/** A secret pattern definition */
+interface SecretPattern {
+    /** Secret type name (e.g., "AWS_ACCESS_KEY") */
+    secretType: string;
+    /** Regex patterns to match */
+    patterns: RegExp[];
+    /** Optional validation function */
+    validate?: (match: string) => boolean;
+    /** Minimum entropy threshold (if applicable) */
+    minEntropy?: number;
+}
+/** Tactic names for detection strategies */
+type TacticName = "pattern" | "heuristic" | "llm";
+/** Result from a tactic execution */
+interface TacticResult {
+    /** Score 0-1 */
+    score: number;
+    /** Additional context about the detection */
+    details?: Record<string, unknown>;
+}
+/** A detection tactic */
+interface Tactic {
+    readonly name: TacticName;
+    readonly defaultThreshold: number;
+    execute(input: string): Promise<TacticResult>;
+}
+
+/**
+ * LLM disambiguation layer (Layer 3) of the cascading classifier.
+ * Only receives ambiguous spans from Layer 2, along with surrounding context.
+ * Makes a focused determination: is this span PII or not?
+ */
+
+/** Function signature for an LLM provider */
+type LlmProvider = (prompt: string) => Promise<string>;
+interface LlmLayerConfig {
+    /** Number of sentences before/after the span to include as context */
+    contextSentences: number;
+    /** LLM provider function */
+    provider?: LlmProvider;
+}
+declare class LlmLayer {
+    private config;
+    constructor(config?: Partial<LlmLayerConfig>);
+    /** Set the LLM provider (can be swapped at runtime) */
+    setProvider(provider: LlmProvider): void;
+    /**
+     * Disambiguate escalated detections using an LLM.
+     * @param escalated Detections with disposition "escalate"
+     * @param fullText The full document text
+     * @param confirmed Already-confirmed detections (passed as context to help disambiguation)
+     */
+    disambiguate(escalated: Detection[], fullText: string, confirmed: Detection[]): Promise<Detection[]>;
+    /** Build a focused disambiguation prompt */
+    private buildPrompt;
+    /** Extract ±N sentences around a span */
+    private extractSentenceContext;
+    /** Parse the LLM response JSON */
+    private parseResponse;
+}
+
+/**
+ * Cascading Classifier — orchestrates the three detection layers.
+ *
+ * Layer 1 (Regex): Always runs, sub-ms. Catches structured PII.
+ *   → confidence: 1.0, disposition: "confirmed"
+ *
+ * Layer 2 (BERT): On-demand, 20-50ms. Catches contextual entities.
+ *   → score >= threshold: "confirmed"
+ *   → score < threshold: "escalate"
+ *
+ * Layer 3 (LLM): Selective, 500ms-2s. Only sees escalated spans.
+ *   → Returns "confirmed" or "dismissed"
+ */
+
+interface CascadeConfig {
+    /** Confidence threshold below which BERT results escalate to LLM */
+    escalationThreshold: number;
+    /** Number of sentences of context to pass to Layer 3 */
+    contextSentences: number;
+    /** Whether Layer 2 (BERT) is enabled */
+    bertEnabled: boolean;
+    /** Whether Layer 3 (LLM) is enabled */
+    llmEnabled: boolean;
+    /** Model ID for BERT layer */
+    modelId?: string;
+    /** LLM provider function for Layer 3 */
+    llmProvider?: LlmProvider;
+}
+declare class CascadeClassifier {
+    private config;
+    private bertLayer;
+    private llmLayer;
+    private regexGuards;
+    constructor(config?: Partial<CascadeConfig>);
+    /** Whether the cascade is ready to serve (BERT model loaded if enabled) */
+    get ready(): boolean;
+    /** Register regex-based guards (Layer 1) */
+    addRegexGuard(guard: Guard): this;
+    /** Set the LLM provider for Layer 3 */
+    setLlmProvider(provider: LlmProvider): void;
+    /**
+     * Run the full cascade: Regex → BERT → LLM
+     * Returns a unified GuardResult with all detections carrying provenance.
+     */
+    deepScan(text: string): Promise<GuardResult>;
+    /** Run Layer 1 only (for fast auto-scan path) */
+    regexScan(text: string): Promise<GuardResult>;
+    /** Run Layers 1 + 2 only (no LLM, for "Scan File" command) */
+    modelScan(text: string): Promise<GuardResult>;
+    private runRegexLayer;
+    private runBertLayer;
+    /** Remove BERT detections that overlap with regex detections */
+    private deduplicateAgainstRegex;
+    private buildCascadeResult;
+    /** Clean up resources */
+    dispose(): Promise<void>;
+}
+
+/**
+ * Main-thread interface to the BERT worker (Layer 2).
+ * Manages the worker lifecycle and maps BERT tokens to Detection objects.
+ */
+
+interface BertLayerConfig {
+    modelId?: string;
+    /** Threshold above which detections are confirmed, below which they escalate */
+    escalationThreshold: number;
+}
+declare class BertLayer {
+    private worker;
+    private pendingRequests;
+    private requestId;
+    private config;
+    /** Whether the BERT model has been loaded and first inference completed */
+    private _loaded;
+    get loaded(): boolean;
+    constructor(config?: Partial<BertLayerConfig>);
+    /** Resolve the worker path — supports both compiled .js and source .ts */
+    private resolveWorkerPath;
+    /** Ensure the worker thread is running */
+    private ensureWorker;
+    /** Send text to the BERT worker and get raw token results */
+    private analyzeRaw;
+    /**
+     * Analyze text and return Detection objects with escalation disposition.
+     * Tokens above the escalation threshold are "confirmed",
+     * tokens below are "escalate" (need LLM review).
+     */
+    analyze(text: string): Promise<Detection[]>;
+    /** Terminate the worker thread */
+    dispose(): Promise<void>;
+}
+
+export { type BertLayerConfig as B, type CascadeConfig as C, type Detection as D, type EngineConfig as E, type GuardMode as G, type LlmLayerConfig as L, type PiiPattern as P, type SecretPattern as S, type Tactic as T, type Guard as a, type GuardResult as b, CascadeClassifier as c, type GuardConfig as d, type DetectionSource as e, type Disposition as f, type Confidence as g, type LlmProvider as h, type TacticName as i, type TacticResult as j, BertLayer as k, LlmLayer as l };

package/dist/index-BNiM_sPB.d.ts

@@ -0,0 +1,237 @@
+/** Confidence level for a detection */
+type Confidence = "high" | "medium" | "low";
+/** Which cascade layer produced this detection */
+type DetectionSource = "regex" | "bert" | "llm";
+/** Whether this detection is final or needs escalation */
+type Disposition = "confirmed" | "escalate" | "dismissed" | "informational";
+/** A detected entity in text */
+interface Detection {
+    /** Entity type (e.g., "CREDIT_CARD", "US_SSN", "AWS_KEY") */
+    entityType: string;
+    /** Start offset in the input text */
+    start: number;
+    /** End offset in the input text */
+    end: number;
+    /** The matched text */
+    text: string;
+    /** Detection confidence */
+    confidence: Confidence;
+    /** Numeric score 0-1 */
+    score: number;
+    /** Which guard produced this detection */
+    guardName: string;
+    /** Which cascade layer produced this detection */
+    source: DetectionSource;
+    /** Surrounding text window for context */
+    context: string;
+    /** Whether this detection is final or needs escalation */
+    disposition: Disposition;
+}
+/** Result from a single guard's analysis */
+interface GuardResult {
+    /** Whether the text passed this guard (no issues found) */
+    passed: boolean;
+    /** Human-readable reason for the result */
+    reason: string;
+    /** Name of the guard that produced this result */
+    guardName: string;
+    /** Overall score 0-1 (0 = safe, 1 = maximum threat) */
+    score: number;
+    /** Individual detections found */
+    detections: Detection[];
+    /** Modified text with redactions applied (if applicable) */
+    redactedText?: string;
+}
+/** Guard mode: block rejects the input, redact sanitizes it */
+type GuardMode = "block" | "redact";
+/** Configuration for a guard */
+interface GuardConfig {
+    /** Whether this guard is enabled */
+    enabled: boolean;
+    /** Detection threshold 0-1 (detections below this score are ignored) */
+    threshold: number;
+    /** What to do when a detection occurs */
+    mode: GuardMode;
+}
+/** A guard analyzes text and returns results */
+interface Guard {
+    /** Unique name for this guard */
+    readonly name: string;
+    /** Analyze text and return results */
+    analyze(text: string, config?: Partial<GuardConfig>): Promise<GuardResult>;
+}
+/** Configuration for the guardrails engine */
+interface EngineConfig {
+    /** Guard-specific configuration overrides */
+    guards: Record<string, Partial<GuardConfig>>;
+}
+/** A PII pattern definition */
+interface PiiPattern {
+    /** Entity type name (e.g., "CREDIT_CARD") */
+    entityType: string;
+    /** Regex patterns to match */
+    patterns: RegExp[];
+    /** Optional validation function (e.g., Luhn check) */
+    validate?: (match: string) => boolean;
+    /** Context words that boost confidence when found nearby */
+    contextWords?: string[];
+    /** Base confidence without context boost */
+    baseConfidence: Confidence;
+    /** Base score without context boost */
+    baseScore: number;
+}
+/** A secret pattern definition */
+interface SecretPattern {
+    /** Secret type name (e.g., "AWS_ACCESS_KEY") */
+    secretType: string;
+    /** Regex patterns to match */
+    patterns: RegExp[];
+    /** Optional validation function */
+    validate?: (match: string) => boolean;
+    /** Minimum entropy threshold (if applicable) */
+    minEntropy?: number;
+}
+/** Tactic names for detection strategies */
+type TacticName = "pattern" | "heuristic" | "llm";
+/** Result from a tactic execution */
+interface TacticResult {
+    /** Score 0-1 */
+    score: number;
+    /** Additional context about the detection */
+    details?: Record<string, unknown>;
+}
+/** A detection tactic */
+interface Tactic {
+    readonly name: TacticName;
+    readonly defaultThreshold: number;
+    execute(input: string): Promise<TacticResult>;
+}
+
+/**
+ * LLM disambiguation layer (Layer 3) of the cascading classifier.
+ * Only receives ambiguous spans from Layer 2, along with surrounding context.
+ * Makes a focused determination: is this span PII or not?
+ */
+
+/** Function signature for an LLM provider */
+type LlmProvider = (prompt: string) => Promise<string>;
+interface LlmLayerConfig {
+    /** Number of sentences before/after the span to include as context */
+    contextSentences: number;
+    /** LLM provider function */
+    provider?: LlmProvider;
+}
+declare class LlmLayer {
+    private config;
+    constructor(config?: Partial<LlmLayerConfig>);
+    /** Set the LLM provider (can be swapped at runtime) */
+    setProvider(provider: LlmProvider): void;
+    /**
+     * Disambiguate escalated detections using an LLM.
+     * @param escalated Detections with disposition "escalate"
+     * @param fullText The full document text
+     * @param confirmed Already-confirmed detections (passed as context to help disambiguation)
+     */
+    disambiguate(escalated: Detection[], fullText: string, confirmed: Detection[]): Promise<Detection[]>;
+    /** Build a focused disambiguation prompt */
+    private buildPrompt;
+    /** Extract ±N sentences around a span */
+    private extractSentenceContext;
+    /** Parse the LLM response JSON */
+    private parseResponse;
+}
+
+/**
+ * Cascading Classifier — orchestrates the three detection layers.
+ *
+ * Layer 1 (Regex): Always runs, sub-ms. Catches structured PII.
+ *   → confidence: 1.0, disposition: "confirmed"
+ *
+ * Layer 2 (BERT): On-demand, 20-50ms. Catches contextual entities.
+ *   → score >= threshold: "confirmed"
+ *   → score < threshold: "escalate"
+ *
+ * Layer 3 (LLM): Selective, 500ms-2s. Only sees escalated spans.
+ *   → Returns "confirmed" or "dismissed"
+ */
+
+interface CascadeConfig {
+    /** Confidence threshold below which BERT results escalate to LLM */
+    escalationThreshold: number;
+    /** Number of sentences of context to pass to Layer 3 */
+    contextSentences: number;
+    /** Whether Layer 2 (BERT) is enabled */
+    bertEnabled: boolean;
+    /** Whether Layer 3 (LLM) is enabled */
+    llmEnabled: boolean;
+    /** Model ID for BERT layer */
+    modelId?: string;
+    /** LLM provider function for Layer 3 */
+    llmProvider?: LlmProvider;
+}
+declare class CascadeClassifier {
+    private config;
+    private bertLayer;
+    private llmLayer;
+    private regexGuards;
+    constructor(config?: Partial<CascadeConfig>);
+    /** Whether the cascade is ready to serve (BERT model loaded if enabled) */
+    get ready(): boolean;
+    /** Register regex-based guards (Layer 1) */
+    addRegexGuard(guard: Guard): this;
+    /** Set the LLM provider for Layer 3 */
+    setLlmProvider(provider: LlmProvider): void;
+    /**
+     * Run the full cascade: Regex → BERT → LLM
+     * Returns a unified GuardResult with all detections carrying provenance.
+     */
+    deepScan(text: string): Promise<GuardResult>;
+    /** Run Layer 1 only (for fast auto-scan path) */
+    regexScan(text: string): Promise<GuardResult>;
+    /** Run Layers 1 + 2 only (no LLM, for "Scan File" command) */
+    modelScan(text: string): Promise<GuardResult>;
+    private runRegexLayer;
+    private runBertLayer;
+    /** Remove BERT detections that overlap with regex detections */
+    private deduplicateAgainstRegex;
+    private buildCascadeResult;
+    /** Clean up resources */
+    dispose(): Promise<void>;
+}
+
+/**
+ * Main-thread interface to the BERT worker (Layer 2).
+ * Manages the worker lifecycle and maps BERT tokens to Detection objects.
+ */
+
+interface BertLayerConfig {
+    modelId?: string;
+    /** Threshold above which detections are confirmed, below which they escalate */
+    escalationThreshold: number;
+}
+declare class BertLayer {
+    private worker;
+    private pendingRequests;
+    private requestId;
+    private config;
+    /** Whether the BERT model has been loaded and first inference completed */
+    private _loaded;
+    get loaded(): boolean;
+    constructor(config?: Partial<BertLayerConfig>);
+    /** Resolve the worker path — supports both compiled .js and source .ts */
+    private resolveWorkerPath;
+    /** Ensure the worker thread is running */
+    private ensureWorker;
+    /** Send text to the BERT worker and get raw token results */
+    private analyzeRaw;
+    /**
+     * Analyze text and return Detection objects with escalation disposition.
+     * Tokens above the escalation threshold are "confirmed",
+     * tokens below are "escalate" (need LLM review).
+     */
+    analyze(text: string): Promise<Detection[]>;
+    /** Terminate the worker thread */
+    dispose(): Promise<void>;
+}
+
+export { type BertLayerConfig as B, type CascadeConfig as C, type Detection as D, type EngineConfig as E, type GuardMode as G, type LlmLayerConfig as L, type PiiPattern as P, type SecretPattern as S, type Tactic as T, type Guard as a, type GuardResult as b, CascadeClassifier as c, type GuardConfig as d, type DetectionSource as e, type Disposition as f, type Confidence as g, type LlmProvider as h, type TacticName as i, type TacticResult as j, BertLayer as k, LlmLayer as l };