@soulcraft/brainy 0.52.0 → 0.54.0

package/README.md

@@ -69,6 +69,160 @@ const results = await brainy.search("AI language models", 5, {
 
 **That's it. You just built a knowledge graph with semantic search and faceted filtering in 8 lines.**
 
+## ⚙️ Configuration Options
+
+Brainy works great with **zero configuration**, but you can customize it for your specific needs:
+
+### 🚀 Quick Start (Recommended)
+```javascript
+const brainy = new BrainyData()  // Auto-detects everything
+await brainy.init()              // Zero config needed
+```
+
+### 🎯 Specialized Configurations
+
+#### Writer Service with Deduplication
+Perfect for high-throughput data ingestion with smart caching:
+```javascript
+const brainy = new BrainyData({
+  writeOnly: true,        // Skip search index loading
+  allowDirectReads: true  // Enable ID-based lookups for deduplication
+})
+// ✅ Can: add(), get(), has(), exists(), getMetadata(), getBatch()
+// ❌ Cannot: search(), similar(), query() (saves memory & startup time)
+```
+
+#### Pure Writer Service
+For maximum performance data ingestion only:
+```javascript
+const brainy = new BrainyData({
+  writeOnly: true,         // No search capabilities
+  allowDirectReads: false  // No read operations at all
+})
+// ✅ Can: add(), addBatch(), relate()
+// ❌ Cannot: Any read operations (fastest startup)
+```
+
+#### Read-Only Service
+For search-only applications with immutable data:
+```javascript
+const brainy = new BrainyData({
+  readOnly: true,    // Block all write operations
+  frozen: true       // Block statistics updates and optimizations
+})
+// ✅ Can: All search operations
+// ❌ Cannot: add(), update(), delete()
+```
+
+#### Custom Storage & Performance
+```javascript
+const brainy = new BrainyData({
+  // Storage options
+  storage: {
+    type: 's3',                    // 's3', 'memory', 'filesystem'
+    requestPersistentStorage: true, // Browser: request persistent storage
+    s3Storage: {
+      bucketName: 'my-vectors',
+      region: 'us-east-1'
+    }
+  },
+  
+  // Performance tuning
+  hnsw: {
+    maxConnections: 16,      // Higher = better search quality
+    efConstruction: 200,     // Higher = better index quality
+    useOptimized: true       // Enable disk-based storage
+  },
+  
+  // Embedding customization
+  embeddingFunction: myCustomEmbedder,
+  distanceFunction: 'euclidean'  // 'cosine', 'euclidean', 'manhattan'
+})
+```
+
+#### Distributed Services
+```javascript
+// Microservice A (Writer)
+const writerService = new BrainyData({
+  writeOnly: true,
+  allowDirectReads: true,  // For deduplication
+  defaultService: 'data-ingestion'
+})
+
+// Microservice B (Reader) 
+const readerService = new BrainyData({
+  readOnly: true,
+  defaultService: 'search-api'
+})
+
+// Full-featured service
+const hybridService = new BrainyData({
+  writeOnly: false,  // Can read and write
+  defaultService: 'full-stack-app'
+})
+```
+
+### 🔧 All Configuration Options
+
+<details>
+<summary>Click to see complete configuration reference</summary>
+
+```javascript
+const brainy = new BrainyData({
+  // === Operation Modes ===
+  writeOnly?: boolean              // Disable search operations, enable fast ingestion
+  allowDirectReads?: boolean       // Enable ID lookups in writeOnly mode
+  readOnly?: boolean              // Disable write operations
+  frozen?: boolean                // Disable all optimizations and statistics
+  lazyLoadInReadOnlyMode?: boolean // Load index on-demand
+  
+  // === Storage Configuration ===
+  storage?: {
+    type?: 'auto' | 'memory' | 'filesystem' | 's3' | 'opfs'
+    requestPersistentStorage?: boolean  // Browser persistent storage
+    
+    // Cloud storage options
+    s3Storage?: {
+      bucketName: string
+      region?: string
+      accessKeyId?: string
+      secretAccessKey?: string
+    },
+    
+    r2Storage?: { /* Cloudflare R2 options */ },
+    gcsStorage?: { /* Google Cloud Storage options */ }
+  },
+  
+  // === Performance Tuning ===
+  hnsw?: {
+    maxConnections?: number        // Default: 16
+    efConstruction?: number        // Default: 200  
+    efSearch?: number             // Default: 50
+    useOptimized?: boolean        // Default: true
+    useDiskBasedIndex?: boolean   // Default: auto-detected
+  },
+  
+  // === Embedding & Distance ===
+  embeddingFunction?: EmbeddingFunction
+  distanceFunction?: 'cosine' | 'euclidean' | 'manhattan'
+  
+  // === Service Identity ===
+  defaultService?: string          // Default service name for operations
+  
+  // === Advanced Options ===
+  logging?: {
+    verbose?: boolean             // Enable detailed logging
+  },
+  
+  timeouts?: {
+    embedding?: number            // Embedding timeout (ms)
+    search?: number              // Search timeout (ms)
+  }
+})
+```
+
+</details>
+
 ## 🔥 MAJOR UPDATES: What's New in v0.51, v0.49 & v0.48
 
 ### 🎯 **v0.51: Revolutionary Developer Experience** 

package/dist/brainyData.d.ts

@@ -105,6 +105,13 @@ export interface BrainyDataConfig {
      * This is useful for data ingestion scenarios where only write operations are needed
      */
     writeOnly?: boolean;
+    /**
+     * Allow direct storage reads in write-only mode
+     * When true and writeOnly is also true, enables direct ID-based lookups (get, has, exists, getMetadata, getBatch, getVerb)
+     * that don't require search indexes. Search operations (search, similar, query, findRelated) remain disabled.
+     * This is useful for writer services that need deduplication without loading expensive search indexes.
+     */
+    allowDirectReads?: boolean;
     /**
      * Remote server configuration for search operations
      */
@@ -354,6 +361,7 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
     private frozen;
     private lazyLoadInReadOnlyMode;
     private writeOnly;
+    private allowDirectReads;
     private storageConfig;
     private config;
     private useOptimizedIndex;
@@ -410,6 +418,7 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
     /**
      * Check if the database is in write-only mode and throw an error if it is
      * @param allowExistenceChecks If true, allows existence checks (get operations) in write-only mode
+     * @param isDirectStorageOperation If true, allows the operation when allowDirectReads is enabled
      * @throws Error if the database is in write-only mode and operation is not allowed
      */
     private checkWriteOnly;
@@ -699,6 +708,34 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
      * Get a vector by ID
      */
     get(id: string): Promise<VectorDocument<T> | null>;
+    /**
+     * Check if a document with the given ID exists
+     * This is a direct storage operation that works in write-only mode when allowDirectReads is enabled
+     * @param id The ID to check for existence
+     * @returns Promise<boolean> True if the document exists, false otherwise
+     */
+    has(id: string): Promise<boolean>;
+    /**
+     * Check if a document with the given ID exists (alias for has)
+     * This is a direct storage operation that works in write-only mode when allowDirectReads is enabled
+     * @param id The ID to check for existence
+     * @returns Promise<boolean> True if the document exists, false otherwise
+     */
+    exists(id: string): Promise<boolean>;
+    /**
+     * Get metadata for a document by ID
+     * This is a direct storage operation that works in write-only mode when allowDirectReads is enabled
+     * @param id The ID of the document
+     * @returns Promise<T | null> The metadata object or null if not found
+     */
+    getMetadata(id: string): Promise<T | null>;
+    /**
+     * Get multiple documents by their IDs
+     * This is a direct storage operation that works in write-only mode when allowDirectReads is enabled
+     * @param ids Array of IDs to retrieve
+     * @returns Promise<Array<VectorDocument<T> | null>> Array of documents (null for missing IDs)
+     */
+    getBatch(ids: string[]): Promise<Array<VectorDocument<T> | null>>;
     /**
      * Get all nouns in the database
      * @returns Array of vector documents
@@ -789,6 +826,7 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
     }): Promise<string>;
     /**
      * Get a verb by ID
+     * This is a direct storage operation that works in write-only mode when allowDirectReads is enabled
      */
     getVerb(id: string): Promise<GraphVerb | null>;
     /**

package/dist/brainyData.js

@@ -122,6 +122,8 @@ export class BrainyData {
         this.lazyLoadInReadOnlyMode = config.lazyLoadInReadOnlyMode || false;
         // Set write-only flag
         this.writeOnly = config.writeOnly || false;
+        // Set allowDirectReads flag
+        this.allowDirectReads = config.allowDirectReads || false;
         // Validate that readOnly and writeOnly are not both true
         if (this.readOnly && this.writeOnly) {
             throw new Error('Database cannot be both read-only and write-only');
@@ -227,11 +229,15 @@ export class BrainyData {
     /**
      * Check if the database is in write-only mode and throw an error if it is
      * @param allowExistenceChecks If true, allows existence checks (get operations) in write-only mode
+     * @param isDirectStorageOperation If true, allows the operation when allowDirectReads is enabled
      * @throws Error if the database is in write-only mode and operation is not allowed
      */
-    checkWriteOnly(allowExistenceChecks = false) {
-        if (this.writeOnly && !allowExistenceChecks) {
-            throw new Error('Cannot perform search operation: database is in write-only mode. Use get() for existence checks.');
+    checkWriteOnly(allowExistenceChecks = false, isDirectStorageOperation = false) {
+        if (this.writeOnly && !allowExistenceChecks && !(isDirectStorageOperation && this.allowDirectReads)) {
+            throw new Error('Cannot perform search operation: database is in write-only mode. ' +
+                (this.allowDirectReads
+                    ? 'Direct storage operations (get, has, exists, getMetadata, getBatch, getVerb) are allowed.'
+                    : 'Use get() for existence checks or enable allowDirectReads for direct storage operations.'));
         }
     }
     /**
@@ -2026,6 +2032,96 @@ export class BrainyData {
             throw new Error(`Failed to get vector ${id}: ${error}`);
         }
     }
+    /**
+     * Check if a document with the given ID exists
+     * This is a direct storage operation that works in write-only mode when allowDirectReads is enabled
+     * @param id The ID to check for existence
+     * @returns Promise<boolean> True if the document exists, false otherwise
+     */
+    async has(id) {
+        if (id === null || id === undefined) {
+            throw new Error('ID cannot be null or undefined');
+        }
+        await this.ensureInitialized();
+        // This is a direct storage operation - check if allowed in write-only mode
+        if (this.writeOnly && !this.allowDirectReads) {
+            throw new Error('Cannot perform has() operation: database is in write-only mode. Enable allowDirectReads for direct storage operations.');
+        }
+        try {
+            // Always query storage directly for existence check
+            const noun = await this.storage.getNoun(id);
+            return noun !== null;
+        }
+        catch (error) {
+            // If storage lookup fails, the item doesn't exist
+            return false;
+        }
+    }
+    /**
+     * Check if a document with the given ID exists (alias for has)
+     * This is a direct storage operation that works in write-only mode when allowDirectReads is enabled
+     * @param id The ID to check for existence
+     * @returns Promise<boolean> True if the document exists, false otherwise
+     */
+    async exists(id) {
+        return this.has(id);
+    }
+    /**
+     * Get metadata for a document by ID
+     * This is a direct storage operation that works in write-only mode when allowDirectReads is enabled
+     * @param id The ID of the document
+     * @returns Promise<T | null> The metadata object or null if not found
+     */
+    async getMetadata(id) {
+        if (id === null || id === undefined) {
+            throw new Error('ID cannot be null or undefined');
+        }
+        await this.ensureInitialized();
+        // This is a direct storage operation - check if allowed in write-only mode
+        if (this.writeOnly && !this.allowDirectReads) {
+            throw new Error('Cannot perform getMetadata() operation: database is in write-only mode. Enable allowDirectReads for direct storage operations.');
+        }
+        try {
+            const metadata = await this.storage.getMetadata(id);
+            return metadata;
+        }
+        catch (error) {
+            console.error(`Failed to get metadata for ${id}:`, error);
+            return null;
+        }
+    }
+    /**
+     * Get multiple documents by their IDs
+     * This is a direct storage operation that works in write-only mode when allowDirectReads is enabled
+     * @param ids Array of IDs to retrieve
+     * @returns Promise<Array<VectorDocument<T> | null>> Array of documents (null for missing IDs)
+     */
+    async getBatch(ids) {
+        if (!Array.isArray(ids)) {
+            throw new Error('IDs must be provided as an array');
+        }
+        await this.ensureInitialized();
+        // This is a direct storage operation - check if allowed in write-only mode
+        if (this.writeOnly && !this.allowDirectReads) {
+            throw new Error('Cannot perform getBatch() operation: database is in write-only mode. Enable allowDirectReads for direct storage operations.');
+        }
+        const results = [];
+        for (const id of ids) {
+            if (id === null || id === undefined) {
+                results.push(null);
+                continue;
+            }
+            try {
+                const result = await this.get(id);
+                results.push(result);
+            }
+            catch (error) {
+                console.error(`Failed to get document ${id} in batch:`, error);
+                results.push(null);
+            }
+        }
+        return results;
+    }
     /**
      * Get all nouns in the database
      * @returns Array of vector documents
@@ -2690,9 +2786,14 @@ export class BrainyData {
     }
     /**
      * Get a verb by ID
+     * This is a direct storage operation that works in write-only mode when allowDirectReads is enabled
      */
     async getVerb(id) {
         await this.ensureInitialized();
+        // This is a direct storage operation - check if allowed in write-only mode
+        if (this.writeOnly && !this.allowDirectReads) {
+            throw new Error('Cannot perform getVerb() operation: database is in write-only mode. Enable allowDirectReads for direct storage operations.');
+        }
         try {
             // Get the lightweight verb from storage
             const hnswVerb = await this.storage.getVerb(id);