@skillsmith/core 0.4.0 → 0.4.2

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

@@ -1,568 +1,58 @@
 /**
  * SMI-1519: HNSW Embedding Store
  *
- * High-performance vector storage using HNSW (Hierarchical Navigable Small World)
- * index for fast approximate nearest neighbor (ANN) search.
- *
- * Features:
- * - O(log n) similarity search vs O(n) brute-force (150x faster)
- * - SQLite for metadata persistence (skill_id, text, created_at)
- * - Graceful fallback to brute-force if HNSW unavailable
- * - Compatible with existing EmbeddingService interface
- * - Uses claude-flow V3 VectorDB API with automatic fallback
- *
- * Enable via environment variable: SKILLSMITH_USE_HNSW=true
+ * High-performance vector storage using HNSW index for fast ANN search.
+ * Uses claude-flow V3 VectorDB API with automatic fallback to brute-force.
  *
+ * Enable via: SKILLSMITH_USE_HNSW=true
  * @see ADR-009: Embedding Service Fallback Strategy
  */
 import type { SimilarityResult } from './index.js';
-/**
- * Type definitions for hnswlib-node (not published on DefinitelyTyped)
- * These are minimal declarations for the parts we use.
- *
- * @see https://github.com/yoshoku/hnswlib-node
- */
-export interface HierarchicalNSW {
-    initIndex(maxElements: number, m?: number, efConstruction?: number): void;
-    loadIndex(path: string, allowReplaceDeleted?: boolean): void;
-    saveIndex(path: string): void;
-    addPoint(point: number[] | Float32Array, label: number, replaceDeleted?: boolean): void;
-    markDelete(label: number): void;
-    searchKnn(query: number[] | Float32Array, k: number, filter?: (label: number) => boolean): HNSWSearchResult;
-    getMaxElements(): number;
-    getCurrentCount(): number;
-    getEfSearch(): number;
-    setEfSearch(ef: number): void;
-    getIdsList(): number[];
-}
-/**
- * Result from HNSW k-nearest neighbor search
- */
-export interface HNSWSearchResult {
-    /** Labels (IDs) of the nearest neighbors */
-    neighbors: number[];
-    /** Distances to each neighbor (lower = closer) */
-    distances: number[];
-}
-/**
- * Constructor type for HierarchicalNSW
- */
-export interface HierarchicalNSWConstructor {
-    new (space: 'cosine' | 'l2' | 'ip', dim: number): HierarchicalNSW;
-}
-/**
- * HNSW algorithm parameters for tuning search quality vs speed.
- *
- * @see https://github.com/nmslib/hnswlib/blob/master/ALGO_PARAMS.md
- */
-export interface HNSWConfig {
-    /**
-     * Number of bidirectional links per node (M parameter).
-     * Higher values = better recall but more memory/slower builds.
-     *
-     * - 8-16: Fast, lower memory, suitable for <100k vectors
-     * - 16-32: Balanced, good for 100k-1M vectors
-     * - 32-64: High recall, suitable for >1M vectors or high accuracy needs
-     *
-     * @default 16
-     */
-    m: number;
-    /**
-     * Size of dynamic candidate list during index construction.
-     * Higher values = better index quality but slower builds.
-     *
-     * - 100-200: Fast builds, acceptable quality
-     * - 200-400: Balanced
-     * - 400-500: High quality, slower builds
-     *
-     * @default 200
-     */
-    efConstruction: number;
-    /**
-     * Size of dynamic candidate list during search.
-     * Higher values = better recall but slower search.
-     *
-     * - 10-50: Fast search, may miss some neighbors
-     * - 50-100: Balanced
-     * - 100-200: High recall, slower search
-     *
-     * Must be >= topK for accurate results.
-     *
-     * @default 100
-     */
-    efSearch: number;
-    /**
-     * Vector dimensionality. Must match embedding model output.
-     * - 384 for all-MiniLM-L6-v2
-     * - 768 for all-mpnet-base-v2
-     *
-     * @default 384
-     */
-    dimensions: number;
-}
-/**
- * Options for HNSWEmbeddingStore initialization
- */
-export interface HNSWEmbeddingStoreOptions {
-    /**
-     * Path to SQLite database for metadata storage.
-     * If not provided, uses in-memory database.
-     */
-    dbPath?: string;
-    /**
-     * Path to HNSW index file for persistence.
-     * If not provided, index is built fresh on each startup.
-     */
-    indexPath?: string;
-    /**
-     * HNSW algorithm configuration.
-     * Uses sensible defaults if not provided.
-     */
-    hnswConfig?: Partial<HNSWConfig>;
-    /**
-     * Maximum number of elements the index can hold.
-     * Index will reject inserts once limit is reached.
-     *
-     * @default 100000
-     */
-    maxElements?: number;
-    /**
-     * Distance metric for similarity calculation.
-     * - 'cosine': Cosine similarity (default, best for normalized embeddings)
-     * - 'l2': Euclidean distance
-     * - 'ip': Inner product
-     *
-     * @default 'cosine'
-     */
-    distanceMetric?: 'cosine' | 'l2' | 'ip';
-    /**
-     * Force fallback to brute-force search (for testing or compatibility).
-     * If not specified, checks SKILLSMITH_USE_HNSW env var.
-     *
-     * When true, uses HNSW. When false, falls back to brute-force.
-     *
-     * @default undefined (auto-detect from environment)
-     */
-    useHNSW?: boolean;
-    /**
-     * Enable automatic index persistence.
-     * When true, saves index to indexPath after each insert.
-     * When false, must call saveIndex() manually.
-     *
-     * @default false
-     */
-    autoSave?: boolean;
-}
-/**
- * Statistics about the HNSW index
- */
-export interface HNSWIndexStats {
-    /** Number of vectors currently stored */
-    vectorCount: number;
-    /** Maximum capacity of the index */
-    maxCapacity: number;
-    /** Utilization percentage (vectorCount / maxCapacity * 100) */
-    utilizationPercent: number;
-    /** Current M parameter */
-    m: number;
-    /** Current efConstruction parameter */
-    efConstruction: number;
-    /** Current efSearch parameter */
-    efSearch: number;
-    /** Vector dimensionality */
-    dimensions: number;
-    /** Approximate memory usage in bytes */
-    memoryUsageBytes: number;
-    /** Whether using HNSW (true) or brute-force fallback (false) */
-    isHNSWEnabled: boolean;
-    /** Path to index file (if persistent) */
-    indexPath?: string;
-}
-/**
- * Result of a batch insert operation
- */
-export interface BatchInsertResult {
-    /** Number of vectors successfully inserted */
-    inserted: number;
-    /** Number of vectors that were updates (already existed) */
-    updated: number;
-    /** Number of vectors that failed to insert */
-    failed: number;
-    /** Skill IDs that failed with their error messages */
-    errors: Array<{
-        skillId: string;
-        error: string;
-    }>;
-    /** Total time taken in milliseconds */
-    durationMs: number;
-}
-/**
- * Interface for embedding storage with similarity search.
- * Implemented by both HNSWEmbeddingStore and EmbeddingService for compatibility.
- */
-export interface IEmbeddingStore {
-    /**
-     * Store an embedding with its metadata.
-     *
-     * @param skillId - Unique identifier for the skill
-     * @param embedding - Vector embedding (Float32Array)
-     * @param text - Original text that was embedded
-     */
-    storeEmbedding(skillId: string, embedding: Float32Array, text: string): void;
-    /**
-     * Retrieve a stored embedding by skill ID.
-     *
-     * @param skillId - Unique identifier for the skill
-     * @returns The embedding if found, null otherwise
-     */
-    getEmbedding(skillId: string): Float32Array | null;
-    /**
-     * Get all stored embeddings.
-     *
-     * @returns Map of skill IDs to their embeddings
-     */
-    getAllEmbeddings(): Map<string, Float32Array>;
-    /**
-     * Find most similar embeddings to a query vector.
-     *
-     * @param queryEmbedding - Query vector to find neighbors for
-     * @param topK - Number of results to return (default: 10)
-     * @returns Array of skill IDs with similarity scores, sorted descending
-     */
-    findSimilar(queryEmbedding: Float32Array, topK?: number): SimilarityResult[];
-    /**
-     * Compute cosine similarity between two embeddings.
-     *
-     * @param a - First embedding
-     * @param b - Second embedding
-     * @returns Similarity score between -1 and 1
-     */
-    cosineSimilarity(a: Float32Array, b: Float32Array): number;
-    /**
-     * Check if running in fallback (brute-force) mode.
-     *
-     * @returns true if using brute-force, false if using HNSW
-     */
-    isUsingFallback(): boolean;
-    /**
-     * Close database connections and release resources.
-     */
-    close(): void;
-}
-/**
- * Default HNSW configuration optimized for skill embeddings.
- * Tuned for ~10k-100k skills with balanced speed/recall.
- */
-export declare const DEFAULT_HNSW_CONFIG: HNSWConfig;
-/**
- * HNSW configuration presets for different use cases
- */
-export declare const HNSW_PRESETS: {
-    /** Fast search, lower memory, suitable for <10k vectors */
-    readonly small: {
-        m: number;
-        efConstruction: number;
-        efSearch: number;
-        dimensions: number;
-    };
-    /** Balanced performance, suitable for 10k-100k vectors */
-    readonly medium: {
-        m: number;
-        efConstruction: number;
-        efSearch: number;
-        dimensions: number;
-    };
-    /** High recall, suitable for 100k-1M vectors */
-    readonly large: {
-        m: number;
-        efConstruction: number;
-        efSearch: number;
-        dimensions: number;
-    };
-    /** Maximum recall, suitable for >1M vectors or critical accuracy */
-    readonly xlarge: {
-        m: number;
-        efConstruction: number;
-        efSearch: number;
-        dimensions: number;
-    };
-};
+export type { HierarchicalNSW, HNSWSearchResult, HierarchicalNSWConstructor, HNSWConfig, HNSWEmbeddingStoreOptions, HNSWIndexStats, BatchInsertResult, IEmbeddingStore, } from './hnsw-store.types.js';
+export { DEFAULT_HNSW_CONFIG, HNSW_PRESETS } from './hnsw-store.types.js';
+export { createHNSWStore, isHNSWAvailable, loadHNSWLib } from './hnsw-store.helpers.js';
+import type { HNSWConfig, HNSWEmbeddingStoreOptions, HNSWIndexStats, BatchInsertResult, IEmbeddingStore } from './hnsw-store.types.js';
 /**
  * High-performance embedding storage using HNSW index.
- *
- * Provides O(log n) approximate nearest neighbor search while maintaining
- * compatibility with the existing EmbeddingService interface.
- *
- * @example
- * ```typescript
- * // Basic usage
- * const store = new HNSWEmbeddingStore({
- *   dbPath: './embeddings.db',
- *   indexPath: './embeddings.hnsw',
- * });
- *
- * // Store embeddings
- * store.storeEmbedding('skill-1', embedding1, 'Jest testing framework helper');
- * store.storeEmbedding('skill-2', embedding2, 'Vitest testing utilities');
- *
- * // Find similar
- * const results = store.findSimilar(queryEmbedding, 10);
- * // [{ skillId: 'skill-1', score: 0.95 }, { skillId: 'skill-2', score: 0.87 }, ...]
- *
- * // Clean up
- * store.close();
- * ```
- *
- * @example
- * ```typescript
- * // With custom HNSW config for large dataset
- * const store = new HNSWEmbeddingStore({
- *   dbPath: './embeddings.db',
- *   indexPath: './embeddings.hnsw',
- *   hnswConfig: HNSW_PRESETS.large,
- *   maxElements: 500000,
- * });
- * ```
+ * Provides O(log n) approximate nearest neighbor search with SQLite persistence.
  */
 export declare class HNSWEmbeddingStore implements IEmbeddingStore {
-    /** SQLite database for metadata */
     private db;
-    /** HNSW index instance (from hnswlib-node) */
     private index;
-    /** Whether HNSW is enabled (false = brute-force fallback) */
     private readonly hnswEnabled;
-    /** Merged HNSW configuration */
     private readonly config;
-    /** Maximum index capacity */
     private readonly maxElements;
-    /** Path to HNSW index file */
     private readonly indexPath;
-    /** Distance metric */
     private readonly distanceMetric;
-    /** Auto-save flag */
     private readonly autoSave;
-    /** Map of skill IDs to internal HNSW labels (for reverse lookup) */
     private skillIdToLabel;
-    /** Map of HNSW labels to skill IDs */
     private labelToSkillId;
-    /** Next available label for HNSW insertion */
     private nextLabel;
-    /**
-     * Create a new HNSWEmbeddingStore instance.
-     *
-     * @param options - Configuration options
-     *
-     * @example
-     * ```typescript
-     * // Default configuration (auto-detects HNSW availability)
-     * const store = new HNSWEmbeddingStore();
-     *
-     * // With persistence
-     * const store = new HNSWEmbeddingStore({
-     *   dbPath: './embeddings.db',
-     *   indexPath: './embeddings.hnsw',
-     * });
-     *
-     * // Force brute-force fallback
-     * const store = new HNSWEmbeddingStore({ useHNSW: false });
-     * ```
-     */
-    /** V3 VectorDB instance (if initialized) */
     private vectorDB;
-    /** Promise for async initialization */
     private initPromise;
     constructor(options?: HNSWEmbeddingStoreOptions);
-    /**
-     * Ensure the store is fully initialized.
-     * Call this before operations that require the HNSW index.
-     */
     ensureInitialized(): Promise<void>;
-    /**
-     * Store an embedding with its metadata.
-     *
-     * Inserts the vector into both HNSW index (for fast search) and
-     * SQLite (for metadata persistence).
-     *
-     * @param skillId - Unique identifier for the skill
-     * @param embedding - Vector embedding (must match configured dimensions)
-     * @param text - Original text that was embedded
-     * @throws Error if embedding dimensions don't match configuration
-     */
     storeEmbedding(skillId: string, embedding: Float32Array, text: string): void;
-    /**
-     * Retrieve a stored embedding by skill ID.
-     *
-     * @param skillId - Unique identifier for the skill
-     * @returns The embedding if found, null otherwise
-     */
     getEmbedding(skillId: string): Float32Array | null;
-    /**
-     * Get all stored embeddings.
-     *
-     * Note: For large datasets, consider using findSimilar() instead
-     * to avoid loading all vectors into memory.
-     *
-     * @returns Map of skill IDs to their embeddings
-     */
     getAllEmbeddings(): Map<string, Float32Array>;
-    /**
-     * Find most similar embeddings to a query vector.
-     *
-     * Uses HNSW for O(log n) approximate search when available,
-     * falls back to O(n) brute-force cosine similarity otherwise.
-     *
-     * @param queryEmbedding - Query vector (must match configured dimensions)
-     * @param topK - Number of results to return (default: 10)
-     * @returns Array of skill IDs with similarity scores, sorted descending
-     */
     findSimilar(queryEmbedding: Float32Array, topK?: number): SimilarityResult[];
-    /**
-     * Async version of findSimilar for backends that require async search.
-     *
-     * @param queryEmbedding - Query vector (must match configured dimensions)
-     * @param topK - Number of results to return (default: 10)
-     * @returns Promise resolving to array of skill IDs with similarity scores
-     */
     findSimilarAsync(queryEmbedding: Float32Array, topK?: number): Promise<SimilarityResult[]>;
-    /**
-     * Compute cosine similarity between two embeddings.
-     *
-     * @param a - First embedding
-     * @param b - Second embedding
-     * @returns Similarity score between -1 and 1
-     * @throws Error if embeddings have different dimensions
-     */
     cosineSimilarity(a: Float32Array, b: Float32Array): number;
-    /**
-     * Check if running in fallback (brute-force) mode.
-     *
-     * @returns true if using brute-force, false if using HNSW
-     */
     isUsingFallback(): boolean;
-    /**
-     * Close database connections and release resources.
-     *
-     * Saves HNSW index to disk if indexPath was configured.
-     * Safe to call multiple times.
-     */
     close(): void;
-    /**
-     * Get statistics about the HNSW index.
-     *
-     * @returns Index statistics including capacity, utilization, and config
-     */
     getStats(): HNSWIndexStats;
-    /**
-     * Batch insert multiple embeddings efficiently.
-     *
-     * More efficient than calling storeEmbedding() in a loop
-     * due to batched SQLite transactions and HNSW insertions.
-     *
-     * @param embeddings - Array of embeddings to insert
-     * @returns Batch operation result with counts and timing
-     */
     batchInsert(embeddings: Array<{
         skillId: string;
         embedding: Float32Array;
         text: string;
     }>): BatchInsertResult;
-    /**
-     * Remove an embedding from the store.
-     *
-     * Note: HNSW does not support true deletion. The vector is marked
-     * as deleted and excluded from search results, but memory is not
-     * reclaimed until the index is rebuilt.
-     *
-     * @param skillId - Unique identifier for the skill to remove
-     * @returns true if removed, false if not found
-     */
     removeEmbedding(skillId: string): boolean;
-    /**
-     * Save the HNSW index to disk.
-     *
-     * Note: V3 VectorDB manages its own persistence, so this is a no-op
-     * unless using hnswlib-node directly.
-     *
-     * @throws Error if indexPath was not configured
-     */
     saveIndex(): void;
-    /**
-     * Load the HNSW index from disk.
-     *
-     * Note: V3 VectorDB manages its own persistence, so this is a no-op
-     * unless using hnswlib-node directly.
-     *
-     * @throws Error if indexPath was not configured or file doesn't exist
-     */
     loadIndex(): void;
-    /**
-     * Rebuild the HNSW index from SQLite data.
-     *
-     * Useful after many deletions to reclaim memory, or to apply
-     * new HNSW configuration parameters.
-     *
-     * @param newConfig - Optional new HNSW configuration
-     */
     rebuildIndex(newConfig?: Partial<HNSWConfig>): Promise<void>;
-    /**
-     * Update efSearch parameter at runtime.
-     *
-     * Note: V3 VectorDB does not expose efSearch tuning directly.
-     * This method is provided for API compatibility.
-     *
-     * @param efSearch - New efSearch value (must be > 0)
-     */
     setEfSearch(efSearch: number): void;
-    /**
-     * Determine whether to use HNSW based on explicit option or environment.
-     */
-    private shouldUseHNSW;
-    /**
-     * Initialize SQLite database and create tables.
-     */
     private initDatabase;
-    /**
-     * Initialize HNSW index using V3 VectorDB API.
-     * Falls back gracefully if V3 is unavailable.
-     */
     private initHNSWIndex;
-    /**
-     * Convert HNSW distance to similarity score.
-     * HNSW returns distances, we need similarities (higher = more similar).
-     */
     private distanceToSimilarity;
 }
-/**
- * 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>;
 //# sourceMappingURL=hnsw-store.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"hnsw-store.d.ts","sourceRoot":"","sources":["../../../src/embeddings/hnsw-store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"hnsw-store.d.ts","sourceRoot":"","sources":["../../../src/embeddings/hnsw-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAMlD,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,0BAA0B,EAC1B,UAAU,EACV,yBAAyB,EACzB,cAAc,EACd,iBAAiB,EACjB,eAAe,GAChB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAGzE,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAGvF,OAAO,KAAK,EACV,UAAU,EACV,yBAAyB,EACzB,cAAc,EACd,iBAAiB,EACjB,eAAe,EAEhB,MAAM,uBAAuB,CAAA;AAI9B;;;GAGG;AACH,qBAAa,kBAAmB,YAAW,eAAe;IACxD,OAAO,CAAC,EAAE,CAA4B;IACtC,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAQ;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoB;IAC9C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAwB;IACvD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,cAAc,CAAiC;IACvD,OAAO,CAAC,cAAc,CAAiC;IACvD,OAAO,CAAC,SAAS,CAAI;IACrB,OAAO,CAAC,QAAQ,CAAwB;IACxC,OAAO,CAAC,WAAW,CAA6B;gBAEpC,OAAO,GAAE,yBAA8B;IAkB7C,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxC,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAsB5E,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAalD,gBAAgB,IAAI,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC;IAiB7C,WAAW,CAAC,cAAc,EAAE,YAAY,EAAE,IAAI,GAAE,MAAW,GAAG,gBAAgB,EAAE;IA0B1E,gBAAgB,CACpB,cAAc,EAAE,YAAY,EAC5B,IAAI,GAAE,MAAW,GAChB,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAgB9B,gBAAgB,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,MAAM;IAgB1D,eAAe,IAAI,OAAO;IAI1B,KAAK,IAAI,IAAI;IAOb,QAAQ,IAAI,cAAc;IA4B1B,WAAW,CACT,UAAU,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,YAAY,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,GAC5E,iBAAiB;IAqDpB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAmBzC,SAAS,IAAI,IAAI;IAKjB,SAAS,IAAI,IAAI;IAKX,YAAY,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAwBlE,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAOnC,OAAO,CAAC,YAAY;YAcN,aAAa;IAsC3B,OAAO,CAAC,oBAAoB;CAI7B"}

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"}