@skillsmith/core 0.4.0 → 0.4.1

package/dist/src/embeddings/hnsw-store.helpers.d.ts

@@ -0,0 +1,83 @@
+/**
+ * HNSW Embedding Store Helper Functions
+ * @module @skillsmith/core/embeddings/hnsw-store.helpers
+ */
+import type { HierarchicalNSWConstructor, HNSWEmbeddingStoreOptions } from './hnsw-store.types.js';
+import { HNSW_PRESETS } from './hnsw-store.types.js';
+import { HNSWEmbeddingStore } from './hnsw-store.js';
+/**
+ * Create an HNSWEmbeddingStore with a preset configuration.
+ *
+ * @param preset - Preset name ('small', 'medium', 'large', 'xlarge')
+ * @param options - Additional options (merged with preset)
+ * @returns Configured HNSWEmbeddingStore instance
+ *
+ * @example
+ * ```typescript
+ * const store = createHNSWStore('large', {
+ *   dbPath: './embeddings.db',
+ *   indexPath: './embeddings.hnsw',
+ * });
+ * ```
+ */
+export declare function createHNSWStore(preset: keyof typeof HNSW_PRESETS, options?: Omit<HNSWEmbeddingStoreOptions, 'hnswConfig'>): HNSWEmbeddingStore;
+/**
+ * Check if hnswlib-node is available.
+ * Useful for conditional logic or graceful degradation.
+ *
+ * @returns true if hnswlib-node can be loaded
+ */
+export declare function isHNSWAvailable(): Promise<boolean>;
+/**
+ * Dynamically load hnswlib-node module.
+ *
+ * @returns The HierarchicalNSW constructor, or null if unavailable
+ * @internal
+ */
+export declare function loadHNSWLib(): Promise<{
+    HierarchicalNSW: HierarchicalNSWConstructor;
+} | null>;
+/**
+ * Compute cosine similarity between two embeddings.
+ * Standalone version for use outside of HNSWEmbeddingStore.
+ *
+ * @param a - First embedding
+ * @param b - Second embedding
+ * @returns Similarity score between -1 and 1
+ */
+export declare function computeCosineSimilarity(a: Float32Array, b: Float32Array): number;
+/**
+ * Convert HNSW distance to similarity score.
+ * HNSW returns distances, we need similarities (higher = more similar).
+ *
+ * @param distance - Distance value from HNSW
+ * @param metric - Distance metric used
+ * @returns Similarity score
+ */
+export declare function distanceToSimilarity(distance: number, metric?: 'cosine' | 'l2' | 'ip'): number;
+/**
+ * Estimate memory usage for an HNSW index.
+ *
+ * @param vectorCount - Number of vectors
+ * @param dimensions - Vector dimensionality
+ * @param m - HNSW M parameter
+ * @returns Estimated memory usage in bytes
+ */
+export declare function estimateMemoryUsage(vectorCount: number, dimensions: number, m: number): number;
+/**
+ * Validate embedding dimensions.
+ *
+ * @param embedding - Embedding to validate
+ * @param expectedDimensions - Expected dimension count
+ * @param context - Context for error message (default: 'Query')
+ * @throws Error if dimensions don't match
+ */
+export declare function validateDimensions(embedding: Float32Array, expectedDimensions: number, context?: string): void;
+/**
+ * Determine whether to use HNSW based on explicit option or environment.
+ *
+ * @param explicit - Explicit useHNSW option (if provided)
+ * @returns Whether to enable HNSW
+ */
+export declare function shouldUseHNSW(explicit?: boolean): boolean;
+//# sourceMappingURL=hnsw-store.helpers.d.ts.map

package/dist/src/embeddings/hnsw-store.helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hnsw-store.helpers.d.ts","sourceRoot":"","sources":["../../../src/embeddings/hnsw-store.helpers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,0BAA0B,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAA;AAClG,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAMpD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,OAAO,YAAY,EACjC,OAAO,GAAE,IAAI,CAAC,yBAAyB,EAAE,YAAY,CAAM,GAC1D,kBAAkB,CAKpB;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC,CAOxD;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC;IAC3C,eAAe,EAAE,0BAA0B,CAAA;CAC5C,GAAG,IAAI,CAAC,CASR;AAMD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,MAAM,CAiBhF;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,QAAQ,GAAG,IAAI,GAAG,IAAe,GACxC,MAAM,CAOR;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAI9F;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,YAAY,EACvB,kBAAkB,EAAE,MAAM,EAC1B,OAAO,GAAE,MAAgB,GACxB,IAAI,CAMN;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,CAYzD"}

package/dist/src/embeddings/hnsw-store.helpers.js

@@ -0,0 +1,147 @@
+/**
+ * HNSW Embedding Store Helper Functions
+ * @module @skillsmith/core/embeddings/hnsw-store.helpers
+ */
+import { HNSW_PRESETS } from './hnsw-store.types.js';
+import { HNSWEmbeddingStore } from './hnsw-store.js';
+// ============================================================================
+// Factory Functions
+// ============================================================================
+/**
+ * Create an HNSWEmbeddingStore with a preset configuration.
+ *
+ * @param preset - Preset name ('small', 'medium', 'large', 'xlarge')
+ * @param options - Additional options (merged with preset)
+ * @returns Configured HNSWEmbeddingStore instance
+ *
+ * @example
+ * ```typescript
+ * const store = createHNSWStore('large', {
+ *   dbPath: './embeddings.db',
+ *   indexPath: './embeddings.hnsw',
+ * });
+ * ```
+ */
+export function createHNSWStore(preset, options = {}) {
+    return new HNSWEmbeddingStore({
+        ...options,
+        hnswConfig: HNSW_PRESETS[preset],
+    });
+}
+/**
+ * Check if hnswlib-node is available.
+ * Useful for conditional logic or graceful degradation.
+ *
+ * @returns true if hnswlib-node can be loaded
+ */
+export async function isHNSWAvailable() {
+    try {
+        await Function('return import("hnswlib-node")')();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Dynamically load hnswlib-node module.
+ *
+ * @returns The HierarchicalNSW constructor, or null if unavailable
+ * @internal
+ */
+export async function loadHNSWLib() {
+    try {
+        const mod = await Function('return import("hnswlib-node")')();
+        return mod;
+    }
+    catch {
+        return null;
+    }
+}
+// ============================================================================
+// Utility Functions
+// ============================================================================
+/**
+ * Compute cosine similarity between two embeddings.
+ * Standalone version for use outside of HNSWEmbeddingStore.
+ *
+ * @param a - First embedding
+ * @param b - Second embedding
+ * @returns Similarity score between -1 and 1
+ */
+export function computeCosineSimilarity(a, b) {
+    if (a.length !== b.length) {
+        throw new Error(`Embedding dimension mismatch: ${a.length} vs ${b.length}`);
+    }
+    let dotProduct = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dotProduct += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    if (normA === 0 || normB === 0)
+        return 0;
+    return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+/**
+ * Convert HNSW distance to similarity score.
+ * HNSW returns distances, we need similarities (higher = more similar).
+ *
+ * @param distance - Distance value from HNSW
+ * @param metric - Distance metric used
+ * @returns Similarity score
+ */
+export function distanceToSimilarity(distance, metric = 'cosine') {
+    if (metric === 'cosine') {
+        // For cosine space, HNSW returns 1 - cosine_similarity
+        return 1 - distance;
+    }
+    // For L2/IP, need different conversion
+    return 1 / (1 + distance);
+}
+/**
+ * Estimate memory usage for an HNSW index.
+ *
+ * @param vectorCount - Number of vectors
+ * @param dimensions - Vector dimensionality
+ * @param m - HNSW M parameter
+ * @returns Estimated memory usage in bytes
+ */
+export function estimateMemoryUsage(vectorCount, dimensions, m) {
+    // HNSW uses ~(4 * dimensions + M * 4 * 2) bytes per vector
+    const bytesPerVector = 4 * dimensions + m * 8;
+    return vectorCount * bytesPerVector;
+}
+/**
+ * Validate embedding dimensions.
+ *
+ * @param embedding - Embedding to validate
+ * @param expectedDimensions - Expected dimension count
+ * @param context - Context for error message (default: 'Query')
+ * @throws Error if dimensions don't match
+ */
+export function validateDimensions(embedding, expectedDimensions, context = 'Query') {
+    if (embedding.length !== expectedDimensions) {
+        throw new Error(`${context} dimension mismatch: got ${embedding.length}, expected ${expectedDimensions}`);
+    }
+}
+/**
+ * Determine whether to use HNSW based on explicit option or environment.
+ *
+ * @param explicit - Explicit useHNSW option (if provided)
+ * @returns Whether to enable HNSW
+ */
+export function shouldUseHNSW(explicit) {
+    if (explicit !== undefined) {
+        return explicit;
+    }
+    const envValue = process.env.SKILLSMITH_USE_HNSW;
+    if (envValue !== undefined) {
+        return envValue === 'true' || envValue === '1';
+    }
+    // Default to false for backward compatibility
+    return false;
+}
+//# sourceMappingURL=hnsw-store.helpers.js.map

package/dist/src/embeddings/hnsw-store.helpers.js.map

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