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

package/dist/embeddings/EmbeddingService.js

@@ -0,0 +1,44 @@
+/**
+ * Abstract class for embedding services
+ */
+export class EmbeddingService {
+    /**
+     * Generate embedding vector for text
+     *
+     * @param text - Text to embed
+     * @returns Embedding vector
+     */
+    async generateEmbedding(_text) {
+        throw new Error('Method not implemented');
+    }
+    /**
+     * Generate embeddings for multiple texts
+     *
+     * @param texts - Array of texts to embed
+     * @returns Array of embedding vectors
+     */
+    async generateEmbeddings(_texts) {
+        throw new Error('Method not implemented');
+    }
+    /**
+     * Get information about the embedding model
+     *
+     * @returns Model information
+     */
+    getModelInfo() {
+        throw new Error('Method not implemented');
+    }
+    /**
+     * Get information about the embedding provider
+     *
+     * @returns Provider information
+     */
+    getProviderInfo() {
+        return {
+            provider: 'default',
+            model: this.getModelInfo().name,
+            dimensions: this.getModelInfo().dimensions,
+        };
+    }
+}
+//# sourceMappingURL=EmbeddingService.js.map

package/dist/embeddings/EmbeddingService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EmbeddingService.js","sourceRoot":"","sources":["../../src/embeddings/EmbeddingService.ts"],"names":[],"mappings":"AA2EA;;GAEG;AACH,MAAM,OAAO,gBAAgB;IAC3B;;;;;OAKG;IACH,KAAK,CAAC,iBAAiB,CAAC,KAAa;QACnC,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;IAC5C,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,kBAAkB,CAAC,MAAgB;QACvC,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;IAC5C,CAAC;IAED;;;;OAIG;IACH,YAAY;QACV,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;IAC5C,CAAC;IAED;;;;OAIG;IACH,eAAe;QACb,OAAO;YACL,QAAQ,EAAE,SAAS;YACnB,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC,IAAI;YAC/B,UAAU,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC,UAAU;SAC3C,CAAC;IACJ,CAAC;CACF"}

package/dist/embeddings/EmbeddingServiceFactory.d.ts

@@ -0,0 +1,72 @@
+import type { EmbeddingService } from './EmbeddingService.js';
+/**
+ * Configuration options for embedding services
+ */
+export interface EmbeddingServiceConfig {
+    provider?: string;
+    model?: string;
+    dimensions?: number;
+    apiKey?: string;
+    [key: string]: unknown;
+}
+/**
+ * Type definition for embedding service provider creation function
+ */
+type EmbeddingServiceProvider = (config?: EmbeddingServiceConfig) => EmbeddingService;
+/**
+ * Factory for creating embedding services
+ */
+export declare class EmbeddingServiceFactory {
+    /**
+     * Registry of embedding service providers
+     */
+    private static providers;
+    /**
+     * Register a new embedding service provider
+     *
+     * @param name - Provider name
+     * @param provider - Provider factory function
+     */
+    static registerProvider(name: string, provider: EmbeddingServiceProvider): void;
+    /**
+     * Reset the provider registry - used primarily for testing
+     */
+    static resetRegistry(): void;
+    /**
+     * Get a list of available provider names
+     *
+     * @returns Array of provider names
+     */
+    static getAvailableProviders(): string[];
+    /**
+     * Create a service using a registered provider
+     *
+     * @param config - Configuration options including provider name and service-specific settings
+     * @returns The created embedding service
+     * @throws Error if the provider is not registered
+     */
+    static createService(config?: EmbeddingServiceConfig): EmbeddingService;
+    /**
+     * Create an embedding service from environment variables
+     *
+     * @returns An embedding service implementation
+     */
+    static createFromEnvironment(): EmbeddingService;
+    /**
+     * Create an OpenAI embedding service
+     *
+     * @param apiKey - OpenAI API key
+     * @param model - Optional model name
+     * @param dimensions - Optional embedding dimensions
+     * @returns OpenAI embedding service
+     */
+    static createOpenAIService(apiKey: string, model?: string, dimensions?: number): EmbeddingService;
+    /**
+     * Create a default embedding service that generates random vectors
+     *
+     * @param dimensions - Optional embedding dimensions
+     * @returns Default embedding service
+     */
+    static createDefaultService(dimensions?: number): EmbeddingService;
+}
+export {};

package/dist/embeddings/EmbeddingServiceFactory.js

@@ -0,0 +1,147 @@
+import { DefaultEmbeddingService } from './DefaultEmbeddingService.js';
+import { OpenAIEmbeddingService } from './OpenAIEmbeddingService.js';
+import { logger } from '../utils/logger.js';
+/**
+ * Factory for creating embedding services
+ */
+export class EmbeddingServiceFactory {
+    /**
+     * Register a new embedding service provider
+     *
+     * @param name - Provider name
+     * @param provider - Provider factory function
+     */
+    static registerProvider(name, provider) {
+        EmbeddingServiceFactory.providers[name.toLowerCase()] = provider;
+    }
+    /**
+     * Reset the provider registry - used primarily for testing
+     */
+    static resetRegistry() {
+        EmbeddingServiceFactory.providers = {};
+    }
+    /**
+     * Get a list of available provider names
+     *
+     * @returns Array of provider names
+     */
+    static getAvailableProviders() {
+        return Object.keys(EmbeddingServiceFactory.providers);
+    }
+    /**
+     * Create a service using a registered provider
+     *
+     * @param config - Configuration options including provider name and service-specific settings
+     * @returns The created embedding service
+     * @throws Error if the provider is not registered
+     */
+    static createService(config = {}) {
+        const providerName = (config.provider || 'default').toLowerCase();
+        logger.debug(`EmbeddingServiceFactory: Creating service with provider "${providerName}"`);
+        const providerFn = EmbeddingServiceFactory.providers[providerName];
+        if (providerFn) {
+            try {
+                const service = providerFn(config);
+                logger.debug(`EmbeddingServiceFactory: Service created successfully with provider "${providerName}"`, {
+                    modelInfo: service.getModelInfo(),
+                });
+                return service;
+            }
+            catch (error) {
+                logger.error(`EmbeddingServiceFactory: Failed to create service with provider "${providerName}"`, error);
+                throw error;
+            }
+        }
+        // If provider not found, throw an error
+        logger.error(`EmbeddingServiceFactory: Provider "${providerName}" is not registered`);
+        throw new Error(`Provider "${providerName}" is not registered`);
+    }
+    /**
+     * Create an embedding service from environment variables
+     *
+     * @returns An embedding service implementation
+     */
+    static createFromEnvironment() {
+        // Check if we should use mock embeddings (for testing)
+        const useMockEmbeddings = process.env.MOCK_EMBEDDINGS === 'true';
+        logger.debug('EmbeddingServiceFactory: Creating service from environment variables', {
+            mockEmbeddings: useMockEmbeddings,
+            openaiKeyPresent: !!process.env.OPENAI_API_KEY,
+            embeddingModel: process.env.OPENAI_EMBEDDING_MODEL || 'default',
+        });
+        if (useMockEmbeddings) {
+            logger.info('EmbeddingServiceFactory: Using mock embeddings for testing');
+            return new DefaultEmbeddingService();
+        }
+        const openaiApiKey = process.env.OPENAI_API_KEY;
+        const embeddingModel = process.env.OPENAI_EMBEDDING_MODEL || 'text-embedding-3-small';
+        if (openaiApiKey) {
+            try {
+                logger.debug('EmbeddingServiceFactory: Creating OpenAI embedding service', {
+                    model: embeddingModel,
+                });
+                const service = new OpenAIEmbeddingService({
+                    apiKey: openaiApiKey,
+                    model: embeddingModel,
+                });
+                logger.info('EmbeddingServiceFactory: OpenAI embedding service created successfully', {
+                    model: service.getModelInfo().name,
+                    dimensions: service.getModelInfo().dimensions,
+                });
+                return service;
+            }
+            catch (error) {
+                logger.error('EmbeddingServiceFactory: Failed to create OpenAI service', error);
+                logger.info('EmbeddingServiceFactory: Falling back to default embedding service');
+                // Fallback to default if OpenAI service creation fails
+                return new DefaultEmbeddingService();
+            }
+        }
+        // No OpenAI API key, using default embedding service
+        logger.info('EmbeddingServiceFactory: No OpenAI API key found, using default embedding service');
+        return new DefaultEmbeddingService();
+    }
+    /**
+     * Create an OpenAI embedding service
+     *
+     * @param apiKey - OpenAI API key
+     * @param model - Optional model name
+     * @param dimensions - Optional embedding dimensions
+     * @returns OpenAI embedding service
+     */
+    static createOpenAIService(apiKey, model, dimensions) {
+        return new OpenAIEmbeddingService({
+            apiKey,
+            model,
+            dimensions,
+        });
+    }
+    /**
+     * Create a default embedding service that generates random vectors
+     *
+     * @param dimensions - Optional embedding dimensions
+     * @returns Default embedding service
+     */
+    static createDefaultService(dimensions) {
+        return new DefaultEmbeddingService(dimensions);
+    }
+}
+/**
+ * Registry of embedding service providers
+ */
+EmbeddingServiceFactory.providers = {};
+// Register built-in providers
+EmbeddingServiceFactory.registerProvider('default', (config = {}) => {
+    return new DefaultEmbeddingService(config.dimensions);
+});
+EmbeddingServiceFactory.registerProvider('openai', (config = {}) => {
+    if (!config.apiKey) {
+        throw new Error('API key is required for OpenAI embedding service');
+    }
+    return new OpenAIEmbeddingService({
+        apiKey: config.apiKey,
+        model: config.model,
+        dimensions: config.dimensions,
+    });
+});
+//# sourceMappingURL=EmbeddingServiceFactory.js.map

package/dist/embeddings/EmbeddingServiceFactory.js.map

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

package/dist/embeddings/OpenAIEmbeddingService.d.ts

@@ -0,0 +1,73 @@
+import { EmbeddingService, type EmbeddingModelInfo } from './EmbeddingService.js';
+/**
+ * Configuration for OpenAI embedding service
+ */
+export interface OpenAIEmbeddingConfig {
+    /**
+     * OpenAI API key
+     */
+    apiKey: string;
+    /**
+     * Optional model name to use
+     */
+    model?: string;
+    /**
+     * Optional dimensions override
+     */
+    dimensions?: number;
+    /**
+     * Optional version string
+     */
+    version?: string;
+}
+/**
+ * Service implementation that generates embeddings using OpenAI's API
+ */
+export declare class OpenAIEmbeddingService extends EmbeddingService {
+    private apiKey;
+    private model;
+    private dimensions;
+    private version;
+    private apiEndpoint;
+    /**
+     * Create a new OpenAI embedding service
+     *
+     * @param config - Configuration for the service
+     */
+    constructor(config: OpenAIEmbeddingConfig);
+    /**
+     * Generate an embedding for a single text
+     *
+     * @param text - Text to generate embedding for
+     * @returns Promise resolving to embedding vector
+     */
+    generateEmbedding(text: string): Promise<number[]>;
+    /**
+     * Generate embeddings for multiple texts
+     *
+     * @param texts - Array of texts to generate embeddings for
+     * @returns Promise resolving to array of embedding vectors
+     */
+    generateEmbeddings(texts: string[]): Promise<number[][]>;
+    /**
+     * Get information about the embedding model
+     *
+     * @returns Model information
+     */
+    getModelInfo(): EmbeddingModelInfo;
+    /**
+     * Extract error message from error object
+     *
+     * @private
+     * @param error - Error object
+     * @returns Error message string
+     */
+    private _getErrorMessage;
+    /**
+     * Normalize a vector to unit length (L2 norm)
+     *
+     * @private
+     * @param vector - Vector to normalize in-place
+     */
+    private _normalizeVector;
+}

package/dist/embeddings/OpenAIEmbeddingService.js

@@ -0,0 +1,195 @@
+import axios from 'axios';
+import { EmbeddingService } from './EmbeddingService.js';
+import { logger } from '../utils/logger.js';
+/**
+ * Service implementation that generates embeddings using OpenAI's API
+ */
+export class OpenAIEmbeddingService extends EmbeddingService {
+    /**
+     * Create a new OpenAI embedding service
+     *
+     * @param config - Configuration for the service
+     */
+    constructor(config) {
+        super();
+        if (!config) {
+            throw new Error('Configuration is required for OpenAI embedding service');
+        }
+        // Only require API key in non-test environments and when it's not provided in env
+        if (!config.apiKey && !process.env.OPENAI_API_KEY) {
+            throw new Error('API key is required for OpenAI embedding service');
+        }
+        this.apiKey = config.apiKey || process.env.OPENAI_API_KEY || '';
+        this.model = config.model || 'text-embedding-3-small';
+        this.dimensions = config.dimensions || 1536; // text-embedding-3-small has 1536 dimensions
+        this.version = config.version || '3.0.0';
+        this.apiEndpoint = 'https://api.openai.com/v1/embeddings';
+    }
+    /**
+     * Generate an embedding for a single text
+     *
+     * @param text - Text to generate embedding for
+     * @returns Promise resolving to embedding vector
+     */
+    async generateEmbedding(text) {
+        if (!this.apiKey) {
+            throw new Error('No OpenAI API key available');
+        }
+        logger.debug('Generating embedding', {
+            text: text.substring(0, 50) + '...',
+            model: this.model,
+            apiEndpoint: this.apiEndpoint,
+        });
+        try {
+            const response = await axios.post(this.apiEndpoint, {
+                input: text,
+                model: this.model,
+            }, {
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+                timeout: 10000, // 10 second timeout
+            });
+            logger.debug('Received response from OpenAI API');
+            if (!response.data || !response.data.data || !response.data.data[0]) {
+                logger.error('Invalid response from OpenAI API', { response: response.data });
+                throw new Error('Invalid response from OpenAI API - missing embedding data');
+            }
+            const embedding = response.data.data[0].embedding;
+            if (!embedding || !Array.isArray(embedding) || embedding.length === 0) {
+                logger.error('Invalid embedding returned', { embedding });
+                throw new Error('Invalid embedding returned from OpenAI API');
+            }
+            logger.debug('Generated embedding', {
+                length: embedding.length,
+                sample: embedding.slice(0, 5),
+                isArray: Array.isArray(embedding),
+            });
+            // Log token usage if in debug mode
+            if (process.env.DEBUG === 'true') {
+                const tokens = response.data.usage?.prompt_tokens || 'unknown';
+                logger.debug('OpenAI embedding token usage', { tokens });
+            }
+            // Normalize the embedding vector
+            this._normalizeVector(embedding);
+            logger.debug('Normalized embedding', {
+                length: embedding.length,
+                sample: embedding.slice(0, 5),
+            });
+            return embedding;
+        }
+        catch (error) {
+            // Handle axios errors specifically
+            const axiosError = error;
+            if (axiosError.isAxiosError) {
+                const statusCode = axiosError.response?.status;
+                const responseData = axiosError.response?.data;
+                logger.error('OpenAI API error', {
+                    status: statusCode,
+                    data: responseData,
+                    message: axiosError.message,
+                });
+                // Handle specific error types
+                if (statusCode === 401) {
+                    throw new Error('OpenAI API authentication failed - invalid API key');
+                }
+                else if (statusCode === 429) {
+                    throw new Error('OpenAI API rate limit exceeded - try again later');
+                }
+                else if (statusCode && statusCode >= 500) {
+                    throw new Error(`OpenAI API server error (${statusCode}) - try again later`);
+                }
+                // Include response data in error if available
+                const errorDetails = responseData
+                    ? `: ${JSON.stringify(responseData).substring(0, 200)}`
+                    : '';
+                throw new Error(`OpenAI API error (${statusCode || 'unknown'})${errorDetails}`);
+            }
+            // Handle other errors
+            const errorMessage = this._getErrorMessage(error);
+            logger.error('Failed to generate embedding', { error: errorMessage });
+            throw new Error(`Error generating embedding: ${errorMessage}`);
+        }
+    }
+    /**
+     * Generate embeddings for multiple texts
+     *
+     * @param texts - Array of texts to generate embeddings for
+     * @returns Promise resolving to array of embedding vectors
+     */
+    async generateEmbeddings(texts) {
+        try {
+            const response = await axios.post(this.apiEndpoint, {
+                input: texts,
+                model: this.model,
+            }, {
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+            });
+            const embeddings = response.data.data.map((item) => item.embedding);
+            // Normalize each embedding vector
+            embeddings.forEach((embedding) => {
+                this._normalizeVector(embedding);
+            });
+            return embeddings;
+        }
+        catch (error) {
+            const errorMessage = this._getErrorMessage(error);
+            throw new Error(`Failed to generate embeddings: ${errorMessage}`);
+        }
+    }
+    /**
+     * Get information about the embedding model
+     *
+     * @returns Model information
+     */
+    getModelInfo() {
+        return {
+            name: this.model,
+            dimensions: this.dimensions,
+            version: this.version,
+        };
+    }
+    /**
+     * Extract error message from error object
+     *
+     * @private
+     * @param error - Error object
+     * @returns Error message string
+     */
+    _getErrorMessage(error) {
+        if (error instanceof Error) {
+            return error.message;
+        }
+        return String(error);
+    }
+    /**
+     * Normalize a vector to unit length (L2 norm)
+     *
+     * @private
+     * @param vector - Vector to normalize in-place
+     */
+    _normalizeVector(vector) {
+        // Calculate magnitude (Euclidean norm / L2 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=OpenAIEmbeddingService.js.map

package/dist/embeddings/OpenAIEmbeddingService.js.map

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

package/dist/embeddings/config.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Configuration for the embedding subsystem
+ */
+/**
+ * Default settings for embedding job processing
+ */
+export declare const DEFAULT_EMBEDDING_SETTINGS: {
+    /**
+     * Maximum batch size for processing embedding jobs
+     * Larger batches may be more efficient but use more memory
+     */
+    BATCH_SIZE: number;
+    /**
+     * Minimum time in milliseconds between API calls (rate limiting)
+     */
+    API_RATE_LIMIT_MS: number;
+    /**
+     * Time-to-live in milliseconds for cached embeddings (default: 30 days)
+     */
+    CACHE_TTL_MS: number;
+    /**
+     * Maximum number of entries to keep in the embedding cache
+     */
+    CACHE_MAX_SIZE: number;
+    /**
+     * Minimum age in milliseconds for jobs to be eligible for cleanup
+     * Default: 30 days
+     */
+    JOB_CLEANUP_AGE_MS: number;
+    /**
+     * Status options for embedding jobs
+     */
+    JOB_STATUS: {
+        PENDING: string;
+        PROCESSING: string;
+        COMPLETED: string;
+        FAILED: string;
+    };
+};
+/**
+ * Configuration for the LRU cache used for embeddings
+ */
+export interface EmbeddingCacheOptions {
+    /**
+     * Maximum number of items to keep in the cache
+     */
+    max: number;
+    /**
+     * Time-to-live in milliseconds for cache entries
+     */
+    ttl: number;
+}
+/**
+ * Configuration for embedding job processing
+ */
+export interface EmbeddingJobProcessingOptions {
+    /**
+     * Maximum number of jobs to process in a single batch
+     */
+    batchSize: number;
+    /**
+     * Minimum time in milliseconds between API calls
+     */
+    apiRateLimitMs: number;
+    /**
+     * Maximum age in milliseconds for jobs to be eligible for cleanup
+     */
+    jobCleanupAgeMs: number;
+}
+/**
+ * Get configuration for the LRU cache for embeddings
+ *
+ * @param options - Optional overrides for cache settings
+ * @returns Configuration object for the LRU cache
+ */
+export declare function getEmbeddingCacheConfig(options?: Partial<EmbeddingCacheOptions>): EmbeddingCacheOptions;
+/**
+ * Get configuration for embedding job processing
+ *
+ * @param options - Optional overrides for job processing settings
+ * @returns Configuration object for job processing
+ */
+export declare function getJobProcessingConfig(options?: Partial<EmbeddingJobProcessingOptions>): EmbeddingJobProcessingOptions;