@soulcraft/brainy 3.34.0 → 3.35.0

package/dist/storage/adapters/opfsStorage.js

@@ -1471,5 +1471,106 @@ export class OPFSStorage extends BaseStorage {
             console.error('Error persisting counts to OPFS:', error);
         }
     }
+    // HNSW Index Persistence (v3.35.0+)
+    /**
+     * Get a noun's vector for HNSW rebuild
+     */
+    async getNounVector(id) {
+        await this.ensureInitialized();
+        const noun = await this.getNoun_internal(id);
+        return noun ? noun.vector : null;
+    }
+    /**
+     * Save HNSW graph data for a noun
+     * Storage path: nouns/hnsw/{shard}/{id}.json
+     */
+    async saveHNSWData(nounId, hnswData) {
+        await this.ensureInitialized();
+        try {
+            // Get or create the hnsw directory under nouns
+            const hnswDir = await this.nounsDir.getDirectoryHandle('hnsw', { create: true });
+            // Use sharded path for HNSW data
+            const shard = getShardIdFromUuid(nounId);
+            const shardDir = await hnswDir.getDirectoryHandle(shard, { create: true });
+            // Create or get the file in the shard directory
+            const fileHandle = await shardDir.getFileHandle(`${nounId}.json`, { create: true });
+            // Write the HNSW data to the file
+            const writable = await fileHandle.createWritable();
+            await writable.write(JSON.stringify(hnswData, null, 2));
+            await writable.close();
+        }
+        catch (error) {
+            console.error(`Failed to save HNSW data for ${nounId}:`, error);
+            throw new Error(`Failed to save HNSW data for ${nounId}: ${error}`);
+        }
+    }
+    /**
+     * Get HNSW graph data for a noun
+     * Storage path: nouns/hnsw/{shard}/{id}.json
+     */
+    async getHNSWData(nounId) {
+        await this.ensureInitialized();
+        try {
+            // Get the hnsw directory under nouns
+            const hnswDir = await this.nounsDir.getDirectoryHandle('hnsw');
+            // Use sharded path for HNSW data
+            const shard = getShardIdFromUuid(nounId);
+            const shardDir = await hnswDir.getDirectoryHandle(shard);
+            // Get the file handle from the shard directory
+            const fileHandle = await shardDir.getFileHandle(`${nounId}.json`);
+            // Read the HNSW data from the file
+            const file = await fileHandle.getFile();
+            const text = await file.text();
+            return JSON.parse(text);
+        }
+        catch (error) {
+            if (error.name === 'NotFoundError') {
+                return null;
+            }
+            console.error(`Failed to get HNSW data for ${nounId}:`, error);
+            throw new Error(`Failed to get HNSW data for ${nounId}: ${error}`);
+        }
+    }
+    /**
+     * Save HNSW system data (entry point, max level)
+     * Storage path: index/hnsw-system.json
+     */
+    async saveHNSWSystem(systemData) {
+        await this.ensureInitialized();
+        try {
+            // Create or get the file in the index directory
+            const fileHandle = await this.indexDir.getFileHandle('hnsw-system.json', { create: true });
+            // Write the system data to the file
+            const writable = await fileHandle.createWritable();
+            await writable.write(JSON.stringify(systemData, null, 2));
+            await writable.close();
+        }
+        catch (error) {
+            console.error('Failed to save HNSW system data:', error);
+            throw new Error(`Failed to save HNSW system data: ${error}`);
+        }
+    }
+    /**
+     * Get HNSW system data (entry point, max level)
+     * Storage path: index/hnsw-system.json
+     */
+    async getHNSWSystem() {
+        await this.ensureInitialized();
+        try {
+            // Get the file handle from the index directory
+            const fileHandle = await this.indexDir.getFileHandle('hnsw-system.json');
+            // Read the system data from the file
+            const file = await fileHandle.getFile();
+            const text = await file.text();
+            return JSON.parse(text);
+        }
+        catch (error) {
+            if (error.name === 'NotFoundError') {
+                return null;
+            }
+            console.error('Failed to get HNSW system data:', error);
+            throw new Error(`Failed to get HNSW system data: ${error}`);
+        }
+    }
 }
 //# sourceMappingURL=opfsStorage.js.map

package/dist/storage/adapters/s3CompatibleStorage.d.ts

@@ -572,4 +572,40 @@ export declare class S3CompatibleStorage extends BaseStorage {
      * @returns true (S3 is cloud storage)
      */
     protected isCloudStorage(): boolean;
+    /**
+     * Get a noun's vector for HNSW rebuild
+     */
+    getNounVector(id: string): Promise<number[] | null>;
+    /**
+     * Save HNSW graph data for a noun
+     * Storage path: entities/nouns/hnsw/{shard}/{id}.json
+     */
+    saveHNSWData(nounId: string, hnswData: {
+        level: number;
+        connections: Record<string, string[]>;
+    }): Promise<void>;
+    /**
+     * Get HNSW graph data for a noun
+     * Storage path: entities/nouns/hnsw/{shard}/{id}.json
+     */
+    getHNSWData(nounId: string): Promise<{
+        level: number;
+        connections: Record<string, string[]>;
+    } | null>;
+    /**
+     * Save HNSW system data (entry point, max level)
+     * Storage path: system/hnsw-system.json
+     */
+    saveHNSWSystem(systemData: {
+        entryPointId: string | null;
+        maxLevel: number;
+    }): Promise<void>;
+    /**
+     * Get HNSW system data (entry point, max level)
+     * Storage path: system/hnsw-system.json
+     */
+    getHNSWSystem(): Promise<{
+        entryPointId: string | null;
+        maxLevel: number;
+    } | null>;
 }

package/dist/storage/adapters/s3CompatibleStorage.js

@@ -2765,5 +2765,117 @@ export class S3CompatibleStorage extends BaseStorage {
     isCloudStorage() {
         return true; // S3 benefits from batching
     }
+    // HNSW Index Persistence (v3.35.0+)
+    /**
+     * Get a noun's vector for HNSW rebuild
+     */
+    async getNounVector(id) {
+        await this.ensureInitialized();
+        const noun = await this.getNode(id);
+        return noun ? noun.vector : null;
+    }
+    /**
+     * Save HNSW graph data for a noun
+     * Storage path: entities/nouns/hnsw/{shard}/{id}.json
+     */
+    async saveHNSWData(nounId, hnswData) {
+        await this.ensureInitialized();
+        try {
+            const { PutObjectCommand } = await import('@aws-sdk/client-s3');
+            // Use sharded path for HNSW data
+            const shard = getShardIdFromUuid(nounId);
+            const key = `entities/nouns/hnsw/${shard}/${nounId}.json`;
+            await this.s3Client.send(new PutObjectCommand({
+                Bucket: this.bucketName,
+                Key: key,
+                Body: JSON.stringify(hnswData, null, 2),
+                ContentType: 'application/json'
+            }));
+        }
+        catch (error) {
+            this.logger.error(`Failed to save HNSW data for ${nounId}:`, error);
+            throw new Error(`Failed to save HNSW data for ${nounId}: ${error}`);
+        }
+    }
+    /**
+     * Get HNSW graph data for a noun
+     * Storage path: entities/nouns/hnsw/{shard}/{id}.json
+     */
+    async getHNSWData(nounId) {
+        await this.ensureInitialized();
+        try {
+            const { GetObjectCommand } = await import('@aws-sdk/client-s3');
+            const shard = getShardIdFromUuid(nounId);
+            const key = `entities/nouns/hnsw/${shard}/${nounId}.json`;
+            const response = await this.s3Client.send(new GetObjectCommand({
+                Bucket: this.bucketName,
+                Key: key
+            }));
+            if (!response || !response.Body) {
+                return null;
+            }
+            const bodyContents = await response.Body.transformToString();
+            return JSON.parse(bodyContents);
+        }
+        catch (error) {
+            if (error.name === 'NoSuchKey' ||
+                error.message?.includes('NoSuchKey') ||
+                error.message?.includes('not found')) {
+                return null;
+            }
+            this.logger.error(`Failed to get HNSW data for ${nounId}:`, error);
+            throw new Error(`Failed to get HNSW data for ${nounId}: ${error}`);
+        }
+    }
+    /**
+     * Save HNSW system data (entry point, max level)
+     * Storage path: system/hnsw-system.json
+     */
+    async saveHNSWSystem(systemData) {
+        await this.ensureInitialized();
+        try {
+            const { PutObjectCommand } = await import('@aws-sdk/client-s3');
+            const key = `${this.systemPrefix}hnsw-system.json`;
+            await this.s3Client.send(new PutObjectCommand({
+                Bucket: this.bucketName,
+                Key: key,
+                Body: JSON.stringify(systemData, null, 2),
+                ContentType: 'application/json'
+            }));
+        }
+        catch (error) {
+            this.logger.error('Failed to save HNSW system data:', error);
+            throw new Error(`Failed to save HNSW system data: ${error}`);
+        }
+    }
+    /**
+     * Get HNSW system data (entry point, max level)
+     * Storage path: system/hnsw-system.json
+     */
+    async getHNSWSystem() {
+        await this.ensureInitialized();
+        try {
+            const { GetObjectCommand } = await import('@aws-sdk/client-s3');
+            const key = `${this.systemPrefix}hnsw-system.json`;
+            const response = await this.s3Client.send(new GetObjectCommand({
+                Bucket: this.bucketName,
+                Key: key
+            }));
+            if (!response || !response.Body) {
+                return null;
+            }
+            const bodyContents = await response.Body.transformToString();
+            return JSON.parse(bodyContents);
+        }
+        catch (error) {
+            if (error.name === 'NoSuchKey' ||
+                error.message?.includes('NoSuchKey') ||
+                error.message?.includes('not found')) {
+                return null;
+            }
+            this.logger.error('Failed to get HNSW system data:', error);
+            throw new Error(`Failed to get HNSW system data: ${error}`);
+        }
+    }
 }
 //# sourceMappingURL=s3CompatibleStorage.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "3.34.0",
+  "version": "3.35.0",
   "description": "Universal Knowledge Protocol™ - World's first Triple Intelligence database unifying vector, graph, and document search in one API. 31 nouns × 40 verbs for infinite expressiveness.",
   "main": "dist/index.js",
   "module": "dist/index.js",