@ai4data/search 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,693 @@
+/**
+ * Types for the collection manifest format produced by the Python pipeline.
+ * The manifest.json file is the browser's entry point to a search collection.
+ */
+interface FlatIndexConfig {
+    /** Relative path to the flat brute-force index, e.g. "flat/embeddings.int8.json" */
+    path: string;
+}
+interface HNSWIndexConfig {
+    /** Directory prefix for all HNSW index files, e.g. "index/" */
+    path: string;
+    /** Relative path to index/config.json */
+    config: string;
+    /** Relative path to index/upper_layers.json */
+    upper_layers?: string;
+    /** Relative path to index/node_to_shard.json */
+    node_to_shard?: string;
+    /** Relative path to index/titles.json (display metadata, no vectors) */
+    titles?: string;
+    /** Relative path to index/cluster_centroids.json */
+    cluster_centroids?: string;
+    /** Relative path to index/bm25_corpus.json (lightweight text-only corpus for BM25) */
+    bm25_corpus?: string;
+}
+type SearchMode$1 = 'flat' | 'hnsw';
+interface ManifestThresholds {
+    /** Maximum n_items for flat (brute-force) mode; above this HNSW is used */
+    flat_max: number;
+}
+/**
+ * Top-level manifest written by 03_build_index.py.
+ * The browser worker fetches this URL first to determine the search mode.
+ */
+interface CollectionManifest {
+    version?: string;
+    collection_id: string;
+    n_items: number;
+    embedding_dim: number;
+    matryoshka_dim?: number | null;
+    quant?: string;
+    model_id: string;
+    search_mode: SearchMode$1;
+    /** Whether index files are gzip-compressed (.json.gz). Static hosts like GitHub Pages require false. */
+    compressed: boolean;
+    flat?: FlatIndexConfig;
+    index?: HNSWIndexConfig;
+    thresholds?: ManifestThresholds;
+    /** Fields included in result metadata (e.g. ["idno","title","abstract","type","doi"]) */
+    preview_fields?: string[];
+    /** Fields used for BM25 lexical search */
+    bm25_fields?: string[];
+}
+/**
+ * Parsed HNSW config.json contents, loaded by HNSWEngine at init.
+ */
+interface HNSWConfig {
+    n_items: number;
+    dim: number;
+    matryoshka_dim: number | null;
+    quant: string;
+    hnsw_M: number;
+    hnsw_ef_construction: number;
+    n_layers: number;
+    n_clusters: number;
+    entry_node_id: number;
+    entry_layer: number;
+    recall_at_10: number;
+}
+/**
+ * A single entry in index/bm25_corpus.json.
+ * Lightweight text corpus written by the pipeline for BM25 indexing.
+ */
+interface BM25CorpusEntry {
+    id: string | number;
+    title: string;
+    text: string;
+}
+
+/**
+ * Core search types: result shapes, options, and the shared engine interface.
+ */
+interface SearchResult {
+    /** Integer node ID (HNSW insertion order) or string document ID (flat mode) */
+    id: number | string;
+    /** Document identifier from the source data (e.g. "WPS9999") */
+    idno?: string;
+    /** Cosine similarity (semantic) or combined hybrid score in [0, 1] */
+    score: number;
+    title: string;
+    /** Abstract / body text (present in flat mode; absent in HNSW-only results) */
+    text?: string;
+    abstract?: string;
+    type?: string;
+    type_extra?: string;
+    sub_title?: string;
+    doi?: string;
+    url?: string;
+    geographic_coverage?: GeographicCoverage[];
+    time_coverage?: string;
+    source?: string[];
+    /** Normalized semantic contribution (0–1) in hybrid mode */
+    semanticScore?: number;
+    /** Normalized BM25 contribution (0–1) in hybrid mode */
+    lexicalScore?: number;
+    /** Score from cross-encoder reranker (higher = more relevant) */
+    rerank_score?: number;
+    /** Allow arbitrary additional preview fields from the pipeline */
+    [key: string]: unknown;
+}
+type GeographicCoverage = string | {
+    title?: string;
+    name?: string;
+    type?: string;
+    [key: string]: unknown;
+};
+interface SearchStats {
+    /** Wall-clock milliseconds for the entire search() call */
+    latencyMs: number;
+    /** New shard files fetched during this query (0 = fully cached) */
+    shardsLoaded: number;
+    /** Total shards currently held in the worker's in-memory Map */
+    totalCachedShards: number;
+}
+interface SearchOptions {
+    topK?: number;
+    /** HNSW beam width at layer 0 (higher = better recall, more shard fetches) */
+    ef?: number;
+    /** HNSW beam width for upper-layer descent */
+    ef_upper?: number;
+    /** Minimum cosine similarity threshold (flat mode) */
+    threshold?: number;
+}
+/**
+ * Common interface implemented by both FlatEngine and HNSWEngine.
+ * Allows search.worker.ts to operate on either engine without type narrowing.
+ */
+interface SearchEngine {
+    readonly ready: boolean;
+    search(queryVec: Float32Array, opts?: SearchOptions): Promise<SearchResult[]> | SearchResult[];
+    lastStats: SearchStats | null;
+}
+/**
+ * A single item in the flat index (flat/embeddings.int8.json).
+ * Contains the int8 quantized vector plus all preview fields.
+ */
+interface FlatItem {
+    id: string | number;
+    idno?: string;
+    title: string;
+    text: string;
+    scale: number;
+    /** Stored as plain number[] in the JSON; converted to Int8Array on load */
+    qv: number[] | Int8Array;
+    type?: string;
+    [key: string]: unknown;
+}
+/**
+ * A node in a layer-0 shard file.
+ */
+interface ShardNode {
+    id: number;
+    scale: number;
+    qv: number[];
+    neighbors: number[];
+}
+/**
+ * Contents of index/layer0/shard_NNN.json.
+ */
+interface Shard {
+    shard_id: number;
+    nodes: ShardNode[];
+}
+/**
+ * A minimal interface for wink-bm25-text-search, enough to type HybridSearch
+ * without a full declaration file for the library.
+ */
+interface BM25Engine {
+    /** Returns [[docIdx, score], ...] sorted by score descending */
+    search(query: string, topK: number): [number, number][];
+}
+
+/**
+ * Discriminated union types for the search worker message protocol.
+ *
+ * Using discriminated unions lets TypeScript narrow the message type in each
+ * `case` branch of the message handler, eliminating unsafe `as` casts and
+ * ensuring inbound/outbound messages stay in sync.
+ *
+ * Usage in main thread:
+ *   worker.postMessage({ type: 'init', manifestUrl: '...' } satisfies WorkerInboundMessage)
+ *
+ * Usage in worker:
+ *   self.postMessage({ type: 'ready', mode: 'hnsw', config: manifest } satisfies WorkerOutboundMessage)
+ */
+
+type WorkerInboundMessage = WorkerInitMessage | WorkerSearchMessage | WorkerEmbedMessage | WorkerPingMessage | WorkerGetRecentMessage | WorkerSearchCompareMessage;
+interface WorkerInitMessage {
+    type: 'init';
+    /** Must be an absolute URL — resolve with new URL(url, location.href).href before posting */
+    manifestUrl: string;
+    /** HuggingFace model ID, defaults to avsolatorio/GIST-small-Embedding-v0 */
+    modelId?: string;
+    /** If true, skip loading the embedding model (for testing BM25 fallback). Index + BM25 still load. */
+    skipModelLoad?: boolean;
+    /** Delay (seconds) before starting to load the embedding model; index + BM25 load first (for testing). */
+    modelLoadDelaySeconds?: number;
+}
+interface WorkerSearchMessage {
+    type: 'search';
+    text: string;
+    topK?: number;
+    ef?: number;
+    ef_upper?: number;
+    threshold?: number;
+    mode?: 'semantic' | 'lexical' | 'hybrid';
+}
+interface WorkerEmbedMessage {
+    type: 'embed';
+    text: string;
+}
+interface WorkerPingMessage {
+    type: 'ping';
+}
+interface WorkerGetRecentMessage {
+    type: 'getRecent';
+    limit?: number;
+}
+interface WorkerSearchCompareMessage {
+    type: 'searchCompare';
+    text: string;
+    topK?: number;
+    ef?: number;
+    ef_upper?: number;
+}
+type WorkerOutboundMessage = WorkerProgressMessage | WorkerIndexReadyMessage | WorkerReadyMessage | WorkerResultsMessage | WorkerEmbeddingMessage | WorkerPongMessage | WorkerLoadingMessage | WorkerRecentMessage | WorkerCompareMessage | WorkerErrorMessage;
+interface WorkerProgressMessage {
+    type: 'progress';
+    phase: 'model' | 'index';
+    message: string;
+}
+/**
+ * Sent when the index files + BM25 corpus are loaded.
+ * Lexical search is available from this point on, even if the embedding model
+ * is still downloading (BM25 fallback).
+ */
+interface WorkerIndexReadyMessage {
+    type: 'index_ready';
+    bm25Ready: boolean;
+}
+/**
+ * Sent when the index is ready; if the embedding model was loaded, semantic/hybrid are available.
+ * When skipModelLoad was used, modelLoaded is false and only lexical (BM25) runs for semantic/hybrid.
+ */
+interface WorkerReadyMessage {
+    type: 'ready';
+    mode: 'flat' | 'hnsw';
+    config: CollectionManifest;
+    /** false when init was called with skipModelLoad (embedding model not loaded). */
+    modelLoaded?: boolean;
+}
+interface WorkerResultsMessage {
+    type: 'results';
+    data: SearchResult[];
+    stats?: SearchStats | null;
+    /**
+     * true when the result was produced via BM25 fallback because the embedding
+     * model was not yet ready (requested mode was semantic or hybrid).
+     */
+    fallback?: boolean;
+}
+interface WorkerEmbeddingMessage {
+    type: 'embedding';
+    /** Transferred as ArrayBuffer for zero-copy */
+    data: Float32Array;
+}
+interface WorkerPongMessage {
+    type: 'pong';
+}
+interface WorkerLoadingMessage {
+    type: 'loading';
+}
+interface WorkerRecentMessage {
+    type: 'recent';
+    data: SearchResult[];
+}
+interface WorkerCompareMessage {
+    type: 'compare';
+    hnsw: SearchResult[];
+    flat: SearchResult[];
+    recall: number;
+    overlap: number;
+    k: number;
+}
+interface WorkerErrorMessage {
+    type: 'error';
+    message: string;
+    originalType?: string;
+}
+
+/**
+ * SearchClient — framework-agnostic wrapper around the search Web Worker.
+ *
+ * Works in any JavaScript environment that supports Web Workers.
+ * Extend or wrap with framework adapters (see adapters/vue.ts, adapters/react.ts).
+ *
+ * @example
+ * ```ts
+ * const client = new SearchClient('https://example.com/data/prwp/manifest.json')
+ *
+ * client.on('index_ready', () => {
+ *   client.search('climate finance', { topK: 10, mode: 'hybrid' })
+ * })
+ *
+ * client.on('results', ({ data, stats }) => {
+ *   console.log(data)   // SearchResult[]
+ *   console.log(stats)  // SearchStats | null
+ * })
+ *
+ * // Clean up when done
+ * client.destroy()
+ * ```
+ */
+
+type SearchMode = 'semantic' | 'lexical' | 'hybrid';
+interface SearchClientOptions {
+    /** HuggingFace model ID to use for embeddings (default: avsolatorio/GIST-small-Embedding-v0) */
+    modelId?: string;
+    /** If true, skip loading the embedding model (for testing BM25 fallback). */
+    skipModelLoad?: boolean;
+    /** Delay (seconds) before loading the embedding model; index + BM25 load first (for testing). */
+    modelLoadDelaySeconds?: number;
+    /**
+     * Factory function that creates the Web Worker.
+     * Defaults to the bundled search worker created via `new URL()`.
+     * Override when you need a custom worker path (e.g. CDN, service worker proxy).
+     *
+     * @example
+     * ```ts
+     * // Vite / webpack 5 (recommended — bundler resolves the path)
+     * new SearchClient(url, {
+     *   workerFactory: () => new Worker(new URL('@ai4data/search/worker', import.meta.url), { type: 'module' })
+     * })
+     * ```
+     */
+    workerFactory?: () => Worker;
+}
+type MessageHandler<T extends WorkerOutboundMessage['type']> = (msg: Extract<WorkerOutboundMessage, {
+    type: T;
+}>) => void;
+declare class SearchClient {
+    /** True once the index + BM25 corpus are loaded. Lexical search available. */
+    isIndexReady: boolean;
+    /** True once the ONNX embedding model is ready. Semantic + hybrid search available. */
+    isModelReady: boolean;
+    /** Latest progress/status message from the worker. */
+    loadingMessage: string;
+    /** True when the last search fell back to BM25 because the model wasn't ready. */
+    activeFallback: boolean;
+    /** Parsed collection manifest, available after `index_ready`. */
+    manifest: CollectionManifest | null;
+    private readonly worker;
+    private readonly handlers;
+    private destroyed;
+    /**
+     * @param manifestUrl - Absolute or relative URL to `manifest.json`.
+     *   Relative URLs are resolved against `location.href`.
+     * @param opts        - Optional configuration.
+     */
+    constructor(manifestUrl: string, opts?: SearchClientOptions);
+    /**
+     * Subscribe to a specific worker message type.
+     * Returns an unsubscribe function — call it to remove the handler.
+     *
+     * @example
+     * ```ts
+     * const off = client.on('results', ({ data }) => setResults(data))
+     * // later…
+     * off()
+     * ```
+     */
+    on<T extends WorkerOutboundMessage['type']>(type: T, handler: MessageHandler<T>): () => void;
+    /**
+     * Submit a search query. No-op if the index is not yet ready.
+     *
+     * @param text - Natural-language query
+     * @param opts - Optional topK, ef, mode ('semantic' | 'lexical' | 'hybrid')
+     */
+    search(text: string, opts?: SearchOptions & {
+        mode?: SearchMode;
+    }): void;
+    /**
+     * Fetch the most-recent items from the index (useful for pre-search state).
+     */
+    getRecent(limit?: number): void;
+    /**
+     * Ping the worker. Resolves when the worker responds with 'pong'.
+     */
+    ping(): Promise<void>;
+    /**
+     * Terminate the worker and clean up all event listeners.
+     * The client is unusable after this call.
+     */
+    destroy(): void;
+    private _handleMessage;
+}
+
+/**
+ * flat-engine.ts
+ *
+ * Brute-force (flat) search engine backed by an Int8-quantized index.
+ * Suitable for collections up to ~50 k documents where exact nearest-neighbour
+ * search is fast enough without an ANN index structure.
+ */
+
+/**
+ * Brute-force semantic search engine.
+ *
+ * Usage:
+ * ```ts
+ * const engine = new FlatEngine()
+ * await engine.load('/data/flat/embeddings.int8.json')
+ * const results = engine.search(queryVec, { topK: 10 })
+ * ```
+ */
+declare class FlatEngine implements SearchEngine {
+    /** Internal item list with Int8-converted vectors */
+    private items;
+    /** True once `load()` has completed successfully */
+    readonly ready: boolean;
+    /** Statistics from the most recent `search()` call, or `null` before first search */
+    lastStats: SearchStats | null;
+    constructor();
+    /**
+     * Fetch and parse the flat index file, converting all `qv` arrays to `Int8Array`.
+     *
+     * @param url - URL of the `embeddings.int8.json` index file
+     * @returns The raw item list from the JSON (before Int8 conversion)
+     */
+    load(url: string): Promise<FlatItem[]>;
+    /**
+     * Run a brute-force cosine-similarity search over all loaded items.
+     *
+     * @param queryVec - L2-normalised query embedding (Float32Array)
+     * @param opts     - Optional search parameters
+     * @returns Top-K results sorted by descending score
+     * @throws {Error} If called before `load()` has completed
+     */
+    search(queryVec: Float32Array, opts?: SearchOptions): SearchResult[];
+}
+
+/**
+ * hnsw-engine.ts
+ *
+ * Approximate nearest-neighbour search using a pre-built HNSW index.
+ * Upper layers (layers ≥ 1) are held entirely in memory; layer-0 is
+ * loaded on demand from shard files via `ShardLoader`.
+ */
+
+/** Options accepted by `HNSWEngine.init()` */
+interface HNSWInitOptions {
+    /** Cache Storage bucket name forwarded to `ShardLoader` and `fetchJson` */
+    cacheName?: string;
+    /** Parsed manifest; used to resolve index file paths and compressed flag */
+    manifest?: CollectionManifest | null;
+}
+/**
+ * HNSW approximate nearest-neighbour search engine.
+ *
+ * Typical usage:
+ * ```ts
+ * const engine = new HNSWEngine()
+ * await engine.init('/data/prwp/')
+ * const results = await engine.search(queryVec, { topK: 10, ef: 50 })
+ * ```
+ */
+declare class HNSWEngine implements SearchEngine {
+    /** Parsed `index/config.json` */
+    private config;
+    /** Parsed `index/upper_layers.json` */
+    private upperLayers;
+    /** Maps string node ID → shard ID */
+    private nodeToShard;
+    /** Shard loader for layer-0 data */
+    private loader;
+    /** In-memory node cache (Int8 vectors, neighbours) */
+    private nodeCache;
+    /** True once `init()` has completed successfully */
+    readonly ready: boolean;
+    /** Statistics from the most recent `search()` call, or `null` before first search */
+    lastStats: SearchStats | null;
+    constructor();
+    /**
+     * Load all index metadata and populate the upper-layer node cache.
+     * This must be called (and awaited) before any call to `search()`.
+     *
+     * @param baseUrl - Base URL of the collection directory (e.g. `/data/prwp/`)
+     * @param opts    - Optional cache name and manifest
+     */
+    init(baseUrl: string, opts?: HNSWInitOptions): Promise<void>;
+    /**
+     * Search the HNSW index for the nearest neighbours of `queryVec`.
+     *
+     * @param queryVec - L2-normalised query embedding (Float32Array)
+     * @param opts     - Optional search parameters (`topK`, `ef`, `ef_upper`)
+     * @returns Top-K results sorted by descending score
+     * @throws {Error} If called before `init()` has completed
+     */
+    search(queryVec: Float32Array, opts?: SearchOptions): Promise<SearchResult[]>;
+    /**
+     * Single-layer greedy beam descent for layers ≥ 1 (upper layers).
+     * All nodes at these layers are already in `nodeCache`.
+     *
+     * @param queryVec    - L2-normalised query vector
+     * @param entryPoints - Current best candidates as `[score, nodeId]` tuples
+     * @param layer       - Layer index to traverse
+     * @param ef_upper    - Beam width (number of candidates to keep)
+     * @returns Updated candidate list for the next layer
+     */
+    private _beamDescentLayer;
+    /**
+     * Score a node that is present in `nodeCache` (upper-layer or already loaded layer-0).
+     *
+     * @param queryVec - L2-normalised query vector
+     * @param nodeId   - Node to score
+     * @returns Approximate dot-product similarity, or `-Infinity` if node is absent
+     */
+    private _scoreUpperNode;
+    /**
+     * Layer-0 beam search.  Loads shard files on demand as the search frontier expands.
+     *
+     * @param queryVec    - L2-normalised query vector
+     * @param entryPoints - Entry candidates from upper-layer descent
+     * @param ef          - Beam width (number of candidates to maintain in `W`)
+     * @returns All candidates in `W` sorted by descending score as `SearchResult` objects
+     */
+    private _beamSearchLayer0;
+    /**
+     * Retrieve a layer-0 node from cache, loading its shard file if necessary.
+     * Once loaded, the node entry in `nodeCache` is augmented with `neighbors`
+     * and `_l0loaded = true`.
+     *
+     * @param nodeId - Node to retrieve
+     * @returns Fully populated cache entry, or `null` if the node cannot be found
+     */
+    private _getLayer0Node;
+}
+
+/**
+ * hybrid-search.ts
+ *
+ * Combines semantic (HNSW / flat) and lexical (BM25) search results using
+ * min-max normalisation and a configurable linear blend.
+ */
+
+/** Options accepted by `HybridSearch.search()` */
+interface HybridSearchOptions {
+    /** Number of results to return (default: 20) */
+    topK?: number;
+    /** Weight applied to normalised semantic scores (default: 0.7) */
+    semanticWeight?: number;
+    /** Weight applied to normalised BM25 scores (default: 0.3) */
+    lexicalWeight?: number;
+    /** HNSW beam width forwarded to the semantic engine (default: 50) */
+    ef?: number;
+    /** Search mode: `'semantic'`, `'lexical'`, or `'hybrid'` (default: `'hybrid'`) */
+    mode?: 'semantic' | 'lexical' | 'hybrid';
+}
+/**
+ * Hybrid search combining a semantic vector engine and an optional BM25 engine.
+ *
+ * In `'hybrid'` mode both engines are queried in parallel; scores are
+ * min-max normalised independently and then linearly blended.
+ *
+ * Example:
+ * ```ts
+ * const hybrid = new HybridSearch(hnswEngine, bm25Engine, id => titlesMap[id])
+ * const results = await hybrid.search(queryVec, 'development finance', { topK: 10 })
+ * ```
+ */
+declare class HybridSearch {
+    private readonly semantic;
+    private readonly bm25;
+    private readonly idToMeta;
+    /**
+     * @param semanticEngine - Initialised `SearchEngine` (FlatEngine or HNSWEngine)
+     * @param bm25Engine     - Optional BM25 engine; pass `null` to disable lexical search
+     * @param idToMeta       - Optional callback to look up display metadata by document ID
+     */
+    constructor(semanticEngine: SearchEngine, bm25Engine?: BM25Engine | null, idToMeta?: ((id: number | string) => Partial<SearchResult>) | null);
+    /**
+     * Run a hybrid (or single-mode) search query.
+     *
+     * @param queryVec  - L2-normalised query embedding, or `null` for lexical-only mode
+     * @param queryText - Raw query string for BM25, or empty string for semantic-only mode
+     * @param opts      - Search options
+     * @returns Top-K results sorted by descending combined score
+     */
+    search(queryVec: Float32Array | null, queryText: string, opts?: HybridSearchOptions): Promise<SearchResult[]>;
+    /**
+     * Run the BM25 engine and map raw `[docIdx, score]` tuples to `SearchResult` objects.
+     *
+     * @param queryText - Raw query string
+     * @param topK      - Maximum number of results to return
+     * @returns BM25 results as `SearchResult` objects (score order: descending)
+     */
+    private _runBM25;
+    /**
+     * Format single-mode results, adding the appropriate `semanticScore` /
+     * `lexicalScore` fields expected by callers.
+     *
+     * @param results - Raw results from one engine
+     * @param topK    - Slice limit
+     * @param source  - Which engine produced the results
+     * @returns Results annotated with zeroed-out score fields for the unused engine
+     */
+    private _formatResults;
+}
+
+/**
+ * fetch-json.ts
+ *
+ * Utility for fetching JSON (plain or gzip-compressed) with optional
+ * Cache Storage read/write so repeat cold-starts skip the network.
+ */
+interface FetchJsonOptions {
+    /**
+     * When provided, the response is read from (and written to) a named
+     * Cache Storage bucket.  Pass `null` to disable caching entirely.
+     */
+    cacheName?: string | null;
+}
+/**
+ * Fetch a JSON resource, transparently handling gzip-compressed responses.
+ *
+ * Caching behaviour:
+ *  1. If `cacheName` is set and the Cache API is available, attempt a cache hit.
+ *  2. On a miss, fetch from the network.
+ *  3. Decompress if the URL ends with `.gz` and the server did not already
+ *     decompress it (i.e. `Content-Encoding` is absent or non-gzip).
+ *  4. Write the parsed object back to Cache Storage for future requests.
+ *
+ * @param url  - Absolute or relative URL to fetch
+ * @param opts - Optional caching configuration
+ * @returns Parsed JSON payload cast to `T`
+ * @throws {Error} On non-2xx HTTP responses
+ */
+declare function fetchJson<T = unknown>(url: string, opts?: FetchJsonOptions): Promise<T>;
+
+/**
+ * int8-codec.ts
+ *
+ * Quantization scheme: vectors are stored as Int8 values in [-127, 127].
+ * Each vector is accompanied by a scalar `scale` such that the original
+ * float value ≈ int8_value * scale.  Dot products are computed in mixed
+ * precision (Float32 query × dequantized Int8 stored vector) to keep
+ * both accuracy and memory efficiency.
+ */
+/**
+ * Compute the dot product between a Float32 query vector and a stored
+ * Int8-quantized vector, dequantizing on the fly.
+ *
+ * @param queryF32   - L2-normalised query vector (Float32Array)
+ * @param storedQV   - Int8-quantized stored vector
+ * @param storedScale - Per-vector dequantization scale factor
+ * @returns Approximate cosine similarity score
+ */
+declare function dotProductMixed(queryF32: Float32Array, storedQV: Int8Array, storedScale: number): number;
+/**
+ * Dequantize an Int8 vector back to Float32 using the stored scale.
+ *
+ * @param qv    - Int8-quantized vector
+ * @param scale - Per-vector dequantization scale factor
+ * @returns Reconstructed Float32 vector
+ */
+declare function dequantize(qv: Int8Array, scale: number): Float32Array;
+/**
+ * L2-normalise a Float32 vector in place.
+ * Vectors whose norm is below 1e-9 are left unchanged to avoid division by zero.
+ *
+ * @param vec - Vector to normalise (mutated in place)
+ * @returns The same (now normalised) vector
+ */
+declare function l2NormalizeInPlace(vec: Float32Array): Float32Array;
+/**
+ * Convert a plain number array (or an existing Int8Array) to an Int8Array.
+ * Values outside [-128, 127] are silently truncated by the typed-array constructor.
+ *
+ * @param arr - Source values
+ * @returns An Int8Array view / copy of the input
+ */
+declare function toInt8Array(arr: number[] | Int8Array): Int8Array;
+
+export { type BM25CorpusEntry, type BM25Engine, type CollectionManifest, FlatEngine, type FlatIndexConfig, type FlatItem, type GeographicCoverage, type HNSWConfig, HNSWEngine, type HNSWIndexConfig, HybridSearch, SearchClient, type SearchClientOptions, type SearchEngine, type SearchMode, type SearchOptions, type SearchResult, type SearchStats, type Shard, type ShardNode, type WorkerErrorMessage, type WorkerInboundMessage, type WorkerIndexReadyMessage, type WorkerInitMessage, type WorkerOutboundMessage, type WorkerProgressMessage, type WorkerReadyMessage, type WorkerResultsMessage, type WorkerSearchMessage, dequantize, dotProductMixed, fetchJson, l2NormalizeInPlace, toInt8Array };