@henrychong-ai/mcp-neo4j-knowledge-graph 1.0.0

package/dist/embeddings/DefaultEmbeddingService.js

@@ -0,0 +1,139 @@
+import { logger } from '../utils/logger.js';
+import { EmbeddingService } from './EmbeddingService.js';
+/**
+ * Default embedding service implementation that generates random vectors.
+ * This is a fallback service for testing and development environments
+ * where an external API provider is not available.
+ */
+export class DefaultEmbeddingService extends EmbeddingService {
+    /**
+     * Create a new default embedding service instance
+     *
+     * @param config - Configuration options or dimensions
+     * @param modelName - Name to use for the model (legacy parameter)
+     * @param modelVersion - Version to use for the model (legacy parameter)
+     */
+    constructor(config = 1536, // Default to OpenAI's dimensions for better test compatibility
+    modelName = 'memento-mcp-mock', modelVersion = '1.0.0') {
+        super();
+        // Handle both object config and legacy number dimensions
+        if (typeof config === 'number') {
+            this.dimensions = config;
+            this.modelName = modelName;
+            this.modelVersion = modelVersion;
+        }
+        else {
+            // For mock mode, default to OpenAI-compatible dimensions if not specified
+            const isMockMode = process.env.MOCK_EMBEDDINGS === 'true';
+            const defaultDimensions = isMockMode ? 1536 : 384;
+            this.dimensions = config.dimensions || defaultDimensions;
+            this.modelName = config.model || (isMockMode ? 'text-embedding-3-small-mock' : modelName);
+            this.modelVersion = config.version?.toString() || modelVersion;
+        }
+        if (process.env.MOCK_EMBEDDINGS === 'true') {
+            logger.info(`Using DefaultEmbeddingService in mock mode with dimensions: ${this.dimensions}`);
+        }
+    }
+    /**
+     * Generate an embedding vector for text
+     *
+     * @param text - Text to generate embedding for
+     * @returns Promise resolving to a vector as Array
+     */
+    async generateEmbedding(text) {
+        // Generate deterministic embedding based on text
+        // This keeps the same input text producing the same output vector
+        const seed = this._hashString(text);
+        // Create an array of the specified dimensions
+        const vector = new Array(this.dimensions);
+        // Fill with seeded random values
+        for (let i = 0; i < this.dimensions; i++) {
+            // Use a simple deterministic algorithm based on seed and position
+            vector[i] = this._seededRandom(seed + i);
+        }
+        // Normalize the vector to unit length
+        this._normalizeVector(vector);
+        return vector;
+    }
+    /**
+     * Generate embedding vectors for multiple texts
+     *
+     * @param texts - Array of texts to generate embeddings for
+     * @returns Promise resolving to array of embedding vectors
+     */
+    async generateEmbeddings(texts) {
+        // Generate embeddings for each text in parallel
+        const embeddings = [];
+        for (const text of texts) {
+            embeddings.push(await this.generateEmbedding(text));
+        }
+        return embeddings;
+    }
+    /**
+     * Get information about the embedding model
+     *
+     * @returns Model information
+     */
+    getModelInfo() {
+        return {
+            name: this.modelName,
+            dimensions: this.dimensions,
+            version: this.modelVersion,
+        };
+    }
+    /**
+     * Generate a simple hash from a string for deterministic random generation
+     *
+     * @private
+     * @param text - Input text to hash
+     * @returns Numeric hash value
+     */
+    _hashString(text) {
+        let hash = 0;
+        if (text.length === 0)
+            return hash;
+        for (let i = 0; i < text.length; i++) {
+            const char = text.charCodeAt(i);
+            hash = (hash << 5) - hash + char;
+            hash = hash & hash; // Convert to 32bit integer
+        }
+        return hash;
+    }
+    /**
+     * Seeded random number generator
+     *
+     * @private
+     * @param seed - Seed value
+     * @returns Random value between 0 and 1
+     */
+    _seededRandom(seed) {
+        const x = Math.sin(seed) * 10000;
+        return x - Math.floor(x);
+    }
+    /**
+     * Normalize a vector to unit length
+     *
+     * @private
+     * @param vector - Vector to normalize
+     */
+    _normalizeVector(vector) {
+        // Calculate magnitude (Euclidean norm)
+        let magnitude = 0;
+        for (let i = 0; i < vector.length; i++) {
+            magnitude += vector[i] * vector[i];
+        }
+        magnitude = Math.sqrt(magnitude);
+        // Avoid division by zero
+        if (magnitude > 0) {
+            // Normalize each component
+            for (let i = 0; i < vector.length; i++) {
+                vector[i] /= magnitude;
+            }
+        }
+        else {
+            // If magnitude is 0, set first element to 1 for a valid unit vector
+            vector[0] = 1;
+        }
+    }
+}
+//# sourceMappingURL=DefaultEmbeddingService.js.map

package/dist/embeddings/DefaultEmbeddingService.js.map

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

package/dist/embeddings/EmbeddingJobManager.d.ts

@@ -0,0 +1,212 @@
+import { LRUCache } from 'lru-cache';
+import type { StorageProvider } from '../storage/StorageProvider.js';
+import type { EmbeddingService } from './EmbeddingService.js';
+import type { Entity } from '../KnowledgeGraphManager.js';
+import type { EntityEmbedding } from '../types/entity-embedding.js';
+/**
+ * Interface for embedding cache options
+ */
+interface CacheOptions {
+    size: number;
+    ttl: number;
+    maxItems?: number;
+    ttlHours?: number;
+}
+/**
+ * Interface for rate limiting options
+ */
+interface RateLimiterOptions {
+    tokensPerInterval: number;
+    interval: number;
+}
+/**
+ * Interface for job processing results
+ */
+interface JobProcessResults {
+    processed: number;
+    successful: number;
+    failed: number;
+}
+/**
+ * Interface for the rate limiter status
+ */
+interface RateLimiterStatus {
+    availableTokens: number;
+    maxTokens: number;
+    resetInMs: number;
+}
+/**
+ * Interface for a cached embedding entry
+ */
+interface CachedEmbedding {
+    embedding: number[];
+    timestamp: number;
+    model: string;
+}
+/**
+ * Interface for a logger
+ */
+interface Logger {
+    debug: (message: string, meta?: Record<string, unknown>) => void;
+    info: (message: string, meta?: Record<string, unknown>) => void;
+    warn: (message: string, meta?: Record<string, unknown>) => void;
+    error: (message: string, meta?: Record<string, unknown>) => void;
+}
+/**
+ * Interface for embedding storage provider, extending the base provider
+ */
+interface EmbeddingStorageProvider extends StorageProvider {
+    /**
+     * Access to the underlying database
+     */
+    db: any;
+    /**
+     * Get an entity by name
+     */
+    getEntity(entityName: string): Promise<Entity | null>;
+    /**
+     * Store an entity vector embedding
+     */
+    storeEntityVector(entityName: string, embedding: EntityEmbedding): Promise<void>;
+}
+/**
+ * Return structure for queue status
+ */
+interface QueueStatus {
+    pending: number;
+    processing: number;
+    completed: number;
+    failed: number;
+    totalJobs: number;
+}
+/**
+ * Manages embedding jobs for semantic search
+ */
+export declare class EmbeddingJobManager {
+    private storageProvider;
+    private embeddingService;
+    rateLimiter: {
+        tokens: number;
+        lastRefill: number;
+        tokensPerInterval: number;
+        interval: number;
+    };
+    cache: LRUCache<string, CachedEmbedding>;
+    private cacheOptions;
+    private logger;
+    /**
+     * Creates a new embedding job manager
+     *
+     * @param storageProvider - Provider for entity storage
+     * @param embeddingService - Service to generate embeddings
+     * @param rateLimiterOptions - Optional configuration for rate limiting
+     * @param cacheOptions - Optional configuration for caching
+     * @param logger - Optional logger for operation logging
+     */
+    constructor(storageProvider: EmbeddingStorageProvider, embeddingService: EmbeddingService, rateLimiterOptions?: RateLimiterOptions | null, cacheOptions?: CacheOptions | null, logger?: Logger | null);
+    /**
+     * Initialize the database schema for embedding jobs
+     *
+     * @private
+     */
+    private _initializeDatabase;
+    /**
+     * Schedule an entity for embedding generation
+     *
+     * @param entityName - Name of the entity to generate embedding for
+     * @param priority - Optional priority (higher priority jobs are processed first)
+     * @returns Job ID
+     */
+    scheduleEntityEmbedding(entityName: string, priority?: number): Promise<string>;
+    /**
+     * Process a batch of pending embedding jobs
+     *
+     * @param batchSize - Maximum number of jobs to process
+     * @returns Result statistics
+     */
+    processJobs(batchSize?: number): Promise<JobProcessResults>;
+    /**
+     * Get the current status of the job queue
+     *
+     * @returns Queue statistics
+     */
+    getQueueStatus(): Promise<QueueStatus>;
+    /**
+     * Retry failed embedding jobs
+     *
+     * @returns Number of jobs reset for retry
+     */
+    retryFailedJobs(): Promise<number>;
+    /**
+     * Clean up old completed jobs
+     *
+     * @param threshold - Age in milliseconds after which to delete completed jobs, defaults to 7 days
+     * @returns Number of jobs cleaned up
+     */
+    cleanupJobs(threshold?: number): Promise<number>;
+    /**
+     * Update a job's status in the database
+     *
+     * @private
+     * @param jobId - ID of the job to update
+     * @param status - New status
+     * @param attempts - Optional attempts count update
+     * @param error - Optional error message
+     * @returns Database result
+     */
+    private _updateJobStatus;
+    /**
+     * Check rate limiter and consume a token if available
+     *
+     * @private
+     * @returns Object with success flag
+     */
+    _checkRateLimiter(): {
+        success: boolean;
+    };
+    /**
+     * Get the current status of the rate limiter
+     *
+     * @returns Rate limiter status information
+     */
+    getRateLimiterStatus(): RateLimiterStatus;
+    /**
+     * Retrieve a cached embedding or generate a new one
+     *
+     * @param text - Text to generate embedding for
+     * @returns Embedding vector
+     */
+    _getCachedEmbeddingOrGenerate(text: string): Promise<number[]>;
+    /**
+     * Store an embedding in the cache
+     *
+     * @private
+     * @param text - Original text
+     * @param embedding - Embedding vector
+     */
+    private _cacheEmbedding;
+    /**
+     * Generate a deterministic cache key for text
+     *
+     * @private
+     * @param text - Text to hash
+     * @returns Cache key
+     */
+    _generateCacheKey(text: string): string;
+    /**
+     * Prepare text for embedding from an entity
+     *
+     * @private
+     * @param entity - Entity to prepare text from
+     * @returns Processed text ready for embedding
+     */
+    private _prepareEntityText;
+    /**
+     * Get a cached embedding entry (used for testing)
+     *
+     * @param key - Cache key
+     * @returns Cached embedding or undefined
+     */
+    getCacheEntry(key: string): CachedEmbedding | undefined;
+}
+export {};