@directive-run/ai 1.19.0 → 1.19.1

package/dist/ann-index-27QV9tPC.d.ts

@@ -1,616 +0,0 @@
-import { m as GuardrailFn, I as InputGuardrailData, O as OutputGuardrailData, q as SchemaValidator, T as ToolCallGuardrailData } from './types-CUp1N0uU.js';
-import { c as Embedding } from './semantic-cache-Ba0-jEwb.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>;
-
-/**
- * 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 as A, DEFAULT_INJECTION_PATTERNS as D, type EnhancedPIIGuardrailOptions as E, type InjectionDetectionResult as I, type PIIDetectionResult as P, type RateLimitGuardrail as R, STRICT_INJECTION_PATTERNS as S, type VPTreeIndexConfig as V, type ANNSearchResult as a, type DetectedPII as b, type PIIDetector as c, type PIIType as d, type PromptInjectionGuardrailOptions as e, type RedactionStyle as f, createBruteForceIndex as g, createContentFilterGuardrail as h, createEnhancedPIIGuardrail as i, createLengthGuardrail as j, createModerationGuardrail as k, createOutputPIIGuardrail as l, createOutputSchemaGuardrail as m, createOutputTypeGuardrail as n, createPIIGuardrail as o, createPromptInjectionGuardrail as p, createRateLimitGuardrail as q, createToolGuardrail as r, createUntrustedContentGuardrail as s, createVPTreeIndex as t, detectAndRedactPII as u, detectPII as v, detectPromptInjection as w, markUntrustedContent as x, redactPII as y, sanitizeInjection as z };