/**
 * Sample dataset loader for CyborgDB.
 *
 * Fetches a small reference dataset hosted on S3 on demand and caches it
 * locally, so quickstart and test code can populate an index without bundling
 * data into the SDK. Hosting the dataset out-of-band keeps the SDK lean and
 * lets us iterate the dataset without cutting an SDK release.
 *
 * Runs on any runtime: download, integrity check, and decompression use only
 * web-standard APIs. The local disk cache is Node-only and loaded lazily, so
 * on browsers and Edge runtimes the dataset is simply re-fetched each time
 * rather than cached.
 *
 * @example
 * ```typescript
 * import { Client, loadSampleDataset } from 'cyborgdb';
 *
 * const dataset = await loadSampleDataset();
 * const index = await client.createIndex({ indexName: 'demo', indexKey });
 * await index.upsert({ items: dataset.items });
 * ```
 */
import type { VectorItem } from "./models";
/**
 * Base URL for hosted sample datasets (public-read S3 bucket).
 *
 * Datasets live at versioned per-dataset paths (`<name>/v<n>/dataset.json.gz`),
 * so the dataset can be iterated without an SDK release — re-upload under a new
 * version path and bump the entry in {@link DATASETS}.
 */
export declare const SAMPLE_DATASETS_BASE_URL = "https://cyborgdb-sample-datasets.s3.amazonaws.com";
/** A curated, named metadata filter that is guaranteed to match rows. */
export interface SampleFilter {
    /** Human-readable label for docs/UX. */
    name: string;
    /** A filter expression accepted by `index.query({ filters })`. */
    filter: Record<string, unknown>;
    /** What demo this filter illustrates. */
    demonstrates: string;
}
/**
 * A fully-loaded sample dataset, ready to upsert and query.
 *
 * Combines three layers:
 *  - **dataset metadata** (`name`, `dimension`, `metric`, …);
 *  - **convenience fields** built by the loader for quickstart/demo use
 *    (`items`, `sampleQueries`, `exampleFilters`);
 *  - **raw parallel arrays** plus **ground-truth fixture data** (`queries`,
 *    `*_neighbors`, `*_recall`, …) used to validate recall/accuracy. These
 *    keep their original snake_case names and are aligned by index.
 */
export interface SampleDataset {
    /** Dataset identifier, e.g. `"quickstart-75k"`. */
    name: string;
    /** Dataset schema version. */
    version: number;
    /** Human-readable description. */
    description: string;
    /** Vector dimensionality. */
    dimension: number;
    /** Distance metric the vectors were generated for, e.g. `"euclidean"`. */
    metric: string;
    /** Number of items in the dataset. */
    count: number;
    /** Items with explicit IDs, vectors, and metadata — drop into `upsert`. */
    items: VectorItem[];
    /** A handful of query vectors for quick ANN similarity-search demos. */
    sampleQueries: number[][];
    /** Curated, guaranteed-to-match filters for metadata / range-query demos. */
    exampleFilters: SampleFilter[];
    /** Explicit IDs, aligned with `vectors` / `metadata`. */
    ids: string[];
    /** All vectors, aligned with `ids` / `metadata`. */
    vectors: number[][];
    /** Per-vector metadata, aligned with `ids` / `vectors`. */
    metadata: Record<string, unknown>[];
    /** Query vectors (superset of `sampleQueries`). */
    queries: number[][];
    /** Metadata filter expressions used by the recall benchmark. */
    metadata_queries: Record<string, unknown>[];
    /** Human-readable names for each entry in `metadata_queries`. */
    metadata_query_names: string[];
    /** Ground-truth nearest-neighbor IDs per query, untrained index. */
    untrained_neighbors: number[][];
    /** Ground-truth nearest-neighbor IDs per query, trained index. */
    trained_neighbors: number[][];
    /** Ground-truth metadata-match counts per filter, untrained index. */
    untrained_metadata_matches: number[][];
    /** Ground-truth metadata-match counts per filter, trained index. */
    trained_metadata_matches: number[][];
    /** Ground-truth neighbors per filter+query, untrained index. */
    untrained_metadata_neighbors: number[][][];
    /** Ground-truth neighbors per filter+query, trained index. */
    trained_metadata_neighbors: number[][][];
    /** Expected mean recall, untrained index. */
    untrained_recall: number;
    /** Expected mean recall, trained index. */
    trained_recall: number;
    /** Number of vectors upserted before training. */
    num_untrained_vectors: number;
    /** Number of vectors upserted after training. */
    num_trained_vectors: number;
}
/**
 * The shape stored in the hosted artifact and the local cache: everything in
 * {@link SampleDataset} except the loader-derived convenience fields, which are
 * rebuilt by `hydrate()` to avoid duplicating vectors on the wire/disk.
 */
export type RawSampleDataset = Omit<SampleDataset, "items" | "sampleQueries">;
/**
 * Catalog of available datasets: where to fetch each one and the SHA-256 of its
 * decompressed JSON, pinned so a bucket compromise or a poisoned local cache
 * file can't be trusted silently. The same digest is verified post-download and
 * on cache read.
 *
 * Exported for tests to inject a fixture digest; it is intentionally not
 * re-exported from `index.ts`, so it is not part of the public API.
 */
export declare const DATASETS: Record<string, {
    objectPath: string;
    sha256: string;
}>;
/** Default dataset returned by `loadSampleDataset()` with no arguments. */
export declare const DEFAULT_SAMPLE_DATASET = "quickstart-75k";
export interface LoadSampleDatasetOptions {
    /**
     * Directory to cache the decompressed dataset in.
     * Defaults to `$XDG_CACHE_HOME/cyborgdb` or `~/.cache/cyborgdb`.
     */
    cacheDir?: string;
    /** Re-download even if a cached copy exists. Defaults to `false`. */
    forceDownload?: boolean;
}
/**
 * Load a hosted sample dataset, fetching from S3 on first use and caching
 * the decompressed copy locally for subsequent calls.
 *
 * @param name Dataset name (default: `"quickstart-75k"`).
 * @param options Cache directory / force-download overrides.
 * @returns The parsed dataset, ready to `upsert` and `query`.
 * @throws If the dataset name is unknown or the download fails.
 */
export declare function loadSampleDataset(name?: string, options?: LoadSampleDatasetOptions): Promise<SampleDataset>;