ai-database 2.1.1 → 2.3.0

package/dist/schema/union-fallback.d.ts

@@ -0,0 +1,219 @@
+/**
+ * Union Type Fallback Search
+ *
+ * Implements fallback search behavior for union types in backward fuzzy (<~) operators.
+ * When searching `<~Type1|Type2|Type3`, searches types in order and falls back to
+ * the next type if no match is found or threshold not met.
+ *
+ * Supports two search modes:
+ * - `ordered`: Search types sequentially, stop on first match (default)
+ * - `parallel`: Search all types concurrently, return best match
+ *
+ * @packageDocumentation
+ */
+/**
+ * Match result from a union type search
+ */
+export interface UnionMatch {
+    /** Unique identifier of the matched entity */
+    $id: string;
+    /** Similarity score (0-1) */
+    $score: number;
+    /** Type that was matched */
+    $type: string;
+    /** Additional match data */
+    [key: string]: unknown;
+}
+/**
+ * Error that occurred during search
+ */
+export interface SearchError {
+    /** Type that failed to search */
+    type: string;
+    /** Error message */
+    message: string;
+    /** Original error */
+    error?: Error;
+}
+/**
+ * Result of a union type search operation
+ */
+export interface UnionSearchResult {
+    /** Matches found (empty array if no matches) */
+    matches: UnionMatch[];
+    /** Types that were searched */
+    searchedTypes: string[];
+    /** Order in which types were searched */
+    searchOrder: string[];
+    /** Whether fallback was triggered (searched more than first type) */
+    fallbackTriggered: boolean;
+    /** Whether all types were exhausted without finding a match */
+    allTypesExhausted: boolean;
+    /** The type that matched (first match in ordered mode, best in parallel) */
+    matchedType?: string;
+    /** Overall confidence score (highest match score) */
+    confidence?: number;
+    /** Matches that were below threshold (for debugging) */
+    belowThresholdMatches?: UnionMatch[];
+    /** Errors that occurred during search */
+    errors?: SearchError[];
+}
+/**
+ * Searcher function type for searching a single type
+ */
+export type UnionSearcher = (type: string, query: string, options?: {
+    threshold?: number;
+    limit?: number;
+}) => Promise<UnionMatch[]>;
+/**
+ * Options for union type fallback search
+ */
+export interface FallbackSearchOptions {
+    /**
+     * Search mode:
+     * - `ordered`: Search types sequentially, stop on first match above threshold
+     * - `parallel`: Search all types concurrently, return best match(es)
+     */
+    mode: 'ordered' | 'parallel';
+    /**
+     * Global similarity threshold (0-1)
+     * Matches below this threshold are ignored (unless includeBelowThreshold is true)
+     */
+    threshold?: number;
+    /**
+     * Per-type thresholds
+     * Overrides the global threshold for specific types
+     */
+    thresholds?: Record<string, number>;
+    /**
+     * Searcher function to perform the actual search
+     * Called with (type, query, options) for each type being searched
+     */
+    searcher: UnionSearcher;
+    /**
+     * In parallel mode, return all matches sorted by score (default: false, return only best)
+     */
+    returnAll?: boolean;
+    /**
+     * Include matches below threshold in result for debugging (stored in belowThresholdMatches)
+     */
+    includeBelowThreshold?: boolean;
+    /**
+     * Error handling mode:
+     * - `throw`: Throw on first error (default in ordered mode)
+     * - `continue`: Continue searching remaining types on error
+     */
+    onError?: 'throw' | 'continue';
+    /**
+     * Maximum number of results to return per type
+     */
+    limit?: number;
+}
+/**
+ * Parse union type string into array of individual types
+ *
+ * Handles various formats:
+ * - `Type1|Type2|Type3` - Standard pipe-separated union
+ * - `Type1 | Type2 | Type3` - With spaces around pipes
+ * - `Type1|Type2(0.8)|Type3` - With threshold syntax (stripped from result)
+ *
+ * @param typeSpec - The union type specification string
+ * @returns Array of individual type names in declaration order
+ *
+ * @example
+ * ```ts
+ * parseUnionTypes('Document|Video|Expert')
+ * // => ['Document', 'Video', 'Expert']
+ *
+ * parseUnionTypes('Type1 | Type2(0.8) | Type3')
+ * // => ['Type1', 'Type2', 'Type3']
+ *
+ * parseUnionTypes('SingleType')
+ * // => ['SingleType']
+ * ```
+ */
+export declare function parseUnionTypes(typeSpec: string): string[];
+/**
+ * Parse per-type thresholds from union type specification
+ *
+ * Extracts threshold values from syntax like `Type1|Type2(0.8)|Type3(0.6)`
+ *
+ * @param typeSpec - The union type specification string
+ * @returns Record mapping type names to their thresholds
+ *
+ * @example
+ * ```ts
+ * parseUnionThresholds('Type1|Type2(0.8)|Type3(0.6)')
+ * // => { Type2: 0.8, Type3: 0.6 }
+ * ```
+ */
+export declare function parseUnionThresholds(typeSpec: string): Record<string, number>;
+/**
+ * Search union types with fallback behavior
+ *
+ * Searches multiple types either sequentially (ordered) or concurrently (parallel),
+ * with support for per-type thresholds and graceful error handling.
+ *
+ * @param types - Array of type names to search (in priority order)
+ * @param query - The search query
+ * @param options - Search options including mode, thresholds, and searcher
+ * @returns Search result with matches and metadata
+ *
+ * @example Ordered mode (stops on first match)
+ * ```ts
+ * const result = await searchUnionTypes(
+ *   ['Document', 'Video', 'Expert'],
+ *   'machine learning tutorial',
+ *   {
+ *     mode: 'ordered',
+ *     threshold: 0.75,
+ *     searcher: async (type, query) => {
+ *       return provider.semanticSearch(type, query)
+ *     }
+ *   }
+ * )
+ * ```
+ *
+ * @example Parallel mode (searches all, returns best)
+ * ```ts
+ * const result = await searchUnionTypes(
+ *   ['Document', 'Video', 'Expert'],
+ *   'machine learning tutorial',
+ *   {
+ *     mode: 'parallel',
+ *     returnAll: true,
+ *     searcher: async (type, query) => {
+ *       return provider.semanticSearch(type, query)
+ *     }
+ *   }
+ * )
+ * ```
+ */
+export declare function searchUnionTypes(types: readonly string[], query: string, options: FallbackSearchOptions): Promise<UnionSearchResult>;
+/**
+ * Create a searcher function that wraps a semantic search provider
+ *
+ * @param provider - The database provider with semanticSearch method
+ * @returns A searcher function compatible with searchUnionTypes
+ *
+ * @example
+ * ```ts
+ * const searcher = createProviderSearcher(provider)
+ * const result = await searchUnionTypes(
+ *   ['Document', 'Video'],
+ *   'tutorial',
+ *   { mode: 'ordered', searcher }
+ * )
+ * ```
+ */
+export declare function createProviderSearcher(provider: {
+    semanticSearch: (type: string, query: string, options?: {
+        minScore?: number;
+        limit?: number;
+    }) => Promise<Array<{
+        $id: string;
+        $score: number;
+        [key: string]: unknown;
+    }>>;
+}): UnionSearcher;
+//# sourceMappingURL=union-fallback.d.ts.map

package/dist/schema/union-fallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"union-fallback.d.ts","sourceRoot":"","sources":["../../src/schema/union-fallback.ts"],"names":[],"mappings":"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"}

package/dist/schema/union-fallback.js

@@ -0,0 +1,331 @@
+/**
+ * Union Type Fallback Search
+ *
+ * Implements fallback search behavior for union types in backward fuzzy (<~) operators.
+ * When searching `<~Type1|Type2|Type3`, searches types in order and falls back to
+ * the next type if no match is found or threshold not met.
+ *
+ * Supports two search modes:
+ * - `ordered`: Search types sequentially, stop on first match (default)
+ * - `parallel`: Search all types concurrently, return best match
+ *
+ * @packageDocumentation
+ */
+/**
+ * Parse union type string into array of individual types
+ *
+ * Handles various formats:
+ * - `Type1|Type2|Type3` - Standard pipe-separated union
+ * - `Type1 | Type2 | Type3` - With spaces around pipes
+ * - `Type1|Type2(0.8)|Type3` - With threshold syntax (stripped from result)
+ *
+ * @param typeSpec - The union type specification string
+ * @returns Array of individual type names in declaration order
+ *
+ * @example
+ * ```ts
+ * parseUnionTypes('Document|Video|Expert')
+ * // => ['Document', 'Video', 'Expert']
+ *
+ * parseUnionTypes('Type1 | Type2(0.8) | Type3')
+ * // => ['Type1', 'Type2', 'Type3']
+ *
+ * parseUnionTypes('SingleType')
+ * // => ['SingleType']
+ * ```
+ */
+export function parseUnionTypes(typeSpec) {
+    if (!typeSpec || typeSpec.trim() === '') {
+        return [];
+    }
+    // Split by pipe and process each type
+    const types = typeSpec.split('|').map((t) => {
+        let type = t.trim();
+        // Strip threshold syntax: Type(0.8) -> Type
+        const thresholdMatch = type.match(/^([A-Za-z][A-Za-z0-9_]*)\s*\([^)]*\)$/);
+        if (thresholdMatch) {
+            type = thresholdMatch[1];
+        }
+        return type;
+    });
+    // Filter out empty strings (from cases like "Type1||Type2")
+    return types.filter((t) => t.length > 0);
+}
+/**
+ * Parse per-type thresholds from union type specification
+ *
+ * Extracts threshold values from syntax like `Type1|Type2(0.8)|Type3(0.6)`
+ *
+ * @param typeSpec - The union type specification string
+ * @returns Record mapping type names to their thresholds
+ *
+ * @example
+ * ```ts
+ * parseUnionThresholds('Type1|Type2(0.8)|Type3(0.6)')
+ * // => { Type2: 0.8, Type3: 0.6 }
+ * ```
+ */
+export function parseUnionThresholds(typeSpec) {
+    const thresholds = {};
+    if (!typeSpec)
+        return thresholds;
+    const parts = typeSpec.split('|');
+    for (const part of parts) {
+        const match = part.trim().match(/^([A-Za-z][A-Za-z0-9_]*)\s*\(([0-9.]+)\)$/);
+        if (match) {
+            const [, typeName, thresholdStr] = match;
+            const threshold = parseFloat(thresholdStr);
+            if (!isNaN(threshold) && threshold >= 0 && threshold <= 1) {
+                thresholds[typeName] = threshold;
+            }
+        }
+    }
+    return thresholds;
+}
+/**
+ * Get the effective threshold for a type
+ *
+ * @param type - The type name
+ * @param options - Search options containing global and per-type thresholds
+ * @returns The threshold to use for this type
+ */
+function getThresholdForType(type, options) {
+    // Per-type threshold takes precedence
+    if (options.thresholds && type in options.thresholds) {
+        return options.thresholds[type];
+    }
+    // Fall back to global threshold, default to 0 (accept all)
+    return options.threshold ?? 0;
+}
+/**
+ * Filter matches by threshold
+ */
+function filterByThreshold(matches, threshold, includeBelowThreshold) {
+    const above = [];
+    const below = [];
+    for (const match of matches) {
+        if (match.$score >= threshold) {
+            above.push(match);
+        }
+        else if (includeBelowThreshold) {
+            below.push(match);
+        }
+    }
+    return { above, below };
+}
+/**
+ * Search union types with fallback behavior
+ *
+ * Searches multiple types either sequentially (ordered) or concurrently (parallel),
+ * with support for per-type thresholds and graceful error handling.
+ *
+ * @param types - Array of type names to search (in priority order)
+ * @param query - The search query
+ * @param options - Search options including mode, thresholds, and searcher
+ * @returns Search result with matches and metadata
+ *
+ * @example Ordered mode (stops on first match)
+ * ```ts
+ * const result = await searchUnionTypes(
+ *   ['Document', 'Video', 'Expert'],
+ *   'machine learning tutorial',
+ *   {
+ *     mode: 'ordered',
+ *     threshold: 0.75,
+ *     searcher: async (type, query) => {
+ *       return provider.semanticSearch(type, query)
+ *     }
+ *   }
+ * )
+ * ```
+ *
+ * @example Parallel mode (searches all, returns best)
+ * ```ts
+ * const result = await searchUnionTypes(
+ *   ['Document', 'Video', 'Expert'],
+ *   'machine learning tutorial',
+ *   {
+ *     mode: 'parallel',
+ *     returnAll: true,
+ *     searcher: async (type, query) => {
+ *       return provider.semanticSearch(type, query)
+ *     }
+ *   }
+ * )
+ * ```
+ */
+export async function searchUnionTypes(types, query, options) {
+    // Initialize result
+    const result = {
+        matches: [],
+        searchedTypes: [],
+        searchOrder: [],
+        fallbackTriggered: false,
+        allTypesExhausted: false,
+        errors: [],
+    };
+    if (options.includeBelowThreshold) {
+        result.belowThresholdMatches = [];
+    }
+    // Handle empty types array
+    if (!types || types.length === 0) {
+        result.allTypesExhausted = true;
+        return result;
+    }
+    if (options.mode === 'parallel') {
+        return searchParallel(types, query, options, result);
+    }
+    else {
+        return searchOrdered(types, query, options, result);
+    }
+}
+/**
+ * Search types in order, stopping on first match
+ */
+async function searchOrdered(types, query, options, result) {
+    const { searcher, includeBelowThreshold, onError = 'throw' } = options;
+    for (let i = 0; i < types.length; i++) {
+        const type = types[i];
+        const threshold = getThresholdForType(type, options);
+        result.searchedTypes.push(type);
+        result.searchOrder.push(type);
+        if (i > 0) {
+            result.fallbackTriggered = true;
+        }
+        try {
+            const searchOpts = { threshold };
+            if (options.limit !== undefined)
+                searchOpts.limit = options.limit;
+            const matches = await searcher(type, query, searchOpts);
+            // Filter by threshold
+            const { above, below } = filterByThreshold(matches, threshold, includeBelowThreshold);
+            // Collect below-threshold matches for debugging
+            if (includeBelowThreshold && below.length > 0) {
+                result.belowThresholdMatches.push(...below);
+            }
+            // If we found matches above threshold, stop searching
+            if (above.length > 0) {
+                result.matches = above;
+                result.matchedType = type;
+                result.confidence = Math.max(...above.map((m) => m.$score));
+                return result;
+            }
+        }
+        catch (error) {
+            if (onError === 'throw') {
+                throw error;
+            }
+            // Continue mode: record error and try next type
+            const searchError = {
+                type,
+                message: error instanceof Error ? error.message : String(error),
+            };
+            if (error instanceof Error)
+                searchError.error = error;
+            result.errors.push(searchError);
+        }
+    }
+    // No matches found in any type
+    result.allTypesExhausted = true;
+    return result;
+}
+/**
+ * Search all types in parallel, return best match(es)
+ */
+async function searchParallel(types, query, options, result) {
+    const { searcher, returnAll = false, includeBelowThreshold, onError = 'continue' } = options;
+    // Mark all types as searched
+    result.searchedTypes = [...types];
+    result.searchOrder = [...types];
+    // Search all types in parallel
+    const searchPromises = types.map(async (type) => {
+        const threshold = getThresholdForType(type, options);
+        try {
+            const searchOpts = { threshold };
+            if (options.limit !== undefined)
+                searchOpts.limit = options.limit;
+            const matches = await searcher(type, query, searchOpts);
+            return { type, matches, error: null };
+        }
+        catch (error) {
+            return {
+                type,
+                matches: [],
+                error: error instanceof Error ? error : new Error(String(error)),
+            };
+        }
+    });
+    const results = await Promise.all(searchPromises);
+    // Collect all matches and errors
+    const allMatches = [];
+    const allBelowThreshold = [];
+    for (const { type, matches, error } of results) {
+        if (error) {
+            if (onError === 'throw') {
+                throw error;
+            }
+            result.errors.push({
+                type,
+                message: error.message,
+                error,
+            });
+            continue;
+        }
+        const threshold = getThresholdForType(type, options);
+        const { above, below } = filterByThreshold(matches, threshold, includeBelowThreshold);
+        allMatches.push(...above);
+        if (includeBelowThreshold) {
+            allBelowThreshold.push(...below);
+        }
+    }
+    // Sort by score descending
+    allMatches.sort((a, b) => b.$score - a.$score);
+    result.belowThresholdMatches = allBelowThreshold;
+    if (allMatches.length === 0) {
+        result.allTypesExhausted = true;
+        return result;
+    }
+    // Return all matches or just the best one
+    if (returnAll) {
+        result.matches = allMatches;
+    }
+    else {
+        result.matches = [allMatches[0]];
+    }
+    result.matchedType = result.matches[0].$type;
+    result.confidence = result.matches[0].$score;
+    // Fallback triggered if the best match isn't from the first type
+    result.fallbackTriggered = result.matchedType !== types[0];
+    return result;
+}
+/**
+ * Create a searcher function that wraps a semantic search provider
+ *
+ * @param provider - The database provider with semanticSearch method
+ * @returns A searcher function compatible with searchUnionTypes
+ *
+ * @example
+ * ```ts
+ * const searcher = createProviderSearcher(provider)
+ * const result = await searchUnionTypes(
+ *   ['Document', 'Video'],
+ *   'tutorial',
+ *   { mode: 'ordered', searcher }
+ * )
+ * ```
+ */
+export function createProviderSearcher(provider) {
+    return async (type, query, options) => {
+        const searchOpts = {
+            limit: options?.limit ?? 10,
+        };
+        if (options?.threshold !== undefined)
+            searchOpts.minScore = options.threshold;
+        const results = await provider.semanticSearch(type, query, searchOpts);
+        return results.map((r) => ({
+            ...r,
+            $type: type,
+        }));
+    };
+}
+//# sourceMappingURL=union-fallback.js.map

package/dist/schema/union-fallback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"union-fallback.js","sourceRoot":"","sources":["../../src/schema/union-fallback.ts"],"names":[],"mappings":"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"}

package/dist/schema/value-generators/ai.d.ts

@@ -0,0 +1,54 @@
+/**
+ * AIValueGenerator Implementation
+ *
+ * Generates values using AI/LLM integration for production use.
+ * Supports context-aware generation with parent chain and array context.
+ *
+ * @packageDocumentation
+ */
+import type { ValueGenerator, GenerationRequest, GenerationResult, AIFunction } from './types.js';
+/**
+ * Configuration for AIValueGenerator
+ */
+export interface AIValueGeneratorConfig {
+    /** AI function for generating values */
+    aiFunction: AIFunction;
+    /** Model to use for generation */
+    model?: string;
+    /** Maximum tokens for generation */
+    maxTokens?: number;
+    /** Temperature for generation */
+    temperature?: number;
+    /** Whether to fall back to placeholder on AI errors */
+    fallbackToPlaceholder?: boolean;
+}
+/**
+ * AIValueGenerator
+ *
+ * Generates values using an AI function for production use.
+ * Builds rich context from parent chain, previous generations, and array context.
+ */
+export declare class AIValueGenerator implements ValueGenerator {
+    private aiFunction;
+    private model?;
+    private maxTokens?;
+    private temperature?;
+    private fallbackToPlaceholder;
+    private placeholderGenerator;
+    constructor(config: AIValueGeneratorConfig);
+    /**
+     * Generate a value using AI
+     *
+     * @param request - The generation request
+     * @returns Promise resolving to the generated value with metadata
+     */
+    generate(request: GenerationRequest): Promise<GenerationResult>;
+    /**
+     * Build a prompt from the generation request
+     *
+     * Combines field info, context, hints, and generation context
+     * into a comprehensive prompt for the AI.
+     */
+    private buildPrompt;
+}
+//# sourceMappingURL=ai.d.ts.map

package/dist/schema/value-generators/ai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.d.ts","sourceRoot":"","sources":["../../../src/schema/value-generators/ai.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAGjG;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,wCAAwC;IACxC,UAAU,EAAE,UAAU,CAAA;IACtB,kCAAkC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,oCAAoC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,uDAAuD;IACvD,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAChC;AAED;;;;;GAKG;AACH,qBAAa,gBAAiB,YAAW,cAAc;IACrD,OAAO,CAAC,UAAU,CAAY;IAC9B,OAAO,CAAC,KAAK,CAAC,CAAQ;IACtB,OAAO,CAAC,SAAS,CAAC,CAAQ;IAC1B,OAAO,CAAC,WAAW,CAAC,CAAQ;IAC5B,OAAO,CAAC,qBAAqB,CAAS;IACtC,OAAO,CAAC,oBAAoB,CAA2B;gBAE3C,MAAM,EAAE,sBAAsB;IAS1C;;;;;OAKG;IACG,QAAQ,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA6BrE;;;;;OAKG;IACH,OAAO,CAAC,WAAW;CAsEpB"}