@soulcraft/brainy 0.9.5

package/dist/hnsw/hnswIndex.d.ts

@@ -0,0 +1,96 @@
+/**
+ * HNSW (Hierarchical Navigable Small World) Index implementation
+ * Based on the paper: "Efficient and robust approximate nearest neighbor search using Hierarchical Navigable Small World graphs"
+ */
+import { DistanceFunction, HNSWConfig, HNSWNoun, Vector, VectorDocument } from '../coreTypes.js';
+export declare class HNSWIndex {
+    private nouns;
+    private entryPointId;
+    private maxLevel;
+    private config;
+    private distanceFunction;
+    private dimension;
+    private useParallelization;
+    constructor(config?: Partial<HNSWConfig>, distanceFunction?: DistanceFunction, options?: {
+        useParallelization?: boolean;
+    });
+    /**
+     * Set whether to use parallelization for performance-critical operations
+     */
+    setUseParallelization(useParallelization: boolean): void;
+    /**
+     * Get whether parallelization is enabled
+     */
+    getUseParallelization(): boolean;
+    /**
+     * Calculate distances between a query vector and multiple vectors in parallel
+     * This is used to optimize performance for search operations
+     * @param queryVector The query vector
+     * @param vectors Array of vectors to compare against
+     * @returns Array of distances
+     */
+    private calculateDistancesInParallel;
+    /**
+     * Add a vector to the index
+     */
+    addItem(item: VectorDocument): Promise<string>;
+    /**
+     * Search for nearest neighbors
+     */
+    search(queryVector: Vector, k?: number): Promise<Array<[string, number]>>;
+    /**
+     * Remove an item from the index
+     */
+    removeItem(id: string): boolean;
+    /**
+     * Get all nouns in the index
+     */
+    getNouns(): Map<string, HNSWNoun>;
+    /**
+     * Clear the index
+     */
+    clear(): void;
+    /**
+     * Get the size of the index
+     */
+    size(): number;
+    /**
+     * Get the distance function used by the index
+     */
+    getDistanceFunction(): DistanceFunction;
+    /**
+     * Get the entry point ID
+     */
+    getEntryPointId(): string | null;
+    /**
+     * Get the maximum level
+     */
+    getMaxLevel(): number;
+    /**
+     * Get the dimension
+     */
+    getDimension(): number | null;
+    /**
+     * Get the configuration
+     */
+    getConfig(): HNSWConfig;
+    /**
+     * Search within a specific layer
+     * Returns a map of noun IDs to distances, sorted by distance
+     */
+    private searchLayer;
+    /**
+     * Select M nearest neighbors from the candidate set
+     */
+    private selectNeighbors;
+    /**
+     * Ensure a noun doesn't have too many connections at a given level
+     */
+    private pruneConnections;
+    /**
+     * Generate a random level for a new noun
+     * Uses the same distribution as in the original HNSW paper
+     */
+    private getRandomLevel;
+}
+//# sourceMappingURL=hnswIndex.d.ts.map

package/dist/hnsw/hnswIndexOptimized.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Optimized HNSW (Hierarchical Navigable Small World) Index implementation
+ * Extends the base HNSW implementation with support for large datasets
+ * Uses product quantization for dimensionality reduction and disk-based storage when needed
+ */
+import { DistanceFunction, HNSWConfig, Vector, VectorDocument } from '../coreTypes.js';
+import { HNSWIndex } from './hnswIndex.js';
+import { StorageAdapter } from '../coreTypes.js';
+export interface HNSWOptimizedConfig extends HNSWConfig {
+    memoryThreshold?: number;
+    productQuantization?: {
+        enabled: boolean;
+        numSubvectors?: number;
+        numCentroids?: number;
+    };
+    useDiskBasedIndex?: boolean;
+}
+/**
+ * Product Quantization implementation
+ * Reduces vector dimensionality by splitting vectors into subvectors
+ * and quantizing each subvector to the nearest centroid
+ */
+declare class ProductQuantizer {
+    private numSubvectors;
+    private numCentroids;
+    private centroids;
+    private subvectorSize;
+    private initialized;
+    private dimension;
+    constructor(numSubvectors?: number, numCentroids?: number);
+    /**
+     * Initialize the product quantizer with training data
+     * @param vectors Training vectors to use for learning centroids
+     */
+    train(vectors: Vector[]): void;
+    /**
+     * Quantize a vector using product quantization
+     * @param vector Vector to quantize
+     * @returns Array of centroid indices, one for each subvector
+     */
+    quantize(vector: Vector): number[];
+    /**
+     * Reconstruct a vector from its quantized representation
+     * @param codes Array of centroid indices
+     * @returns Reconstructed vector
+     */
+    reconstruct(codes: number[]): Vector;
+    /**
+     * Compute squared Euclidean distance between two vectors
+     * @param a First vector
+     * @param b Second vector
+     * @returns Squared Euclidean distance
+     */
+    private euclideanDistanceSquared;
+    /**
+     * Implement k-means++ algorithm to initialize centroids
+     * @param vectors Vectors to cluster
+     * @param k Number of clusters
+     * @returns Array of centroids
+     */
+    private kMeansPlusPlus;
+    /**
+     * Get the centroids for each subvector
+     * @returns Array of centroid arrays
+     */
+    getCentroids(): Vector[][];
+    /**
+     * Set the centroids for each subvector
+     * @param centroids Array of centroid arrays
+     */
+    setCentroids(centroids: Vector[][]): void;
+    /**
+     * Get the dimension of the vectors
+     * @returns Dimension
+     */
+    getDimension(): number;
+    /**
+     * Set the dimension of the vectors
+     * @param dimension Dimension
+     */
+    setDimension(dimension: number): void;
+}
+/**
+ * Optimized HNSW Index implementation
+ * Extends the base HNSW implementation with support for large datasets
+ * Uses product quantization for dimensionality reduction and disk-based storage when needed
+ */
+export declare class HNSWIndexOptimized extends HNSWIndex {
+    private optimizedConfig;
+    private productQuantizer;
+    private storage;
+    private useDiskBasedIndex;
+    private useProductQuantization;
+    private quantizedVectors;
+    private memoryUsage;
+    private vectorCount;
+    constructor(config: Partial<HNSWOptimizedConfig> | undefined, distanceFunction: DistanceFunction, storage?: StorageAdapter | null);
+    /**
+     * Add a vector to the index
+     * Uses product quantization if enabled and memory threshold is exceeded
+     */
+    addItem(item: VectorDocument): Promise<string>;
+    /**
+     * Search for nearest neighbors
+     * Uses product quantization if enabled
+     */
+    search(queryVector: Vector, k?: number): Promise<Array<[string, number]>>;
+    /**
+     * Remove an item from the index
+     */
+    removeItem(id: string): boolean;
+    /**
+     * Clear the index
+     */
+    clear(): void;
+    /**
+     * Initialize product quantizer with existing vectors
+     */
+    private initializeProductQuantizer;
+    /**
+     * Get the product quantizer
+     * @returns Product quantizer or null if not enabled
+     */
+    getProductQuantizer(): ProductQuantizer | null;
+    /**
+     * Get the optimized configuration
+     * @returns Optimized configuration
+     */
+    getOptimizedConfig(): HNSWOptimizedConfig;
+    /**
+     * Get the estimated memory usage
+     * @returns Estimated memory usage in bytes
+     */
+    getMemoryUsage(): number;
+    /**
+     * Set the storage adapter
+     * @param storage Storage adapter
+     */
+    setStorage(storage: StorageAdapter): void;
+    /**
+     * Get the storage adapter
+     * @returns Storage adapter or null if not set
+     */
+    getStorage(): StorageAdapter | null;
+    /**
+     * Set whether to use disk-based index
+     * @param useDiskBasedIndex Whether to use disk-based index
+     */
+    setUseDiskBasedIndex(useDiskBasedIndex: boolean): void;
+    /**
+     * Get whether disk-based index is used
+     * @returns Whether disk-based index is used
+     */
+    getUseDiskBasedIndex(): boolean;
+    /**
+     * Set whether to use product quantization
+     * @param useProductQuantization Whether to use product quantization
+     */
+    setUseProductQuantization(useProductQuantization: boolean): void;
+    /**
+     * Get whether product quantization is used
+     * @returns Whether product quantization is used
+     */
+    getUseProductQuantization(): boolean;
+}
+export {};
+//# sourceMappingURL=hnswIndexOptimized.d.ts.map

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+/**
+ * OPFS BrainyData
+ * A vector database using HNSW indexing with Origin Private File System storage
+ */
+import { BrainyData, BrainyDataConfig } from './brainyData.js';
+export { BrainyData };
+export type { BrainyDataConfig };
+import { euclideanDistance, cosineDistance, manhattanDistance, dotProductDistance } from './utils/index.js';
+export { euclideanDistance, cosineDistance, manhattanDistance, dotProductDistance };
+import { UniversalSentenceEncoder, createEmbeddingFunction, createTensorFlowEmbeddingFunction, createThreadedEmbeddingFunction, defaultEmbeddingFunction } from './utils/embedding.js';
+export { UniversalSentenceEncoder, createEmbeddingFunction, createTensorFlowEmbeddingFunction, createThreadedEmbeddingFunction, defaultEmbeddingFunction };
+import { OPFSStorage, MemoryStorage, createStorage } from './storage/opfsStorage.js';
+import { FileSystemStorage } from './storage/fileSystemStorage.js';
+import { R2Storage, S3CompatibleStorage } from './storage/s3CompatibleStorage.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';
+import { createSenseAugmentation, addWebSocketSupport, executeAugmentation, loadAugmentationModule, AugmentationOptions } from './augmentationFactory.js';
+export { Pipeline, pipeline, augmentationPipeline, ExecutionMode, SequentialPipeline, sequentialPipeline, executeStreamlined, executeByType, executeSingle, processStaticData, processStreamingData, createPipeline, createStreamingPipeline, StreamlinedExecutionMode, createSenseAugmentation, addWebSocketSupport, executeAugmentation, loadAugmentationModule };
+export type { PipelineOptions, PipelineResult, SequentialPipelineOptions, StreamlinedPipelineOptions, StreamlinedPipelineResult, AugmentationOptions };
+import { availableAugmentations, registerAugmentation, initializeAugmentationPipeline, setAugmentationEnabled, getAugmentationsByType } from './augmentationRegistry.js';
+export { availableAugmentations, registerAugmentation, initializeAugmentationPipeline, setAugmentationEnabled, getAugmentationsByType };
+import { loadAugmentationsFromModules, createAugmentationRegistryPlugin, createAugmentationRegistryRollupPlugin } from './augmentationRegistryLoader.js';
+import type { AugmentationRegistryLoaderOptions, AugmentationLoadResult } from './augmentationRegistryLoader.js';
+export { loadAugmentationsFromModules, createAugmentationRegistryPlugin, createAugmentationRegistryRollupPlugin };
+export type { AugmentationRegistryLoaderOptions, AugmentationLoadResult };
+import { MemoryStorageAugmentation, FileSystemStorageAugmentation, OPFSStorageAugmentation, createMemoryAugmentation } from './augmentations/memoryAugmentations.js';
+import { WebSocketConduitAugmentation, WebRTCConduitAugmentation, createConduitAugmentation } from './augmentations/conduitAugmentations.js';
+import { ServerSearchConduitAugmentation, ServerSearchActivationAugmentation, createServerSearchAugmentations } from './augmentations/serverSearchAugmentations.js';
+export { MemoryStorageAugmentation, FileSystemStorageAugmentation, OPFSStorageAugmentation, createMemoryAugmentation, WebSocketConduitAugmentation, WebRTCConduitAugmentation, createConduitAugmentation, ServerSearchConduitAugmentation, ServerSearchActivationAugmentation, createServerSearchAugmentations };
+import type { Vector, VectorDocument, SearchResult, DistanceFunction, EmbeddingFunction, EmbeddingModel, HNSWNoun, GraphVerb, HNSWConfig, StorageAdapter } from './coreTypes.js';
+import { HNSWIndex } from './hnsw/hnswIndex.js';
+import { HNSWIndexOptimized, HNSWOptimizedConfig } from './hnsw/hnswIndexOptimized.js';
+export { HNSWIndex, HNSWIndexOptimized };
+export type { Vector, VectorDocument, SearchResult, DistanceFunction, EmbeddingFunction, EmbeddingModel, HNSWNoun, GraphVerb, HNSWConfig, HNSWOptimizedConfig, StorageAdapter };
+import type { IAugmentation, AugmentationResponse, IWebSocketSupport, ISenseAugmentation, IConduitAugmentation, ICognitionAugmentation, IMemoryAugmentation, IPerceptionAugmentation, IDialogAugmentation, IActivationAugmentation } from './types/augmentations.js';
+import { AugmentationType, BrainyAugmentations } from './types/augmentations.js';
+export type { IAugmentation, AugmentationResponse, IWebSocketSupport };
+export { AugmentationType, BrainyAugmentations, ISenseAugmentation, IConduitAugmentation, ICognitionAugmentation, IMemoryAugmentation, IPerceptionAugmentation, IDialogAugmentation, IActivationAugmentation };
+export type { IWebSocketCognitionAugmentation, IWebSocketSenseAugmentation, IWebSocketPerceptionAugmentation, IWebSocketActivationAugmentation, IWebSocketDialogAugmentation, IWebSocketConduitAugmentation, IWebSocketMemoryAugmentation } from './types/augmentations.js';
+import type { GraphNoun, EmbeddedGraphVerb, Person, Place, Thing, Event, Concept, Content } from './types/graphTypes.js';
+import { NounType, VerbType } from './types/graphTypes.js';
+export type { GraphNoun, EmbeddedGraphVerb, Person, Place, Thing, Event, Concept, Content };
+export { NounType, VerbType };
+import { BrainyMCPAdapter, MCPAugmentationToolset, BrainyMCPService } from './mcp/index.js';
+import { MCPRequest, MCPResponse, MCPDataAccessRequest, MCPToolExecutionRequest, MCPSystemInfoRequest, MCPAuthenticationRequest, MCPRequestType, MCPServiceOptions, MCPTool, MCP_VERSION } from './types/mcpTypes.js';
+export { BrainyMCPAdapter, MCPAugmentationToolset, BrainyMCPService, MCPRequestType, MCP_VERSION };
+export type { MCPRequest, MCPResponse, MCPDataAccessRequest, MCPToolExecutionRequest, MCPSystemInfoRequest, MCPAuthenticationRequest, MCPServiceOptions, MCPTool };
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp/brainyMCPAdapter.d.ts

@@ -0,0 +1,69 @@
+/**
+ * BrainyMCPAdapter
+ *
+ * This class provides an adapter for accessing Brainy data through the Model Control Protocol (MCP).
+ * It wraps a BrainyData instance and exposes methods for getting vectors, searching similar items,
+ * and getting relationships.
+ */
+import { BrainyDataInterface } from '../types/brainyDataInterface.js';
+import { MCPResponse, MCPDataAccessRequest } from '../types/mcpTypes.js';
+export declare class BrainyMCPAdapter {
+    private brainyData;
+    /**
+     * Creates a new BrainyMCPAdapter
+     * @param brainyData The BrainyData instance to wrap
+     */
+    constructor(brainyData: BrainyDataInterface);
+    /**
+     * Handles an MCP data access request
+     * @param request The MCP request
+     * @returns An MCP response
+     */
+    handleRequest(request: MCPDataAccessRequest): Promise<MCPResponse>;
+    /**
+     * Handles a get request
+     * @param request The MCP request
+     * @returns An MCP response
+     */
+    private handleGetRequest;
+    /**
+     * Handles a search request
+     * @param request The MCP request
+     * @returns An MCP response
+     */
+    private handleSearchRequest;
+    /**
+     * Handles an add request
+     * @param request The MCP request
+     * @returns An MCP response
+     */
+    private handleAddRequest;
+    /**
+     * Handles a getRelationships request
+     * @param request The MCP request
+     * @returns An MCP response
+     */
+    private handleGetRelationshipsRequest;
+    /**
+     * Creates a success response
+     * @param requestId The request ID
+     * @param data The response data
+     * @returns An MCP response
+     */
+    private createSuccessResponse;
+    /**
+     * Creates an error response
+     * @param requestId The request ID
+     * @param code The error code
+     * @param message The error message
+     * @param details Optional error details
+     * @returns An MCP response
+     */
+    private createErrorResponse;
+    /**
+     * Creates a new request ID
+     * @returns A new UUID
+     */
+    generateRequestId(): string;
+}
+//# sourceMappingURL=brainyMCPAdapter.d.ts.map

package/dist/mcp/brainyMCPService.d.ts

@@ -0,0 +1,99 @@
+/**
+ * BrainyMCPService
+ *
+ * This class provides a unified service for accessing Brainy data and augmentations
+ * through the Model Control Protocol (MCP). It integrates the BrainyMCPAdapter and
+ * MCPAugmentationToolset classes and provides WebSocket and REST server implementations
+ * for external model access.
+ */
+import { BrainyDataInterface } from '../types/brainyDataInterface.js';
+import { MCPRequest, MCPResponse, MCPServiceOptions } from '../types/mcpTypes.js';
+export declare class BrainyMCPService {
+    private dataAdapter;
+    private toolset;
+    private options;
+    private authTokens;
+    private rateLimits;
+    /**
+     * Creates a new BrainyMCPService
+     * @param brainyData The BrainyData instance to wrap
+     * @param options Configuration options for the service
+     */
+    constructor(brainyData: BrainyDataInterface, options?: MCPServiceOptions);
+    /**
+     * Handles an MCP request
+     * @param request The MCP request
+     * @returns An MCP response
+     */
+    handleRequest(request: MCPRequest): Promise<MCPResponse>;
+    /**
+     * Handles a system info request
+     * @param request The MCP request
+     * @returns An MCP response
+     */
+    private handleSystemInfoRequest;
+    /**
+     * Handles an authentication request
+     * @param request The MCP request
+     * @returns An MCP response
+     */
+    private handleAuthenticationRequest;
+    /**
+     * Checks if a request is valid
+     * @param request The request to check
+     * @returns Whether the request is valid
+     */
+    private isValidRequest;
+    /**
+     * Checks if a request is authenticated
+     * @param request The request to check
+     * @returns Whether the request is authenticated
+     */
+    private isAuthenticated;
+    /**
+     * Checks if a token is valid
+     * @param token The token to check
+     * @returns Whether the token is valid
+     */
+    private isValidToken;
+    /**
+     * Generates an authentication token
+     * @param userId The user ID to associate with the token
+     * @returns The generated token
+     */
+    private generateAuthToken;
+    /**
+     * Checks if a client has exceeded the rate limit
+     * @param clientId The client ID to check
+     * @returns Whether the client is within the rate limit
+     */
+    private checkRateLimit;
+    /**
+     * Creates a success response
+     * @param requestId The request ID
+     * @param data The response data
+     * @returns An MCP response
+     */
+    private createSuccessResponse;
+    /**
+     * Creates an error response
+     * @param requestId The request ID
+     * @param code The error code
+     * @param message The error message
+     * @param details Optional error details
+     * @returns An MCP response
+     */
+    private createErrorResponse;
+    /**
+     * Creates a new request ID
+     * @returns A new UUID
+     */
+    generateRequestId(): string;
+    /**
+     * Handles an MCP request directly (for in-process models)
+     * @param request The MCP request
+     * @returns An MCP response
+     */
+    handleMCPRequest(request: MCPRequest): Promise<MCPResponse>;
+}
+//# sourceMappingURL=brainyMCPService.d.ts.map

package/dist/mcp/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Model Control Protocol (MCP) for Brainy
+ *
+ * This module provides a Model Control Protocol (MCP) implementation for Brainy,
+ * allowing external models to access Brainy data and use the augmentation pipeline as tools.
+ */
+import { BrainyMCPAdapter } from './brainyMCPAdapter.js';
+import { MCPAugmentationToolset } from './mcpAugmentationToolset.js';
+import { BrainyMCPService } from './brainyMCPService.js';
+export { BrainyMCPAdapter };
+export { MCPAugmentationToolset };
+export { BrainyMCPService };
+export * from '../types/mcpTypes.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp/mcpAugmentationToolset.d.ts

@@ -0,0 +1,68 @@
+/**
+ * MCPAugmentationToolset
+ *
+ * This class exposes the Brainy augmentation pipeline as tools through the Model Control Protocol (MCP).
+ * It provides methods for getting available tools and executing tools.
+ */
+import { MCPResponse, MCPToolExecutionRequest, MCPTool } from '../types/mcpTypes.js';
+export declare class MCPAugmentationToolset {
+    /**
+     * Creates a new MCPAugmentationToolset
+     */
+    constructor();
+    /**
+     * Handles an MCP tool execution request
+     * @param request The MCP request
+     * @returns An MCP response
+     */
+    handleRequest(request: MCPToolExecutionRequest): Promise<MCPResponse>;
+    /**
+     * Gets all available tools
+     * @returns An array of MCP tools
+     */
+    getAvailableTools(): Promise<MCPTool[]>;
+    /**
+     * Creates a tool definition
+     * @param type The augmentation type
+     * @param augmentationName The augmentation name
+     * @param method The method name
+     * @returns An MCP tool definition
+     */
+    private createToolDefinition;
+    /**
+     * Executes the appropriate pipeline based on the augmentation type
+     * @param type The augmentation type
+     * @param method The method to execute
+     * @param parameters The parameters for the method
+     * @returns The result of the pipeline execution
+     */
+    private executePipeline;
+    /**
+     * Checks if an augmentation type is valid
+     * @param type The augmentation type to check
+     * @returns Whether the augmentation type is valid
+     */
+    private isValidAugmentationType;
+    /**
+     * Creates a success response
+     * @param requestId The request ID
+     * @param data The response data
+     * @returns An MCP response
+     */
+    private createSuccessResponse;
+    /**
+     * Creates an error response
+     * @param requestId The request ID
+     * @param code The error code
+     * @param message The error message
+     * @param details Optional error details
+     * @returns An MCP response
+     */
+    private createErrorResponse;
+    /**
+     * Creates a new request ID
+     * @returns A new UUID
+     */
+    generateRequestId(): string;
+}
+//# sourceMappingURL=mcpAugmentationToolset.d.ts.map