@soulcraft/brainy 6.2.2 → 6.2.4

package/dist/query/typeInference.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Type Inference System - Phase 3: Type-First Query Optimization
+ *
+ * Automatically infers NounTypes from natural language queries using keyword-based
+ * heuristics for fast O(1) type detection.
+ *
+ * Performance Guarantee: < 1ms per query
+ * Accuracy Target: > 80%
+ *
+ * Examples:
+ * - "Find engineers in San Francisco" → [Person, Location]
+ * - "Show documents about AI" → [Document, Concept]
+ * - "List companies in tech sector" → [Organization, Topic]
+ */
+import { NounType } from '../types/graphTypes.js';
+/**
+ * Result of type inference with confidence score
+ */
+export interface TypeInference {
+    type: NounType;
+    confidence: number;
+    matchedKeywords: string[];
+}
+/**
+ * Configuration for type inference behavior
+ */
+export interface TypeInferenceConfig {
+    /**
+     * Minimum confidence threshold to include a type (default: 0.4)
+     */
+    minConfidence?: number;
+    /**
+     * Maximum number of types to return (default: 5)
+     */
+    maxTypes?: number;
+    /**
+     * Enable debug logging (default: false)
+     */
+    debug?: boolean;
+    /**
+     * Enable vector similarity fallback for unknown words (default: false)
+     * When enabled, queries with low keyword confidence trigger vector-based type inference
+     */
+    enableVectorFallback?: boolean;
+    /**
+     * Minimum confidence threshold to trigger vector fallback (default: 0.7)
+     * If keyword matching produces confidence below this, vector fallback is used
+     */
+    fallbackConfidenceThreshold?: number;
+    /**
+     * Minimum similarity score for vector-based type matches (default: 0.5)
+     */
+    vectorThreshold?: number;
+}
+/**
+ * Type Inference System
+ *
+ * Uses keyword matching for fast type detection from natural language.
+ * Designed for billion-scale performance with minimal latency.
+ */
+export declare class TypeInferenceSystem {
+    private keywordMap;
+    private phraseMap;
+    private config;
+    private typeEmbeddings;
+    private embedder;
+    constructor(config?: TypeInferenceConfig);
+    /**
+     * Infer noun types from a natural language query (synchronous keyword matching only)
+     * For hybrid mode with vector fallback, use inferTypesAsync()
+     *
+     * @param query - Natural language query string
+     * @returns Array of type inferences sorted by confidence (highest first)
+     */
+    inferTypes(query: string): TypeInference[];
+    /**
+     * Infer noun types with hybrid approach: keyword matching + optional vector fallback
+     * This is the async version that supports vector similarity fallback
+     *
+     * @param query - Natural language query string
+     * @returns Promise resolving to array of type inferences
+     */
+    inferTypesAsync(query: string): Promise<TypeInference[]>;
+    /**
+     * Internal: Keyword-based type inference (synchronous, fast)
+     */
+    private inferTypesViaKeywords;
+    /**
+     * Internal: Hybrid inference with vector fallback (asynchronous)
+     */
+    private inferTypesWithFallback;
+    /**
+     * Match multi-word phrases in query
+     */
+    private matchPhrases;
+    /**
+     * Match individual keywords in query
+     */
+    private matchKeywords;
+    /**
+     * Find closest keyword using edit distance (for typo correction)
+     * Allows edit distance 1-2 depending on word length
+     */
+    private findFuzzyKeywordMatch;
+    /**
+     * Calculate Levenshtein (edit) distance between two strings
+     */
+    private levenshteinDistance;
+    /**
+     * Update type score with new match
+     */
+    private updateTypeScore;
+    /**
+     * Load pre-compiled type embeddings from embeddedTypeEmbeddings.ts
+     */
+    private loadTypeEmbeddings;
+    /**
+     * Lazy-load TransformerEmbedding model (only when vector fallback is triggered)
+     */
+    private loadEmbedder;
+    /**
+     * Calculate cosine similarity between two vectors
+     */
+    private cosineSimilarity;
+    /**
+     * Infer types using vector similarity against pre-compiled type embeddings
+     */
+    private inferTypesViaVectorSimilarity;
+    /**
+     * Merge keyword-based and vector-based results
+     * Prioritizes keyword results (explicit matches) over vector results (semantic matches)
+     */
+    private mergeResults;
+    /**
+     * Build keyword dictionary for single-word matching
+     */
+    private buildKeywordMap;
+    /**
+     * Build phrase dictionary for multi-word matching
+     */
+    private buildPhraseMap;
+    /**
+     * Get statistics about the inference system
+     */
+    getStats(): {
+        keywordCount: number;
+        phraseCount: number;
+        config: Required<TypeInferenceConfig>;
+    };
+}
+/**
+ * Get or create the global TypeInferenceSystem instance
+ */
+export declare function getTypeInferenceSystem(config?: TypeInferenceConfig): TypeInferenceSystem;
+/**
+ * Convenience function to infer types from a query
+ */
+export declare function inferTypes(query: string, config?: TypeInferenceConfig): TypeInference[];