quiver-client 0.22.0

package/README.md

@@ -0,0 +1,91 @@
+# quiver-client (TypeScript)
+
+A small, dependency-free TypeScript/JavaScript client for
+[Quiver](https://github.com/achref-soua/quiver) — a security-first, memory-frugal
+vector database. It mirrors the server's REST contract and uses the global
+`fetch`, so it runs on Node ≥ 20 and modern runtimes with no dependencies.
+
+```bash
+pnpm add quiver-client
+```
+
+```ts
+import { Client } from "quiver-client";
+
+const q = new Client("http://127.0.0.1:6333", { apiKey: "…" });
+
+// Create a memory-frugal, disk-resident collection (PQ codes in RAM,
+// graph + vectors on encrypted SSD), or use "hnsw" (default) / "ivf".
+await q.createCollection("items", 384, {
+  metric: "cosine",
+  index: "disk_vamana",
+  pqSubspaces: 48,
+});
+
+await q.upsert("items", [
+  { id: "a", vector: embed("…"), payload: { tag: "x" } },
+]);
+
+const hits = await q.search("items", embed("query"), {
+  k: 5,
+  filter: { eq: { field: "tag", value: "x" } },
+});
+```
+
+Embeddings are produced by the caller — Quiver is model-agnostic.
+
+## API
+
+| Method | Description |
+|---|---|
+| `createCollection(name, dim, { metric?, index?, pqSubspaces? })` | Create a collection and pick its index |
+| `listCollections()` / `getCollection(name)` / `deleteCollection(name)` | Collection CRUD |
+| `upsert(collection, points)` / `deletePoints(collection, ids)` / `getPoint(collection, id)` | Points |
+| `search(collection, vector, { k?, filter?, efSearch?, withPayload?, withVector? })` | Filtered k-NN |
+| `upsertDocuments(collection, documents)` / `deleteDocuments(collection, ids)` | Multi-vector (ColBERT) documents |
+| `searchMultiVector(collection, query, { k?, filter? })` | MaxSim late-interaction search |
+| `healthz()` | Liveness probe |
+
+Create a multi-vector collection with `createCollection(name, dim, { metric: "cosine", multivector: true })`, then index documents as token sets and rank them by MaxSim.
+
+Errors from the server (or transport) reject with a `QuiverError` carrying the
+HTTP `status`. A custom `fetch` can be injected via the constructor for testing
+or a bespoke transport.
+
+## Client-side payload encryption
+
+Seal payload fields with a key Quiver never sees; the server stores and returns
+ciphertext it cannot read (ADR-0012). The helper lives at the
+`quiver-client/encryption` subpath, so the core client stays dependency-free —
+install the optional peer dependency to use it:
+
+```bash
+pnpm add @stablelib/xchacha20poly1305
+```
+
+```ts
+import { Client } from "quiver-client";
+import { PayloadCipher } from "quiver-client/encryption";
+
+const cipher = PayloadCipher.fromHex("…64 hex chars…"); // a dedicated key, never the at-rest one
+const q = new Client("http://127.0.0.1:6333", { apiKey: "…" });
+
+// Keep `tier` server-filterable; hide `ssn` from the server.
+const payload = { tier: "gold", ...cipher.seal({ ssn: "078-05-1120" }) };
+await q.upsert("people", [{ id: "p1", vector: embed("…"), payload }]);
+
+const point = await q.getPoint("people", "p1");
+const secret = cipher.open(point!.payload); // -> { ssn: "078-05-1120" }
+```
+
+The envelope (XChaCha20-Poly1305) matches the Rust reference and the Python SDK
+byte-for-byte — see [client-side encryption](https://github.com/achref-soua/quiver/blob/main/docs/security/crypto.md#client-side-payload-encryption-adr-0012).
+
+## Develop
+
+```bash
+pnpm install
+pnpm typecheck   # tsc --noEmit
+pnpm test        # vitest
+pnpm build       # tsc -> dist/ (ESM + .d.ts)
+```

package/dist/client.d.ts

@@ -0,0 +1,258 @@
+import type { VectorCipher } from "./vector.js";
+/** An error from the Quiver server or the transport. `status` is the HTTP code
+ * when the failure came from the server, or `undefined` for a transport error. */
+export declare class QuiverError extends Error {
+    readonly status?: number;
+    constructor(message: string, status?: number);
+}
+/** A point to upsert: a caller-supplied id, its vector, and an optional payload. */
+export interface Point {
+    id: string;
+    vector: number[];
+    payload?: unknown;
+}
+/** A search hit (or a fetched point, with `score` 0). */
+export interface Match {
+    id: string;
+    score: number;
+    payload?: unknown;
+    vector?: number[];
+}
+/** What a {@link QuiverClient.snapshot} captured (ADR-0050). */
+export interface SnapshotInfo {
+    manifestVersion: number;
+    files: number;
+    bytes: number;
+}
+/** A multi-vector (late-interaction / ColBERT) document: an id, its set of token
+ * vectors, and an optional payload. */
+export interface Document {
+    id: string;
+    vectors: number[][];
+    payload?: unknown;
+}
+/** A multi-vector document hit, ranked by MaxSim late interaction. */
+export interface DocumentMatch {
+    id: string;
+    score: number;
+    payload?: unknown;
+    vectors?: number[][];
+}
+/** The index structure a collection is served by (ADR-0007, ADR-0034).
+ * `colbert` is the ColBERTv2/PLAID token-pool index for multivector collections. */
+export type IndexKind = "hnsw" | "vamana" | "disk_vamana" | "ivf" | "colbert";
+/** A distance metric. */
+export type Metric = "l2" | "cosine" | "dot";
+/** Client-side vector encryption mode — the server never holds the key (ADR-0031,
+ * ADR-0032): `none` (plaintext, the server ranks), `dcpe` (the server ranks
+ * ciphertexts but leaks distance ordering by design; not semantically secure), or
+ * `client_side` (semantically secure opaque AEAD; the server does not rank, so you
+ * fetch and rank locally). */
+export type VectorEncryption = "none" | "dcpe" | "client_side";
+/** The value type of a filterable payload field (ADR-0022). */
+export type FieldType = "keyword" | "numeric";
+/** A payload field declared filterable for hybrid (pre-filtered) search. */
+export interface FilterableField {
+    path: string;
+    fieldType?: FieldType;
+}
+/** Metadata about a collection. */
+export interface CollectionInfo {
+    name: string;
+    dim: number;
+    metric: string;
+    count: number;
+    index: IndexKind;
+    pqSubspaces?: number;
+    filterable: FilterableField[];
+    multivector: boolean;
+    vectorEncryption: VectorEncryption;
+}
+/** Options for constructing a {@link Client}. */
+export interface ClientOptions {
+    apiKey?: string;
+    timeoutMs?: number;
+    /** Inject a `fetch` implementation (for tests or a custom transport). */
+    fetch?: typeof fetch;
+}
+/** Options for {@link Client.createCollection}. */
+export interface CreateCollectionOptions {
+    metric?: Metric;
+    /** Index structure; `disk_vamana` is the memory-frugal disk path (l2/cosine);
+     * `colbert` is the ColBERTv2/PLAID token-pool index for multivector collections. */
+    index?: IndexKind;
+    /** Product-quantization subspaces for `disk_vamana` / `ivf` (must divide dim). */
+    pqSubspaces?: number;
+    /** Payload fields to index for hybrid (pre-filtered) search. */
+    filterable?: FilterableField[];
+    /** Create a multi-vector (late-interaction / ColBERT) collection. */
+    multivector?: boolean;
+    /**
+     * Client-side vector encryption (the server never holds the key): `"dcpe"` is
+     * experimental property-preserving encryption (ADR-0031; the server ranks,
+     * requires `l2`, not semantically secure); `"client_side"` is semantically
+     * secure opaque AEAD (ADR-0032; the server does not rank — use
+     * {@link Client.fetch} / {@link Client.searchClientSide}). Defaults to `"none"`.
+     */
+    vectorEncryption?: VectorEncryption;
+}
+/** Options for {@link Client.search}. */
+export interface SearchOptions {
+    k?: number;
+    /** A Quiver payload filter expression (see the API docs). */
+    filter?: unknown;
+    efSearch?: number;
+    withPayload?: boolean;
+    withVector?: boolean;
+}
+/** A sparse query vector for hybrid search (ADR-0043): parallel dimension ids
+ * (`indices`) and weights (`values`). */
+export interface SparseVector {
+    indices: number[];
+    values: number[];
+}
+/** Options for {@link Client.hybridSearch}. Provide `vector`, `sparse`, or both;
+ * at least one is required. */
+export interface HybridSearchOptions {
+    /** Dense query vector (omit for pure-sparse/text search). */
+    vector?: number[];
+    /** Sparse query vector (omit for pure-dense/text search). */
+    sparse?: SparseVector;
+    /** Full-text query, tokenized server-side and scored by BM25 (ADR-0046). */
+    queryText?: string;
+    k?: number;
+    /** A Quiver payload filter expression (applied on both sides). */
+    filter?: unknown;
+    efSearch?: number;
+    /** RRF rank-bias constant (default 60). */
+    rrfK0?: number;
+    withPayload?: boolean;
+    withVector?: boolean;
+}
+/** A text point for {@link Client.upsertText} (ADR-0047): the server embeds
+ * `text` with the collection's configured provider and indexes it for BM25. */
+export interface TextPoint {
+    id: string;
+    text: string;
+    payload?: unknown;
+}
+/** Options for {@link Client.searchText} (ADR-0047). */
+export interface SearchTextOptions {
+    k?: number;
+    /** A Quiver payload filter expression. */
+    filter?: unknown;
+    efSearch?: number;
+    /** RRF rank-bias constant (default 60). */
+    rrfK0?: number;
+    withPayload?: boolean;
+    withVector?: boolean;
+    /** Opt-in: rerank the candidate pool with the collection's rerank provider. */
+    rerank?: boolean;
+}
+/** Options for {@link Client.fetch}. */
+export interface FetchOptions {
+    /** A Quiver payload filter expression to narrow the set. */
+    filter?: unknown;
+    /** Maximum number of points to return (default 100). */
+    limit?: number;
+    withPayload?: boolean;
+    withVector?: boolean;
+}
+/** Options for {@link Client.searchClientSide}. */
+export interface ClientSideSearchOptions {
+    k?: number;
+    /** A Quiver payload filter expression (applied server-side, on cleartext fields). */
+    filter?: unknown;
+    /** Metric to rank by, client-side (default `"l2"`). */
+    metric?: Metric;
+    /** How many candidates to fetch before ranking locally (default 10000). */
+    candidateLimit?: number;
+}
+/** A synchronous-feeling, promise-based Quiver REST client. */
+export declare class Client {
+    #private;
+    constructor(baseUrl?: string, opts?: ClientOptions);
+    /** Create a collection. Rejects with {@link QuiverError} if the name is taken
+     * or the index/metric combination is unsupported. */
+    createCollection(name: string, dim: number, opts?: CreateCollectionOptions): Promise<CollectionInfo>;
+    /** List all collections. */
+    listCollections(): Promise<CollectionInfo[]>;
+    /** Fetch one collection's metadata. */
+    getCollection(name: string): Promise<CollectionInfo>;
+    /** Delete a collection; resolves to whether it existed. */
+    deleteCollection(name: string): Promise<boolean>;
+    /** Insert or replace points; resolves to the number upserted. */
+    upsert(collection: string, points: Point[]): Promise<number>;
+    /** Delete points by id; resolves to the number deleted. */
+    deletePoints(collection: string, ids: string[]): Promise<number>;
+    /** Fetch a point by id, or `null` if it does not exist. */
+    getPoint(collection: string, id: string): Promise<Match | null>;
+    /** Search for the `k` nearest points to `vector`, nearest first. */
+    search(collection: string, vector: number[], opts?: SearchOptions): Promise<Match[]>;
+    /** Hybrid search fused with Reciprocal Rank Fusion (ADR-0043/0046). Provide a
+     * dense `vector`, a `sparse` query vector, and/or a full-text `queryText` (scored
+     * by BM25) — at least one is required. The same payload `filter` applies to every
+     * side. */
+    hybridSearch(collection: string, opts?: HybridSearchOptions): Promise<Match[]>;
+    /** Embed each point's `text` server-side and upsert it (ADR-0047); the text is
+     * also indexed for BM25. Requires an `[embedding.<collection>]` provider on the
+     * server. Resolves to the number upserted. */
+    upsertText(collection: string, points: TextPoint[]): Promise<number>;
+    /** Embed `text` server-side and search dense ⊕ BM25, optionally reranking the
+     * candidate pool in one call (ADR-0047). Requires an `[embedding.<collection>]`
+     * provider (and a `[rerank.<collection>]` provider for `rerank: true`). */
+    searchText(collection: string, text: string, opts?: SearchTextOptions): Promise<Match[]>;
+    /** Fetch points without ranking; an optional payload `filter` narrows the set
+     * and `limit` bounds it. The retrieval path for `client_side`-encrypted
+     * collections (ADR-0032): the server returns the entitled set (each payload
+     * carries the sealed vector under `__quiver_vec__`) and you decrypt and rank
+     * locally (see {@link searchClientSide}). Also a general list-points call for
+     * any collection; returned matches carry `score` 0. */
+    fetch(collection: string, opts?: FetchOptions): Promise<Match[]>;
+    /** Upsert a large (sync or async) iterable of points in server-friendly
+     * batches; resolves to the total upserted. `batch` must stay within the
+     * server's `max_batch_size` (ADR-0040, default 1000). `onProgress` is called
+     * with the running total after each batch (may be sync or async). Mirrors the
+     * Python `upsert_iter`. */
+    upsertIter(collection: string, points: Iterable<Point> | AsyncIterable<Point>, opts?: {
+        batch?: number;
+        onProgress?: (total: number) => void | Promise<void>;
+    }): Promise<number>;
+    /** Yield points page by page, for export / re-embedding. The REST fetch is
+     * limit-bounded without a server cursor, so this returns up to `batch` points
+     * in one page — pass a narrowing `filter` for large collections (a server-side
+     * scroll cursor is a follow-up). Mirrors the Python async `scroll`. */
+    scroll(collection: string, opts?: {
+        filter?: unknown;
+        batch?: number;
+        withPayload?: boolean;
+        withVector?: boolean;
+    }): AsyncGenerator<Match>;
+    /** Delete every point matching `filter`; resolves to the number deleted.
+     * Fetches matching ids (paged by `batch`) and deletes them until none remain —
+     * useful for GDPR erasure and re-indexing. Mirrors the Python `delete_by_filter`. */
+    deleteByFilter(collection: string, filter: unknown, opts?: {
+        batch?: number;
+    }): Promise<number>;
+    /** Take a consistent online snapshot (backup) of the whole database into a
+     * server-local directory, which must not already exist (ADR-0050); admin-only.
+     * Resolves to the captured manifest version and the file/byte counts. */
+    snapshot(destination: string): Promise<SnapshotInfo>;
+    /** Nearest-neighbour search over a `client_side`-encrypted collection (ADR-0032),
+     * done entirely client-side: {@link fetch} the (optionally filtered) candidate
+     * set, decrypt each vector with `cipher` (a `VectorCipher` from
+     * `quiver-client/vector`), rank by metric, and return the top `k`. The server
+     * never ranks and never sees the key. This mode suits small/medium or
+     * pre-filtered collections; `candidateLimit` bounds how many points are fetched
+     * before ranking. Each result carries the decrypted `vector` and a `score` under
+     * the chosen metric. */
+    searchClientSide(collection: string, query: number[], cipher: VectorCipher, opts?: ClientSideSearchOptions): Promise<Match[]>;
+    /** Insert or replace multi-vector documents; resolves to the number upserted. */
+    upsertDocuments(collection: string, documents: Document[]): Promise<number>;
+    /** Delete multi-vector documents by id; resolves to the number deleted. */
+    deleteDocuments(collection: string, ids: string[]): Promise<number>;
+    /** Rank documents by MaxSim late interaction against the `query` token set. */
+    searchMultiVector(collection: string, query: number[][], opts?: SearchOptions): Promise<DocumentMatch[]>;
+    /** Whether the server's liveness probe succeeds. */
+    healthz(): Promise<boolean>;
+}