@soulcraft/brainy 0.13.0 → 0.15.0

package/dist/index.d.ts

@@ -12,9 +12,7 @@ import { UniversalSentenceEncoder, createEmbeddingFunction, createTensorFlowEmbe
 import { executeInThread, cleanupWorkerPools } from './utils/workerUtils.js';
 import { isBrowser, isNode, isWebWorker, areWebWorkersAvailable, areWorkerThreadsAvailable, areWorkerThreadsAvailableSync, isThreadingAvailable, isThreadingAvailableAsync } from './utils/environment.js';
 export { UniversalSentenceEncoder, createEmbeddingFunction, createTensorFlowEmbeddingFunction, createThreadedEmbeddingFunction, defaultEmbeddingFunction, executeInThread, cleanupWorkerPools, isBrowser, isNode, isWebWorker, areWebWorkersAvailable, areWorkerThreadsAvailable, areWorkerThreadsAvailableSync, isThreadingAvailable, isThreadingAvailableAsync };
-import { OPFSStorage, MemoryStorage, createStorage } from './storage/opfsStorage.js';
-import { FileSystemStorage } from './storage/fileSystemStorage.js';
-import { R2Storage, S3CompatibleStorage } from './storage/s3CompatibleStorage.js';
+import { OPFSStorage, MemoryStorage, FileSystemStorage, R2Storage, S3CompatibleStorage, createStorage } from './storage/storageFactory.js';
 export { OPFSStorage, MemoryStorage, FileSystemStorage, R2Storage, S3CompatibleStorage, createStorage };
 import { Pipeline, pipeline, augmentationPipeline, ExecutionMode, PipelineOptions, PipelineResult, executeStreamlined, executeByType, executeSingle, processStaticData, processStreamingData, createPipeline, createStreamingPipeline, StreamlinedExecutionMode, StreamlinedPipelineOptions, StreamlinedPipelineResult } from './pipeline.js';
 import { SequentialPipeline, sequentialPipeline, SequentialPipelineOptions } from './sequentialPipeline.js';

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

@@ -0,0 +1,104 @@
+/**
+ * File System Storage Adapter
+ * File system storage adapter for Node.js environments
+ */
+import { GraphVerb, HNSWNoun } from '../../coreTypes.js';
+import { BaseStorage } from '../baseStorage.js';
+type HNSWNode = HNSWNoun;
+type Edge = GraphVerb;
+/**
+ * File system storage adapter for Node.js environments
+ * Uses the file system to store data in the specified directory structure
+ */
+export declare class FileSystemStorage extends BaseStorage {
+    private rootDir;
+    private nounsDir;
+    private verbsDir;
+    private metadataDir;
+    private indexDir;
+    /**
+     * Initialize the storage adapter
+     * @param rootDirectory The root directory for storage
+     */
+    constructor(rootDirectory: string);
+    /**
+     * Initialize the storage adapter
+     */
+    init(): Promise<void>;
+    /**
+     * Ensure a directory exists, creating it if necessary
+     */
+    private ensureDirectoryExists;
+    /**
+     * Save a node to storage
+     */
+    protected saveNode(node: HNSWNode): Promise<void>;
+    /**
+     * Get a node from storage
+     */
+    protected getNode(id: string): Promise<HNSWNode | null>;
+    /**
+     * Get all nodes from storage
+     */
+    protected getAllNodes(): Promise<HNSWNode[]>;
+    /**
+     * Get nodes by noun type
+     * @param nounType The noun type to filter by
+     * @returns Promise that resolves to an array of nodes of the specified noun type
+     */
+    protected getNodesByNounType(nounType: string): Promise<HNSWNode[]>;
+    /**
+     * Delete a node from storage
+     */
+    protected deleteNode(id: string): Promise<void>;
+    /**
+     * Save an edge to storage
+     */
+    protected saveEdge(edge: Edge): Promise<void>;
+    /**
+     * Get an edge from storage
+     */
+    protected getEdge(id: string): Promise<Edge | null>;
+    /**
+     * Get all edges from storage
+     */
+    protected getAllEdges(): Promise<Edge[]>;
+    /**
+     * Get edges by source
+     */
+    protected getEdgesBySource(sourceId: string): Promise<Edge[]>;
+    /**
+     * Get edges by target
+     */
+    protected getEdgesByTarget(targetId: string): Promise<Edge[]>;
+    /**
+     * Get edges by type
+     */
+    protected getEdgesByType(type: string): Promise<Edge[]>;
+    /**
+     * Delete an edge from storage
+     */
+    protected deleteEdge(id: string): Promise<void>;
+    /**
+     * Save metadata to storage
+     */
+    saveMetadata(id: string, metadata: any): Promise<void>;
+    /**
+     * Get metadata from storage
+     */
+    getMetadata(id: string): Promise<any | null>;
+    /**
+     * Clear all data from storage
+     */
+    clear(): Promise<void>;
+    /**
+     * Get information about storage usage and capacity
+     */
+    getStorageStatus(): Promise<{
+        type: string;
+        used: number;
+        quota: number | null;
+        details?: Record<string, any>;
+    }>;
+}
+export {};

package/dist/storage/adapters/fileSystemStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileSystemStorage.d.ts","sourceRoot":"","sources":["../../../src/storage/adapters/fileSystemStorage.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,EAAE,WAAW,EAAiD,MAAM,mBAAmB,CAAA;AAG9F,KAAK,QAAQ,GAAG,QAAQ,CAAA;AACxB,KAAK,IAAI,GAAG,SAAS,CAAA;AAyBrB;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,WAAW;IAChD,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,WAAW,CAAQ;IAC3B,OAAO,CAAC,QAAQ,CAAQ;IAExB;;;OAGG;gBACS,aAAa,EAAE,MAAM;IASjC;;OAEG;IACU,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAmClC;;OAEG;YACW,qBAAqB;IAWnC;;OAEG;cACa,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAevD;;OAEG;cACa,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IA2B7D;;OAEG;cACa,WAAW,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAiClD;;;;OAIG;cACa,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAuCzE;;OAEG;cACa,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcrD;;OAEG;cACa,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAenD;;OAEG;cACa,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAgCzD;;OAEG;cACa,WAAW,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;IAsC9C;;OAEG;cACa,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAKnE;;OAEG;cACa,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAKnE;;OAEG;cACa,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAK7D;;OAEG;cACa,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcrD;;OAEG;IACU,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAOnE;;OAEG;IACU,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC;IAezD;;OAEG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAsCnC;;OAEG;IACU,gBAAgB,IAAI,OAAO,CAAC;QACvC,IAAI,EAAE,MAAM,CAAA;QACZ,IAAI,EAAE,MAAM,CAAA;QACZ,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;QACpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAC9B,CAAC;CAsFH"}

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

@@ -0,0 +1,101 @@
+/**
+ * Memory Storage Adapter
+ * In-memory storage adapter for environments where persistent storage is not available or needed
+ */
+import { GraphVerb, HNSWNoun } from '../../coreTypes.js';
+import { BaseStorage } from '../baseStorage.js';
+/**
+ * Type alias for HNSWNoun to make the code more readable
+ */
+type HNSWNode = HNSWNoun;
+/**
+ * Type alias for GraphVerb to make the code more readable
+ */
+type Edge = GraphVerb;
+/**
+ * In-memory storage adapter
+ * Uses Maps to store data in memory
+ */
+export declare class MemoryStorage extends BaseStorage {
+    private nouns;
+    private verbs;
+    private metadata;
+    constructor();
+    /**
+     * Initialize the storage adapter
+     * Nothing to initialize for in-memory storage
+     */
+    init(): Promise<void>;
+    /**
+     * Save a node to storage
+     */
+    protected saveNode(node: HNSWNode): Promise<void>;
+    /**
+     * Get a node from storage
+     */
+    protected getNode(id: string): Promise<HNSWNode | null>;
+    /**
+     * Get all nodes from storage
+     */
+    protected getAllNodes(): Promise<HNSWNode[]>;
+    /**
+     * Get nodes by noun type
+     * @param nounType The noun type to filter by
+     * @returns Promise that resolves to an array of nodes of the specified noun type
+     */
+    protected getNodesByNounType(nounType: string): Promise<HNSWNode[]>;
+    /**
+     * Delete a node from storage
+     */
+    protected deleteNode(id: string): Promise<void>;
+    /**
+     * Save an edge to storage
+     */
+    protected saveEdge(edge: Edge): Promise<void>;
+    /**
+     * Get an edge from storage
+     */
+    protected getEdge(id: string): Promise<Edge | null>;
+    /**
+     * Get all edges from storage
+     */
+    protected getAllEdges(): Promise<Edge[]>;
+    /**
+     * Get edges by source
+     */
+    protected getEdgesBySource(sourceId: string): Promise<Edge[]>;
+    /**
+     * Get edges by target
+     */
+    protected getEdgesByTarget(targetId: string): Promise<Edge[]>;
+    /**
+     * Get edges by type
+     */
+    protected getEdgesByType(type: string): Promise<Edge[]>;
+    /**
+     * Delete an edge from storage
+     */
+    protected deleteEdge(id: string): Promise<void>;
+    /**
+     * Save metadata to storage
+     */
+    saveMetadata(id: string, metadata: any): Promise<void>;
+    /**
+     * Get metadata from storage
+     */
+    getMetadata(id: string): Promise<any | null>;
+    /**
+     * Clear all data from storage
+     */
+    clear(): Promise<void>;
+    /**
+     * Get information about storage usage and capacity
+     */
+    getStorageStatus(): Promise<{
+        type: string;
+        used: number;
+        quota: number | null;
+        details?: Record<string, any>;
+    }>;
+}
+export {};

package/dist/storage/adapters/memoryStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memoryStorage.d.ts","sourceRoot":"","sources":["../../../src/storage/adapters/memoryStorage.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAE/C;;GAEG;AACH,KAAK,QAAQ,GAAG,QAAQ,CAAA;AAExB;;GAEG;AACH,KAAK,IAAI,GAAG,SAAS,CAAA;AAErB;;;GAGG;AACH,qBAAa,aAAc,SAAQ,WAAW;IAE5C,OAAO,CAAC,KAAK,CAAmC;IAChD,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,QAAQ,CAA8B;;IAM9C;;;OAGG;IACU,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIlC;;OAEG;cACa,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBvD;;OAEG;cACa,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAwB7D;;OAEG;cACa,WAAW,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAuBlD;;;;OAIG;cACa,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IA6BzE;;OAEG;cACa,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKrD;;OAEG;cACa,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBnD;;OAEG;cACa,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IA6BzD;;OAEG;cACa,WAAW,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;IA4B9C;;OAEG;cACa,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAKnE;;OAEG;cACa,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAKnE;;OAEG;cACa,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAK7D;;OAEG;cACa,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKrD;;OAEG;IACU,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAInE;;OAEG;IACU,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC;IASzD;;OAEG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAMnC;;OAEG;IACU,gBAAgB,IAAI,OAAO,CAAC;QACvC,IAAI,EAAE,MAAM,CAAA;QACZ,IAAI,EAAE,MAAM,CAAA;QACZ,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;QACpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAC9B,CAAC;CAYH"}

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

@@ -0,0 +1,114 @@
+/**
+ * OPFS (Origin Private File System) Storage Adapter
+ * Provides persistent storage for the vector database using the Origin Private File System API
+ */
+import { GraphVerb, HNSWNoun } from '../../coreTypes.js';
+import { BaseStorage } from '../baseStorage.js';
+import '../../types/fileSystemTypes.js';
+type HNSWNode = HNSWNoun;
+type Edge = GraphVerb;
+/**
+ * OPFS storage adapter for browser environments
+ * Uses the Origin Private File System API to store data persistently
+ */
+export declare class OPFSStorage extends BaseStorage {
+    private rootDir;
+    private nounsDir;
+    private verbsDir;
+    private metadataDir;
+    private indexDir;
+    private isAvailable;
+    private isPersistentRequested;
+    private isPersistentGranted;
+    constructor();
+    /**
+     * Initialize the storage adapter
+     */
+    init(): Promise<void>;
+    /**
+     * Check if OPFS is available in the current environment
+     */
+    isOPFSAvailable(): boolean;
+    /**
+     * Request persistent storage permission from the user
+     * @returns Promise that resolves to true if permission was granted, false otherwise
+     */
+    requestPersistentStorage(): Promise<boolean>;
+    /**
+     * Check if persistent storage is granted
+     * @returns Promise that resolves to true if persistent storage is granted, false otherwise
+     */
+    isPersistent(): Promise<boolean>;
+    /**
+     * Save a node to storage
+     */
+    protected saveNode(node: HNSWNode): Promise<void>;
+    /**
+     * Get a node from storage
+     */
+    protected getNode(id: string): Promise<HNSWNode | null>;
+    /**
+     * Get all nodes from storage
+     */
+    protected getAllNodes(): Promise<HNSWNode[]>;
+    /**
+     * Get nodes by noun type
+     * @param nounType The noun type to filter by
+     * @returns Promise that resolves to an array of nodes of the specified noun type
+     */
+    protected getNodesByNounType(nounType: string): Promise<HNSWNode[]>;
+    /**
+     * Delete a node from storage
+     */
+    protected deleteNode(id: string): Promise<void>;
+    /**
+     * Save an edge to storage
+     */
+    protected saveEdge(edge: Edge): Promise<void>;
+    /**
+     * Get an edge from storage
+     */
+    protected getEdge(id: string): Promise<Edge | null>;
+    /**
+     * Get all edges from storage
+     */
+    protected getAllEdges(): Promise<Edge[]>;
+    /**
+     * Get edges by source
+     */
+    protected getEdgesBySource(sourceId: string): Promise<Edge[]>;
+    /**
+     * Get edges by target
+     */
+    protected getEdgesByTarget(targetId: string): Promise<Edge[]>;
+    /**
+     * Get edges by type
+     */
+    protected getEdgesByType(type: string): Promise<Edge[]>;
+    /**
+     * Delete an edge from storage
+     */
+    protected deleteEdge(id: string): Promise<void>;
+    /**
+     * Save metadata to storage
+     */
+    saveMetadata(id: string, metadata: any): Promise<void>;
+    /**
+     * Get metadata from storage
+     */
+    getMetadata(id: string): Promise<any | null>;
+    /**
+     * Clear all data from storage
+     */
+    clear(): Promise<void>;
+    /**
+     * Get information about storage usage and capacity
+     */
+    getStorageStatus(): Promise<{
+        type: string;
+        used: number;
+        quota: number | null;
+        details?: Record<string, any>;
+    }>;
+}
+export {};

package/dist/storage/adapters/opfsStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"opfsStorage.d.ts","sourceRoot":"","sources":["../../../src/storage/adapters/opfsStorage.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAC,SAAS,EAAE,QAAQ,EAAC,MAAM,oBAAoB,CAAA;AACtD,OAAO,EAAC,WAAW,EAAgD,MAAM,mBAAmB,CAAA;AAC5F,OAAO,gCAAgC,CAAA;AAavC,KAAK,QAAQ,GAAG,QAAQ,CAAA;AACxB,KAAK,IAAI,GAAG,SAAS,CAAA;AAKrB;;;GAGG;AACH,qBAAa,WAAY,SAAQ,WAAW;IACxC,OAAO,CAAC,OAAO,CAAyC;IACxD,OAAO,CAAC,QAAQ,CAAyC;IACzD,OAAO,CAAC,QAAQ,CAAyC;IACzD,OAAO,CAAC,WAAW,CAAyC;IAC5D,OAAO,CAAC,QAAQ,CAAyC;IACzD,OAAO,CAAC,WAAW,CAAQ;IAC3B,OAAO,CAAC,qBAAqB,CAAQ;IACrC,OAAO,CAAC,mBAAmB,CAAQ;;IAWnC;;OAEG;IACU,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA6ClC;;OAEG;IACI,eAAe,IAAI,OAAO;IAIjC;;;OAGG;IACU,wBAAwB,IAAI,OAAO,CAAC,OAAO,CAAC;IAuBzD;;;OAGG;IACU,YAAY,IAAI,OAAO,CAAC,OAAO,CAAC;IAc7C;;OAEG;cACa,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BvD;;OAEG;cACa,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IA6B7D;;OAEG;cACa,WAAW,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAqClD;;;;OAIG;cACa,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IA4CzE;;OAEG;cACa,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcrD;;OAEG;cACa,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BnD;;OAEG;cACa,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAkCzD;;OAEG;cACa,WAAW,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;IA0C9C;;OAEG;cACa,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAKnE;;OAEG;cACa,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAKnE;;OAEG;cACa,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAK7D;;OAEG;cACa,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcrD;;OAEG;IACU,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBnE;;OAEG;IACU,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC;IAiBzD;;OAEG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmCnC;;OAEG;IACU,gBAAgB,IAAI,OAAO,CAAC;QACrC,IAAI,EAAE,MAAM,CAAA;QACZ,IAAI,EAAE,MAAM,CAAA;QACZ,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;QACpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAChC,CAAC;CAoIL"}

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

@@ -0,0 +1,136 @@
+/**
+ * S3-Compatible Storage Adapter
+ * Uses the AWS S3 client to interact with S3-compatible storage services
+ * including Amazon S3, Cloudflare R2, and Google Cloud Storage
+ */
+import { GraphVerb, HNSWNoun } from '../../coreTypes.js';
+import { BaseStorage } from '../baseStorage.js';
+type HNSWNode = HNSWNoun;
+type Edge = GraphVerb;
+export { S3CompatibleStorage as R2Storage };
+/**
+ * S3-compatible storage adapter for server environments
+ * Uses the AWS S3 client to interact with S3-compatible storage services
+ * including Amazon S3, Cloudflare R2, and Google Cloud Storage
+ *
+ * To use this adapter with Amazon S3, you need to provide:
+ * - region: AWS region (e.g., 'us-east-1')
+ * - credentials: AWS credentials (accessKeyId and secretAccessKey)
+ * - bucketName: S3 bucket name
+ *
+ * To use this adapter with Cloudflare R2, you need to provide:
+ * - accountId: Cloudflare account ID
+ * - accessKeyId: R2 access key ID
+ * - secretAccessKey: R2 secret access key
+ * - bucketName: R2 bucket name
+ *
+ * To use this adapter with Google Cloud Storage, you need to provide:
+ * - region: GCS region (e.g., 'us-central1')
+ * - credentials: GCS credentials (accessKeyId and secretAccessKey)
+ * - endpoint: GCS endpoint (e.g., 'https://storage.googleapis.com')
+ * - bucketName: GCS bucket name
+ */
+export declare class S3CompatibleStorage extends BaseStorage {
+    private s3Client;
+    private bucketName;
+    private serviceType;
+    private region;
+    private endpoint?;
+    private accountId?;
+    private accessKeyId;
+    private secretAccessKey;
+    private sessionToken?;
+    private nounPrefix;
+    private verbPrefix;
+    private metadataPrefix;
+    private indexPrefix;
+    /**
+     * Initialize the storage adapter
+     * @param options Configuration options for the S3-compatible storage
+     */
+    constructor(options: {
+        bucketName: string;
+        region?: string;
+        endpoint?: string;
+        accountId?: string;
+        accessKeyId: string;
+        secretAccessKey: string;
+        sessionToken?: string;
+        serviceType?: string;
+    });
+    /**
+     * Initialize the storage adapter
+     */
+    init(): Promise<void>;
+    /**
+     * Save a node to storage
+     */
+    protected saveNode(node: HNSWNode): Promise<void>;
+    /**
+     * Get a node from storage
+     */
+    protected getNode(id: string): Promise<HNSWNode | null>;
+    /**
+     * Get all nodes from storage
+     */
+    protected getAllNodes(): Promise<HNSWNode[]>;
+    /**
+     * Get nodes by noun type
+     * @param nounType The noun type to filter by
+     * @returns Promise that resolves to an array of nodes of the specified noun type
+     */
+    protected getNodesByNounType(nounType: string): Promise<HNSWNode[]>;
+    /**
+     * Delete a node from storage
+     */
+    protected deleteNode(id: string): Promise<void>;
+    /**
+     * Save an edge to storage
+     */
+    protected saveEdge(edge: Edge): Promise<void>;
+    /**
+     * Get an edge from storage
+     */
+    protected getEdge(id: string): Promise<Edge | null>;
+    /**
+     * Get all edges from storage
+     */
+    protected getAllEdges(): Promise<Edge[]>;
+    /**
+     * Get edges by source
+     */
+    protected getEdgesBySource(sourceId: string): Promise<Edge[]>;
+    /**
+     * Get edges by target
+     */
+    protected getEdgesByTarget(targetId: string): Promise<Edge[]>;
+    /**
+     * Get edges by type
+     */
+    protected getEdgesByType(type: string): Promise<Edge[]>;
+    /**
+     * Delete an edge from storage
+     */
+    protected deleteEdge(id: string): Promise<void>;
+    /**
+     * Save metadata to storage
+     */
+    saveMetadata(id: string, metadata: any): Promise<void>;
+    /**
+     * Get metadata from storage
+     */
+    getMetadata(id: string): Promise<any | null>;
+    /**
+     * Clear all data from storage
+     */
+    clear(): Promise<void>;
+    /**
+     * Get information about storage usage and capacity
+     */
+    getStorageStatus(): Promise<{
+        type: string;
+        used: number;
+        quota: number | null;
+        details?: Record<string, any>;
+    }>;
+}

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

@@ -0,0 +1 @@
+{"version":3,"file":"s3CompatibleStorage.d.ts","sourceRoot":"","sources":["../../../src/storage/adapters/s3CompatibleStorage.ts"],"names":[],"mappings":"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"}

package/dist/storage/baseStorage.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Base Storage Adapter
+ * Provides common functionality for all storage adapters
+ */
+import { GraphVerb, HNSWNoun, StorageAdapter } from '../coreTypes.js';
+export declare const NOUNS_DIR = "nouns";
+export declare const VERBS_DIR = "verbs";
+export declare const METADATA_DIR = "metadata";
+export declare const INDEX_DIR = "index";
+/**
+ * Base storage adapter that implements common functionality
+ * This is an abstract class that should be extended by specific storage adapters
+ */
+export declare abstract class BaseStorage implements StorageAdapter {
+    protected isInitialized: boolean;
+    /**
+     * Initialize the storage adapter
+     * This method should be implemented by each specific adapter
+     */
+    abstract init(): Promise<void>;
+    /**
+     * Ensure the storage adapter is initialized
+     */
+    protected ensureInitialized(): Promise<void>;
+    /**
+     * Save a noun to storage
+     */
+    saveNoun(noun: HNSWNoun): Promise<void>;
+    /**
+     * Get a noun from storage
+     */
+    getNoun(id: string): Promise<HNSWNoun | null>;
+    /**
+     * Get all nouns from storage
+     */
+    getAllNouns(): Promise<HNSWNoun[]>;
+    /**
+     * Get nouns by noun type
+     * @param nounType The noun type to filter by
+     * @returns Promise that resolves to an array of nouns of the specified noun type
+     */
+    getNounsByNounType(nounType: string): Promise<HNSWNoun[]>;
+    /**
+     * Delete a noun from storage
+     */
+    deleteNoun(id: string): Promise<void>;
+    /**
+     * Save a verb to storage
+     */
+    saveVerb(verb: GraphVerb): Promise<void>;
+    /**
+     * Get a verb from storage
+     */
+    getVerb(id: string): Promise<GraphVerb | null>;
+    /**
+     * Get all verbs from storage
+     */
+    getAllVerbs(): Promise<GraphVerb[]>;
+    /**
+     * Get verbs by source
+     */
+    getVerbsBySource(sourceId: string): Promise<GraphVerb[]>;
+    /**
+     * Get verbs by target
+     */
+    getVerbsByTarget(targetId: string): Promise<GraphVerb[]>;
+    /**
+     * Get verbs by type
+     */
+    getVerbsByType(type: string): Promise<GraphVerb[]>;
+    /**
+     * Delete a verb from storage
+     */
+    deleteVerb(id: string): Promise<void>;
+    /**
+     * Clear all data from storage
+     * This method should be implemented by each specific adapter
+     */
+    abstract clear(): Promise<void>;
+    /**
+     * Get information about storage usage and capacity
+     * This method should be implemented by each specific adapter
+     */
+    abstract getStorageStatus(): Promise<{
+        type: string;
+        used: number;
+        quota: number | null;
+        details?: Record<string, any>;
+    }>;
+    /**
+     * Save metadata to storage
+     * This method should be implemented by each specific adapter
+     */
+    abstract saveMetadata(id: string, metadata: any): Promise<void>;
+    /**
+     * Get metadata from storage
+     * This method should be implemented by each specific adapter
+     */
+    abstract getMetadata(id: string): Promise<any | null>;
+    /**
+     * Save a node to storage
+     * This method should be implemented by each specific adapter
+     */
+    protected abstract saveNode(node: HNSWNoun): Promise<void>;
+    /**
+     * Get a node from storage
+     * This method should be implemented by each specific adapter
+     */
+    protected abstract getNode(id: string): Promise<HNSWNoun | null>;
+    /**
+     * Get all nodes from storage
+     * This method should be implemented by each specific adapter
+     */
+    protected abstract getAllNodes(): Promise<HNSWNoun[]>;
+    /**
+     * Get nodes by noun type
+     * This method should be implemented by each specific adapter
+     */
+    protected abstract getNodesByNounType(nounType: string): Promise<HNSWNoun[]>;
+    /**
+     * Delete a node from storage
+     * This method should be implemented by each specific adapter
+     */
+    protected abstract deleteNode(id: string): Promise<void>;
+    /**
+     * Save an edge to storage
+     * This method should be implemented by each specific adapter
+     */
+    protected abstract saveEdge(edge: GraphVerb): Promise<void>;
+    /**
+     * Get an edge from storage
+     * This method should be implemented by each specific adapter
+     */
+    protected abstract getEdge(id: string): Promise<GraphVerb | null>;
+    /**
+     * Get all edges from storage
+     * This method should be implemented by each specific adapter
+     */
+    protected abstract getAllEdges(): Promise<GraphVerb[]>;
+    /**
+     * Get edges by source
+     * This method should be implemented by each specific adapter
+     */
+    protected abstract getEdgesBySource(sourceId: string): Promise<GraphVerb[]>;
+    /**
+     * Get edges by target
+     * This method should be implemented by each specific adapter
+     */
+    protected abstract getEdgesByTarget(targetId: string): Promise<GraphVerb[]>;
+    /**
+     * Get edges by type
+     * This method should be implemented by each specific adapter
+     */
+    protected abstract getEdgesByType(type: string): Promise<GraphVerb[]>;
+    /**
+     * Delete an edge from storage
+     * This method should be implemented by each specific adapter
+     */
+    protected abstract deleteEdge(id: string): Promise<void>;
+    /**
+     * Helper method to convert a Map to a plain object for serialization
+     */
+    protected mapToObject<K extends string | number, V>(map: Map<K, V>, valueTransformer?: (value: V) => any): Record<string, any>;
+}

package/dist/storage/baseStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseStorage.d.ts","sourceRoot":"","sources":["../../src/storage/baseStorage.ts"],"names":[],"mappings":"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"}

package/dist/storage/fileSystemStorage.d.ts

@@ -7,13 +7,6 @@ export declare class FileSystemStorage implements StorageAdapter {
     private nounsDir;
     private verbsDir;
     private metadataDir;
-    private personDir;
-    private placeDir;
-    private thingDir;
-    private eventDir;
-    private conceptDir;
-    private contentDir;
-    private defaultDir;
     private isInitialized;
     constructor(rootDirectory?: string);
     /**