@astermind/astermind-elm/dist/core/EmbeddingStore.d.ts

JavaScript Extreme Learning Machine (ELM) library for browser and Node.js.

export type Metric = 'cosine' | 'dot' | 'euclidean' | 'manhattan';
export interface EmbeddingItem<M extends Record<string, any> = Record<string, any>> {
    id: string;
    vec: number[] | Float32Array;
    meta?: M;
}
export interface QueryOptions<M extends Record<string, any> = Record<string, any>> {
    /** Similarity/distance metric (default: 'cosine') */
    metric?: Metric;
    /** Return only hits that pass this predicate */
    filter?: (meta: M | undefined, id: string) => boolean;
    /** Include vectors in results (default: false) */
    returnVectors?: boolean;
    /** For cosine/dot: keep only hits with score >= minScore */
    minScore?: number;
    /** For L2/L1: keep only hits with distance <= maxDistance */
    maxDistance?: number;
    /** Optional subset restriction by ids */
    restrictToIds?: string[];
}
export interface SearchHit<M extends Record<string, any> = Record<string, any>> {
    id: string;
    score: number;
    index: number;
    meta?: M;
    vec?: Float32Array;
}
export interface EmbeddingStoreJSON<M extends Record<string, any> = Record<string, any>> {
    dim: number;
    /** If true, stored 'vec' arrays are L2-normalized (unit length) */
    normalized: boolean;
    /** If true, payload includes 'raw' arrays with the original unnormalized vectors */
    alsoStoredRaw?: boolean;
    /** Optional capacity for ring buffer behavior */
    capacity?: number;
    items: Array<{
        id: string;
        vec: number[];
        raw?: number[];
        meta?: M;
    }>;
    __version: string;
}
export declare class EmbeddingStore<M extends Record<string, any> = Record<string, any>> {
    private readonly dim;
    /** If true, 'vecs' are unit vectors (good for cosine); otherwise raw are stored in 'vecs' and norms[] is cached. */
    private readonly storeUnit;
    /** If true, keep original unnormalized vectors alongside normalized ones (enables Euclidean even when storeUnit=true). */
    private readonly alsoStoreRaw;
    private capacity?;
    private ids;
    private metas;
    private vecs;
    private rawVecs?;
    private norms?;
    private rawNorms?;
    private idToIdx;
    constructor(dim: number, opts?: {
        storeUnit?: boolean;
        capacity?: number;
        alsoStoreRaw?: boolean;
    });
    size(): number;
    dimension(): number;
    isUnitStored(): boolean;
    keepsRaw(): boolean;
    getCapacity(): number | undefined;
    setCapacity(capacity?: number): void;
    clear(): void;
    has(id: string): boolean;
    get(id: string): {
        id: string;
        vec: Float32Array;
        raw?: Float32Array;
        meta?: M;
    } | undefined;
    /** Remove by id. Returns true if removed. */
    remove(id: string): boolean;
    /** Add or replace an item by id. Returns true if added, false if replaced. */
    upsert(item: EmbeddingItem<M>): boolean;
    add(item: EmbeddingItem<M>): void;
    addAll(items: EmbeddingItem<M>[], allowUpsert?: boolean): void;
    /** Merge another store (same dim & normalization strategy) into this one. */
    merge(other: EmbeddingStore<M>, allowOverwrite?: boolean): void;
    /** Top-K KNN query. For L2/L1 we return NEGATIVE distance so higher is better. */
    query(queryVec: ArrayLike<number>, k?: number, opts?: QueryOptions<M>): SearchHit<M>[];
    /** Batch query helper. Returns array of results aligned to input queries. */
    queryBatch(queries: ArrayLike<number>[], k?: number, opts?: QueryOptions<M>): SearchHit<M>[][];
    /** Convenience: query by id */
    queryById(id: string, k?: number, opts?: QueryOptions<M>): SearchHit<M>[];
    toJSON(): EmbeddingStoreJSON<M>;
    static fromJSON<M extends Record<string, any> = Record<string, any>>(obj: string | EmbeddingStoreJSON<M>): EmbeddingStore<M>;
    /** Estimate memory footprint in bytes (arrays only; metadata excluded). */
    memoryUsageBytes(): number;
    /** Re-normalize all vectors in-place (useful if you bulk-updated raw storage). */
    reNormalizeAll(): void;
    /** Iterate over all items */
    entries(): IterableIterator<{
        id: string;
        vec: Float32Array;
        raw?: Float32Array;
        meta?: M;
    }>;
    private removeFromNorms;
    /** After a splice at 'start', rebuild id→index for shifted tail */
    private rebuildIndex;
    /** Enforce capacity by evicting oldest items (front of arrays) */
    private enforceCapacity;
    private buildNorms;
    private buildRawNorms;
}