@directive-run/ai 1.19.0 → 1.19.2

package/dist/guardrails.d.ts

@@ -1,7 +1,219 @@
-export { A as ANNIndex, a as ANNSearchResult, D as DEFAULT_INJECTION_PATTERNS, b as DetectedPII, E as EnhancedPIIGuardrailOptions, I as InjectionDetectionResult, P as PIIDetectionResult, c as PIIDetector, d as PIIType, e as PromptInjectionGuardrailOptions, R as RateLimitGuardrail, f as RedactionStyle, S as STRICT_INJECTION_PATTERNS, V as VPTreeIndexConfig, g as createBruteForceIndex, h as createContentFilterGuardrail, i as createEnhancedPIIGuardrail, j as createLengthGuardrail, k as createModerationGuardrail, l as createOutputPIIGuardrail, m as createOutputSchemaGuardrail, n as createOutputTypeGuardrail, o as createPIIGuardrail, p as createPromptInjectionGuardrail, q as createRateLimitGuardrail, r as createToolGuardrail, s as createUntrustedContentGuardrail, t as createVPTreeIndex, u as detectAndRedactPII, v as detectPII, w as detectPromptInjection, x as markUntrustedContent, y as redactPII, z as sanitizeInjection } from './ann-index-27QV9tPC.js';
+import { m as GuardrailFn, I as InputGuardrailData, O as OutputGuardrailData, aW as SchemaValidator, T as ToolCallGuardrailData } from './types-DJ09LjZX.js';
+import { a as Embedding } from './semantic-cache-DM7ev7NQ.js';
+export { B as BatchedEmbedder, C as CacheEntry, b as CacheLookupResult, c as CacheStats, E as EmbedderFn, S as SemanticCache, d as SemanticCacheConfig, e as SemanticCacheStorage, f as createBatchedEmbedder, g as createInMemoryStorage, h as createSemanticCache, i as createSemanticCacheGuardrail, j as createTestEmbedder } from './semantic-cache-DM7ev7NQ.js';
 import { Plugin } from '@directive-run/core';
-export { B as BatchedEmbedder, C as CacheEntry, a as CacheLookupResult, b as CacheStats, E as EmbedderFn, c as Embedding, S as SemanticCache, d as SemanticCacheConfig, e as SemanticCacheStorage, f as createBatchedEmbedder, g as createInMemoryStorage, h as createSemanticCache, i as createSemanticCacheGuardrail, j as createTestEmbedder } from './semantic-cache-Ba0-jEwb.js';
-import './types-CUp1N0uU.js';
+
+/**
+ * Built-in guardrails for AI adapter — PII, moderation, rate limiting, tool allowlists, schema validation.
+ */
+
+/**
+ * Create a PII detection guardrail that scans input text for personally identifiable
+ * information. Blocks input when PII is detected, or optionally redacts matches and
+ * passes the sanitized text through.
+ *
+ * @param options - Configuration for PII detection: `patterns` sets the RegExp list (defaults to SSN, credit card, email), `redact` replaces matches instead of blocking, `redactReplacement` sets the replacement string (defaults to `"[REDACTED]"`).
+ * @returns An input guardrail that blocks or redacts PII in user input.
+ *
+ * @example
+ * ```typescript
+ * const piiGuardrail = createPIIGuardrail({
+ *   patterns: [
+ *     /\b\d{3}-\d{2}-\d{4}\b/, // SSN
+ *     /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/i, // Email
+ *   ],
+ *   redact: true,
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function createPIIGuardrail(options: {
+    patterns?: RegExp[];
+    redact?: boolean;
+    redactReplacement?: string;
+}): GuardrailFn<InputGuardrailData>;
+/**
+ * Create a content moderation guardrail that delegates to a user-supplied check function.
+ * Works on both input and output data — the guardrail extracts the text content
+ * automatically and passes it to {@link options.checkFn}.
+ *
+ * @param options - Configuration for content moderation: `checkFn` returns `true` when content should be flagged (supports async), `message` sets the rejection reason (defaults to `"Content flagged by moderation"`).
+ * @returns A guardrail that blocks content flagged by the check function.
+ *
+ * @example
+ * ```typescript
+ * const moderationGuardrail = createModerationGuardrail({
+ *   checkFn: async (text) => {
+ *     const result = await openai.moderations.create({ input: text });
+ *     return result.results[0].flagged;
+ *   },
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function createModerationGuardrail(options: {
+    checkFn: (text: string) => boolean | Promise<boolean>;
+    message?: string;
+}): GuardrailFn<InputGuardrailData | OutputGuardrailData>;
+/** Rate limiter with reset capability for testing */
+interface RateLimitGuardrail extends GuardrailFn<InputGuardrailData> {
+    reset(): void;
+}
+/**
+ * Create a rate limit guardrail that tracks token and request counts over a sliding
+ * one-minute window. Returns a {@link RateLimitGuardrail} — a guardrail function with
+ * an additional `reset()` method for testing.
+ *
+ * @param options - Configuration for rate limiting: `maxTokensPerMinute` caps tokens in the sliding window (defaults to `100000`), `maxRequestsPerMinute` caps requests (defaults to `60`).
+ * @returns A rate limit guardrail with an attached `reset()` method.
+ *
+ * @example
+ * ```typescript
+ * const rateLimiter = createRateLimitGuardrail({
+ *   maxTokensPerMinute: 50000,
+ *   maxRequestsPerMinute: 30,
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function createRateLimitGuardrail(options: {
+    maxTokensPerMinute?: number;
+    maxRequestsPerMinute?: number;
+}): RateLimitGuardrail;
+/**
+ * Create a tool-call guardrail that restricts which tools an agent may invoke.
+ * Supports allowlist mode, denylist mode, or both — when both are provided, a tool
+ * must appear in the allowlist and not appear in the denylist.
+ *
+ * @param options - Configuration for tool filtering: `allowlist` sets permitted tool names, `denylist` sets blocked tool names, `caseSensitive` controls case matching (defaults to `false`).
+ * @returns A tool-call guardrail that enforces the allowlist/denylist rules.
+ *
+ * @example
+ * ```typescript
+ * const toolGuardrail = createToolGuardrail({
+ *   allowlist: ["search", "calculate"],
+ *   denylist: ["delete_account"],
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function createToolGuardrail(options: {
+    allowlist?: string[];
+    denylist?: string[];
+    /** @default false */
+    caseSensitive?: boolean;
+}): GuardrailFn<ToolCallGuardrailData>;
+/**
+ * Create an output guardrail that validates agent output against a schema using
+ * a user-supplied {@link SchemaValidator}. Compatible with any validation library
+ * (Zod, Valibot, ArkType, etc.) via the adapter pattern.
+ *
+ * @param options - Configuration for schema validation: `validate` checks the output against the expected schema, `errorPrefix` is prepended to error messages (defaults to `"Output schema validation failed"`).
+ * @returns An output guardrail that rejects output failing schema validation.
+ *
+ * @example
+ * ```typescript
+ * import { z } from "zod";
+ *
+ * const schemaGuardrail = createOutputSchemaGuardrail({
+ *   validate: (value) => {
+ *     const result = z.object({ answer: z.string() }).safeParse(value);
+ *     return { valid: result.success, errors: result.error?.issues.map(i => i.message) };
+ *   },
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function createOutputSchemaGuardrail<T = unknown>(options: {
+    validate: SchemaValidator<T>;
+    errorPrefix?: string;
+}): GuardrailFn<OutputGuardrailData>;
+/**
+ * Create an output guardrail that performs lightweight runtime type checks without
+ * requiring a schema library. Supports `"string"`, `"number"`, `"boolean"`, `"object"`,
+ * and `"array"` with optional size and field constraints.
+ *
+ * @param options - Configuration for type checking: `type` sets the expected JS type, `requiredFields` lists object keys that must exist, `minLength`/`maxLength` constrain array size, `minStringLength`/`maxStringLength` constrain string length.
+ * @returns An output guardrail that rejects output not matching the expected type or constraints.
+ *
+ * @example
+ * ```typescript
+ * const typeGuardrail = createOutputTypeGuardrail({
+ *   type: "object",
+ *   requiredFields: ["id", "name"],
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function createOutputTypeGuardrail(options: {
+    type: "string" | "number" | "boolean" | "object" | "array";
+    requiredFields?: string[];
+    minLength?: number;
+    maxLength?: number;
+    minStringLength?: number;
+    maxStringLength?: number;
+}): GuardrailFn<OutputGuardrailData>;
+/**
+ * Create an output guardrail that enforces maximum length constraints on agent output,
+ * measured in characters or estimated tokens.
+ *
+ * @param options - Configuration for length limits: `maxCharacters` caps character count, `maxTokens` caps estimated token count, `estimateTokens` provides a custom token estimator (defaults to `Math.ceil(text.length / 4)`).
+ * @returns An output guardrail that rejects output exceeding the configured length limits.
+ *
+ * @example
+ * ```typescript
+ * const lengthGuardrail = createLengthGuardrail({
+ *   maxCharacters: 5000,
+ *   maxTokens: 1200,
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function createLengthGuardrail(options: {
+    /** Maximum characters in output */
+    maxCharacters?: number;
+    /** Maximum estimated tokens in output */
+    maxTokens?: number;
+    /** Custom token estimator (default: chars / 4) */
+    estimateTokens?: (text: string) => number;
+}): GuardrailFn<OutputGuardrailData>;
+/**
+ * Create an output guardrail that blocks content matching any of the provided patterns.
+ * String patterns are escaped and compiled to RegExp; RegExp patterns are used as-is.
+ *
+ * @remarks
+ * A warning is logged when `blockedPatterns` is empty, since an empty list means no
+ * content will ever be filtered.
+ *
+ * @param options - Configuration for content filtering: `blockedPatterns` lists strings or RegExps to match against output, `caseSensitive` controls case matching for string patterns (defaults to `false`).
+ * @returns An output guardrail that rejects output containing any blocked pattern.
+ *
+ * @example
+ * ```typescript
+ * const contentFilter = createContentFilterGuardrail({
+ *   blockedPatterns: [
+ *     /\bpassword\b/i,
+ *     /\bsecret\b/i,
+ *     'internal-only',
+ *   ],
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function createContentFilterGuardrail(options: {
+    /** Patterns to block — strings or RegExp */
+    blockedPatterns: Array<string | RegExp>;
+    /** Case-sensitive matching for string patterns (default: false) */
+    caseSensitive?: boolean;
+}): GuardrailFn<OutputGuardrailData>;
 
 /**
  * Fact-PII Guardrail — input guardrail at the fact-store boundary
@@ -148,26 +360,38 @@ interface FactPIIGuardrailOptions {
     customDetector?: (text: string) => readonly FactPIIMatch[];
     /**
      * Maximum nesting depth to walk when scanning a structured fact
-     * value. Default `1` — the scanner inspects top-level strings, then
-     * descends one level into the object/array. Arrays and plain objects
-     * count as one depth level each. Maps and Sets are still NOT walked
-     * by the built-in scanner; PII inside those structures must go
-     * through a `customDetector`.
+     * value. Default `1` — the scanner inspects top-level strings AND
+     * recurses one level into nested objects / arrays. Each array level
+     * burns one depth slot (so `[[email]]` at `walkDepth: 1` walks the
+     * outer array but its inner array is NOT scanned). Maps and Sets
+     * are still NOT walked by the built-in scanner; PII inside those
+     * structures must go through a `customDetector`.
      *
-     * Per R13-C6 the walker recurses into arrays (Supabase realtime
-     * payloads ship as `payload.new = [{...}]`, MCP resource lists ship
-     * as arrays — those shapes silently bypassed the Tier 0 guard before).
+     * Real-world common shapes and the `walkDepth` they need:
+     * - **Flat object** (`{ email, ssn }`) — works at default `1`.
+     * - **Nested object** (`{ profile: { email } }`) — needs `walkDepth: 2`.
+     * - **Supabase realtime row payload** (`payload.new = [{ email }]`,
+     *   passed as the fact value) — the fact's value is the object
+     *   `{ new: [...] }`, so the chain is object → array → object →
+     *   string and needs `walkDepth: 4`.
+     * - **MCP resource notification list** (`{ resources: [{...}] }`) —
+     *   same shape, needs `walkDepth: 4`.
      *
-     * Consumers with deeply-nested PII shapes have two options:
-     * 1. Pass `walkDepth: 2` (or higher) — the scanner walks plain
-     *    objects and arrays to that depth. Maps and Sets are still
-     *    skipped.
-     * 2. Pass a `customDetector` that walks the consumer-specific shape
-     *    and returns concrete matches — the right answer for
-     *    domain-specific structures (Maps, Sets, getters, Symbol keys).
+     * For deeper or non-object structures (Maps, Sets, class instances
+     * with getters, Symbol-keyed properties), pass a `customDetector`
+     * that walks the consumer-specific shape and returns concrete
+     * matches.
      *
-     * Maximum is `5` to prevent pathological recursion on cyclic
-     * structures. Passing anything higher clamps to `5`.
+     * **Hard caps for safety:**
+     * - `walkDepth` clamps to `[1, 5]` to prevent pathological recursion
+     *   on cyclic structures. Non-finite values (`NaN`, `Infinity`,
+     *   non-number casts) clamp to `1`.
+     * - The walker caps any single array's element count at 10,000
+     *   (warns + truncates). Pass a `customDetector` for larger
+     *   payloads.
+     * - Cycles via shared object references are detected and the
+     *   walker treats re-encountered ancestors as "no match" rather
+     *   than recursing.
      *
      * Property iteration uses `Object.entries`, which skips
      * Symbol-keyed properties and non-enumerable string keys. If you
@@ -187,4 +411,404 @@ interface FactPIIGuardrailOptions {
  */
 declare function createFactPIIGuardrail(options?: FactPIIGuardrailOptions): Plugin;
 
-export { type FactPIICategory, type FactPIIGuardrailMode, type FactPIIGuardrailOptions, type FactPIIMatch, createFactPIIGuardrail };
+/**
+ * Enhanced PII Detection Guardrail
+ *
+ * Provides comprehensive PII detection beyond basic regex patterns:
+ * - Multiple PII types (SSN, credit cards, emails, phones, addresses, names)
+ * - Pluggable detection backends (regex, custom, or external services)
+ * - Context-aware detection (reduces false positives)
+ * - Redaction with reversible or irreversible options
+ *
+ * @example
+ * ```typescript
+ * import { createEnhancedPIIGuardrail } from '@directive-run/ai';
+ *
+ * const guardrail = createEnhancedPIIGuardrail({
+ *   types: ['ssn', 'credit_card', 'email'],
+ *   redact: true,
+ *   detector: 'regex', // or 'custom' with custom detector
+ * });
+ * ```
+ */
+
+/** Supported PII types */
+type PIIType = "ssn" | "credit_card" | "email" | "phone" | "address" | "name" | "date_of_birth" | "passport" | "driver_license" | "ip_address" | "bank_account" | "medical_id" | "national_id";
+/** Detected PII instance */
+interface DetectedPII {
+    type: PIIType;
+    value: string;
+    position: {
+        start: number;
+        end: number;
+    };
+    confidence: number;
+    context?: string;
+}
+/** PII detection result */
+interface PIIDetectionResult {
+    detected: boolean;
+    items: DetectedPII[];
+    typeCounts: Partial<Record<PIIType, number>>;
+    /** Text with PII redacted (if requested) */
+    redactedText?: string;
+}
+/** Custom PII detector interface */
+interface PIIDetector {
+    detect(text: string, types: PIIType[]): Promise<DetectedPII[]>;
+    name: string;
+}
+/** Redaction style */
+type RedactionStyle = 
+/** Replace with [REDACTED] */
+"placeholder"
+/** Replace with type-specific placeholder like [EMAIL] */
+ | "typed"
+/**
+ * Replace with a fixed-width `****` mask plus the last 4 characters
+ * (e.g. `****6789`). Does not preserve or reveal the original length.
+ */
+ | "masked"
+/**
+ * Replace with a deterministic FNV-1a hash.
+ *
+ * **WARNING — this is PSEUDONYMIZATION, not anonymization.** FNV-1a is a
+ * fast, non-cryptographic 32-bit hash. For low-entropy structured PII (SSNs,
+ * card numbers, phone numbers) the output is trivially RE-IDENTIFIABLE via
+ * brute force or a precomputed rainbow table. It MUST NOT be relied on for
+ * GDPR / HIPAA de-identification. Use it only for referential integrity
+ * (correlating the same value across audit logs).
+ */
+ | "hashed";
+/** Redact detected PII from text */
+declare function redactPII(text: string, items: DetectedPII[], style?: RedactionStyle): string;
+/** Options for enhanced PII guardrail */
+interface EnhancedPIIGuardrailOptions {
+    /** PII types to detect (default: all) */
+    types?: PIIType[];
+    /** Detection backend (default: 'regex') */
+    detector?: "regex" | PIIDetector;
+    /** Redact instead of blocking */
+    redact?: boolean;
+    /** Redaction style (default: 'typed') */
+    redactionStyle?: RedactionStyle;
+    /** Minimum confidence to flag (0-1, default: 0.7) */
+    minConfidence?: number;
+    /** Callback when PII is detected */
+    onDetected?: (items: DetectedPII[]) => void;
+    /** Allow specific values (whitelist) */
+    allowlist?: string[];
+    /** Block only if count exceeds threshold */
+    minItemsToBlock?: number;
+    /** Timeout for custom detector in milliseconds (default: 5000) */
+    detectorTimeout?: number;
+}
+/**
+ * Create an enhanced PII detection guardrail.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const guardrail = createEnhancedPIIGuardrail();
+ *
+ * // Redact instead of blocking
+ * const redactGuardrail = createEnhancedPIIGuardrail({
+ *   redact: true,
+ *   redactionStyle: 'masked',
+ * });
+ *
+ * // Custom detection with external service
+ * const customGuardrail = createEnhancedPIIGuardrail({
+ *   detector: myPresidioDetector,
+ *   types: ['ssn', 'credit_card', 'medical_id'],
+ * });
+ * ```
+ */
+declare function createEnhancedPIIGuardrail(options?: EnhancedPIIGuardrailOptions): GuardrailFn<InputGuardrailData>;
+/**
+ * Create an output PII guardrail (for checking agent responses).
+ *
+ * @example
+ * ```typescript
+ * const outputGuardrail = createOutputPIIGuardrail({
+ *   types: ['ssn', 'credit_card'],
+ *   redact: true,
+ * });
+ * ```
+ */
+declare function createOutputPIIGuardrail(options?: EnhancedPIIGuardrailOptions): GuardrailFn<OutputGuardrailData>;
+/**
+ * Detect PII in text without using as a guardrail.
+ * Useful for analysis and logging.
+ *
+ * @example
+ * ```typescript
+ * const result = await detectPII('My SSN is 123-45-6789');
+ * console.log(result.items); // [{ type: 'ssn', value: '123-45-6789', ... }]
+ *
+ * // With custom detector and timeout
+ * const result = await detectPII(text, {
+ *   detector: myPresidioDetector,
+ *   timeout: 10000, // 10 seconds
+ * });
+ * ```
+ */
+declare function detectPII(text: string, options?: {
+    types?: PIIType[];
+    detector?: "regex" | PIIDetector;
+    minConfidence?: number;
+    /** Timeout for custom detectors in milliseconds (default: 5000) */
+    timeout?: number;
+}): Promise<PIIDetectionResult>;
+/**
+ * Detect PII in text and return a result whose `redactedText` is populated.
+ *
+ * This composes {@link detectPII} and {@link redactPII} so callers do not have
+ * to manually wire the two together (and do not have to mutate the detection
+ * result). When no PII is detected, `redactedText` is left `undefined` — it is
+ * deliberately NOT defaulted to the raw input.
+ *
+ * @example
+ * ```typescript
+ * const result = await detectAndRedactPII('My SSN is 123-45-6789', {
+ *   types: ['ssn'],
+ *   style: 'typed',
+ * });
+ * console.log(result.detected);      // true
+ * // ssn is a sensitive-category type, so `typed` emits a generic [REDACTED]
+ * console.log(result.redactedText);  // 'My SSN is [REDACTED]'
+ *
+ * const clean = await detectAndRedactPII('nothing here', { types: ['ssn'] });
+ * console.log(clean.detected);       // false
+ * console.log(clean.redactedText);   // undefined
+ * ```
+ */
+declare function detectAndRedactPII(text: string, options?: {
+    types?: PIIType[];
+    detector?: "regex" | PIIDetector;
+    minConfidence?: number;
+    /** Timeout for custom detectors in milliseconds (default: 5000) */
+    timeout?: number;
+    /** Redaction style applied when PII is detected (default: 'typed') */
+    style?: RedactionStyle;
+}): Promise<PIIDetectionResult>;
+
+/**
+ * Prompt Injection Detection Guardrail
+ *
+ * Detects and blocks prompt injection attacks including:
+ * - Direct injection attempts ("ignore previous instructions")
+ * - Jailbreak patterns ("DAN mode", "pretend you can")
+ * - Indirect injection via external content
+ * - Encoding-based evasion attempts
+ *
+ * @example
+ * ```typescript
+ * import { createPromptInjectionGuardrail } from '@directive-run/ai';
+ *
+ * const guardrail = createPromptInjectionGuardrail({
+ *   strictMode: true,
+ *   onBlocked: (input, patterns) => logSecurityEvent(input, patterns),
+ * });
+ * ```
+ */
+
+/** Pattern with metadata for better debugging */
+interface InjectionPattern {
+    pattern: RegExp;
+    name: string;
+    severity: "low" | "medium" | "high" | "critical";
+    category: InjectionCategory;
+}
+/** Categories of injection attacks */
+type InjectionCategory = "instruction_override" | "jailbreak" | "role_manipulation" | "encoding_evasion" | "delimiter_injection" | "context_manipulation" | "indirect_injection";
+/** Default injection patterns - well-tested and low false-positive rate */
+declare const DEFAULT_INJECTION_PATTERNS: InjectionPattern[];
+/** Strict patterns - more aggressive, may have higher false positives */
+declare const STRICT_INJECTION_PATTERNS: InjectionPattern[];
+/** Detailed detection result */
+interface InjectionDetectionResult {
+    detected: boolean;
+    patterns: Array<{
+        name: string;
+        category: InjectionCategory;
+        severity: InjectionPattern["severity"];
+        match: string;
+        position: number;
+    }>;
+    riskScore: number;
+    sanitizedInput?: string;
+}
+/**
+ * Detect prompt injection patterns in text.
+ * Returns detailed results about what was detected.
+ *
+ * @throws Error if input exceeds MAX_INJECTION_INPUT_LENGTH (100KB)
+ */
+declare function detectPromptInjection(text: string, patterns?: InjectionPattern[]): InjectionDetectionResult;
+/**
+ * Sanitize text by removing detected injection patterns.
+ * Warning: This is a best-effort sanitization, not a security guarantee.
+ *
+ * Uses a single-pass approach to prevent infinite loops where a replacement
+ * could create a new pattern match.
+ */
+declare function sanitizeInjection(text: string, patterns?: InjectionPattern[]): string;
+/** Options for prompt injection guardrail */
+interface PromptInjectionGuardrailOptions {
+    /** Additional patterns to check (added to defaults) */
+    additionalPatterns?: InjectionPattern[];
+    /** Replace default patterns entirely */
+    replacePatterns?: InjectionPattern[];
+    /** Use strict mode with more aggressive detection */
+    strictMode?: boolean;
+    /** Minimum risk score to block (0-100, default: 50) */
+    blockThreshold?: number;
+    /** Attempt to sanitize instead of blocking */
+    sanitize?: boolean;
+    /** Callback when injection is detected */
+    onBlocked?: (input: string, result: InjectionDetectionResult) => void;
+    /** Categories to ignore (e.g., allow 'role_manipulation' for roleplay apps) */
+    ignoreCategories?: InjectionCategory[];
+}
+/**
+ * Create a prompt injection detection guardrail.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const guardrail = createPromptInjectionGuardrail();
+ *
+ * // Strict mode for high-security applications
+ * const strictGuardrail = createPromptInjectionGuardrail({
+ *   strictMode: true,
+ *   blockThreshold: 25,
+ * });
+ *
+ * // Allow role manipulation for roleplay apps
+ * const roleplayGuardrail = createPromptInjectionGuardrail({
+ *   ignoreCategories: ['role_manipulation'],
+ * });
+ * ```
+ */
+declare function createPromptInjectionGuardrail(options?: PromptInjectionGuardrailOptions): GuardrailFn<InputGuardrailData>;
+/**
+ * Mark content as potentially untrusted (from external sources).
+ * This wraps the content with markers that injection detection will scrutinize more closely.
+ *
+ * @example
+ * ```typescript
+ * const userUpload = await readFile(path);
+ * const markedContent = markUntrustedContent(userUpload, 'user-upload');
+ * const prompt = `Summarize this document: ${markedContent}`;
+ * ```
+ */
+declare function markUntrustedContent(content: string, source: string): string;
+/**
+ * Create a guardrail that applies stricter checks to marked untrusted content.
+ *
+ * @example
+ * ```typescript
+ * const guardrail = createUntrustedContentGuardrail({
+ *   baseGuardrail: createPromptInjectionGuardrail({ strictMode: true }),
+ * });
+ * ```
+ */
+declare function createUntrustedContentGuardrail(options: {
+    /** Guardrail to apply to untrusted sections */
+    baseGuardrail?: GuardrailFn<InputGuardrailData>;
+    /** Block if untrusted content contains these patterns */
+    additionalPatterns?: InjectionPattern[];
+}): GuardrailFn<InputGuardrailData>;
+
+/**
+ * Approximate Nearest Neighbor (ANN) Index for Semantic Cache
+ *
+ * Provides pluggable vector search backends for efficient similarity lookups.
+ * Includes a brute-force exact search and a VP-tree (Vantage Point Tree) for
+ * fast approximate nearest neighbor queries.
+ *
+ * @example
+ * ```typescript
+ * import { createSemanticCache } from '@directive-run/ai';
+ * import { createVPTreeIndex } from '@directive-run/ai';
+ *
+ * const index = createVPTreeIndex();
+ *
+ * const cache = createSemanticCache({
+ *   embedder: myEmbedder,
+ *   annIndex: index,
+ * });
+ * ```
+ */
+
+/** Search result from an ANN index */
+interface ANNSearchResult {
+    /** ID of the matched item */
+    id: number;
+    /** Similarity score (0-1, higher is more similar) */
+    similarity: number;
+}
+/** ANN Index interface - pluggable vector search backend */
+interface ANNIndex {
+    /** Add a vector to the index */
+    add(id: number, embedding: Embedding): void;
+    /** Remove a vector from the index */
+    remove(id: number): void;
+    /** Search for the k nearest neighbors */
+    search(query: Embedding, k: number, threshold?: number): ANNSearchResult[];
+    /** Rebuild the index (call after batch additions) */
+    rebuild(): void;
+    /** Get the number of indexed vectors */
+    size(): number;
+    /** Clear the index */
+    clear(): void;
+    /** Check if the index needs to be rebuilt (e.g., after additions/removals) */
+    needsRebuild(): boolean;
+}
+/**
+ * Create a brute-force exact search index.
+ *
+ * O(n) search, O(1) add/remove. Best for small collections (< 10,000 vectors).
+ *
+ * @example
+ * ```typescript
+ * const index = createBruteForceIndex();
+ * index.add(0, [0.1, 0.2, 0.3]);
+ * index.add(1, [0.4, 0.5, 0.6]);
+ *
+ * const results = index.search([0.1, 0.2, 0.3], 1);
+ * // [{ id: 0, similarity: 1.0 }]
+ * ```
+ */
+declare function createBruteForceIndex(): ANNIndex;
+/** VP-Tree index configuration */
+interface VPTreeIndexConfig {
+    /** Optional random number generator for deterministic builds. Returns a number in [0, 1). */
+    random?: () => number;
+}
+/**
+ * Create a VP-Tree (Vantage Point Tree) index for efficient approximate nearest neighbor search.
+ *
+ * O(log n) search on average, requires rebuild after batch additions.
+ * Best for medium collections (1,000 - 100,000 vectors).
+ *
+ * @example
+ * ```typescript
+ * const index = createVPTreeIndex();
+ *
+ * // Add vectors
+ * for (let i = 0; i < embeddings.length; i++) {
+ *   index.add(i, embeddings[i]);
+ * }
+ *
+ * // Build the tree
+ * index.rebuild();
+ *
+ * // Search
+ * const results = index.search(queryEmbedding, 5, 0.9);
+ * ```
+ */
+declare function createVPTreeIndex(vpConfig?: VPTreeIndexConfig): ANNIndex;
+
+export { type ANNIndex, type ANNSearchResult, DEFAULT_INJECTION_PATTERNS, type DetectedPII, Embedding, type EnhancedPIIGuardrailOptions, type FactPIICategory, type FactPIIGuardrailMode, type FactPIIGuardrailOptions, type FactPIIMatch, type InjectionDetectionResult, type PIIDetectionResult, type PIIDetector, type PIIType, type PromptInjectionGuardrailOptions, type RateLimitGuardrail, type RedactionStyle, STRICT_INJECTION_PATTERNS, type VPTreeIndexConfig, createBruteForceIndex, createContentFilterGuardrail, createEnhancedPIIGuardrail, createFactPIIGuardrail, createLengthGuardrail, createModerationGuardrail, createOutputPIIGuardrail, createOutputSchemaGuardrail, createOutputTypeGuardrail, createPIIGuardrail, createPromptInjectionGuardrail, createRateLimitGuardrail, createToolGuardrail, createUntrustedContentGuardrail, createVPTreeIndex, detectAndRedactPII, detectPII, detectPromptInjection, markUntrustedContent, redactPII, sanitizeInjection };