ai-database 2.1.1 → 2.1.3

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,325 @@
+/**
+ * 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,
+        belowThresholdMatches: options.includeBelowThreshold ? [] : undefined,
+        errors: [],
+    };
+    // 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 matches = await searcher(type, query, {
+                threshold,
+                limit: options.limit,
+            });
+            // 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
+            result.errors.push({
+                type,
+                message: error instanceof Error ? error.message : String(error),
+                error: error instanceof Error ? error : undefined,
+            });
+        }
+    }
+    // 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 matches = await searcher(type, query, {
+                threshold,
+                limit: options.limit,
+            });
+            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 results = await provider.semanticSearch(type, query, {
+            minScore: options?.threshold,
+            limit: options?.limit ?? 10,
+        });
+        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/verb-derivation.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Verb Derivation for Backward Cascade Resolution
+ *
+ * Derives reverse verbs for backward relationships:
+ * - manages -> managedBy
+ * - owns -> ownedBy
+ * - creates -> createdBy
+ * - parent_of <-> child_of (bidirectional)
+ *
+ * Used by the cascade resolver to determine the reverse relationship
+ * when traversing relationships in the opposite direction.
+ *
+ * @example
+ * ```ts
+ * import { deriveReverseVerb, fieldNameToVerb, isPassiveVerb } from './verb-derivation.js'
+ *
+ * deriveReverseVerb('manages')     // 'managedBy'
+ * deriveReverseVerb('parent_of')   // 'child_of'
+ * deriveReverseVerb('managedBy')   // 'manages'
+ *
+ * fieldNameToVerb('manager')       // 'manages'
+ * fieldNameToVerb('owner')         // 'owns'
+ *
+ * isPassiveVerb('managedBy')       // true
+ * isPassiveVerb('manages')         // false
+ * ```
+ *
+ * @packageDocumentation
+ */
+/**
+ * Forward verbs to their reverse forms.
+ * Common active verbs mapped to their passive counterparts.
+ *
+ * @example
+ * ```ts
+ * FORWARD_TO_REVERSE.manages   // 'managedBy'
+ * FORWARD_TO_REVERSE.owns      // 'ownedBy'
+ * FORWARD_TO_REVERSE.creates   // 'createdBy'
+ * ```
+ */
+export declare const FORWARD_TO_REVERSE: Readonly<Record<string, string>>;
+/**
+ * Known verb pairs for bidirectional relationships.
+ * These are symmetric - each maps to the other.
+ *
+ * @example
+ * ```ts
+ * BIDIRECTIONAL_PAIRS.parent_of  // 'child_of'
+ * BIDIRECTIONAL_PAIRS.child_of   // 'parent_of'
+ * ```
+ */
+export declare const BIDIRECTIONAL_PAIRS: Readonly<Record<string, string>>;
+/**
+ * Derives the reverse verb for a given forward verb.
+ *
+ * Resolution order:
+ * 1. Check bidirectional pairs first (parent_of <-> child_of)
+ * 2. Check known forward verbs (manages -> managedBy)
+ * 3. Check if already a reversed verb (managedBy -> manages)
+ * 4. Apply standard transformation for verbs ending in 's'
+ * 5. Add 'By' suffix for unknown verbs
+ *
+ * @param verb - The verb to derive the reverse of
+ * @returns The reverse verb
+ *
+ * @example
+ * ```ts
+ * deriveReverseVerb('manages')        // 'managedBy'
+ * deriveReverseVerb('owns')           // 'ownedBy'
+ * deriveReverseVerb('parent_of')      // 'child_of'
+ * deriveReverseVerb('managedBy')      // 'manages' (already reversed)
+ * deriveReverseVerb('customAction')   // 'customActionBy' (unknown verb)
+ * ```
+ */
+export declare function deriveReverseVerb(verb: string): string;
+/**
+ * Derives a verb from a field name.
+ *
+ * Common field names like "manager", "owner", "creator" are mapped
+ * to their corresponding verbs. Unknown field names are returned as-is.
+ *
+ * @param fieldName - The field name to derive a verb from
+ * @returns The derived verb or the field name if no mapping exists
+ *
+ * @example
+ * ```ts
+ * fieldNameToVerb('manager')     // 'manages'
+ * fieldNameToVerb('owner')       // 'owns'
+ * fieldNameToVerb('creator')     // 'creates'
+ * fieldNameToVerb('customField') // 'customField' (no mapping)
+ * ```
+ */
+export declare function fieldNameToVerb(fieldName: string): string;
+/**
+ * Checks if a verb is in passive form.
+ *
+ * A verb is considered passive if it ends with:
+ * - 'By' (managedBy, ownedBy, createdBy)
+ * - 'To' (relatedTo, linkedTo, connectedTo)
+ * - 'Of' (parent_of, child_of, partOf)
+ *
+ * @param verb - The verb to check
+ * @returns True if the verb is passive, false otherwise
+ *
+ * @example
+ * ```ts
+ * isPassiveVerb('managedBy')   // true
+ * isPassiveVerb('relatedTo')   // true
+ * isPassiveVerb('parent_of')   // true
+ * isPassiveVerb('manages')     // false
+ * ```
+ */
+export declare function isPassiveVerb(verb: string): boolean;
+/**
+ * Register a custom verb pair for forward/reverse derivation.
+ *
+ * This allows extending the verb derivation system with domain-specific
+ * verb mappings at runtime.
+ *
+ * @param forward - The forward (active) verb
+ * @param reverse - The reverse (passive) verb
+ *
+ * @example
+ * ```ts
+ * registerVerbPair('sponsors', 'sponsoredBy')
+ * deriveReverseVerb('sponsors')     // 'sponsoredBy'
+ * deriveReverseVerb('sponsoredBy')  // 'sponsors'
+ * ```
+ */
+export declare function registerVerbPair(forward: string, reverse: string): void;
+/**
+ * Register a bidirectional verb pair.
+ *
+ * Bidirectional pairs are symmetric relationships where each verb
+ * maps to the other. For self-referential relationships, both
+ * arguments can be the same verb.
+ *
+ * @param verbA - The first verb
+ * @param verbB - The second verb (can be same as verbA for symmetric)
+ *
+ * @example
+ * ```ts
+ * // Asymmetric bidirectional
+ * registerBidirectionalPair('mentor_of', 'mentee_of')
+ * deriveReverseVerb('mentor_of')  // 'mentee_of'
+ * deriveReverseVerb('mentee_of')  // 'mentor_of'
+ *
+ * // Symmetric (self-referential)
+ * registerBidirectionalPair('relatedTo', 'relatedTo')
+ * deriveReverseVerb('relatedTo')  // 'relatedTo'
+ * ```
+ */
+export declare function registerBidirectionalPair(verbA: string, verbB: string): void;
+/**
+ * Register a field name to verb mapping.
+ *
+ * @param fieldName - The field name
+ * @param verb - The verb it derives to
+ *
+ * @example
+ * ```ts
+ * registerFieldVerb('coordinator', 'coordinates')
+ * fieldNameToVerb('coordinator')  // 'coordinates'
+ * ```
+ */
+export declare function registerFieldVerb(fieldName: string, verb: string): void;
+//# sourceMappingURL=verb-derivation.d.ts.map

package/dist/schema/verb-derivation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verb-derivation.d.ts","sourceRoot":"","sources":["../../src/schema/verb-derivation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAiCH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAqB,CAAA;AAcrF;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAuB,CAAA;AAwBxF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAwCtD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAYnD;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAGvE;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAG5E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAEvE"}