@pattern-js/mod-vectors 0.4.0-main.c8eb671

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Makkr Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,21 @@
+# @pattern-js/mod-vectors
+
+Vector search for [Pattern](https://github.com/makkr-studio/pattern):
+embedding collections that **declare their embedding alias** (so
+index-with-one-model-query-with-another is unrepresentable), filterable
+metadata pruned before scoring, hybrid vector+keyword retrieval with RRF
+fusion, a no-tokenizer text chunker, and a zero-dependency sqlite-backed
+local engine — durable and offload-safe — with a driver SPI for sqlite-vec
+and pgvector later.
+
+```jsonc
+// pattern.config.json
+{ "mods": ["@pattern-js/mod-ai", "@pattern-js/mod-vectors"] }
+```
+
+Ops: `vectors.collection.ensure`, `vectors.index` (chunk→embed→upsert),
+`vectors.chunk`, `vectors.upsert`, `vectors.query` (vector | keyword |
+hybrid, `filter: { field: value }`), `vectors.delete`.
+
+Full chapter: your app's `/docs` → **Vectors** (or
+[the handbook source](./docs/index.md)).

package/dist/admin.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @pattern-js/mod-vectors — the admin surface (Tier-1 declarative, zero build).
+ *
+ * One Vectors page under Data, three sections: the collections table (what is
+ * indexed, through which model), **Ingest text** (paste → chunk → embed —
+ * feeding a knowledge base is a form, not a curl), and **Search** (try a
+ * hybrid query, see scored matches). Together they are the whole RAG loop
+ * without leaving the admin. Each section is backed by its own dedicated
+ * admin-scoped route.
+ */
+import { type FrontendContribution, type OpDefinition, type Workflow } from "@pattern-js/core";
+/** Backing op for the collections table (privileged; the route carries the admin gate). */
+export declare const collectionsListOp: OpDefinition;
+/** Paste-to-RAG (admin): chunk a text and index it, creating the collection when new. */
+export declare const collectionsIngestOp: OpDefinition;
+/** Try a query (admin): hybrid by default, scored matches back — the smoke test for what got indexed. */
+export declare const collectionsSearchOp: OpDefinition;
+export declare function vectorsAdminRoutes(): Workflow[];
+export declare function vectorsFrontend(): FrontendContribution;
+//# sourceMappingURL=admin.d.ts.map

package/dist/admin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin.d.ts","sourceRoot":"","sources":["../src/admin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAoC,KAAK,oBAAoB,EAAkB,KAAK,YAAY,EAAE,KAAK,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAsCjJ,2FAA2F;AAC3F,eAAO,MAAM,iBAAiB,EAAE,YAuB/B,CAAC;AAEF,yFAAyF;AACzF,eAAO,MAAM,mBAAmB,EAAE,YAsCjC,CAAC;AAEF,yGAAyG;AACzG,eAAO,MAAM,mBAAmB,EAAE,YAmCjC,CAAC;AAEF,wBAAgB,kBAAkB,IAAI,QAAQ,EAAE,CA8B/C;AAED,wBAAgB,eAAe,IAAI,oBAAoB,CA8DtD"}

package/dist/admin.js

@@ -0,0 +1,249 @@
+/**
+ * @pattern-js/mod-vectors — the admin surface (Tier-1 declarative, zero build).
+ *
+ * One Vectors page under Data, three sections: the collections table (what is
+ * indexed, through which model), **Ingest text** (paste → chunk → embed —
+ * feeding a knowledge base is a form, not a curl), and **Search** (try a
+ * hybrid query, see scored matches). Together they are the whole RAG loop
+ * without leaving the admin. Each section is backed by its own dedicated
+ * admin-scoped route.
+ */
+import { httpEndpoint, fromBody, value, z } from "@pattern-js/core";
+import { chunkDoc } from "./chunk.js";
+import { VECTORS_SERVICE } from "./service.js";
+import { collectionSpecSchema } from "./types.js";
+const PATH = "/vectors/api/collections";
+const INGEST_PATH = "/vectors/api/ingest";
+const SEARCH_PATH = "/vectors/api/search";
+const API = "/admin/api";
+function requireService(ctx) {
+    const svc = ctx.services[VECTORS_SERVICE];
+    if (!svc)
+        throw new Error("vectors: service not available — is @pattern-js/mod-vectors listed in pattern.config.json mods?");
+    return svc;
+}
+/** Stable content hash (djb2) — re-pasting the same text re-uses the doc id, so dedupe holds. */
+function stableHash(s) {
+    let h = 5381;
+    for (let i = 0; i < s.length; i++)
+        h = ((h << 5) + h + s.charCodeAt(i)) >>> 0;
+    return h.toString(36);
+}
+/** The form's meta field is a JSON string (or empty); a workflow may pass an object. */
+function parseMeta(raw) {
+    if (raw == null)
+        return undefined;
+    if (typeof raw === "object")
+        return raw;
+    const s = String(raw).trim();
+    if (!s)
+        return undefined;
+    try {
+        const parsed = JSON.parse(s);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+            return parsed;
+    }
+    catch {
+        /* fall through to the located error */
+    }
+    throw new Error(`meta must be a JSON object, e.g. {"topic":"billing"} — got: ${s.slice(0, 60)}`);
+}
+/** Backing op for the collections table (privileged; the route carries the admin gate). */
+export const collectionsListOp = {
+    type: "vectors.collections.list",
+    title: "vectors.collections.list",
+    description: "List vector collections with alias, dims, filterables, row count and the active engine (admin).",
+    reusable: false,
+    sensitivity: "privileged",
+    inputs: {},
+    outputs: { collections: value() },
+    execute: async (ctx) => {
+        const svc = ctx.services[VECTORS_SERVICE];
+        if (!svc)
+            return { collections: [] };
+        const collections = await svc.listCollections();
+        return {
+            collections: collections.map((c) => ({
+                name: c.name,
+                alias: c.alias,
+                dims: c.dims ?? "(locks on first write)",
+                filterables: c.filterables.join(", ") || "—",
+                rows: c.rows,
+                engine: svc.engineId(),
+            })),
+        };
+    },
+};
+/** Paste-to-RAG (admin): chunk a text and index it, creating the collection when new. */
+export const collectionsIngestOp = {
+    type: "vectors.collections.ingest",
+    title: "vectors.collections.ingest",
+    description: "Ingest pasted text into a collection (admin): chunk → embed → upsert, creating the collection (with the " +
+        "given embedding alias) when it doesn't exist yet. Re-pasting the same text re-uses its content-derived doc id, " +
+        "so unchanged chunks are skipped. Args { collection, text, alias?, docId?, meta? (JSON object) }.",
+    reusable: false,
+    sensitivity: "privileged",
+    inputs: {
+        collection: value(z.string()),
+        text: value(z.string()),
+        alias: value(z.string().optional()),
+        docId: value(z.string().optional()),
+        meta: value(z.unknown().optional()),
+    },
+    outputs: { result: value() },
+    execute: async (ctx) => {
+        const svc = requireService(ctx);
+        const collection = String((await ctx.input.value("collection")) ?? "").trim();
+        const text = String((await ctx.input.value("text")) ?? "");
+        if (!collection)
+            throw new Error("collection is required");
+        if (!text.trim())
+            throw new Error("nothing to ingest — paste some text");
+        const alias = ctx.input.has("alias") ? String((await ctx.input.value("alias")) ?? "").trim() : "";
+        const docIdIn = ctx.input.has("docId") ? String((await ctx.input.value("docId")) ?? "").trim() : "";
+        const meta = parseMeta(ctx.input.has("meta") ? await ctx.input.value("meta") : undefined);
+        // Only a NEW collection takes the alias — an existing one already declared
+        // its embedding model, and silently re-pointing it would corrupt the space.
+        const exists = (await svc.listCollections()).some((c) => c.name === collection);
+        // Through the schema, so metric/filterables defaults apply like the canvas op's config does.
+        if (!exists)
+            await svc.ensureCollection(collectionSpecSchema.parse({ name: collection, alias: alias || "embeddings" }));
+        const docId = docIdIn || `paste-${stableHash(text)}`;
+        const chunks = chunkDoc({ id: docId, text, meta }, { maxChars: 1200, overlap: 150, separators: ["\n\n", "\n", ". "] });
+        const res = await svc.upsert(collection, chunks.map((c) => ({ id: c.id, text: c.text, meta: c.meta })), ctx);
+        return { result: { ok: true, collection, docId, chunks: chunks.length, indexed: res.count, embedded: res.embedded } };
+    },
+};
+/** Try a query (admin): hybrid by default, scored matches back — the smoke test for what got indexed. */
+export const collectionsSearchOp = {
+    type: "vectors.collections.search",
+    title: "vectors.collections.search",
+    description: "Search a collection from the admin (hybrid by default): top-k scored matches with their text and meta — " +
+        "the quickest way to verify what an ingest actually indexed. Args { collection, query, k?, mode? (vector/keyword/hybrid) }.",
+    reusable: false,
+    sensitivity: "privileged",
+    inputs: {
+        collection: value(z.string()),
+        query: value(z.string()),
+        k: value(z.union([z.string(), z.number()]).optional()),
+        mode: value(z.string().optional()),
+    },
+    outputs: { matches: value() },
+    execute: async (ctx) => {
+        const svc = requireService(ctx);
+        const collection = String((await ctx.input.value("collection")) ?? "").trim();
+        const query = String((await ctx.input.value("query")) ?? "");
+        if (!collection || !query.trim())
+            throw new Error("collection and query are required");
+        const kRaw = ctx.input.has("k") ? String((await ctx.input.value("k")) ?? "").trim() : "";
+        const k = kRaw ? Number(kRaw) : 5;
+        if (!Number.isFinite(k) || k <= 0)
+            throw new Error("k must be a positive number");
+        const modeRaw = ctx.input.has("mode") ? String((await ctx.input.value("mode")) ?? "").trim() : "";
+        const mode = (modeRaw || "hybrid");
+        const matches = await svc.query(collection, { text: query, k, mode }, ctx);
+        return {
+            matches: matches.map((m) => ({
+                score: Number(m.score.toFixed(4)),
+                id: m.id,
+                text: (m.text ?? "").length > 200 ? `${(m.text ?? "").slice(0, 200)}…` : (m.text ?? ""),
+                meta: m.meta ?? {},
+            })),
+        };
+    },
+};
+export function vectorsAdminRoutes() {
+    return [
+        httpEndpoint({
+            id: "vectors.route.admin.collections",
+            name: `Vectors · GET ${API}${PATH}`,
+            method: "GET",
+            path: `${API}${PATH}`,
+            op: "vectors.collections.list",
+            io: { out: "collections" },
+            auth: { scopes: ["admin"] },
+        }),
+        httpEndpoint({
+            id: "vectors.route.admin.ingest",
+            name: `Vectors · POST ${API}${INGEST_PATH}`,
+            method: "POST",
+            path: `${API}${INGEST_PATH}`,
+            op: "vectors.collections.ingest",
+            io: { in: { collection: fromBody(), text: fromBody(), alias: fromBody(), docId: fromBody(), meta: fromBody() }, out: "result" },
+            auth: { scopes: ["admin"] },
+        }),
+        httpEndpoint({
+            id: "vectors.route.admin.search",
+            name: `Vectors · POST ${API}${SEARCH_PATH}`,
+            method: "POST",
+            path: `${API}${SEARCH_PATH}`,
+            op: "vectors.collections.search",
+            io: { in: { collection: fromBody(), query: fromBody(), k: fromBody(), mode: fromBody() }, out: "matches" },
+            auth: { scopes: ["admin"] },
+        }),
+    ];
+}
+export function vectorsFrontend() {
+    return {
+        menu: [{ category: "Data", label: "Vectors", icon: "network", path: "/x/vectors/collections", order: 30 }],
+        pages: [
+            {
+                // The whole RAG loop on one page: what's indexed, paste to ingest, search to verify.
+                path: "/x/vectors/collections",
+                views: [
+                    {
+                        title: "Collections",
+                        view: {
+                            kind: "table",
+                            route: { method: "GET", path: PATH },
+                            columns: [
+                                { key: "name", label: "Collection" },
+                                { key: "alias", label: "Embedding alias" },
+                                { key: "dims", label: "Dims" },
+                                { key: "filterables", label: "Filterables" },
+                                { key: "rows", label: "Rows" },
+                                { key: "engine", label: "Engine" },
+                            ],
+                        },
+                    },
+                    {
+                        title: "Ingest text",
+                        view: {
+                            kind: "form",
+                            schema: {
+                                type: "object",
+                                properties: {
+                                    collection: { type: "string", default: "kb", description: "Target collection (created if new)" },
+                                    text: { type: "string", format: "multiline", description: "Paste anything — it's chunked, embedded and indexed" },
+                                    alias: { type: "string", default: "embeddings", description: "Embedding alias for a NEW collection (Settings → AI Providers)" },
+                                    docId: { type: "string", description: "Stable id for re-ingesting updates (empty = derived from the text)" },
+                                    meta: { type: "string", description: 'JSON object stamped on every chunk, e.g. {"topic":"billing"} — filterable if declared' },
+                                },
+                                required: ["collection", "text"],
+                            },
+                            route: { method: "POST", path: INGEST_PATH },
+                        },
+                    },
+                    {
+                        title: "Search",
+                        view: {
+                            kind: "form",
+                            schema: {
+                                type: "object",
+                                properties: {
+                                    collection: { type: "string", default: "kb", description: "Collection to search" },
+                                    query: { type: "string", description: "What are you looking for?" },
+                                    k: { type: "string", default: "5", description: "How many matches" },
+                                    mode: { type: "string", enum: ["hybrid", "vector", "keyword"], description: "hybrid = vector + keyword, RRF-fused" },
+                                },
+                                required: ["collection", "query"],
+                            },
+                            route: { method: "POST", path: SEARCH_PATH },
+                        },
+                    },
+                ],
+            },
+        ],
+    };
+}
+//# sourceMappingURL=admin.js.map

package/dist/admin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin.js","sourceRoot":"","sources":["../src/admin.ts"],"names":[],"mappings":"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"}

package/dist/chunk.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @pattern-js/mod-vectors — the text chunker.
+ *
+ * A recursive character splitter (no tokenizer dependency): split on the
+ * coarsest separator that still yields pieces under `maxChars`, recurse into
+ * oversized pieces with the next separator, then re-join neighbors greedily
+ * and carry `overlap` characters of context across chunk boundaries.
+ */
+export interface ChunkOptions {
+    maxChars?: number;
+    overlap?: number;
+    separators?: string[];
+}
+export interface Chunk {
+    /** `${docId}#${i}` when a doc id is known, else `#${i}`. */
+    id: string;
+    text: string;
+    meta?: Record<string, unknown>;
+}
+/** Greedily merge neighbor pieces up to maxChars, threading `overlap` chars across boundaries. */
+export declare function chunkText(text: string, opts?: ChunkOptions): string[];
+/** Chunk one document into id-stamped chunks carrying the doc's meta. */
+export declare function chunkDoc(doc: {
+    id?: string;
+    text: string;
+    meta?: Record<string, unknown>;
+}, opts?: ChunkOptions): Chunk[];
+//# sourceMappingURL=chunk.d.ts.map

package/dist/chunk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk.d.ts","sourceRoot":"","sources":["../src/chunk.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,KAAK;IACpB,4DAA4D;IAC5D,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAyBD,kGAAkG;AAClG,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,YAAiB,GAAG,MAAM,EAAE,CA0BzE;AAED,yEAAyE;AACzE,wBAAgB,QAAQ,CACtB,GAAG,EAAE;IAAE,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,EAClE,IAAI,GAAE,YAAiB,GACtB,KAAK,EAAE,CAMT"}

package/dist/chunk.js

@@ -0,0 +1,74 @@
+/**
+ * @pattern-js/mod-vectors — the text chunker.
+ *
+ * A recursive character splitter (no tokenizer dependency): split on the
+ * coarsest separator that still yields pieces under `maxChars`, recurse into
+ * oversized pieces with the next separator, then re-join neighbors greedily
+ * and carry `overlap` characters of context across chunk boundaries.
+ */
+const DEFAULTS = { maxChars: 1200, overlap: 150, separators: ["\n\n", "\n", ". "] };
+/** Split `text` recursively so every piece fits in maxChars. */
+function split(text, maxChars, separators) {
+    if (text.length <= maxChars)
+        return text.trim() ? [text] : [];
+    const [sep, ...rest] = separators;
+    if (!sep) {
+        // Out of separators — hard-cut (pathological input: one giant unbroken run).
+        const out = [];
+        for (let i = 0; i < text.length; i += maxChars)
+            out.push(text.slice(i, i + maxChars));
+        return out;
+    }
+    const parts = text.split(sep);
+    if (parts.length === 1)
+        return split(text, maxChars, rest);
+    const out = [];
+    for (const part of parts) {
+        const piece = part.trim() ? part + (sep === ". " ? "." : "") : "";
+        if (!piece)
+            continue;
+        out.push(...(piece.length > maxChars ? split(piece, maxChars, rest) : [piece]));
+    }
+    return out;
+}
+/** Greedily merge neighbor pieces up to maxChars, threading `overlap` chars across boundaries. */
+export function chunkText(text, opts = {}) {
+    const { maxChars, overlap, separators } = { ...DEFAULTS, ...opts };
+    if (maxChars <= 0)
+        throw new Error("vectors.chunk: maxChars must be positive");
+    if (overlap >= maxChars)
+        throw new Error("vectors.chunk: overlap must be smaller than maxChars");
+    const pieces = split(text, maxChars, separators);
+    const chunks = [];
+    let current = "";
+    for (const piece of pieces) {
+        const candidate = current ? `${current}\n${piece}` : piece;
+        if (candidate.length <= maxChars) {
+            current = candidate;
+            continue;
+        }
+        if (current)
+            chunks.push(current);
+        // Overlap: seed the next chunk with the tail of the previous one.
+        const tail = overlap > 0 && current ? current.slice(-overlap) : "";
+        current = tail ? `${tail}\n${piece}` : piece;
+        // The seeded piece may itself overflow (tail + long piece) — flush the tail alone.
+        if (current.length > maxChars) {
+            if (tail)
+                chunks.push(tail);
+            current = piece;
+        }
+    }
+    if (current.trim())
+        chunks.push(current);
+    return chunks;
+}
+/** Chunk one document into id-stamped chunks carrying the doc's meta. */
+export function chunkDoc(doc, opts = {}) {
+    return chunkText(doc.text, opts).map((text, i) => ({
+        id: `${doc.id ?? ""}#${i}`,
+        text,
+        ...(doc.meta ? { meta: doc.meta } : {}),
+    }));
+}
+//# sourceMappingURL=chunk.js.map

package/dist/chunk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk.js","sourceRoot":"","sources":["../src/chunk.ts"],"names":[],"mappings":"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"}

package/dist/engine-local.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @pattern-js/mod-vectors — the default "local" engine.
+ *
+ * node:sqlite-backed (WAL + busy_timeout, the mod-store recipe): durable AND
+ * offload-safe — a worker's own service instance opens the SAME file, so
+ * offloaded workflows see every vector the host wrote. Vectors are Float32
+ * BLOBs, L2-normalized at write time so cosine similarity is a dot product;
+ * search is an honest brute-force scan with a top-k heap (fine to ~100k
+ * vectors — past that, register a real driver: the SPI carries filter+mode).
+ *
+ * Filterables prune BEFORE the scan through the indexed `vec_meta` side
+ * table. Keyword ranking uses FTS5 when this sqlite build has it (probed at
+ * open) and a zero-dep token-overlap scorer otherwise; hybrid fuses the two
+ * rankings with reciprocal-rank fusion (RRF, k=60) — no score calibration.
+ */
+import type { CollectionInfo, CollectionSpec, EngineQuery, EngineRow, Filter, Match, VectorsEngine } from "./types.js";
+/** L2-normalize into a fresh Float32Array (cosine ≡ dot afterwards). */
+export declare function normalize(vector: number[] | Float32Array): Float32Array;
+/** Reciprocal-rank fusion of one or more rankings (RRF, k=60). */
+export declare function rrfFuse(rankings: string[][], k?: number): Map<string, number>;
+export interface LocalEngineOptions {
+    /** ":memory:" works too (tests). */
+    path: string;
+    /** Test seam: pretend this sqlite build has no FTS5 (exercise the fallback scorer). */
+    disableFts?: boolean;
+}
+export declare class LocalVectorsEngine implements VectorsEngine {
+    readonly id = "local";
+    private readonly db;
+    /** Whether this sqlite build compiled FTS5 (probed at open). */
+    readonly hasFts: boolean;
+    constructor(opts: LocalEngineOptions);
+    private runMigrations;
+    ensureCollection(spec: CollectionSpec): Promise<void>;
+    getCollection(name: string): Promise<CollectionSpec | null>;
+    listCollections(): Promise<CollectionInfo[]>;
+    /** Lock dims on the collection's first vector write; mismatch names the alias. */
+    private lockDims;
+    hashes(collection: string, ids: string[]): Promise<Map<string, string>>;
+    upsert(collection: string, rows: EngineRow[]): Promise<void>;
+    delete(collection: string, ids: string[]): Promise<number>;
+    query(collection: string, q: EngineQuery): Promise<Match[]>;
+    list(collection: string, q: {
+        filter?: Filter;
+        limit?: number;
+        offset?: number;
+    }): Promise<Array<{
+        id: string;
+        text: string | null;
+        meta: Record<string, unknown> | null;
+        updatedAt: number;
+    }>>;
+    /** AND of equality/any-of via the side table: one indexed lookup per field, intersected. */
+    private filterIds;
+    /** Brute-force cosine over the (possibly pruned) rows with a bounded top-k. */
+    private vectorRank;
+    private keywordRank;
+    private loadRows;
+    private hydrate;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=engine-local.d.ts.map

package/dist/engine-local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-local.d.ts","sourceRoot":"","sources":["../src/engine-local.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EACd,WAAW,EACX,SAAS,EACT,MAAM,EAEN,KAAK,EACL,aAAa,EACd,MAAM,YAAY,CAAC;AAgDpB,wEAAwE;AACxE,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,YAAY,GAAG,YAAY,CAOvE;AAcD,kEAAkE;AAClE,wBAAgB,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,SAAK,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAQzE;AAED,MAAM,WAAW,kBAAkB;IACjC,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,uFAAuF;IACvF,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,qBAAa,kBAAmB,YAAW,aAAa;IACtD,QAAQ,CAAC,EAAE,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAc;IACjC,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;gBAEb,IAAI,EAAE,kBAAkB;IA2BpC,OAAO,CAAC,aAAa;IAmBf,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBrD,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAY3D,eAAe,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAelD,kFAAkF;IAClF,OAAO,CAAC,QAAQ;IAmBV,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAWvE,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAmC5D,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAoB1D,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;IAsB3D,IAAI,CACR,UAAU,EAAE,MAAM,EAClB,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GACtD,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IA2B/G,4FAA4F;IAC5F,OAAO,CAAC,SAAS;IAoBjB,+EAA+E;IAC/E,OAAO,CAAC,UAAU;IAuBlB,OAAO,CAAC,WAAW;IA6BnB,OAAO,CAAC,QAAQ;IAyBhB,OAAO,CAAC,OAAO;IAUT,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}