@soulcraft/brainy 3.13.0 → 3.14.1

package/README.md

@@ -209,54 +209,65 @@ await brain.find("Popular JavaScript libraries similar to Vue")
 await brain.find("Documentation about authentication from last month")
 ```
 
-### 🧠🌐 **Knowledge Graph + Virtual Filesystem - Where Ideas Come Alive**
+### 🧠🌐 **Virtual Filesystem - Intelligent File Management**
 
-**Store ANY knowledge. Connect EVERYTHING. Files are optional.**
+**Build file explorers, IDEs, and knowledge systems that never crash from infinite recursion.**
 
-- **Living Knowledge**: Characters, concepts, and systems that exist independently of files
-- **Universal Connections**: Link files to entities, entities to concepts, anything to anything
-- **Semantic Intelligence**: Find knowledge by meaning, not by where it's stored
-- **Optional Files**: Use filesystem operations when helpful, pure knowledge when not
-- **Perfect Memory**: Every piece of knowledge remembers its entire history
-- **Knowledge Evolution**: Watch ideas grow and connect across time and projects
+- **Tree-Aware Operations**: Safe directory listing prevents recursive loops
+- **Semantic Search**: Find files by content, not just filename
+- **Production Storage**: Filesystem and cloud storage for real applications
+- **Zero-Config**: Works out of the box with intelligent defaults
 
 ```javascript
 import { Brainy } from '@soulcraft/brainy'
 
-const brain = new Brainy({ storage: { type: 'memory' } })
+// ✅ CORRECT: Use persistent storage for file systems
+const brain = new Brainy({
+  storage: {
+    type: 'filesystem',    // Persisted to disk
+    path: './brainy-data'  // Your file storage
+  }
+})
 await brain.init()
+
 const vfs = brain.vfs()
 await vfs.init()
 
-// Start with familiar files if you want
-await vfs.writeFile('/story.txt', 'A tale of adventure...')
+// ✅ Safe file operations
+await vfs.writeFile('/projects/app/index.js', 'console.log("Hello")')
+await vfs.mkdir('/docs')
+await vfs.writeFile('/docs/README.md', '# My Project')
 
-// But knowledge doesn't need files!
-const alice = await vfs.createEntity({
-  name: 'Alice',
-  type: 'character',
-  description: 'Brave explorer discovering quantum worlds'
-})
+// ✅ NEVER crashes: Tree-aware directory listing
+const children = await vfs.getDirectChildren('/projects')
+// Returns only direct children, never the directory itself
 
-const quantumPhysics = await vfs.createConcept({
-  name: 'Quantum Entanglement',
-  domain: 'physics',
-  keywords: ['superposition', 'measurement', 'correlation']
+// ✅ Build file explorers safely
+const tree = await vfs.getTreeStructure('/projects', {
+  maxDepth: 3,          // Prevent deep recursion
+  sort: 'name'         // Organized results
 })
 
-// Connect EVERYTHING - files, entities, concepts
-await vfs.linkEntities(alice, quantumPhysics, 'studies')
-await vfs.addRelationship('/story.txt', alice.id, 'features')
+// ✅ Semantic file search
+const reactFiles = await vfs.search('React components with hooks')
+const docs = await vfs.search('API documentation', {
+  path: '/docs'  // Search within specific directory
+})
 
-// Find knowledge by meaning, not location
-const physics = await vfs.search('quantum mechanics')
-// Returns: files, entities, concepts, relationships - ALL knowledge
+// ✅ Connect related files
+await vfs.addRelationship('/src/auth.js', '/tests/auth.test.js', 'tested-by')
 
-// Knowledge transcends boundaries
-const aliceKnowledge = await vfs.getEntityGraph(alice)
-// Her relationships, appearances, evolution - her entire existence
+// Perfect for: File explorers, IDEs, documentation systems, code analysis
 ```
 
+**🚨 Prevents Common Mistakes:**
+- ❌ No infinite recursion in file trees (like brain-cloud team experienced)
+- ❌ No data loss from memory storage
+- ❌ No performance issues with large directories
+- ❌ No need for complex fallback patterns
+
+**[📖 VFS Quick Start →](docs/vfs/QUICK_START.md)** | **[🎯 Common Patterns →](docs/vfs/COMMON_PATTERNS.md)**
+
 **Your knowledge isn't trapped anymore.** Characters live beyond stories. APIs exist beyond code files. Concepts connect across domains. This is knowledge that happens to support files, not a filesystem that happens to store knowledge.
 
 ### 🎯 Zero Configuration Philosophy

package/dist/brainy.d.ts

@@ -56,10 +56,122 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
     get isInitialized(): boolean;
     /**
      * Add an entity to the database
+     *
+     * @param params - Parameters for adding the entity
+     * @returns Promise that resolves to the entity ID
+     *
+     * @example Basic entity creation
+     * ```typescript
+     * const id = await brain.add({
+     *   data: "John Smith is a software engineer",
+     *   type: NounType.Person,
+     *   metadata: { role: "engineer", team: "backend" }
+     * })
+     * console.log(`Created entity: ${id}`)
+     * ```
+     *
+     * @example Adding with custom ID
+     * ```typescript
+     * const customId = await brain.add({
+     *   id: "user-12345",
+     *   data: "Important document content",
+     *   type: NounType.Document,
+     *   metadata: { priority: "high", department: "legal" }
+     * })
+     * ```
+     *
+     * @example Using pre-computed vector (optimization)
+     * ```typescript
+     * const vector = await brain.embed("Optimized content")
+     * const id = await brain.add({
+     *   data: "Optimized content",
+     *   type: NounType.Document,
+     *   vector: vector,  // Skip re-embedding
+     *   metadata: { optimized: true }
+     * })
+     * ```
+     *
+     * @example Multi-tenant usage
+     * ```typescript
+     * const id = await brain.add({
+     *   data: "Customer feedback",
+     *   type: NounType.Message,
+     *   service: "customer-portal",  // Multi-tenancy
+     *   metadata: { rating: 5, verified: true }
+     * })
+     * ```
      */
     add(params: AddParams<T>): Promise<string>;
     /**
      * Get an entity by ID
+     *
+     * @param id - The unique identifier of the entity to retrieve
+     * @returns Promise that resolves to the entity if found, null if not found
+     *
+     * @example
+     * // Basic entity retrieval
+     * const entity = await brainy.get('user-123')
+     * if (entity) {
+     *   console.log('Found entity:', entity.data)
+     *   console.log('Created at:', new Date(entity.createdAt))
+     * } else {
+     *   console.log('Entity not found')
+     * }
+     *
+     * @example
+     * // Working with typed entities
+     * interface User {
+     *   name: string
+     *   email: string
+     * }
+     *
+     * const brainy = new Brainy<User>({ storage: 'filesystem' })
+     * const user = await brainy.get('user-456')
+     * if (user) {
+     *   // TypeScript knows user.metadata is of type User
+     *   console.log(`Hello ${user.metadata.name}`)
+     * }
+     *
+     * @example
+     * // Safe retrieval with error handling
+     * try {
+     *   const entity = await brainy.get('document-789')
+     *   if (!entity) {
+     *     throw new Error('Document not found')
+     *   }
+     *
+     *   // Process the entity
+     *   return {
+     *     id: entity.id,
+     *     content: entity.data,
+     *     type: entity.type,
+     *     metadata: entity.metadata
+     *   }
+     * } catch (error) {
+     *   console.error('Failed to retrieve entity:', error)
+     *   return null
+     * }
+     *
+     * @example
+     * // Batch retrieval pattern
+     * const ids = ['doc-1', 'doc-2', 'doc-3']
+     * const entities = await Promise.all(
+     *   ids.map(id => brainy.get(id))
+     * )
+     * const foundEntities = entities.filter(entity => entity !== null)
+     * console.log(`Found ${foundEntities.length} out of ${ids.length} entities`)
+     *
+     * @example
+     * // Using with async iteration
+     * const entityIds = ['user-1', 'user-2', 'user-3']
+     *
+     * for (const id of entityIds) {
+     *   const entity = await brainy.get(id)
+     *   if (entity) {
+     *     console.log(`Processing ${entity.type}: ${id}`)
+     *     // Process entity...
+     *   }
+     * }
      */
     get(id: string): Promise<Entity<T> | null>;
     /**
@@ -76,6 +188,107 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
     delete(id: string): Promise<void>;
     /**
      * Create a relationship between entities
+     *
+     * @param params - Parameters for creating the relationship
+     * @returns Promise that resolves to the relationship ID
+     *
+     * @example
+     * // Basic relationship creation
+     * const userId = await brainy.add({
+     *   data: { name: 'John', role: 'developer' },
+     *   type: NounType.Person
+     * })
+     * const projectId = await brainy.add({
+     *   data: { name: 'AI Assistant', status: 'active' },
+     *   type: NounType.Thing
+     * })
+     *
+     * const relationId = await brainy.relate({
+     *   from: userId,
+     *   to: projectId,
+     *   type: VerbType.WorksOn
+     * })
+     *
+     * @example
+     * // Bidirectional relationships
+     * const friendshipId = await brainy.relate({
+     *   from: 'user-1',
+     *   to: 'user-2',
+     *   type: VerbType.Knows,
+     *   bidirectional: true // Creates both directions automatically
+     * })
+     *
+     * @example
+     * // Weighted relationships for importance/strength
+     * const collaborationId = await brainy.relate({
+     *   from: 'team-lead',
+     *   to: 'project-alpha',
+     *   type: VerbType.LeadsOn,
+     *   weight: 0.9, // High importance/strength
+     *   metadata: {
+     *     startDate: '2024-01-15',
+     *     responsibility: 'technical leadership',
+     *     hoursPerWeek: 40
+     *   }
+     * })
+     *
+     * @example
+     * // Typed relationships with custom metadata
+     * interface CollaborationMeta {
+     *   role: string
+     *   startDate: string
+     *   skillLevel: number
+     * }
+     *
+     * const brainy = new Brainy<CollaborationMeta>({ storage: 'filesystem' })
+     * const relationId = await brainy.relate({
+     *   from: 'developer-123',
+     *   to: 'project-456',
+     *   type: VerbType.WorksOn,
+     *   weight: 0.85,
+     *   metadata: {
+     *     role: 'frontend developer',
+     *     startDate: '2024-03-01',
+     *     skillLevel: 8
+     *   }
+     * })
+     *
+     * @example
+     * // Creating complex relationship networks
+     * const entities = []
+     * // Create entities
+     * for (let i = 0; i < 5; i++) {
+     *   const id = await brainy.add({
+     *     data: { name: `Entity ${i}`, value: i * 10 },
+     *     type: NounType.Thing
+     *   })
+     *   entities.push(id)
+     * }
+     *
+     * // Create hierarchical relationships
+     * for (let i = 0; i < entities.length - 1; i++) {
+     *   await brainy.relate({
+     *     from: entities[i],
+     *     to: entities[i + 1],
+     *     type: VerbType.DependsOn,
+     *     weight: (i + 1) / entities.length
+     *   })
+     * }
+     *
+     * @example
+     * // Error handling for invalid relationships
+     * try {
+     *   await brainy.relate({
+     *     from: 'nonexistent-entity',
+     *     to: 'another-entity',
+     *     type: VerbType.RelatedTo
+     *   })
+     * } catch (error) {
+     *   if (error.message.includes('not found')) {
+     *     console.log('One or both entities do not exist')
+     *     // Handle missing entities...
+     *   }
+     * }
      */
     relate(params: RelateParams<T>): Promise<string>;
     /**
@@ -89,10 +302,252 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
     /**
      * Unified find method - supports natural language and structured queries
      * Implements Triple Intelligence with parallel search optimization
+     *
+     * @param query - Natural language string or structured FindParams object
+     * @returns Promise that resolves to array of search results with scores
+     *
+     * @example
+     * // Natural language queries (most common)
+     * const results = await brainy.find('users who work on AI projects')
+     * const docs = await brainy.find('documents about machine learning')
+     * const code = await brainy.find('JavaScript functions for data processing')
+     *
+     * @example
+     * // Structured queries with filtering
+     * const results = await brainy.find({
+     *   query: 'artificial intelligence',
+     *   type: NounType.Document,
+     *   limit: 5,
+     *   where: {
+     *     status: 'published',
+     *     author: 'expert'
+     *   }
+     * })
+     *
+     * // Process results
+     * for (const result of results) {
+     *   console.log(`Found: ${result.entity.data} (score: ${result.score})`)
+     * }
+     *
+     * @example
+     * // Metadata-only filtering (no vector search)
+     * const activeUsers = await brainy.find({
+     *   type: NounType.Person,
+     *   where: {
+     *     status: 'active',
+     *     department: 'engineering'
+     *   },
+     *   service: 'user-management'
+     * })
+     *
+     * @example
+     * // Vector similarity search with custom vectors
+     * const queryVector = await brainy.embed('machine learning algorithms')
+     * const similar = await brainy.find({
+     *   vector: queryVector,
+     *   limit: 10,
+     *   type: [NounType.Document, NounType.Thing]
+     * })
+     *
+     * @example
+     * // Proximity search (find entities similar to existing ones)
+     * const relatedContent = await brainy.find({
+     *   near: 'document-123', // Find entities similar to this one
+     *   limit: 8,
+     *   where: {
+     *     published: true
+     *   }
+     * })
+     *
+     * @example
+     * // Pagination for large result sets
+     * const firstPage = await brainy.find({
+     *   query: 'research papers',
+     *   limit: 20,
+     *   offset: 0
+     * })
+     *
+     * const secondPage = await brainy.find({
+     *   query: 'research papers',
+     *   limit: 20,
+     *   offset: 20
+     * })
+     *
+     * @example
+     * // Complex search with multiple criteria
+     * const results = await brainy.find({
+     *   query: 'machine learning models',
+     *   type: [NounType.Thing, NounType.Document],
+     *   where: {
+     *     accuracy: { $gte: 0.9 }, // Metadata filtering
+     *     framework: { $in: ['tensorflow', 'pytorch'] }
+     *   },
+     *   service: 'ml-pipeline',
+     *   limit: 15
+     * })
+     *
+     * @example
+     * // Empty query returns all entities (paginated)
+     * const allEntities = await brainy.find({
+     *   limit: 50,
+     *   offset: 0
+     * })
+     *
+     * @example
+     * // Performance-optimized search patterns
+     * // Fast metadata-only search (no vector computation)
+     * const fastResults = await brainy.find({
+     *   type: NounType.Person,
+     *   where: { active: true },
+     *   limit: 100
+     * })
+     *
+     * // Combined vector + metadata for precision
+     * const preciseResults = await brainy.find({
+     *   query: 'senior developers',
+     *   where: {
+     *     experience: { $gte: 5 },
+     *     skills: { $includes: 'javascript' }
+     *   },
+     *   limit: 10
+     * })
+     *
+     * @example
+     * // Error handling and result processing
+     * try {
+     *   const results = await brainy.find('complex query here')
+     *
+     *   if (results.length === 0) {
+     *     console.log('No results found')
+     *     return
+     *   }
+     *
+     *   // Filter by confidence threshold
+     *   const highConfidence = results.filter(r => r.score > 0.7)
+     *
+     *   // Sort by score (already sorted by default)
+     *   const topResults = results.slice(0, 5)
+     *
+     *   return topResults.map(r => ({
+     *     id: r.id,
+     *     content: r.entity.data,
+     *     confidence: r.score,
+     *     metadata: r.entity.metadata
+     *   }))
+     * } catch (error) {
+     *   console.error('Search failed:', error)
+     *   return []
+     * }
      */
     find(query: string | FindParams<T>): Promise<Result<T>[]>;
     /**
-     * Find similar entities
+     * Find similar entities using vector similarity
+     *
+     * @param params - Parameters specifying the target for similarity search
+     * @returns Promise that resolves to array of similar entities with similarity scores
+     *
+     * @example
+     * // Find entities similar to a specific entity by ID
+     * const similarDocs = await brainy.similar({
+     *   to: 'document-123',
+     *   limit: 10
+     * })
+     *
+     * // Process similarity results
+     * for (const result of similarDocs) {
+     *   console.log(`Similar entity: ${result.entity.data} (similarity: ${result.score})`)
+     * }
+     *
+     * @example
+     * // Find similar entities with type filtering
+     * const similarUsers = await brainy.similar({
+     *   to: 'user-456',
+     *   type: NounType.Person,
+     *   limit: 5,
+     *   where: {
+     *     active: true,
+     *     department: 'engineering'
+     *   }
+     * })
+     *
+     * @example
+     * // Find similar using a custom vector
+     * const customVector = await brainy.embed('artificial intelligence research')
+     * const similar = await brainy.similar({
+     *   to: customVector,
+     *   limit: 8,
+     *   type: [NounType.Document, NounType.Thing]
+     * })
+     *
+     * @example
+     * // Find similar using an entity object
+     * const sourceEntity = await brainy.get('research-paper-789')
+     * if (sourceEntity) {
+     *   const relatedPapers = await brainy.similar({
+     *     to: sourceEntity,
+     *     limit: 12,
+     *     where: {
+     *       published: true,
+     *       category: 'machine-learning'
+     *     }
+     *   })
+     * }
+     *
+     * @example
+     * // Content recommendation system
+     * async function getRecommendations(userId: string) {
+     *   // Get user's recent interactions
+     *   const user = await brainy.get(userId)
+     *   if (!user) return []
+     *
+     *   // Find similar content
+     *   const recommendations = await brainy.similar({
+     *     to: userId,
+     *     type: NounType.Document,
+     *     limit: 20,
+     *     where: {
+     *       published: true,
+     *       language: 'en'
+     *     }
+     *   })
+     *
+     *   // Filter out already seen content
+     *   return recommendations.filter(rec =>
+     *     !user.metadata.viewedItems?.includes(rec.id)
+     *   )
+     * }
+     *
+     * @example
+     * // Duplicate detection system
+     * async function findPotentialDuplicates(entityId: string) {
+     *   const duplicates = await brainy.similar({
+     *     to: entityId,
+     *     limit: 10
+     *   })
+     *
+     *   // High similarity might indicate duplicates
+     *   const highSimilarity = duplicates.filter(d => d.score > 0.95)
+     *
+     *   if (highSimilarity.length > 0) {
+     *     console.log('Potential duplicates found:', highSimilarity.map(d => d.id))
+     *   }
+     *
+     *   return highSimilarity
+     * }
+     *
+     * @example
+     * // Error handling for missing entities
+     * try {
+     *   const similar = await brainy.similar({
+     *     to: 'nonexistent-entity',
+     *     limit: 5
+     *   })
+     * } catch (error) {
+     *   if (error.message.includes('not found')) {
+     *     console.log('Source entity does not exist')
+     *     // Handle missing source entity
+     *   }
+     * }
      */
     similar(params: SimilarParams<T>): Promise<Result<T>[]>;
     /**
@@ -342,8 +797,117 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
      */
     private verbsToRelations;
     /**
-     * Embed data into vector
-     * Handles any data type by converting to string representation
+     * Embed data into vector representation
+     * Handles any data type by intelligently converting to string representation
+     *
+     * @param data - Any data to convert to vector (string, object, array, etc.)
+     * @returns Promise that resolves to a numerical vector representation
+     *
+     * @example
+     * // Basic string embedding
+     * const vector = await brainy.embed('machine learning algorithms')
+     * console.log('Vector dimensions:', vector.length)
+     *
+     * @example
+     * // Object embedding with intelligent field extraction
+     * const documentVector = await brainy.embed({
+     *   title: 'AI Research Paper',
+     *   content: 'This paper discusses neural networks...',
+     *   author: 'Dr. Smith',
+     *   category: 'machine-learning'
+     * })
+     * // Uses 'content' field for embedding by default
+     *
+     * @example
+     * // Different object field priorities
+     * // Priority: data > content > text > name > title > description
+     * const vectors = await Promise.all([
+     *   brainy.embed({ data: 'primary content' }),        // Uses 'data'
+     *   brainy.embed({ content: 'main content' }),        // Uses 'content'
+     *   brainy.embed({ text: 'text content' }),           // Uses 'text'
+     *   brainy.embed({ name: 'entity name' }),            // Uses 'name'
+     *   brainy.embed({ title: 'document title' }),        // Uses 'title'
+     *   brainy.embed({ description: 'description text' }) // Uses 'description'
+     * ])
+     *
+     * @example
+     * // Array embedding for batch processing
+     * const batchVectors = await brainy.embed([
+     *   'first document',
+     *   'second document',
+     *   { content: 'third document as object' },
+     *   { title: 'fourth document' }
+     * ])
+     * // Returns vector representing all items combined
+     *
+     * @example
+     * // Complex object handling
+     * const complexData = {
+     *   user: { name: 'John', role: 'developer' },
+     *   project: { name: 'AI Assistant', status: 'active' },
+     *   metrics: { score: 0.95, performance: 'excellent' }
+     * }
+     * const vector = await brainy.embed(complexData)
+     * // Converts entire object to JSON for embedding
+     *
+     * @example
+     * // Pre-computing vectors for performance optimization
+     * const documents = [
+     *   { id: 'doc1', content: 'Document 1 content...' },
+     *   { id: 'doc2', content: 'Document 2 content...' },
+     *   { id: 'doc3', content: 'Document 3 content...' }
+     * ]
+     *
+     * // Pre-compute all vectors
+     * const vectors = await Promise.all(
+     *   documents.map(doc => brainy.embed(doc.content))
+     * )
+     *
+     * // Add entities with pre-computed vectors (faster)
+     * for (let i = 0; i < documents.length; i++) {
+     *   await brainy.add({
+     *     data: documents[i],
+     *     type: NounType.Document,
+     *     vector: vectors[i] // Skip embedding computation
+     *   })
+     * }
+     *
+     * @example
+     * // Custom embedding for search queries
+     * async function searchWithCustomEmbedding(query: string) {
+     *   // Enhance query for better matching
+     *   const enhancedQuery = `search: ${query} relevant information`
+     *   const queryVector = await brainy.embed(enhancedQuery)
+     *
+     *   // Use pre-computed vector for search
+     *   return brainy.find({
+     *     vector: queryVector,
+     *     limit: 10
+     *   })
+     * }
+     *
+     * @example
+     * // Handling edge cases gracefully
+     * const edgeCases = await Promise.all([
+     *   brainy.embed(null),           // Returns vector for empty string
+     *   brainy.embed(undefined),      // Returns vector for empty string
+     *   brainy.embed(''),             // Returns vector for empty string
+     *   brainy.embed(42),             // Converts number to string
+     *   brainy.embed(true),           // Converts boolean to string
+     *   brainy.embed([]),             // Empty array handling
+     *   brainy.embed({})              // Empty object handling
+     * ])
+     *
+     * @example
+     * // Using with similarity comparisons
+     * const doc1Vector = await brainy.embed('artificial intelligence research')
+     * const doc2Vector = await brainy.embed('machine learning algorithms')
+     *
+     * // Find entities similar to doc1Vector
+     * const similar = await brainy.find({
+     *   vector: doc1Vector,
+     *   limit: 5
+     * })
      */
     embed(data: any): Promise<Vector>;
     /**