@soulcraft/brainy 1.5.0 → 2.0.1

package/dist/neural/naturalLanguageProcessor.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 🧠 Natural Language Query Processor
+ * Auto-breaks down natural language into structured Triple Intelligence queries
+ *
+ * Uses all of Brainy's sophisticated features:
+ * - Embedding model for semantic understanding
+ * - Pattern library with 100+ research-based patterns
+ * - Entity Registry for concept mapping
+ * - Progressive learning from usage
+ */
+import { TripleQuery } from '../triple/TripleIntelligence.js';
+import { BrainyData } from '../brainyData.js';
+export interface NaturalQueryIntent {
+    type: 'vector' | 'field' | 'graph' | 'combined';
+    confidence: number;
+    extractedTerms: {
+        searchTerms?: string[];
+        fields?: Record<string, any>;
+        connections?: {
+            entities: string[];
+            relationships: string[];
+        };
+        filters?: Record<string, any>;
+        modifiers?: {
+            recent?: boolean;
+            popular?: boolean;
+            limit?: number;
+            boost?: string;
+        };
+    };
+}
+export declare class NaturalLanguageProcessor {
+    private brain;
+    private patternLibrary;
+    private queryHistory;
+    private initialized;
+    constructor(brain: BrainyData);
+    /**
+     * Initialize the pattern library (lazy loading)
+     */
+    private ensureInitialized;
+    /**
+     * 🎯 MAIN METHOD: Convert natural language to Triple Intelligence query
+     */
+    processNaturalQuery(naturalQuery: string): Promise<TripleQuery>;
+    /**
+     * Hybrid parse when pattern matching fails
+     */
+    private hybridParse;
+    /**
+     * Analyze intent using keywords and structure
+     */
+    private analyzeIntent;
+    /**
+     * Step 2: Use neural analysis to decompose complex queries
+     */
+    private decomposeQuery;
+    /**
+     * Step 3: Map concepts using Entity Registry and taxonomy
+     */
+    private mapConcepts;
+    /**
+     * Step 4: Construct final Triple Intelligence query
+     */
+    private constructTripleQuery;
+    /**
+     * Initialize pattern recognition for common query types
+     */
+    private initializePatterns;
+    /**
+     * Detect field query patterns
+     */
+    private hasFieldPatterns;
+    /**
+     * Detect connection query patterns
+     */
+    private hasConnectionPatterns;
+    /**
+     * Extract terms and modifiers from query
+     */
+    private extractTerms;
+    /**
+     * Find entity matches using Brainy's search capabilities
+     */
+    private findEntityMatches;
+    /**
+     * Check if term is a known field name
+     */
+    private isKnownField;
+    /**
+     * Map colloquial terms to actual field names
+     */
+    private mapToFieldName;
+}

package/dist/neural/naturalLanguageProcessor.js

@@ -0,0 +1,317 @@
+/**
+ * 🧠 Natural Language Query Processor
+ * Auto-breaks down natural language into structured Triple Intelligence queries
+ *
+ * Uses all of Brainy's sophisticated features:
+ * - Embedding model for semantic understanding
+ * - Pattern library with 100+ research-based patterns
+ * - Entity Registry for concept mapping
+ * - Progressive learning from usage
+ */
+import { PatternLibrary } from './patternLibrary.js';
+export class NaturalLanguageProcessor {
+    constructor(brain) {
+        this.initialized = false;
+        this.brain = brain;
+        this.patternLibrary = new PatternLibrary(brain);
+        this.queryHistory = [];
+    }
+    /**
+     * Initialize the pattern library (lazy loading)
+     */
+    async ensureInitialized() {
+        if (!this.initialized) {
+            await this.patternLibrary.init();
+            this.initialized = true;
+        }
+    }
+    /**
+     * 🎯 MAIN METHOD: Convert natural language to Triple Intelligence query
+     */
+    async processNaturalQuery(naturalQuery) {
+        await this.ensureInitialized();
+        // Step 1: Embed the query for semantic matching
+        const queryEmbedding = await this.brain.embed(naturalQuery);
+        // Step 2: Find best matching patterns from our library
+        const matches = await this.patternLibrary.findBestPatterns(queryEmbedding, 3);
+        // Step 3: Try each pattern until we get a good match
+        for (const { pattern, similarity } of matches) {
+            if (similarity < 0.5)
+                break; // Too low similarity, skip
+            // Extract slots from the query based on pattern
+            const extraction = this.patternLibrary.extractSlots(naturalQuery, pattern);
+            if (extraction.confidence > 0.6) {
+                // Fill the template with extracted slots
+                const query = this.patternLibrary.fillTemplate(pattern.template, extraction.slots);
+                // Track this query for learning
+                this.queryHistory.push({
+                    query: naturalQuery,
+                    result: query,
+                    success: true // Will be updated based on user behavior
+                });
+                // Update pattern success metric
+                this.patternLibrary.updateSuccessMetric(pattern.id, true);
+                return query;
+            }
+        }
+        // Step 4: Fall back to hybrid approach if no pattern matches well
+        return this.hybridParse(naturalQuery, queryEmbedding);
+    }
+    /**
+     * Hybrid parse when pattern matching fails
+     */
+    async hybridParse(query, queryEmbedding) {
+        // Analyze intent using embeddings and keywords
+        const intent = await this.analyzeIntent(query);
+        // Find similar successful queries from history
+        // TODO: Implement findSimilarQueries method
+        // const similar = await this.findSimilarQueries(queryEmbedding)
+        // if (similar.length > 0 && similar[0].similarity > 0.9) {
+        //   // Adapt a very similar previous query
+        //   return this.adaptQuery(query, similar[0].result)
+        // }
+        // Extract entities using Brainy's search
+        // TODO: Implement extractEntities method
+        // const entities = await this.extractEntities(query)
+        // Build query based on intent and entities
+        // TODO: Implement buildQuery method
+        // return this.buildQuery(query, intent, entities)
+        // Return a basic query for now
+        return {
+            like: query,
+            limit: 10
+        };
+    }
+    /**
+     * Analyze intent using keywords and structure
+     */
+    async analyzeIntent(query) {
+        // Use Brainy's embedding function to get semantic representation
+        const queryEmbedding = await this.brain.embed(query);
+        // Search for similar queries in history (if available)
+        let confidence = 0.7; // Base confidence
+        let type = 'vector'; // Default
+        // Analyze query structure patterns
+        const lowerQuery = query.toLowerCase();
+        // Detect field queries
+        if (this.hasFieldPatterns(lowerQuery)) {
+            type = 'field';
+            confidence += 0.2;
+        }
+        // Detect connection queries  
+        if (this.hasConnectionPatterns(lowerQuery)) {
+            type = type === 'field' ? 'combined' : 'graph';
+            confidence += 0.1;
+        }
+        // Extract basic terms
+        const extractedTerms = this.extractTerms(query);
+        return {
+            type,
+            confidence: Math.min(confidence, 1.0),
+            extractedTerms
+        };
+    }
+    /**
+     * Step 2: Use neural analysis to decompose complex queries
+     */
+    async decomposeQuery(query, intent) {
+        // Use Brainy's neural clustering to find similar patterns
+        const queryTerms = query.split(/\\s+/).filter(term => term.length > 2);
+        // Try to find existing entities that match query terms
+        const entityMatches = await this.findEntityMatches(queryTerms);
+        return {
+            originalQuery: query,
+            intent,
+            entityMatches,
+            queryTerms
+        };
+    }
+    /**
+     * Step 3: Map concepts using Entity Registry and taxonomy
+     */
+    async mapConcepts(decomposition) {
+        const mappedFields = {};
+        const searchTerms = [];
+        const connections = {};
+        // Use Entity Registry to map known entities
+        for (const term of decomposition.queryTerms) {
+            const entityMatch = decomposition.entityMatches.find((m) => m.term.toLowerCase() === term.toLowerCase());
+            if (entityMatch) {
+                if (entityMatch.type === 'field') {
+                    mappedFields[entityMatch.field] = entityMatch.value;
+                }
+                else if (entityMatch.type === 'entity') {
+                    connections[entityMatch.id] = entityMatch;
+                }
+            }
+            else {
+                searchTerms.push(term);
+            }
+        }
+        return {
+            searchTerms,
+            mappedFields,
+            connections
+        };
+    }
+    /**
+     * Step 4: Construct final Triple Intelligence query
+     */
+    constructTripleQuery(originalQuery, intent, mapped) {
+        const query = {};
+        // Set vector search if we have search terms
+        if (mapped.searchTerms.length > 0) {
+            query.like = mapped.searchTerms.join(' ');
+        }
+        else if (intent.type === 'vector') {
+            query.like = originalQuery;
+        }
+        // Set field filters if we found field mappings
+        if (Object.keys(mapped.mappedFields).length > 0) {
+            query.where = mapped.mappedFields;
+        }
+        // Set connection searches if we found entity connections
+        if (Object.keys(mapped.connections).length > 0) {
+            const entities = Object.keys(mapped.connections);
+            if (entities.length > 0) {
+                query.connected = { to: entities };
+            }
+        }
+        // Apply extracted modifiers
+        if (intent.extractedTerms.modifiers) {
+            const mods = intent.extractedTerms.modifiers;
+            if (mods.limit)
+                query.limit = mods.limit;
+            if (mods.boost)
+                query.boost = mods.boost;
+        }
+        return query;
+    }
+    /**
+     * Initialize pattern recognition for common query types
+     */
+    initializePatterns() {
+        const patterns = new Map();
+        // "Find papers about AI from 2023"
+        patterns.set(/find\\s+(.+?)\\s+about\\s+(.+?)\\s+from\\s+(\\d{4})/i, (match) => ({
+            like: match[2],
+            where: { year: parseInt(match[3]) }
+        }));
+        // "Show me recent posts by John"
+        patterns.set(/show\\s+me\\s+recent\\s+(.+?)\\s+by\\s+(.+)/i, (match) => ({
+            like: match[1],
+            boost: 'recent',
+            connected: { from: match[2] }
+        }));
+        // "Papers with more than 100 citations"  
+        patterns.set(/(.+?)\\s+with\\s+more\\s+than\\s+(\\d+)\\s+(.+)/i, (match) => ({
+            like: match[1],
+            where: { [match[3]]: { greaterThan: parseInt(match[2]) } }
+        }));
+        // "Documents related to Stanford"
+        patterns.set(/(.+?)\\s+related\\s+to\\s+(.+)/i, (match) => ({
+            like: match[1],
+            connected: { to: match[2] }
+        }));
+        return patterns;
+    }
+    /**
+     * Detect field query patterns
+     */
+    hasFieldPatterns(query) {
+        const fieldIndicators = [
+            'from', 'after', 'before', 'with more than', 'with less than',
+            'published', 'created', 'year', 'date', 'citations', 'score'
+        ];
+        return fieldIndicators.some(indicator => query.includes(indicator));
+    }
+    /**
+     * Detect connection query patterns
+     */
+    hasConnectionPatterns(query) {
+        const connectionIndicators = [
+            'by', 'from', 'connected to', 'related to', 'authored by',
+            'created by', 'associated with', 'linked to'
+        ];
+        return connectionIndicators.some(indicator => query.includes(indicator));
+    }
+    /**
+     * Extract terms and modifiers from query
+     */
+    extractTerms(query) {
+        const extracted = {};
+        // Extract limit numbers
+        const limitMatch = query.match(/(?:top|first|limit)\\s+(\\d+)/i);
+        if (limitMatch) {
+            extracted.modifiers = { limit: parseInt(limitMatch[1]) };
+        }
+        // Extract boost indicators
+        if (query.toLowerCase().includes('recent')) {
+            extracted.modifiers = { ...extracted.modifiers, boost: 'recent' };
+        }
+        if (query.toLowerCase().includes('popular')) {
+            extracted.modifiers = { ...extracted.modifiers, boost: 'popular' };
+        }
+        return extracted;
+    }
+    /**
+     * Find entity matches using Brainy's search capabilities
+     */
+    async findEntityMatches(terms) {
+        const matches = [];
+        for (const term of terms) {
+            try {
+                // Search for similar entities in the knowledge base
+                const results = await this.brain.search(term, { limit: 5 });
+                for (const result of results) {
+                    if (result.score > 0.8) { // High similarity threshold
+                        matches.push({
+                            term,
+                            id: result.id,
+                            type: 'entity',
+                            confidence: result.score,
+                            metadata: result.metadata
+                        });
+                    }
+                }
+                // Check if term matches known field names
+                if (this.isKnownField(term)) {
+                    matches.push({
+                        term,
+                        type: 'field',
+                        field: this.mapToFieldName(term),
+                        confidence: 0.9
+                    });
+                }
+            }
+            catch (error) {
+                // If search fails, continue with other terms
+                console.debug(`Failed to search for term: ${term}`, error);
+            }
+        }
+        return matches;
+    }
+    /**
+     * Check if term is a known field name
+     */
+    isKnownField(term) {
+        const knownFields = [
+            'year', 'date', 'created', 'published', 'author', 'title',
+            'citations', 'views', 'score', 'rating', 'category', 'type'
+        ];
+        return knownFields.includes(term.toLowerCase());
+    }
+    /**
+     * Map colloquial terms to actual field names
+     */
+    mapToFieldName(term) {
+        const fieldMappings = {
+            'published': 'publishDate',
+            'created': 'createdAt',
+            'author': 'authorId',
+            'citations': 'citationCount'
+        };
+        return fieldMappings[term.toLowerCase()] || term.toLowerCase();
+    }
+}
+//# sourceMappingURL=naturalLanguageProcessor.js.map

package/dist/neural/naturalLanguageProcessorStatic.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 🧠 Natural Language Query Processor - STATIC VERSION
+ * No runtime initialization, no memory leaks, patterns pre-built at compile time
+ *
+ * Uses static pattern matching with 220 pre-built patterns
+ */
+import { Vector } from '../coreTypes.js';
+import { TripleQuery } from '../triple/TripleIntelligence.js';
+export interface NaturalQueryIntent {
+    type: 'vector' | 'field' | 'graph' | 'combined';
+    confidence: number;
+    extractedTerms: {
+        entities?: string[];
+        fields?: string[];
+        relationships?: string[];
+        modifiers?: string[];
+    };
+}
+export declare class NaturalLanguageProcessor {
+    private queryHistory;
+    constructor();
+    /**
+     * No initialization needed - patterns are pre-built!
+     */
+    init(): Promise<void>;
+    /**
+     * Process natural language query into structured Triple Intelligence query
+     * @param naturalQuery The natural language query string
+     * @param queryEmbedding Pre-computed embedding from BrainyData (passed in to avoid circular dependency)
+     */
+    processNaturalQuery(naturalQuery: string, queryEmbedding?: Vector): Promise<TripleQuery>;
+    /**
+     * Analyze query intent using keywords
+     */
+    private analyzeIntent;
+    /**
+     * Extract field terms from query
+     */
+    private extractFieldTerms;
+    /**
+     * Extract relationship terms
+     */
+    private extractRelationshipTerms;
+    /**
+     * Build field constraints from extracted terms
+     */
+    private buildFieldConstraints;
+    /**
+     * Find similar queries from history (without using BrainyData)
+     */
+    private findSimilarQueries;
+    /**
+     * Adapt a previous query for new input
+     */
+    private adaptQuery;
+    /**
+     * Extract entities from query
+     */
+    private extractEntities;
+    /**
+     * Build query from components
+     */
+    private buildQuery;
+}

package/dist/neural/naturalLanguageProcessorStatic.js

@@ -0,0 +1,151 @@
+/**
+ * 🧠 Natural Language Query Processor - STATIC VERSION
+ * No runtime initialization, no memory leaks, patterns pre-built at compile time
+ *
+ * Uses static pattern matching with 220 pre-built patterns
+ */
+import { patternMatchQuery } from './staticPatternMatcher.js';
+export class NaturalLanguageProcessor {
+    constructor() {
+        this.queryHistory = [];
+        // Patterns are static - no initialization needed!
+    }
+    /**
+     * No initialization needed - patterns are pre-built!
+     */
+    async init() {
+        // Nothing to do - patterns are compiled into the code
+        return Promise.resolve();
+    }
+    /**
+     * Process natural language query into structured Triple Intelligence query
+     * @param naturalQuery The natural language query string
+     * @param queryEmbedding Pre-computed embedding from BrainyData (passed in to avoid circular dependency)
+     */
+    async processNaturalQuery(naturalQuery, queryEmbedding) {
+        // Use static pattern matcher (no async, no memory allocation!)
+        const structuredQuery = patternMatchQuery(naturalQuery, queryEmbedding);
+        // Step 3: Enhance with intent analysis if needed
+        if (!structuredQuery.where && !structuredQuery.connected) {
+            const intent = await this.analyzeIntent(naturalQuery);
+            // Add metadata based on intent
+            if (intent.type === 'field' && intent.extractedTerms.fields) {
+                structuredQuery.where = this.buildFieldConstraints(intent.extractedTerms.fields);
+            }
+        }
+        // Track for learning (but don't create new BrainyData!)
+        this.queryHistory.push({
+            query: naturalQuery,
+            result: structuredQuery,
+            success: false // Will be updated based on user interaction
+        });
+        // Keep history limited to prevent memory growth
+        if (this.queryHistory.length > 100) {
+            this.queryHistory.shift();
+        }
+        return structuredQuery;
+    }
+    /**
+     * Analyze query intent using keywords
+     */
+    async analyzeIntent(query) {
+        const lowerQuery = query.toLowerCase();
+        // Check for field-specific keywords
+        const fieldKeywords = ['where', 'filter', 'with', 'has', 'contains', 'equals', 'greater', 'less', 'between'];
+        const hasFieldIntent = fieldKeywords.some(kw => lowerQuery.includes(kw));
+        // Check for graph keywords
+        const graphKeywords = ['related', 'connected', 'linked', 'associated', 'references'];
+        const hasGraphIntent = graphKeywords.some(kw => lowerQuery.includes(kw));
+        // Determine type
+        let type = 'vector';
+        if (hasFieldIntent && hasGraphIntent) {
+            type = 'combined';
+        }
+        else if (hasFieldIntent) {
+            type = 'field';
+        }
+        else if (hasGraphIntent) {
+            type = 'graph';
+        }
+        return {
+            type,
+            confidence: 0.8,
+            extractedTerms: {
+                fields: hasFieldIntent ? this.extractFieldTerms(query) : undefined,
+                relationships: hasGraphIntent ? this.extractRelationshipTerms(query) : undefined
+            }
+        };
+    }
+    /**
+     * Extract field terms from query
+     */
+    extractFieldTerms(query) {
+        const terms = [];
+        // Simple extraction of potential field names
+        const words = query.split(/\s+/);
+        const fieldIndicators = ['year', 'date', 'author', 'type', 'category', 'status', 'price'];
+        for (const word of words) {
+            if (fieldIndicators.includes(word.toLowerCase())) {
+                terms.push(word.toLowerCase());
+            }
+        }
+        return terms;
+    }
+    /**
+     * Extract relationship terms
+     */
+    extractRelationshipTerms(query) {
+        const terms = [];
+        const relationshipWords = ['related', 'connected', 'linked', 'references', 'cites'];
+        const words = query.toLowerCase().split(/\s+/);
+        for (const word of words) {
+            if (relationshipWords.includes(word)) {
+                terms.push(word);
+            }
+        }
+        return terms;
+    }
+    /**
+     * Build field constraints from extracted terms
+     */
+    buildFieldConstraints(fields) {
+        const constraints = {};
+        // Simple mapping for common fields
+        for (const field of fields) {
+            // This would be enhanced with actual value extraction
+            constraints[field] = { exists: true };
+        }
+        return constraints;
+    }
+    /**
+     * Find similar queries from history (without using BrainyData)
+     */
+    findSimilarQueries(embedding) {
+        // Simple similarity check against recent history
+        // This is just a placeholder - real implementation would use cosine similarity
+        return [];
+    }
+    /**
+     * Adapt a previous query for new input
+     */
+    adaptQuery(newQuery, previousResult) {
+        return previousResult;
+    }
+    /**
+     * Extract entities from query
+     */
+    async extractEntities(query) {
+        // Could use the Entity Registry here if available
+        return [];
+    }
+    /**
+     * Build query from components
+     */
+    buildQuery(query, intent, entities) {
+        return {
+            like: query,
+            limit: 10
+        };
+    }
+}
+//# sourceMappingURL=naturalLanguageProcessorStatic.js.map