@soulcraft/brainy 3.9.0 → 3.10.0

package/dist/brainy.js

@@ -14,6 +14,7 @@ import { createDefaultAugmentations } from './augmentations/defaultAugmentations
 import { ImprovedNeuralAPI } from './neural/improvedNeuralAPI.js';
 import { NaturalLanguageProcessor } from './neural/naturalLanguageProcessor.js';
 import { TripleIntelligenceSystem } from './triple/TripleIntelligenceSystem.js';
+import { VirtualFileSystem } from './vfs/VirtualFileSystem.js';
 import { MetadataIndexManager } from './utils/metadataIndex.js';
 import { GraphAdjacencyIndex } from './graph/graphAdjacencyIndex.js';
 import { createPipeline } from './streaming/pipeline.js';
@@ -138,6 +139,12 @@ export class Brainy {
             throw new Error('Brainy not initialized. Call init() first.');
         }
     }
+    /**
+     * Check if Brainy is initialized
+     */
+    get isInitialized() {
+        return this.initialized;
+    }
     // ============= CORE CRUD OPERATIONS =============
     /**
      * Add an entity to the database
@@ -895,6 +902,15 @@ export class Brainy {
         }
         return this._nlp;
     }
+    /**
+     * Virtual File System API - Knowledge Operating System
+     */
+    vfs() {
+        if (!this._vfs) {
+            this._vfs = new VirtualFileSystem(this);
+        }
+        return this._vfs;
+    }
     /**
      * Data Management API - backup, restore, import, export
      */
@@ -1448,9 +1464,79 @@ export class Brainy {
     }
     /**
      * Embed data into vector
+     * Handles any data type by converting to string representation
      */
     async embed(data) {
-        return this.embedder(data);
+        // Handle different data types intelligently
+        let textToEmbed;
+        if (typeof data === 'string') {
+            textToEmbed = data;
+        }
+        else if (Array.isArray(data)) {
+            // Array of items - convert each to string
+            textToEmbed = data.map(item => {
+                if (typeof item === 'string')
+                    return item;
+                if (typeof item === 'number' || typeof item === 'boolean')
+                    return String(item);
+                if (item && typeof item === 'object') {
+                    // For objects, try to extract meaningful text
+                    if (item.data)
+                        return String(item.data);
+                    if (item.content)
+                        return String(item.content);
+                    if (item.text)
+                        return String(item.text);
+                    if (item.name)
+                        return String(item.name);
+                    if (item.title)
+                        return String(item.title);
+                    if (item.description)
+                        return String(item.description);
+                    // Fallback to JSON for complex objects
+                    try {
+                        return JSON.stringify(item);
+                    }
+                    catch {
+                        return String(item);
+                    }
+                }
+                return String(item);
+            });
+        }
+        else if (data && typeof data === 'object') {
+            // Single object - extract meaningful text
+            if (data.data)
+                textToEmbed = String(data.data);
+            else if (data.content)
+                textToEmbed = String(data.content);
+            else if (data.text)
+                textToEmbed = String(data.text);
+            else if (data.name)
+                textToEmbed = String(data.name);
+            else if (data.title)
+                textToEmbed = String(data.title);
+            else if (data.description)
+                textToEmbed = String(data.description);
+            else {
+                // For complex objects, create a descriptive string
+                try {
+                    textToEmbed = JSON.stringify(data);
+                }
+                catch {
+                    textToEmbed = String(data);
+                }
+            }
+        }
+        else if (data === null || data === undefined) {
+            // Handle null/undefined gracefully
+            textToEmbed = '';
+        }
+        else {
+            // Numbers, booleans, etc - convert to string
+            textToEmbed = String(data);
+        }
+        return this.embedder(textToEmbed);
     }
     /**
      * Warm up the system

package/dist/embeddings/EmbeddingManager.js

@@ -165,8 +165,20 @@ export class EmbeddingManager {
         if (!this.model) {
             throw new Error('Model not initialized');
         }
-        // Handle array input
-        const input = Array.isArray(text) ? text.join(' ') : text;
+        // CRITICAL FIX: Ensure input is always a string
+        let input;
+        if (Array.isArray(text)) {
+            // Join array elements, converting each to string first
+            input = text.map(t => typeof t === 'string' ? t : String(t)).join(' ');
+        }
+        else if (typeof text === 'string') {
+            input = text;
+        }
+        else {
+            // This shouldn't happen but let's be defensive
+            console.warn('EmbeddingManager.embed received non-string input:', typeof text);
+            input = String(text);
+        }
         // Generate embedding
         const output = await this.model(input, {
             pooling: 'mean',

package/dist/utils/mutex.d.ts

@@ -29,7 +29,9 @@ export declare class FileMutex implements MutexInterface {
     private lockDir;
     private processLocks;
     private lockTimers;
+    private modulesLoaded;
     constructor(lockDir: string);
+    private loadNodeModules;
     acquire(key: string, timeout?: number): Promise<() => void>;
     private release;
     runExclusive<T>(key: string, fn: () => Promise<T>, timeout?: number): Promise<T>;

package/dist/utils/mutex.js

@@ -74,14 +74,25 @@ export class FileMutex {
     constructor(lockDir) {
         this.processLocks = new Map();
         this.lockTimers = new Map();
+        this.modulesLoaded = false;
         this.lockDir = lockDir;
-        // Lazy load Node.js modules
+    }
+    async loadNodeModules() {
+        if (this.modulesLoaded)
+            return;
         if (typeof window === 'undefined') {
-            this.fs = require('fs');
-            this.path = require('path');
+            // Modern ESM-compatible dynamic imports
+            const [fs, path] = await Promise.all([
+                import('fs'),
+                import('path')
+            ]);
+            this.fs = fs;
+            this.path = path;
+            this.modulesLoaded = true;
         }
     }
     async acquire(key, timeout = 30000) {
+        await this.loadNodeModules();
         if (!this.fs || !this.path) {
             throw new Error('FileMutex is only available in Node.js environments');
         }

package/dist/vfs/ConceptSystem.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Universal Concept System for VFS
+ *
+ * Manages concepts that transcend files and exist independently
+ * Ideas that can be linked to multiple manifestations across domains
+ * PRODUCTION-READY: Real implementation using Brainy
+ */
+import { Brainy } from '../brainy.js';
+/**
+ * Universal concept that exists independently of files
+ */
+export interface UniversalConcept {
+    id: string;
+    name: string;
+    description?: string;
+    domain: string;
+    category: string;
+    keywords: string[];
+    links: ConceptLink[];
+    manifestations: ConceptManifestation[];
+    strength: number;
+    created: number;
+    lastUpdated: number;
+    version: number;
+    metadata: Record<string, any>;
+}
+/**
+ * A link between concepts
+ */
+export interface ConceptLink {
+    id: string;
+    targetConceptId: string;
+    relationship: 'extends' | 'implements' | 'uses' | 'opposite' | 'related' | 'contains' | 'part-of';
+    strength: number;
+    context?: string;
+    bidirectional: boolean;
+}
+/**
+ * A manifestation of a concept in a specific location
+ */
+export interface ConceptManifestation {
+    id: string;
+    conceptId: string;
+    filePath: string;
+    context: string;
+    form: 'definition' | 'usage' | 'example' | 'discussion' | 'implementation';
+    position?: {
+        line?: number;
+        column?: number;
+        offset?: number;
+    };
+    confidence: number;
+    timestamp: number;
+    extractedBy: 'manual' | 'auto' | 'ai';
+}
+/**
+ * Configuration for concept system
+ */
+export interface ConceptSystemConfig {
+    autoLink?: boolean;
+    similarityThreshold?: number;
+    maxManifestations?: number;
+    strengthDecay?: number;
+}
+/**
+ * Concept graph structure for visualization
+ */
+export interface ConceptGraph {
+    concepts: Array<{
+        id: string;
+        name: string;
+        domain: string;
+        strength: number;
+        manifestationCount: number;
+    }>;
+    links: Array<{
+        source: string;
+        target: string;
+        relationship: string;
+        strength: number;
+    }>;
+}
+/**
+ * Universal Concept System
+ *
+ * Manages concepts that exist independently of any specific file or context
+ * Examples:
+ * - "Authentication" concept appearing in docs, code, tests
+ * - "Customer Journey" concept in marketing, UX, analytics
+ * - "Dependency Injection" pattern across multiple codebases
+ * - "Sustainability" theme in various research papers
+ */
+export declare class ConceptSystem {
+    private brain;
+    private config;
+    private conceptCache;
+    constructor(brain: Brainy, config?: ConceptSystemConfig);
+    /**
+     * Create a new universal concept
+     */
+    createConcept(concept: Omit<UniversalConcept, 'id' | 'created' | 'lastUpdated' | 'version' | 'links' | 'manifestations'>): Promise<string>;
+    /**
+     * Find concepts by various criteria
+     */
+    findConcepts(query: {
+        name?: string;
+        domain?: string;
+        category?: string;
+        keywords?: string[];
+        similar?: string;
+        manifestedIn?: string;
+    }): Promise<UniversalConcept[]>;
+    /**
+     * Link two concepts together
+     */
+    linkConcept(fromConceptId: string, toConceptId: string, relationship: ConceptLink['relationship'], options?: {
+        strength?: number;
+        context?: string;
+        bidirectional?: boolean;
+    }): Promise<string>;
+    /**
+     * Record a manifestation of a concept in a file
+     */
+    recordManifestation(conceptId: string, filePath: string, context: string, form: ConceptManifestation['form'], options?: {
+        position?: ConceptManifestation['position'];
+        confidence?: number;
+        extractedBy?: ConceptManifestation['extractedBy'];
+    }): Promise<string>;
+    /**
+     * Extract and link concepts from content
+     */
+    extractAndLinkConcepts(filePath: string, content: Buffer): Promise<string[]>;
+    /**
+     * Get concept graph for visualization
+     */
+    getConceptGraph(options?: {
+        domain?: string;
+        minStrength?: number;
+        maxConcepts?: number;
+    }): Promise<ConceptGraph>;
+    /**
+     * Find appearances of a concept
+     */
+    findAppearances(conceptId: string, options?: {
+        filePath?: string;
+        form?: ConceptManifestation['form'];
+        minConfidence?: number;
+        limit?: number;
+    }): Promise<ConceptManifestation[]>;
+    /**
+     * Auto-link concept to similar concepts
+     */
+    private autoLinkConcept;
+    /**
+     * Get concept by ID
+     */
+    private getConcept;
+    /**
+     * Update stored concept
+     */
+    private updateConcept;
+    /**
+     * Calculate similarity between two concepts
+     */
+    private calculateConceptSimilarity;
+    /**
+     * Generate embedding for concept
+     */
+    private generateConceptEmbedding;
+    /**
+     * Generate embedding for text
+     */
+    private generateTextEmbedding;
+    /**
+     * Get reverse relationship type
+     */
+    private getReverseRelationship;
+    /**
+     * Map concept relationship to VerbType
+     */
+    private getVerbType;
+    /**
+     * Detect concept domain from context
+     */
+    private detectDomain;
+    /**
+     * Detect concept category
+     */
+    private detectCategory;
+    /**
+     * Detect manifestation form from context
+     */
+    private detectManifestationForm;
+    /**
+     * Extract context around a position
+     */
+    private extractContext;
+    /**
+     * Clear concept cache
+     */
+    clearCache(conceptId?: string): void;
+}